Agentic Python Coder

This package provides two utilities for Python code execution:

1. coder — An autonomous coding agent using the ReAct pattern (CLI + Python library)
2. ipython_mcp — An MCP server that gives any MCP-compatible client (Claude Desktop, etc.) Python execution capability

Both share a persistent IPython kernel for stateful code execution.

For details on architecture and constraint modelling applications, see [Szeider 2025, arxiv-2508.07468].

Installation

Prerequisites

• Python 3.13 or newer
• UV package manager: curl -LsSf https://astral.sh/uv/install.sh | sh

For the Coding Agent

# Install as CLI tool (--python 3.14: ortools, used by cpmpy, has no 3.15 wheels yet)
uv tool install --python 3.14 agentic-python-coder

# Set up OpenRouter API key
mkdir -p ~/.config/coder
echo 'OPENROUTER_API_KEY="your-key-here"' > ~/.config/coder/.env

Get your API key from openrouter.ai.

For the MCP Server

No installation required — use uvx to run directly. See MCP Server Configuration.

Quick Start

Option A: Autonomous Agent

# Simple task
coder "Create a function that calculates factorial"

# With packages and project template
coder --with cpmpy --project coder-examples/cpmpy/cpmpy.md "Solve 8-queens"

# Interactive mode
coder -i

Option B: MCP Server

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "ipython": {
      "command": "uvx",
      "args": ["--python", "3.14", "--from", "agentic-python-coder", "ipython_mcp"]
    }
  }
}

Then ask Claude Desktop to execute Python code — it will use the persistent IPython session.

The Coding Agent

CLI Usage

# Inline task
coder "your task"

# Task from file (creates {basename}_code.py and {basename}.jsonl)
coder --task problem.md

# Specify working directory
coder --dir results/test1 "your task"

# Interactive mode
coder -i

CLI Options

Model Selection

# Built-in models (versioned names)
coder --model sonnet45 "task"   # Claude Sonnet 4.5
coder --model sonnet46 "task"   # Claude Sonnet 4.6
coder --model sonnet5 "task"    # Claude Sonnet 5
coder --model opus45 "task"     # Claude Opus 4.5
coder --model opus48 "task"     # Claude Opus 4.8
coder --model sonnet55 "task"   # Claude Sonnet 5.5 (default)
coder --model opus55 "task"     # Claude Opus 5.5
coder --model deepseek31 "task" # DeepSeek v3.1
coder --model grok47 "task"     # X.AI Grok 4.7
coder --model qwen3 "task"      # Qwen3 Coder
coder --model gemini25 "task"     # Gemini Pro 2.5
coder --model gemini31 "task"      # Gemini 3.1 Pro Preview
coder --model gemini3flash "task"  # Gemini 3 Flash Preview (fast, low-cost)
coder --model gpt52 "task"         # GPT-5.2
coder --model gpt56sol "task"      # GPT-5.6 Sol
coder --model gpt56terra "task"    # GPT-5.6 Terra
coder --model gpt6sol "task"       # GPT-6 Sol
coder --model gpt6astra "task"     # GPT-6 Astra
coder --model gemini4argon "task"  # Gemini 4 Argon

# Custom model (JSON file)
coder --model ./mymodel.json "task"

A custom model JSON can also point at any OpenAI-compatible endpoint (OpenAI directly, a local Ollama/vLLM server, etc.) instead of OpenRouter:

{
  "path": "gpt-4o-mini",
  "base_url": "https://api.openai.com/v1",
  "api_key_env": "OPENAI_API_KEY",
  "temperature": 0.0
}

base_url overrides the OpenRouter endpoint; api_key_env names the environment variable holding the key for that endpoint (default: OPENROUTER_API_KEY).

Project Templates

Domain-specific templates improve results. Bundled examples are available on GitHub at coder/src/agentic_python_coder/examples/. Use --init to copy them locally:

# Copy all bundled examples to coder-examples/
coder --init

# Or copy a specific template
coder --init cpmpy

# Then use with your task
coder --with cpmpy --project coder-examples/cpmpy/cpmpy.md "Solve 8-queens"
coder --with clingo --project coder-examples/clingo/clingo.md "Model bird flight"

Interactive Mode

Interactive mode (-i) maintains a persistent session for multi-turn conversations:

coder -i --project coder-examples/cpmpy/cpmpy.md --with cpmpy

State is preserved across turns. Type exit or quit to end.

Library Usage

import agentic_python_coder as coder

# High-level: run a complete task
messages, stats, log_path = coder.solve_task(
    "Write a fibonacci function",
    working_directory="/tmp/workspace",
    model="sonnet55",
    quiet=True,
)

# Get the final response
response = coder.get_final_response(messages)
print(response)

Library API Reference

solve_task() — High-Level API

from agentic_python_coder import solve_task

messages, stats, log_path = solve_task(
    task="Your task description",
    working_directory=".",           # Where to run and save files
    model=None,                      # Model name: "sonnet55", "opus55", or JSON file
    system_prompt=None,              # Custom system prompt (string)
    system_prompt_path=None,         # Path to system prompt file
    project_prompt=None,             # Domain-specific context
    with_packages=None,              # ["pandas", "numpy"] for dynamic install
    api_key=None,                    # Override API key
    todo=False,                      # Enable todo_write tool
    quiet=False,                     # Suppress console output
    save_log=True,                   # Save conversation log
    task_basename=None,              # Base name for output files
    step_limit=None,                 # Max agent steps (default: 200)
    llm_config=None,                 # Pre-built LLMConfig (overrides model/api_key)
)

Returns: (messages, stats, log_path)

• messages: List of agent messages
• stats: Dict with tool_usage, token_consumption, execution_time_seconds
• log_path: Path to saved log file (or None if save_log=False)

create_coding_agent() / run_agent() — Low-Level API

from agentic_python_coder import create_coding_agent, run_agent, get_final_response

# Create agent
agent = create_coding_agent(
    working_directory="/tmp/workspace",
    system_prompt="You are a Python expert.",
    model="deepseek31",
    with_packages=["pandas"],
)

# Run one or more turns
messages, stats = run_agent(agent, "Load data.csv", quiet=True)
messages2, stats2 = run_agent(agent, "Now plot column A", quiet=True)

print(get_final_response(messages2))

Instead of a model name, you can pass a pre-built LLMConfig wrapping any OpenAI-compatible client:

from openai import OpenAI
from agentic_python_coder import LLMConfig, create_coding_agent

llm_config = LLMConfig(
    client=OpenAI(api_key="...", base_url="https://api.openai.com/v1"),
    model="gpt-4o-mini",
    api_params={"temperature": 0.0},
)

agent = create_coding_agent(
    working_directory="/tmp/workspace",
    llm_config=llm_config,
)

get_openrouter_llm() — LLM Access

from agentic_python_coder import get_openrouter_llm, list_available_models

llm = get_openrouter_llm(model="sonnet55")
print(list_available_models())
# ['deepseek31', 'gemini25', 'gemini31', 'gemini3flash', 'gpt52', ...]

The MCP Server

The ipython_mcp server provides Python code execution via the Model Context Protocol. Use it to give Claude Desktop (or any MCP-compatible client) the ability to run Python code in a persistent session.

MCP Server Configuration

Add to your MCP settings (e.g., ~/.claude/claude_desktop_config.json or project .mcp.json):

{
  "mcpServers": {
    "ipython": {
      "command": "uvx",
      "args": ["--python", "3.14", "--from", "agentic-python-coder", "ipython_mcp"]
    }
  }
}

Available Tools

Multi-Agent Workflow

For parallel agents, each agent gets its own kernel:

Agent A                              Agent B
────────                             ────────
python_reset() → kernel_id="aaa"     python_reset() → kernel_id="bbb"
python_exec(kernel_id="aaa", ...)    python_exec(kernel_id="bbb", ...)
python_exec(kernel_id="aaa", ...)    python_exec(kernel_id="bbb", ...)

Simple single-agent use: just call python_exec() — the default kernel auto-starts.

Features

• Persistent state: Variables, imports, and definitions persist across executions
• Auto-start: Default session starts automatically on first python_exec
• Package installation: Use python_reset with packages parameter to install dependencies
• Timeout handling: Long-running code times out gracefully (session preserved)
• Interrupt support: Stop runaway code without losing session state
• Multi-kernel: Each python_reset() creates an isolated kernel for parallel agents

Usage Tips

When using the MCP server for domain-specific tasks (constraint programming, ASP, etc.), provide the project template content directly in your conversation. For example, paste the contents of coder-examples/cpmpy/cpmpy.md when working with CPMpy.

Configuration

API Key (Coding Agent only)

The coding agent requires an OpenRouter API key. It looks in order:

1. --api-key flag or api_key parameter
2. ~/.config/coder/.env file
3. OPENROUTER_API_KEY environment variable

mkdir -p ~/.config/coder
echo 'OPENROUTER_API_KEY="sk-or-v1-..."' > ~/.config/coder/.env

The MCP server does not require an API key — it only executes code.

Environment Variables

Security Notice

This is experimental software. Both the coding agent and MCP server execute code automatically.

• Run in a VM or container for untrusted inputs
• Code executes in the working directory
• Use isolated environments for sensitive projects

License

Apache License 2.0 - see LICENSE for details.