The problem
Contractors on a job site need exact answers about installation, ventilation, specs and warranty. Those answers live in PDF installation guides and spec sheets, many of which explain things through diagrams.
Sending PDFs to a model on every question is the most expensive way to ground it: each page is processed as an image as well as text, so the bill grows with every question, forever.
The opportunity
Pay for the expensive read once per document, keep a cheap and faithful text copy, and let the model choose which documents it needs before it reads anything.
My approach
- 01
Tick a box to add a document
An admin ticks “Pro Assist” on any PDF in the content library. A Firestore trigger fires only when that flag flips to pending, so nothing runs by accident.
- 02
Convert once, faithfully
Claude reads the PDF a single time under strict rules: reproduce all text word for word, keep every number and tolerance, rebuild tables as tables, and replace each diagram with a written description that includes its labelled measurements. The result is saved as a Markdown file.
- 03
Summarize for routing
A second, small call writes a dense paragraph about each document: product lines, topics and the kinds of specs inside. That paragraph is what the assistant uses to decide what to read.
- 04
Read only what's needed
At question time the model sees a catalogue of summaries and calls a read_documents tool for the few documents it needs. Only then is Markdown loaded, with citations on, so every answer names its source.
Architecture
Select a component to see what it does, what it connects to, and its status.
Two pipelines on Firebase: a one-time conversion an admin triggers, and a per-question tool-use loop that reads cheap Markdown instead of PDFs.
- Clients
- Server
- Data
- External
Architectural decisions
- Why not a free PDF text extractor?
- The installation guides communicate through diagrams: ventilation cross-sections, fastener placement, ridge details with measurements on the drawing. A text extractor returns nothing for those. Paying once for a model to describe each figure is what lets the assistant answer real installation questions.
- Summaries instead of a vector database
- No embeddings, no chunking, no re-indexing job. For a library this size, a model reading one-paragraph summaries and choosing whole documents by name is simpler to run and avoids answering from fragments.
- Keep the cache byte-identical
- The catalogue is sorted by document id before it goes into the cached system prompt. Unstable ordering would silently break prompt caching on every request.
- Refuse rather than guess
- The assistant must read documents before answering product questions, may never guess specs, measurements or warranty terms, and points to a rep when the documents don't cover it.
Implementation details
- Conversion streams the model's response to handle long manuals, and rejects PDFs over the API's request size with a message telling the admin to split the document.
- Re-ticking the box re-converts an updated document; the stored cost always reflects the latest conversion.
- Chat history is trimmed and sanitized on the server; documents per question and tool rounds are capped.
- The system prompt and each attached document are marked for prompt caching, so multi-round tool loops and follow-up questions reuse what was already read.
- Question logging is best-effort and can never break a contractor's answer. A question with no cited source is flagged as not covered.
Challenges overcome
Cost scales with traffic
A chatbot is cheap to build and expensive to run. The engineering went into making the per-question cost small and flat.
Never paraphrase a spec
The conversion prompt forbids summarizing or rewording, so the numbers in the Markdown are the numbers in the PDF.
Capability status
Completed, experimental and planned capabilities, kept separate on purpose.
Live6
- One-click document conversion for admins
- Diagrams converted to written descriptions
- Summary-based document routing
- Cited answers
- Per-user daily quota
- Question log and cost reporting
Planned1
- Cheaper conversion model · Under evaluation; figure descriptions are the quality risk
Results & current status
- Live in production, answering contractors' questions from approved documents only.
- Modeled, not measured: a Markdown page uses about 3.3× fewer input tokens than the same page sent as a PDF, which makes a typical three-document question about 70% cheaper. A document's one-time conversion pays for itself after roughly one question.
- The question log became marketing input: it shows what contractors don't understand about the products.