Patchling
Formerly gptdiff. Same library, same API —
pip install patchling(thegptdiffpackage still resolves during the transition).
Natural-language code transformation, as a library. Hand Patchling a dict of files and a plain-English goal; get back a unified diff — and, via smartapply, the transformed files. It's a bounded primitive you embed inside your own software systems, not an open-ended coding agent.
from patchling import generate_diff, smartapply, build_environment
files = {"main.py": "def old_name():\n print('Need renaming')\n"}
diff = generate_diff(build_environment(files), "Rename old_name to new_name")
updated = smartapply(diff, files)
print(updated["main.py"])
Files in, files out. No filesystem access required, no agent harness. The hard part — applying an LLM-generated diff that git apply would reject — is what smartapply solves: per-file, AI-assisted patch resolution that survives fuzzy hunks, renames, new files, and deletions.
🌐 Project home: patchling.app — try it live in your browser · 📚 Full documentation at 255bits.github.io/patchling-py
Prefer the browser? The same primitive ships on npm as patchling for JS
(generateDiff + smartapply, zero-dependency ESM) — try the live demos →.
The Patchling family
The same primitive exists for every runtime, and it powers a real product:
| Project | What it is |
|---|---|
| patchling for Python (this repo) | Python library + CLI tools — PyPI |
| patchling for JS | Zero-dependency ESM package for browser and Node — generateDiff + smartapply on in-memory file maps — npm |
| patchling.app | Project homepage with a live in-browser demo of the whole diff → smartapply loop |
| nanoodle.com | Visual AI workflow editor built on patchling — no server, no signup, bring your own key. See the primitive working in production |
| Live demos | Browser examples: LLM-edited games, 3D scenes, stream overlays, AI characters |
Building for the browser? Start with patchling for JS. Building a Python backend, pipeline, or your own agent? You're in the right repo.
Quick Start
1. Install
pip install patchling
Verify the installed CLI version with patchling --version or patchling-apply --version.
2. Set your API key
Works with any OpenAI-compatible endpoint. Get a key at nano-gpt.com/api, or point GPTDIFF_LLM_BASE_URL at your own provider.
# Linux/macOS
export GPTDIFF_LLM_API_KEY='your-api-key'
# Windows
set GPTDIFF_LLM_API_KEY=your-api-key
3. Transform files in your code
from patchling import generate_diff, smartapply, build_environment
files = {
"models.py": "class User:\n name = CharField()",
"tests/test_models.py": "def test_user():\n User(name='Test').save()",
}
diff = generate_diff(
build_environment(files),
"Rename the 'name' field to 'username' across all layers",
)
files = smartapply(diff, files)
The diff is plain unified-diff text — log it, review it, gate it behind approval, or apply it immediately. That's the point: your system stays in control of what changes and when.
See examples/usage_example.py for a runnable version.
Core API
generate_diff(environment: str, goal: str, model: str = ...) -> str— generates a unified diff implementing the goal.modeldefaults to theGPTDIFF_MODELenv var.smartapply(diff_text: str, files: dict[str, str], model: str = ...) -> dict[str, str]— applies a diff with AI-powered conflict resolution. Handles new files, deletions, and hunks that standard patching rejects. Returns a new dict; input is not mutated.build_environment(files: dict[str, str]) -> str— serializes a files dict into the environment stringgenerate_diffexpects. Passfilter_relevant=Trueandtask=to drop files a cheap model marks irrelevant first.filter_relevant(files, task, model=..., concurrency=..., cache=...) -> FilterRelevantResult— opt-in relevance filter for large directories. Each file is sent, with the task, to a cheap OpenAI-compatible model that answers yes/no. Only theyesfiles are returned forgenerate_diffandsmartapply. The default model isxiaomi/mimo-v2.6-flash(Flask recall 1.0 and ~0.8x overhead figures are UNVERIFIED). The JS counterpart isfilterRelevant.load_project_files(path, cwd) -> dict/save_files(files, base_dir)— optional filesystem helpers for when you do want to read/write a real project (respects.gitignoreand.gptignore).
Full signatures, error handling, and edge cases: API Reference.
Pipeline example — sequential transformations over an in-memory codebase:
from patchling import generate_diff, smartapply, build_environment
files = load_your_codebase() # dict of {path: content}
for task in [
"Add python type annotations",
"Convert string formatting to f-strings",
"Update deprecated API calls",
]:
files = smartapply(generate_diff(build_environment(files), task), files)
This is the pattern nanoodle.com runs in the browser (via patchling): each workflow node is a bounded diff→apply step over an in-memory file map, and the app never touches a server.
Choosing a Model
Reasoning models produce more accurate diffs for complex changes; fast models win for applying diffs and simple edits.
| Model | Best for | Notes |
|---|---|---|
deepseek/deepseek-v4.1-flash-1017 |
Generating diffs | Default (DEFAULT_MODEL); $0.10 / $0.60 per 1M tokens |
xiaomi/mimo-v2.6-pro / anthropic/claude-sonnet-4.6 |
Complex or context-sensitive changes | $0.435 / $0.87 and $3 / $15 per 1M tokens |
openai/gpt-5-mini |
Applying diffs (smartapply) |
A cheap choice for the CLI's GPTDIFF_SMARTAPPLY_MODEL (or model= in the library); $0.25 / $2 per 1M tokens |
gemini-2.5-flash-lite |
Simple text changes | $0.10 / $0.40 per 1M tokens |
Ids and prices are from NanoGPT's public model list (https://nano-gpt.com/api/v1/models?detailed=true) as of 2026-10-21. Use --model to select a compatible text-generation model.
export GPTDIFF_MODEL='deepseek/deepseek-v4.1-flash-1017'
export GPTDIFF_SMARTAPPLY_MODEL='openai/gpt-5-mini'
Environment variables
| Variable | Purpose | Default |
|---|---|---|
GPTDIFF_LLM_API_KEY |
API key (required) | — |
GPTDIFF_MODEL |
Model for diff generation | deepseek/deepseek-v4.1-flash-1017 (DEFAULT_MODEL) |
GPTDIFF_SMARTAPPLY_MODEL |
CLI only: model for --apply (--applymodel overrides it) |
openai/gpt-4.1-mini. Never falls back to GPTDIFF_MODEL |
GPTDIFF_LLM_BASE_URL |
OpenAI-compatible endpoint | https://nano-gpt.com/api/v1/ |
GPTDIFF_FILTER_MODEL |
Cheap model for filter_relevant |
xiaomi/mimo-v2.6-flash (Flask recall 1.0 / ~0.8x overhead: UNVERIFIED) |
Command-Line Tools
The library also ships two CLIs for working on a real project directory.
The former command names
gptdiffandgptpatchstill work as aliases forpatchlingandpatchling-apply, so existing scripts don't break.
patchling
Describe a change; Patchling scans the project (respecting .gitignore/.gptignore), generates a diff, and optionally applies it:
| Command | What it does |
|---|---|
patchling "prompt" |
Writes prompt.txt only — preview what would be sent |
patchling "prompt" --call |
Generates the diff into diff.patch for review |
patchling "prompt" --apply |
Generates and applies in one step |
cd your-project
patchling "Add type hints to all functions" --apply
# Target specific paths
patchling "Add logging" src/api/ src/utils/helpers.py
Useful flags: --model, --temperature, --prepend <file> (custom instructions), --image <path> (visual context), --filter-relevant (ask a cheap model which files to send; --filter-model picks that model), --nobeep. Full list: CLI Reference.
Because changes arrive as diffs, the CLI is git-native: review with git diff, keep with git add -p, discard with git checkout ..
patchling-apply
Applies an existing unified diff to a project — standard patch logic first, smartapply fallback when that fails:
patchling-apply path/to/diff.patch
patchling-apply --diff "<diff text>"
Options: --project-dir, --model, --max_tokens, --nobeep. Details: patchling-apply docs.
Agent loops
Because each invocation is bounded (one goal → one diff), the CLI composes into loops:
while true; do
patchling "Add missing test cases for edge conditions" --apply
git add -A && git commit -m "Auto-improvement $(date +%H:%M)" 2>/dev/null
sleep 30
done
One overnight test-coverage loop took a project from 18 to 127 test cases. Recipes and guardrails: Automation Guide.
Testing
pip install -e .[test]
pytest tests/
Documentation
Docs live at 255bits.github.io/patchling-py. To preview locally:
pip install .[docs]
mkdocs serve
Related projects
- patchling.app — project home, with a live in-browser demo
- patchling for JS — the browser/Node package on npm
- nanoodle.com — visual AI workflow editor built on patchling
- patchling live demos
- AI Agent Toolbox — powers Patchling's tool-call parsing across models
MIT licensed. Built by 255labs.
Metadata
Release files for patchling 0.9.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| patchling-0.9.4.tar.gz | 93.0 kB | Without provenance | Details for patchling-0.9.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| patchling-0.9.4-py3-none-any.whl | Python 3 | none | any | Details for patchling-0.9.4-py3-none-any.whl |
Total release size: 145.8 kB
Release files / patchling-0.9.4.tar.gz
| Download URL | patchling-0.9.4.tar.gz |
|---|---|
| Size | 93.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b2834291f9f7911d0c14626c4d79715a94c4d1b6ac00eb14fa9dc2a400c6626d
|
|
BLAKE2b-256 checksum How to use checksums |
c65651148509373379ead269306d605fc9dcd61418c7fb1c3ef49840777b14aa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Release files / patchling-0.9.4-py3-none-any.whl
| Download URL | patchling-0.9.4-py3-none-any.whl |
|---|---|
| Size | 52.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
68aa80bce1a30dce926fcd0358e93e198f93129c568c65a6301aeb352c7be276
|
|
BLAKE2b-256 checksum How to use checksums |
b4821a1827fc8847a7bbc10d5c64f2eb711865843581e74df569054e435fd16b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Security for patchling 0.9.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.