The Problem

Raw large language models writing SQL hit a wall due to missing schema meaning, misleading types, and absent tribal knowledge. This repository addresses that by implementing a self-learning data agent that grounds answers in six layers of context—table usage, human annotations, query patterns, institutional knowledge, learned patterns, and runtime context—improving with every query rather than requiring retraining.

What This Does

The system is structured as a context-aware agent. Six layers of context are loaded at query time via hybrid search from dash/knowledge/tables/*.json, dash/knowledge/business/*.json, and dash/knowledge/queries/*.sql. The "self-learning loop" distinguishes between Knowledge (curated validated queries and business context) and Learnings (discovered error patterns managed by the Learning Machine). The value proposition is insight generation over raw row returns; for example, answering "Who won the most races in 2019?" with a performance narrative rather than just "Hamilton: 11."

Execution flows from an entry point through context retrieval and SQL generation, with evaluation handled by dash/evals/grader.py and dash/evals/run_evals.py.

How It Is Wired

Control starts at app/main.py and dash/__main__.py. The internal call graph contains 21 resolved edges. The most connected hub is dash/agents (Ca 5, Ce 4). Key traced paths include run_evals → evaluate_response → grade_response, which calls a model for inference, and execute_golden_sql, which reads from the database. dash/context/semantic_model.py (load_table_metadata, build_semantic_model) and dash/context/business_rules.py (load_business_rules, build_business_context) are the primary wires for grounding answers. The agent relies on db/session.py (get_postgres_db) for persistence. Broad exception handling in dash/evals/run_evals.py and deep nesting in dash/tools/introspect.py and dash/evals/run_evals.py currently obscure control flow.

How To Use It

# Clone this repo
git clone https://github.com/moses-y/dash.git && cd dash
# Add OPENAI_API_KEY to .env file or export OPENAI_API_KEY=sk-***
cp example.env .env

# Start the application
docker compose up -d --build

# Load sample data and knowledge
docker exec -it dash-api python -m dash.scripts.load_data
docker exec -it dash-api python -m dash.scripts.load_knowledge

Navigate to http://localhost:8000/docs to confirm the service is running. Connect via the OS Web UI at os.agno.com.

Real-World Use

A user asks, "Who won the most F1 World Championships?" The agent retrieves context from the six layers, generates grounded SQL against the F1 schema, executes the query, and returns a structured insight. Contrast this with a typical SQL agent returning Hamilton: 11; Dash returns: "Lewis Hamilton dominated 2019 with 11 wins out of 21 races, more than double Bottas’s 4 wins. This performance secured his sixth world championship." If a query fails—e.g., position is TEXT instead of INTEGER—the agent saves the error as a Learning, preventing recurrence.

Code Health & Issues

Static analysis of 29 code files identified the following:

  • [CRITICAL] Pinned dependencies carrying critical advisories: cryptography@46.0.4 (CVE-2026-39892), gitpython@3.1.46 (CVE-2026-42284), pyjwt@2.11.0 (CVE-2026-48526). The manifest pins the exact vulnerable versions, making this reachable over the network without credentials. Fix: upgrade and commit the lockfile.
  • [HIGH] GitHub Actions pinned to @vN tags instead of commit SHAs (e.g., astral-sh/setup-uv@v3). Tags can be moved, meaning the action running with secrets changes without notice. Fix: pin to 40-character commit SHAs.
  • [HIGH] No lockfile present beside pyproject.toml. Unlocked ranges mean the artifact tested and the artifact shipped can differ, allowing malicious patch releases to reach production unnoticed. Fix: generate and commit the lockfile.
  • [MEDIUM] Broad exception handling in dash/evals/run_evals.py swallows errors indiscriminately. Fix: catch specific exceptions; re-raise or log the rest.
  • [MEDIUM] High branching density (17 branch points over 52 lines) in dash/context/business_rules.py. Fix: decompose decision-heavy logic; consider strategy dispatch.

The Bottom Line

This repo presents a strong architectural pattern for context-grounded Text-to-SQL agents, successfully trading raw row counts for interpretable insights via its six-layer context system. However, it is currently held back by critical dependency vulnerabilities and the absence of a lockfile, alongside code health issues—deep nesting and broad exception handling—in the evaluation and introspection modules. It is suitable for teams needing a self-improving data agent but requires immediate dependency hygiene and refactoring before production deployment.