docs: add phased implementation plan and architecture decision records
Turns the design doc into an ordered, dependency-correct build plan (phases 0-9) with an exit criterion per phase, and records the twelve architectural decisions it rests on as ADRs. Decisions: single Rust binary with routed compose services; Streamable HTTP only; per-agent bearer tokens with clientInfo as a display hint only; SQLite; get_rules delivered via session gating; full-document rule delivery; project_id from day one; enforcement tier scoped to Bridle-mediated actions; stable tool list on upstream failure; OpenAI-compatible embeddings with model/dim guarding; pattern RAG gated behind a spike; CLAUDE.md + AGENTS.md as v1 renderer targets. Deviates from the design doc's original 1-8 ordering by moving the audit log and multi-project schema into phase 1, building the admin API incrementally rather than all at the Web Panel phase, downgrading vendor guardrail sourcing to manual-first, and gating the pattern-example RAG behind a validation spike. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019RZerbsHGF9Ka3bKhCjJ9m
This commit is contained in:
29
docs/adr/0010-openai-compatible-embeddings.md
Normal file
29
docs/adr/0010-openai-compatible-embeddings.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# ADR-0010: Generic OpenAI-compatible embeddings with model/dimension guarding
|
||||
|
||||
**Status:** Accepted (2026-08-08)
|
||||
|
||||
## Context
|
||||
|
||||
The design doc specified embeddings generated locally via LM Studio on an RTX 3060. Hard-coding
|
||||
that makes the entire memory subsystem depend on one service and one GPU box being up. Separately,
|
||||
the choice of embedding model **pins the vector dimensionality** of a Qdrant collection — changing
|
||||
models silently corrupts a collection or forces a full reindex, and neither should happen by
|
||||
accident.
|
||||
|
||||
## Decision
|
||||
|
||||
Target a **generic OpenAI-compatible embeddings endpoint**, configured by `EMBEDDING_URL`,
|
||||
`EMBEDDING_MODEL`, and `EMBEDDING_DIM`. LM Studio, Ollama, and text-embeddings-inference all
|
||||
satisfy this.
|
||||
|
||||
Record `{model, dim, created_at}` in each Qdrant collection's metadata. On any write, compare the
|
||||
configured model and dimension against the collection's recorded values; on mismatch, **refuse the
|
||||
write** and flag that a reindex is required.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The 3060 is no longer a hard single point of failure; users may point at whatever they run.
|
||||
- Changing embedding models becomes a loud, explicit reindex rather than silent corruption.
|
||||
- Slightly more configuration surface than hard-coding LM Studio.
|
||||
- Bundling a small CPU embedding container as a compose profile default remains available later to
|
||||
improve the out-of-box experience for new adopters.
|
||||
Reference in New Issue
Block a user