patchllm 0.2.2__tar.gz → 1.0.0__tar.gz

patchllm-1.0.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: patchllm
+Version: 1.0.0
+Summary: An interactive agent for codebase modification using LLMs
+Author: nassimberrada
+License: MIT License
+        
+        Copyright (c) 2025 nassimberrada
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the “Software”), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: litellm
+Requires-Dist: python-dotenv
+Requires-Dist: rich
+Requires-Dist: prompt_toolkit
+Requires-Dist: InquirerPy
+Provides-Extra: voice
+Requires-Dist: SpeechRecognition; extra == "voice"
+Requires-Dist: pyttsx3; extra == "voice"
+Provides-Extra: url
+Requires-Dist: html2text; extra == "url"
+Provides-Extra: all
+Requires-Dist: SpeechRecognition; extra == "all"
+Requires-Dist: pyttsx3; extra == "all"
+Requires-Dist: html2text; extra == "all"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source srcset="./assets/logo_dark.png" media="(prefers-color-scheme: dark)">
+    <source srcset="./assets/logo_light.png" media="(prefers-color-scheme: light)">
+    <img src="./assets/logo_light.png" alt="PatchLLM Logo" height="200">
+  </picture>
+</p>
+
+## About
+PatchLLM is an interactive command-line agent that helps you modify your codebase. It uses an LLM to plan and execute changes, allowing you to review and approve every step.
+
+## Key Features
+- **Interactive Planning:** The agent proposes a step-by-step plan before writing any code. You stay in control.
+- **Dynamic Context:** Build and modify the code context on-the-fly using powerful scope definitions (`@git:staged`, `@dir:src`, etc.).
+- **Mobile-First TUI:** A clean, command-driven interface with autocompletion makes it easy to use on any device.
+- **Resilient Sessions:** Automatically saves your progress so you can resume if you get disconnected.
+
+## Getting Started
+
+**1. Initialize a configuration file (optional):**
+This creates a `scopes.py` file to define reusable file collections.
+```bash
+patchllm --init
+```
+
+**2. Start the Agent:**
+Running `patchllm` with no arguments drops you into the interactive agentic TUI.
+```bash
+patchllm
+```
+
+**3. Follow the Agent Workflow:**
+Inside the TUI, you direct the agent with simple slash commands.
+
+```bash
+# 1. Set the goal
+>>> /task Add a health check endpoint to the API
+
+# 2. Build the context
+>>> /context @dir:src/api
+
+# 3. Ask the agent to generate a plan
+>>> /plan
+1. Add a new route `/health` to `src/api/routes.py`.
+2. Implement the health check logic to return a 200 OK status.
+
+# 4. Execute the first step and review the proposed changes
+>>> /run
+
+# 5. If the changes look good, approve them
+>>> /approve
+```
+
+## Agent Commands (TUI)
+| Command | Description |
+|---|---|
+| `/task <goal>` | Sets the high-level goal for the agent. |
+| `/plan [management]` | Generates a plan, or opens an interactive TUI to edit/add/remove steps. |
+| `/run [all]` | Executes the next step, or all remaining steps with `/run all`. |
+| `/approve` | Interactively select and apply changes from the last run. |
+| `/diff [all \| file]`| Shows the full diff for the proposed changes. |
+| `/retry <feedback>`| Retries the last step with new feedback. |
+| `/skip` | Skips the current step and moves to the next. |
+| `/revert` | Reverts the changes from the last `/approve`. |
+| `/context <scope>` | Replaces the context with files from a scope. |
+| `/scopes` | Opens an interactive menu to manage your saved scopes. |
+| `/ask <question>` | Ask a question about the plan or code context. |
+| `/refine <feedback>`| Refine the plan based on new feedback or ideas. |
+| `/show [state]` | Shows the current state (goal, plan, context, history, step). |
+| `/settings` | Configure the model and API keys. |
+| `/help` | Shows the detailed help message. |
+| `/exit` | Exits the agent session. |
+
+## Headless Mode Flags
+For scripting or single-shot edits, you can still use the original flags.
+
+| Flag | Alias | Description |
+|---|---|---|
+| `-p`, `--patch` | **Main action:** Query the LLM and apply file changes. |
+| `-t`, `--task` | Provide a specific instruction to the LLM. |
+| `-s`, `--scope` | Use a static scope from `scopes.py` or a dynamic one. |
+| `-r`, `--recipe` | Use a predefined task from `recipes.py`. |
+| `-in`, `--interactive` | Interactively build the context by selecting files. |
+| `-i`, `--init` | Create a new `scopes.py` file. |
+| `-sl`, `--list-scopes`| List all available scopes. |
+| `-ff`, `--from-file` | Apply patches from a local file. |
+| `-fc`, `--from-clipboard` | Apply patches from the system clipboard. |
+| `-m`, `--model` | Specify a different model (default: `gemini/gemini-1.5-flash`). |
+| `-v`, `--voice` | Enable voice interaction (requires voice dependencies). |
+
+## Setup
+PatchLLM uses [LiteLLM](https://github.com/BerriAI/litellm). Set up your API keys (e.g., `OPENAI_API_KEY`, `GEMINI_API_KEY`) in a `.env` file.
+
+The interactive TUI requires `prompt_toolkit` and `InquirerPy`. You can install all core dependencies with:```bash
+pip install -r requirements.txt
+```
+
+Optional features require extra dependencies:
+```bash
+# For URL support in scopes
+pip install "patchllm[url]"
+
+# For voice commands (in headless mode)
+pip install "patchllm[voice]"
+```
+
+## License
+This project is licensed under the MIT License.

patchllm-1.0.0/README.md

@@ -0,0 +1,108 @@
+<p align="center">
+  <picture>
+    <source srcset="./assets/logo_dark.png" media="(prefers-color-scheme: dark)">
+    <source srcset="./assets/logo_light.png" media="(prefers-color-scheme: light)">
+    <img src="./assets/logo_light.png" alt="PatchLLM Logo" height="200">
+  </picture>
+</p>
+
+## About
+PatchLLM is an interactive command-line agent that helps you modify your codebase. It uses an LLM to plan and execute changes, allowing you to review and approve every step.
+
+## Key Features
+- **Interactive Planning:** The agent proposes a step-by-step plan before writing any code. You stay in control.
+- **Dynamic Context:** Build and modify the code context on-the-fly using powerful scope definitions (`@git:staged`, `@dir:src`, etc.).
+- **Mobile-First TUI:** A clean, command-driven interface with autocompletion makes it easy to use on any device.
+- **Resilient Sessions:** Automatically saves your progress so you can resume if you get disconnected.
+
+## Getting Started
+
+**1. Initialize a configuration file (optional):**
+This creates a `scopes.py` file to define reusable file collections.
+```bash
+patchllm --init
+```
+
+**2. Start the Agent:**
+Running `patchllm` with no arguments drops you into the interactive agentic TUI.
+```bash
+patchllm
+```
+
+**3. Follow the Agent Workflow:**
+Inside the TUI, you direct the agent with simple slash commands.
+
+```bash
+# 1. Set the goal
+>>> /task Add a health check endpoint to the API
+
+# 2. Build the context
+>>> /context @dir:src/api
+
+# 3. Ask the agent to generate a plan
+>>> /plan
+1. Add a new route `/health` to `src/api/routes.py`.
+2. Implement the health check logic to return a 200 OK status.
+
+# 4. Execute the first step and review the proposed changes
+>>> /run
+
+# 5. If the changes look good, approve them
+>>> /approve
+```
+
+## Agent Commands (TUI)
+| Command | Description |
+|---|---|
+| `/task <goal>` | Sets the high-level goal for the agent. |
+| `/plan [management]` | Generates a plan, or opens an interactive TUI to edit/add/remove steps. |
+| `/run [all]` | Executes the next step, or all remaining steps with `/run all`. |
+| `/approve` | Interactively select and apply changes from the last run. |
+| `/diff [all \| file]`| Shows the full diff for the proposed changes. |
+| `/retry <feedback>`| Retries the last step with new feedback. |
+| `/skip` | Skips the current step and moves to the next. |
+| `/revert` | Reverts the changes from the last `/approve`. |
+| `/context <scope>` | Replaces the context with files from a scope. |
+| `/scopes` | Opens an interactive menu to manage your saved scopes. |
+| `/ask <question>` | Ask a question about the plan or code context. |
+| `/refine <feedback>`| Refine the plan based on new feedback or ideas. |
+| `/show [state]` | Shows the current state (goal, plan, context, history, step). |
+| `/settings` | Configure the model and API keys. |
+| `/help` | Shows the detailed help message. |
+| `/exit` | Exits the agent session. |
+
+## Headless Mode Flags
+For scripting or single-shot edits, you can still use the original flags.
+
+| Flag | Alias | Description |
+|---|---|---|
+| `-p`, `--patch` | **Main action:** Query the LLM and apply file changes. |
+| `-t`, `--task` | Provide a specific instruction to the LLM. |
+| `-s`, `--scope` | Use a static scope from `scopes.py` or a dynamic one. |
+| `-r`, `--recipe` | Use a predefined task from `recipes.py`. |
+| `-in`, `--interactive` | Interactively build the context by selecting files. |
+| `-i`, `--init` | Create a new `scopes.py` file. |
+| `-sl`, `--list-scopes`| List all available scopes. |
+| `-ff`, `--from-file` | Apply patches from a local file. |
+| `-fc`, `--from-clipboard` | Apply patches from the system clipboard. |
+| `-m`, `--model` | Specify a different model (default: `gemini/gemini-1.5-flash`). |
+| `-v`, `--voice` | Enable voice interaction (requires voice dependencies). |
+
+## Setup
+PatchLLM uses [LiteLLM](https://github.com/BerriAI/litellm). Set up your API keys (e.g., `OPENAI_API_KEY`, `GEMINI_API_KEY`) in a `.env` file.
+
+The interactive TUI requires `prompt_toolkit` and `InquirerPy`. You can install all core dependencies with:```bash
+pip install -r requirements.txt
+```
+
+Optional features require extra dependencies:
+```bash
+# For URL support in scopes
+pip install "patchllm[url]"
+
+# For voice commands (in headless mode)
+pip install "patchllm[voice]"
+```
+
+## License
+This project is licensed under the MIT License.

patchllm-1.0.0/patchllm/agent/actions.py

@@ -0,0 +1,73 @@
+import subprocess
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+
+def run_tests():
+    """
+    Runs tests using pytest and displays the output.
+    """
+    console.print("\n--- Running Tests ---", style="bold yellow")
+    try:
+        process = subprocess.run(
+            ["pytest"],
+            capture_output=True,
+            text=True,
+            check=False  # We don't want to crash if tests fail
+        )
+        
+        output = process.stdout + process.stderr
+        
+        if process.returncode == 0:
+            title = "[bold green]✅ Tests Passed[/bold green]"
+            border_style = "green"
+        else:
+            title = "[bold red]❌ Tests Failed[/bold red]"
+            border_style = "red"
+            
+        console.print(Panel(output, title=title, border_style=border_style, expand=True))
+
+    except FileNotFoundError:
+        console.print("❌ 'pytest' command not found. Is it installed and in your PATH?", style="red")
+    except Exception as e:
+        console.print(f"❌ An unexpected error occurred while running tests: {e}", style="red")
+
+
+def stage_files(files_to_stage: list[str] = None):
+    """
+    Stages files using git. If no files are specified, stages all changes.
+
+    Args:
+        files_to_stage (list[str], optional): A list of specific files to stage. Defaults to None.
+    """
+    command = ["git", "add"]
+    action_desc = "all changes"
+    if files_to_stage:
+        command.extend(files_to_stage)
+        action_desc = f"{len(files_to_stage)} file(s)"
+    else:
+        command.append(".")
+
+    console.print(f"\n--- Staging {action_desc} ---", style="bold yellow")
+    try:
+        process = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        
+        output = process.stdout + process.stderr
+        if output:
+            console.print(output, style="dim")
+            
+        console.print("✅ Files staged successfully.", style="green")
+
+    except FileNotFoundError:
+        console.print("❌ 'git' command not found. Is it installed and in your PATH?", style="red")
+    except subprocess.CalledProcessError as e:
+        console.print("❌ Failed to stage files.", style="red")
+        console.print(e.stderr)
+    except Exception as e:
+        console.print(f"❌ An unexpected error occurred while staging files: {e}", style="red")

patchllm-1.0.0/patchllm/agent/executor.py

@@ -0,0 +1,57 @@
+from ..llm import run_llm_query
+from ..parser import summarize_changes, get_diff_for_file, parse_change_summary
+
+def execute_step(step_instruction: str, history: list[dict], context: str | None, context_images: list | None, model_name: str) -> dict | None:
+    """
+    Executes a single step of the plan by calling the LLM.
+
+    Args:
+        step_instruction (str): The instruction for the current step.
+        history (list[dict]): The full conversation history.
+        context (str | None): The file context for the LLM.
+        context_images (list | None): A list of image data dictionaries for multimodal context.
+        model_name (str): The name of the LLM to use.
+
+    Returns:
+        A dictionary containing the instruction, response, and diffs, or None if it fails.
+    """
+    
+    prompt_text = f"## Current Task:\n{step_instruction}"
+    if context:
+        prompt_text = f"## Context:\n{context}\n\n---\n\n{prompt_text}"
+    
+    user_content = [{"type": "text", "text": prompt_text}]
+
+    if context_images:
+        for image_info in context_images:
+            user_content.append({
+                "type": "image_url",
+                "image_url": {
+                    "url": f"data:{image_info['mime_type']};base64,{image_info['content_base64']}"
+                }
+            })
+
+    # Create a temporary message history for this specific call
+    messages = history + [{"role": "user", "content": user_content}]
+    
+    llm_response = run_llm_query(messages, model_name)
+    
+    if not llm_response:
+        return None
+    
+    change_summary = parse_change_summary(llm_response)
+    summary = summarize_changes(llm_response)
+    all_files = summary.get("modified", []) + summary.get("created", [])
+    
+    diffs = []
+    for file_path in all_files:
+        diff_text = get_diff_for_file(file_path, llm_response)
+        diffs.append({"file_path": file_path, "diff_text": diff_text})
+        
+    return {
+        "instruction": step_instruction,
+        "llm_response": llm_response,
+        "summary": summary,
+        "diffs": diffs,
+        "change_summary": change_summary,
+    }

patchllm-1.0.0/patchllm/agent/planner.py

@@ -0,0 +1,76 @@
+import re
+from ..llm import run_llm_query
+
+def _get_planning_prompt(goal: str, context_tree: str) -> list[dict]:
+    """Constructs the initial prompt for the planning phase."""
+    
+    system_prompt = (
+        "You are an expert software architect. Your task is to create a high-level, milestone-focused plan to "
+        "accomplish a user's goal. Break down the goal into logical, sequential steps that represent significant "
+        "pieces of functionality or architectural changes."
+        "\n\n"
+        "IMPORTANT RULES:\n"
+        "- DO NOT list individual file modifications. Instead, group related changes into a single milestone.\n"
+        "- For example, instead of a plan like '1. Add route to api.py, 2. Create logic in services.py', a better, "
+        "milestone-focused step would be '1. Implement the user authentication endpoint, including routes and server actions'.\n"
+        "- Do not write any code or implementation details in the plan.\n"
+        "- Each step should be a clear, actionable instruction for a developer.\n"
+        "- The final plan must be a numbered list."
+    )
+    
+    user_prompt = (
+        "Based on my goal and the project structure below, create your plan.\n\n"
+        f"## Project Structure:\n```\n{context_tree}\n```\n\n"
+        f"## Goal:\n{goal}"
+    )
+    
+    return [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_prompt}
+    ]
+
+def _get_refine_prompt(history: list[dict], feedback: str) -> list[dict]:
+    """Constructs the prompt for refining an existing plan."""
+    refine_instruction = (
+        "The user has provided feedback or a new idea on the plan you created. "
+        "Carefully review the entire conversation and their latest feedback. "
+        "Your task is to generate a new, complete, and improved step-by-step plan that incorporates their feedback. "
+        "The new plan should be a single, cohesive, numbered list. Do not just add to the old plan; create a new one from scratch."
+        f"\n\n## User Feedback:\n{feedback}"
+    )
+    
+    return history + [{"role": "user", "content": refine_instruction}]
+
+def parse_plan_from_response(response_text: str) -> list[str] | None:
+    """Finds all lines that start with a number and a period (e.g., "1.", "2.")."""
+    if not response_text:
+        return None
+    # This is more robust than splitting by newline.
+    plan = re.findall(r"^\s*\d+\.\s+(.*)", response_text, re.MULTILINE)
+    return plan if plan else None
+
+def generate_plan_and_history(goal: str, context_tree: str, model_name: str) -> tuple[list[dict], str | None]:
+    """
+    Calls the LLM to generate an initial plan and returns the history and response.
+
+    Returns:
+        A tuple containing the initial planning history (list of messages) and the LLM's raw response text.
+    """
+    messages = _get_planning_prompt(goal, context_tree)
+    response_text = run_llm_query(messages, model_name)
+    
+    if response_text:
+        messages.append({"role": "assistant", "content": response_text})
+    
+    return messages, response_text
+
+def generate_refined_plan(history: list[dict], feedback: str, model_name: str) -> str | None:
+    """
+    Calls the LLM to refine a plan based on conversation history and new feedback.
+
+    Returns:
+        The LLM's raw response text containing the new plan.
+    """
+    messages = _get_refine_prompt(history, feedback)
+    response_text = run_llm_query(messages, model_name)
+    return response_text