agentic-python-coder 2.0.1__tar.gz → 2.2.0__tar.gz

{agentic_python_coder-2.0.1 → agentic_python_coder-2.2.0}/.gitignore

@@ -153,6 +153,7 @@ uv.lock
 
 # Project specific
 CLAUDE-archive.md
+PROCESS_NOTES.md
 conversation_log.json
 coder_output.log
 task.md
@@ -164,15 +165,19 @@ TRASH/
 LOCAL/
 ASP/
 CPBENCH/
+CPMPY/
 PAPER/
+PAPER-ASP/
+ZEBRA/
+.mcp.json
 examples/cpmpy/cpmpy_v*.md
 examples/cpmpy/cpmpy.md.backup-*
 examples/clingo/clingo_v*.md
 
-# Test files and folders
-test-*/
-test_*.py
-test_*/
+# Test files and folders (root level only)
+/test-*/
+/test_*.py
+/test_*/
 PROBLEM.md
 *.log
 

{agentic_python_coder-2.0.1 → agentic_python_coder-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-python-coder
-Version: 2.0.1
+Version: 2.2.0
 Summary: A lightweight Python coding agent that writes, executes, and iterates on code through natural language instructions
 Author: Stefan Szeider
 License: Apache-2.0
@@ -21,6 +21,7 @@ Requires-Dist: langchain-core>=1.1.0
 Requires-Dist: langchain-experimental>=0.4.0
 Requires-Dist: langchain-openai>=1.1.0
 Requires-Dist: langgraph>=1.0.4
+Requires-Dist: mcp>=1.0.0
 Requires-Dist: python-dotenv>=1.2.1
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: rich>=14.2.0
@@ -28,6 +29,7 @@ Provides-Extra: dev
 Requires-Dist: mypy>=1.19.0; extra == 'dev'
 Requires-Dist: ruff>=0.14.7; extra == 'dev'
 Provides-Extra: test
+Requires-Dist: pytest-asyncio>=1.2.0; extra == 'test'
 Requires-Dist: pytest-cov>=7.0.0; extra == 'test'
 Requires-Dist: pytest-watch>=4.2.0; extra == 'test'
 Requires-Dist: pytest>=9.0.1; extra == 'test'
@@ -37,10 +39,16 @@ Description-Content-Type: text/markdown
 
 [![Python 3.13](https://img.shields.io/badge/python-3.13-blue.svg)](https://www.python.org/downloads/)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
 [![UV](https://img.shields.io/badge/Packaged%20with-UV-purple)](https://github.com/astral-sh/uv)
 [![LangGraph](https://img.shields.io/badge/Built%20with-LangGraph-green)](https://github.com/langchain-ai/langgraph)
 
-A Python coding agent using the ReAct framework with a persistent IPython kernel. Works as a **CLI tool** or as a **Python library** for integration into your own applications.
+This package provides two utilities for Python code execution:
+
+1. **coder** — An autonomous coding agent using the ReAct framework (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]](https://arxiv.org/abs/2508.07468).
 
@@ -50,52 +58,136 @@ For details on architecture and constraint modelling applications, see [[Szeider
 
 - Python 3.13
 - UV package manager: `curl -LsSf https://astral.sh/uv/install.sh | sh`
-- OpenRouter API key from [openrouter.ai](https://openrouter.ai)
 
-### CLI Installation
+### For the Coding Agent
 
 ```bash
 # Install as CLI tool
 uv tool install agentic-python-coder
 
-# Set up API key
+# Set up OpenRouter API key
 mkdir -p ~/.config/coder
 echo 'OPENROUTER_API_KEY="your-key-here"' > ~/.config/coder/.env
 ```
 
-### Library Installation
+Get your API key from [openrouter.ai](https://openrouter.ai).
 
-```bash
-# Add to your project
-uv add agentic-python-coder
+### For the MCP Server
 
-# Or with pip
-uv pip install agentic-python-coder
-```
+No installation required — use `uvx` to run directly. See [MCP Server Configuration](#mcp-server-configuration).
 
-API key options:
-- Pass directly: `solve_task(..., api_key="sk-or-...")`
-- Environment variable: `export OPENROUTER_API_KEY="sk-or-..."`
-- Config file: `~/.config/coder/.env` (same as CLI)
+---
 
 ## Quick Start
 
-### CLI Usage
+### Option A: Autonomous Agent
 
 ```bash
 # Simple task
 coder "Create a function that calculates factorial"
 
-# Task from file
+# 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:
+
+```json
+{
+  "mcpServers": {
+    "ipython": {
+      "command": "uvx",
+      "args": ["--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
+
+```bash
+# Inline task
+coder "your task"
+
+# Task from file (creates {basename}_code.py and {basename}.jsonl)
 coder --task problem.md
 
-# Initialize example templates (one-time)
+# Specify working directory
+coder --dir results/test1 "your task"
+
+# Interactive mode
+coder -i
+```
+
+### CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `--version`, `-V` | Show version and exit |
+| `--init [TEMPLATE]` | Initialize example templates (cpmpy, clingo, regex, or all) |
+| `--task`, `-t FILE` | Load task from markdown file |
+| `--model MODEL` | Model name or JSON file (default: sonnet45) |
+| `--project`, `-p FILE` | Project template for domain-specific prompts |
+| `--with PACKAGE` | Add packages dynamically (repeatable) |
+| `--dir`, `-d DIR` | Working directory |
+| `--api-key KEY` | Override API key |
+| `--todo` | Enable task tracking tool |
+| `--quiet`, `-q` | Suppress console output |
+| `--step-limit N` | Max agent steps (default: 200) |
+| `-i`, `--interactive` | Interactive conversation mode |
+
+### Model Selection
+
+```bash
+# Built-in models (versioned names)
+coder --model sonnet45 "task"   # Claude Sonnet 4.5 (default)
+coder --model opus45 "task"     # Claude Opus 4.5
+coder --model deepseek31 "task" # DeepSeek v3.1
+coder --model grok41 "task"     # X.AI Grok 4.1
+coder --model qwen3 "task"      # Qwen3 Coder
+coder --model gemini25 "task"   # Gemini Pro 2.5
+coder --model gpt5 "task"       # GPT-5
+
+# Custom model (JSON file)
+coder --model ./mymodel.json "task"
+```
+
+### Project Templates
+
+Domain-specific templates improve results:
+
+```bash
+# Initialize example templates (creates coder-examples/ directory)
 coder --init
 
-# With packages and project template
+# Constraint programming with CPMpy
 coder --with cpmpy --project coder-examples/cpmpy/cpmpy.md "Solve 8-queens"
+
+# Answer Set Programming with Clingo
+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:
+
+```bash
+coder -i --project coder-examples/cpmpy/cpmpy.md --with cpmpy
 ```
 
+State is preserved across turns. Type `exit` or `quit` to end.
+
 ### Library Usage
 
 ```python
@@ -105,8 +197,8 @@ import agentic_python_coder as coder
 messages, stats, log_path = coder.solve_task(
     "Write a fibonacci function",
     working_directory="/tmp/workspace",
-    model="sonnet",
-    quiet=True,  # Suppress console output
+    model="sonnet45",
+    quiet=True,
 )
 
 # Get the final response
@@ -114,13 +206,9 @@ response = coder.get_final_response(messages)
 print(response)
 ```
 
----
-
-## API Reference
+### Library API Reference
 
-### `solve_task()` — High-Level API
-
-Run a complete coding task end-to-end. Recommended for most use cases.
+#### `solve_task()` — High-Level API
 
 ```python
 from agentic_python_coder import solve_task
@@ -128,7 +216,7 @@ 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 alias: "sonnet", "opus", "deepseek", etc.
+    model=None,                      # Model name: "sonnet45", "opus45", 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
@@ -147,9 +235,7 @@ messages, stats, log_path = solve_task(
 - `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
-
-For custom workflows, multi-turn conversations, or fine-grained control.
+#### `create_coding_agent()` / `run_agent()` — Low-Level API
 
 ```python
 from agentic_python_coder import create_coding_agent, run_agent, get_final_response
@@ -158,7 +244,7 @@ from agentic_python_coder import create_coding_agent, run_agent, get_final_respo
 agent = create_coding_agent(
     working_directory="/tmp/workspace",
     system_prompt="You are a Python expert.",
-    model="deepseek",
+    model="deepseek31",
     with_packages=["pandas"],
 )
 
@@ -166,182 +252,91 @@ agent = create_coding_agent(
 messages, stats = run_agent(agent, "Load data.csv", quiet=True)
 messages2, stats2 = run_agent(agent, "Now plot column A", quiet=True)
 
-# Extract response
 print(get_final_response(messages2))
 ```
 
-### `get_openrouter_llm()` — LLM Access
-
-Get a configured LangChain LLM instance for custom use.
+#### `get_openrouter_llm()` — LLM Access
 
 ```python
-from agentic_python_coder import get_openrouter_llm, MODEL_REGISTRY
-
-# Get LLM by alias
-llm = get_openrouter_llm(model="sonnet")
+from agentic_python_coder import get_openrouter_llm, list_available_models
 
-# See available models
-print(MODEL_REGISTRY.keys())
-# dict_keys(['deepseek', 'sonnet', 'opus', 'default', 'grok', 'qwen', 'gemini', 'gpt'])
+llm = get_openrouter_llm(model="sonnet45")
+print(list_available_models())
+# ['deepseek31', 'gemini25', 'gpt5', 'grok41', 'opus45', 'qwen3', 'sonnet45']
 ```
 
 ---
 
-## CLI Reference
+## The MCP Server
 
-### Basic Commands
-
-```bash
-# Inline task
-coder "your task"
+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.
 
-# Task from file (creates {basename}_code.py and {basename}.jsonl)
-coder --task problem.md
+### MCP Server Configuration
 
-# Specify working directory
-coder --dir results/test1 "your task"
+Add to your MCP settings (e.g., `~/.claude/claude_desktop_config.json` or project `.mcp.json`):
 
-# Interactive mode
-coder -i
+```json
+{
+  "mcpServers": {
+    "ipython": {
+      "command": "uvx",
+      "args": ["--from", "agentic-python-coder", "ipython_mcp"]
+    }
+  }
+}
 ```
 
-### Options
+### Available Tools
 
-| Flag | Description |
+| Tool | Description |
 |------|-------------|
-| `--version`, `-V` | Show version and exit |
-| `--init [TEMPLATE]` | Initialize example templates (cpmpy, clingo, regex, or all) |
-| `--task`, `-t FILE` | Load task from markdown file |
-| `--model MODEL` | Model to use (default: sonnet) |
-| `--project`, `-p FILE` | Project template for domain-specific prompts |
-| `--with PACKAGE` | Add packages dynamically (repeatable) |
-| `--dir`, `-d DIR` | Working directory |
-| `--api-key KEY` | Override API key |
-| `--todo` | Enable task tracking tool |
-| `--quiet`, `-q` | Suppress console output |
-| `--step-limit N` | Max agent steps (default: 200) |
-| `-i`, `--interactive` | Interactive conversation mode |
-
-### Model Selection
-
-```bash
-coder --model sonnet "task"     # Claude Sonnet 4.5 (default)
-coder --model opus "task"       # Claude Opus 4.5
-coder --model deepseek "task"   # DeepSeek v3.1
-coder --model grok "task"       # X.AI Grok
-coder --model qwen "task"       # Qwen3 Coder
-coder --model gemini "task"     # Gemini Pro 2.5
-coder --model gpt "task"        # GPT-5
-```
-
-### Project Templates
-
-Domain-specific templates improve results. First, initialize the examples:
-
-```bash
-# Initialize all example templates (creates coder-examples/ directory)
-coder --init
-
-# Or initialize only specific templates
-coder --init cpmpy
-```
-
-Then use them:
-
-```bash
-# Constraint programming
-coder --with cpmpy --project coder-examples/cpmpy/cpmpy.md "Solve 8-queens"
+| `python_exec` | Execute Python code. Auto-starts session if needed. Default 30s timeout. |
+| `python_reset` | Clear session state. Optionally install packages (e.g., `packages=["numpy", "pandas"]`). |
+| `python_status` | Check if session is active, Python version, installed packages, defined variables. |
+| `python_interrupt` | Send interrupt signal to stop long-running code. Session state is preserved. |
 
-# Run a sample task
-coder --with cpmpy --project coder-examples/cpmpy/cpmpy.md \
-      --task coder-examples/cpmpy/sample_tasks/n_queens.md
+### Features
 
-# Answer Set Programming
-coder --with clingo --project coder-examples/clingo/clingo.md "Model bird flight"
-```
+- **Persistent state**: Variables, imports, and definitions persist across executions
+- **Auto-start**: 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
 
-### Interactive Mode
+### Usage Tips
 
-Interactive mode (`-i`) maintains a persistent session for multi-turn conversations:
-
-```bash
-# Start interactive session
-coder -i
-
-# With project template
-coder -i --project coder-examples/cpmpy/cpmpy.md --with cpmpy
-```
-
-**Features:**
-- Persistent IPython kernel (state preserved across turns)
-- Type `exit` or `quit` to end session
-- Cumulative statistics shown on exit
-- Conversation log saved to `log.jsonl`
-
-**Example session:**
-```
-$ coder -i
-Interactive mode - working in: /path/to/dir
-Type 'exit' or 'quit' to stop.
-
-You: Load data.csv and show the columns
-Agent working...
-[Agent loads file, displays columns]
-
-You: Plot the 'sales' column
-Agent working...
-[Agent creates plot using existing dataframe]
-
-You: exit
-Goodbye!
-Log saved to: log.jsonl
-```
+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
+### API Key (Coding Agent only)
 
-The agent looks for API key in order:
+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
 
 ```bash
-# Recommended: one-time setup
 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
 
 | Variable | Description |
 |----------|-------------|
-| `OPENROUTER_API_KEY` | API key for OpenRouter |
+| `OPENROUTER_API_KEY` | API key for OpenRouter (agent only) |
 | `CODER_VERBOSE` | Show detailed model configuration |
-| `CODER_WITH_PACKAGES` | Comma-separated packages (internal use) |
-
----
-
-## How It Works
-
-1. Task is parsed and sent to the LLM
-2. Agent reasons about approach using ReAct framework
-3. Code executes in persistent IPython kernel (state preserved)
-4. Errors detected and fixed automatically
-5. Solution refined until complete
-
-### Output Files
-
-- **Inline tasks**: `solution.py` + `log.jsonl`
-- **File tasks**: `{basename}_code.py` + `{basename}.jsonl`
 
 ---
 
 ## Security Notice
 
-**This is experimental software.** The agent executes code automatically.
+**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