Architecture
How it works
Ask Brightworks is a portfolio demo of retrieval-augmented generation. It answers from approved public Brightworks pages. It is not a person, and it is not an official support channel.
- 1
Curated pages
Markdown files in this repo are the only knowledge. Each file has a slug, title, and the public HTTPS page it came from.
- 2
Chunks and checksums
Ingest splits those pages by heading and paragraph, keeps the heading path, and stores a SHA-256 checksum so unchanged pages are skipped.
- 3
Embeddings
Changed passages are embedded with OpenAI text-embedding-3-small at 1536 dimensions. The database rejects any other model or size.
- 4
pgvector
Vectors live in a dedicated rag schema on Supabase Postgres. Search uses cosine distance and an HNSW index.
- 5
A question
The server rate-limits the request, embeds the question, and asks Postgres for the closest passages.
- 6
A grounded answer
The model may use only those passages. If none are relevant, the app says it cannot answer. A business question the pages do not cover also gets the quote form. An unrelated question, such as the weather, does not.
What the model is allowed to say
The generator sees numbered excerpts and a fixed instruction: use only that text, cite the numbers, and stay within about 240 words. Pricing, timelines, credentials, reviews, contact details, and client results have to be present in an excerpt. The excerpts are treated as untrusted data. Instructions hidden inside a page, or inside a question, are not followed. The app does not call tools.
When it should refuse
If retrieval finds nothing strong enough, the app does not call the model. It says it cannot answer from the Brightworks pages and points to the Brightworks quote form. The same refusal is required when the pages do not contain the fact, even if a model could guess one.
Privacy
A question is sent to OpenAI for the embedding and, when excerpts exist, for the answer. Do not submit confidential information. The app does not store the question or the raw IP address. Rate limiting stores a salted hash of the address and a counter in Postgres.
What this version leaves out
There is no crawler, account, upload form, admin screen, or payment. The corpus changes only when someone edits the Markdown and runs ingest. Keyword search and per-client corpora are future options, not part of this demo.