# MentorCore

Name a person → compile a persona from canonical sources → converse with them in their philosophy, style, tone, and (where policy allows) voice. Text or spoken conversation, local-first, phone-capable over Tailscale.

> "Go for a walk with Marcus Aurelius." Or debrief a sim-racing stint with your crew chief.

## How it works

Three components, decoupled by one contract — the **Persona Package** (a versioned directory the compiler writes and the runtime reads):

```
sources/<slug>.yaml     curated/discovered source lists (books, interviews, podcasts)
captures/<slug>/        frontier-model-authored deep distillation (philosophy, style,
                        verified quotes, voice references) — the precious, checked-in tier
        │
        ▼  compiler (offline: acquire → transcribe → index → style → capture-import → eval)
personas/<slug>/        compiled package: corpus, vector index, style profile, voice config
        │
        ▼  runtime (FastAPI: retrieval-grounded chat, STT/TTS voice loop)
web/                    Next.js PWA — text chat + hold-to-talk voice, installable on the phone
```

Fidelity is measured, not vibed: ~10% of genuine passages are held out at compile time and an LLM judge scores every build on groundedness and style-match, with fabricated quotes as a zero-tolerance sub-metric.

## Docs

Read in this order:

| Doc | What |
|---|---|
| [docs/PRD.md](docs/PRD.md) | Product: use cases, voice policy, roadmap, agentic loop spec |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | The Persona Package contract, compiler stages, runtime pipeline, latency budget |
| [docs/PERSONA-CAPTURE.md](docs/PERSONA-CAPTURE.md) | The capture format: model-authored philosophy/style/quotes/voice distillations |
| [docs/BUILDPLAN.md](docs/BUILDPLAN.md) | Phased punch lists — the live progress ledger |
| [docs/TESTING.md](docs/TESTING.md) | Test strategy and the fidelity eval harness |
| [docs/DECISIONS.md](docs/DECISIONS.md) | Why the non-obvious choices were made |

## Quickstart

```bash
./scripts/check.sh                          # lint + offline tests + web build
uv run mentor compile <slug> --propose      # discover sources → human approves
uv run mentor compile <slug> --build        # build the persona package
uv run mentor chat <slug>                   # terminal REPL
uv run uvicorn runtime.api.app:app --reload # API server
cd web && npm run dev                       # web client
```

Requires `uv`, Node 20+, and `ANTHROPIC_API_KEY` for real compiles and chat (tests run offline against a fake provider).

## Voice policy

Cloning a real person's voice is personal-tier only (and the cloning engine is CC-BY-NC); public-facing personas use stylized or generated voices unless documented rights exist. Enforced in code via `voice_policy`, not by convention. Details: PRD §4.