Alex OS

Alex OS is a separate service, not a feature bolted onto the CMS. It reads structured content through the CMS's internal API, retrieves and ranks relevant items, and answers questions using that content as grounding — it doesn't invent facts and it doesn't have its own opinions about what a visitor should see. The three homepage threads (what I've shipped, where I've worked, what I know) influence what it prioritizes when answering, but the assistant doesn't create or control them itself.

Beyond single-item answers, it reasons over the relationship graph — two-hop traversals where the model's stated reasons are persisted, so a connection drawn once becomes a fact it can reuse — and a coach layer folds what it has learned into concrete guidance inside the admin.

FastAPI service with distinct route groups for ask/surface/recommend/capture/synthesis/admin, a config-driven engine layer (persona resolver, model router, block composer), and a services layer for retrieval, embeddings, and relationship-graph traversal. Reads CMS content over an internal HTTP API rather than touching the CMS database directly.

Postgres/pgvector is optional, with a keyword-scoring fallback, so retrieval degrades instead of failing outright. Personas and prompts are config — stored as data, editable without a redeploy — rather than behavior hardcoded in Python.

The retrieval layer carries the most deliberate trade-offs. Content is chunked (roughly 1,800 characters per chunk, with overlap) rather than embedded as one vector per item, and query rewriting handles conversational follow-ups. A hybrid keyword+vector fusion path (reciprocal rank fusion) shipped enabled by default. When I finally benchmarked it against plain semantic ranking on 31 hand-labeled queries, it didn't win: semantic alone scored MRR 0.925 against hybrid's 0.898, and the shipped default (hybrid plus the reranker) came last at 0.882. The full ablation, and what I'm doing about it, is in the evaluation report. Each ask-mode has its own minimum relevance score, because "no good answer" is a better result than a confidently irrelevant one.

One bug shaped the design more than any feature request: typing "projects" into the assistant returned exactly one project. The fix wasn't retrieving more items — it was recognizing that naming a content type is a browse intent, not a question, and switching strategy for it: widen the net, boost the named type, drop the diversity cap that Q&A mode needs.

Build a harder, graded query set (paraphrases, multi-hop, questions with no good answer) and re-run the ablation on it before deciding hybrid fusion's future.