Skip to main content

Documents

The Documents surface is backed by Supabase Storage, the documents catalog table, the knowledge_chunks retrieval index, and spreadsheet_rows for workbook row/range extraction.

Documents support three workflows:

  • In-app document viewing/downloading through short-lived signed URLs.
  • Server-issued upload sessions that allocate a document row before the browser uploads.
  • Ask SABLE retrieval over scoped, chunk-level evidence.

Retrieval Route​

GET /api/doc?id=<documentId>

The route:

  1. Verifies the Supabase user JWT.
  2. Loads the document row.
  3. Blocks restricted documents for non-admin/non-lead users.
  4. Checks project membership for non-leads.
  5. Mints a 10-minute signed URL from the documents bucket.

Upload + Index Flow​

POST /api/doc-upload-session
POST /api/ingest-doc

The browser first asks for an upload session. The server validates project access, creates the document row, chooses a Storage path under documents/<org>/<project>/..., and returns a signed upload token.

For PDFs, DOCX, PPTX, images, ZIP bundles, Outlook messages, and text-like files, /api/ingest-doc extracts text, chunks the document, embeds chunks with Voyage voyage-4, and writes knowledge_chunks. Scanned PDFs and images use Claude vision OCR when text extraction cannot read a real text layer.

For XLSX/XLSM/CSV/TSV files, ingestion treats the file as semi-structured data. It extracts workbook, sheet, table/range, row, column, formula, and display-value metadata into spreadsheet_rows, then creates row/table/sheet/workbook discovery chunks in knowledge_chunks. If a workbook cannot be loaded by the structured parser but still has readable OOXML strings, SABLE indexes that text fallback instead of marking the file unsupported.

Restricted Documents​

Restricted documents, such as contracts and SOWs, are admin/lead only. The route enforces this before issuing a signed URL.

Contract Extraction​

When an uploaded or Drive-synced contracts_sow document is indexed, SABLE extracts structured contract_obligations and SOW budget_lines from the text when possible. These stay admin/lead-only and feed Draft Workbench guardrails, update generation, scope-change review, and outcome estimates.

Admin/lead users can review extraction health through /api/document-inventory.

RAG​

Ask SABLE uses Voyage embeddings and the match_knowledge_chunks_scoped RPC when VOYAGE_API_KEY is configured. Retrieval combines scoped vector and keyword candidates, reranks with Voyage rerank-2.5, balances by source, expands adjacent chunks, and cites chunk-level evidence.

See Search and Indexing for the full extraction and retrieval contract.