patchpal 0.4.5__py3-none-any.whl → 0.6.0__py3-none-any.whl

patchpal/__init__.py

@@ -1,6 +1,6 @@
 """PatchPal - An open-source Claude Code clone implemented purely in Python."""
 
-__version__ = "0.4.5"
+__version__ = "0.6.0"
 
 from patchpal.agent import create_agent
 from patchpal.tools import (

patchpal/agent.py

@@ -811,12 +811,17 @@ def _apply_prompt_caching(messages: List[Dict[str, Any]], model_id: str) -> List
 class PatchPalAgent:
     """Simple agent that uses LiteLLM for tool calling."""
 
-    def __init__(self, model_id: str = "anthropic/claude-sonnet-4-5"):
+    def __init__(self, model_id: str = "anthropic/claude-sonnet-4-5", custom_tools=None):
         """Initialize the agent.
 
         Args:
             model_id: LiteLLM model identifier
+            custom_tools: Optional list of Python functions to add as tools
         """
+        # Store custom tools
+        self.custom_tools = custom_tools or []
+        self.custom_tool_funcs = {func.__name__: func for func in self.custom_tools}
+
         # Convert ollama/ to ollama_chat/ for LiteLLM compatibility
         if model_id.startswith("ollama/"):
             model_id = model_id.replace("ollama/", "ollama_chat/", 1)
@@ -1029,6 +1034,67 @@ class PatchPalAgent:
         if self.enable_auto_compact and self.context_manager.needs_compaction(self.messages):
             self._perform_auto_compaction()
 
+        # Agent loop with interrupt handling
+        try:
+            return self._run_agent_loop(max_iterations)
+        except KeyboardInterrupt:
+            # Clean up conversation state if interrupted mid-execution
+            self._cleanup_interrupted_state()
+            raise  # Re-raise so CLI can handle it
+
+    def _cleanup_interrupted_state(self):
+        """Clean up conversation state after KeyboardInterrupt.
+
+        If the last message is an assistant message with tool_calls but no
+        corresponding tool responses, we need to either remove the message
+        or add error responses to maintain valid conversation structure.
+        """
+        if not self.messages:
+            return
+
+        last_msg = self.messages[-1]
+
+        # Check if last message is assistant with tool_calls
+        if last_msg.get("role") == "assistant" and last_msg.get("tool_calls"):
+            tool_calls = last_msg["tool_calls"]
+
+            # Check if we have tool responses for all tool_calls
+            tool_call_ids = {tc.id for tc in tool_calls}
+
+            # Look for tool responses after this assistant message
+            # (should be immediately following, but scan to be safe)
+            response_ids = set()
+            for msg in self.messages[self.messages.index(last_msg) + 1 :]:
+                if msg.get("role") == "tool":
+                    response_ids.add(msg.get("tool_call_id"))
+
+            # If we're missing responses, add error responses for all tool calls
+            if tool_call_ids != response_ids:
+                missing_ids = tool_call_ids - response_ids
+
+                # Add error tool responses for the missing tool calls
+                for tool_call in tool_calls:
+                    if tool_call.id in missing_ids:
+                        self.messages.append(
+                            {
+                                "role": "tool",
+                                "tool_call_id": tool_call.id,
+                                "name": tool_call.function.name,
+                                "content": "Error: Operation interrupted by user (Ctrl-C)",
+                            }
+                        )
+
+    def _run_agent_loop(self, max_iterations: int) -> str:
+        """Internal method that runs the agent loop.
+
+        Separated from run() to enable proper interrupt handling.
+
+        Args:
+            max_iterations: Maximum number of agent iterations
+
+        Returns:
+            The agent's final response
+        """
         # Agent loop
         for iteration in range(max_iterations):
             # Show thinking message
@@ -1042,10 +1108,18 @@ class PatchPalAgent:
 
             # Use LiteLLM for all providers
             try:
+                # Build tool list (built-in + custom)
+                tools = list(TOOLS)
+                if self.custom_tools:
+                    from patchpal.tool_schema import function_to_tool_schema
+
+                    for func in self.custom_tools:
+                        tools.append(function_to_tool_schema(func))
+
                 response = litellm.completion(
                     model=self.model_id,
                     messages=messages,
-                    tools=TOOLS,
+                    tools=tools,
                     tool_choice="auto",
                     **self.litellm_kwargs,
                 )
@@ -1099,15 +1173,25 @@ class PatchPalAgent:
                         tool_result = f"Error: Invalid JSON arguments for {tool_name}"
                         print(f"\033[1;31m✗ {tool_name}: Invalid arguments\033[0m")
                     else:
-                        # Get the tool function
-                        tool_func = TOOL_FUNCTIONS.get(tool_name)
+                        # Get the tool function (check custom tools first, then built-in)
+                        tool_func = self.custom_tool_funcs.get(tool_name) or TOOL_FUNCTIONS.get(
+                            tool_name
+                        )
                         if tool_func is None:
                             tool_result = f"Error: Unknown tool {tool_name}"
                             print(f"\033[1;31m✗ Unknown tool: {tool_name}\033[0m")
                         else:
                             # Show tool call message
-                            tool_display = tool_name.replace("_", " ").title()
-                            if tool_name == "read_file":
+                            if tool_name in self.custom_tool_funcs:
+                                # Custom tool - show generic message with args
+                                args_preview = str(tool_args)[:60]
+                                if len(str(tool_args)) > 60:
+                                    args_preview += "..."
+                                print(
+                                    f"\033[2m🔧 {tool_name}({args_preview})\033[0m",
+                                    flush=True,
+                                )
+                            elif tool_name == "read_file":
                                 print(
                                     f"\033[2m📖 Reading: {tool_args.get('path', '')}\033[0m",
                                     flush=True,
@@ -1250,7 +1334,7 @@ class PatchPalAgent:
                                 tool_result = tool_func(**filtered_args)
                             except Exception as e:
                                 tool_result = f"Error executing {tool_name}: {e}"
-                                print(f"\033[1;31m✗ {tool_display}: {e}\033[0m")
+                                print(f"\033[1;31m✗ {tool_name}: {e}\033[0m")
 
                     # Add tool result to messages
                     self.messages.append(
@@ -1299,18 +1383,33 @@ class PatchPalAgent:
         )
 
 
-def create_agent(model_id: str = "anthropic/claude-sonnet-4-5") -> PatchPalAgent:
+def create_agent(model_id: str = "anthropic/claude-sonnet-4-5", custom_tools=None) -> PatchPalAgent:
     """Create and return a PatchPal agent.
 
     Args:
         model_id: LiteLLM model identifier (default: anthropic/claude-sonnet-4-5)
+        custom_tools: Optional list of Python functions to use as custom tools.
+                     Each function should have type hints and a docstring.
 
     Returns:
         A configured PatchPalAgent instance
+
+    Example:
+        def calculator(x: int, y: int) -> str:
+            '''Add two numbers.
+
+            Args:
+                x: First number
+                y: Second number
+            '''
+            return str(x + y)
+
+        agent = create_agent(custom_tools=[calculator])
+        response = agent.run("What's 5 + 3?")
     """
     # Reset session todos for new session
     from patchpal.tools import reset_session_todos
 
     reset_session_todos()
 
-    return PatchPalAgent(model_id=model_id)
+    return PatchPalAgent(model_id=model_id, custom_tools=custom_tools)

patchpal/cli.py

@@ -211,9 +211,26 @@ Supported models: Any LiteLLM-supported model
     # Determine model to use (priority: CLI arg > env var > default)
     model_id = args.model or os.getenv("PATCHPAL_MODEL") or "anthropic/claude-sonnet-4-5"
 
-    # Create the agent with the specified model
+    # Discover custom tools from ~/.patchpal/tools/
+    from patchpal.tool_schema import discover_tools, list_custom_tools
+
+    custom_tools = discover_tools()
+
+    # Show custom tools info if any were loaded
+    custom_tool_info = list_custom_tools()
+    if custom_tool_info:
+        tool_names = [name for name, _, _ in custom_tool_info]
+        tools_str = ", ".join(tool_names)
+        # Store for later display (after model info)
+        custom_tools_message = (
+            f"\033[1;36m🔧 Loaded {len(custom_tool_info)} custom tool(s): {tools_str}\033[0m"
+        )
+    else:
+        custom_tools_message = None
+
+    # Create the agent with the specified model and custom tools
     # LiteLLM will handle API key validation and provide appropriate error messages
-    agent = create_agent(model_id=model_id)
+    agent = create_agent(model_id=model_id, custom_tools=custom_tools)
 
     # Get max iterations from environment variable or use default
     max_iterations = int(os.getenv("PATCHPAL_MAX_ITERATIONS", "100"))
@@ -238,6 +255,10 @@ Supported models: Any LiteLLM-supported model
     print("=" * 80)
     print(f"\nUsing model: {model_id}")
 
+    # Show custom tools info if any were loaded
+    if custom_tools_message:
+        print(custom_tools_message)
+
     # Show require-permission-for-all indicator if active
     if args.require_permission_for_all:
         print("\033[1;33m🔒 Permission required for ALL operations (including reads)\033[0m")

patchpal/tool_schema.py

@@ -0,0 +1,288 @@
+"""Utility to automatically convert Python functions to LiteLLM tool schemas.
+
+Also provides custom tools discovery system for loading user-defined tools
+from ~/.patchpal/tools/
+"""
+
+import inspect
+import sys
+from importlib import util
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Union, get_args, get_origin, get_type_hints
+
+
+def python_type_to_json_schema(py_type: Any) -> Dict[str, Any]:
+    """Convert Python type hint to JSON schema type.
+
+    Args:
+        py_type: Python type hint
+
+    Returns:
+        JSON schema type dict
+    """
+    if py_type is type(None):
+        return {"type": "null"}
+
+    origin = get_origin(py_type)
+
+    # Handle Optional/Union types
+    if origin is Union:
+        args = get_args(py_type)
+        non_none = [a for a in args if a is not type(None)]
+        if non_none:
+            return python_type_to_json_schema(non_none[0])
+
+    # Handle List
+    if origin is list:
+        args = get_args(py_type)
+        if args:
+            return {"type": "array", "items": python_type_to_json_schema(args[0])}
+        return {"type": "array"}
+
+    # Handle Dict
+    if origin is dict:
+        return {"type": "object"}
+
+    # Basic types
+    type_map = {
+        str: {"type": "string"},
+        int: {"type": "integer"},
+        float: {"type": "number"},
+        bool: {"type": "boolean"},
+        list: {"type": "array"},
+        dict: {"type": "object"},
+    }
+
+    return type_map.get(py_type, {"type": "string"})
+
+
+def parse_docstring_params(docstring: str) -> Dict[str, str]:
+    """Parse parameter descriptions from Google-style docstring.
+
+    Args:
+        docstring: Function docstring
+
+    Returns:
+        Dict mapping parameter names to descriptions
+    """
+    if not docstring:
+        return {}
+
+    params = {}
+    lines = docstring.split("\n")
+    in_args = False
+
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+
+        if stripped.lower() in ("args:", "arguments:", "parameters:"):
+            in_args = True
+            continue
+
+        if in_args:
+            # Check if we left the Args section
+            if stripped and not line.startswith((" ", "\t")) and ":" in stripped:
+                break
+
+            # Parse "param_name: description"
+            if ":" in stripped:
+                parts = stripped.split(":", 1)
+                param_name = parts[0].strip()
+                description = parts[1].strip()
+
+                # Collect continuation lines
+                for j in range(i + 1, len(lines)):
+                    next_line = lines[j].strip()
+                    if not next_line or ":" in next_line:
+                        break
+                    description += " " + next_line
+
+                params[param_name] = description
+
+    return params
+
+
+def function_to_tool_schema(func: Callable) -> Dict[str, Any]:
+    """Convert a Python function to LiteLLM tool schema.
+
+    Extracts schema from function signature and docstring.
+
+    Args:
+        func: Python function with type hints and docstring
+
+    Returns:
+        LiteLLM tool schema dict
+    """
+    sig = inspect.signature(func)
+    docstring = inspect.getdoc(func) or ""
+
+    # Extract description (first paragraph)
+    description = (
+        docstring.split("\n\n")[0].replace("\n", " ").strip() or f"Execute {func.__name__}"
+    )
+
+    # Parse parameter descriptions
+    param_descriptions = parse_docstring_params(docstring)
+
+    # Get type hints
+    try:
+        type_hints = get_type_hints(func)
+    except Exception:
+        type_hints = {}
+
+    # Build parameters
+    properties = {}
+    required = []
+
+    for param_name, param in sig.parameters.items():
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            continue
+
+        param_type = type_hints.get(param_name, str)
+        param_schema = python_type_to_json_schema(param_type)
+        param_schema["description"] = param_descriptions.get(param_name, f"Parameter {param_name}")
+
+        properties[param_name] = param_schema
+
+        if param.default is inspect.Parameter.empty:
+            required.append(param_name)
+
+    return {
+        "type": "function",
+        "function": {
+            "name": func.__name__,
+            "description": description,
+            "parameters": {
+                "type": "object",
+                "properties": properties,
+                "required": required,
+            },
+        },
+    }
+
+
+def _is_valid_tool_function(func: Callable) -> bool:
+    """Check if a function is valid for use as a tool.
+
+    Args:
+        func: Function to validate
+
+    Returns:
+        True if function can be used as a tool
+    """
+    # Must have a docstring
+    if not func.__doc__:
+        return False
+
+    # Must have type hints
+    try:
+        sig = inspect.signature(func)
+        for param_name, param in sig.parameters.items():
+            # Skip *args, **kwargs
+            if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+                continue
+            # Check if parameter has annotation
+            if param.annotation is inspect.Parameter.empty:
+                return False
+    except Exception:
+        return False
+
+    return True
+
+
+def discover_tools(tools_dir: Optional[Path] = None) -> List[Callable]:
+    """Discover custom tool functions from Python files.
+
+    Loads all .py files from the tools directory and extracts functions
+    that have proper type hints and docstrings.
+
+    Tool functions must:
+    - Have type hints for all parameters
+    - Have a docstring with description and Args section
+    - Be defined at module level (not nested)
+    - Not start with underscore (private functions ignored)
+
+    Args:
+        tools_dir: Directory to search for tool files (default: ~/.patchpal/tools/)
+
+    Returns:
+        List of callable tool functions
+    """
+    if tools_dir is None:
+        tools_dir = Path.home() / ".patchpal" / "tools"
+
+    if not tools_dir.exists():
+        return []
+
+    tools = []
+    loaded_modules = []
+
+    # Discover all .py files
+    for tool_file in sorted(tools_dir.glob("*.py")):
+        try:
+            # Create a unique module name to avoid conflicts
+            module_name = f"patchpal_custom_tools.{tool_file.stem}"
+
+            # Load the module
+            spec = util.spec_from_file_location(module_name, tool_file)
+            if spec and spec.loader:
+                module = util.module_from_spec(spec)
+
+                # Store reference to prevent garbage collection
+                sys.modules[module_name] = module
+                loaded_modules.append(module)
+
+                # Execute the module
+                spec.loader.exec_module(module)
+
+                # Extract valid tool functions
+                for name, obj in inspect.getmembers(module, inspect.isfunction):
+                    # Skip private functions
+                    if name.startswith("_"):
+                        continue
+
+                    # Skip functions from imports (only module-level definitions)
+                    if obj.__module__ != module_name:
+                        continue
+
+                    # Validate tool function
+                    if _is_valid_tool_function(obj):
+                        tools.append(obj)
+
+        except Exception as e:
+            # Print warning but continue with other tools
+            print(
+                f"\033[1;33m⚠️  Warning: Failed to load custom tool from {tool_file.name}: {e}\033[0m"
+            )
+            continue
+
+    return tools
+
+
+def list_custom_tools(tools_dir: Optional[Path] = None) -> List[tuple[str, str, Path]]:
+    """List all custom tools with their descriptions.
+
+    Args:
+        tools_dir: Directory to search for tool files (default: ~/.patchpal/tools/)
+
+    Returns:
+        List of (tool_name, description, file_path) tuples
+    """
+    tools = discover_tools(tools_dir)
+
+    result = []
+    for tool in tools:
+        # Extract description from docstring (first line)
+        description = ""
+        if tool.__doc__:
+            description = tool.__doc__.split("\n")[0].strip()
+
+        # Get source file
+        try:
+            source_file = Path(inspect.getfile(tool))
+        except Exception:
+            source_file = Path("unknown")
+
+        result.append((tool.__name__, description, source_file))
+
+    return result

patchpal/tools.py

@@ -2521,8 +2521,24 @@ def web_search(query: str, max_results: int = 5) -> str:
     max_results = min(max_results, 10)
 
     try:
+        # Determine SSL verification setting
+        # Priority: PATCHPAL_VERIFY_SSL env var > SSL_CERT_FILE > REQUESTS_CA_BUNDLE > default True
+        verify_ssl = os.getenv("PATCHPAL_VERIFY_SSL")
+        if verify_ssl is not None:
+            # User explicitly set PATCHPAL_VERIFY_SSL
+            if verify_ssl.lower() in ("false", "0", "no"):
+                verify = False
+            elif verify_ssl.lower() in ("true", "1", "yes"):
+                verify = True
+            else:
+                # Treat as path to CA bundle
+                verify = verify_ssl
+        else:
+            # Use SSL_CERT_FILE or REQUESTS_CA_BUNDLE if set (for corporate environments)
+            verify = os.getenv("SSL_CERT_FILE") or os.getenv("REQUESTS_CA_BUNDLE") or True
+
         # Perform search using DuckDuckGo
-        with DDGS() as ddgs:
+        with DDGS(verify=verify) as ddgs:
             results = list(ddgs.text(query, max_results=max_results))
 
         if not results:

{patchpal-0.4.5.dist-info → patchpal-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchpal
-Version: 0.4.5
+Version: 0.6.0
 Summary: A lean Claude Code clone in pure  Python
 Author: PatchPal Contributors
 License-Expression: Apache-2.0
@@ -46,6 +46,18 @@ Dynamic: license-file
 
 A key goal of this project is to approximate Claude Code's core functionality while remaining lean, accessible, and configurable, enabling learning, experimentation, and broad applicability across use cases.
 
+```bash
+$ls ./patchpal
+__init__.py agent.py  cli.py context.py permissions.py  skills.py system_prompt.md tool_schema.py tools.py
+```
+
+## Quick Start
+
+```bash
+$ pip install patchpal  # install
+$ patchpal              # start
+```
+
 ## Table of Contents
 
 - [Installation](https://github.com/amaiya/patchpal?tab=readme-ov-file#installation)
@@ -58,12 +70,14 @@ A key goal of this project is to approximate Claude Code's core functionality wh
     - [Git Operations](https://github.com/amaiya/patchpal?tab=readme-ov-file#git-operations-no-permission-required)
     - [Web Capabilities](https://github.com/amaiya/patchpal?tab=readme-ov-file#web-capabilities-requires-permission)
   - [Skills System](https://github.com/amaiya/patchpal?tab=readme-ov-file#skills-system)
+  - [Custom Tools](https://github.com/amaiya/patchpal?tab=readme-ov-file#custom-tools)
 - [Model Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#model-configuration)
   - [Supported Models](https://github.com/amaiya/patchpal?tab=readme-ov-file#supported-models)
   - [Using Local Models (vLLM & Ollama)](https://github.com/amaiya/patchpal?tab=readme-ov-file#using-local-models-vllm--ollama)
   - [Air-Gapped and Offline Environments](https://github.com/amaiya/patchpal?tab=readme-ov-file#air-gapped-and-offline-environments)
   - [Maximum Security Mode](https://github.com/amaiya/patchpal?tab=readme-ov-file#maximum-security-mode)
 - [Usage](https://github.com/amaiya/patchpal?tab=readme-ov-file#usage)
+- [Python API](https://github.com/amaiya/patchpal?tab=readme-ov-file#python-api)
 - [Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#configuration)
 - [Example Tasks](https://github.com/amaiya/patchpal?tab=readme-ov-file#example-tasks)
 - [Safety](https://github.com/amaiya/patchpal?tab=readme-ov-file#safety)
@@ -71,10 +85,6 @@ A key goal of this project is to approximate Claude Code's core functionality wh
 - [Troubleshooting](https://github.com/amaiya/patchpal?tab=readme-ov-file#troubleshooting)
 
 
-```bash
-$ls ./patchpal
-__init__.py agent.py  cli.py context.py permissions.py  skills.py system_prompt.md tools.py
-```
 
 ## Installation
 
@@ -307,6 +317,197 @@ You: list skills
 
 Project skills (`.patchpal/skills/`) override personal skills (`~/.patchpal/skills/`) with the same name.
 
+### Custom Tools
+
+Custom tools extend PatchPal's capabilities by adding new Python functions that the agent can call. Unlike skills (which are prompt-based workflows), custom tools are executable Python code that the agent invokes automatically when needed.
+
+**Key Differences:**
+- **Skills**: Markdown files with instructions for the agent to follow
+- **Custom Tools**: Python functions that execute code and return results
+
+**Installation:**
+
+1. **Create the tools directory:**
+```bash
+mkdir -p ~/.patchpal/tools
+```
+
+2. **Copy the example tools (or create your own):**
+```bash
+# After pip install patchpal, get the example tools
+curl -L https://github.com/amaiya/patchpal/archive/main.tar.gz | tar xz --strip=1 patchpal-main/examples
+
+# Copy to your tools directory
+cp examples/tools/calculator.py ~/.patchpal/tools/
+```
+
+3. **Start PatchPal - tools are loaded automatically:**
+```bash
+$ patchpal
+================================================================================
+PatchPal - Claude Code–inspired coding and automation assistant
+================================================================================
+
+Using model: anthropic/claude-sonnet-4-5
+🔧 Loaded 7 custom tool(s): add, subtract, multiply, divide, calculate_percentage, fahrenheit_to_celsius, celsius_to_fahrenheit
+```
+
+**Creating Custom Tools:**
+
+Custom tools are Python functions with specific requirements:
+
+**Requirements:**
+1. **Type hints** for all parameters
+2. **Docstring** with description and Args section (Google-style)
+3. **Module-level** functions (not nested inside classes)
+4. **Return type** should typically be `str` (for LLM consumption)
+5. Function names **cannot start with underscore** (private functions ignored)
+
+**Example:**
+
+```python
+# ~/.patchpal/tools/my_tools.py
+
+def add(x: int, y: int) -> str:
+    """Add two numbers together.
+
+    Args:
+        x: First number
+        y: Second number
+
+    Returns:
+        The sum as a string
+    """
+    result = x + y
+    return f"{x} + {y} = {result}"
+
+
+def convert_currency(amount: float, from_currency: str, to_currency: str) -> str:
+    """Convert between currencies.
+
+    Args:
+        amount: Amount to convert
+        from_currency: Source currency code (e.g., USD)
+        to_currency: Target currency code (e.g., EUR)
+
+    Returns:
+        Converted amount as a string
+    """
+    # Your implementation here (API call, etc.)
+    # This is just a simple example
+    rates = {"USD": 1.0, "EUR": 0.85, "GBP": 0.73}
+    usd_amount = amount / rates.get(from_currency, 1.0)
+    result = usd_amount * rates.get(to_currency, 1.0)
+    return f"{amount} {from_currency} = {result:.2f} {to_currency}"
+```
+
+**Using Custom Tools:**
+
+Once loaded, the agent calls your custom tools automatically:
+
+```bash
+You: What's 15 + 27?
+Agent: [Calls the add tool]
+        15 + 27 = 42
+
+You: Convert 100 USD to EUR
+Agent: [Calls convert_currency tool]
+        100 USD = 85.00 EUR
+```
+
+**Tool Discovery:**
+
+PatchPal discovers tools from `~/.patchpal/tools/*.py` at startup. All `.py` files are scanned for valid tool functions.
+
+**What Gets Loaded:**
+- ✅ Functions with type hints and docstrings
+- ✅ Multiple functions per file
+- ✅ Files can import standard libraries
+- ❌ Functions without type hints
+- ❌ Functions without docstrings
+- ❌ Private functions (starting with `_`)
+- ❌ Imported functions (must be defined in the file)
+
+**Example Tools:**
+
+The repository includes [example tools](https://github.com/amaiya/patchpal/tree/main/examples/tools):
+- **calculator.py**: Basic arithmetic (add, subtract, multiply, divide), temperature conversion, percentage calculations
+  - Demonstrates different numeric types (int, float)
+  - Shows proper formatting of results for LLM consumption
+  - Examples: `add`, `subtract`, `multiply`, `divide`, `calculate_percentage`, `fahrenheit_to_celsius`
+
+View the [examples/tools/](https://github.com/amaiya/patchpal/tree/main/examples/tools) directory for complete examples and a detailed README.
+
+**Security Note:**
+
+⚠️ Custom tools execute arbitrary Python code on your system. Only install tools from sources you trust.
+
+- Tools are only loaded from `~/.patchpal/tools/` (your home directory)
+- Project-local tools (`.patchpal/tools/`) are **not supported** for security
+- This prevents accidental execution of untrusted code from repositories
+
+**Advanced Features:**
+
+**Optional Parameters:**
+```python
+from typing import Optional
+
+def greet(name: str, greeting: Optional[str] = "Hello") -> str:
+    """Greet someone.
+
+    Args:
+        name: Person's name
+        greeting: Optional greeting message (default: "Hello")
+    """
+    return f"{greeting}, {name}!"
+```
+
+**Complex Types:**
+```python
+from typing import List
+
+def sum_numbers(numbers: List[int]) -> str:
+    """Sum a list of numbers.
+
+    Args:
+        numbers: List of integers to sum
+    """
+    total = sum(numbers)
+    return f"Sum of {numbers} = {total}"
+```
+
+**Python API:**
+
+Custom tools can also be used programmatically:
+
+```python
+from patchpal.agent import create_agent
+
+def calculator(x: int, y: int) -> str:
+    """Add two numbers.
+
+    Args:
+        x: First number
+        y: Second number
+    """
+    return str(x + y)
+
+# Create agent with custom tools
+agent = create_agent(custom_tools=[calculator])
+response = agent.run("What's 5 + 3?")
+```
+
+See the [Python API](https://github.com/amaiya/patchpal?tab=readme-ov-file#python-api) section for more details.
+
+**Troubleshooting:**
+
+If tools aren't loading:
+1. Check the file has a `.py` extension
+2. Ensure functions have type hints for all parameters
+3. Verify docstrings follow Google style (with Args: section)
+4. Look for warning messages when starting PatchPal
+5. Test the function directly in Python to check for syntax errors
+
 ## Model Configuration
 
 PatchPal supports any LiteLLM-compatible model. You can configure the model in three ways (in order of priority):
@@ -668,6 +869,163 @@ The agent will process your request and show you the results. You can continue w
 - **Interrupt Agent**: Press `Ctrl-C` during agent execution to stop the current task without exiting PatchPal
 - **Exit**: Type `exit`, `quit`, or press `Ctrl-C` at the prompt to exit PatchPal
 
+## Python API
+
+PatchPal can be used programmatically from Python scripts or a REPL, giving you full agent capabilities with a simple API. **Unlike fully autonomous agent frameworks, PatchPal is designed for human-in-the-loop workflows** where users maintain control through interactive permission prompts, making it ideal for code assistance, debugging, and automation tasks that benefit from human oversight.
+
+**Basic Usage:**
+
+```python
+from patchpal.agent import create_agent
+
+# Create an agent (uses default model or PATCHPAL_MODEL env var)
+agent = create_agent()
+
+# Or specify a model explicitly
+agent = create_agent(model_id="anthropic/claude-sonnet-4_5")
+
+# Run the agent on a task
+response = agent.run("List all Python files in this directory")
+print(response)
+
+# Continue the conversation (history is maintained)
+response = agent.run("Now read the main agent file")
+print(response)
+```
+
+**Adding Custom Tools:**
+
+Custom tools can be used in two ways:
+
+1. **CLI**: Place `.py` files in `~/.patchpal/tools/` (auto-discovered at startup)
+2. **Python API**: Pass functions directly to `create_agent(custom_tools=[...])`
+
+Both methods use the same tool schema auto-generation from Python functions with type hints and docstrings:
+
+```python
+from patchpal.agent import create_agent
+
+def calculator(x: int, y: int, operation: str = "add") -> str:
+    """Perform basic arithmetic operations.
+
+    Args:
+        x: First number
+        y: Second number
+        operation: Operation to perform (add, subtract, multiply, divide)
+
+    Returns:
+        Result as a string
+    """
+    if operation == "add":
+        return f"{x} + {y} = {x + y}"
+    elif operation == "subtract":
+        return f"{x} - {y} = {x - y}"
+    elif operation == "multiply":
+        return f"{x} * {y} = {x * y}"
+    elif operation == "divide":
+        if y == 0:
+            return "Error: Cannot divide by zero"
+        return f"{x} / {y} = {x / y}"
+    return "Unknown operation"
+
+
+def get_weather(city: str, units: str = "celsius") -> str:
+    """Get weather information for a city.
+
+    Args:
+        city: Name of the city
+        units: Temperature units (celsius or fahrenheit)
+
+    Returns:
+        Weather information string
+    """
+    # Your implementation here (API call, etc.)
+    return f"Weather in {city}: 22°{units[0].upper()}, Sunny"
+
+
+# Create agent with custom tools
+agent = create_agent(
+    model_id="anthropic/claude-sonnet-4-5",
+    custom_tools=[calculator, get_weather]
+)
+
+# Use the agent - it will call your custom tools when appropriate
+response = agent.run("What's 15 multiplied by 23?")
+print(response)
+
+response = agent.run("What's the weather in Paris?")
+print(response)
+```
+
+**Key Points:**
+- Custom tools are automatically converted to LLM tool schemas
+- Functions should have type hints and Google-style docstrings
+- The agent will call your functions when appropriate
+- Tool execution follows the same permission system as built-in tools
+
+**Advanced Usage:**
+
+```python
+from patchpal.agent import PatchPalAgent
+
+# Create agent with custom configuration
+agent = PatchPalAgent(model_id="anthropic/claude-sonnet-4-5")
+
+# Set custom max iterations for complex tasks
+response = agent.run("Refactor the entire codebase", max_iterations=200)
+
+# Access conversation history
+print(f"Messages in history: {len(agent.messages)}")
+
+# Check context window usage
+stats = agent.context_manager.get_usage_stats(agent.messages)
+print(f"Token usage: {stats['total_tokens']:,} / {stats['context_limit']:,}")
+print(f"Usage: {stats['usage_percent']}%")
+
+# Manually trigger compaction if needed
+if agent.context_manager.needs_compaction(agent.messages):
+    agent._perform_auto_compaction()
+
+# Track API costs (cumulative token counts across session)
+print(f"Total LLM calls: {agent.total_llm_calls}")
+print(f"Cumulative input tokens: {agent.cumulative_input_tokens:,}")
+print(f"Cumulative output tokens: {agent.cumulative_output_tokens:,}")
+print(f"Total tokens: {agent.cumulative_input_tokens + agent.cumulative_output_tokens:,}")
+```
+
+**Use Cases:**
+- **Interactive debugging**: Use in Jupyter notebooks for hands-on debugging with agent assistance
+- **Automation scripts**: Build scripts that use the agent for complex tasks with human oversight
+- **Custom workflows**: Integrate PatchPal into your own tools and pipelines
+- **Code review assistance**: Programmatic code analysis with permission controls
+- **Batch processing**: Process multiple tasks programmatically while maintaining control
+- **Testing and evaluation**: Test agent behavior with different prompts and configurations
+
+**Key Features:**
+- **Human-in-the-loop design**: Permission prompts ensure human oversight (unlike fully autonomous frameworks)
+- **Stateful conversations**: Agent maintains full conversation history
+- **Custom tools**: Add your own Python functions (via CLI auto-discovery or API parameter) with automatic schema generation
+- **Automatic context management**: Auto-compaction works the same as CLI
+- **All built-in tools available**: File operations, git, web search, skills, etc.
+- **Model flexibility**: Works with any LiteLLM-compatible model
+- **Token tracking**: Monitor API usage and costs in real-time
+- **Environment variables respected**: All `PATCHPAL_*` settings apply
+
+**PatchPal vs. Other Agent Frameworks:**
+
+Unlike fully autonomous agent frameworks (e.g., smolagents, autogen), PatchPal is explicitly designed for **human-in-the-loop workflows**:
+
+| Feature | PatchPal | Autonomous Frameworks |
+|---------|----------|----------------------|
+| **Design Philosophy** | Human oversight & control | Autonomous execution |
+| **Permission System** | Interactive prompts for sensitive operations | Typically no prompts |
+| **Primary Use Case** | Code assistance, debugging, interactive tasks | Automated workflows, batch processing |
+| **Safety Model** | Write boundary protection, command blocking | Varies by framework |
+| **Custom Tools** | Yes, with automatic schema generation | Yes (varies by framework) |
+| **Best For** | Developers who want AI assistance with control | Automation, research, agent benchmarks |
+
+The Python API uses the same agent implementation as the CLI, so you get the complete feature set including permissions, safety guardrails, and context management.
+
 ## Configuration
 
 PatchPal can be configured through `PATCHPAL_*` environment variables to customize behavior, security, and performance.
@@ -734,6 +1092,16 @@ export PATCHPAL_PRUNE_MINIMUM=20000          # Minimum tokens to prune (default:
 # Enable/Disable Web Access
 export PATCHPAL_ENABLE_WEB=false             # Disable web search/fetch for air-gapped environments (default: true)
 
+# SSL Certificate Verification (for web_search)
+export PATCHPAL_VERIFY_SSL=true              # SSL verification for web searches (default: true)
+                                              # Set to 'false' to disable (not recommended for production)
+                                              # Or set to path of CA bundle file for corporate certificates
+                                              # Auto-detects SSL_CERT_FILE and REQUESTS_CA_BUNDLE if not set
+                                              # Examples:
+                                              #   export PATCHPAL_VERIFY_SSL=false  # Disable verification
+                                              #   export PATCHPAL_VERIFY_SSL=/path/to/ca-bundle.crt  # Custom CA bundle
+                                              #   (Leave unset to auto-detect from SSL_CERT_FILE/REQUESTS_CA_BUNDLE)
+
 # Web Request Limits
 export PATCHPAL_WEB_TIMEOUT=60               # Web request timeout in seconds (default: 30)
 export PATCHPAL_MAX_WEB_SIZE=10485760        # Max web content size in bytes (default: 5MB)

patchpal-0.6.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+patchpal/__init__.py,sha256=S3dYO3L8dSQG2Eaosbu4Pbdq5eTxXLmmvxSzh-TIPiI,606
+patchpal/agent.py,sha256=ayMkZUoohUsf5Tz4esBjOPZUvBT5n-ijOzoOp3c9LAA,59719
+patchpal/cli.py,sha256=6Imrd4hGupIrTi9jnnfwvraNZ_Pq0VJxfo6aSjLRoCY,24131
+patchpal/context.py,sha256=hdTUvyAXXUP47JY1Q3YJDU7noGAcHuBGlNuU272Fjp4,14831
+patchpal/permissions.py,sha256=pVlzit2KFmCpfcbHrHhjPA0LPka04wOtaQdZCf3CCa0,10781
+patchpal/skills.py,sha256=ESLPHkDI8DH4mnAbN8mIcbZ6Bis4vCcqS_NjlYPNCOs,3926
+patchpal/system_prompt.md,sha256=LQzcILr41s65hk7JjaX_WzjUHBHCazVSrx_F_ErqTmA,10850
+patchpal/tool_schema.py,sha256=dGEGYV160G9c7EnSMtnbQ_mYuoR1n6PHHE8T20BriYE,8357
+patchpal/tools.py,sha256=YAUX2-8BBqjZEadIWlUdO-KV2-WHGazgKdMHkYRAExI,93819
+patchpal-0.6.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+patchpal-0.6.0.dist-info/METADATA,sha256=hjleiaXTNaavuW0OygY1XPdbuflYxMQb0hAWw9pGWPw,57384
+patchpal-0.6.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+patchpal-0.6.0.dist-info/entry_points.txt,sha256=XcuQikKu5i8Sd8AfHLuKxSE2RWByInTcQgWpP61sr48,47
+patchpal-0.6.0.dist-info/top_level.txt,sha256=YWgv2F-_PIHCu-sF3AF8N1ut5_FbOT-VV6HB70pGSQ8,9
+patchpal-0.6.0.dist-info/RECORD,,

patchpal-0.4.5.dist-info/RECORD

@@ -1,14 +0,0 @@
-patchpal/__init__.py,sha256=BZKk70eNcw6BLNVrj1TWs91vUTXbRMaHOHObNttZgrM,606
-patchpal/agent.py,sha256=uO-MA1ptt2FdpXrrbo07vVIPQj3radcIwP5izdjzmkQ,55519
-patchpal/cli.py,sha256=6UKoMxtow6Xd643vQ89tb6podepAgU1TjGlE2p8FFzE,23352
-patchpal/context.py,sha256=hdTUvyAXXUP47JY1Q3YJDU7noGAcHuBGlNuU272Fjp4,14831
-patchpal/permissions.py,sha256=pVlzit2KFmCpfcbHrHhjPA0LPka04wOtaQdZCf3CCa0,10781
-patchpal/skills.py,sha256=ESLPHkDI8DH4mnAbN8mIcbZ6Bis4vCcqS_NjlYPNCOs,3926
-patchpal/system_prompt.md,sha256=LQzcILr41s65hk7JjaX_WzjUHBHCazVSrx_F_ErqTmA,10850
-patchpal/tools.py,sha256=6zynI83wW6hwddIDKCYVRK8ICprj93bopp0K60PabS8,93042
-patchpal-0.4.5.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-patchpal-0.4.5.dist-info/METADATA,sha256=9J5IPsOWx0OTPkghGpE6tF-6CnchyBJYFL_DBLr-uIA,44203
-patchpal-0.4.5.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-patchpal-0.4.5.dist-info/entry_points.txt,sha256=XcuQikKu5i8Sd8AfHLuKxSE2RWByInTcQgWpP61sr48,47
-patchpal-0.4.5.dist-info/top_level.txt,sha256=YWgv2F-_PIHCu-sF3AF8N1ut5_FbOT-VV6HB70pGSQ8,9
-patchpal-0.4.5.dist-info/RECORD,,