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:
- HyDE: write a hypothetical answer first and search with it, so questions match the language of the documents
- Query embeddings tuned for retrieval
- Variable top-K: simple questions pull a few chunks, broad ones pull more
- Tuned chunk size and overlap, so tables and numbers stop getting split mid-thought
- Parent-child chunking: search on small precise chunks, answer with their larger parent sections
- 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:
| Step | What changed | Why | Execution accuracy on Spider |
|---|---|---|---|
| 1. Zero-shot | Question and database type sent straight to the model, no schema | Baseline once we moved from small specialized models to LLMs (a text-to-SQL SLM had scored 23%) | 33% (Llama3.2:3b) |
| 2. Larger model | Same approach on Llama3.1:8b | Test whether a bigger model can reason past missing schema | 49% |
| 3. Schema retrieval | Schema 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 prompt | The model was guessing table and column names, especially for synonyms | 55% |
| 4. Dynamic few-shot | The 3 most similar question-to-SQL examples retrieved by vector search and added to the prompt | Show the model how to handle this type of query | 63% |
| 5. Chain-of-thought | Prompt rebuilt as steps: understand intent, plan the retrieval with as few joins as possible, then write the query | Multi-join queries needed step-by-step reasoning | 78% |
| 6. Business glossary | Business definitions added as a semantic layer, e.g. "active customer" means a purchase in the last 6 months | Jargon that no schema can explain | 84% |
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