Dash: A Self-Learning Text-to-SQL Agent With Six Context Layers
A self-learning data agent built with systems engineering principles. It grounds answers in 6 layers of context and improves with every query.
At a glance
- What is it?
- Dash is an Apache-2.0 Python agent from agno-agi that splits SQL work between a read-only Analyst and a schema-writing Engineer, grounding answers in six context layers and a Learning Machine that stores error fixes. The design is opinionated and the setup cost is real.
- Who is it for?
- Dash fits teams that already run PostgreSQL with pgvector, have a schema worth documenting, and want an agent they can extend rather than a closed analytics product. It does not fit anyone who wants a hosted BI tool or cannot supply an OPENAI_API_KEY.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 68 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem Dash Targets: LLMs Writing SQL Without Meaning
The README states the failure mode directly: raw LLMs writing SQL hit a wall because schemas lack meaning, types are misleading, tribal knowledge is missing, there is no way to learn from mistakes, and results lack interpretation. That list is a fair summary of why text-to-SQL demos break on real warehouses. A column named status with values 1, 2, 3 tells a model nothing. A metric called MRR lives in a finance wiki, not in the DDL. A query that failed last week because of a timezone cast will fail again next week unless something remembers.
Dash is for engineers who want to fix that with infrastructure rather than prompt wording. The target user is someone comfortable with docker compose, Python, and PostgreSQL, who has a dataset worth asking questions about and is willing to curate knowledge files. The README's sample questions (current MRR, highest churn plan, revenue trends by plan, customers at risk of churning) describe the intended shape of use: recurring analytical questions against a stable schema, not one-off exploration.
Two Agents, Two Schemas, and a Structural Boundary
The architecture separates reading from writing at the agent level. A Leader coordinates two workers. The Analyst reads the public schema and the dash schema, holds read-only SQL tools, and can call introspect_schema, save_validated_query, and ReasoningTools. The Engineer reads public but writes only to dash, holds full SQL tools, and can call introspect_schema, update_knowledge, and ReasoningTools. The Leader optionally carries SlackTools.
That split is the most interesting design decision in the repository. The public schema holds company data loaded externally and is described as read-only, never modified by agents. The dash schema is agent-managed and holds views and summary tables. Because the Engineer owns dash, it can materialize a derived table or a view without touching source data. Because the Analyst cannot write anywhere, a bad generated query has no path to mutating company tables even if the model is wrong.
The enforcement is described as read-only SQL enforcement at the security layer, alongside AgentOS auth and RBAC. The README does not spell out how that enforcement is implemented (a database role, a query parser, or both), so if you need to know whether a prompt injection could escape the boundary, you have to read the code in dash/agents/ rather than the README.
Knowledge and Learnings Are Two Different Stores
Dash keeps two memory systems with different owners. Knowledge holds validated queries and business context, curated by you and by Dash, and lives in a table called dash_knowledge. Learnings hold error patterns and fixes, managed automatically by the Agno Learning Machine, and live in dash_learnings.
The distinction matters operationally. Knowledge is a reviewed asset: table schemas, human annotations, known-good SQL, business rules, dash views. Learnings are machine-written and grow from failure. The loop in the README runs retrieve, reason, generate, execute, then branches. On success it returns an insight and may save the query as knowledge. On error it diagnoses, fixes, and saves a learning, with the stated intent that the error is never repeated. Nothing in the supplied material shows a measurement of whether that intent holds, so treat the claim as a design goal rather than a verified outcome.
The six context layers are: table usage from knowledge/tables/*.json, human annotations from knowledge/business/*.json, query patterns from knowledge/queries/*.sql, institutional knowledge via optional MCP, learnings from the Learning Machine, and runtime context from introspect_schema. Four of the six are files you author or approve. That is the real cost of this project: the agent is only as grounded as the JSON and SQL you put in those directories.
Getting It Running Locally
The README gives a short path. Clone the repository, copy example.env to .env, add an OPENAI_API_KEY, then run docker compose up -d --build. Two scripts run inside the container: python scripts/generate_data.py and python scripts/load_knowledge.py. The API is expected at http://localhost:8000/docs.
The AgentOS web UI is a separate hosted service. You open os.agno.com, log in, choose Add OS, Local, enter http://localhost:8000, and click Connect. Slack is listed as an optional interface, so the terminal and the web UI are the default surfaces.
Production on Railway is more involved and the README is honest about the sequence. You copy example.env to .env.production, run railway login, then ./scripts/railway_up.sh. The documentation warns that the app will crash-loop until the JWT key is added, and calls that expected. You then take the Railway domain, register it in AgentOS as a Live OS, generate a key pair under Settings, and paste the public key into .env.production as JWT_VERIFICATION_KEY wrapped in single quotes. Two more scripts finish the job: railway_env.sh pushes each variable to the service (the README notes it is safe to re-run and handles multiline PEM values) and railway_redeploy.sh restarts. Database scripts must run through railway ssh --service dash because the internal hostname pgvector.railway.internal is not reachable from your machine. Logs and the dashboard come from railway logs --service dash and railway open.
Where Dash Is the Wrong Tool
The deployment model is the first constraint. Production requires an AgentOS account to mint a JWT key pair, and the web UI is hosted at os.agno.com. If your organization will not register an external service to obtain a verification key, the documented production path does not work for you, even though the code is Apache-2.0.
The second constraint is the model provider. The quick start asks for OPENAI_API_KEY and nothing in the material describes a provider abstraction or a local-model path. Anyone with a data residency rule against sending schema text and query results to a hosted model should stop at the README.
The third constraint is the shape of the data. Dash assumes PostgreSQL with pgvector, a public schema loaded externally, and a body of business definitions worth writing into knowledge/business/*.json. On a one-table dataset, the six-layer apparatus is overhead with no payoff. On a schema that changes daily, the curated knowledge files become stale faster than anyone will update them, and the runtime introspect_schema layer is doing most of the work anyway.
Finally, error handling is probabilistic. The loop saves a learning after a fix, but the material contains no evaluation harness, no test suite description, and no accuracy figure. If you need a number before rollout, you have to build the evaluation yourself.
Compared With a Semantic Layer
The closest conventional alternative is a semantic layer such as dbt's metric definitions or a Cube-style metrics API, where a human defines each metric once in YAML or code and every consumer queries that definition. The difference in approach is where the meaning lives. A semantic layer puts it in a versioned artifact that a human reviews and that a BI tool reads. Dash puts it in a retrieval store that the agent reads at query time, and lets the agent append to that store after a successful run.
That trade is legible. A semantic layer is deterministic and testable; a query either matches the metric definition or it does not. Dash is adaptive, which means its answers depend on what has been retrieved and what has been learned so far, and two runs against the same question are not guaranteed to produce the same SQL. For a regulated reporting pipeline, the semantic layer wins on auditability. For a long tail of ad hoc questions where nobody will write a metric definition, Dash's save_validated_query path is the cheaper way to accumulate coverage, because the agent writes the first draft of the knowledge entry instead of a data engineer.
Maintenance Cost and Licence Position
Two stores need care. dash_knowledge accumulates validated queries and business rules; without review, wrong-but-plausible SQL can be saved and then retrieved as grounding for later questions. The README says knowledge is curated by you and Dash, so the review step is yours to define. dash_learnings grows automatically, and the material does not describe a pruning, expiry, or conflict-resolution mechanism, so a learning that was correct against an old schema may persist after the schema changes. The Engineer's update_knowledge tool exists to record schema changes, which suggests the intended remedy, but the README does not describe how stale entries are retired.
Upgrades also touch the Agno dependency, since the Learning Machine and AgentOS come from that project, and the production path depends on the hosted os.agno.com service for key generation. Version drift between the local agent code and the hosted control plane is a real operational question the README does not address.
The repository is Apache-2.0, which permits commercial use and modification with the usual notice and patent terms. That covers Dash's own code. It does not automatically cover the Agno packages Dash imports or the hosted AgentOS service, whose terms are separate. Check the licence of each dependency before shipping, and treat the Apache-2.0 label as the starting point of that review rather than the end of it.
Editorial conclusion
Dash fits teams that already run PostgreSQL with pgvector, have a schema worth documenting, and want an agent they can extend rather than a closed analytics product. It does not fit anyone who wants a hosted BI tool or cannot supply an OPENAI_API_KEY. Before adopting, read dash/team.py and dash/agents/ to confirm the tool boundaries match your data policy, and check the licence text for the Agno dependency.
Community notes