Welcome to Sharp Docs

Chat with any documentation. Ingest doc URLs, then ask questions and get streaming, source-cited answers powered by Google Gemini and a hybrid (vector + BM25) retriever.

Features

• Ingestion pipeline — fetch a URL, strip boilerplate, chunk, embed, and store.
• Hybrid retrieval — cosine vector search fused with BM25 keyword ranking.
• Streaming chat — token-by-token SSE responses with inline source citations.
• Disk persistence — the vector store is snapshotted to data/store.json and rehydrated on startup.
• Observability — in-memory trace ring buffer plus optional OpenTelemetry OTLP export.
• Retrieval eval — Precision@k, Recall@k, and MRR benchmarks.

Prerequisites

• Node.js 20+
• A Google AI Studio API key: https://aistudio.google.com/apikey

Setup

npm install --legacy-peer-deps
cp .env.example .env # then set GOOGLE_API_KEY

The --legacy-peer-deps flag is required because @langchain/community declares an optional peer on html-to-text@^9 while this project uses html-to-text@^10.

Note: Documents and queries are embedded with Gemini's asymmetric retrieval task types (RETRIEVAL_DOCUMENT / RETRIEVAL_QUERY). If you have a store from an older build, re-ingest your URLs so passages and queries share the same embedding space.

Environment variables

Variable	Required	Default	Description
GOOGLE_API_KEY	yes	—	Google AI Studio key for chat + embeddings
GOOGLE_CHAT_MODEL	no	gemini-2.5-flash	Chat model
GOOGLE_EMBEDDING_MODEL	no	gemini-embedding-001	Embedding model
OTEL_EXPORTER_OTLP_ENDPOINT	no	—	Enables OTLP trace export when set
OTEL_SERVICE_NAME	no	sharp-docs	Service name reported to OTLP

Development

npm run dev # start the dev server at http://localhost:3000
npm test# run the Vitest suite
npm run lint # run ESLint
npm run build # production build

API

Route	Method	Description
/api/ingest	POST	{ urls: string[] } (max 10, http(s) only) → ingestion results
/api/chat	POST	{ query, history } → SSE stream (sources → token* → done / error)
/api/store	GET	Ingested sources and total chunk count
/api/store?url=...	DELETE	Remove all chunks for a source URL
/api/traces	GET	Aggregate trace stats and recent traces

Retrieval evaluation

With documents already ingested:

npx tsx src/lib/eval.ts

Prints Precision@1/3/5, Recall@3/5, and MRR over auto-generated queries.

Project structure

src/
instrumentation.ts startup store preload + OTLP init
app/
page.tsx chat UI (client)
api/ chat | ingest | store | traces route handlers
lib/
rag.ts retrieval + streaming chat chain
observability.ts in-memory trace buffer + stats
telemetry.ts OTLP exporter
eval.ts / gen-eval.ts retrieval + generation evaluation
ingestion/ fetcher | chunker | embedder | pipeline
vectorstore/ store | bm25 | persistence