Clyde / Live AI product
How Clyde works.
A small portfolio does not need RAG to exist. I use it here because Clyde is part of the work itself: a live assistant that shows how I handle sources, retrieval, safety, and interaction design in one place.
In use
The live assistant makes the product contract visible.
These three states explain the experience end to end: a grounded answer, a clear no-source boundary, and an unlock flow that keeps the tool open without making it unsafe.
01 / System map
The RAG system is small, but every boundary is visible.
Click any node to open the reviewed markdown behind that part of Clyde. The graph sits near the top so visitors can understand the architecture before they read the deeper implementation notes below.
Loading graph and source notes...
Each node opens the related public markdown in a modal.
02 / Sources
It starts with reviewed public sources.
Clyde indexes reviewed Markdown sources, not the whole repository. Each source has frontmatter for title, type, tags, keywords, aliases, confidence, visibility, reviewed date, and public citation URL.
That choice is the same pattern Andy uses in larger AI product systems: make product truth readable before making retrieval clever, then let humans and models inspect the same source boundaries.
Raw PDFs are not linked from public HTML and are not treated as public citations. CV material should be extracted into reviewed Markdown or HTML before it becomes part of the assistant corpus.
docs/andy-knowledge
data/rag/index.json
HTML pages only
03 / Retrieval
Retrieval stays narrow so the answers stay honest.
The build script chunks each source by H2 section and adds contextual prefixes so every retrieved chunk can stand alone. Long sections can split again at H3.
At runtime, the API retrieves sparse BM25 matches and dense-vector matches, then combines them with reciprocal rank fusion. The first index uses deterministic local lexical vectors so the repo can validate without secrets; Gemini embeddings can be enabled for production builds.
The point is not to make Clyde broad. It is to make him trustworthy in his lane: reviewed public portfolio material, visible citations, source-limited fallback, and refusal behavior when a question is outside the evidence.
- 1
Parse frontmatter and Markdown source files.
- 2
Chunk by section with document and heading context.
- 3
Build sparse terms and dense vectors.
- 4
Fuse retrieval results and send compact context to Gemini.
04 / Protection
The backend keeps Clyde useful without making it unsafe.
The homepage calls same-origin API routes. Anonymous questions are verified with Cloudflare Turnstile and capped to a very small quota before Gemini is called. Unlocking Clyde creates a server-signed session with a higher quota, while Redis-backed limits keep abuse controls consistent across serverless invocations.
That boundary is a product design choice as much as an engineering one. The useful AI surface is what the visitor sees; the responsible system is the server-side path, source filtering, quota model, and refusal contract underneath it.
The Gemini API key, Turnstile secret, Redis token, session secret, and password hash live in deployment environment variables. The browser only receives public configuration such as the Turnstile site key and source metadata.
This is why GitHub Pages alone is not enough for the assistant. GitHub Pages can still host static HTML, but Gemini-backed answers require an API proxy on Vercel, Netlify, Cloudflare, or another backend-capable platform.
First deployment target
The repository includes Vercel-compatible API functions and a local Node preview server. The recommended low-cost deployment pairs Vercel with free Cloudflare Turnstile and an Upstash Redis REST database.