Metadata-Version: 2.4
Name: box-agent
Version: 0.5.1
Summary: AI agent framework with Jupyter sandbox, data analysis, MCP tools, ACP protocol, multi-provider LLM, and standalone runtime packaging
Author: Box Agent Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/Raccoon-Office/Box-Agent
Project-URL: Repository, https://github.com/Raccoon-Office/Box-Agent
Project-URL: Documentation, https://github.com/Raccoon-Office/Box-Agent#readme
Project-URL: Issues, https://github.com/Raccoon-Office/Box-Agent/issues
Project-URL: Changelog, https://github.com/Raccoon-Office/Box-Agent/releases
Keywords: agent,ai,llm,sandbox,mcp,acp,tool-calling,safety,jupyter,data-analysis,electron,standalone-runtime
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: anthropic>=0.39.0
Requires-Dist: openai>=1.57.4
Requires-Dist: agent-client-protocol>=0.6.0
Requires-Dist: jupyter-client>=8.6.0
Requires-Dist: ipykernel>=6.29.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Provides-Extra: runtime
Requires-Dist: pandas; extra == "runtime"
Requires-Dist: numpy; extra == "runtime"
Requires-Dist: matplotlib; extra == "runtime"
Requires-Dist: seaborn; extra == "runtime"
Requires-Dist: openpyxl; extra == "runtime"
Requires-Dist: scikit-learn; extra == "runtime"
Requires-Dist: pip; extra == "runtime"
Dynamic: license-file

# Box Agent

English | [中文](./README_CN.md)

**Box Agent** is a professional AI agent framework that supports multiple LLM providers (Anthropic, OpenAI-compatible, DeepSeek, SiliconFlow, and any third-party API). It features interleaved thinking, tool calling, sandboxed code execution, data analysis, and a robust agent loop for complex tasks.

This project comes packed with features designed for a robust and intelligent agent development experience:

**Core Agent**
*   ✅ **Full Agent Execution Loop**: A complete and reliable foundation with a basic toolset for file system and shell operations.
*   ✅ **Multi-Provider LLM**: Supports Anthropic, OpenAI-compatible, DeepSeek, SiliconFlow, and any third-party API endpoint out of the box.
*   ✅ **Intelligent Context Management**: Automatically summarizes conversation history to handle contexts up to a configurable token limit, enabling infinitely long tasks.
*   ✅ **Persistent Memory**: An active **Session Note Tool** ensures the agent retains key information across multiple sessions.
*   ✅ **Non-Interactive Mode**: Run headless with `--task` for CI/CD pipelines and automation scripts.

**Sandbox & Data Analysis**
*   ✅ **Jupyter Sandbox Execution**: Isolated `execute_code` tool runs Python in a sandboxed venv with its own kernel — safe from host environment pollution. In standalone runtime mode, uses an in-process kernel with bundled packages — no external Python required.
*   ✅ **Built-in Data Analysis**: Pre-installed `pandas`, `numpy`, `matplotlib`, `openpyxl`, `scikit-learn` in the sandbox — ready for CSV/XLSX analysis and chart generation.
*   ✅ **Auto Package Install**: Detects `ModuleNotFoundError` at runtime and automatically `pip install`s missing packages (sklearn → scikit-learn, cv2 → opencv-python, PIL → Pillow, etc.) with retry. In runtime mode, installs to `~/.box-agent/runtime-packages/` with whitelist control.
*   ✅ **Structured Artifact Events**: Files generated by code execution (PNG, CSV, XLSX, PDF) are detected via pre/post snapshot and emitted as structured `ArtifactEvent`s for downstream consumers.

**Integration & Deployment**
*   ✅ **ACP Protocol Bridge**: Full [Agent Communication Protocol](https://github.com/nichochar/agent-client-protocol) support — integrates with Zed Editor, Electron apps, and any ACP-compatible host via JSON-RPC over stdio.
*   ✅ **Standalone Runtime**: PyInstaller-packaged binary bundles Python + all dependencies including data science packages (pandas, numpy, matplotlib, scikit-learn) and pip for on-demand installs. No external Python required — just download and run. Available for macOS (arm64/x64) and Linux.
*   ✅ **MCP Tool Integration**: Natively supports MCP for tools like knowledge graph access and web search.
*   ✅ **Claude Skills Integration**: Comes with 11 professional skills for documents, design, testing, and development.

**Safety & Quality**
*   ✅ **Safety Layer**: Dangerous command detection and confirmation, workspace scope control, and automatic file backup to `~/.box-agent/trash/` before modifications.
*   ✅ **Robust File Handling**: UTF-8 fallback with `errors='replace'` for non-UTF-8 files (GBK CSVs, Latin-1 text, etc.).
*   ✅ **Comprehensive Logging**: Detailed logs for every request, response, and tool execution. Structured debug logging with env-var control for the standalone runtime.
*   ✅ **Clean & Simple Design**: A beautiful CLI and a codebase that is easy to understand, making it the perfect starting point for building advanced agents.

## Table of Contents

- [Box Agent](#box-agent)
  - [Table of Contents](#table-of-contents)
  - [Quick Start](#quick-start)
    - [1. Get API Key](#1-get-api-key)
    - [2. Choose Your Usage Mode](#2-choose-your-usage-mode)
      - [🚀 Quick Start Mode (Recommended for Beginners)](#-quick-start-mode-recommended-for-beginners)
      - [🔧 Development Mode](#-development-mode)
  - [ACP \& Zed Editor Integration(optional)](#acp--zed-editor-integrationoptional)
  - [Standalone Runtime (Electron Integration)](#standalone-runtime-electron-integration)
  - [Usage Examples](#usage-examples)
    - [Task Execution](#task-execution)
    - [Using a Claude Skill (e.g., PDF Generation)](#using-a-claude-skill-eg-pdf-generation)
    - [Web Search \& Summarization (MCP Tool)](#web-search--summarization-mcp-tool)
  - [Testing](#testing)
    - [Quick Run](#quick-run)
    - [Test Coverage](#test-coverage)
  - [Troubleshooting](#troubleshooting)
    - [SSL Certificate Error](#ssl-certificate-error)
    - [Module Not Found Error](#module-not-found-error)
  - [Related Documentation](#related-documentation)
  - [Community](#community)
  - [Contributing](#contributing)
  - [License](#license)
  - [References](#references)

## Quick Start

### 1. Get API Key

Get an API key from your preferred LLM provider:

| Provider       | Platform                                                                 | API Base                          |
| -------------- | ------------------------------------------------------------------------ | --------------------------------- |
| **Anthropic**  | [https://console.anthropic.com](https://console.anthropic.com)           | `https://api.anthropic.com`       |
| **OpenAI**     | [https://platform.openai.com](https://platform.openai.com)              | `https://api.openai.com/v1`       |
| **DeepSeek**   | [https://platform.deepseek.com](https://platform.deepseek.com)          | `https://api.deepseek.com`        |
| **SiliconFlow** | [https://siliconflow.cn](https://siliconflow.cn)                       | `https://api.siliconflow.cn/v1`   |

**Steps:**
1. Visit the provider's platform to register and login
2. Navigate to API Key management
3. Create a new key and save it securely

### 2. Choose Your Usage Mode

**Prerequisites: Install uv**

Both usage modes require uv. If you don't have it installed:

```bash
# macOS/Linux/WSL
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
python -m pip install --user pipx
python -m pipx ensurepath
# Restart PowerShell after installation

# After installation, restart your terminal or run:
source ~/.bashrc  # or ~/.zshrc (macOS/Linux)
```

We offer two usage modes - choose based on your needs:

#### 🚀 Quick Start Mode (Recommended for Beginners)

Perfect for users who want to quickly try Box Agent without cloning the repository or modifying code.

**Installation:**

```bash
# 1. Install directly from GitHub
uv tool install git+https://github.com/Raccoon-Office/Box-Agent.git

# 2. Run interactive setup wizard (creates config and guides you through provider/key setup)
box-agent setup
```

> 💡 **Tip**: If you want to develop locally or modify code, use "Development Mode" below

**Configuration:**

The setup wizard creates config files in `~/.box-agent/config/`. You can review or edit them anytime:

```bash
box-agent config          # Show current configuration
box-agent config --edit   # Open config file in your editor
```

Fill in your API Key and corresponding API Base:

```yaml
api_key: "YOUR_API_KEY_HERE"
api_base: "https://api.anthropic.com"
model: "claude-sonnet-4-20250514"
provider: "anthropic"
```

**Start Using:**

```bash
box-agent                                    # Use current directory as workspace
box-agent --workspace /path/to/your/project  # Specify workspace directory
box-agent doctor                             # Check environment and connectivity
box-agent --version                          # Check version

# Management commands
uv tool upgrade box-agent                    # Upgrade to latest version
uv tool uninstall box-agent                  # Uninstall if needed
uv tool list                                  # View all installed tools
```

#### 🔧 Development Mode

For developers who need to modify code, add features, or debug.

**Installation & Configuration:**

```bash
# 1. Clone the repository
git clone https://github.com/Raccoon-Office/Box-Agent.git
cd Box-Agent

# 2. Install uv (if you haven't)
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell):
irm https://astral.sh/uv/install.ps1 | iex
# Restart terminal after installation

# 3. Sync dependencies
uv sync

# Alternative: Install dependencies manually (if not using uv)
# pip install -r requirements.txt
# Or install required packages:
# pip install tiktoken pyyaml httpx pydantic requests prompt-toolkit mcp

# 4. Initialize Claude Skills (Optional)
git submodule update --init --recursive

# 5. Copy config template
```

**macOS/Linux:**
```bash
cp box_agent/config/config-example.yaml box_agent/config/config.yaml
```

**Windows:**
```powershell
Copy-Item box_agent\config\config-example.yaml box_agent\config\config.yaml

# 6. Edit config file
vim box_agent/config/config.yaml  # Or use your preferred editor
```

Fill in your API Key and corresponding API Base:

```yaml
api_key: "YOUR_API_KEY_HERE"
api_base: "https://api.anthropic.com"
model: "claude-sonnet-4-20250514"
provider: "anthropic"
max_steps: 100
workspace_dir: "./workspace"
```

> 📖 Full configuration guide: See [config-example.yaml](box_agent/config/config-example.yaml)

**Run Methods:**

Choose your preferred run method:

```bash
# Method 1: Run as module directly (good for debugging)
uv run python -m box_agent.cli

# Method 2: Install in editable mode (recommended)
uv tool install -e .
# After installation, run from anywhere and code changes take effect immediately
box-agent
box-agent --workspace /path/to/your/project
```

> 📖 For more development guidance, see [Development Guide](docs/DEVELOPMENT_GUIDE.md)

> 📖 For more production deployment guidance, see [Production Guide](docs/PRODUCTION_GUIDE.md)

## ACP & Zed Editor Integration(optional)

Box Agent supports the [Agent Communication Protocol (ACP)](https://github.com/modelcontextprotocol/protocol) for integration with code editors like Zed.

**Setup in Zed Editor:**

1. Install Box Agent in development mode or as a tool
2. Add to your Zed `settings.json`:

```json
{
  "agent_servers": {
    "box-agent": {
      "command": "/path/to/box-agent-acp"
    }
  }
}
```

The command path should be:
- If installed via `uv tool install`: Use the output of `which box-agent-acp`
- If in development mode: `./box_agent/acp/server.py`

**Usage:**
- Open Zed's agent panel with `Ctrl+Shift+P` → "Agent: Toggle Panel"
- Select "box-agent" from the agent dropdown
- Start conversations with Box Agent directly in your editor

## Standalone Runtime (Electron Integration)

Box Agent can be packaged as a **standalone binary** for embedding in Electron apps or other host processes. The binary bundles Python and all dependencies — no external Python installation required.

### Pre-built Downloads

Download platform-specific runtime artifacts from [GitHub Releases](https://github.com/Raccoon-Office/Box-Agent/releases):

```bash
# Download via gh CLI
gh release download v0.5.0 --repo Raccoon-Office/Box-Agent \
  --pattern "box-agent-runtime-*.tar.gz"
```

Available platforms: `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`

### Runtime Structure

```
box-agent-runtime/
├── manifest.json          # {"name","version","platform","arch","entry","mode"}
├── VERSION                # Plain text version
└── bin/
    ├── box-agent-acp      # Entry binary
    └── _internal/         # Bundled Python + dependencies
```

### Integration Protocol

The runtime binary communicates via **ACP JSON-RPC over stdio**:
- **stdin**: JSON-RPC requests from host process
- **stdout**: JSON-RPC responses only (zero diagnostic output)
- **stderr**: All logs, diagnostics, tool loading status

Environment variables for debug logging:
- `BOX_AGENT_LOG_LEVEL`: `DEBUG` | `INFO` | `WARN` | `ERROR` (default: `INFO`)
- `BOX_AGENT_LOG_FILE`: Path to log file (in addition to stderr)
- `BOX_AGENT_LOG_FORMAT`: `text` | `json` (default: `text`)

### Build from Source

```bash
# Install build dependencies
uv sync --group dev

# Build for current platform (reads version from __version__)
uv run python scripts/build_runtime.py

# Output: dist/runtime/box-agent-runtime-v{version}-{platform}-{arch}.tar.gz
```

## Usage Examples

Here are a few examples of what Box Agent can do.

### Task Execution

*In this demo, the agent is asked to create a simple, beautiful webpage and display it in the browser, showcasing the basic tool-use loop.*

![Demo GIF 1: Basic Task Execution](docs/assets/demo1-task-execution.gif "Basic Task Execution Demo")

### Using a Claude Skill (e.g., PDF Generation)

*Here, the agent leverages a Claude Skill to create a professional document (like a PDF or DOCX) based on the user's request, demonstrating its advanced capabilities.*

![Demo GIF 2: Claude Skill Usage](docs/assets/demo2-claude-skill.gif "Claude Skill Usage Demo")

### Web Search & Summarization (MCP Tool)

*This demo shows the agent using its web search tool to find up-to-date information online and summarize it for the user.*

![Demo GIF 3: Web Search](docs/assets/demo3-web-search.gif "Web Search Demo")

## Testing

The project includes comprehensive test cases covering unit tests, functional tests, and integration tests.

### Quick Run

```bash
# Run all tests
pytest tests/ -v

# Run core functionality tests
pytest tests/test_agent.py tests/test_note_tool.py -v
```

### Test Coverage

- ✅ **Unit Tests** - Tool classes, LLM client
- ✅ **Functional Tests** - Session Note Tool, MCP loading
- ✅ **Integration Tests** - Agent end-to-end execution
- ✅ **External Services** - Git MCP Server loading


## Troubleshooting

### SSL Certificate Error

If you encounter `[SSL: CERTIFICATE_VERIFY_FAILED]` error:

**Quick fix for testing** (modify `box_agent/llm.py`):
```python
# Line 50: Add verify=False to AsyncClient
async with httpx.AsyncClient(timeout=120.0, verify=False) as client:
```

**Production solution**:
```bash
# Update certificates
pip install --upgrade certifi

# Or configure system proxy/certificates
```

### Module Not Found Error

Make sure you're running from the project directory:
```bash
cd Box-Agent
python -m box_agent.cli
```

## Related Documentation

- [Development Guide](docs/DEVELOPMENT_GUIDE.md) - Detailed development and configuration guidance
- [Production Guide](docs/PRODUCTION_GUIDE.md) - Best practices for production deployment

## Contributing

Issues and Pull Requests are welcome!

- [Contributing Guide](CONTRIBUTING.md) - How to contribute
- [Code of Conduct](CODE_OF_CONDUCT.md) - Community guidelines

## License

This project is licensed under the [MIT License](LICENSE).

## References

- Anthropic API: https://docs.anthropic.com/claude/reference
- OpenAI API: https://platform.openai.com/docs/api-reference
- Claude Skills: https://github.com/anthropics/skills
- MCP Servers: https://github.com/modelcontextprotocol/servers

---

**⭐ If this project helps you, please give it a Star!**
