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

pdd/prompts/detect_change_LLM.prompt

@@ -392,7 +392,7 @@ if __name__ == "__main__":
 % Error Handling
 - Ensure the function handles edge cases, such as missing inputs or model errors, and provide clear error messages.</preamble>
 
-% Here is an example of this being done: <example>% You are an expert Python engineer. Your goal is to write a python function, "code_generator", that will compile a prompt into a code file. 
+% Here is an example of this being done: <example>% You are an expert Python engineer. Your goal is to write a python function, "code_generator", that will compile a prompt into a code file.
 
 You are an expert Python engineer working on the PDD Cloud project.
 
@@ -409,7 +409,11 @@ Python Coding Standards (PDD Cloud)
 import function_import_setup  # MUST be first import
 
 This enables subprocess module resolution for Firebase Functions Framework.
-All endpoint files must have this as their very first import statement.
+All TOP-LEVEL endpoint files (e.g., generate_code.py, main.py) must have this
+as their very first import statement.
+
+**IMPORTANT:** Utility modules inside `utils/` should NOT import this.
+Use relative imports instead (e.g., `from .firebase_helpers import ...`).
 
 ## Standard Library Imports
 import os
@@ -433,14 +437,15 @@ Return tuple: (response_dict, status_code)
 
 
 % Here are the inputs and outputs of the function:
-    Inputs: 
+    Inputs:
         'prompt' - A string containing the raw prompt to be processed.
         'language' - A string that is the language type (e.g. python, bash) of file that will be outputed by the LLM.
         'strength' - A float between 0 and 1 that is the strength of the LLM model to use.
         'temperature' - A float that is the temperature of the LLM model to use. Default is 0.
-        'time' - A float in [0,1] or None that controls the thinking effort for the LLM model, passed to llm_invoke. Default is DEFAULT_TIME. If None, treat as DEFAULT_TIME before invoking llm_invoke.
+        'time' - A float in [0,1] or None that controls the thinking effort for the LLM model, passed to llm_invoke. Default is None.
         'verbose' - A boolean that indicates whether to print out the details of the function. Default is False.
         'preprocess_prompt' - A boolean that indicates whether to preprocess the prompt. Default is True.
+        'output_schema' - An optional dict (JSON schema) to enforce structured output. Default is None.
     Outputs:
         'runnable_code' - A string that is runnable code
         'total_cost' - A float that is the total cost of all LLM calls within this function (initial generation, unfinished check, continuation if used, and postprocess)
@@ -450,27 +455,578 @@ Return tuple: (response_dict, status_code)
     <internal_modules>
         For running prompts with llm_invoke:
         <llm_invoke_example>
-            [File not found: ../context/llm_invoke_example.py]
+            import os
+import sys
+import json
+import logging
+import threading
+import time
+import requests
+from flask import Flask, request, jsonify
+from unittest.mock import MagicMock, patch
+
+# --- 1. Environment Setup ---
+# Set environment variables to simulate local execution
+os.environ['FUNCTIONS_EMULATOR'] = 'true'
+
+# Ensure 'backend/functions' is in PYTHONPATH so we can import the module
+# In a real deployment, this is handled by the Cloud Functions environment.
+current_dir = os.path.dirname(os.path.abspath(__file__))
+backend_functions_path = os.path.abspath(os.path.join(current_dir, '../backend/functions'))
+sys.path.insert(0, backend_functions_path)
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+# --- 2. Mocking Dependencies ---
+# Since this example runs in isolation, we need to mock the complex dependencies
+# that the endpoint relies on (Firebase, PDD CLI internals, etc.)
+
+# Mock function_import_setup
+sys.modules['function_import_setup'] = MagicMock()
+
+# Mock utils.auth_helpers
+mock_auth = MagicMock()
+# Create decorators that just pass through the function
+def pass_through_decorator(func):
+    def wrapper(*args, **kwargs):
+        # Inject dummy user and token if not present
+        if 'user' not in kwargs:
+            kwargs['user'] = MagicMock(uid='test-user-id')
+        if 'token' not in kwargs:
+            kwargs['token'] = {'uid': 'test-user-id'}
+        return func(*args, **kwargs)
+    return wrapper
+
+mock_auth.require_approval = pass_through_decorator
+mock_auth.require_authentication = pass_through_decorator
+sys.modules['utils.auth_helpers'] = mock_auth
+
+# Mock utils.credit_helpers
+mock_credits = MagicMock()
+def credit_decorator(cost_key='totalCost', estimated_cost=0.20):
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            # Simulate credit check passing
+            result, status = func(*args, **kwargs)
+            # Simulate credit deduction logic adding fields to response
+            if isinstance(result, dict):
+                result['creditsDeducted'] = 10  # Dummy deduction
+                result['newBalance'] = 990
+            return result, status
+        return wrapper
+    return decorator
+
+mock_credits.require_credits = credit_decorator
+sys.modules['utils.credit_helpers'] = mock_credits
+
+# Mock utils.error_handling
+mock_errors = MagicMock()
+class AuthenticationError(Exception): pass
+class AuthorizationError(Exception): pass
+class ValidationError(Exception): pass
+mock_errors.AuthenticationError = AuthenticationError
+mock_errors.AuthorizationError = AuthorizationError
+mock_errors.ValidationError = ValidationError
+sys.modules['utils.error_handling'] = mock_errors
+
+# Mock pdd.llm_invoke
+mock_pdd = MagicMock()
+# Define a mock implementation of llm_invoke
+def mock_llm_invoke_impl(prompt=None, input_json=None, messages=None, **kwargs):
+    logger.info(f"[Mock LLM] Invoked with prompt='{prompt}'")
+    return {
+        "result": f"Processed: {prompt or messages}",
+        "cost": 0.005,
+        "model_name": "gpt-4-mock",
+        "thinking_output": "I thought about this deeply..."
+    }
+mock_pdd.llm_invoke = mock_llm_invoke_impl
+sys.modules['pdd.llm_invoke'] = mock_pdd
+
+# --- 3. Import the Module Under Test ---
+try:
+    import llm_invoke
+    logger.info("Successfully imported llm_invoke module")
+except ImportError as e:
+    logger.error(f"Failed to import module: {e}")
+    sys.exit(1)
+
+# --- 4. Flask Server Setup ---
+app = Flask(__name__)
+
+@app.route('/llm_invoke', methods=['POST'])
+def handle_llm_invoke():
+    # The module expects (request, user, token)
+    # In a real Flask app using the decorators, user/token are injected.
+    # Here we call the decorated function directly.
+    
+    # We need to mock the request object passed to the function
+    # Flask's global 'request' proxy works because we are inside a route context
+    return llm_invoke.llm_invoke(request)
+
+def run_server():
+    app.run(port=5005, debug=False, use_reloader=False)
+
+# --- 5. Functional Tests ---
+def run_tests():
+    base_url = 'http://localhost:5005/llm_invoke'
+    headers = {'Content-Type': 'application/json'}
+
+    print("\n" + "="*60)
+    print("Testing llm_invoke")
+    print("="*60)
+
+    # Test Case 1: Basic Prompt
+    print("\n--- Test 1: Basic Prompt & Input JSON ---")
+    payload_1 = {
+        "prompt": "Hello {{name}}",
+        "inputJson": {"name": "World"},
+        "strength": 0.7
+    }
+    try:
+        resp = requests.post(base_url, json=payload_1, headers=headers)
+        print(f"Status: {resp.status_code}")
+        print(f"Response: {json.dumps(resp.json(), indent=2)}")
+        assert resp.status_code == 200
+        assert resp.json()['result'] == "Processed: Hello {{name}}"
+    except Exception as e:
+        print(f"Test 1 Failed: {e}")
+
+    # Test Case 2: Messages List (Chat format)
+    print("\n--- Test 2: Messages List ---")
+    payload_2 = {
+        "messages": [
+            {"role": "system", "content": "You are a bot."},
+            {"role": "user", "content": "Hi."}
+        ],
+        "temperature": 0.5
+    }
+    try:
+        resp = requests.post(base_url, json=payload_2, headers=headers)
+        print(f"Status: {resp.status_code}")
+        print(f"Response: {json.dumps(resp.json(), indent=2)}")
+        assert resp.status_code == 200
+    except Exception as e:
+        print(f"Test 2 Failed: {e}")
+
+    # Test Case 3: Validation Error (Missing inputs)
+    print("\n--- Test 3: Validation Error (Missing inputs) ---")
+    payload_3 = {
+        "strength": 0.5
+        # Missing prompt/inputJson AND messages
+    }
+    try:
+        resp = requests.post(base_url, json=payload_3, headers=headers)
+        print(f"Status: {resp.status_code}")
+        print(f"Response: {json.dumps(resp.json(), indent=2)}")
+        assert resp.status_code == 400
+    except Exception as e:
+        print(f"Test 3 Failed: {e}")
+
+    # Test Case 4: Validation Error (Invalid strength)
+    print("\n--- Test 4: Validation Error (Invalid strength) ---")
+    payload_4 = {
+        "prompt": "Hi",
+        "inputJson": {},
+        "strength": 1.5  # Invalid, must be 0-1
+    }
+    try:
+        resp = requests.post(base_url, json=payload_4, headers=headers)
+        print(f"Status: {resp.status_code}")
+        print(f"Response: {json.dumps(resp.json(), indent=2)}")
+        assert resp.status_code == 400
+    except Exception as e:
+        print(f"Test 4 Failed: {e}")
+
+    print("\n" + "="*60)
+    print("All tests completed.")
+    print("="*60)
+    
+    # Force exit to stop the server thread
+    os._exit(0)
+
+if __name__ == "__main__":
+    # Start the Flask server in a daemon thread
+    server_thread = threading.Thread(target=run_server, daemon=True)
+    server_thread.start()
+    
+    # Give the server a moment to start
+    time.sleep(2)
+    
+    # Run the tests
+    run_tests()
         </llm_invoke_example>
 
         For preprocessing prompts:
         <preprocess_example>
-            [File not found: ../context/preprocess_example.py]
+            from pdd.preprocess import preprocess
+from rich.console import Console   
+console = Console()     
+
+prompt = """
+<prompt>
+    Hello World
+
+    <pdd>This is a comment</pdd>
+    [Error: firecrawl-py package not installed. Cannot scrape https://www.google.com]
+    {test}
+    {test2}
+    ```<TODO.md>```
+
+    <pdd>
+        multi-line
+        comment should not show up
+    </pdd>
+</prompt>
+"""
+
+recursive = False
+double_curly_brackets = True
+exclude_keys = ["test2"] # exclude test2 from being doubled
+
+# Debug info
+console.print(f"[bold yellow]Debug: exclude_keys = {exclude_keys}[/bold yellow]")
+
+processed = preprocess(prompt, recursive, double_curly_brackets, exclude_keys=exclude_keys)
+console.print("[bold white]Processed Prompt:[/bold white]")
+console.print(processed)
+
         </preprocess_example>
 
         For handling unfinished prompts:
         <unfinished_prompt_example>
-            [File not found: ../context/unfinished_prompt_example.py]
+            from pdd.unfinished_prompt import unfinished_prompt
+from rich import print as rprint
+
+# This script provides a concise example of how to use the `unfinished_prompt` function
+# from the `pdd.unfinished_prompt` module.
+
+# --- Pre-requisites for running this example: ---
+# 1. The `pdd` Python package must be accessible. This means:
+#    - It's installed in your Python environment (e.g., via pip if it's a package), OR
+#    - The directory containing the `pdd` package is added to your PYTHONPATH.
+#      For instance, if your project structure is:
+#      my_project/
+#      ├── pdd/  # The module's package
+#      │   ├── __init__.py
+#      │   ├── unfinished_prompt.py
+#      │   ├── load_prompt_template.py
+#      │   └── llm_invoke.py
+#      └── examples/
+#          └── run_this_example.py (this file)
+#      You would typically run this script from the `my_project` directory
+#      (e.g., `python examples/run_this_example.py`) after ensuring `my_project`
+#      is in PYTHONPATH (e.g., `export PYTHONPATH=$PYTHONPATH:/path/to/my_project`).
+#
+# 2. The `pdd` package requires internal setup for its dependencies:
+#    - A prompt template file named "unfinished_prompt_LLM" (e.g., "unfinished_prompt_LLM.txt")
+#      must be present where `pdd.load_prompt_template` (used internally by `unfinished_prompt`)
+#      can find it. This location is usually relative to the `pdd` package structure.
+#    - The `pdd.llm_invoke` function (used internally) must be configured for access to an LLM.
+#      This typically involves setting environment variables for API keys (e.g., `OPENAI_API_KEY`).
+#
+# This script should be saved outside the `pdd` package, for instance, in an
+# `examples/` directory as shown above.
+# To run: `python name_of_this_script.py` (adjust path as needed).
+
+# --- Example Usage ---
+
+# 1. Define the prompt text you want to analyze.
+#    This example uses a prompt that is intentionally incomplete to demonstrate
+#    the function's ability to detect incompleteness.
+my_prompt_text = "Write a comprehensive guide on how to bake a sourdough bread, starting from creating a starter, then the kneading process, and finally"
+
+rprint(f"[bold cyan]Analyzing prompt:[/bold cyan] \"{my_prompt_text}\"")
+
+# 2. Call the `unfinished_prompt` function.
+#    Review the function's docstring for detailed parameter information.
+#    - `prompt_text` (str): The text of the prompt to analyze.
+#    - `strength` (float, optional, 0.0-1.0, default=0.5): Influences the LLM's behavior or model choice.
+#    - `temperature` (float, optional, 0.0-1.0, default=0.0): Controls the randomness of the LLM's output.
+#    - `verbose` (bool, optional, default=False): If True, the function will print detailed internal logs.
+#
+#    The function returns a tuple: (reasoning, is_finished, total_cost, model_name)
+#    - `reasoning` (str): The LLM's structured explanation for its completeness assessment.
+#    - `is_finished` (bool): True if the prompt is considered complete, False otherwise.
+#    - `total_cost` (float): The estimated cost of the LLM call. The unit (e.g., USD) depends on the LLM provider.
+#    - `model_name` (str): The name of the LLM model that was used for the analysis.
+
+# Example call with verbose output and custom strength/temperature settings.
+reasoning_str, is_complete_flag, call_cost, llm_model = unfinished_prompt(
+    prompt_text=my_prompt_text,
+    strength=0.6,       # Example: using a specific strength value
+    temperature=0.1,    # Example: using a low temperature for more deterministic reasoning
+    verbose=True        # Set to True to see detailed logs from within the unfinished_prompt function
+)
+
+# 3. Print the results returned by the function.
+rprint("\n[bold green]--- Analysis Results ---[/bold green]")
+rprint(f"  [bold]Prompt Analyzed:[/bold] \"{my_prompt_text}\"")
+rprint(f"  [bold]Is prompt complete?:[/bold] {'Yes, the LLM considers the prompt complete.' if is_complete_flag else 'No, the LLM suggests the prompt needs continuation.'}")
+rprint(f"  [bold]LLM's Reasoning:[/bold]\n    {reasoning_str}") # Rich print will handle newlines in the reasoning string
+rprint(f"  [bold]Cost of Analysis:[/bold] ${call_cost:.6f}") # Display cost, assuming USD. Adjust currency/format as needed.
+rprint(f"  [bold]LLM Model Used:[/bold] {llm_model}")
+
+# --- Example of calling with default parameters ---
+# If you want to use the default strength (0.5), temperature (0.0), and verbose (False):
+#
+# default_prompt_text = "What is the capital of Canada?"
+# rprint(f"\n[bold cyan]Analyzing prompt with default settings:[/bold cyan] \"{default_prompt_text}\"")
+#
+# reasoning_def, is_finished_def, cost_def, model_def = unfinished_prompt(
+#     prompt_text=default_prompt_text
+# )
+#
+# rprint("\n[bold green]--- Default Call Analysis Results ---[/bold green]")
+# rprint(f"  [bold]Prompt Analyzed:[/bold] \"{default_prompt_text}\"")
+# rprint(f"  [bold]Is prompt complete?:[/bold] {'Yes' if is_finished_def else 'No'}")
+# rprint(f"  [bold]LLM's Reasoning:[/bold]\n    {reasoning_def}")
+# rprint(f"  [bold]Cost of Analysis:[/bold] ${cost_def:.6f}")
+# rprint(f"  [bold]LLM Model Used:[/bold] {model_def}")
+
         </unfinished_prompt_example>
 
         For continuing generation:
         <continue_generation_example>
-            [File not found: ../context/continue_generation_example.py]
+            from pdd.continue_generation import continue_generation
+
+def main() -> None:
+    """
+    Main function to demonstrate the usage of the continue_generation function.
+    It continues the generation of text using a language model and calculates the cost.
+    """
+    # Define the input parameters for the continue_generation function
+    # formatted_input_prompt: str = "Once upon a time in a land far away, there was a"
+    # load context/cli_python_preprocessed.prompt into formatted_input_prompt
+    with open("context/cli_python_preprocessed.prompt", "r") as file:
+        formatted_input_prompt = file.read()
+    
+    # llm_output: str = ""  # Initial LLM output is empty
+    # load context/unfinished_prompt.txt into llm_output
+    with open("context/llm_output_fragment.txt", "r") as file:
+        llm_output = file.read()
+    strength: float = .915  # Strength parameter for the LLM model
+    temperature: float = 0  # Temperature parameter for the LLM model
+
+    try:
+        # Call the continue_generation function
+        final_llm_output, total_cost, model_name = continue_generation(
+            formatted_input_prompt=formatted_input_prompt,
+            llm_output=llm_output,
+            strength=strength,
+            temperature=temperature,
+            verbose=True
+        )
+
+        # Output the results
+        # print(f"Final LLM Output: {final_llm_output}")
+        print(f"Total Cost: ${total_cost:.6f}")
+        print(f"Model Name: {model_name}")
+        # write final_llm_output to context/final_llm_output.txt
+        with open("context/final_llm_output.py", "w") as file:
+            file.write(final_llm_output)
+
+    except FileNotFoundError as e:
+        print(f"Error: {e}")
+    except Exception as e:
+        print(f"An error occurred: {e}")
+
+if __name__ == "__main__":
+    main()
         </continue_generation_example>
 
         For postprocessing results:
         <postprocess_example>
-            [File not found: ../context/postprocess_example.py]
+            """
+Example demonstrating the usage of the `postprocess` function 
+from the `pdd.postprocess` module.
+
+This example showcases two scenarios for extracting code from an LLM's text output:
+1. Simple code extraction (strength = 0): Uses basic string manipulation to find code
+   blocks enclosed in triple backticks. This method is fast and has no cost.
+2. Advanced code extraction (strength > 0): Leverages an LLM for more robust extraction.
+   This method is more powerful but incurs a cost and takes more time.
+
+To run this example:
+1. Ensure the `pdd` package (containing the `postprocess` module) is in your PYTHONPATH
+   or installed in your environment.
+2. Ensure the `rich` library is installed (`pip install rich`).
+3. This script uses `unittest.mock` (part of Python's standard library) to simulate
+   the behavior of internal dependencies (`load_prompt_template` and `llm_invoke`)
+   for the LLM-based extraction scenario. This allows the example to run without
+   requiring actual LLM API calls or specific prompt files.
+"""
+from rich import print
+from unittest.mock import patch, MagicMock
+
+# Assuming 'pdd' package is in PYTHONPATH or installed.
+# The 'postprocess' module is expected to be at pdd/postprocess.py
+from pdd.postprocess import postprocess, ExtractedCode # ExtractedCode is needed for the mock
+from pdd import DEFAULT_STRENGTH
+
+def main():
+    """
+    Runs the demonstration for the postprocess function.
+    """
+    print("[bold underline blue]Demonstrating `postprocess` function from `pdd.postprocess`[/bold underline blue]\n")
+
+    # --- Common Inputs ---
+    # This is a sample string that might be output by an LLM, containing text and code.
+    llm_output_text_with_code = """
+This is some text from an LLM.
+It includes a Python code block:
+```python
+def greet(name):
+    # A simple greeting function
+    print(f"Hello, {name}!")
+
+greet("Developer")
+```
+And some more text after the code block.
+There might be other language blocks too:
+```javascript
+console.log("This is JavaScript");
+```
+But we are only interested in Python.
+"""
+    # The target programming language for extraction.
+    target_language = "python"
+
+    # --- Scenario 1: Simple Extraction (strength = 0) ---
+    # This mode uses the `postprocess_0` internal function, which performs a basic
+    # extraction of content between triple backticks. It does not use an LLM.
+    print("[bold cyan]Scenario 1: Simple Extraction (strength = 0)[/bold cyan]")
+    print("Demonstrates extracting code using basic string processing.")
+    print(f"  Input LLM Output: (see below)")
+    # print(f"[dim]{llm_output_text_with_code}[/dim]") # Printing for brevity in console
+    print(f"  Target Language: '{target_language}' (Note: simple extraction is language-agnostic but extracts first block)")
+    print(f"  Strength: 0 (activates simple, non-LLM extraction)")
+    print(f"  Verbose: True (enables detailed console output from `postprocess`)\n")
+
+    # Call postprocess with strength = 0
+    # Input parameters:
+    #   llm_output (str): The LLM's raw output string.
+    #   language (str): The programming language to extract (less critical for strength=0).
+    #   strength (float): 0-1, model strength. 0 means simple extraction.
+    #   temperature (float): 0-1, LLM temperature (not used for strength=0).
+    #   time (float): 0-1, LLM thinking effort (not used for strength=0).
+    #   verbose (bool): If True, prints internal processing steps.
+    extracted_code_s0, cost_s0, model_s0 = postprocess(
+        llm_output=llm_output_text_with_code,
+        language=target_language,
+        strength=0,
+        verbose=True
+    )
+
+    print("[bold green]Output for Scenario 1:[/bold green]")
+    # Output tuple:
+    #   extracted_code (str): The extracted code.
+    #   total_cost (float): Cost of the operation (in dollars). Expected to be 0.0 for simple extraction.
+    #   model_name (str): Identifier for the method/model used. Expected to be 'simple_extraction'.
+    print(f"  Extracted Code:\n[yellow]{extracted_code_s0}[/yellow]")
+    print(f"  Total Cost: ${cost_s0:.6f}")
+    print(f"  Model Name: '{model_s0}'")
+    print("-" * 60)
+
+    # --- Scenario 2: LLM-based Extraction (strength > 0) ---
+    # This mode uses an LLM via `llm_invoke` to perform a more sophisticated extraction.
+    # It requires a prompt template (`extract_code_LLM.prompt`).
+    # For this example, `load_prompt_template` and `llm_invoke` are mocked.
+    print(f"\n[bold cyan]Scenario 2: LLM-based Extraction (strength = {DEFAULT_STRENGTH})[/bold cyan]")
+    print("Demonstrates extracting code using an LLM (mocked).")
+    print(f"  Input LLM Output: (same as above)")
+    print(f"  Target Language: '{target_language}'")
+    print(f"  Strength: {DEFAULT_STRENGTH} (activates LLM-based extraction)")
+    print(f"  Temperature: 0.0 (LLM creativity, 0-1 scale)")
+    print(f"  Time: 0.5 (LLM thinking effort, 0-1 scale, influences model choice/cost)")
+    print(f"  Verbose: True\n")
+
+    # Mock for `load_prompt_template`:
+    # This function is expected to load a prompt template file (e.g., 'extract_code_LLM.prompt').
+    # In a real scenario, this file would exist in a 'prompts' directory.
+    mock_load_template = MagicMock(return_value="Mocked Prompt: Extract {{language}} code from: {{llm_output}}")
+
+    # Mock for `llm_invoke`:
+    # This function handles the actual LLM API call.
+    # It's expected to return a dictionary containing the LLM's result (parsed into
+    # an `ExtractedCode` Pydantic model), the cost, and the model name.
+    # The `extracted_code` from the LLM mock should include backticks and language identifier
+    # to test the cleaning step within the `postprocess` function.
+    mock_llm_response_code_from_llm = """```python
+def sophisticated_extraction(data):
+    # This code is supposedly extracted by an LLM
+    processed_data = data.upper()  # Example processing
+    return processed_data
+
+result = sophisticated_extraction("test data from llm")
+print(result)
+```"""
+    mock_extracted_code_pydantic_obj = ExtractedCode(extracted_code=mock_llm_response_code_from_llm)
+    mock_llm_invoke_return_value = {
+        'result': mock_extracted_code_pydantic_obj,
+        'cost': 0.00025,  # Example cost in dollars
+        'model_name': 'mock-llm-extractor-v1'
+    }
+    mock_llm_invoke_function = MagicMock(return_value=mock_llm_invoke_return_value)
+
+    # Patch the internal dependencies within the 'pdd.postprocess' module's namespace.
+    # This ensures that when `postprocess` calls `load_prompt_template` or `llm_invoke`,
+    # our mocks are used instead of the real implementations.
+    with patch('pdd.postprocess.load_prompt_template', mock_load_template):
+        with patch('pdd.postprocess.llm_invoke', mock_llm_invoke_function):
+            extracted_code_llm, cost_llm, model_llm = postprocess(
+                llm_output=llm_output_text_with_code,
+                language=target_language,
+                strength=DEFAULT_STRENGTH,
+                temperature=0.0,
+                time=0.5,
+                verbose=True
+            )
+
+            print("[bold green]Output for Scenario 2:[/bold green]")
+            print(f"  Extracted Code:\n[yellow]{extracted_code_llm}[/yellow]")
+            print(f"  Total Cost: ${cost_llm:.6f} (cost is in dollars)")
+            print(f"  Model Name: '{model_llm}'")
+
+            # --- Verification of Mock Calls (for developer understanding) ---
+            # Check that `load_prompt_template` was called correctly.
+            mock_load_template.assert_called_once_with("extract_code_LLM")
+
+            # Check that `llm_invoke` was called correctly.
+            mock_llm_invoke_function.assert_called_once()
+            # Inspect the arguments passed to the mocked llm_invoke
+            call_args_to_llm_invoke = mock_llm_invoke_function.call_args[1] # kwargs
+            assert call_args_to_llm_invoke['prompt'] == mock_load_template.return_value
+            assert call_args_to_llm_invoke['input_json'] == {
+                "llm_output": llm_output_text_with_code,
+                "language": target_language
+            }
+            assert call_args_to_llm_invoke['strength'] == DEFAULT_STRENGTH
+            assert call_args_to_llm_invoke['temperature'] == 0.0
+            assert call_args_to_llm_invoke['time'] == 0.5
+            assert call_args_to_llm_invoke['verbose'] is True
+            assert call_args_to_llm_invoke['output_pydantic'] == ExtractedCode
+            print("[dim]  (Mocked LLM calls verified successfully)[/dim]")
+
+    print("\n[bold underline blue]Demonstration finished.[/bold underline blue]")
+    print("\n[italic]Important Notes:[/italic]")
+    print("  - For Scenario 2 (LLM-based extraction), `load_prompt_template` and `llm_invoke` were mocked.")
+    print("    In a real-world scenario:")
+    print("    - `load_prompt_template('extract_code_LLM')` would attempt to load a file named ")
+    print("      `extract_code_LLM.prompt` (typically from a 'prompts' directory configured within the `pdd` package).")
+    print("    - `llm_invoke` would make an actual API call to a Large Language Model, which requires")
+    print("      API keys and network access.")
+    print("  - The `time` parameter (0-1) for `postprocess` (and `llm_invoke`) generally controls the")
+    print("    'thinking effort' or computational resources allocated to the LLM, potentially affecting")
+    print("    which underlying LLM model is chosen and the quality/cost of the result.")
+    print("  - No actual files (like prompt files or output files) are created or read by this example script,")
+    print("    particularly in the './output' directory, due to the use of mocks for file-dependent operations.")
+
+if __name__ == "__main__":
+    main()
+
         </postprocess_example>
     </internal_modules>
 
@@ -478,21 +1034,22 @@ Return tuple: (response_dict, status_code)
     Step 1. Conditionally preprocess the raw prompt using the preprocess function from the preprocess module based on the value of 'preprocess_prompt'. If 'preprocess_prompt' is True, preprocess the prompt; otherwise, use the raw prompt directly. When preprocessing, it is acceptable to enable options such as double_curly_brackets=True and recursive=False to preserve placeholders and avoid over-expansion.
 
     Step 2. Generate the initial response as follows:
-        - If the prompt contains embedded data URLs (e.g., 'data:image/...;base64,...'), split the prompt into alternating text and image parts (preserving order) and call llm_invoke with messages=[{role: 'user', content: [{type: 'image_url', image_url: {url: ...}}, {type: 'text', text: ...}, ...]}] and the provided strength, temperature, time, and verbose.
-        - Otherwise, call llm_invoke with the (preprocessed or raw) prompt, input_json={}, and the provided strength, temperature, time, and verbose.
+        - If the prompt contains embedded data URLs (e.g., 'data:image/...;base64,...'), split the prompt into alternating text and image parts (preserving order) and call llm_invoke with messages=[{role: 'user', content: [{type: 'image_url', image_url: {url: ...}}, {type: 'text', text: ...}, ...]}] and the provided strength, temperature, time, verbose, output_schema, and language.
+        - Otherwise, call llm_invoke with the (preprocessed or raw) prompt, input_json={}, and the provided strength, temperature, time, verbose, output_schema, and language.
 
     Step 3. Detect if the generation is incomplete using the unfinished_prompt function (use strength=0.5, temperature=0.0) by passing in the last 600 characters of the output of Step 2. Pass through language, time, and verbose.
-        - a. If incomplete, call the continue_generation function to complete the generation and set final_output to that result.
+        - a. If incomplete, call the continue_generation function to complete the generation and set final_output to that result. Pass through language, time, and verbose.
         - b. Else, set final_output to the initial model output.
 
-    Step 4. Postprocess the final_output using the postprocess function from the postprocess module with the EXTRACTION_STRENGTH constant. Use temperature=0.0 and pass through language, time, and verbose.
+    Step 4. Postprocess the final_output:
+        - If language is "json" (case-insensitive) or output_schema is provided, skip extraction: if final_output is a string, return it as-is; otherwise, serialize it with json.dumps.
+        - Otherwise, use the postprocess function from the postprocess module with the EXTRACTION_STRENGTH constant. Use temperature=0.0 and pass through language, time, and verbose.
 
     Step 5. Return the runnable_code, total_cost and model_name.
 
 % Validation and defaults:
     - Validate non-empty 'prompt' and 'language'.
     - Enforce 0 ≤ strength ≤ 1 and 0 ≤ temperature ≤ 2.
-    - Enforce 0 ≤ time ≤ 1 when provided; if time is None, substitute DEFAULT_TIME before llm_invoke.
 </example>
         </change_description_example>
     </input_example>

pdd/prompts/fix_code_module_errors_LLM.prompt

@@ -8,6 +8,14 @@
 - If you are not able to fix the calling program, or if you cannot access it, you shouldn't guess at fixes to the calling program. Do not add the functionality of the calling program to the code_module.
 - You must ensure that the code_module strictly adheres to the prompt requirements
 
+% The program file is located at: {program_path}
+% The code module is located at: {code_path}
+
+% IMPORTANT for path-related errors: When fixing path calculations (e.g., os.path.dirname,
+% sys.path manipulation), consider the file's actual location relative to the project root.
+% For example, if the program is at "context/backend/example.py", it needs to traverse UP
+% two directories to reach the project root, not one.
+
 % Here is the calling program that is running the code_module that crashed and/or has errors: <program>{program}</program>
 
 % Here is the prompt that generated the code_module below: <prompt>{prompt}</prompt>

pdd/prompts/fix_errors_from_unit_tests_LLM.prompt

@@ -28,4 +28,5 @@
     Step 5. Explain in detail step by step how to solve each of the errors and warnings. For each error and warning, there should be several paragraphs description of the solution steps. Sometimes logging or print statements can help debug the code in subsequent iterations. It is important to make sure the tests are still sufficiently comprehensive to catch potential errors.
     Step 6. Review the above steps and correct for any errors and warnings in the code under test or unit test.
     Step 7. For the code that need changes, write the corrected code_under_test and/or corrected unit_test in its/their entirety.
+    Step 8. CRITICAL: You MUST preserve ALL existing test functions from the original unit_test. Only modify the tests that are failing. Do not remove, skip, or omit any test functions that were present in the original unit_test, even if they seem unrelated to the current errors. The output must include every single test function from the input.
 </instructions>