patchpal 0.4.5__py3-none-any.whl → 0.7.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- patchpal/__init__.py +1 -1
- patchpal/agent.py +248 -12
- patchpal/cli.py +72 -2
- patchpal/tool_schema.py +288 -0
- patchpal/tools.py +21 -2
- {patchpal-0.4.5.dist-info → patchpal-0.7.1.dist-info}/METADATA +402 -17
- patchpal-0.7.1.dist-info/RECORD +15 -0
- patchpal-0.4.5.dist-info/RECORD +0 -14
- {patchpal-0.4.5.dist-info → patchpal-0.7.1.dist-info}/WHEEL +0 -0
- {patchpal-0.4.5.dist-info → patchpal-0.7.1.dist-info}/entry_points.txt +0 -0
- {patchpal-0.4.5.dist-info → patchpal-0.7.1.dist-info}/licenses/LICENSE +0 -0
- {patchpal-0.4.5.dist-info → patchpal-0.7.1.dist-info}/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: patchpal
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.7.1
|
|
4
4
|
Summary: A lean Claude Code clone in pure Python
|
|
5
5
|
Author: PatchPal Contributors
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -46,6 +46,18 @@ Dynamic: license-file
|
|
|
46
46
|
|
|
47
47
|
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.
|
|
48
48
|
|
|
49
|
+
```bash
|
|
50
|
+
$ls ./patchpal
|
|
51
|
+
__init__.py agent.py cli.py context.py permissions.py skills.py system_prompt.md tool_schema.py tools.py
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Quick Start
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
$ pip install patchpal # install
|
|
58
|
+
$ patchpal # start
|
|
59
|
+
```
|
|
60
|
+
|
|
49
61
|
## Table of Contents
|
|
50
62
|
|
|
51
63
|
- [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
|
|
|
58
70
|
- [Git Operations](https://github.com/amaiya/patchpal?tab=readme-ov-file#git-operations-no-permission-required)
|
|
59
71
|
- [Web Capabilities](https://github.com/amaiya/patchpal?tab=readme-ov-file#web-capabilities-requires-permission)
|
|
60
72
|
- [Skills System](https://github.com/amaiya/patchpal?tab=readme-ov-file#skills-system)
|
|
73
|
+
- [Custom Tools](https://github.com/amaiya/patchpal?tab=readme-ov-file#custom-tools)
|
|
61
74
|
- [Model Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#model-configuration)
|
|
62
75
|
- [Supported Models](https://github.com/amaiya/patchpal?tab=readme-ov-file#supported-models)
|
|
63
76
|
- [Using Local Models (vLLM & Ollama)](https://github.com/amaiya/patchpal?tab=readme-ov-file#using-local-models-vllm--ollama)
|
|
64
77
|
- [Air-Gapped and Offline Environments](https://github.com/amaiya/patchpal?tab=readme-ov-file#air-gapped-and-offline-environments)
|
|
65
78
|
- [Maximum Security Mode](https://github.com/amaiya/patchpal?tab=readme-ov-file#maximum-security-mode)
|
|
66
79
|
- [Usage](https://github.com/amaiya/patchpal?tab=readme-ov-file#usage)
|
|
80
|
+
- [Python API](https://github.com/amaiya/patchpal?tab=readme-ov-file#python-api)
|
|
67
81
|
- [Configuration](https://github.com/amaiya/patchpal?tab=readme-ov-file#configuration)
|
|
68
82
|
- [Example Tasks](https://github.com/amaiya/patchpal?tab=readme-ov-file#example-tasks)
|
|
69
83
|
- [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
|
|
|
71
85
|
- [Troubleshooting](https://github.com/amaiya/patchpal?tab=readme-ov-file#troubleshooting)
|
|
72
86
|
|
|
73
87
|
|
|
74
|
-
```bash
|
|
75
|
-
$ls ./patchpal
|
|
76
|
-
__init__.py agent.py cli.py context.py permissions.py skills.py system_prompt.md tools.py
|
|
77
|
-
```
|
|
78
88
|
|
|
79
89
|
## Installation
|
|
80
90
|
|
|
@@ -119,7 +129,7 @@ export HOSTED_VLLM_API_KEY=token-abc123 # optional depending on your v
|
|
|
119
129
|
patchpal
|
|
120
130
|
|
|
121
131
|
# Use a specific model via command-line argument
|
|
122
|
-
patchpal --model openai/gpt-
|
|
132
|
+
patchpal --model openai/gpt-5.2 # or openai/gpt-5-mini, anthropic/claude-opus-4-5 etc.
|
|
123
133
|
|
|
124
134
|
# Use vLLM (local)
|
|
125
135
|
# Note: vLLM server must be started with --tool-call-parser and --enable-auto-tool-choice
|
|
@@ -133,7 +143,7 @@ export OLLAMA_CONTEXT_LENGTH=32768
|
|
|
133
143
|
patchpal --model ollama_chat/qwen3:32b
|
|
134
144
|
|
|
135
145
|
# Or set the model via environment variable
|
|
136
|
-
export PATCHPAL_MODEL=openai/gpt-5
|
|
146
|
+
export PATCHPAL_MODEL=openai/gpt-5.2
|
|
137
147
|
patchpal
|
|
138
148
|
```
|
|
139
149
|
|
|
@@ -145,6 +155,8 @@ The agent has the following tools:
|
|
|
145
155
|
|
|
146
156
|
### File Operations
|
|
147
157
|
- **read_file**: Read contents of files in the repository
|
|
158
|
+
- Limited to 500KB by default (configurable with `PATCHPAL_MAX_FILE_SIZE`)
|
|
159
|
+
- For larger files, use `read_lines` or `grep_code` for targeted access
|
|
148
160
|
- **read_lines**: Read specific line ranges from a file without loading the entire file
|
|
149
161
|
- Example: `read_lines("app.py", 100, 150)` - read lines 100-150
|
|
150
162
|
- More efficient than read_file when you only need a few lines
|
|
@@ -271,7 +283,7 @@ cd patchpal
|
|
|
271
283
|
# Copy examples to your personal skills directory
|
|
272
284
|
cp -r examples/skills/commit ~/.patchpal/skills/
|
|
273
285
|
cp -r examples/skills/review ~/.patchpal/skills/
|
|
274
|
-
cp -r examples/skills/
|
|
286
|
+
cp -r examples/skills/skill-creator ~/.patchpal/skills/
|
|
275
287
|
```
|
|
276
288
|
|
|
277
289
|
**View examples online:**
|
|
@@ -307,20 +319,225 @@ You: list skills
|
|
|
307
319
|
|
|
308
320
|
Project skills (`.patchpal/skills/`) override personal skills (`~/.patchpal/skills/`) with the same name.
|
|
309
321
|
|
|
322
|
+
### Custom Tools
|
|
323
|
+
|
|
324
|
+
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.
|
|
325
|
+
|
|
326
|
+
**Key Differences:**
|
|
327
|
+
- **Skills**: Markdown files with instructions for the agent to follow
|
|
328
|
+
- **Custom Tools**: Python functions that execute code and return results
|
|
329
|
+
|
|
330
|
+
**Installation:**
|
|
331
|
+
|
|
332
|
+
1. **Create the tools directory:**
|
|
333
|
+
```bash
|
|
334
|
+
mkdir -p ~/.patchpal/tools
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
2. **Copy the example tools (or create your own):**
|
|
338
|
+
```bash
|
|
339
|
+
# After pip install patchpal, get the example tools
|
|
340
|
+
curl -L https://github.com/amaiya/patchpal/archive/main.tar.gz | tar xz --strip=1 patchpal-main/examples
|
|
341
|
+
|
|
342
|
+
# Copy to your tools directory
|
|
343
|
+
cp examples/tools/calculator.py ~/.patchpal/tools/
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
3. **Start PatchPal - tools are loaded automatically:**
|
|
347
|
+
```bash
|
|
348
|
+
$ patchpal
|
|
349
|
+
================================================================================
|
|
350
|
+
PatchPal - Claude Code–inspired coding and automation assistant
|
|
351
|
+
================================================================================
|
|
352
|
+
|
|
353
|
+
Using model: anthropic/claude-sonnet-4-5
|
|
354
|
+
🔧 Loaded 7 custom tool(s): add, subtract, multiply, divide, calculate_percentage, fahrenheit_to_celsius, celsius_to_fahrenheit
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
**Creating Custom Tools:**
|
|
358
|
+
|
|
359
|
+
Custom tools are Python functions with specific requirements:
|
|
360
|
+
|
|
361
|
+
**Requirements:**
|
|
362
|
+
1. **Type hints** for all parameters
|
|
363
|
+
2. **Docstring** with description and Args section (Google-style)
|
|
364
|
+
3. **Module-level** functions (not nested inside classes)
|
|
365
|
+
4. **Return type** should typically be `str` (for LLM consumption)
|
|
366
|
+
5. Function names **cannot start with underscore** (private functions ignored)
|
|
367
|
+
|
|
368
|
+
**Example:**
|
|
369
|
+
|
|
370
|
+
```python
|
|
371
|
+
# ~/.patchpal/tools/my_tools.py
|
|
372
|
+
|
|
373
|
+
def calculator(x: int, y: int, operation: str = "add") -> str:
|
|
374
|
+
"""Perform basic arithmetic operations.
|
|
375
|
+
|
|
376
|
+
Args:
|
|
377
|
+
x: First number
|
|
378
|
+
y: Second number
|
|
379
|
+
operation: Operation to perform (add, subtract, multiply, divide)
|
|
380
|
+
|
|
381
|
+
Returns:
|
|
382
|
+
Result as a string
|
|
383
|
+
"""
|
|
384
|
+
if operation == "add":
|
|
385
|
+
return f"{x} + {y} = {x + y}"
|
|
386
|
+
elif operation == "subtract":
|
|
387
|
+
return f"{x} - {y} = {x - y}"
|
|
388
|
+
elif operation == "multiply":
|
|
389
|
+
return f"{x} * {y} = {x * y}"
|
|
390
|
+
elif operation == "divide":
|
|
391
|
+
if y == 0:
|
|
392
|
+
return "Error: Cannot divide by zero"
|
|
393
|
+
return f"{x} / {y} = {x / y}"
|
|
394
|
+
return "Unknown operation"
|
|
395
|
+
|
|
396
|
+
|
|
397
|
+
def convert_currency(amount: float, from_currency: str, to_currency: str) -> str:
|
|
398
|
+
"""Convert between currencies.
|
|
399
|
+
|
|
400
|
+
Args:
|
|
401
|
+
amount: Amount to convert
|
|
402
|
+
from_currency: Source currency code (e.g., USD)
|
|
403
|
+
to_currency: Target currency code (e.g., EUR)
|
|
404
|
+
|
|
405
|
+
Returns:
|
|
406
|
+
Converted amount as a string
|
|
407
|
+
"""
|
|
408
|
+
# Your implementation here (API call, etc.)
|
|
409
|
+
# This is just a simple example
|
|
410
|
+
rates = {"USD": 1.0, "EUR": 0.85, "GBP": 0.73}
|
|
411
|
+
usd_amount = amount / rates.get(from_currency, 1.0)
|
|
412
|
+
result = usd_amount * rates.get(to_currency, 1.0)
|
|
413
|
+
return f"{amount} {from_currency} = {result:.2f} {to_currency}"
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
**Using Custom Tools:**
|
|
417
|
+
|
|
418
|
+
Once loaded, the agent calls your custom tools automatically:
|
|
419
|
+
|
|
420
|
+
```bash
|
|
421
|
+
You: What's 15 + 27?
|
|
422
|
+
Agent: [Calls calculator(15, 27, "add")]
|
|
423
|
+
15 + 27 = 42
|
|
424
|
+
|
|
425
|
+
You: What's 100 divided by 4?
|
|
426
|
+
Agent: [Calls calculator(100, 4, "divide")]
|
|
427
|
+
100 / 4 = 25
|
|
428
|
+
|
|
429
|
+
You: Convert 100 USD to EUR
|
|
430
|
+
Agent: [Calls convert_currency(100, "USD", "EUR")]
|
|
431
|
+
100 USD = 85.00 EUR
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
**Tool Discovery:**
|
|
435
|
+
|
|
436
|
+
PatchPal discovers tools from `~/.patchpal/tools/*.py` at startup. All `.py` files are scanned for valid tool functions.
|
|
437
|
+
|
|
438
|
+
**What Gets Loaded:**
|
|
439
|
+
- ✅ Functions with type hints and docstrings
|
|
440
|
+
- ✅ Multiple functions per file
|
|
441
|
+
- ✅ Files can import standard libraries
|
|
442
|
+
- ❌ Functions without type hints
|
|
443
|
+
- ❌ Functions without docstrings
|
|
444
|
+
- ❌ Private functions (starting with `_`)
|
|
445
|
+
- ❌ Imported functions (must be defined in the file)
|
|
446
|
+
|
|
447
|
+
**Example Tools:**
|
|
448
|
+
|
|
449
|
+
The repository includes [example tools](https://github.com/amaiya/patchpal/tree/main/examples/tools):
|
|
450
|
+
- **calculator.py**: Basic arithmetic (add, subtract, multiply, divide), temperature conversion, percentage calculations
|
|
451
|
+
- Demonstrates different numeric types (int, float)
|
|
452
|
+
- Shows proper formatting of results for LLM consumption
|
|
453
|
+
- Examples: `add`, `subtract`, `multiply`, `divide`, `calculate_percentage`, `fahrenheit_to_celsius`
|
|
454
|
+
|
|
455
|
+
View the [examples/tools/](https://github.com/amaiya/patchpal/tree/main/examples/tools) directory for complete examples and a detailed README.
|
|
456
|
+
|
|
457
|
+
**Security Note:**
|
|
458
|
+
|
|
459
|
+
⚠️ Custom tools execute arbitrary Python code on your system. Only install tools from sources you trust.
|
|
460
|
+
|
|
461
|
+
- Tools are only loaded from `~/.patchpal/tools/` (your home directory)
|
|
462
|
+
- Project-local tools (`.patchpal/tools/`) are **not supported** for security
|
|
463
|
+
- This prevents accidental execution of untrusted code from repositories
|
|
464
|
+
|
|
465
|
+
**Advanced Features:**
|
|
466
|
+
|
|
467
|
+
**Optional Parameters:**
|
|
468
|
+
```python
|
|
469
|
+
from typing import Optional
|
|
470
|
+
|
|
471
|
+
def greet(name: str, greeting: Optional[str] = "Hello") -> str:
|
|
472
|
+
"""Greet someone.
|
|
473
|
+
|
|
474
|
+
Args:
|
|
475
|
+
name: Person's name
|
|
476
|
+
greeting: Optional greeting message (default: "Hello")
|
|
477
|
+
"""
|
|
478
|
+
return f"{greeting}, {name}!"
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
**Complex Types:**
|
|
482
|
+
```python
|
|
483
|
+
from typing import List
|
|
484
|
+
|
|
485
|
+
def sum_numbers(numbers: List[int]) -> str:
|
|
486
|
+
"""Sum a list of numbers.
|
|
487
|
+
|
|
488
|
+
Args:
|
|
489
|
+
numbers: List of integers to sum
|
|
490
|
+
"""
|
|
491
|
+
total = sum(numbers)
|
|
492
|
+
return f"Sum of {numbers} = {total}"
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
**Python API:**
|
|
496
|
+
|
|
497
|
+
Custom tools can also be used programmatically:
|
|
498
|
+
|
|
499
|
+
```python
|
|
500
|
+
from patchpal.agent import create_agent
|
|
501
|
+
|
|
502
|
+
def calculator(x: int, y: int) -> str:
|
|
503
|
+
"""Add two numbers.
|
|
504
|
+
|
|
505
|
+
Args:
|
|
506
|
+
x: First number
|
|
507
|
+
y: Second number
|
|
508
|
+
"""
|
|
509
|
+
return str(x + y)
|
|
510
|
+
|
|
511
|
+
# Create agent with custom tools
|
|
512
|
+
agent = create_agent(custom_tools=[calculator])
|
|
513
|
+
response = agent.run("What's 5 + 3?")
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
See the [Python API](https://github.com/amaiya/patchpal?tab=readme-ov-file#python-api) section for more details.
|
|
517
|
+
|
|
518
|
+
**Troubleshooting:**
|
|
519
|
+
|
|
520
|
+
If tools aren't loading:
|
|
521
|
+
1. Check the file has a `.py` extension
|
|
522
|
+
2. Ensure functions have type hints for all parameters
|
|
523
|
+
3. Verify docstrings follow Google style (with Args: section)
|
|
524
|
+
4. Look for warning messages when starting PatchPal
|
|
525
|
+
5. Test the function directly in Python to check for syntax errors
|
|
526
|
+
|
|
310
527
|
## Model Configuration
|
|
311
528
|
|
|
312
529
|
PatchPal supports any LiteLLM-compatible model. You can configure the model in three ways (in order of priority):
|
|
313
530
|
|
|
314
531
|
### 1. Command-line Argument
|
|
315
532
|
```bash
|
|
316
|
-
patchpal --model openai/gpt-5
|
|
533
|
+
patchpal --model openai/gpt-5.2
|
|
317
534
|
patchpal --model anthropic/claude-sonnet-4-5
|
|
318
535
|
patchpal --model hosted_vllm/openai/gpt-oss-20b # local model - no API charges
|
|
319
536
|
```
|
|
320
537
|
|
|
321
538
|
### 2. Environment Variable
|
|
322
539
|
```bash
|
|
323
|
-
export PATCHPAL_MODEL=openai/gpt-5
|
|
540
|
+
export PATCHPAL_MODEL=openai/gpt-5.2
|
|
324
541
|
patchpal
|
|
325
542
|
```
|
|
326
543
|
|
|
@@ -332,7 +549,7 @@ If no model is specified, PatchPal uses `anthropic/claude-sonnet-4-5` (Claude So
|
|
|
332
549
|
PatchPal works with any model supported by LiteLLM, including:
|
|
333
550
|
|
|
334
551
|
- **Anthropic** (Recommended): `anthropic/claude-sonnet-4-5`, `anthropic/claude-opus-4-5`, `anthropic/claude-3-7-sonnet-latest`
|
|
335
|
-
- **OpenAI**: `openai/gpt-5`, `openai/gpt-
|
|
552
|
+
- **OpenAI**: `openai/gpt-5.2`, `openai/gpt-5-mini`
|
|
336
553
|
- **AWS Bedrock**: `bedrock/anthropic.claude-sonnet-4-5-v1:0`
|
|
337
554
|
- **vLLM (Local)** (Recommended for local): See vLLM section below for setup
|
|
338
555
|
- **Ollama (Local)**: See Ollama section below for setup
|
|
@@ -668,6 +885,163 @@ The agent will process your request and show you the results. You can continue w
|
|
|
668
885
|
- **Interrupt Agent**: Press `Ctrl-C` during agent execution to stop the current task without exiting PatchPal
|
|
669
886
|
- **Exit**: Type `exit`, `quit`, or press `Ctrl-C` at the prompt to exit PatchPal
|
|
670
887
|
|
|
888
|
+
## Python API
|
|
889
|
+
|
|
890
|
+
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.
|
|
891
|
+
|
|
892
|
+
**Basic Usage:**
|
|
893
|
+
|
|
894
|
+
```python
|
|
895
|
+
from patchpal.agent import create_agent
|
|
896
|
+
|
|
897
|
+
# Create an agent (uses default model or PATCHPAL_MODEL env var)
|
|
898
|
+
agent = create_agent()
|
|
899
|
+
|
|
900
|
+
# Or specify a model explicitly
|
|
901
|
+
agent = create_agent(model_id="anthropic/claude-sonnet-4_5")
|
|
902
|
+
|
|
903
|
+
# Run the agent on a task
|
|
904
|
+
response = agent.run("List all Python files in this directory")
|
|
905
|
+
print(response)
|
|
906
|
+
|
|
907
|
+
# Continue the conversation (history is maintained)
|
|
908
|
+
response = agent.run("Now read the main agent file")
|
|
909
|
+
print(response)
|
|
910
|
+
```
|
|
911
|
+
|
|
912
|
+
**Adding Custom Tools:**
|
|
913
|
+
|
|
914
|
+
Custom tools can be used in two ways:
|
|
915
|
+
|
|
916
|
+
1. **CLI**: Place `.py` files in `~/.patchpal/tools/` (auto-discovered at startup)
|
|
917
|
+
2. **Python API**: Pass functions directly to `create_agent(custom_tools=[...])`
|
|
918
|
+
|
|
919
|
+
Both methods use the same tool schema auto-generation from Python functions with type hints and docstrings:
|
|
920
|
+
|
|
921
|
+
```python
|
|
922
|
+
from patchpal.agent import create_agent
|
|
923
|
+
|
|
924
|
+
def calculator(x: int, y: int, operation: str = "add") -> str:
|
|
925
|
+
"""Perform basic arithmetic operations.
|
|
926
|
+
|
|
927
|
+
Args:
|
|
928
|
+
x: First number
|
|
929
|
+
y: Second number
|
|
930
|
+
operation: Operation to perform (add, subtract, multiply, divide)
|
|
931
|
+
|
|
932
|
+
Returns:
|
|
933
|
+
Result as a string
|
|
934
|
+
"""
|
|
935
|
+
if operation == "add":
|
|
936
|
+
return f"{x} + {y} = {x + y}"
|
|
937
|
+
elif operation == "subtract":
|
|
938
|
+
return f"{x} - {y} = {x - y}"
|
|
939
|
+
elif operation == "multiply":
|
|
940
|
+
return f"{x} * {y} = {x * y}"
|
|
941
|
+
elif operation == "divide":
|
|
942
|
+
if y == 0:
|
|
943
|
+
return "Error: Cannot divide by zero"
|
|
944
|
+
return f"{x} / {y} = {x / y}"
|
|
945
|
+
return "Unknown operation"
|
|
946
|
+
|
|
947
|
+
|
|
948
|
+
def get_weather(city: str, units: str = "celsius") -> str:
|
|
949
|
+
"""Get weather information for a city.
|
|
950
|
+
|
|
951
|
+
Args:
|
|
952
|
+
city: Name of the city
|
|
953
|
+
units: Temperature units (celsius or fahrenheit)
|
|
954
|
+
|
|
955
|
+
Returns:
|
|
956
|
+
Weather information string
|
|
957
|
+
"""
|
|
958
|
+
# Your implementation here (API call, etc.)
|
|
959
|
+
return f"Weather in {city}: 22°{units[0].upper()}, Sunny"
|
|
960
|
+
|
|
961
|
+
|
|
962
|
+
# Create agent with custom tools
|
|
963
|
+
agent = create_agent(
|
|
964
|
+
model_id="anthropic/claude-sonnet-4-5",
|
|
965
|
+
custom_tools=[calculator, get_weather]
|
|
966
|
+
)
|
|
967
|
+
|
|
968
|
+
# Use the agent - it will call your custom tools when appropriate
|
|
969
|
+
response = agent.run("What's 15 multiplied by 23?")
|
|
970
|
+
print(response)
|
|
971
|
+
|
|
972
|
+
response = agent.run("What's the weather in Paris?")
|
|
973
|
+
print(response)
|
|
974
|
+
```
|
|
975
|
+
|
|
976
|
+
**Key Points:**
|
|
977
|
+
- Custom tools are automatically converted to LLM tool schemas
|
|
978
|
+
- Functions should have type hints and Google-style docstrings
|
|
979
|
+
- The agent will call your functions when appropriate
|
|
980
|
+
- Tool execution follows the same permission system as built-in tools
|
|
981
|
+
|
|
982
|
+
**Advanced Usage:**
|
|
983
|
+
|
|
984
|
+
```python
|
|
985
|
+
from patchpal.agent import PatchPalAgent
|
|
986
|
+
|
|
987
|
+
# Create agent with custom configuration
|
|
988
|
+
agent = PatchPalAgent(model_id="anthropic/claude-sonnet-4-5")
|
|
989
|
+
|
|
990
|
+
# Set custom max iterations for complex tasks
|
|
991
|
+
response = agent.run("Refactor the entire codebase", max_iterations=200)
|
|
992
|
+
|
|
993
|
+
# Access conversation history
|
|
994
|
+
print(f"Messages in history: {len(agent.messages)}")
|
|
995
|
+
|
|
996
|
+
# Check context window usage
|
|
997
|
+
stats = agent.context_manager.get_usage_stats(agent.messages)
|
|
998
|
+
print(f"Token usage: {stats['total_tokens']:,} / {stats['context_limit']:,}")
|
|
999
|
+
print(f"Usage: {stats['usage_percent']}%")
|
|
1000
|
+
|
|
1001
|
+
# Manually trigger compaction if needed
|
|
1002
|
+
if agent.context_manager.needs_compaction(agent.messages):
|
|
1003
|
+
agent._perform_auto_compaction()
|
|
1004
|
+
|
|
1005
|
+
# Track API costs (cumulative token counts across session)
|
|
1006
|
+
print(f"Total LLM calls: {agent.total_llm_calls}")
|
|
1007
|
+
print(f"Cumulative input tokens: {agent.cumulative_input_tokens:,}")
|
|
1008
|
+
print(f"Cumulative output tokens: {agent.cumulative_output_tokens:,}")
|
|
1009
|
+
print(f"Total tokens: {agent.cumulative_input_tokens + agent.cumulative_output_tokens:,}")
|
|
1010
|
+
```
|
|
1011
|
+
|
|
1012
|
+
**Use Cases:**
|
|
1013
|
+
- **Interactive debugging**: Use in Jupyter notebooks for hands-on debugging with agent assistance
|
|
1014
|
+
- **Automation scripts**: Build scripts that use the agent for complex tasks with human oversight
|
|
1015
|
+
- **Custom workflows**: Integrate PatchPal into your own tools and pipelines
|
|
1016
|
+
- **Code review assistance**: Programmatic code analysis with permission controls
|
|
1017
|
+
- **Batch processing**: Process multiple tasks programmatically while maintaining control
|
|
1018
|
+
- **Testing and evaluation**: Test agent behavior with different prompts and configurations
|
|
1019
|
+
|
|
1020
|
+
**Key Features:**
|
|
1021
|
+
- **Human-in-the-loop design**: Permission prompts ensure human oversight (unlike fully autonomous frameworks)
|
|
1022
|
+
- **Stateful conversations**: Agent maintains full conversation history
|
|
1023
|
+
- **Custom tools**: Add your own Python functions (via CLI auto-discovery or API parameter) with automatic schema generation
|
|
1024
|
+
- **Automatic context management**: Auto-compaction works the same as CLI
|
|
1025
|
+
- **All built-in tools available**: File operations, git, web search, skills, etc.
|
|
1026
|
+
- **Model flexibility**: Works with any LiteLLM-compatible model
|
|
1027
|
+
- **Token tracking**: Monitor API usage and costs in real-time
|
|
1028
|
+
- **Environment variables respected**: All `PATCHPAL_*` settings apply
|
|
1029
|
+
|
|
1030
|
+
**PatchPal vs. Other Agent Frameworks:**
|
|
1031
|
+
|
|
1032
|
+
Unlike fully autonomous agent frameworks (e.g., smolagents, autogen), PatchPal is explicitly designed for **human-in-the-loop workflows**:
|
|
1033
|
+
|
|
1034
|
+
| Feature | PatchPal | Autonomous Frameworks |
|
|
1035
|
+
|---------|----------|----------------------|
|
|
1036
|
+
| **Design Philosophy** | Human oversight & control | Autonomous execution |
|
|
1037
|
+
| **Permission System** | Interactive prompts for sensitive operations | Typically no prompts |
|
|
1038
|
+
| **Primary Use Case** | Code assistance, debugging, interactive tasks | Automated workflows, batch processing |
|
|
1039
|
+
| **Safety Model** | Write boundary protection, command blocking | Varies by framework |
|
|
1040
|
+
| **Custom Tools** | Yes, with automatic schema generation | Yes (varies by framework) |
|
|
1041
|
+
| **Best For** | Developers who want AI assistance with control | Automation, research, agent benchmarks |
|
|
1042
|
+
|
|
1043
|
+
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.
|
|
1044
|
+
|
|
671
1045
|
## Configuration
|
|
672
1046
|
|
|
673
1047
|
PatchPal can be configured through `PATCHPAL_*` environment variables to customize behavior, security, and performance.
|
|
@@ -675,7 +1049,7 @@ PatchPal can be configured through `PATCHPAL_*` environment variables to customi
|
|
|
675
1049
|
### Model Selection
|
|
676
1050
|
|
|
677
1051
|
```bash
|
|
678
|
-
export PATCHPAL_MODEL=openai/gpt-
|
|
1052
|
+
export PATCHPAL_MODEL=openai/gpt-5.2 # Override default model
|
|
679
1053
|
# Priority: CLI arg > PATCHPAL_MODEL env var > default (anthropic/claude-sonnet-4-5)
|
|
680
1054
|
```
|
|
681
1055
|
|
|
@@ -687,11 +1061,12 @@ export PATCHPAL_REQUIRE_PERMISSION=true # Prompt before executing commands/
|
|
|
687
1061
|
# ⚠️ WARNING: Setting to false disables prompts - only use in trusted environments
|
|
688
1062
|
|
|
689
1063
|
# File Safety
|
|
690
|
-
export PATCHPAL_MAX_FILE_SIZE=
|
|
1064
|
+
export PATCHPAL_MAX_FILE_SIZE=512000 # Maximum file size in bytes for read/write (default: 500KB)
|
|
1065
|
+
# Reduced from 10MB to prevent context window explosions
|
|
691
1066
|
export PATCHPAL_READ_ONLY=true # Prevent ALL file modifications (default: false)
|
|
692
|
-
|
|
1067
|
+
# Useful for: code review, exploration, security audits
|
|
693
1068
|
export PATCHPAL_ALLOW_SENSITIVE=true # Allow access to .env, credentials (default: false - blocked)
|
|
694
|
-
|
|
1069
|
+
# Only enable with test/dummy credentials
|
|
695
1070
|
|
|
696
1071
|
# Command Safety
|
|
697
1072
|
export PATCHPAL_ALLOW_SUDO=true # Allow sudo/privilege escalation (default: false - blocked)
|
|
@@ -734,6 +1109,16 @@ export PATCHPAL_PRUNE_MINIMUM=20000 # Minimum tokens to prune (default:
|
|
|
734
1109
|
# Enable/Disable Web Access
|
|
735
1110
|
export PATCHPAL_ENABLE_WEB=false # Disable web search/fetch for air-gapped environments (default: true)
|
|
736
1111
|
|
|
1112
|
+
# SSL Certificate Verification (for web_search)
|
|
1113
|
+
export PATCHPAL_VERIFY_SSL=true # SSL verification for web searches (default: true)
|
|
1114
|
+
# Set to 'false' to disable (not recommended for production)
|
|
1115
|
+
# Or set to path of CA bundle file for corporate certificates
|
|
1116
|
+
# Auto-detects SSL_CERT_FILE and REQUESTS_CA_BUNDLE if not set
|
|
1117
|
+
# Examples:
|
|
1118
|
+
# export PATCHPAL_VERIFY_SSL=false # Disable verification
|
|
1119
|
+
# export PATCHPAL_VERIFY_SSL=/path/to/ca-bundle.crt # Custom CA bundle
|
|
1120
|
+
# (Leave unset to auto-detect from SSL_CERT_FILE/REQUESTS_CA_BUNDLE)
|
|
1121
|
+
|
|
737
1122
|
# Web Request Limits
|
|
738
1123
|
export PATCHPAL_WEB_TIMEOUT=60 # Web request timeout in seconds (default: 30)
|
|
739
1124
|
export PATCHPAL_MAX_WEB_SIZE=10485760 # Max web content size in bytes (default: 5MB)
|
|
@@ -823,7 +1208,7 @@ PatchPal includes comprehensive security protections enabled by default:
|
|
|
823
1208
|
**Critical Security:**
|
|
824
1209
|
- **Permission prompts**: Agent asks for permission before executing commands or modifying files (like Claude Code)
|
|
825
1210
|
- **Sensitive file protection**: Blocks access to `.env`, credentials, API keys
|
|
826
|
-
- **File size limits**: Prevents OOM with configurable size limits (
|
|
1211
|
+
- **File size limits**: Prevents OOM and context explosions with configurable size limits (500KB default)
|
|
827
1212
|
- **Binary file detection**: Blocks reading non-text files
|
|
828
1213
|
- **Critical file warnings**: Warns when modifying infrastructure files (package.json, Dockerfile, etc.)
|
|
829
1214
|
- **Read-only mode**: Optional mode that prevents all modifications
|
|
@@ -1085,7 +1470,7 @@ When using cloud LLM providers (Anthropic, OpenAI, etc.), token usage directly i
|
|
|
1085
1470
|
- Use less expensive models for routine tasks:
|
|
1086
1471
|
```bash
|
|
1087
1472
|
patchpal --model anthropic/claude-3-7-sonnet-latest # Cheaper than claude-sonnet-4-5
|
|
1088
|
-
patchpal --model openai/gpt-
|
|
1473
|
+
patchpal --model openai/gpt-5-mini # Cheaper than gpt-5.2
|
|
1089
1474
|
```
|
|
1090
1475
|
- Reserve premium models for complex reasoning tasks
|
|
1091
1476
|
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
patchpal/__init__.py,sha256=4rzkvbbI76tGtYc-FRxKp_3NVJ9XF1eClqPickmGQDE,606
|
|
2
|
+
patchpal/agent.py,sha256=oNw7QzIBmFE4XAN_3n1vcsx-wyHZBKcnwX_D9K62KHQ,66789
|
|
3
|
+
patchpal/cli.py,sha256=wzZtAHuTDXFsGWrUuvDh0vf7IKOmAk2nP_drUb-3vQE,27056
|
|
4
|
+
patchpal/context.py,sha256=hdTUvyAXXUP47JY1Q3YJDU7noGAcHuBGlNuU272Fjp4,14831
|
|
5
|
+
patchpal/permissions.py,sha256=pVlzit2KFmCpfcbHrHhjPA0LPka04wOtaQdZCf3CCa0,10781
|
|
6
|
+
patchpal/skills.py,sha256=ESLPHkDI8DH4mnAbN8mIcbZ6Bis4vCcqS_NjlYPNCOs,3926
|
|
7
|
+
patchpal/system_prompt.md,sha256=LQzcILr41s65hk7JjaX_WzjUHBHCazVSrx_F_ErqTmA,10850
|
|
8
|
+
patchpal/tool_schema.py,sha256=dGEGYV160G9c7EnSMtnbQ_mYuoR1n6PHHE8T20BriYE,8357
|
|
9
|
+
patchpal/tools.py,sha256=eZ5eh8DKYyqO95Vdu-tn1_6-W6OsBbY4JL5APGyp-tc,94018
|
|
10
|
+
patchpal-0.7.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
|
|
11
|
+
patchpal-0.7.1.dist-info/METADATA,sha256=LUA1x8Rp2HQ_YZkOa64UD4LjvjPvV3ne52m7wigzxCE,58247
|
|
12
|
+
patchpal-0.7.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
|
|
13
|
+
patchpal-0.7.1.dist-info/entry_points.txt,sha256=XcuQikKu5i8Sd8AfHLuKxSE2RWByInTcQgWpP61sr48,47
|
|
14
|
+
patchpal-0.7.1.dist-info/top_level.txt,sha256=YWgv2F-_PIHCu-sF3AF8N1ut5_FbOT-VV6HB70pGSQ8,9
|
|
15
|
+
patchpal-0.7.1.dist-info/RECORD,,
|
patchpal-0.4.5.dist-info/RECORD
DELETED
|
@@ -1,14 +0,0 @@
|
|
|
1
|
-
patchpal/__init__.py,sha256=BZKk70eNcw6BLNVrj1TWs91vUTXbRMaHOHObNttZgrM,606
|
|
2
|
-
patchpal/agent.py,sha256=uO-MA1ptt2FdpXrrbo07vVIPQj3radcIwP5izdjzmkQ,55519
|
|
3
|
-
patchpal/cli.py,sha256=6UKoMxtow6Xd643vQ89tb6podepAgU1TjGlE2p8FFzE,23352
|
|
4
|
-
patchpal/context.py,sha256=hdTUvyAXXUP47JY1Q3YJDU7noGAcHuBGlNuU272Fjp4,14831
|
|
5
|
-
patchpal/permissions.py,sha256=pVlzit2KFmCpfcbHrHhjPA0LPka04wOtaQdZCf3CCa0,10781
|
|
6
|
-
patchpal/skills.py,sha256=ESLPHkDI8DH4mnAbN8mIcbZ6Bis4vCcqS_NjlYPNCOs,3926
|
|
7
|
-
patchpal/system_prompt.md,sha256=LQzcILr41s65hk7JjaX_WzjUHBHCazVSrx_F_ErqTmA,10850
|
|
8
|
-
patchpal/tools.py,sha256=6zynI83wW6hwddIDKCYVRK8ICprj93bopp0K60PabS8,93042
|
|
9
|
-
patchpal-0.4.5.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
|
|
10
|
-
patchpal-0.4.5.dist-info/METADATA,sha256=9J5IPsOWx0OTPkghGpE6tF-6CnchyBJYFL_DBLr-uIA,44203
|
|
11
|
-
patchpal-0.4.5.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
|
|
12
|
-
patchpal-0.4.5.dist-info/entry_points.txt,sha256=XcuQikKu5i8Sd8AfHLuKxSE2RWByInTcQgWpP61sr48,47
|
|
13
|
-
patchpal-0.4.5.dist-info/top_level.txt,sha256=YWgv2F-_PIHCu-sF3AF8N1ut5_FbOT-VV6HB70pGSQ8,9
|
|
14
|
-
patchpal-0.4.5.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|