Metadata-Version: 2.4
Name: loreley
Version: 0.7.5a0
Summary: Whole-repository Quality-Diversity optimization for real git codebases.
Project-URL: Homepage, https://NeapolitanIcecream.github.io/loreley/
Project-URL: Repository, https://github.com/NeapolitanIcecream/loreley
Project-URL: Documentation, https://NeapolitanIcecream.github.io/loreley/
Project-URL: Issues, https://github.com/NeapolitanIcecream/loreley/issues
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: dramatiq[redis]>=2.0.0
Requires-Dist: gitpython>=3.1.45
Requires-Dist: httpx>=0.28.1
Requires-Dist: loguru>=0.7.3
Requires-Dist: openai>=2.8.1
Requires-Dist: pathspec>=0.12.1
Requires-Dist: psycopg[binary,pool]>=3.2.12
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: pydantic>=2.12.4
Requires-Dist: ribs>=0.8.3
Requires-Dist: rich>=14.2.0
Requires-Dist: scikit-learn>=1.7.2
Requires-Dist: sqlalchemy>=2.0.44
Requires-Dist: tenacity>=9.1.2
Requires-Dist: typer>=0.21.1
Provides-Extra: dev
Requires-Dist: mkdocs-material>=9.7.0; extra == 'dev'
Requires-Dist: pymdown-extensions>=10.17.2; extra == 'dev'
Requires-Dist: pytest>=9.0.1; extra == 'dev'
Provides-Extra: ui
Requires-Dist: fastapi>=0.124.4; extra == 'ui'
Requires-Dist: networkx>=3.6.1; extra == 'ui'
Requires-Dist: pandas>=2.3.3; extra == 'ui'
Requires-Dist: plotly>=6.5.0; extra == 'ui'
Requires-Dist: polars>=1.36.1; extra == 'ui'
Requires-Dist: pyvis>=0.3.2; extra == 'ui'
Requires-Dist: streamlit-aggrid>=1.2.1; extra == 'ui'
Requires-Dist: streamlit>=1.52.1; extra == 'ui'
Requires-Dist: uvicorn[standard]>=0.38.0; extra == 'ui'
Description-Content-Type: text/markdown

## Loreley

> Whole-repository Quality‑Diversity optimization for real git codebases.

Loreley is a distributed system that **evolves entire git repositories** (the unit of search is a git commit). It continuously samples base commits, asks external planning/coding agents to implement repo-wide changes, evaluates the result with your evaluator, and stores metrics plus a MAP‑Elites archive in Postgres for later sampling and reuse.

![](./docs/assets/loreley.svg)

### Why use it

- **Whole-repo evolution**: cross-module refactors and “production-style” changes are first-class.
- **QD-native (MAP-Elites)**: keeps multiple high-performing but *different* solutions instead of a single champion line.
- **Learned behaviour space**: behaviour descriptors come from repo-state code embeddings (cached by git blob SHA), not hand-crafted heuristics.
- **Production loop**: scheduler + Redis/Dramatiq workers + Postgres, with preflight checks, logs, and reproducible git history.

### Quick start (local)

**Requirements**: Python 3.11+, [`uv`](https://github.com/astral-sh/uv), Git (worktrees), PostgreSQL, Redis, and an OpenAI-compatible API for embeddings (`OPENAI_API_KEY`). You also need:

- **Planning/coding backend**: default is the `codex` CLI on `PATH` (override via `WORKER_PLANNING_BACKEND` / `WORKER_CODING_BACKEND`).
- **Evaluator plugin**: `WORKER_EVALUATOR_PLUGIN=module:callable` that runs unattended and returns structured metrics.

```bash
git clone <YOUR_FORK_OR_ORIGIN_URL> loreley
cd loreley
uv sync
docker compose up -d postgres redis

cp env.example .env
# Minimal required vars:
# - OPENAI_API_KEY
# - MAPELITES_EXPERIMENT_ROOT_COMMIT=<git commit hash>
# - SCHEDULER_REPO_ROOT=/abs/path/to/your/target-git-checkout
# - WORKER_REPO_REMOTE_URL=<git remote URL with push access>
# - WORKER_EVOLUTION_GLOBAL_GOAL="..."
# - WORKER_EVALUATOR_PLUGIN=module:callable
# - (optional) WORKER_EVALUATOR_PYTHON_PATHS=["/abs/path/to/plugin_dir"]
# - (optional) SCHEDULER_STARTUP_APPROVE=true  # skip interactive startup approval

uv run loreley doctor --role all
uv run loreley scheduler
uv run loreley worker
```

### Optional UI (read-only)

```bash
uv sync --extra ui
uv run loreley ui
```

![](./docs/assets/ui.jpeg)

### Documentation

- [`docs/index.md`](docs/index.md) (local)
- [Online docs](https://NeapolitanIcecream.github.io/loreley/)
- Key guides: [`docs/loreley/config.md`](docs/loreley/config.md), [`docs/script/run_scheduler.md`](docs/script/run_scheduler.md), [`docs/script/run_worker.md`](docs/script/run_worker.md)


