diff --git a/README.md b/README.md index 2d80ce8..4a0f09c 100644 --- a/README.md +++ b/README.md @@ -1,65 +1,134 @@ # teleo-infrastructure -Pipeline infrastructure for the Teleo collective knowledge base. Async Python daemon that extracts, validates, evaluates, and merges claims via Forgejo PRs. +This repo runs the pipeline that processes contributions into the +[teleo-codex](https://github.com/living-ip/teleo-codex) knowledge base. -## Directory Structure +Every claim on `main` has been extracted from a source, validated for schema +and duplicates, evaluated by at least two independent reviewers, and merged +through an event-sourced audit log. The whole flow is an async Python daemon +talking to a Forgejo git server, an SQLite WAL state store, OpenRouter (for +most LLM calls), and the Anthropic Claude CLI (for Opus deep reviews). +**Production state** (live): + +| Metric | Value | +|---|---| +| Claims merged into `main` | 1,546 across 13 domains | +| PRs merged through the pipeline | 1,975 | +| Merge throughput (last 7d) | 508 PRs (~73/day) | +| Review approval rate | 94% | +| Cost per merged claim (last 30d) | $0.10 incl. extract + triage + multi-tier review | +| Production agents | 6 (rio, theseus, leo, vida, astra, clay) | + +## Pipeline + +Concurrent stage loops in a single daemon (`teleo-pipeline.py`), coordinated +by SQLite. Circuit breakers cap costs, retry budgets cap attempts, and merges +are serialized per-domain to avoid cross-PR conflicts. + +```mermaid +flowchart LR + Inbox["inbox/queue/"] --> Extract + Extract["Extract
(Sonnet 4.5)"] --> Validate + Validate["Validate
(tier 0, $0)"] --> Evaluate + Evaluate["Evaluate
(tiered, multi-model)"] --> Merge + Merge["Merge
(Forgejo, domain-serial)"] --> Effects + Effects["Effects
cascade · backlinks · reciprocal edges"] ``` -teleo-infrastructure/ -├── teleo-pipeline.py # Daemon entry point -├── reweave.py # Reciprocal edge maintenance -├── lib/ # Pipeline modules (Python package) -├── diagnostics/ # Monitoring dashboard (port 8081) -├── telegram/ # Telegram bot interface -├── deploy/ # Deployment + mirror scripts -├── systemd/ # Service definitions -├── agent-state/ # Cross-session agent state -├── research/ # Nightly research orchestration -├── hermes-agent/ # Hermes agent setup -├── scripts/ # One-off backfills + migrations -├── tests/ # Test suite -└── docs/ # Operational documentation + +If any reviewer rejects, the PR gets a structured rationale and either +re-extraction guidance (for fixable issues) or a terminal close (for +scope or duplicate problems). Approved merges trigger downstream effects: + +- **Cascade** — agents whose beliefs/positions depend on the changed claim get inbox notifications +- **Bidirectional provenance** — `sourced_from:` is stamped on each claim at extraction; the source's `claims_extracted:` list is updated post-merge +- **Reciprocal edges** — when a new claim has `supports: [X]`, X's frontmatter is updated with `supports: [new]` +- **Cross-domain index** — entity mentions across domain boundaries are logged for silo detection + +## Multi-agent review + +Reviews aren't free. Tier classification is deterministic where possible +(changes to `core/` or `foundations/` always go Deep) and otherwise picked +by Haiku based on PR scope. Last 30d distribution: 76% Standard, 21% Light, +2% Deep. + +```mermaid +flowchart TD + PR[New PR] --> Classify{Classify} + Classify -->|"core/, foundations/, challenged"| Deep + Classify -->|default| Standard + Classify -->|single claim, low risk| Light + Light["Light tier
Domain agent only"] --> Result + Standard["Standard tier
Domain agent + Leo (Sonnet 4.5)"] --> Result + Deep["Deep tier
Domain agent + Leo (Opus)"] --> Result + Result{Both approve?} + Result -->|yes| MergeOK[Merge] + Result -->|no| Reject[Structured rejection
+ re-extract guidance] ``` +Domain agents bring domain expertise: **Rio** (internet-finance), **Vida** +(health), **Astra** (space-development), **Clay** (entertainment), +**Theseus** (ai-alignment). **Leo** brings cross-domain consistency on +every PR. Disagreement between the two reviewers surfaces in `audit_log` +and is tracked as a quality signal, not silenced. + +Model diversity isn't cosmetic — same-family models share ~60% of their +errors (Kim et al. ICML 2025). Pipeline mixes Haiku for triage, Gemini 2.5 +Flash for domain review, Sonnet 4.5 for Leo standard, Opus for Leo deep. + +## Contributor flow + +External contributors submit PRs to +[`living-ip/teleo-codex`](https://github.com/living-ip/teleo-codex) on GitHub. +A mirror sync (every 2 minutes) fast-forwards the PR onto Forgejo, where +the pipeline picks it up. From there it's the same flow as agent-authored +PRs — same tiers, same reviewers, same merge rules. + +The contributor-facing guide lives in +[`teleo-codex/CONTRIBUTING.md`](https://github.com/living-ip/teleo-codex/blob/main/CONTRIBUTING.md). + +## Repository layout + +| Directory | What it does | +|-----------------|-----------------------------------------------------------| +| `lib/` | Pipeline modules — config, db, extract, evaluate, merge, cascade | +| `diagnostics/` | Argus monitoring dashboard (4 pages: ops, health, agents, epistemic) | +| `telegram/` | Telegram bot that answers from the knowledge base | +| `research/` | Nightly autonomous research sessions for domain agents | +| `agent-state/` | File-backed state for cross-session agent continuity | +| `deploy/` | Auto-deploy pipeline (Forgejo → working dirs → systemd) | +| `systemd/` | Service definitions for daemon + dashboard + agents | +| `scripts/` | Backfills and one-off migrations | +| `tests/` | pytest suite | +| `docs/` | Architecture specs and operational protocols | + ## Ownership -Each directory has one owning agent. The owner is accountable for correctness and reviews all changes to their section. See `CODEOWNERS` for per-file detail. +Code review authority is enforced by [`CODEOWNERS`](./CODEOWNERS) — every +file has one accountable agent. The high-level map: -| Directory | Owner | What it does | -|-----------|-------|-------------| -| `lib/` (core) | **Ship** | Config, DB, merge, cascade, validation, LLM calls | -| `lib/` (extraction) | **Epimetheus** | Source extraction, entity processing, pre-screening | -| `lib/` (evaluation) | **Leo** | Claim evaluation, analytics, attribution | -| `lib/` (health) | **Argus** | Health checks, search, claim index | -| `diagnostics/` | **Argus** | 4-page dashboard, alerting, vitality metrics | -| `telegram/` | **Ship** | Telegram bot, X integration, retrieval | -| `deploy/` | **Ship** | rsync deploy, GitHub-Forgejo mirror | -| `systemd/` | **Ship** | teleo-pipeline, teleo-diagnostics, teleo-agent@ | -| `agent-state/` | **Ship** | Bootstrap, state library, cascade inbox processor | -| `research/` | **Ship** | Nightly research sessions, prompt templates | -| `scripts/` | **Ship** | Backfills, migrations, one-off maintenance | -| `tests/` | **Ganymede** | pytest suite, integration tests | -| `docs/` | Shared | Architecture, specs, protocols | +- **Ship** — pipeline core, telegram, deploy, agent-state, research, systemd +- **Epimetheus** — extraction (intake, entity processing, pre-screening, post-extract validation) +- **Leo** — evaluation (claim review, analytics, attribution) +- **Argus** — health (diagnostics dashboard, alerting, claim index, search) +- **Ganymede** — tests (pytest suite, integration, code review gate) -## VPS Layout +For active sprint work and per-agent in-flight items, see each agent's +status report in their Pentagon profile. -Runs on Hetzner CAX31 (77.42.65.182) as user `teleo`. - -| VPS Path | Repo Source | Service | -|----------|-------------|---------| -| `/opt/teleo-eval/pipeline/` | `lib/`, `teleo-pipeline.py`, `reweave.py` | teleo-pipeline | -| `/opt/teleo-eval/diagnostics/` | `diagnostics/` | teleo-diagnostics | -| `/opt/teleo-eval/telegram/` | `telegram/` | (manual) | -| `/opt/teleo-eval/agent-state/` | `agent-state/` | (used by research-session.sh) | - -## Quick Start +## Development ```bash -# Run tests pip install -e ".[dev]" pytest - -# Deploy to VPS -./deploy/deploy.sh --dry-run # preview -./deploy/deploy.sh # deploy ``` + +## Operations + +Production deployment runs on a single VPS. Runbook, restart procedures, +secret rotation, and on-call live in the private +[`teleo-ops`](https://github.com/living-ip/teleo-ops) repo (request access). + +## License + +[TBD]