Python SDK

A synchronous, typed Python client for the local engine. Requires Python 3.9+, macOS or Linux, and the native CLI installed separately.

Install from source

python3 -m pip install --upgrade pip
python3 -m pip install 'git+https://github.com/djsydney04/repo_maintainer.git#subdirectory=sdk/python'

The package is not yet published to PyPI. For a pinned install, insert @COMMIT_SHA before #subdirectory. It does not download an engine or make model requests during installation.

from repo_maintainer import Maintainer

maintainer = Maintainer("/path/to/repository")
maintainer.check()
result = maintainer.run("Fix the empty search state and add a regression test.")
print(result.status, result.summary)
print(result.artifacts.patch)

Pass task text, or omit it to use the configured task. For a file:

from pathlib import Path
result = maintainer.run(Path("task.md").read_text(encoding="utf-8"))

Results and errors

A blocked run returns a RunResult, including blockers and any retained partial patch. Catch MaintainerError for missing binaries, invalid configuration, operational failures or incompatible protocol responses.

from repo_maintainer import Maintainer, MaintainerError

try:
    client = Maintainer("/repos/app", binary="/usr/local/bin/repo-maintainer",
                        config=".maintainer/work.yml")
    result = client.run("Repair the documented bug.", output="/jobs/run-42")
    if result.status == "blocked":
        print(result.blockers)
except MaintainerError as error:
    print(error)

Calls block until the engine returns. Agent/check deadlines remain in the repository configuration. The client inherits your worker environment, sends task text over stdin without a shell, and never schedules or publishes work. Do not call it on a web request thread for long-running work; use a background job.

Result fields and validation guarantees.

Configure entirely in Python

Pass a dictionary instead of a file path. No YAML file is loaded:

from repo_maintainer import Maintainer

client = Maintainer("/repos/app", config={
    "version": 2,
    "agent": {"allow_paid": True},
    "instructions": "Keep this repository compatible with its official references.",
    "sources": ["https://developers.openai.com/api/docs/changelog"],
    "official_hosts": ["developers.openai.com"],
    "editable": {"source_dirs": ["src", "tests"], "extensions": [".py"]},
    "validation": {"checks": [
        {"name": "tests", "command": ["python3", "-m", "unittest", "discover"]}
    ]},
})
client.check()
result = client.run("Fix one documented compatibility gap with a regression test.")

Dictionary fields use the same schema, defaults and environment overrides as YAML. The client sends configuration and task over stdin to the native engine. A string config still selects an existing file. Keep configuration trusted; webhook data belongs in task evidence, not executable check commands.

Runnable Python script · Agent setup prompt