Skip to main content

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.

CI PyPI Python 3.11+ License: MIT

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.

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)

Source distribution for angrist 0.1.3
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)

Table of built distributions (wheels) for angrist 0.1.3
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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.

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page