py4agent 0.0.3
Python Dev Kit Inside Code Interpreter for AI Agents - Jupyter-based code execution with multimodal support
Requires Python: >=3.9
Keywords: jupyter, code-interpreter, ai-agent, code-execution, multimodal

# 🤖 py4agent - Python Dev Kit Inside Code Interpreter for AI Agents

A Jupyter-based code execution server with multimodal support designed for AI agents to execute Python code safely and efficiently.

## Features

- 🚀 Fast and reliable code execution via Jupyter kernels
- 🎨 Multimodal output support (text, plots, tables, images)
- 🌐 MCP (Model Context Protocol) server support
- 🔧 Dev Kit Inside Code Interpreter

## 🚀 Quick Start

### 📦 Installation

```bash
pip install py4agent --upgrade
```

For detailed installation instructions, see [INSTALL.md](docs/INSTALL.md).

### ▶️ Running the Code Interpreter Server with Third-Party Jupyter Server

Set up your Jupyter connection parameters:
```bash
jupyterlab --no-browser --port=8888 --NotebookApp.token='your-token-here'
```

Dynamically connect to your Jupyter server and start executing code!

```bash
export JUPYTER_HOST="localhost"
export JUPYTER_PORT="8888"
export JUPYTER_TOKEN="your-token-here"
py4agent --host 0.0.0.0 --port 8889 --debug --workers 4
```

### 🔌 Running the MCP Server with Self-Contains Jupyter Kernel Manager

Just start it directly without needing an external Jupyter server:

```bash
py4agent-mcp --host 0.0.0.0 --port 8889 --debug --workers 4
```

## 📁 Project Structure

```
py4agent/
├── __init__.py           # Package initialization
├── __main__.py           # Main entry point
├── server.py             # FastAPI server implementation
├── mcp_server.py         # MCP server implementation
└── injection/           # Code injection utilities
    ├── __main__.py      # Injection entry point
    ├── jupyter_parse.py # Jupyter message parsing
    ├── display_mime.py  # MIME type display handling
    ├── multimodal.py    # Multimodal output handling
    ├── types.py         # Type definitions
    └── blocks/          # Display block implementations
        ├── plotly_json.py      # Plotly visualization
        ├── table_json.py       # Table display
        ├── search_result.py    # Search results
        └── visual_json.py      # Visual display
```

## 📡 API Usage

See the full test examples in [test.py](test.py).

### ⚡ Execute Code

```bash
curl -X POST http://localhost:8889/execute \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(1+1)",
    "kernel_id": "your-kernel-id",
    "jupyter_host": "localhost",
    "jupyter_port": "8888",
    "jupyter_token": "your-token",
    "session_id": "test",
    "timeout": 10
  }'
```

### 🔧 Create Kernel

```bash
curl -X POST http://localhost:8889/jupyter/create \
  -H "Content-Type: application/json" \
  -d '{
    "jupyter_host": "localhost",
    "jupyter_port": "8888",
    "jupyter_token": "your-token"
  }'
```

## 🛠️ Development

### 📚 Dependencies Management

The dependencies are organized into:

- **Core**: Web framework and HTTP clients (FastAPI, uvicorn, httpx)
- **Scientific Computing**: NumPy, Pandas, SciPy, scikit-learn, etc.
- **Visualization**: Plotly, Matplotlib, Seaborn, etc.
- **Database**: SQLAlchemy, Redis, MongoDB, etc.
- **Web Scraping**: BeautifulSoup, Selenium, Playwright
- **Dev**: Testing and linting tools (pytest, black, ruff, mypy)

### 🧪 Testing

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# With coverage
pytest --cov=py4agent
```

### ✨ Code Quality

```bash
# Format code
black py4agent/

# Lint code
ruff check py4agent/

# Type checking
mypy py4agent/
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [FastAPI](https://fastapi.tiangolo.com/)
- Powered by [Jupyter](https://jupyter.org/)
- Visualization by [Plotly](https://plotly.com/)

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📧 Contact

- GitHub: [@LinXueyuanStdio](https://github.com/LinXueyuanStdio)
- Issues: [GitHub Issues](https://github.com/LinXueyuanStdio/code_interpreter_server/issues)