agentic-python-coder 3.0.0__tar.gz → 3.2.0__tar.gz

agentic_python_coder-3.2.0/MEM/MEM_000.md

@@ -0,0 +1,114 @@
+---
+keywords: [session log, process notes, history]
+context: Searchable session log — grep when needed, not loaded routinely
+added: 2026-01-31
+---
+# Process Notes
+
+Searchable session log. Not loaded routinely—search with grep when needed.
+
+---
+## 2026-02-15
+
+**Goal**: Routine maintenance — dependency updates, new model config, code review fixes
+
+**Done**:
+- Bumped deps: openai 2.16→2.21, rich 14.3.1→14.3.2, ipykernel 7.1→7.2
+- Added gemini3flash model config (Gemini 3 Flash Preview)
+- Code review (ULTRA) found 6 issues in llm.py — all fixed: provider routing bug, OSError handling, model_path→model_id rename, empty "Available:" message, Warning→Error label, unnecessary ./ prefix
+- Published v3.1.0 to PyPI
+- Migrated EXPERTISE/ → MEM/ (2 entries + PROCESS_NOTES.md)
+
+**Tried**:
+- Initially copied gemini3pro.json params blindly for gemini3flash — Stefan caught this, verified actual supported params via WS7
+
+**Notes**: PyPI token is at ~/git/.pipy.txt (updated CLAUDE.md to record this)
+
+---
+
+
+## 2026-01-31 (session 3)
+
+**Goal**: Run e2e benchmark tests across models, fix failures, improve prompts, merge v3.0.0 to main, publish to PyPI
+
+**Done**:
+- Ran hard problem benchmarks (5 CPMpy + 5 Clingo) across opus45, gpt52, gemini3pro
+- Created gemini3pro.json model config (google/gemini-3-pro-preview)
+- Fixed gpt52 max_tokens: 3000→16384 (was truncating tool calls, caused 0/5 Clingo)
+- Rewrote Clingo validate.py (old one was wrong ASP-Bench full-suite validator)
+- Added mandatory verification prompts to system.md, system_todo.md, and save_code tool description
+- Analyzed GPT-5.2 CPMpy failures with GPTT consult (circular verification, wrong problem interpretation)
+- Fixed flaky test_todo_flag_integration (catch TimeoutExpired for partial output)
+- Squash-merged dev→main, published v3.0.0 to PyPI
+- Updated README: examples link, gemini3pro in model list
+
+**Tried**:
+- Verification prompts in system prompt + tool description — improved opus45 CPMpy 4/5→5/5 and gpt52 Clingo 0/5→5/5
+- GPT-5.2 on CPMpy still only 2/5 despite verification prompts — model sometimes ignores them (2 tool calls before save) or writes circular verify()
+- Gemini 3 Pro initially 0/10 with max_tokens=2048; bumped to 16384 → 5/10
+
+**Notes**: Key insight — verification gates work but models can write verify() functions that re-implement solver bugs instead of checking problem text independently. Future prompt work should address this circular verification pitfall.
+
+---
+
+## 2026-01-31 (session 2)
+
+**Goal**: Clean up dev branch for v3.0.0 release — model configs, tool descriptions, README, examples consolidation
+
+**Done**:
+- Replaced gpt5 model config with gpt52 (openai/gpt-5.2)
+- Restored verbose LangGraph-era tool descriptions in tools.py (fixes performance regression on hard tasks)
+- Restored parameter schemas to match tested reference (title fields, additionalProperties style)
+- Created EXPERTISE/E002_tool_description_quality.md
+- Removed LangGraph badge and references from README
+- Bumped all dependency minimum versions to current
+- Consolidated examples: deleted legacy examples/ dir, kept only bundled coder/src/.../examples/
+- Confirmed _todo.md project prompts are unused (--todo only switches system prompt)
+- Improved CPMpy project prompt with InDomain constraint and pitfalls section
+- Copied e2e challenge tests (hard_cpmpy, hard_clingo) to tests/ (gitignored)
+- All 70 unit tests pass
+
+**Tried**:
+- Initially kept minimal tool descriptions after LangGraph removal — caused performance regression on challenging tasks, discovered in separate test session
+- Tried using "description" field in JSON schemas instead of "title" — reverted to match LangGraph-generated style that was proven to work
+
+**Notes**: Tool descriptions are behavioral instructions for the model, not documentation. Verbose descriptions with examples, Args/Returns sections are essential for tool-calling quality. This is documented in E002.
+
+---
+
+## 2026-01-31
+
+**Goal**: Update model configs and fix tool description regression
+
+**Done**:
+- Replaced gpt5 model config with gpt52 (openai/gpt-5.2) — JSON, README, tests
+- Restored tool descriptions in tools.py to verbose LangGraph-era format (critical for performance)
+- Restored parameter schemas to match tested reference (title fields, additionalProperties style)
+- Created EXPERTISE/E002_tool_description_quality.md
+- Removed unused _task_basename import in test_library_api.py
+
+**Tried**:
+- Initially kept minimal tool descriptions after LangGraph removal — caused performance regression on challenging tasks
+- Discovered that verbose descriptions with examples, Args/Returns sections are essential for model tool-calling quality
+
+**Notes**: Tool descriptions are behavioral instructions for the model, not documentation for humans. This is a key insight for any framework migration.
+
+---
+
+## 2026-01-30
+
+**Goal**: Verify test suite, create expertise entry for frameworkless agent pattern, housekeeping
+
+**Done**:
+- Ran all 70 pytest tests — all pass after v3.0.0 migration
+- Confirmed examples/ has sample tasks but no automated e2e tests
+- Created EXPERTISE/E001_frameworkless_react_agent.md documenting the frameworkless ReAct pattern
+- Added EXPERTISE/ to .gitignore, committed and pushed to dev
+- Removed dead links from Key Documents (LOCAL/ directory no longer exists)
+
+**Tried**:
+- Looked for e2e tests in examples/ — only sample task files and one manual test run (regex/sample_tasks/test_email/)
+
+**Notes**: E2E tests remain the top priority open goal. They need mocked OpenAI API responses (mock client.chat.completions.create()).
+
+---

agentic_python_coder-3.2.0/MEM/MEM_001_frameworkless_react_agent.md

@@ -0,0 +1,110 @@
+---
+keywords: [react, agent, openai, frameworkless, langgraph, langchain, migration, tool-calling]
+context: Building LLM-powered agents without heavy frameworks (LangGraph, LangChain, CrewAI, etc.)
+added: 2026-01-30
+---
+# Frameworkless ReAct Agent Pattern
+
+## Insight
+
+A fully functional ReAct agent requires only ~4 components using the `openai` Python client directly, with no framework overhead:
+
+1. **LLM config** — A dataclass wrapping `openai.OpenAI` client, model path, and API params (temperature, max_tokens). Route through OpenRouter for multi-provider access.
+
+2. **Tool registry** — A `Tool` dataclass (name, description, JSON Schema parameters, callable function) with a `ToolRegistry` class that converts tools to OpenAI format via `to_openai_tool()`. Each tool's `execute()` returns a JSON string.
+
+3. **ReAct loop** — A simple `for step in range(limit)` loop that:
+   - Calls `client.chat.completions.create()` with messages + tools
+   - If response has `tool_calls`: execute each, append tool results to messages
+   - If no `tool_calls`: it's the final answer — break
+   - Messages list grows naturally (system → user → assistant+tool_calls → tool → assistant+tool_calls → ... → assistant)
+
+4. **Agent dataclass** — Holds config, tools, system prompt, working directory, and persistent `messages` list (enables multi-turn/interactive mode).
+
+### Key advantages over LangGraph/LangChain
+
+- **Dependency reduction**: 112 → 69 installed packages (removed all LangChain/LangGraph deps)
+- **Debuggability**: The entire agent loop is ~60 lines of straightforward Python. No graph compilation, no state machines, no hidden middleware.
+- **Message format control**: Full control over the `messages` list. No framework-imposed message wrappers or serialization formats.
+- **Token tracking**: Direct access to `response.usage.prompt_tokens` / `completion_tokens`.
+- **Error handling**: Tool errors are just JSON strings fed back to the model — the model self-corrects. No need for framework error recovery machinery.
+
+### Pitfalls learned during migration
+
+- **`model or "default"` bug**: If `model=""` (empty string), `or` evaluates to `"default"` — use explicit `None` checks instead.
+- **Environment variable leaks**: Global env vars (e.g., `CODER_WITH_PACKAGES`) persist across runs — always clear them with `os.environ.pop()` when not set.
+- **Global state accumulation**: Module-level globals (todo lists, file basenames) accumulate across runs. Add a `reset_global_state()` function called at agent creation time.
+- **Tool call message format**: OpenAI API requires tool_calls in assistant messages to be dicts with `id`, `type`, `function.name`, `function.arguments`. Missing any field causes cryptic errors.
+- **UTF-8 encoding**: Always use `encoding="utf-8"` when opening files — platform default encoding can vary.
+
+### When to use a framework instead
+
+- If you need **graph-based workflows** with conditional branching between multiple agents
+- If you need **built-in memory/persistence** across sessions (vector stores, checkpoints)
+- If you need **streaming with backpressure** and complex output routing
+- For simple single-agent ReAct loops, the framework adds complexity without benefit
+
+## Example
+
+```python
+from dataclasses import dataclass, field
+from openai import OpenAI
+import json
+
+@dataclass
+class Tool:
+    name: str
+    description: str
+    parameters: dict
+    function: callable
+
+    def to_openai_tool(self):
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    def execute(self, **kwargs):
+        return self.function(**kwargs)
+
+# ReAct loop core (~30 lines)
+def run(client, model, messages, tools, limit=200):
+    openai_tools = [t.to_openai_tool() for t in tools]
+    tool_map = {t.name: t for t in tools}
+
+    for _ in range(limit):
+        resp = client.chat.completions.create(
+            model=model, messages=messages, tools=openai_tools, tool_choice="auto"
+        )
+        msg = resp.choices[0].message
+
+        if msg.tool_calls:
+            messages.append({
+                "role": "assistant",
+                "content": msg.content or "",
+                "tool_calls": [
+                    {"id": tc.id, "type": "function",
+                     "function": {"name": tc.function.name,
+                                  "arguments": tc.function.arguments}}
+                    for tc in msg.tool_calls
+                ],
+            })
+            for tc in msg.tool_calls:
+                args = json.loads(tc.function.arguments)
+                result = tool_map[tc.function.name].execute(**args)
+                messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})
+        else:
+            messages.append({"role": "assistant", "content": msg.content or ""})
+            break
+    return messages
+```
+
+## Reference
+
+- Blueprint implementation: `/Users/szeider/work/myreact` (the original pattern)
+- Production implementation: `coder/src/agentic_python_coder/agent.py` (v3.0.0)
+- Migration context: LangGraph v2.x → frameworkless in one session, all 70 tests passing

agentic_python_coder-3.2.0/MEM/MEM_002_tool_description_quality.md

@@ -0,0 +1,107 @@
+---
+keywords: [tool-descriptions, openai, tool-calling, performance, langgraph, schema, regression]
+context: When writing or modifying OpenAI tool definitions for agents that use tool calling
+added: 2026-01-31
+---
+# Tool Description Quality Impacts Agent Performance
+
+## Insight
+
+Verbose, LangGraph-style tool descriptions significantly outperform minimal descriptions on challenging tasks. When migrating from LangGraph to frameworkless tool definitions, preserving the full docstring content is critical.
+
+### What works (LangGraph-style verbose descriptions)
+
+1. **Multiple examples** showing multi-step usage patterns — not just what the tool does, but how to chain calls (e.g., define a function in one call, use it in the next)
+2. **Explicit Args section** describing each parameter in natural language
+3. **Explicit Returns section** listing every possible field in the response JSON (`success`, `stdout`, `result`, `stderr`, `error`)
+4. **Behavioral hints** embedded in the description (e.g., "The kernel maintains state between executions!", "use print() to see output")
+
+### What fails (minimal descriptions)
+
+Stripping descriptions to just the core purpose (e.g., "Execute Python code in a persistent IPython kernel.") removes behavioral guidance the model relies on for:
+- Understanding that state persists across calls
+- Knowing what output format to expect
+- Planning multi-step tool use sequences
+
+### Parameter schema style also matters
+
+The LangGraph auto-generated schemas use `"title"` fields on properties and top-level schema, plus `"additionalProperties": True` for flexible object items. Switching to `"description"` fields and strict schemas (with explicit properties and enums) may change how models interpret and use the tools. When in doubt, match the schema style that was tested and proven to work.
+
+### Verification gates in tool descriptions
+
+Adding verification requirements to `save_code` tool description ("Only call this AFTER you have executed the code and confirmed it produces correct output") measurably improved benchmark scores. Opus 4.5 went from 4/5→5/5 on hard CPMpy and GPT-5.2 from 0/5→5/5 on hard Clingo after adding these gates. However, GPT-5.2 still sometimes ignores verification (only 2 tool calls before saving on 016_sports). The verification prompt works better on some models than others.
+
+### Circular verification pitfall
+
+Models that do write verify() functions sometimes verify against their own wrong model rather than the problem statement. The verify() re-implements the same bugs as the solver constraints. Prompt language should explicitly require deriving verification checks from the problem text, not from the model code.
+
+### Key takeaway
+
+Tool descriptions are not documentation for humans — they are **behavioral instructions for the model**. Treat them as part of the prompt engineering, not as code comments to be minimized.
+
+**Updated**: 2026-01-31
+
+## Example
+
+```python
+# BAD: Minimal description (causes performance regression)
+PYTHON_EXEC_TOOL = Tool(
+    name="python_exec",
+    description="Execute Python code in a persistent IPython kernel.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "code": {"type": "string", "description": "Python code to execute."},
+        },
+        "required": ["code"],
+    },
+    function=python_exec,
+)
+
+# GOOD: Verbose LangGraph-style description (proven performance)
+PYTHON_EXEC_TOOL = Tool(
+    name="python_exec",
+    description=(
+        "Execute Python code in a persistent IPython kernel.\n\n"
+        "IMPORTANT: The kernel maintains state between executions!\n"
+        "- Variables, functions, and imports persist across calls\n"
+        "- Use print() to see output, or the last expression will be returned\n"
+        "- The kernel runs in the working directory context\n\n"
+        "Example:\n"
+        "    First call:  x = 5\n"
+        '    Second call: print(x)  # Returns: {"success": true, "stdout": "5"}\n\n'
+        "    First call:  def add(a, b): return a + b\n"
+        '    Second call: add(3, 4)  # Returns: {"success": true, "result": "7"}\n\n'
+        "The code executes in the working directory context, so you can read/write files\n"
+        "using relative paths.\n\n"
+        "Args:\n"
+        "    code: Python code to execute. Multi-line code is supported.\n\n"
+        "Returns:\n"
+        "    JSON string with execution results:\n"
+        "    - success: boolean indicating if execution succeeded\n"
+        "    - stdout: captured print output (if any)\n"
+        "    - result: the last expression's value (if any)\n"
+        "    - stderr: warnings (if any)\n"
+        "    - error: error message (if execution failed)"
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "code": {
+                "type": "string",
+                "title": "Code",
+            },
+        },
+        "required": ["code"],
+        "title": "python_exec",
+    },
+    function=python_exec,
+)
+```
+
+## Reference
+
+- Regression discovered: 2026-01-31 during benchmark testing of dev branch
+- Fix verified in: `/Users/szeider/temp/codertest/agentic-python-coder-dev/`
+- Production file: `coder/src/agentic_python_coder/tools.py`
+- Related: E001_frameworkless_react_agent.md (migration context)

{agentic_python_coder-3.0.0 → agentic_python_coder-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-python-coder
-Version: 3.0.0
+Version: 3.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
@@ -14,13 +14,13 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Code Generators
 Requires-Python: <3.14,>=3.13
-Requires-Dist: ipykernel>=7.1.0
+Requires-Dist: ipykernel>=7.2.0
 Requires-Dist: jupyter-client>=8.8.0
 Requires-Dist: mcp>=1.26.0
-Requires-Dist: openai>=2.16.0
+Requires-Dist: openai>=2.21.0
 Requires-Dist: python-dotenv>=1.2.1
 Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: rich>=14.3.1
+Requires-Dist: rich>=14.3.2
 Provides-Extra: dev
 Requires-Dist: mypy>=1.19.1; extra == 'dev'
 Requires-Dist: ruff>=0.14.14; extra == 'dev'
@@ -152,8 +152,9 @@ 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 gemini3pro "task"  # Gemini 3 Pro Preview
-coder --model gpt52 "task"       # GPT-5.2
+coder --model gemini3pro "task"    # Gemini 3 Pro Preview
+coder --model gemini3flash "task"  # Gemini 3 Flash Preview (fast, low-cost)
+coder --model gpt52 "task"         # GPT-5.2
 
 # Custom model (JSON file)
 coder --model ./mymodel.json "task"
@@ -259,7 +260,7 @@ from agentic_python_coder import get_openrouter_llm, list_available_models
 
 llm = get_openrouter_llm(model="sonnet45")
 print(list_available_models())
-# ['deepseek31', 'gemini25', 'gemini3pro', 'gpt52', 'grok41', 'opus45', 'qwen3', 'sonnet45']
+# ['deepseek31', 'gemini25', 'gemini3flash', 'gemini3pro', 'gpt52', 'grok41', 'opus45', 'qwen3', 'sonnet45']
 ```
 
 ---

{agentic_python_coder-3.0.0 → agentic_python_coder-3.2.0}/README.md

@@ -119,8 +119,9 @@ 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 gemini3pro "task"  # Gemini 3 Pro Preview
-coder --model gpt52 "task"       # GPT-5.2
+coder --model gemini3pro "task"    # Gemini 3 Pro Preview
+coder --model gemini3flash "task"  # Gemini 3 Flash Preview (fast, low-cost)
+coder --model gpt52 "task"         # GPT-5.2
 
 # Custom model (JSON file)
 coder --model ./mymodel.json "task"
@@ -226,7 +227,7 @@ from agentic_python_coder import get_openrouter_llm, list_available_models
 
 llm = get_openrouter_llm(model="sonnet45")
 print(list_available_models())
-# ['deepseek31', 'gemini25', 'gemini3pro', 'gpt52', 'grok41', 'opus45', 'qwen3', 'sonnet45']
+# ['deepseek31', 'gemini25', 'gemini3flash', 'gemini3pro', 'gpt52', 'grok41', 'opus45', 'qwen3', 'sonnet45']
 ```
 
 ---

{agentic_python_coder-3.0.0 → agentic_python_coder-3.2.0}/coder/src/agentic_python_coder/llm.py

@@ -43,7 +43,7 @@ def get_api_key() -> str:
     api_key = os.getenv("OPENROUTER_API_KEY")
 
     if not api_key:
-        print("Warning: No API key found. Set up with:", file=sys.stderr)
+        print("Error: No API key found. Set up with:", file=sys.stderr)
         print("  mkdir -p ~/.config/coder", file=sys.stderr)
         print(
             "  echo 'OPENROUTER_API_KEY=sk-or-...' > ~/.config/coder/.env",
@@ -62,6 +62,8 @@ def _load_json_file(path: Path, model: str) -> dict[str, Any]:
             config = json.load(f)
     except json.JSONDecodeError as e:
         raise ValueError(f"Invalid JSON in model config '{model}': {e}") from e
+    except OSError as e:
+        raise FileNotFoundError(f"Cannot read model config '{model}': {e}") from e
 
     if "path" not in config:
         raise ValueError(f"Model config '{model}' missing required key: 'path'")
@@ -95,7 +97,7 @@ def load_model_config(model: str) -> dict[str, Any]:
         return _load_json_file(path, model)
 
     # Local override: ./{model}.json
-    local_path = Path(f"./{model}.json")
+    local_path = Path(f"{model}.json")
     if local_path.exists():
         return _load_json_file(local_path, model)
 
@@ -107,9 +109,8 @@ def load_model_config(model: str) -> dict[str, Any]:
 
     # List available models for error message
     available = list_available_models()
-    raise FileNotFoundError(
-        f"Model '{model}' not found. Available: {', '.join(available)}"
-    )
+    suffix = f" Available: {', '.join(available)}" if available else ""
+    raise FileNotFoundError(f"Model '{model}' not found.{suffix}")
 
 
 def list_available_models() -> list[str]:
@@ -146,10 +147,10 @@ def get_openrouter_llm(
     """
     # Load config from JSON
     config = load_model_config(model)
-    model_path = config["path"]
+    model_id = config["path"]
 
     if verbose:
-        print(f"Using model: {model_path}")
+        print(f"Using model: {model_id}")
         if os.getenv("CODER_VERBOSE"):
             for key, value in config.items():
                 if key != "path":
@@ -194,7 +195,14 @@ def get_openrouter_llm(
             if key in config:
                 api_params[key] = config[key]
         if "top_k" in config:
-            # OpenRouter supports top_k via extra_body
-            api_params["extra_body"] = {"top_k": config["top_k"]}
+            api_params.setdefault("extra_body", {})["top_k"] = config["top_k"]
 
-    return LLMConfig(client=client, model=model_path, api_params=api_params)
+    # Provider routing works for all models (including no_sampling_params)
+    if "provider" in config:
+        api_params.setdefault("extra_body", {})["provider"] = config["provider"]
+
+    # Reasoning/thinking tokens (e.g. Gemini 3 Flash thinking levels)
+    if "reasoning" in config:
+        api_params.setdefault("extra_body", {})["reasoning"] = config["reasoning"]
+
+    return LLMConfig(client=client, model=model_id, api_params=api_params)

agentic_python_coder-3.2.0/coder/src/agentic_python_coder/models/gemini31.json

@@ -0,0 +1,7 @@
+{
+  "path": "google/gemini-3.1-pro-preview",
+  "temperature": 0.0,
+  "max_tokens": 16384,
+  "streaming": true,
+  "request_timeout": 120
+}

agentic_python_coder-3.2.0/coder/src/agentic_python_coder/models/gemini3flash.json

@@ -0,0 +1,5 @@
+{
+  "path": "google/gemini-3-flash-preview",
+  "temperature": 0.3,
+  "max_tokens": 16384
+}

agentic_python_coder-3.2.0/coder/src/agentic_python_coder/models/sonnet46.json

@@ -0,0 +1,6 @@
+{
+  "path": "anthropic/claude-sonnet-4.6",
+  "temperature": 0.0,
+  "max_tokens": 16384,
+  "streaming": true
+}

{agentic_python_coder-3.0.0 → agentic_python_coder-3.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentic-python-coder"
-version = "3.0.0"
+version = "3.2.0"
 description = "A lightweight Python coding agent that writes, executes, and iterates on code through natural language instructions"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -19,11 +19,11 @@ classifiers = [
 ]
 keywords = ["ai", "coding", "agent", "llm", "code-generation", "automation"]
 dependencies = [
-    "openai>=2.16.0",
+    "openai>=2.21.0",
     "python-dotenv>=1.2.1",
-    "rich>=14.3.1",
+    "rich>=14.3.2",
     "jupyter-client>=8.8.0",
-    "ipykernel>=7.1.0",
+    "ipykernel>=7.2.0",
     "PyYAML>=6.0.3",
     "mcp>=1.26.0",
 ]