pdd-cli 0.0.42__py3-none-any.whl → 0.0.90__py3-none-any.whl

pdd/preprocess.py

@@ -1,7 +1,8 @@
 import os
 import re
+import base64
 import subprocess
-from typing import List, Optional
+from typing import List, Optional, Tuple
 import traceback
 from rich.console import Console
 from rich.panel import Panel
@@ -11,22 +12,110 @@ from rich.traceback import install
 install()
 console = Console()
 
+# Debug/Instrumentation controls
+_DEBUG_PREPROCESS = str(os.getenv("PDD_PREPROCESS_DEBUG", "")).lower() in ("1", "true", "yes", "on")
+_DEBUG_OUTPUT_FILE = os.getenv("PDD_PREPROCESS_DEBUG_FILE")  # Optional path to write a debug report
+_DEBUG_EVENTS: List[str] = []
+
+def _dbg(msg: str) -> None:
+    if _DEBUG_PREPROCESS:
+        console.print(f"[dim][PPD][preprocess][/dim] {escape(msg)}")
+        _DEBUG_EVENTS.append(msg)
+
+def _write_debug_report() -> None:
+    if _DEBUG_PREPROCESS and _DEBUG_OUTPUT_FILE:
+        try:
+            with open(_DEBUG_OUTPUT_FILE, "w", encoding="utf-8") as fh:
+                fh.write("Preprocess Debug Report\n\n")
+                for line in _DEBUG_EVENTS:
+                    fh.write(line + "\n")
+            console.print(f"[green]Debug report written to:[/green] {_DEBUG_OUTPUT_FILE}")
+        except Exception as e:
+            # Report the error so users know why the log file wasn't written
+            console.print(f"[yellow]Warning: Could not write debug report to {_DEBUG_OUTPUT_FILE}: {e}[/yellow]")
+    elif _DEBUG_PREPROCESS and not _DEBUG_OUTPUT_FILE:
+        console.print("[dim]Debug mode enabled but PDD_PREPROCESS_DEBUG_FILE not set (output shown in console only)[/dim]")
+
+def _extract_fence_spans(text: str) -> List[Tuple[int, int]]:
+    """Return list of (start, end) spans for fenced code blocks ```...```.
+
+    The spans are [start, end) indices in the original text.
+    """
+    spans: List[Tuple[int, int]] = []
+    try:
+        for m in re.finditer(r"```[\w\s]*\n[\s\S]*?```", text):
+            spans.append((m.start(), m.end()))
+    except Exception:
+        pass
+    return spans
+
+def _is_inside_any_span(idx: int, spans: List[Tuple[int, int]]) -> bool:
+    for s, e in spans:
+        if s <= idx < e:
+            return True
+    return False
+
+def _scan_risky_placeholders(text: str) -> Tuple[List[Tuple[int, str]], List[Tuple[int, str]]]:
+    """Scan for risky placeholders outside code fences.
+
+    Returns two lists of (line_no, snippet):
+      - single_brace: matches like {name} not doubled and not part of {{...}}
+      - template_brace: `${...}` occurrences (which include single { ... })
+    """
+    single_brace: List[Tuple[int, str]] = []
+    template_brace: List[Tuple[int, str]] = []
+    try:
+        fence_spans = _extract_fence_spans(text)
+        # Single-brace variable placeholders (avoid matching {{ or }})
+        for m in re.finditer(r"(?<!\{)\{([A-Za-z_][A-Za-z0-9_]*)\}(?!\})", text):
+            if not _is_inside_any_span(m.start(), fence_spans):
+                line_no = text.count("\n", 0, m.start()) + 1
+                single_brace.append((line_no, m.group(0)))
+        # JavaScript template placeholders like ${...}
+        for m in re.finditer(r"\$\{[^\}]+\}", text):
+            if not _is_inside_any_span(m.start(), fence_spans):
+                line_no = text.count("\n", 0, m.start()) + 1
+                template_brace.append((line_no, m.group(0)))
+    except Exception:
+        pass
+    return single_brace, template_brace
+
 def preprocess(prompt: str, recursive: bool = False, double_curly_brackets: bool = True, exclude_keys: Optional[List[str]] = None) -> str:
     try:
         if not prompt:
             console.print("[bold red]Error:[/bold red] Empty prompt provided")
             return ""
+        _DEBUG_EVENTS.clear()
+        _dbg(f"Start preprocess(recursive={recursive}, double_curly={double_curly_brackets}, exclude_keys={exclude_keys})")
+        _dbg(f"Initial length: {len(prompt)} characters")
         console.print(Panel("Starting prompt preprocessing", style="bold blue"))
         prompt = process_backtick_includes(prompt, recursive)
+        _dbg("After backtick includes processed")
         prompt = process_xml_tags(prompt, recursive)
+        _dbg("After XML-like tags processed")
         if double_curly_brackets:
             prompt = double_curly(prompt, exclude_keys)
+            _dbg("After double_curly execution")
+        # Scan for risky placeholders remaining outside code fences
+        singles, templates = _scan_risky_placeholders(prompt)
+        if singles:
+            _dbg(f"WARNING: Found {len(singles)} single-brace placeholders outside code fences (examples):")
+            for ln, frag in singles[:5]:
+                _dbg(f"  line {ln}: {frag}")
+        if templates:
+            _dbg(f"INFO: Found {len(templates)} template literals ${'{...'} outside code fences (examples):")
+            for ln, frag in templates[:5]:
+                _dbg(f"  line {ln}: {frag}")
         # Don't trim whitespace that might be significant for the tests
         console.print(Panel("Preprocessing complete", style="bold green"))
+        _dbg(f"Final length: {len(prompt)} characters")
+        _write_debug_report()
         return prompt
     except Exception as e:
         console.print(f"[bold red]Error during preprocessing:[/bold red] {str(e)}")
         console.print(Panel(traceback.format_exc(), title="Error Details", style="red"))
+        _dbg(f"Exception: {str(e)}")
+        _write_debug_report()
         return prompt
 
 def get_file_path(file_name: str) -> str:
@@ -45,12 +134,17 @@ def process_backtick_includes(text: str, recursive: bool) -> str:
                 content = file.read()
                 if recursive:
                     content = preprocess(content, recursive=True, double_curly_brackets=False)
+                _dbg(f"Included via backticks: {file_path} (len={len(content)})")
                 return f"```{content}```"
         except FileNotFoundError:
             console.print(f"[bold red]Warning:[/bold red] File not found: {file_path}")
-            return match.group(0)
+            _dbg(f"Missing backtick include: {file_path}")
+            # First pass (recursive=True): leave the tag so a later env expansion can resolve it
+            # Second pass (recursive=False): replace with a visible placeholder
+            return match.group(0) if recursive else f"```[File not found: {file_path}]```"
         except Exception as e:
             console.print(f"[bold red]Error processing include:[/bold red] {str(e)}")
+            _dbg(f"Error processing backtick include {file_path}: {e}")
             return f"```[Error processing include: {file_path}]```"
     prev_text = ""
     current_text = text
@@ -62,9 +156,9 @@ def process_backtick_includes(text: str, recursive: bool) -> str:
 def process_xml_tags(text: str, recursive: bool) -> str:
     text = process_pdd_tags(text)
     text = process_include_tags(text, recursive)
-
-    text = process_shell_tags(text)
-    text = process_web_tags(text)
+    text = process_include_many_tags(text, recursive)
+    text = process_shell_tags(text, recursive)
+    text = process_web_tags(text, recursive)
     return text
 
 def process_include_tags(text: str, recursive: bool) -> str:
@@ -73,17 +167,63 @@ def process_include_tags(text: str, recursive: bool) -> str:
         file_path = match.group(1).strip()
         try:
             full_path = get_file_path(file_path)
-            console.print(f"Processing XML include: [cyan]{full_path}[/cyan]")
-            with open(full_path, 'r', encoding='utf-8') as file:
-                content = file.read()
-                if recursive:
-                    content = preprocess(content, recursive=True, double_curly_brackets=False)
-                return content
+            ext = os.path.splitext(file_path)[1].lower()
+            image_extensions = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.heic']
+            
+            if ext in image_extensions:
+                console.print(f"Processing image include: [cyan]{full_path}[/cyan]")
+                from PIL import Image
+                import io
+                import pillow_heif
+                
+                pillow_heif.register_heif_opener()
+
+                MAX_DIMENSION = 1024
+                with open(full_path, 'rb') as file:
+                    img = Image.open(file)
+                    img.load() # Force loading the image data before the file closes
+                    
+                    if img.width > MAX_DIMENSION or img.height > MAX_DIMENSION:
+                        img.thumbnail((MAX_DIMENSION, MAX_DIMENSION))
+                        console.print(f"Image resized to {img.size}")
+
+                # Handle GIFs: convert to a static PNG of the first frame
+                if ext == '.gif':
+                    img.seek(0)
+                    img = img.convert("RGB")
+                    img_format = 'PNG'
+                    mime_type = 'image/png'
+                elif ext == '.heic':
+                    img_format = 'JPEG'
+                    mime_type = 'image/jpeg'
+                else:
+                    img_format = 'JPEG' if ext in ['.jpg', '.jpeg'] else 'PNG'
+                    mime_type = f'image/{img_format.lower()}'
+
+                # Save the (potentially resized and converted) image to an in-memory buffer
+                buffer = io.BytesIO()
+                img.save(buffer, format=img_format)
+                content = buffer.getvalue()
+
+                encoded_string = base64.b64encode(content).decode('utf-8')
+                return f"data:{mime_type};base64,{encoded_string}"
+            else:
+                console.print(f"Processing XML include: [cyan]{full_path}[/cyan]")
+                with open(full_path, 'r', encoding='utf-8') as file:
+                    content = file.read()
+                    if recursive:
+                        content = preprocess(content, recursive=True, double_curly_brackets=False)
+                    _dbg(f"Included via XML tag: {file_path} (len={len(content)})")
+                    return content
         except FileNotFoundError:
             console.print(f"[bold red]Warning:[/bold red] File not found: {file_path}")
-            return f"[File not found: {file_path}]"
+            _dbg(f"Missing XML include: {file_path}")
+            # First pass (recursive=True): leave the tag so a later env expansion can resolve it
+            # Second pass (recursive=False): replace with a visible placeholder
+            return match.group(0) if recursive else f"[File not found: {file_path}]"
         except Exception as e:
             console.print(f"[bold red]Error processing include:[/bold red] {str(e)}")
+            _dbg(f"Error processing XML include {file_path}: {e}")
             return f"[Error processing include: {file_path}]"
     prev_text = ""
     current_text = text
@@ -101,54 +241,101 @@ def process_pdd_tags(text: str) -> str:
         return "This is a test "
     return processed
 
-def process_shell_tags(text: str) -> str:
+def process_shell_tags(text: str, recursive: bool) -> str:
     pattern = r'<shell>(.*?)</shell>'
     def replace_shell(match):
         command = match.group(1).strip()
+        if recursive:
+            # Defer execution until after env var expansion
+            return match.group(0)
         console.print(f"Executing shell command: [cyan]{escape(command)}[/cyan]")
+        _dbg(f"Shell tag command: {command}")
         try:
             result = subprocess.run(command, shell=True, check=True, capture_output=True, text=True)
             return result.stdout
         except subprocess.CalledProcessError as e:
             error_msg = f"Command '{command}' returned non-zero exit status {e.returncode}."
             console.print(f"[bold red]Error:[/bold red] {error_msg}")
+            _dbg(f"Shell command error: {error_msg}")
             return f"Error: {error_msg}"
         except Exception as e:
             console.print(f"[bold red]Error executing shell command:[/bold red] {str(e)}")
+            _dbg(f"Shell execution exception: {e}")
             return f"[Shell execution error: {str(e)}]"
     return re.sub(pattern, replace_shell, text, flags=re.DOTALL)
 
-def process_web_tags(text: str) -> str:
+def process_web_tags(text: str, recursive: bool) -> str:
     pattern = r'<web>(.*?)</web>'
     def replace_web(match):
         url = match.group(1).strip()
+        if recursive:
+            # Defer network operations until after env var expansion
+            return match.group(0)
         console.print(f"Scraping web content from: [cyan]{url}[/cyan]")
+        _dbg(f"Web tag URL: {url}")
         try:
             try:
                 from firecrawl import FirecrawlApp
             except ImportError:
+                _dbg("firecrawl import failed; package not installed")
                 return f"[Error: firecrawl-py package not installed. Cannot scrape {url}]"
             api_key = os.environ.get('FIRECRAWL_API_KEY')
             if not api_key:
                 console.print("[bold yellow]Warning:[/bold yellow] FIRECRAWL_API_KEY not found in environment")
+                _dbg("FIRECRAWL_API_KEY not set")
                 return f"[Error: FIRECRAWL_API_KEY not set. Cannot scrape {url}]"
             app = FirecrawlApp(api_key=api_key)
             response = app.scrape_url(url, formats=['markdown'])
             if hasattr(response, 'markdown'):
+                _dbg(f"Web scrape returned markdown (len={len(response.markdown)})")
                 return response.markdown
             else:
                 console.print(f"[bold yellow]Warning:[/bold yellow] No markdown content returned for {url}")
+                _dbg("Web scrape returned no markdown content")
                 return f"[No content available for {url}]"
         except Exception as e:
             console.print(f"[bold red]Error scraping web content:[/bold red] {str(e)}")
+            _dbg(f"Web scraping exception: {e}")
             return f"[Web scraping error: {str(e)}]"
     return re.sub(pattern, replace_web, text, flags=re.DOTALL)
 
+def process_include_many_tags(text: str, recursive: bool) -> str:
+    """Process <include-many> blocks whose inner content is a comma- or newline-separated
+    list of file paths (typically provided via variables after env expansion)."""
+    pattern = r'<include-many>(.*?)</include-many>'
+    def replace_many(match):
+        inner = match.group(1)
+        if recursive:
+            # Wait for env expansion to materialize the list
+            return match.group(0)
+        # Split by newlines or commas
+        raw_items = [s.strip() for part in inner.split('\n') for s in part.split(',')]
+        paths = [p for p in raw_items if p]
+        contents: list[str] = []
+        for p in paths:
+            try:
+                full_path = get_file_path(p)
+                console.print(f"Including (many): [cyan]{full_path}[/cyan]")
+                with open(full_path, 'r', encoding='utf-8') as fh:
+                    contents.append(fh.read())
+                _dbg(f"Included (many): {p}")
+            except FileNotFoundError:
+                console.print(f"[bold red]Warning:[/bold red] File not found: {p}")
+                _dbg(f"Missing include-many: {p}")
+                contents.append(f"[File not found: {p}]")
+            except Exception as e:
+                console.print(f"[bold red]Error processing include-many:[/bold red] {str(e)}")
+                _dbg(f"Error processing include-many {p}: {e}")
+                contents.append(f"[Error processing include: {p}]")
+        return "\n".join(contents)
+    return re.sub(pattern, replace_many, text, flags=re.DOTALL)
+
 def double_curly(text: str, exclude_keys: Optional[List[str]] = None) -> str:
     if exclude_keys is None:
         exclude_keys = []
     
     console.print("Doubling curly brackets...")
+    _dbg("double_curly invoked")
     
     # Special case handling for specific test patterns
     if "Mix of {excluded{inner}} nesting" in text and "excluded" in exclude_keys:
@@ -172,6 +359,14 @@ def double_curly(text: str, exclude_keys: Optional[List[str]] = None) -> str:
             "2": {{"id": "2", "name": "Resource Two"}}
         }}"""
     
+    # Protect ${IDENT} placeholders so we can safely double braces, then restore
+    # them as ${{IDENT}} to avoid PromptTemplate interpreting {IDENT}.
+    protected_vars: List[str] = []
+    def _protect_var(m):
+        protected_vars.append(m.group(0))
+        return f"__PDD_VAR_{len(protected_vars)-1}__"
+    text = re.sub(r"\$\{[A-Za-z_][A-Za-z0-9_]*\}", _protect_var, text)
+
     # First, protect any existing double curly braces
     text = re.sub(r'\{\{([^{}]*)\}\}', r'__ALREADY_DOUBLED__\1__END_ALREADY__', text)
     
@@ -188,6 +383,24 @@ def double_curly(text: str, exclude_keys: Optional[List[str]] = None) -> str:
     
     # Restore already doubled brackets
     text = re.sub(r'__ALREADY_DOUBLED__(.*?)__END_ALREADY__', r'{{\1}}', text)
+
+    # Restore protected ${IDENT} placeholders as ${{IDENT}} so single braces
+    # don't leak into PromptTemplate formatting. This is safe for JS template
+    # literals and prevents missing-key errors in later formatting steps.
+    def _restore_var(m):
+        idx = int(m.group(1))
+        if 0 <= idx < len(protected_vars):
+            original = protected_vars[idx]  # e.g., ${FOO}
+            try:
+                inner = re.match(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}", original)
+                if inner:
+                    # Build as concatenation to avoid f-string brace escaping confusion
+                    return "${{" + inner.group(1) + "}}"  # -> ${{FOO}}
+            except Exception:
+                pass
+            return original
+        return m.group(0)
+    text = re.sub(r"__PDD_VAR_(\d+)__", _restore_var, text)
     
     # Special handling for code blocks
     code_block_pattern = r'```([\w\s]*)\n([\s\S]*?)```'
@@ -213,4 +426,4 @@ def double_curly(text: str, exclude_keys: Optional[List[str]] = None) -> str:
     # Process code blocks
     text = re.sub(code_block_pattern, process_code_block, text, flags=re.DOTALL)
     
-    return text
+    return text

pdd/preprocess_main.py

@@ -4,10 +4,10 @@ from typing import Tuple, Optional
 import click
 from rich import print as rprint
 
+from .config_resolution import resolve_effective_config
 from .construct_paths import construct_paths
 from .preprocess import preprocess
 from .xml_tagger import xml_tagger
-from . import DEFAULT_TIME, DEFAULT_STRENGTH
 def preprocess_main(
     ctx: click.Context, prompt_file: str, output: Optional[str], xml: bool, recursive: bool, double: bool, exclude: list
 ) -> Tuple[str, float, str]:
@@ -33,6 +33,7 @@ def preprocess_main(
             quiet=ctx.obj.get("quiet", False),
             command="preprocess",
             command_options=command_options,
+            context_override=ctx.obj.get('context')
         )
 
         # Load prompt file
@@ -40,10 +41,12 @@ def preprocess_main(
 
         if xml:
             # Use xml_tagger to add XML delimiters
-            strength = ctx.obj.get("strength", DEFAULT_STRENGTH)
-            temperature = ctx.obj.get("temperature", 0.0)
+            # Use centralized config resolution with proper priority: CLI > pddrc > defaults
+            effective_config = resolve_effective_config(ctx, resolved_config)
+            strength = effective_config["strength"]
+            temperature = effective_config["temperature"]
+            time = effective_config["time"]
             verbose = ctx.obj.get("verbose", False)
-            time = ctx.obj.get("time", DEFAULT_TIME)
             xml_tagged, total_cost, model_name = xml_tagger(
                 prompt,
                 strength,
@@ -76,4 +79,4 @@ def preprocess_main(
     except Exception as e:
         if not ctx.obj.get("quiet", False):
             rprint(f"[bold red]Error during preprocessing:[/bold red] {e}")
-        sys.exit(1)
+        sys.exit(1)

pdd/prompts/agentic_crash_explore_LLM.prompt

@@ -0,0 +1,49 @@
+You are fixing a crash in a PDD (Prompt-Driven Development) project.
+You are running as FALLBACK after PDD's normal crash loop failed multiple times. This loop was only allowed to change the code and/or program file.
+The error(s) is likely outside of these files.
+
+## PDD Principle
+The PROMPT FILE is the source of truth. Code is a generated artifact.
+The PROGRAM FILE calls the code and crashed. Both files may need fixes.
+
+## Files (you have full read/write access)
+- Prompt file (THE SPEC): {prompt_path}
+- Code file: {code_path}
+- Program file: {program_path}
+- Project root: {project_root}
+
+## Previous Fix Attempts
+The following shows what PDD's normal crash loop already tried.
+DO NOT repeat these approaches - try something different.
+
+<previous_attempts>
+{previous_attempts}
+</previous_attempts>
+
+## Your Task
+1. Read the prompt file to understand the intended behavior
+2. Read the code and program files
+3. Analyze the crash traceback to identify the root cause
+4. Explore related files (imports, dependencies, conftest.py) if needed
+5. Determine what needs fixing:
+   - Code has a bug -> fix the code
+   - Program calls code incorrectly -> fix the program
+   - Both have issues -> fix both
+   - Issue requires changes to other files -> make those changes
+6. Make ALL necessary changes to stop the crash including other files if needed
+7. Run the program file to verify the fix
+8. Repeat steps 4-7 until the program output aligns with the prompt's intent
+9. Output a JSON string with the following fields:
+   - success: bool
+   - message: str
+   - cost: float
+   - model: str
+   - changed_files: list[str]
+
+## Critical Rules
+- The prompt file defines what's correct - code should conform to it
+- DO NOT repeat approaches from the fix history above
+- You MAY modify BOTH the code file AND the program file
+- IMPORTANT: Read actual source files before assuming what functions/classes exist
+  - Do NOT guess at imports or API names
+  - Explore the codebase to understand actual exports

pdd/prompts/agentic_fix_explore_LLM.prompt

@@ -0,0 +1,45 @@
+You are fixing a test failure in a PDD (Prompt-Driven Development) project.
+You are running as FALLBACK after PDD's normal fix loop failed multiple times. This loop was only allowed to change the code and/or test file.
+
+## PDD Principle
+The PROMPT FILE is the source of truth. Code and tests are generated artifacts.
+If tests expect behavior not defined in the prompt, the TESTS may be wrong.
+
+## Files (you have full read/write access)
+- Prompt file (THE SPEC): {prompt_path}
+- Code file: {code_path}
+- Test file: {test_path}
+- Example program file: {example_program_path}
+- Project root: {project_root}
+
+## Previous Fix Attempts
+The following shows what PDD's normal fix loop already tried.
+DO NOT repeat these approaches - try something different.
+
+{error_content}
+
+## Your Task
+1. Read the prompt file to understand the intended behavior
+2. Read the code and test files
+3. Run test file to get the error(s)
+4. Explore related files (helpers, fixtures, etc.) if needed
+5. Determine what needs fixing:
+   - Code doesn't match the prompt spec -> fix the code
+   - Tests don't match the prompt spec -> fix the tests
+   - Tests have implementation issues (mocking, isolation) -> fix test implementation
+   - Issue requires changes to other files -> make those changes
+5. Make ALL necessary changes to fix the tests
+6. Run the example program file to verify the fix didn't break the program
+7. Repeat steps 4-6 until the program output aligns with the prompt's intent
+8. Output a JSON string with the following fields:
+   - success: bool
+   - message: str
+   - cost: float
+   - model: str
+   - changed_files: list[str]
+
+## Critical Rules
+- The prompt file defines what's correct - code and tests should conform to it
+- DO NOT repeat approaches from the fix history above
+- You may modify existing files or create new ones
+- If the error involves mocking/test isolation, focus on the TEST implementation

pdd/prompts/agentic_fix_harvest_only_LLM.prompt

@@ -0,0 +1,48 @@
+% You are a strictly constrained code emitter. Your goal is to make {test_abs} run without errors. The bug could be in EITHER {code_abs} (the source code) OR {test_abs} (the test/example file). Analyze the error carefully to determine which file needs fixing. Read the prompt content which describes the intended functionality, then fix the appropriate file(s). Your ONLY task is to output fully corrected contents of one or more changed files, and optionally one shell command to run the tests. Wrap outputs between the provided BEGIN/END markers. No commentary or extra text.
+
+% IMPORTANT: Analyze the error traceback carefully:
+  - If the error is in how the test/example USES the code (wrong exception caught, wrong API usage), fix {test_abs}
+  - If the error is in the code's IMPLEMENTATION (wrong behavior, missing functionality), fix {code_abs}
+  - You may need to fix BOTH files in some cases
+
+% IMPORTANT: If you see ModuleNotFoundError or ImportError:
+  - For external packages: include "pip install <package> &&" before the test command in TESTCMD
+  - For local imports: fix the sys.path or import statement to correctly locate {code_abs}
+  - The code file is at: {code_abs} - ensure imports can find this path
+
+<inputs>
+    <paths>
+        <begin_marker>{begin}</begin_marker>
+        <end_marker>{end}</end_marker>
+        <code_file>{code_abs}</code_file>
+    </paths>
+
+    <context>
+        <prompt_content>
+            {prompt_content}
+        </prompt_content>
+        <relevant_error>
+            {error_content}
+        </relevant_error>
+    </context>
+</inputs>
+
+% Follow these instructions:
+
+  1) Output ALL files you changed that are needed to make tests pass (source files, tests, or small support files).
+     Use one block per file, with this exact wrapping:
+       <<<BEGIN_FILE:{code_abs}>>>
+       <FULL CORRECTED FILE CONTENT>
+       <<<END_FILE:{code_abs}>>>
+
+     If you also modify the test file:
+       <<<BEGIN_FILE:{test_abs}>>>
+       <FULL CORRECTED FILE CONTENT>
+       <<<END_FILE:{test_abs}>>>
+
+  2) If you cannot run tests, ALSO print a single block containing the exact shell command to run tests such that it returns 0 on success:
+       <<<BEGIN_TESTCMD>>>
+       python {test_abs}
+       <<<END_TESTCMD>>>
+
+  3) Print nothing else. No code fences, no comments, no prose.

pdd/prompts/agentic_fix_primary_LLM.prompt

@@ -0,0 +1,85 @@
+% YOU ARE A DEBUGGING AGENT with full file system access.
+
+% TASK: Fix the failing test at {test_abs}
+
+% APPROACH:
+1. Read the error traceback carefully to understand what's failing
+2. Explore the relevant files to understand the codebase structure
+3. Identify the root cause - is the bug in the code module or the test file or both?
+4. Use your file editing tools to make minimal, targeted fixes
+5. After fixing, output the test command to verify your changes
+
+% FILES YOU CAN READ AND EDIT:
+<code_module>
+    {code_abs}
+  </code_module>
+<test_file>
+    {test_abs}
+</test_file>
+
+
+% ORIGINAL SPECIFICATION:
+<proompt_content> 
+    {prompt_content}
+</proompt_content>
+
+
+% ERROR LOG:
+<error_content>
+  {error_content}
+</error_content>
+
+
+% DEBUGGING GUIDELINES:
+- Analyze the traceback to find WHERE the error occurs and WHY
+- The bug could be in EITHER file - don't assume it's always in the code
+- If the error is in how the test USES the code → fix the test
+- If the error is in the code's IMPLEMENTATION → fix the code
+- You may need to fix BOTH files in some cases
+
+% COMMON ERROR TYPES AND FIXES:
+- ImportError/ModuleNotFoundError for LOCAL modules: The import statement may be wrong.
+  FIX: Change the import to use the correct module name (look at what modules exist).
+  DO NOT create new modules to match a wrong import - fix the import instead!
+- ImportError/ModuleNotFoundError for EXTERNAL packages (pip packages like toml, requests, humanize, etc.):
+  PREFERRED: Install the missing package using TESTCMD:
+    <<<BEGIN_TESTCMD>>>
+    pip install <package_name> && python -m pytest "{test_abs}" -q
+    <<<END_TESTCMD>>>
+
+  DO NOT rewrite the code to remove or replace the dependency unless the specification
+  explicitly says the dependency is optional. If the code uses a library, INSTALL IT.
+
+  ONLY use try/except fallback if the specification says the feature is optional:
+    ```python
+    try:
+        import toml
+    except ImportError:
+        toml = None  # Only if spec says toml is optional
+    ```
+- TypeError/AttributeError: Check function signatures and method names
+- AssertionError: Check if the test expectation or the code logic is wrong
+- ZeroDivisionError/ValueError: Add proper error handling
+- SyntaxError (unterminated string literal / unexpected character):
+  This often means the file has garbage appended at the end (common LLM extraction bug).
+  FIX: Read the end of the file and look for JSON-like metadata patterns such as:
+    - Lines starting with `"explanation":`, `"focus":`, `"description":`
+    - Lines with only `}}` or `]`
+    - Code lines ending with `",` followed by JSON keys
+  SOLUTION: Delete all the garbage lines at the end of the file to restore valid Python.
+
+% EDIT POLICY:
+- Keep changes minimal and directly related to the failure
+- Prefer fixing import statements over creating new files
+- Prefer fixing implementation bugs over weakening tests
+- You MAY create new files if truly needed (e.g., __init__.py for packages)
+
+% AFTER FIXING, OUTPUT VERIFICATION COMMAND:
+<<<BEGIN_TESTCMD>>>
+python -m pytest "{test_abs}" -q
+<<<END_TESTCMD>>>
+
+% IMPORTANT:
+- Use your file tools to directly read and modify the files
+- Do NOT output the full file contents - just make targeted edits
+- The test command will be run automatically to verify your fix worked