claude
93987f2dfc
Seventeen markdown files at the repo root, twelve of them dated one-shot reports sitting next to CLAUDE.md. That is why stale docs read as current: nothing in the path said which was which. Root now keeps CLAUDE.md and AGENTS.md. Living docs move under docs/ and carry a Last verified line. Dated measurements move to docs/evals/ ISO-prefixed, and are never edited after the day, so a newer number is a new file. The senior review moves to docs/archive/. Every reference was rewritten across markdown, Go comments, the Makefile and the recall fixture. The touched Go packages still build. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
99 lines
4.6 KiB
Markdown
99 lines
4.6 KiB
Markdown
# Maven — Re-architecture (Qwen3 resident model, revised 2026-07-18)
|
|
|
|
*Last verified: 2026-08-02 @ 7079a24. Living doc: correct it in place, do not append.*
|
|
|
|
> Supersedes the classifier-first routing model. Agreed in a design session
|
|
> after diagnosing that homesrv deploys with a **stub phraser** (no LLM
|
|
> running) and an embedder-classifier that routes by nearest-neighbor between
|
|
> frozen seed phrases — the structural cause of "she messes up queries."
|
|
>
|
|
> Hardware reality: homesrv = Ryzen 5 5600U laptop, Vega iGPU, 14 GB shared
|
|
> RAM. Workstation (RX 7900 XT) is NOT the deploy target and is often busy.
|
|
> So: small models, on-demand where heavy, always-on where cheap.
|
|
|
|
## Principle
|
|
|
|
The LLM is **not** the center of everything. Deterministic tools handle the
|
|
bulk. One locally trained **Qwen3-1.7B** resident model is used for routing and
|
|
talking back. Its system prompt selects one of two independently evaluated
|
|
contracts: route actions or persona responses.
|
|
|
|
**If the router is good, Maven feels good.** Routing is the linchpin.
|
|
|
|
## The spine
|
|
|
|
```
|
|
utterance
|
|
→ [world-state context] cheap: time, presence, calendar_busy, weather (no LLM)
|
|
→ ROUTER = Qwen3-1.7B (always-on, grammar-constrained)
|
|
reads utterance + context + tool schema, emits a STRUCTURED action:
|
|
• call a tool (deterministic) • answer directly
|
|
→ tools (deterministic, fast)
|
|
→ PHRASER = Qwen3-1.7B (same resident process) → TTS / text
|
|
```
|
|
|
|
- **Router = Phraser = one resident Qwen3-1.7B llama-server**, with separate
|
|
route and persona prompts/contracts. Always warm; classifier/stub remain the
|
|
failure floors.
|
|
- The resident checkpoint is trained end-to-end as: Qwen3-1.7B-Base → RU CPT →
|
|
joint persona/router SFT → merge → GGUF. Larger on-demand reasoning models
|
|
are deferred until the main feature set is complete.
|
|
- **Embedder demoted from router to tool** — it now backs `memory.search`
|
|
(RAG) and gives the router a cheap "similar past notes/intents" hint. The
|
|
router no longer depends on it clearing a threshold. Upgrade MiniLM → bge-m3
|
|
for better RU retrieval later (model swap, not architecture).
|
|
|
|
### Router output
|
|
- Constrained structured JSON action `{tool, args, escalate}` — NOT free-form
|
|
multi-step function-calling. Sub-1B is far more reliable emitting a fixed
|
|
schema. Enforce with a **GBNF grammar** in llama.cpp (near-bulletproof).
|
|
- Keep the existing **stage-0 exact-match fast-path** for dead-obvious commands
|
|
(skips the router entirely) — cheap insurance, already built.
|
|
|
|
## The proactive / memory half — one background engine
|
|
|
|
"Take notes," "remember," "reflect," "suggest do you want to add X?", "remind"
|
|
are NOT request-path features. They are one **digestion worker**:
|
|
|
|
```
|
|
DIGESTION WORKER (periodic + event-driven, off the request path)
|
|
• reads new facts/notes since last pass
|
|
• RAG-consolidates: dedupe, link, summarize into durable memory
|
|
• reflects: detect patterns ("mentioned X three times")
|
|
• proposes: "want me to add X / remind you about Y?" → nudge dispatcher
|
|
• surfaces due reminders
|
|
uses the resident Qwen3 model for bounded synthesis — never blocks a turn
|
|
```
|
|
|
|
Notes capture is a deterministic Tier-0 tool; making notes *mean something
|
|
later* is the worker + RAG.
|
|
|
|
## Layer table
|
|
|
|
| Layer | What | Runs |
|
|
|---|---|---|
|
|
| Context | world-state (time/presence/calendar/weather) | always, no LLM |
|
|
| **Router** | Qwen3 structured-action orchestrator — linchpin | **always-on** |
|
|
| Tools | note/reminder/memory/calendar/weather/act (deterministic) | always |
|
|
| Reasoner | larger specialist model | **deferred** |
|
|
| Phraser | Qwen3 persona response | **always-on (same proc as router)** |
|
|
| Digestion worker | reflection → suggestions/nudges/memory | **background** |
|
|
| Reach | telegram (+ existing ntfy/voice) | quick win |
|
|
| Voice quality | custom/better TTS | **deferred** (workstation GPU busy) |
|
|
|
|
## Build order
|
|
|
|
1. **Foundation + router** — completed shared llama-server client, router,
|
|
fallback, replier, TTS normalization and telegram reach.
|
|
2. **Qwen3 resident checkpoint** — finish RU CPT, pass the raw-vs-CPT gate,
|
|
jointly SFT persona/router contracts, merge, quantize and deploy.
|
|
3. **Main features** — reflection, proactive suggestions, memory
|
|
consolidation, RAG read-back.
|
|
4. **Deferred work** — larger reasoner, custom Piper voice and other expansions.
|
|
|
|
## Non-goals (unchanged)
|
|
Not a nag. Not autonomous. Feminine-gendered RU self-ref. No telemetry, no
|
|
cloud model, no third-party account — but she MAY read external sources to
|
|
answer world questions (Kiwix first, search optional). "Never phones home" as
|
|
an absolute is deprecated, owner's call 2026-07-31; see CLAUDE.md § Non-goals.
|