Talk2Database

A powerful Agentic-Ai application that converts natural language queries into SQL commands and executes them against your database. Built FastAPI, Paritok, and Langgraph.

Comment

Talk2Database — Agentic Text-to-SQL Platform

Inspiration

Data is the lifeblood of modern decision-making, yet retrieving actionable insights from complex relational databases remains locked behind technical SQL expertise or tedious dashboard requests. Existing AI text-to-SQL solutions suffer from two major flaws:

  1. Massive Context Bloat & High Token Costs: Autonomous SQL agents iterate through multiple tool calls (fetching schemas, inspecting tables, verifying queries), rapidly blowing up context length and LLM API costs.
  2. Fragile Single-Prompt Generation: Basic LLM text-to-SQL prompts lack verification, safety guardrails, and execution plan visibility, often hallucinating column names or returning runtime errors.

We built Talk2Database to solve both problems: creating a state-of-the-art, autonomous agentic SQL assistant that seamlessly converts natural language into verified SQL queries.

What it does

Talk2Database is an end-to-end, enterprise-grade AI Text-to-SQL agentic web application.

Key features include:

  • 💬 Natural Language to SQL Agent: Converts natural language queries into precise, execute-ready SQL statements using an autonomous, tool-calling LangGraph agent.
  • ⚡ Integrated Paritok Context Compression: Intercepts agent trajectories and database schema payloads in real time, compressing context before forwarding to upstream LLMs (Groq / OpenAI) to cut token bills and prefill latency.
  • ☁️ Dual Compression Deployment (Hosted GPU & Self-Hosted): Supports both Paritok's hosted cloud GPU server (use_gpu_server: true) and local self-hosted compression via Ollama (paritok/paritok-4b-v1).
  • 🔍 Interactive Query Plan Execution (EXPLAIN Visualizer): Inspects query execution paths across PostgreSQL, MySQL, and SQLite, visualizing cost estimates, index usage, and scan steps.
  • 🛡️ Strict Read-Only Guardrails & Prompt Injection Protection: Enforces strict execution safety rules that allow only SELECT queries while intercepting and blocking schema modification (DROP, ALTER) or data tampering (UPDATE, DELETE).
  • 📊 Paritok Compression Inspector UI: A dedicated real-time dashboard displaying token reduction percentages, total tokens saved, estimated cost savings ($), and side-by-side original vs. compressed context segment traces.

How we built it

Backend & AI Architecture

  • Python 3.13 & uv: Managed high-performance dependency isolation and virtual environment setup using uv.
  • FastAPI: Built clean, async RESTful APIs for database connections (/setup-connection), natural language query execution (/query), query plan explanations (/query/explain), and Paritok statistics (/paritok/stats).
  • LangGraph & LangChain: Engineered a resilient state machine agent that dynamically navigates tool selection (list_tables, get_schema, execute_query) with memory checkpointers.
  • Paritok Context Compression Proxy: Deployed the paritok middleware gateway (paritok proxy) sitting transparently between the agent and upstream LLMs (Groq openai/gpt-oss-120b).

Frontend & User Experience

  • React 18, Vite & TypeScript: Developed a fast, modern single-page web application with responsive layout and real-time state management.
  • Tailwind CSS & Glassmorphism Design: Designed a dark-mode, futuristic glassmorphic UI using curated color palettes, micro-animations, and dynamic status indicators.
  • React Markdown & GFM: Formatted SQL responses into syntax-highlighted code blocks with copy-to-clipboard functionality and collapsible query plan trees.

Challenges we ran into

  1. Paritok Cloud GPU Server Availability & Fail-Safe Pass-Through:
    During integration, we encountered moments when Paritok’s hosted cloud GPU returned gpu_available: false. We learned how Paritok’s proxy architecture handles this gracefully: when cloud GPUs are offline, requests pass through uncompressed so the user’s queries never fail. To guarantee continuous, 100% active compression regardless of cloud status, we configured local self-hosting with Ollama (ollama pull paritok/paritok-4b-v1), giving us full offline compression control on local hardware.

  2. Upstream API Key Passthrough vs. Compressor Authentication:
    Configuring the Paritok proxy required carefully decoupling the Paritok GPU server authentication key (pk_live_...) from the upstream LLM provider key (Groq gsk_...). The proxy forwards the upstream Authorization header directly to Groq, so ensuring the correct provider key was passed prevented 401 Unauthorized errors.

  3. LangGraph Trajectory Recursion & Infinite Loops:
    Early iterations of the supervisor agent fell into infinite loops calling list_tables repeatedly. We resolved this by refining system prompts to inspect previous conversation history before selecting tools and enforcing strict graph recursion limits (recursion_limit: 15).

  4. Database Driver Validation & Compatibility:
    Handling connection strings across diverse database engines (PostgreSQL, MySQL, and SQLite URIs without network hosts) required building adaptive connection validation routines.

Accomplishments that we're proud of

  • 🚀 Seamless Paritok Middleware Integration: Successfully routed multi-step agent trajectories through Paritok context compression, achieving up to 74%+ token reductions on heavy schema payloads.
  • 🛡️ Robust Read-Only Security Guardrails: Built a resilient security policy layer that guarantees safe database exploration without risk of data destruction.
  • 🎨 State-of-the-Art UX: Built a clean UI complete with syntax highlighting, EXPLAIN query execution plan visualizations, and a live Paritok token savings inspector.
  • ⚡ Zero-Downtime Fallback Architecture: Engineered our setup to handle hosted GPU offline states without breaking backend query execution.

What we learned

  • Context is the bottleneck for agentic systems: Agentic workflows spend up to 80%+ of their token budget re-sending previous tool outputs and schemas. Context compression model gateways like Paritok are essential for production-grade agent scalability.
  • Fail-Safe Gateway Design: A non-destructive compression gateway that passes uncompressed traffic when GPU nodes are offline ensures 100% application uptime.
  • Structured Prompts vs. Graph Routing: Clear, guardrailed system prompts inside state machines prevent agent loop stalls far more effectively than basic prompt chains.

What's next for Talk2Database

  • 📈 Automated Data Visualizations: Auto-generating interactive charts (bar charts, line graphs, pie charts) directly from SQL query results.
  • 🔌 Native MCP (Model Context Protocol) Server: Packaging Talk2Database as an MCP server so developer tools like Claude Code and Cursor can query connected databases securely.
  • 🧠 Schema Indexing & Vector Search: Embedding large database schemas with bge-small-en for semantic table/column filtering before sending queries.
  • 🔄 Multi-Database Federated Queries: Allowing users to join data across different databases (e.g., SQLite + PostgreSQL) in a single natural language prompt.

Built With

Share this project:

Updates