Angrist
"As Angrist carved the Silmaril from the Iron Crown of Morgoth: excise the flaw, preserve the tree."
A micro-agent CLI and Python library for targeted Python bug repairs using LLMs. Constrains every model edit to a single AST node and validates each patch in an isolated Git worktree before it touches your codebase.
Key Highlights
Hard AST Scope Lock: Tree-sitter parses the file and extracts only the target function or method. When the model returns a patch, Angrist byte-level verifies that every character outside the target node is identical to the original.
Git Worktree Isolation: Patches are applied, tested, and linted inside a throwaway Git worktree. Your working tree and uncommitted changes are never modified, and the sandbox is destroyed on exit.
Delta Regression Gating: A candidate patch must pass the full test suite and introduce zero new lint findings compared to the pre-patch baseline. Both gates are verified independently before any merge is allowed.
Model Agnostic: Connects to any OpenAI-compatible endpoint. Run locally with Ollama or vLLM using open-weights models, or connect to Groq and OpenAI without changing your workflow.
Zero Infrastructure: No daemon, no background service, no persistent process. Invoke it once per target and it exits cleanly.
Installation
# Recommended via uv
uv tool install angrist
# Or via pipx
pipx install angrist
# Or standard pip
pip install angrist
Requirements: Python 3.11+, Git 2.20+
Configuration
Angrist resolves credentials in order: CLI flags > environment variables > .env file > defaults.
Copy .env.example to .env and point it at your provider:
# Default: Groq (free and fast)
ANGRIST_LLM_BASE_URL=https://api.groq.com/openai/v1
ANGRIST_LLM_API_KEY=gsk_your_groq_api_key
ANGRIST_LLM_MODEL=llama-3.3-70b-versatile
# Local Ollama
# ANGRIST_LLM_BASE_URL=http://localhost:11434/v1
# ANGRIST_LLM_MODEL=qwen2.5-coder:7b
# Local vLLM
# ANGRIST_LLM_BASE_URL=http://localhost:8000/v1
# ANGRIST_LLM_MODEL=deepseek-ai/DeepSeek-Coder-V2-Lite-Instruct
Quickstart
1. Fix a Function or Method
Target a specific function or class method. Angrist extracts only that node, sends it to the model, applies the patch in a worktree, and runs your test suite before reporting the result:
angrist fix \
--file src/payment_processor.py \
--target PaymentProcessor.settle_batch \
--instruction "Fix fee deduction precedence and update transaction status" \
--test-cmd "pytest tests/test_payment_processor.py"
2. Automatic Safe Merge
Once all gates pass, merge the verified patch directly into your current branch:
angrist fix \
--file src/auth.py \
--target authenticate_user \
--instruction "Reject tokens past their expiry timestamp" \
--auto-merge
3. Run SWE-bench Lite Benchmark
Evaluate Angrist against 10 curated real-world bug instances from major open-source repositories:
angrist benchmark
4. Version and Help
angrist --version
angrist fix --help
python -m angrist --help
Python API
from angrist.cli import run_fix
from angrist.patcher import OpenAICompatibleClient
client = OpenAICompatibleClient(
base_url="https://api.groq.com/openai/v1",
api_key="gsk_...",
model="llama-3.3-70b-versatile",
)
result = run_fix(
file_path="src/payment_processor.py",
target="PaymentProcessor.settle_batch",
instruction="Fix fee deduction precedence and update transaction status",
llm_client=client,
test_cmd="pytest tests/test_payment_processor.py",
lint_cmd="ruff check .",
auto_merge=False,
)
if result["status"] == "success":
print(f"Patch on branch: {result['branch']}")
print(result["diff"])
else:
print(f"Rejected: {result['reason']}")
Capabilities and Known Limitations
Supported targets: Logic bugs, boundary conditions, off-by-one errors, type coercion, regex repairs, and any bug expressible as a single-function rewrite. Angrist preserves indentation, comments, and decorators exactly as written.
Out of scope: Multi-file refactors, cross-module import injections, and architecture-level changes. The target function must already exist and parse cleanly through Tree-sitter.
Model quality dependency: The patch quality is bounded by the model's ability to follow scope constraints. Strongly-scoped, single-task instructions produce better results than vague descriptions.
Test command dependency: Gates require a working baseline test command. If the baseline already fails, Angrist aborts before invoking the model.
Benchmark Results
Evaluated against openai/gpt-oss-120b via Groq across 10 real-world bug instances from SWE-bench Lite:
| Instance | Target | Status | Duration |
|---|---|---|---|
psf__requests-1142 |
PreparedRequest.prepare_url |
PASS | 2.52s |
marshmallow__marshmallow-1343 |
Schema._do_load |
PASS | 2.50s |
pallets__flask-4045 |
Blueprint.add_url_rule |
PASS | 2.52s |
django__django-11099 |
ASCIIUsernameValidator |
PASS | 2.15s |
pallets__flask-4992 |
Config.from_file |
PASS | 3.16s |
pylint-dev__pylint-5859 |
EncodingChecker.open |
PASS | 2.04s |
pytest-dev__pytest-11148 |
import_path |
FAIL | 4.72s |
django__django-11049 |
DurationField.get_error_message |
FAIL | 2.94s |
sphinx-doc__sphinx-10325 |
inherited_members_option |
PASS | 3.29s |
psf__requests-1963 |
SessionRedirect.resolve_redirect_method |
PASS | 2.58s |
80.0% pass rate (8/10). Both failures were cleanly rejected by the delta test gate before reaching the merge step.
Resources and Links
GitHub Repository: https://github.com/flxhrdyn/angrist
Demo Script: https://github.com/flxhrdyn/angrist/blob/main/demo/README.md
SWE-bench Benchmark Instances: https://github.com/flxhrdyn/angrist/tree/main/benchmarks/swe_bench
License: MIT License
Metadata
Release files for angrist 0.1.3
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 |
|---|---|---|---|---|
| angrist-0.1.3.tar.gz | 37.1 kB | With provenance | Details for angrist-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| angrist-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for angrist-0.1.3-py3-none-any.whl |
Total release size: 60.3 kB
Release files / angrist-0.1.3.tar.gz
| Download URL | angrist-0.1.3.tar.gz |
|---|---|
| Size | 37.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2668610ac38b07d7b8117c0a7f1af07f561edf8ea9898400331a8b77fa0f64bc
|
|
BLAKE2b-256 checksum How to use checksums |
46e1e2289b5026e8d0a65ff5916478ad99a8d78e1654ddb4c2b84bdcac32a61b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logRelease files / angrist-0.1.3-py3-none-any.whl
| Download URL | angrist-0.1.3-py3-none-any.whl |
|---|---|
| Size | 23.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bab71c8121d643d2b3cfe8b657ba21eb4b6d8fd1e31c8f13187a0cc6003e6774
|
|
BLAKE2b-256 checksum How to use checksums |
9d859ec73d1eb1bb1c6528aa66f388916d9afe3caeec96c8d1b5192de6a6b70b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logSecurity for angrist 0.1.3
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for angrist-0.1.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 3, 2026.
Transparency logA 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.