# PRD: MentorCore — Persona Platform

## 1. Executive Summary

MentorCore lets you talk with anyone who ever wrote anything down. Give the system the name of a person — a historical figure, an author, a fictional character, a philosopher, a domain expert — and it seeks out canonical sources (biographies, autobiographies, interviews, podcast appearances, primary writings), compiles them into a persona, and lets you converse with that persona in their philosophy, style, tone, and (where policy allows) their voice.

Interaction is modality-matched: text chat gets text replies; voice gets voice replies. The system is local-first for personal use, with a roadmap toward a publicly accessible persona library.

The product name is **MentorCore** (settled; earlier candidates EchoSage, PersonaLink, VeritasVoice, and Proximal are retired).

## 2. Use Cases

In priority order:

1. **Walking companion.** Voice conversation with a historical figure or philosopher over a Bluetooth headset and phone while walking the dogs — "go for a walk with Marcus Aurelius." This is the MVP scenario: it exercises the full name → sources → persona pipeline plus the voice loop, with relaxed latency constraints (mobile network tolerable).
2. **VR sim-racing pit companion.** Local, low-latency voice conversation inside a PC sim-racing session while wearing a VR headset — one persona (driver coach) or two (driver coach + crew chief), push-to-talk via steering-wheel button mapping, telemetry-aware debriefs during pit stops. Full scenario spec in **Appendix A**. This use case must work; it is the original motivation for the project.
3. **Public tool.** A hosted library of compiled personas that other users can browse and converse with, including requesting compilation of new figures. Lots of pre-processing happens per persona; the library amortizes that cost across users.

## 3. Product Concepts

Three components, decoupled by one artifact (full technical design in `ARCHITECTURE.md`):

- **Persona Compiler** (offline pre-processing): name → source discovery (biography, autobiography, interviews, podcast audio, primary writings, with rights metadata) → acquisition and normalization → indexed knowledge base (RAG) → extracted style/philosophy profile (tone, vocabulary, beliefs, speech patterns, few-shot exemplars) → voice model per policy tier → fidelity evaluation. Output is a versioned **Persona Package**.
- **Persona Runtime** (online): the conversation engine. Retrieval-grounded responses, persona-consistency and misattribution guards ("X wrote" vs "X might say" — never invent quotes), era-knowledge limits (a persona doesn't know events after their death unless configured otherwise), modality matching (STT → LLM → TTS for voice; LLM only for text), and multi-persona sessions with distinct voices and roles.
- **Persona Library**: the catalog of compiled packages. Personal/local personas vs published/public ones, with policy enforcement at the boundary.

## 4. Voice Policy (tiered)

| Tier | What | Where allowed |
|---|---|---|
| **Generated** | Synthetic voice chosen to suit era/character description | Everywhere; default for fictional characters and long-dead figures |
| **Stylized** | Voice matched on accent, era, cadence — evocative, not cloned | Everywhere; the public-tier ceiling absent rights |
| **Cloned (personal)** | Zero-shot clone from reference audio of the real person | Personal/local use only |
| **Cloned (licensed)** | Clone with documented consent/rights | Public, gated on recorded rights in the persona manifest |

Right-of-publicity exposure is the gating legal item for any public launch of cloned voices; the public tier ships stylized-only until rights workflows exist. The cloning engine's non-commercial license (see `DECISIONS.md`) independently restricts cloned output to the personal tier.

## 5. Architecture Modes

- **Local:** Mac Studio (M4) as the inference host; clients (VR PC, desktop browser) on the local network. Preserves privacy and the <2s voice-latency target.
- **Mobile:** phone PWA + BT headset → home server over Tailscale. The dog-walk mode.
- **Public:** hosted compiler and runtime with accounts and the shared library. Requirements-only until the personal product proves out.

LLM strategy is hybrid: Claude API by default (conversation, style extraction, fidelity judging) behind a provider abstraction so the Mac Studio can serve a local model for fully private operation later. Audio (STT/TTS) is local in all modes.

## 6. Phased Roadmap

Detailed punch lists and exit criteria live in `BUILDPLAN.md`.

- **Phase 1 — General persona chat (MVP):** compile one public-domain persona end-to-end from real sources; text + voice chat on desktop and phone; stylized/generated voice; then semi-agentic source discovery.
- **Phase 2 — Racing companion:** push-to-talk, dual persona (coach + crew chief), telemetry hook, cloned voices under the personal tier, LAN latency budget.
- **Phase 3 — Public platform:** persona library, on-demand compile requests with human review, voice-policy enforcement, accounts and sharing.

## 7. Agentic Version

The persona compiler is the agentic system: an unattended compile → evaluate → improve loop. The five preconditions:

| # | Precondition | MentorCore answer |
|---|---|---|
| 1 | **Objective metric** | **Persona fidelity score** — composite of (a) groundedness: claims in responses traceable to the source corpus, and (b) style match: blind LLM-judge comparison of responses against held-out genuine writings/transcripts. Misattribution (fabricated verbatim quotes) is a hard zero-tolerance sub-metric. |
| 2 | **Measurement mechanism** | Automated eval harness (`TESTING.md` §2): ~10% of passages held out at compile time, never indexed; judge model scores groundedness + style per run; scores append to the package's `eval/history.jsonl`. |
| 3 | **Action space** | Re-search for additional sources; re-chunk/re-index; regenerate the style profile and exemplars; adjust retrieval parameters; regenerate the voice config. |
| 4 | **Stopping condition** | Fidelity plateaus over N compile iterations, or the per-persona compute/cost budget is reached. |
| 5 | **Rollback / guardrail** | A persona never ships below threshold (groundedness ≥ 0.7, style ≥ 0.6, misattribution = 0, initial values). Previous package build retained; a recompile that regresses >0.05 fails and rolls back. Public publishing additionally requires a human-review gate and a figure-eligibility safety screen. |

Three tiers:
1. **Simple automation** — hand-curated source lists, scripted ingestion, manual eval review (Phase 1a).
2. **Semi-agentic** — automatic source discovery with human approval of the source list and of publishing (Phase 1d default).
3. **Fully agentic** — the compile-evaluate-improve loop runs unattended to threshold or budget (`mentor compile --auto`).

## 8. Risks & Mitigations

| Risk | Mitigation |
|---|---|
| Misattribution — persona presents invented text as a real quote | Prompt guard + judge check on every quoted span + red-team suite; hard gate at 0 |
| Hallucinated expertise (e.g. impossible car setups) | Groundedness scoring; domain verification layer for racing advice (Appendix A) |
| Persona drift in long conversations | Persona-consistency system prompt, style exemplars, eval includes multi-turn sessions |
| Voice-cloning legal exposure | Tiered policy (§4); stylized-only public tier; rights recorded in the manifest |
| Source licensing/copyright for ingested books | Rights metadata per source; public-domain-first; fair-use excerpting policy needed before Phase 3 |
| Compile cost per persona | Cheap-model bulk extraction + Batches API; cost accounting per package; budget as the agentic stopping condition |
| Latency (voice feels laggy) | Per-stage budget with benchmarks as a build gate; sentence-streaming TTS; local audio stack |
| VR hardware contention (frame drops) | Inference runs on a separate machine from the sim (Appendix A) |

## 9. Appendix A — Sim-Racing Pit Companion (scenario spec)

Preserved from the original draft; this is the Phase 2 specification.

**Topology (edge computing):** a dedicated processing machine (Mac Studio) runs all AI inference; the Windows VR sim PC runs only the game plus a thin client, communicating over the local network. This keeps voice-model inference off the sim machine so VR frame rates are unaffected.

**Interaction:** push-to-talk mapped to a steering-wheel or controller button (the user is in a VR headset and cannot use keyboard/mouse). Voice pipeline: low-latency STT → RAG-grounded persona LLM → high-fidelity TTS in the expert's voice (cloned, personal tier). Real-time conversational turnaround under 2 seconds.

**Personas and hierarchy:** two experts with prioritized roles —
1. *Driver Coach* — primary for driving technique and driver improvement.
2. *Crew Chief* — secondary, for technical setup adjustments grounded in consistent data.

**Dynamic debriefing:** the user describes "feel" by voice (e.g., how the car handles on corner entry); the system correlates that subjective report with telemetry (throttle/brake traces and other data points) ingested via a sim hook during a pit-in pause or on button trigger.

**Experimental feedback loops:** the crew chief proposes a setup change; the user drives and reports back the resulting feel; the system tracks the experiment chain across runs ("we softened the rear bar — how did it feel?").

**Prototype scope (from the original MVP):** single expert (one race-engineer/coach persona) first; fully local with no cloud dependency for privacy; basic telemetry hook; <2s latency.

**Risks specific to this scenario (from the original draft):** the AI suggesting impossible setups (mitigate with a verification/confidence layer over setup advice); losing the persona during long technical explanations; hardware bottlenecks affecting VR frame rate (mitigated by the two-machine topology).