Privacy choices

This site may send the owner a minimal page-visit notice with page, browser, device type, and resolution. If you accept analytics, it can also remember an anonymous visit/session ID and collect richer engagement signals.

Read the privacy notice
AlexPersonal Operating System
Alex OS Online
Back to Projects
LinkedIn
ProjectJuly 12, 2026

Alex OS

A FastAPI reasoning and retrieval layer that sits between the CMS and the public site — grounded answers, journey-aware recommendations, and a relationship-graph reasoning pass, not an open-ended chatbot.

Category
ai_rag
Tech stack
FastAPI, Python, Anthropic API, Postgres, pgvector
Metrics
Source-grounded answers, Per-call cost tracing
Role
Architecture + build

Content

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 journeys (Proof, Build, Thinking) influence what it prioritizes when answering, but the assistant doesn't create or control the journeys themselves.

Problem

A static portfolio site can show work, but it can't answer specific questions about it, connect related pieces, or reprioritize itself based on what a visitor actually cares about.

Architecture

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.

Decisions

Chose to make Postgres/pgvector optional with a keyword-scoring fallback rather than a hard dependency, so retrieval degrades instead of failing outright. Chose config-driven personas/prompts (stored as data, editable without a redeploy) over hardcoding assistant behavior in Python.

Limitations

Production hardening is still an open checklist item per the internal progress tracker — confirming Nginx doesn't expose the service publicly, rate limits on public AI endpoints, and secret handling are noted as unconfirmed rather than done.

Next steps

Close out the hardening checklist; expand automated eval coverage for retrieval quality.

Outcome

Grounded Q&A, journey recommendations, and content surfacing.

alex-osfastapireasoningretrievalproofimpactaisystem
Internal Links
ExpertiseRelatedFull-Stack Product DevelopmentExpertiseRelatedAPI and Backend IntegrationExpertiseRelatedAI Workflow AutomationExpertiseRelatedRAG and Knowledge RetrievalExpertiseRelatedApplied AI SystemsSkillUsesSystem ArchitectureSkillUsesVPS DeploymentSkillUsesREST APIs

Explore with Alex OS

Alex OS is a FastAPI service that gives a static portfolio site the ability to answer specific questions about its content — grounded in CMS data, not generate…

The Problem

A static portfolio site can display work but can't answer a question like 'what has Alex built with LLMs?' or surface connections between a case study and a related discovery. Without a reasoning layer, every visitor gets the same undifferentiated view regardless of what they actually want to know.

How It's Built

Key Decision: Retrieval That Degrades Gracefully

pgvector is optional. If the vector store isn't available, the system falls back to keyword scoring rather than failing outright. This was a deliberate tradeoff: slightly lower retrieval quality in the fallback case in exchange for a service that stays functional without a hard infrastructure dependency. The discovery that pgvector is a useful enhancement rather than a system of record shaped this directly — that reasoning is documented separately in the site's discoveries section.

What It Actually Does (and Doesn't Do)

The assistant answers questions using CMS content as grounding — it doesn't invent facts or express opinions about what a visitor should see. The three homepage journeys (Proof, Build, Thinking) influence answer prioritization, but the assistant doesn't create or control those journeys. It's scoped deliberately: a retrieval and reasoning layer, not an open-ended chatbot.

Current Status and Open Items

The service is active. Production hardening is an open checklist item: Nginx exposure, rate limits on public AI endpoints, and secret handling are noted as unconfirmed in the internal progress tracker. Next steps are closing that checklist and expanding automated eval coverage for retrieval quality. If you want to run the system yourself, the local setup guide covers both the CMS and Alex OS together.