agentic-python-coder 3.3.0__tar.gz → 3.4.1__tar.gz

{agentic_python_coder-3.3.0 → agentic_python_coder-3.4.1}/.gitignore

@@ -154,7 +154,6 @@ uv.lock
 # Project specific
 tests/
 coder-examples/
-CLAUDE-archive.md
 EXPERTISE/
 PROCESS_NOTES.md
 conversation_log.json
@@ -162,8 +161,6 @@ coder_output.log
 task.md
 solution.py
 *.tmp
-CLAUDE.md
-**/CLAUDE.md
 TRASH/
 LOCAL/
 ASP/
@@ -172,7 +169,6 @@ CPMPY/
 PAPER/
 PAPER-ASP/
 ZEBRA/
-.mcp.json
 
 # Test files and folders (root level only)
 /test-*/

{agentic_python_coder-3.3.0 → agentic_python_coder-3.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-python-coder
-Version: 3.3.0
+Version: 3.4.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

{agentic_python_coder-3.3.0 → agentic_python_coder-3.4.1}/coder/src/agentic_python_coder/kernel.py

@@ -10,6 +10,7 @@ import logging
 import os
 import re
 import shutil
+import signal
 import threading
 import time
 import uuid
@@ -219,13 +220,13 @@ except ImportError:
         self._execute_raw(startup_code)
 
     def _cleanup_on_error(self):
-        """Clean up resources if initialization fails."""
+        """Clean up resources if initialization fails.
+
+        Routes through shutdown() so a partially-started kernel tree gets
+        the same defensive process-group kill as a healthy one.
+        """
         try:
-            if hasattr(self, "kc") and self.kc:
-                self.kc.stop_channels()
-            if hasattr(self, "km") and self.km:
-                if self.km.is_alive():
-                    self.km.shutdown_kernel(now=True)
+            self.shutdown()
         except Exception:
             pass  # Best effort cleanup
 
@@ -311,7 +312,21 @@ except ImportError:
             return self._execute_raw(code, deadline_timeout)
 
     def shutdown(self):
-        """Shutdown the kernel and clean up."""
+        """Shutdown the kernel and clean up.
+
+        Kernels run in their own process group (jupyter_client launches with
+        start_new_session=True). After the regular shutdown, defensively kill
+        the whole group: uv-wrapped kernels are a tree (uv parent + python
+        child) and a surviving member would be orphaned.
+        """
+        # Capture the kernel's process group before shutdown clears it
+        pgid = None
+        try:
+            if hasattr(self, "km") and self.km:
+                pgid = getattr(getattr(self.km, "provisioner", None), "pgid", None)
+        except Exception:
+            pass
+
         try:
             if hasattr(self, "kc") and self.kc:
                 try:
@@ -330,6 +345,15 @@ except ImportError:
             # Ignore errors during shutdown
             pass
 
+        # Defensive: ensure no process-tree member survived. Never signal our
+        # own group (pgid could be bogus if start_new_session did not apply).
+        if pgid and pgid > 0:
+            try:
+                if pgid != os.getpgid(0):
+                    os.killpg(pgid, signal.SIGKILL)
+            except (ProcessLookupError, PermissionError, OSError):
+                pass
+
 
 # =============================================================================
 # Core Registry Functions
@@ -603,6 +627,33 @@ def shutdown_all_kernels():
             pass  # Best effort
 
 
+def kill_all_kernel_process_groups():
+    """Hard-kill (SIGKILL) every registered kernel's process group.
+
+    Deliberately lock-free: this is the termination path, where a busy
+    kernel's _exec_lock may be held indefinitely by an in-flight execution
+    and the graceful shutdown_all_kernels() would block behind it. Snapshot
+    the registry and signal each group directly. Never signals our own
+    process group. Kernels mid-creation (registry slot still None) cannot
+    be reached here — that sub-second window is a known limitation.
+    """
+    try:
+        own_pgid = os.getpgid(0)
+    except OSError:
+        own_pgid = None
+
+    for state in list(_kernels.values()):
+        if state is None:
+            continue
+        try:
+            km = state.kernel.km
+            pgid = getattr(getattr(km, "provisioner", None), "pgid", None)
+            if pgid and pgid > 0 and pgid != own_pgid:
+                os.killpg(pgid, signal.SIGKILL)
+        except (ProcessLookupError, PermissionError, OSError, AttributeError):
+            pass  # Best effort
+
+
 # =============================================================================
 # Backward Compatibility API
 # =============================================================================

{agentic_python_coder-3.3.0 → agentic_python_coder-3.4.1}/coder/src/agentic_python_coder/mcp_server.py

@@ -7,6 +7,9 @@ import ast
 import asyncio
 import json
 import logging
+import os
+import signal
+import threading
 
 from mcp.server import Server
 from mcp.server.stdio import stdio_server
@@ -18,8 +21,10 @@ from agentic_python_coder.kernel import (
     execute_in_kernel,
     interrupt_kernel_by_id,
     kernel_exists,
+    kill_all_kernel_process_groups,
     list_kernels,
     restart_kernel,
+    shutdown_all_kernels,
 )
 
 # Configure logging
@@ -32,6 +37,7 @@ server = Server("ipython_mcp")
 MAX_OUTPUT = 100 * 1024  # 100KB truncation limit
 MAX_TIMEOUT = 300  # Maximum allowed timeout in seconds
 DEFAULT_TIMEOUT = 30  # Default timeout in seconds
+STATUS_PROBE_TIMEOUT = 10  # Timeout for python_status introspection probes
 KERNEL_TIMEOUT_BUFFER = 5  # Extra seconds for kernel deadline vs asyncio timeout
 
 # Async lock for session operations (default kernel management)
@@ -240,6 +246,30 @@ No side effects - safe to call anytime.""",
                 },
             },
         ),
+        Tool(
+            name="submit_code",
+            description="""Submit your final, verified, self-contained Python program.
+
+Call this ONCE at the end of a solve, only after you have executed the program
+via python_exec and your verification passed. The submission must be a
+standalone program: all imports included, no reliance on session state.
+
+The code is syntax-checked with compile():
+- {"ok": true} if it parses
+- {"ok": false, "error": "<detail>"} on a syntax error — fix and resubmit
+
+The code is NOT executed and NOT written to disk; the client persists it.""",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "code": {
+                        "type": "string",
+                        "description": "Complete standalone Python program (final answer).",
+                    },
+                },
+                "required": ["code"],
+            },
+        ),
         Tool(
             name="python_interrupt",
             description="""Interrupt running code in the session.
@@ -318,7 +348,9 @@ versions
                     % packages
                 )
                 try:
-                    result = await execute_with_timeout(version_code, 30, kernel_id)
+                    result = await execute_with_timeout(
+                        version_code, DEFAULT_TIMEOUT, kernel_id
+                    )
                     if result.get("result"):
                         versions = ast.literal_eval(result["result"])
                         if isinstance(versions, dict):
@@ -391,6 +423,24 @@ versions
         result = await execute_with_timeout(code, timeout, kernel_id)
         return [TextContent(type="text", text=json.dumps(result))]
 
+    elif name == "submit_code":
+        code = arguments.get("code", "")
+        if not code.strip():
+            payload = {"ok": False, "error": "Empty submission"}
+        else:
+            try:
+                compile(code, "<submission>", "exec")
+                payload = {"ok": True}
+            except SyntaxError as e:
+                payload = {
+                    "ok": False,
+                    "error": f"Syntax error at line {e.lineno or '?'}: {e.msg}",
+                }
+            except ValueError as e:
+                # compile() raises ValueError e.g. for null bytes in source
+                payload = {"ok": False, "error": f"Invalid source: {e}"}
+        return [TextContent(type="text", text=json.dumps(payload))]
+
     elif name == "python_status":
         kernel_id = get_kernel_id(arguments)
         is_active = kernel_exists(kernel_id)
@@ -412,7 +462,7 @@ versions
             # Get Python version
             try:
                 result = await execute_with_timeout(
-                    "import sys; sys.version", 10, kernel_id
+                    "import sys; sys.version", STATUS_PROBE_TIMEOUT, kernel_id
                 )
                 if result.get("result"):
                     status["python_version"] = result["result"].strip("'\"")
@@ -426,7 +476,9 @@ import importlib.metadata
 [f"{d.metadata['Name']} {d.version}" for d in importlib.metadata.distributions()
  if d.metadata['Name'] not in ('pip', 'setuptools', 'wheel', 'ipykernel', 'jupyter-client')][:20]
 """
-                result = await execute_with_timeout(pkg_code, 10, kernel_id)
+                result = await execute_with_timeout(
+                    pkg_code, STATUS_PROBE_TIMEOUT, kernel_id
+                )
                 if result.get("result"):
                     status["packages"] = ast.literal_eval(result["result"])
             except Exception:
@@ -438,7 +490,9 @@ import importlib.metadata
 [name for name in dir() if not name.startswith('_')
  and name not in ('In', 'Out', 'get_ipython', 'exit', 'quit', 'open')]
 """
-                result = await execute_with_timeout(var_code, 10, kernel_id)
+                result = await execute_with_timeout(
+                    var_code, STATUS_PROBE_TIMEOUT, kernel_id
+                )
                 if result.get("result"):
                     status["variables"] = ast.literal_eval(result["result"])
             except Exception:
@@ -521,9 +575,51 @@ async def run_server():
         await server.run(read, write, server.create_initialization_options())
 
 
+# Hard-exit fallback if kernel cleanup hangs after a termination signal
+_TERMINATION_CLEANUP_TIMEOUT = 10.0
+
+# Set on the first termination signal; later signals are ignored instead of
+# stacking additional timers and cleanup threads
+_terminating = threading.Event()
+
+
+def _handle_termination(signum, frame):
+    """Shut down all kernels on SIGTERM/SIGINT, then exit.
+
+    Kernel process groups are hard-killed first (lock-free, cannot block on
+    a busy kernel's exec lock); the graceful registry cleanup then runs in a
+    thread, with a timer that hard-exits if it hangs.
+    """
+    if _terminating.is_set():
+        return
+    _terminating.set()
+
+    def _cleanup_and_exit():
+        try:
+            kill_all_kernel_process_groups()
+            shutdown_all_kernels()
+        finally:
+            os._exit(128 + signum)
+
+    threading.Timer(
+        _TERMINATION_CLEANUP_TIMEOUT, lambda: os._exit(128 + signum)
+    ).start()
+    threading.Thread(target=_cleanup_and_exit, daemon=True).start()
+
+
 def main():
     """Entry point for coder-mcp command."""
-    asyncio.run(run_server())
+    signal.signal(signal.SIGTERM, _handle_termination)
+    signal.signal(signal.SIGINT, _handle_termination)
+    try:
+        asyncio.run(run_server())
+    finally:
+        # stdin EOF / transport close / normal exit: the client is gone, so
+        # hard-kill kernel groups first (immune to a busy kernel's exec
+        # lock), then clean up the registry (atexit also runs the graceful
+        # path, but only on clean interpreter shutdown)
+        kill_all_kernel_process_groups()
+        shutdown_all_kernels()
 
 
 if __name__ == "__main__":

{agentic_python_coder-3.3.0 → agentic_python_coder-3.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentic-python-coder"
-version = "3.3.0"
+version = "3.4.1"
 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"
@@ -60,6 +60,10 @@ exclude = [
     "*.jsonl",
     "*_code.py",
     "RELEASE_NOTES_*.md",
+    "CLAUDE.md",
+    "CLAUDE-archive.md",
+    "MEM/",
+    ".claude/",
 ]
 
 [tool.hatch.build.targets.wheel]

agentic_python_coder-3.3.0/MEM/MEM_000.md

@@ -1,131 +0,0 @@
----
-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-23
-
-**Goal**: Add new model configs (sonnet46, gemini31) and publish v3.2.0
-
-**Done**:
-- Created sonnet46.json (anthropic/claude-sonnet-4.6, temp 0.0)
-- Created gemini31.json (google/gemini-3.1-pro-preview, temp 0.0, timeout 120)
-- Added reasoning/thinking token support in llm.py
-- Bumped version to 3.2.0, all 70 unit tests pass
-- Published to PyPI
-
-**Tried**:
-- Initially copied gemini3pro params (temp 0.3, top_p 0.9) for gemini31 — Stefan corrected to temp 0.0, no top_p
-
-**Notes**: Quick session. Stefan provided the gemini model path directly (google/gemini-3.1-pro-preview).
-
----
-## 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 GPPT 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.3.0/MEM/MEM_001_frameworkless_react_agent.md

@@ -1,110 +0,0 @@
----
-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.3.0/MEM/MEM_002_tool_description_quality.md

@@ -1,107 +0,0 @@
----
-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)