b267e55f8c
- AGENTS.md: build spec for Paperclip (constraints, conventions, 7 phases) - docs/phase-1..7: per-phase work, DoD, out-of-scope, risks - reference/: frozen decisions, stack+ports+budgets, content map, acceptance tests - agents/: persona and security policy drafts - Retires the React scaffold; history retained as record of the false start
3.7 KiB
3.7 KiB
Frozen decisions
These are not open for reconsideration inside the build. Changing any of them requires Sam's written approval and an ADR in this folder. Detail and reasoning: ../../resume_ai_system/plan/10-technology-plan.md and 40-cull-register.md.
| # | Decision | Chosen | Rejected, and why |
|---|---|---|---|
| D1 | Site shell | Go + templ + HTMX |
React 19/Vite — node build + bundler for no UX gain. Svelte/Solid — no benefit for a server-rendered content site. Astro — credible runner-up, but adds a Node toolchain we control away. Leptos/Wasm — complexity overhead |
| D2 | Templating | templ |
html/template — stringly typed, fails at runtime not compile time. templ compiles to Go, so a broken view is a compiler error |
| D3 | AI console | One hand-written TS island, ES modules | React island — second toolchain. No framework — xterm and SSE are plain-library concerns |
| D4 | Markdown / highlighting | Server-side goldmark + chroma |
Client-side Prism/marked — bundle weight, flash of unstyled code, two implementations for two modes |
| D5 | Embedded data | SQLite + FTS5 | Postgres — another container for a site with one writer. Redis — explicitly rejected previously, and unnecessary |
| D6 | Vector store | Qdrant | ChromaDB — heavier footprint, weaker payload filtering, and it is the stack being retired. SQLite-vec — promising, less mature filtering. Weaviate/Milvus/pgvector — overkill |
| D7 | Ingestion | Prefect (server already running) | Airflow — already abandoned once for RAM. n8n — retained for household automation only |
| D8 | Query graph | LangGraph, four nodes | Flowise/Windmill/Activepieces — visual builders, not needed for 200 lines of Python. More agents — complexity that causes drift |
| D9 | Model access | OmniRoute only | LiteLLM — would duplicate an existing gateway. Direct provider SDKs — violates house rule |
| D10 | Retrieval | Hybrid: vectors + BM25/FTS5 → RRF → cross-encoder rerank | Vector-only — misses exact tokens (repo names, LoRaWAN, MQTT, dates) |
| D11 | Memory | None. Stateless by design | Hindsight, TencentDB Agent Memory, LangMem, Engram, Headroom — all rejected for this product. A public assistant with no returning user gains nothing and gains a write path. Engram/Headroom remain part of Sam's own workflow and are documented as such |
| D12 | Observability | JSONL trace + Langfuse Cloud free tier | Self-hosted Langfuse — 6 containers, ~2 GiB, unaffordable on .13 |
| D13 | Guardrails | mozilla-ai/any-guardrail |
Prompt-only defence. The library is the mechanism; agents/security.md is the policy |
| D14 | Agent tools | None | A code-execution sandbox was considered and rejected: a public CV site will not run model-generated code |
| D15 | Voice | Reuse existing Whisper + Piper on .13 |
New STT/TTS stack — already solved |
Standing rules
- All models through OmniRoute.
- Secrets from
~/.config/environment.d/only. - Own service, own port, own folder.
- No LLM in the path of a fast or consequential action.
- Mode A must work with every AI service stopped.
- New footprint ≤ 1.0 GiB RAM, ≤ 4 containers.
Rejected before deployment
Airflow · self-hosted Langfuse · Trigger.dev · LiteLLM · second Garage instance · OpenCode as a "brain" service · Flowise · Windmill · Activepieces · Helm/Helicone · Multica · Archon · CAO CLI · AgentPipe · CrewAI · nine documentation platforms.
Why this list is kept: "alternatives considered" is a senior signal, and it converts a cull from a subtraction into an exhibit. The public site gets a short page listing these with the reasoning.