agentic-python-coder 2.1.0__tar.gz → 2.2.1__tar.gz

{agentic_python_coder-2.1.0 → agentic_python_coder-2.2.1}/.gitignore

@@ -152,7 +152,9 @@ cython_debug/
 uv.lock
 
 # Project specific
+coder-examples/
 CLAUDE-archive.md
+PROCESS_NOTES.md
 conversation_log.json
 coder_output.log
 task.md
@@ -173,10 +175,10 @@ 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.1.0 → agentic_python_coder-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-python-coder
-Version: 2.1.0
+Version: 2.2.1
 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
@@ -106,7 +198,7 @@ messages, stats, log_path = coder.solve_task(
     "Write a fibonacci function",
     working_directory="/tmp/workspace",
     model="sonnet45",
-    quiet=True,  # Suppress console output
+    quiet=True,
 )
 
 # Get the final response
@@ -114,13 +206,9 @@ response = coder.get_final_response(messages)
 print(response)
 ```
 
----
-
-## API Reference
-
-### `solve_task()` — High-Level API
+### Library API Reference
 
-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
@@ -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
@@ -166,189 +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, list_available_models
 
-# Get LLM by model name
 llm = get_openrouter_llm(model="sonnet45")
-
-# See available models
 print(list_available_models())
 # ['deepseek31', 'gemini25', 'gpt5', 'grok41', 'opus45', 'qwen3', 'sonnet45']
-
-# Use a custom model JSON file
-llm = get_openrouter_llm(model="./mymodel.json")
 ```
 
 ---
 
-## CLI Reference
+## The MCP Server
 
-### Basic Commands
+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.
 
-```bash
-# Inline task
-coder "your task"
+### MCP Server Configuration
 
-# Task from file (creates {basename}_code.py and {basename}.jsonl)
-coder --task problem.md
+Add to your MCP settings (e.g., `~/.claude/claude_desktop_config.json` or project `.mcp.json`):
 
-# Specify working directory
-coder --dir results/test1 "your task"
-
-# 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 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"
-```
+| `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. |
 
-### Project Templates
+### Features
 
-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
-```
+- **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
 
-Then use them:
+### Usage Tips
 
-```bash
-# Constraint programming
-coder --with cpmpy --project coder-examples/cpmpy/cpmpy.md "Solve 8-queens"
-
-# Run a sample task
-coder --with cpmpy --project coder-examples/cpmpy/cpmpy.md \
-      --task coder-examples/cpmpy/sample_tasks/n_queens.md
-
-# Answer Set Programming
-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
-# 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