Knittrix

## Context

Construction projects generate hundreds of documents — specifications, drawings, RFIs, submittals, addenda, change orders. The information you need to do the work is buried across PDFs nobody can fully read end-to-end.

Knittrix turns those documents into queryable knowledge with sourced citations. Ask "what color is the ceramic tile?" and get the answer plus the exact paragraph in the spec that says so.

## Approach

I designed and built Knittrix end-to-end as a multi-tenant SaaS platform.

### The retrieval pipeline

PDF text extraction → chunking with character + sentence overlap → semantic embedding via Voyage voyage-3-lite → tenant-scoped retrieval against pgvector with cosine similarity → answer generation via Anthropic Claude with the retrieved chunks as context, returning sourced citations inline.

### Multi-tenant isolation

Every read and write through store.py, retrieve.py, and pipeline.py takes an explicit tenant_id or project_id and refuses cross-tenant access. Chunks have a denormalized tenant_id so retrieval queries can filter at the index level rather than joining through projects.

### Backend, worker queue, and frontend

FastAPI on uvicorn for the API, arq for async background jobs (ingest, render, eval). Next.js web client with signup, organization switcher, project library, document upload with ingest polling, and a chat interface with a citation drawer that lets you click any cited span to jump to the source PDF page.

### Performance work

Stage 3 chunk rebuild dropped from 26.68s to 1.59s by moving the blocking work onto asyncio.to_thread from the render coordinator. End-to-end on a 7-page document went from 10:22 to 8:53 after that and a few smaller wins.

### Cost reduction

Plan 7p chat cost reduction shipped — added should_escalate() heuristic, prompt caching across system + history, and a query mode router. Cuts cost per chat without measurably affecting answer quality.

## Outcome

Phase 16 ships real semantic embeddings via Voyage. 545 default + 9 network + 11 Vitest tests green. Plan 7g + polish-1 shipped on Fly v18 with the perf wins above. Phases 1–16 in production behind the multi-tenant SaaS surface.

The construction-fixture corpus (40 RFIs, drawing sets, addenda, submittals, change orders) is the moat — generic RAG won't beat domain-specific evals on real construction documents. That's where the next phases of work go.