🤖 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

pip install py4agent --upgrade

For detailed installation instructions, see INSTALL.md.

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

Set up your Jupyter connection parameters:

jupyter-lab --no-browser --port=8888 --NotebookApp.token='your-token-here'

Dynamically connect to your Jupyter server and start executing code!

export JUPYTER_HOST="localhost"
export JUPYTER_PORT="8888"
export JUPYTER_TOKEN="your-token-here"
py4agent-server --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:

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

📁 Project Structure

py4agent/
├── __init__.py           # Package initialization
└── 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.

⚡ Execute Code

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

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

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

# Run tests
pytest

# With coverage
pytest --cov=py4agent

✨ Code Quality

# 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 file for details.

🙏 Acknowledgments

• Built with FastAPI
• Powered by Jupyter
• Visualization by Plotly

🤝 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
• Issues: GitHub Issues