Metadata-Version: 2.4
Name: mini-box-agent
Version: 0.1.0
Summary: Minimal AI agent with Python sandbox for data analysis
Author: Mini Box Agent Team
License: MIT
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: pytest>=8.4.2
Requires-Dist: requests>=2.31.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: pip>=25.3
Requires-Dist: pipx>=1.8.0
Requires-Dist: anthropic>=0.39.0
Requires-Dist: openai>=1.57.4
Requires-Dist: agent-client-protocol>=0.6.0
Requires-Dist: jupyter>=1.0.0
Requires-Dist: jupyter_client>=8.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: matplotlib>=3.7.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: license-file

# Mini Box Agent

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

**Mini Box Agent** is a minimal yet professional AI agent with Python sandbox capabilities for data analysis. It supports multiple LLM providers (Anthropic, OpenAI) and features interleaved thinking for powerful reasoning on complex tasks.

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

*   ✅ **Full Agent Execution Loop**: A complete and reliable foundation with a basic toolset for file system and shell operations.
*   ✅ **Persistent Memory**: An active **Session Note Tool** ensures the agent retains key information across multiple sessions.
*   ✅ **Intelligent Context Management**: Automatically summarizes conversation history to handle contexts up to a configurable token limit, enabling infinitely long tasks.
*   ✅ **Claude Skills Integration**: Comes with 15 professional skills for documents, design, testing, and development.
*   ✅ **MCP Tool Integration**: Natively supports MCP for tools like knowledge graph access and web search.
*   ✅ **Python Sandbox**: Secure Jupyter-based Python execution with pandas, numpy, matplotlib support. Includes timeout, memory limits, and dangerous command blocking.
*   ✅ **Comprehensive Logging**: Detailed logs for every request, response, and tool execution for easy debugging.
*   ✅ **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

- [Mini Box Agent](#mini-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)
  - [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. Install

**Prerequisites: Install uv**

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

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex
# Restart terminal after installation
```

**Install Mini Box Agent:**

```bash
# Install in editable mode
cd /path/to/Mini-Agent_opencode
uv tool install -e .

# Or install from PyPI (when published)
uv tool install mini-box-agent
```

### 2. Run - Interactive Setup

Simply run:

```bash
mini-box
```

On first run, you'll be guided through interactive setup:
1. Select LLM Provider (Anthropic or OpenAI)
2. Enter API Base URL (defaults provided for official APIs)
3. Select Model (common options provided)
4. Enter API Key
5. API Key will be validated automatically

**Usage:**

```bash
mini-box                                    # Use current directory as workspace
mini-box --workspace /path/to/project      # Specify workspace directory
mini-box --task "analyze data.csv"        # Run task non-interactively
mini-box --validate                        # Validate existing API key
mini-box --version                         # Check version
mini-box log                               # View logs

# Management
uv tool upgrade mini-box                   # Upgrade
uv tool uninstall mini-box                 # Uninstall
```

### 3. Configuration

Configuration is stored in `~/.mini-box-agent/config/config.yaml`.

Manual configuration:

```yaml
api_key: "YOUR_API_KEY_HERE"
provider: "anthropic"  # or "openai"
api_base: "https://api.anthropic.com"  # or your custom endpoint
model: "claude-3-5-sonnet"  # or your chosen model
```

### Development Mode

For developers who need to modify code:

```bash
# Clone and install
git clone https://github.com/your-repo/Mini-Agent.git
cd Mini-Agent
uv sync

# Run directly
uv run python -m mini_box_agent.cli

# Or install in editable mode
uv tool install -e .
```

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

## ACP & Zed Editor Integration(optional)

Mini 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 Mini Box Agent in development mode or as a tool
2. Add to your Zed `settings.json`:

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

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

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

## Usage Examples

Here are a few examples of what Mini 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")

### Python Sandbox

Mini Box Agent includes a secure Jupyter-based Python execution sandbox for data analysis and visualization tasks.

**Features:**
- **Secure Execution**: Blocks dangerous commands (os, subprocess, eval, exec)
- **Timeout Control**: 300 second timeout per execution prevents infinite loops
- **Memory Limits**: Detects and prevents memory-intensive operations
- **Persistent State**: Variables persist within a session
- **Rich Libraries**: pandas, numpy, matplotlib, scipy pre-installed

**Usage:**
```bash
mini-box --sandbox    # Enable sandbox (default)
mini-box --no-sandbox # Disable sandbox

# In chat, use execute_code tool:
# > Analyze this CSV file and create a visualization
```

**Example Code Execution:**
```
>>> import pandas as pd
>>> df = pd.read_csv('data.csv')
>>> df.describe()
```

**Security:**
- Blocked: `import os`, `subprocess`, `eval()`, `exec()`, `sys.exit()`
- Blocked: Absolute file paths like `open('/etc/passwd')`
- Sandboxed: Each session runs in isolated directory

### Multi-Sandbox for Parallel Analysis

For analyzing multiple files simultaneously, use the `multi_sandbox` tool:

```python
# Create two isolated sessions
multi_sandbox(action="create")  # Returns session_id_1
multi_sandbox(action="create")  # Returns session_id_2

# Execute in parallel
multi_sandbox(action="execute", session_id=session_id_1, code="import pandas as pd; df1 = pd.read_csv('file1.csv')")
multi_sandbox(action="execute", session_id=session_id_2, code="import pandas as pd; df2 = pd.read_csv('file2.csv')")

# List active sessions
multi_sandbox(action="list")

# Clean up
multi_sandbox(action="close", session_id=session_id_1)
multi_sandbox(action="close_all")
```

**Use cases:**
- Parallel data analysis on multiple files
- Isolated analysis to prevent interference
- Long-running tasks that don't block each other

## 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
- ✅ **Sandbox Tests** - Security blocking, timeout, interrupt, kernel management, multi-sandbox isolation
- ✅ **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 `mini_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 Mini-Agent
python -m mini_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

## Community

Join the MiniMax official community to get help, share ideas, and stay updated:

- **WeChat Group**: Scan the QR code on [Contact Us](https://platform.minimaxi.com/docs/faq/contact-us) page to join

## 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
- Claude Skills: https://github.com/anthropics/skills
- MCP Servers: https://github.com/modelcontextprotocol/servers

---

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