🌸 TARA: Autonomous SQL Architect & Memory-First Data Agent

Transparent Analytic Retrieval Assistant

TARA is an autonomous, domain agnostic data assistant. Point her at any SQLite database—whether it's retail inventory, hospital patient records, or financial ledgers and she acts as a conversational Database Administrator. She analyzes the schema, writes highly optimized SQL, executes it, and translates the results into natural language.

Built with LangGraph and a custom Next.js frontend, TARA is engineered specifically to solve the two biggest problems with LLM-to-SQL agents: Token Bloat and Join Hallucinations.

---

✨ The Problem TARA Solves

Standard AI assistants often fail at enterprise data analysis because they:

1. Hallucinate Joins: They guess how tables connect, leading to inaccurate data retrieval.
2. Hit Token Limits: They send the entire chat history on every API call, causing expensive crashes.
3. Waste Compute: They trigger heavy SQL-generation LLMs just to say "Hello" or answer out-of-scope questions.

TARA was built to solve this. She uses a "Reasoning-over-Data" architecture that treats your database like a professional DBA would, wrapped in a premium, conversational UI.

---

✨ Core Engineering Features

1. View-Based SQL Generator (Token & Compute Efficiency)

Standard SQL agents pass the entire database schema to the LLM on every turn. TARA solves token bloat using Progressive Schema Visibility and a View Metadata Store. When a user asks a question, TARA executes a 3-step routing logic:

• Step 1 - Base Table Scan: Can this be answered using a single base table? If yes, she injects only that table's schema.
• Step 2 - View Matching (The Sweet Spot): If multiple tables are needed, TARA queries her VIEW_COVERAGE_CONTEXT. Instead of writing a risky 5-table JOIN, she finds a pre-compiled Master View that covers the required data and queries SELECT * FROM view_name.
• Step 3 - Hard Mode: Only if no view exists does she expose the full schema to write manual joins.
• Result: This drastically reduces prompt size, drops token latency, and ensures 100% accurate joins.

2. State-Compressed "Fact-Based" Memory

Most conversational agents append chat history to an array until the context window crashes. TARA uses LangGraph state management to maintain a highly compressed Working Memory.

• After every interaction, a dedicated node_summarize function compresses the entire chat into a strict, <40-word fact sheet (e.g., User: Sakshi | Active Filters: Adelaide, 2023 | Goal: Analyzing Sales).
• This micro-state is injected into the SQL Generator. If you ask a follow-up like "What about last month?", TARA automatically applies the "Adelaide" filter without needing the raw chat history.

3. Automated Schema Intelligence

When a new database is ingested, TARA actively parses the architecture:

• Identifies Primary and Foreign Keys.
• Generates the code for visual ER Diagrams so developers can verify relationships.
• Extracts column metadata to feed her intelligent routing engine.

4. Graph-Based Computational Guardrails

TARA uses a highly efficient LangGraph node architecture to prevent wasted compute.

• Intent Router (The Gatekeeper): Every prompt is first classified.
• If the user says "Hello," it routes to a lightweight Casual Node.
• If the user asks to "Predict the stock market," it routes to the Guardrail Node, which conversationally declines out-of-scope requests.
• The heavy, expensive SQL logic is only triggered when the intent is strictly database-related.

---

✨ Technology & Model Stack

Technology	Implementation Details
Groq API & LLMs	The Inference Engine: Utilizing Groq's ultra-low latency LPU API to run open-weight models. Chosen specifically for near-instantaneous time-to-first-token (TTFT).
LangGraph	The Orchestrator: Handles the stateful, cyclic graph logic, conditional routing, and global state (memory) management.
LangChain	The Framework: Provides the core wrappers for tool execution (SQL execution) and message formatting.
SQLite3	The Database: Chosen for zero-latency local execution. Allows TARA to test SQL queries and retrieve historical data instantly.
LangSmith	The Evaluation Lab: Used extensively for CI/CD tracing, prompt versioning, and running A/B tests across different LLMs.
Next.js / Tailwind	The Frontend: A custom-built, responsive UI ("Tara Inbox") featuring a premium Peach/Pink aesthetic, real-time streaming, and thread management.

---

✨ Model Evaluation & Testing (LangSmith)

Building an autonomous SQL agent requires strict guardrails against hallucinations. We utilized LangSmith not just for logging, but as a core testing framework to evaluate which model would serve as Tara's brain.

• A/B Model Testing: We ran identical evaluation datasets (comprising complex domain-specific questions, multi-table join requests, and out-of-scope conversational attempts) across multiple models via the Groq API.
• Selection Criteria: Models were scored based on three metrics:
  1. SQL Accuracy & Syntax: Did the model successfully utilize the VIEW_COVERAGE_CONTEXT instead of hallucinating a base-table join?
  2. Token Economy: Which model followed the strict <40-word output constraint for the node_summarize memory compression?
  3. Latency: Measuring the exact milliseconds taken for Intent Routing vs. full SQL generation.
• The Result: By actively tracing execution paths in LangSmith, we identified the exact model configuration that provided 98%+ SQL accuracy while keeping intent-routing latency under 800ms.

---

✨ Getting Started

Prerequisites

• Node.js (v18+)
• Python (3.10+)
• Groq API Key
• LangSmith API Key (Optional, for tracing)

Installation

1. Clone the repository

   git clone [https://github.com/YOUR_USERNAME/Tara.git](https://github.com/YOUR_USERNAME/Tara.git)
   cd Tara