Skip to content
aakashk.dev

USense

Ask your documents and your data in plain English.

  • 58% to 94% retrieval hit rate
  • 33% to 84% execution accuracy
  • Team of three

USense grew from a privacy-first document chatbot into an MCP agent that answers business questions from documents and databases. I raised its document retrieval hit rate from 58% to 94%, then designed and built its database feature end to end.

My role: one of a three-person team. I improved RAG retrieval, and I designed the architecture of the NL2SQL feature and built it.

Part 1: Making document answers reliable

USense began as a simple RAG chatbot running on any local model Ollama supports, for teams whose documents couldn't leave their own machines. The model was swappable; what mattered was the harness around it, the context and tools that let a small local model give good answers. Its only controls were top-K, top-P and temperature. It worked on single, simple documents, and broke when a question spanned several files, or when the answer was spread across chunks as tables, diagrams or numbers.

What I added:

  1. HyDE: write a hypothetical answer first and search with it, so questions match the language of the documents
  2. Query embeddings tuned for retrieval
  3. Variable top-K: simple questions pull a few chunks, broad ones pull more
  4. Tuned chunk size and overlap, so tables and numbers stop getting split mid-thought
  5. Parent-child chunking: search on small precise chunks, answer with their larger parent sections
  6. Multi-document search, so one question can draw on several files

Result: retrieval hit rate from 58% to 94%.

How it was measured: a custom evaluation on free-to-use documents: published research papers, technical textbooks and novels. Each document was chunked at several sizes and a question written for every chunk. The documents were then uploaded through the app as a normal user, every question was run, and a hit meant the answer chunk appeared in the top-K retrieved chunks.

Part 2: Answering from the database

Who it was for: business leaders in finance, retail, marketing and sales who check the data before they decide. Instead of sending a question to an analyst and waiting on their turnaround, they ask USense directly. When an answer deserves a permanent dashboard, they hand the analyst the USense result as the spec, so the dashboard starts from a clear example rather than a vague request.

How it works: a user asks a business question in plain English. USense turns it into SQL, runs it, and replies with a summary, the SQL and the rows it used, so people can check the work. Answers export to CSV, PDF, Excel, Google Docs, Power BI and Tableau.

How it got to 84%, one problem at a time:

StepWhat changedWhyExecution accuracy on Spider
1. Zero-shotQuestion and database type sent straight to the model, no schemaBaseline once we moved from small specialized models to LLMs (a text-to-SQL SLM had scored 23%)33% (Llama3.2:3b)
2. Larger modelSame approach on Llama3.1:8bTest whether a bigger model can reason past missing schema49%
3. Schema retrievalSchema read on first connection and on every change, indexed in a vector DB; only the tables and columns relevant to the question go into the promptThe model was guessing table and column names, especially for synonyms55%
4. Dynamic few-shotThe 3 most similar question-to-SQL examples retrieved by vector search and added to the promptShow the model how to handle this type of query63%
5. Chain-of-thoughtPrompt rebuilt as steps: understand intent, plan the retrieval with as few joins as possible, then write the queryMulti-join queries needed step-by-step reasoning78%
6. Business glossaryBusiness definitions added as a semantic layer, e.g. "active customer" means a purchase in the last 6 monthsJargon that no schema can explain84%

Models: local models for the individual-user version; Mistral Large, hosted in the cloud, for the enterprise version. Both reached similar accuracy: local models on simpler schemas, Mistral Large on complex enterprise schemas.

Safety and cost: role-based access, a SQL parser that blocks every non-read statement before it runs, BigQuery partitioning and clustering guidelines, per-query cost limits and audit logging.

What came next: USense was retired as frontier models caught up. Its ideas live on in PlainQuery.

Built with

  • MCP
  • LangChain
  • SQLAlchemy
  • ChromaDB
  • Ollama
  • Mistral Large
  • PostgreSQL
  • Oracle
  • BigQuery