patchllm 0.2.1__tar.gz → 0.2.2__tar.gz

{patchllm-0.2.1 → patchllm-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchllm
-Version: 0.2.1
+Version: 0.2.2
 Summary: Lightweight tool to manage contexts and update code with LLMs
 Author: nassimberrada
 License: MIT License
@@ -49,21 +49,21 @@ Dynamic: license-file
 PatchLLM is a command-line tool that lets you flexibly build LLM context from your codebase using glob patterns, URLs, and keyword searches. It then automatically applies file edits directly from the LLM's response.
 
 ## Usage
-PatchLLM is designed to be used directly from your terminal.
+PatchLLM is designed to be used directly from your terminal. The core workflow is to define a **scope** of files, provide a **task**, and choose an **action** (like patching files directly).
 
-### 1. Initialize a Configuration
-The easiest way to get started is to run the interactive initializer. This will create a `configs.py` file for you.
+### 1. Initialize a Scope
+The easiest way to get started is to run the interactive initializer. This will create a `scopes.py` file for you, which holds your saved scopes.
 
 ```bash
 patchllm --init
 ```
 
-This will guide you through creating your first context configuration, including setting a base path and file patterns. You can add multiple configurations to this file.
+This will guide you through creating your first scope, including setting a base path and file patterns. You can add multiple scopes to this file for different projects or tasks.
 
-A generated `configs.py` might look like this:
+A generated `scopes.py` might look like this:
 ```python
-# configs.py
-configs = {
+# scopes.py
+scopes = {
     "default": {
         "path": ".",
         "include_patterns": ["**/*.py"],
@@ -78,45 +78,47 @@ configs = {
 ```
 
 ### 2. Run a Task
-Use the `patchllm` command with a configuration name and a task instruction.
+Use the `patchllm` command with a scope, a task, and an action flag like `--patch` (`-p`).
 
 ```bash
-# Apply a change using the 'default' configuration
-patchllm --config default --task "Add type hints to the main function in main.py"
+# Apply a change using the 'default' scope and the --patch action
+patchllm -s default -t "Add type hints to the main function in main.py" -p
 ```
 
 The tool will then:
-1.  Build a context from the files and URLs matching your configuration.
+1.  Build a context from the files and URLs matching your `default` scope.
 2.  Send the context and your task to the configured LLM.
 3.  Parse the response and automatically write the changes to the relevant files.
 
 ### All Commands & Options
 
-#### Configuration Management
-*   `--init`: Create a new configuration interactively.
-*   `--list-configs`: List all available configurations from your `configs.py`.
-*   `--show-config <name>`: Display the settings for a specific configuration.
+#### Core Patching Flow
+*   `-s, --scope <name>`: Name of the scope to use from your `scopes.py` file.
+*   `-t, --task "<instruction>"`: The task instruction for the LLM.
+*   `-p, --patch`: Query the LLM and directly apply the file updates from the response. **This is the main action flag.**
 
-#### Core Task Execution
-*   `--config <name>`: The name of the configuration to use for building context.
-*   `--task "<instruction>"`: The task instruction for the LLM.
-*   `--model <model_name>`: Specify a different model (e.g., `claude-3-opus`). Defaults to `gemini/gemini-1.5-flash`.
+#### Scope Management
+*   `-i, --init`: Create a new scope interactively.
+*   `-sl, --list-scopes`: List all available scopes from your `scopes.py` file.
+*   `-ss, --show-scope <name>`: Display the settings for a specific scope.
 
-#### Context Handling
-*   `--context-out [filename]`: Save the generated context to a file (defaults to `context.md`) instead of sending it to the LLM.
-*   `--context-in <filename>`: Use a previously saved context file directly, skipping context generation.
-*   `--update False`: A flag to prevent sending the prompt to the LLM. Useful when you only want to generate and save the context with `--context-out`.
+#### I/O & Context Management
+*   `-co, --context-out [filename]`: Export the generated context to a file (defaults to `context.md`) instead of running a task.
+*   `-ci, --context-in <filename>`: Use a previously saved context file as input for a task.
+*   `-tf, --to-file [filename]`: Send the LLM response to a file (defaults to `response.md`) instead of patching directly.
+*   `-tc, --to-clipboard`: Copy the LLM response to the clipboard.
+*   `-ff, --from-file <filename>`: Apply patches from a local file instead of an LLM response.
+*   `-fc, --from-clipboard`: Apply patches directly from your clipboard content.
 
-#### Alternative Inputs
-*   `--from-file <filename>`: Apply file patches directly from a local file instead of from an LLM response.
-*   `--from-clipboard`: Apply file patches directly from your clipboard content.
-*   `--voice True`: Use voice recognition to provide the task instruction. Requires extra dependencies.
+#### General Options
+*   `--model <model_name>`: Specify a different model (e.g., `gpt-4o`). Defaults to `gemini/gemini-1.5-flash`.
+*   `--voice`: Enable voice recognition to provide the task instruction.
 
 ### Setup
 
 PatchLLM uses [LiteLLM](https://github.com/BerriAI/litellm) under the hood. Please refer to their documentation for setting up API keys (e.g., `OPENAI_API_KEY`, `GEMINI_API_KEY`) in a `.env` file and for a full list of available models.
 
-To use the voice feature (`--voice True`), you will need to install extra dependencies:
+To use the voice feature (`--voice`), you will need to install extra dependencies:
 ```bash
 pip install "speechrecognition>=3.10" "pyttsx3>=2.90"
 # Note: speechrecognition may require PyAudio, which might have system-level dependencies.

patchllm-0.2.2/README.md

@@ -0,0 +1,90 @@
+<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 a command-line tool that lets you flexibly build LLM context from your codebase using glob patterns, URLs, and keyword searches. It then automatically applies file edits directly from the LLM's response.
+
+## Usage
+PatchLLM is designed to be used directly from your terminal. The core workflow is to define a **scope** of files, provide a **task**, and choose an **action** (like patching files directly).
+
+### 1. Initialize a Scope
+The easiest way to get started is to run the interactive initializer. This will create a `scopes.py` file for you, which holds your saved scopes.
+
+```bash
+patchllm --init
+```
+
+This will guide you through creating your first scope, including setting a base path and file patterns. You can add multiple scopes to this file for different projects or tasks.
+
+A generated `scopes.py` might look like this:
+```python
+# scopes.py
+scopes = {
+    "default": {
+        "path": ".",
+        "include_patterns": ["**/*.py"],
+        "exclude_patterns": ["**/tests/*", "venv/*"],
+        "urls": ["https://docs.python.org/3/library/argparse.html"]
+    },
+    "docs": {
+        "path": "./docs",
+        "include_patterns": ["**/*.md"],
+    }
+}
+```
+
+### 2. Run a Task
+Use the `patchllm` command with a scope, a task, and an action flag like `--patch` (`-p`).
+
+```bash
+# Apply a change using the 'default' scope and the --patch action
+patchllm -s default -t "Add type hints to the main function in main.py" -p
+```
+
+The tool will then:
+1.  Build a context from the files and URLs matching your `default` scope.
+2.  Send the context and your task to the configured LLM.
+3.  Parse the response and automatically write the changes to the relevant files.
+
+### All Commands & Options
+
+#### Core Patching Flow
+*   `-s, --scope <name>`: Name of the scope to use from your `scopes.py` file.
+*   `-t, --task "<instruction>"`: The task instruction for the LLM.
+*   `-p, --patch`: Query the LLM and directly apply the file updates from the response. **This is the main action flag.**
+
+#### Scope Management
+*   `-i, --init`: Create a new scope interactively.
+*   `-sl, --list-scopes`: List all available scopes from your `scopes.py` file.
+*   `-ss, --show-scope <name>`: Display the settings for a specific scope.
+
+#### I/O & Context Management
+*   `-co, --context-out [filename]`: Export the generated context to a file (defaults to `context.md`) instead of running a task.
+*   `-ci, --context-in <filename>`: Use a previously saved context file as input for a task.
+*   `-tf, --to-file [filename]`: Send the LLM response to a file (defaults to `response.md`) instead of patching directly.
+*   `-tc, --to-clipboard`: Copy the LLM response to the clipboard.
+*   `-ff, --from-file <filename>`: Apply patches from a local file instead of an LLM response.
+*   `-fc, --from-clipboard`: Apply patches directly from your clipboard content.
+
+#### General Options
+*   `--model <model_name>`: Specify a different model (e.g., `gpt-4o`). Defaults to `gemini/gemini-1.5-flash`.
+*   `--voice`: Enable voice recognition to provide the task instruction.
+
+### Setup
+
+PatchLLM uses [LiteLLM](https://github.com/BerriAI/litellm) under the hood. Please refer to their documentation for setting up API keys (e.g., `OPENAI_API_KEY`, `GEMINI_API_KEY`) in a `.env` file and for a full list of available models.
+
+To use the voice feature (`--voice`), you will need to install extra dependencies:
+```bash
+pip install "speechrecognition>=3.10" "pyttsx3>=2.90"
+# Note: speechrecognition may require PyAudio, which might have system-level dependencies.
+```
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.

{patchllm-0.2.1 → patchllm-0.2.2}/patchllm/context.py

@@ -175,23 +175,23 @@ def fetch_and_process_urls(urls: list[str]) -> str:
 
 # --- Main Context Building Function ---
 
-def build_context(config: dict) -> dict | None:
+def build_context(scope: dict) -> dict | None:
     """
-    Builds the context string from files specified in the config.
+    Builds the context string from files specified in the scope.
 
     Args:
-        config (dict): The configuration for file searching.
+        scope (dict): The scope for file searching.
 
     Returns:
         dict: A dictionary with the source tree and formatted context, or None.
     """
-    base_path = Path(config.get("path", ".")).resolve()
+    base_path = Path(scope.get("path", ".")).resolve()
     
-    include_patterns = config.get("include_patterns", [])
-    exclude_patterns = config.get("exclude_patterns", [])
-    exclude_extensions = config.get("exclude_extensions", DEFAULT_EXCLUDE_EXTENSIONS)
-    search_words = config.get("search_words", [])
-    urls = config.get("urls", [])
+    include_patterns = scope.get("include_patterns", [])
+    exclude_patterns = scope.get("exclude_patterns", [])
+    exclude_extensions = scope.get("exclude_extensions", DEFAULT_EXCLUDE_EXTENSIONS)
+    search_words = scope.get("search_words", [])
+    urls = scope.get("urls", [])
 
     # Step 1: Find files
     relevant_files = find_files(base_path, include_patterns, exclude_patterns)

patchllm-0.2.2/patchllm/main.py

@@ -0,0 +1,326 @@
+import textwrap
+import argparse
+import litellm
+import pprint
+import os
+from dotenv import load_dotenv
+from rich.console import Console
+from rich.panel import Panel
+
+from .context import build_context
+from .parser import paste_response
+from .utils import load_from_py_file
+
+console = Console()
+
+# --- Core Functions ---
+
+def collect_context(scope_name, scopes):
+    """Builds the code context from a provided scope dictionary."""
+    console.print("\n--- Building Code Context... ---", style="bold")
+    if not scopes:
+        raise FileNotFoundError("Could not find a 'scopes.py' file.")
+    selected_scope = scopes.get(scope_name)
+    if selected_scope is None:
+        raise KeyError(f"Context scope '{scope_name}' not found in provided scopes file.")
+    
+    context_object = build_context(selected_scope)
+    if context_object:
+        tree, context = context_object.values()
+        console.print("--- Context Building Finished. The following files were extracted ---", style="bold")
+        console.print(tree)
+        return context
+    else:
+        console.print("--- Context Building Failed (No files found) ---", style="yellow")
+        return None
+
+def run_llm_query(task_instructions, model_name, history, context=None):
+    """
+    Assembles the final prompt, sends it to the LLM, and returns the response.
+    """
+    console.print("\n--- Sending Prompt to LLM... ---", style="bold")
+    final_prompt = task_instructions
+    if context:
+        final_prompt = f"{context}\n\n{task_instructions}"
+    
+    history.append({"role": "user", "content": final_prompt})
+    
+    try:
+        with console.status("[bold cyan]Waiting for LLM response...", spinner="dots"):
+            response = litellm.completion(model=model_name, messages=history)
+        
+        assistant_response_content = response.choices[0].message.content
+        history.append({"role": "assistant", "content": assistant_response_content})
+
+        if not assistant_response_content or not assistant_response_content.strip():
+            console.print("⚠️  Response is empty. Nothing to process.", style="yellow")
+            return None
+        
+        return assistant_response_content
+
+    except Exception as e:
+        history.pop() # Keep history clean on error
+        raise RuntimeError(f"An error occurred while communicating with the LLM via litellm: {e}") from e
+
+def write_to_file(file_path, content):
+    """Utility function to write content to a file."""
+    console.print(f"Writing to {file_path}..", style="cyan")
+    try:
+        with open(file_path, "w", encoding="utf-8") as file:
+            file.write(content)
+        console.print(f'✅ Content saved to {file_path}', style="green")
+    except Exception as e:
+        raise RuntimeError(f"Failed to write to file {file_path}: {e}") from e
+
+def read_from_file(file_path):
+    """Utility function to read and return the content of a file."""
+    console.print(f"Importing from {file_path}..", style="cyan")
+    try:
+        with open(file_path, "r", encoding="utf-8") as file:
+            content = file.read()
+            console.print("✅ Finished reading file.", style="green")
+            return content
+    except Exception as e:
+        raise RuntimeError(f"Failed to read from file {file_path}: {e}") from e
+
+def create_new_scope(scopes, scopes_file_str):
+    """Interactively creates a new scope and saves it to the specified scopes file."""
+    console.print(f"\n--- Creating a new scope in '{scopes_file_str}' ---", style="bold")
+    
+    try:
+        name = console.input("[bold]Enter a name for the new scope: [/]").strip()
+        if not name:
+            console.print("❌ Scope name cannot be empty.", style="red")
+            return
+
+        if name in scopes:
+            overwrite = console.input(f"Scope '[bold]{name}[/]' already exists. Overwrite? (y/n): ").lower()
+            if overwrite not in ['y', 'yes']:
+                console.print("Operation cancelled.", style="yellow")
+                return
+
+        path = console.input("[bold]Enter the base path[/] (e.g., '.' for current directory): ").strip() or "."
+        
+        console.print("\nEnter comma-separated glob patterns for files to include.")
+        include_raw = console.input('[cyan]> (e.g., "[bold]**/*.py, src/**/*.js[/]"): [/]').strip()
+        include_patterns = [p.strip() for p in include_raw.split(',') if p.strip()]
+
+        console.print("\nEnter comma-separated glob patterns for files to exclude (optional).")
+        exclude_raw = console.input('[cyan]> (e.g., "[bold]**/tests/*, venv/*[/]"): [/]').strip()
+        exclude_patterns = [p.strip() for p in exclude_raw.split(',') if p.strip()]
+        
+        new_scope_data = {
+            "path": path,
+            "include_patterns": include_patterns,
+            "exclude_patterns": exclude_patterns
+        }
+
+        scopes[name] = new_scope_data
+
+        with open(scopes_file_str, "w", encoding="utf-8") as f:
+            f.write("# scopes.py\n")
+            f.write("scopes = ")
+            f.write(pprint.pformat(scopes, indent=4))
+            f.write("\n")
+        
+        console.print(f"\n✅ Successfully created and saved scope '[bold]{name}[/]' in '[bold]{scopes_file_str}[/]'.", style="green")
+
+    except KeyboardInterrupt:
+        console.print("\n\n⚠️ Scope creation cancelled by user.", style="yellow")
+        return
+
+def main():
+    """
+    Main entry point for the patchllm command-line tool.
+    """
+    load_dotenv()
+    
+    scopes_file_path = os.getenv("PATCHLLM_SCOPES_FILE", "./scopes.py")
+
+    parser = argparse.ArgumentParser(
+        description="A CLI tool to apply code changes using an LLM.",
+        formatter_class=argparse.RawTextHelpFormatter
+    )
+
+    # --- Group: Core Patching Flow ---
+    patch_group = parser.add_argument_group('Core Patching Flow')
+    patch_group.add_argument("-s", "--scope", type=str, default=None, help="Name of the scope to use from the scopes file.")
+    patch_group.add_argument("-t", "--task", type=str, default=None, help="The task instructions to guide the assistant.")
+    patch_group.add_argument("-p", "--patch", action="store_true", help="Query the LLM and directly apply the file updates from the response. Requires --task.")
+
+    # --- Group: Scope Management ---
+    scope_group = parser.add_argument_group('Scope Management')
+    scope_group.add_argument("-i", "--init", action="store_true", help="Create a new scope interactively.")
+    scope_group.add_argument("-sl", "--list-scopes", action="store_true", help="List all available scopes from the scopes file and exit.")
+    scope_group.add_argument("-ss", "--show-scope", type=str, help="Display the settings for a specific scope and exit.")
+
+    # --- Group: I/O Utils---
+    code_io = parser.add_argument_group('Code I/O')
+    code_io.add_argument("-co", "--context-out", nargs='?', const="context.md", default=None, help="Export the generated context to a file. Defaults to 'context.md'.")
+    code_io.add_argument("-ci", "--context-in", type=str, default=None, help="Import a previously saved context from a file.")
+    code_io.add_argument("-tf", "--to-file", nargs='?', const="response.md", default=None, help="Query the LLM and save the response to a file. Requires --task. Defaults to 'response.md'.")
+    code_io.add_argument("-tc", "--to-clipboard", action="store_true", help="Query the LLM and save the response to the clipboard. Requires --task.")
+    code_io.add_argument("-ff", "--from-file", type=str, default=None, help="Apply code updates directly from a file.")
+    code_io.add_argument("-fc", "--from-clipboard", action="store_true", help="Apply code updates directly from the clipboard.")
+    
+    # --- Group: General Options ---
+    options_group = parser.add_argument_group('General Options')
+    options_group.add_argument("-m", "--model", type=str, default="gemini/gemini-2.5-flash", help="Model name to use (e.g., 'gpt-4o', 'claude-3-sonnet').")
+    options_group.add_argument("-v", "--voice", type=str, default="False", help="Enable voice interaction for providing task instructions. (True/False)")
+    
+    args = parser.parse_args()
+
+    try:
+        scopes = load_from_py_file(scopes_file_path, "scopes")
+    except FileNotFoundError:
+        scopes = {}
+        if not any([args.init, args.list_scopes, args.show_scope]):
+             console.print(f"⚠️  Scope file '{scopes_file_path}' not found. You can create one with the --init flag.", style="yellow")
+
+
+    if args.list_scopes:
+        console.print(f"Available scopes in '[bold]{scopes_file_path}[/]':", style="bold")
+        if not scopes:
+            console.print(f"  -> No scopes found or '{scopes_file_path}' is missing.")
+        else:
+            for scope_name in scopes:
+                console.print(f"  - {scope_name}")
+        return
+
+    if args.show_scope:
+        scope_name = args.show_scope
+        if not scopes:
+            console.print(f"⚠️  Scope file '{scopes_file_path}' not found or is empty.", style="yellow")
+            return
+        
+        scope_data = scopes.get(scope_name)
+        if scope_data:
+            pretty_scope = pprint.pformat(scope_data, indent=2)
+            console.print(
+                Panel(
+                    pretty_scope,
+                    title=f"[bold cyan]Scope: '{scope_name}'[/]",
+                    subtitle=f"[dim]from {scopes_file_path}[/dim]",
+                    border_style="blue"
+                )
+            )
+        else:
+            console.print(f"❌ Scope '[bold]{scope_name}[/]' not found in '{scopes_file_path}'.", style="red")
+        return
+
+    if args.init:
+        create_new_scope(scopes, scopes_file_path)
+        return
+
+    if args.from_clipboard:
+        try:
+            import pyperclip
+            updates = pyperclip.paste()
+            if updates:
+                console.print("--- Parsing updates from clipboard ---", style="bold")
+                paste_response(updates)
+            else:
+                console.print("⚠️ Clipboard is empty. Nothing to parse.", style="yellow")
+        except ImportError:
+            console.print("❌ The 'pyperclip' library is required for clipboard functionality.", style="red")
+            console.print("Please install it using: pip install pyperclip", style="cyan")
+        except Exception as e:
+            console.print(f"❌ An error occurred while reading from the clipboard: {e}", style="red")
+        return
+
+    if args.from_file:
+        updates = read_from_file(args.from_file)
+        paste_response(updates)
+        return
+        
+    system_prompt = textwrap.dedent("""
+        You are an expert pair programmer. Your purpose is to help users by modifying files based on their instructions.
+        Follow these rules strictly:
+        Your output should be a single file including all the updated files. For each file-block:
+        1. Only include code for files that need to be updated / edited.
+        2. For updated files, do not exclude any code even if it is unchanged code; assume the file code will be copy-pasted full in the file.
+        3. Do not include verbose inline comments explaining what every small change does. Try to keep comments concise but informative, if any.
+        4. Only update the relevant parts of each file relative to the provided task; do not make irrelevant edits even if you notice areas of improvements elsewhere.
+        5. Do not use diffs.
+        6. Make sure each file-block is returned in the following exact format. No additional text, comments, or explanations should be outside these blocks.
+        Expected format for a modified or new file:
+        <file_path:/absolute/path/to/your/file.py>
+        ```python
+        # The full, complete content of /absolute/path/to/your/file.py goes here.
+        def example_function():
+            return "Hello, World!"
+        ```
+    """)
+    history = [{"role": "system", "content": system_prompt}]
+    
+    context = None
+    if args.voice not in ["False", "false"]:
+        from .listener import listen, speak
+        speak("Say your task instruction.")
+        task = listen()
+        if not task:
+            speak("No instruction heard. Exiting.")
+            return
+        speak(f"You said: {task}. Should I proceed?")
+        confirm = listen()
+        if confirm and "yes" in confirm.lower():
+            if not args.scope:
+                parser.error("A --scope name is required when using --voice.")
+            context = collect_context(args.scope, scopes)
+            llm_response = run_llm_query(task, args.model, history, context)
+            if llm_response:
+                paste_response(llm_response)
+                speak("Changes applied.")
+        else:
+            speak("Cancelled.")
+        return
+
+    # --- Main LLM Task Logic ---
+    if args.task:
+        action_flags = [args.patch, args.to_file is not None, args.to_clipboard]
+        if sum(action_flags) == 0:
+            parser.error("A task was provided, but no action was specified. Use --patch, --to-file, or --to-clipboard.")
+        if sum(action_flags) > 1:
+            parser.error("Please specify only one action: --patch, --to-file, or --to-clipboard.")
+
+        if args.context_in:
+            context = read_from_file(args.context_in)
+        else:
+            if not args.scope:
+                parser.error("A --scope name is required to build context for a task.")
+            context = collect_context(args.scope, scopes)
+            if context and args.context_out:
+                write_to_file(args.context_out, context)
+
+        if not context:
+            console.print("Proceeding with task but without any file context.", style="yellow")
+
+        llm_response = run_llm_query(args.task, args.model, history, context)
+
+        if llm_response:
+            if args.patch:
+                console.print("\n--- Updating files ---", style="bold")
+                paste_response(llm_response)
+                console.print("--- File Update Process Finished ---", style="bold")
+            
+            elif args.to_file is not None:
+                write_to_file(args.to_file, llm_response)
+
+            elif args.to_clipboard:
+                try:
+                    import pyperclip
+                    pyperclip.copy(llm_response)
+                    console.print("✅ Copied LLM response to clipboard.", style="green")
+                except ImportError:
+                    console.print("❌ The 'pyperclip' library is required for clipboard functionality.", style="red")
+                    console.print("Please install it using: pip install pyperclip", style="cyan")
+                except Exception as e:
+                    console.print(f"❌ An error occurred while copying to the clipboard: {e}", style="red")
+    
+    elif args.scope and args.context_out:
+        context = collect_context(args.scope, scopes)
+        if context:
+            write_to_file(args.context_out, context)
+
+if __name__ == "__main__":
+    main()

{patchllm-0.2.1 → patchllm-0.2.2}/patchllm.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchllm
-Version: 0.2.1
+Version: 0.2.2
 Summary: Lightweight tool to manage contexts and update code with LLMs
 Author: nassimberrada
 License: MIT License
@@ -49,21 +49,21 @@ Dynamic: license-file
 PatchLLM is a command-line tool that lets you flexibly build LLM context from your codebase using glob patterns, URLs, and keyword searches. It then automatically applies file edits directly from the LLM's response.
 
 ## Usage
-PatchLLM is designed to be used directly from your terminal.
+PatchLLM is designed to be used directly from your terminal. The core workflow is to define a **scope** of files, provide a **task**, and choose an **action** (like patching files directly).
 
-### 1. Initialize a Configuration
-The easiest way to get started is to run the interactive initializer. This will create a `configs.py` file for you.
+### 1. Initialize a Scope
+The easiest way to get started is to run the interactive initializer. This will create a `scopes.py` file for you, which holds your saved scopes.
 
 ```bash
 patchllm --init
 ```
 
-This will guide you through creating your first context configuration, including setting a base path and file patterns. You can add multiple configurations to this file.
+This will guide you through creating your first scope, including setting a base path and file patterns. You can add multiple scopes to this file for different projects or tasks.
 
-A generated `configs.py` might look like this:
+A generated `scopes.py` might look like this:
 ```python
-# configs.py
-configs = {
+# scopes.py
+scopes = {
     "default": {
         "path": ".",
         "include_patterns": ["**/*.py"],
@@ -78,45 +78,47 @@ configs = {
 ```
 
 ### 2. Run a Task
-Use the `patchllm` command with a configuration name and a task instruction.
+Use the `patchllm` command with a scope, a task, and an action flag like `--patch` (`-p`).
 
 ```bash
-# Apply a change using the 'default' configuration
-patchllm --config default --task "Add type hints to the main function in main.py"
+# Apply a change using the 'default' scope and the --patch action
+patchllm -s default -t "Add type hints to the main function in main.py" -p
 ```
 
 The tool will then:
-1.  Build a context from the files and URLs matching your configuration.
+1.  Build a context from the files and URLs matching your `default` scope.
 2.  Send the context and your task to the configured LLM.
 3.  Parse the response and automatically write the changes to the relevant files.
 
 ### All Commands & Options
 
-#### Configuration Management
-*   `--init`: Create a new configuration interactively.
-*   `--list-configs`: List all available configurations from your `configs.py`.
-*   `--show-config <name>`: Display the settings for a specific configuration.
+#### Core Patching Flow
+*   `-s, --scope <name>`: Name of the scope to use from your `scopes.py` file.
+*   `-t, --task "<instruction>"`: The task instruction for the LLM.
+*   `-p, --patch`: Query the LLM and directly apply the file updates from the response. **This is the main action flag.**
 
-#### Core Task Execution
-*   `--config <name>`: The name of the configuration to use for building context.
-*   `--task "<instruction>"`: The task instruction for the LLM.
-*   `--model <model_name>`: Specify a different model (e.g., `claude-3-opus`). Defaults to `gemini/gemini-1.5-flash`.
+#### Scope Management
+*   `-i, --init`: Create a new scope interactively.
+*   `-sl, --list-scopes`: List all available scopes from your `scopes.py` file.
+*   `-ss, --show-scope <name>`: Display the settings for a specific scope.
 
-#### Context Handling
-*   `--context-out [filename]`: Save the generated context to a file (defaults to `context.md`) instead of sending it to the LLM.
-*   `--context-in <filename>`: Use a previously saved context file directly, skipping context generation.
-*   `--update False`: A flag to prevent sending the prompt to the LLM. Useful when you only want to generate and save the context with `--context-out`.
+#### I/O & Context Management
+*   `-co, --context-out [filename]`: Export the generated context to a file (defaults to `context.md`) instead of running a task.
+*   `-ci, --context-in <filename>`: Use a previously saved context file as input for a task.
+*   `-tf, --to-file [filename]`: Send the LLM response to a file (defaults to `response.md`) instead of patching directly.
+*   `-tc, --to-clipboard`: Copy the LLM response to the clipboard.
+*   `-ff, --from-file <filename>`: Apply patches from a local file instead of an LLM response.
+*   `-fc, --from-clipboard`: Apply patches directly from your clipboard content.
 
-#### Alternative Inputs
-*   `--from-file <filename>`: Apply file patches directly from a local file instead of from an LLM response.
-*   `--from-clipboard`: Apply file patches directly from your clipboard content.
-*   `--voice True`: Use voice recognition to provide the task instruction. Requires extra dependencies.
+#### General Options
+*   `--model <model_name>`: Specify a different model (e.g., `gpt-4o`). Defaults to `gemini/gemini-1.5-flash`.
+*   `--voice`: Enable voice recognition to provide the task instruction.
 
 ### Setup
 
 PatchLLM uses [LiteLLM](https://github.com/BerriAI/litellm) under the hood. Please refer to their documentation for setting up API keys (e.g., `OPENAI_API_KEY`, `GEMINI_API_KEY`) in a `.env` file and for a full list of available models.
 
-To use the voice feature (`--voice True`), you will need to install extra dependencies:
+To use the voice feature (`--voice`), you will need to install extra dependencies:
 ```bash
 pip install "speechrecognition>=3.10" "pyttsx3>=2.90"
 # Note: speechrecognition may require PyAudio, which might have system-level dependencies.

{patchllm-0.2.1 → patchllm-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "patchllm"
-version = "0.2.1"
+version = "0.2.2"
 description = "Lightweight tool to manage contexts and update code with LLMs"
 readme = "README.md"
 requires-python = ">=3.8"

patchllm-0.2.1/README.md

@@ -1,88 +0,0 @@
-<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 a command-line tool that lets you flexibly build LLM context from your codebase using glob patterns, URLs, and keyword searches. It then automatically applies file edits directly from the LLM's response.
-
-## Usage
-PatchLLM is designed to be used directly from your terminal.
-
-### 1. Initialize a Configuration
-The easiest way to get started is to run the interactive initializer. This will create a `configs.py` file for you.
-
-```bash
-patchllm --init
-```
-
-This will guide you through creating your first context configuration, including setting a base path and file patterns. You can add multiple configurations to this file.
-
-A generated `configs.py` might look like this:
-```python
-# configs.py
-configs = {
-    "default": {
-        "path": ".",
-        "include_patterns": ["**/*.py"],
-        "exclude_patterns": ["**/tests/*", "venv/*"],
-        "urls": ["https://docs.python.org/3/library/argparse.html"]
-    },
-    "docs": {
-        "path": "./docs",
-        "include_patterns": ["**/*.md"],
-    }
-}
-```
-
-### 2. Run a Task
-Use the `patchllm` command with a configuration name and a task instruction.
-
-```bash
-# Apply a change using the 'default' configuration
-patchllm --config default --task "Add type hints to the main function in main.py"
-```
-
-The tool will then:
-1.  Build a context from the files and URLs matching your configuration.
-2.  Send the context and your task to the configured LLM.
-3.  Parse the response and automatically write the changes to the relevant files.
-
-### All Commands & Options
-
-#### Configuration Management
-*   `--init`: Create a new configuration interactively.
-*   `--list-configs`: List all available configurations from your `configs.py`.
-*   `--show-config <name>`: Display the settings for a specific configuration.
-
-#### Core Task Execution
-*   `--config <name>`: The name of the configuration to use for building context.
-*   `--task "<instruction>"`: The task instruction for the LLM.
-*   `--model <model_name>`: Specify a different model (e.g., `claude-3-opus`). Defaults to `gemini/gemini-1.5-flash`.
-
-#### Context Handling
-*   `--context-out [filename]`: Save the generated context to a file (defaults to `context.md`) instead of sending it to the LLM.
-*   `--context-in <filename>`: Use a previously saved context file directly, skipping context generation.
-*   `--update False`: A flag to prevent sending the prompt to the LLM. Useful when you only want to generate and save the context with `--context-out`.
-
-#### Alternative Inputs
-*   `--from-file <filename>`: Apply file patches directly from a local file instead of from an LLM response.
-*   `--from-clipboard`: Apply file patches directly from your clipboard content.
-*   `--voice True`: Use voice recognition to provide the task instruction. Requires extra dependencies.
-
-### Setup
-
-PatchLLM uses [LiteLLM](https://github.com/BerriAI/litellm) under the hood. Please refer to their documentation for setting up API keys (e.g., `OPENAI_API_KEY`, `GEMINI_API_KEY`) in a `.env` file and for a full list of available models.
-
-To use the voice feature (`--voice True`), you will need to install extra dependencies:
-```bash
-pip install "speechrecognition>=3.10" "pyttsx3>=2.90"
-# Note: speechrecognition may require PyAudio, which might have system-level dependencies.
-```
-
-## License
-
-This project is licensed under the MIT License. See the `LICENSE` file for details.

patchllm-0.2.1/patchllm/main.py

@@ -1,286 +0,0 @@
-import textwrap
-import argparse
-import litellm
-import pprint
-import os
-from dotenv import load_dotenv
-from rich.console import Console
-from rich.panel import Panel
-
-from .context import build_context
-from .parser import paste_response
-from .utils import load_from_py_file
-
-console = Console()
-
-# --- Core Functions ---
-
-def collect_context(config_name, configs):
-    """Builds the code context from a provided configuration dictionary."""
-    console.print("\n--- Building Code Context... ---", style="bold")
-    if not configs:
-        raise FileNotFoundError("Could not find a 'configs.py' file.")
-    selected_config = configs.get(config_name)
-    if selected_config is None:
-        raise KeyError(f"Context config '{config_name}' not found in provided configs file.")
-    
-    context_object = build_context(selected_config)
-    if context_object:
-        tree, context = context_object.values()
-        console.print("--- Context Building Finished. The following files were extracted ---", style="bold")
-        console.print(tree)
-        return context
-    else:
-        console.print("--- Context Building Failed (No files found) ---", style="yellow")
-        return None
-
-def run_update(task_instructions, model_name, history, context=None):
-    """
-    Assembles the final prompt, sends it to the LLM, and applies file updates.
-    """
-    console.print("\n--- Sending Prompt to LLM... ---", style="bold")
-    final_prompt = task_instructions
-    if context:
-        final_prompt = f"{context}\n\n{task_instructions}"
-    
-    history.append({"role": "user", "content": final_prompt})
-    
-    try:
-        with console.status("[bold cyan]Waiting for LLM response...", spinner="dots"):
-            response = litellm.completion(model=model_name, messages=history)
-        
-        assistant_response_content = response.choices[0].message.content
-        history.append({"role": "assistant", "content": assistant_response_content})
-
-        if not assistant_response_content or not assistant_response_content.strip():
-            console.print("⚠️  Response is empty. Nothing to paste.", style="yellow")
-            return
-        
-        console.print("\n--- Updating files ---", style="bold")
-        paste_response(assistant_response_content)
-        console.print("--- File Update Process Finished ---", style="bold")
-
-    except Exception as e:
-        history.pop() # Keep history clean on error
-        raise RuntimeError(f"An error occurred while communicating with the LLM via litellm: {e}") from e
-
-def write_context_to_file(file_path, context):
-    """Utility function to write the context to a file."""
-    console.print("Exporting context..", style="cyan")
-    with open(file_path, "w", encoding="utf-8") as file:
-        file.write(context)
-    console.print(f'✅ Context exported to {file_path.split("/")[-1]}', style="green")
-
-def read_from_file(file_path):
-    """Utility function to read and return the content of a file."""
-    console.print(f"Importing from {file_path}..", style="cyan")
-    try:
-        with open(file_path, "r", encoding="utf-8") as file:
-            content = file.read()
-            console.print("✅ Finished reading file.", style="green")
-            return content
-    except Exception as e:
-        raise RuntimeError(f"Failed to read from file {file_path}: {e}") from e
-
-def create_new_config(configs, configs_file_str):
-    """Interactively creates a new configuration and saves it to the specified configs file."""
-    console.print(f"\n--- Creating a new configuration in '{configs_file_str}' ---", style="bold")
-    
-    try:
-        name = console.input("[bold]Enter a name for the new configuration: [/]").strip()
-        if not name:
-            console.print("❌ Configuration name cannot be empty.", style="red")
-            return
-
-        if name in configs:
-            overwrite = console.input(f"Configuration '[bold]{name}[/]' already exists. Overwrite? (y/n): ").lower()
-            if overwrite not in ['y', 'yes']:
-                console.print("Operation cancelled.", style="yellow")
-                return
-
-        path = console.input("[bold]Enter the base path[/] (e.g., '.' for current directory): ").strip() or "."
-        
-        console.print("\nEnter comma-separated glob patterns for files to include.")
-        include_raw = console.input('[cyan]> (e.g., "[bold]**/*.py, src/**/*.js[/]"): [/]').strip()
-        include_patterns = [p.strip() for p in include_raw.split(',') if p.strip()]
-
-        console.print("\nEnter comma-separated glob patterns for files to exclude (optional).")
-        exclude_raw = console.input('[cyan]> (e.g., "[bold]**/tests/*, venv/*[/]"): [/]').strip()
-        exclude_patterns = [p.strip() for p in exclude_raw.split(',') if p.strip()]
-        
-        console.print("\nEnter comma-separated URLs to include as context (optional).")
-        urls_raw = console.input('[cyan]> (e.g., "[bold]https://docs.example.com, ...[/]"): [/]').strip()
-        urls = [u.strip() for u in urls_raw.split(',') if u.strip()]
-
-        new_config_data = {
-            "path": path,
-            "include_patterns": include_patterns,
-            "exclude_patterns": exclude_patterns,
-            "urls": urls,
-        }
-
-        configs[name] = new_config_data
-
-        with open(configs_file_str, "w", encoding="utf-8") as f:
-            f.write("# configs.py\n")
-            f.write("configs = ")
-            f.write(pprint.pformat(configs, indent=4))
-            f.write("\n")
-        
-        console.print(f"\n✅ Successfully created and saved configuration '[bold]{name}[/]' in '[bold]{configs_file_str}[/]'.", style="green")
-
-    except KeyboardInterrupt:
-        console.print("\n\n⚠️ Configuration creation cancelled by user.", style="yellow")
-        return
-
-def main():
-    """
-    Main entry point for the patchllm command-line tool.
-    """
-    load_dotenv()
-    
-    configs_file_path = os.getenv("PATCHLLM_CONFIGS_FILE", "./configs.py")
-
-    parser = argparse.ArgumentParser(
-        description="A CLI tool to apply code changes using an LLM.",
-        formatter_class=argparse.RawTextHelpFormatter
-    )
-
-    parser.add_argument("-i", "--init", action="store_true", help="Create a new configuration interactively.")
-    
-    parser.add_argument("-c", "--config", type=str, default=None, help="Name of the config key to use from the configs file.")
-    parser.add_argument("-t", "--task", type=str, default=None, help="The task instructions to guide the assistant.")
-    
-    parser.add_argument("-co", "--context-out", nargs='?', const="context.md", default=None, help="Export the generated context to a file. Defaults to 'context.md'.")
-    parser.add_argument("-ci", "--context-in", type=str, default=None, help="Import a previously saved context from a file.")
-    
-    parser.add_argument("-u", "--update", type=str, default="True", help="Control whether to send the context to the LLM for updates. (True/False)")
-    parser.add_argument("-ff", "--from-file", type=str, default=None, help="Apply updates directly from a file instead of the LLM.")
-    parser.add_argument("-fc", "--from-clipboard", action="store_true", help="Apply updates directly from the clipboard.")
-    
-    parser.add_argument("--model", type=str, default="gemini/gemini-1.5-flash", help="Model name to use (e.g., 'gpt-4o', 'claude-3-sonnet').")
-    parser.add_argument("--voice", type=str, default="False", help="Enable voice interaction for providing task instructions. (True/False)")
-    
-    parser.add_argument("--list-configs", action="store_true", help="List all available configurations from the configs file and exit.")
-    parser.add_argument("--show-config", type=str, help="Display the settings for a specific configuration and exit.")
-    
-    args = parser.parse_args()
-
-    try:
-        configs = load_from_py_file(configs_file_path, "configs")
-    except FileNotFoundError:
-        configs = {}
-        if not any([args.init, args.list_configs, args.show_config]):
-             console.print(f"⚠️  Config file '{configs_file_path}' not found. You can create one with the --init flag.", style="yellow")
-
-
-    if args.list_configs:
-        console.print(f"Available configurations in '[bold]{configs_file_path}[/]':", style="bold")
-        if not configs:
-            console.print(f"  -> No configurations found or '{configs_file_path}' is missing.")
-        else:
-            for config_name in configs:
-                console.print(f"  - {config_name}")
-        return
-
-    if args.show_config:
-        config_name = args.show_config
-        if not configs:
-            console.print(f"⚠️  Config file '{configs_file_path}' not found or is empty.", style="yellow")
-            return
-        
-        config_data = configs.get(config_name)
-        if config_data:
-            pretty_config = pprint.pformat(config_data, indent=2)
-            console.print(
-                Panel(
-                    pretty_config,
-                    title=f"[bold cyan]Configuration: '{config_name}'[/]",
-                    subtitle=f"[dim]from {configs_file_path}[/dim]",
-                    border_style="blue"
-                )
-            )
-        else:
-            console.print(f"❌ Configuration '[bold]{config_name}[/]' not found in '{configs_file_path}'.", style="red")
-        return
-
-    if args.init:
-        create_new_config(configs, configs_file_path)
-        return
-
-    if args.from_clipboard:
-        try:
-            import pyperclip
-            updates = pyperclip.paste()
-            if updates:
-                console.print("--- Parsing updates from clipboard ---", style="bold")
-                paste_response(updates)
-            else:
-                console.print("⚠️ Clipboard is empty. Nothing to parse.", style="yellow")
-        except ImportError:
-            console.print("❌ The 'pyperclip' library is required for clipboard functionality.", style="red")
-            console.print("Please install it using: pip install pyperclip", style="cyan")
-        except Exception as e:
-            console.print(f"❌ An error occurred while reading from the clipboard: {e}", style="red")
-        return
-
-    if args.from_file:
-        updates = read_from_file(args.from_file)
-        paste_response(updates)
-        return
-        
-    system_prompt = textwrap.dedent("""
-        You are an expert pair programmer. Your purpose is to help users by modifying files based on their instructions.
-        Follow these rules strictly:
-        Your output should be a single file including all the updated files. For each file-block:
-        1. Only include code for files that need to be updated / edited.
-        2. For updated files, do not exclude any code even if it is unchanged code; assume the file code will be copy-pasted full in the file.
-        3. Do not include verbose inline comments explaining what every small change does. Try to keep comments concise but informative, if any.
-        4. Only update the relevant parts of each file relative to the provided task; do not make irrelevant edits even if you notice areas of improvements elsewhere.
-        5. Do not use diffs.
-        6. Make sure each file-block is returned in the following exact format. No additional text, comments, or explanations should be outside these blocks.
-        Expected format for a modified or new file:
-        <file_path:/absolute/path/to/your/file.py>
-        ```python
-        # The full, complete content of /absolute/path/to/your/file.py goes here.
-        def example_function():
-            return "Hello, World!"
-        ```
-    """)
-    history = [{"role": "system", "content": system_prompt}]
-    
-    context = None
-    if args.voice not in ["False", "false"]:
-        from .listener import listen, speak
-        speak("Say your task instruction.")
-        task = listen()
-        if not task:
-            speak("No instruction heard. Exiting.")
-            return
-        speak(f"You said: {task}. Should I proceed?")
-        confirm = listen()
-        if confirm and "yes" in confirm.lower():
-            context = collect_context(args.config, configs)
-            run_update(task, args.model, history, context)
-            speak("Changes applied.")
-        else:
-            speak("Cancelled.")
-        return
-
-    if args.context_in:
-        context = read_from_file(args.context_in)
-    else:
-        if not args.config:
-            parser.error("A --config name is required unless using other flags like --context-in or other utility flags.")
-        context = collect_context(args.config, configs)
-        if context and args.context_out:
-            write_context_to_file(args.context_out, context)
-
-    if args.update not in ["False", "false"]:
-        if not args.task:
-            parser.error("The --task argument is required to generate updates.")
-        if context:
-            run_update(args.task, args.model, history, context)
-
-if __name__ == "__main__":
-    main()