Libra

Self-evolving Markdown catalog ("Libra") applied to code localization. The pipeline iteratively:

1. Generates localization Q/A pairs (agents/prompter/)
2. Runs a locator agent that navigates the repo via catalog.md files (agents/locator/)
3. Heals the catalog from locator failures (agents/healer/)
4. Drives the loop and reports metrics (orchestrator/)

See Autoresearch/ for the design notes (Healer Analysis, Healer Prompt, Catalog Initialization, etc.).

Setup

This repo is managed with uv. Install uv (e.g. brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh), then:

uv sync                 # creates .venv/ and installs dependencies from uv.lock
cp .env.example .env    # then fill in values

Activate the environment with source .venv/bin/activate, or prefix any command with uv run to use it without activating.

The repo is configured entirely through environment variables documented in .env.example:

Variable	Purpose
REPO_PATH_PREFIX	Directory under which target repos live, e.g. ./repos/
HF_USER	Your HuggingFace username, used to build repo_id strings
HF_TOKEN	Required for private datasets / pushing
OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL	LLM gateway
OPENAI_TLS_VERIFY	Set to 0 for self-signed gateways
ANTHROPIC_API_KEY	Required for the Claude Agent SDK variant

Layout

.
├── agents/                # Prompter, Locator, Healer agents + shared SDK wrappers
│   ├── agent.py            # Claude Agent SDK wrapper
│   ├── agent_plain.py      # OpenAI-compatible agentic loop
│   ├── locator/            # ant.py + plain.py
│   ├── prompter/           # ant.py + plain.py + PROMPTS.yaml
│   ├── healer/             # healer.py + healer_ant.py + healer_ant_unified.py + healer_crappy.py
│   └── tools/              # read / bash tool dispatchers
├── orchestrator/          # Training loop, evaluation, distillation, plotting
│   ├── train.py
│   ├── train_config.yaml
│   ├── evaluate.py
│   ├── eval_config.yaml
│   ├── distill.py
│   └── train_utils.py
├── scripts/
│   └── replay_test_eval.py
├── llm.py                 # Cached OpenAI-compatible client + retry/streaming
├── utils.py               # HuggingFace upload helpers
├── bench_config.yaml
├── pyproject.toml         # uv-managed project + dependencies
├── uv.lock                # pinned resolution (commit this)
├── .python-version        # interpreter version uv installs
└── .env.example

Each subdirectory has its own CLAUDE.md that explains its agents and design.

Running

Edit orchestrator/eval_config.yaml (single-shot evaluation) or orchestrator/train_config.yaml (full Libra loop), then:

# evaluation only
uv run python -m orchestrator.evaluate

# full training loop
uv run python -m orchestrator.train

For the legacy bench wrapper:

uv run python bench_locate.py [path/to/config.yaml]

To add or upgrade a dependency, use uv add <package> (or uv add --upgrade <package>); both refresh uv.lock automatically.

Notes

• Catalogs (catalog.md files inside the target repo) are the artifact the Healer modifies and the Locator consumes. They live next to the source they describe — co-located, not in a separate index tree.
• The Locator is read-only on the target repo; the Healer commits its catalog edits via git_commit in agents/healer/utils.py.

Disclaimer

This code should not be used to develop models that compete with Anthropic.