How agno-agi/dash works
1. What this repo is
- Dash is a Python-based text-to-SQL data agent for the F1 sample domain.
- The architecture is centered on one core loop: understand the question, retrieve grounding context, generate SQL, run it, explain the result, and remember what happened.
2. Two runtime entrypoints
- app/main.py is the service entrypoint used when running Dash as an API server.
- dash/__main__.py exposes the same core package as a CLI mode.
- Both appear to share the same underlying agent implementation in dash/agent.py.
3. Core orchestration layer
- dash/agent.py is the main orchestrator.
- It likely coordinates prompt construction, context retrieval, SQL generation, execution, result interpretation, and learning/persistence.
- This is the main boundary to draw in the diagram: everything else supports this loop.
4. Grounding / context subsystem
- dash/context/semantic_model.py and dash/context/business_rules.py define the agent’s semantic layer.
- This is where raw schema is translated into human-meaningful concepts like metrics, business rules, and table meanings.
- The repo’s “6 layers of context” concept is implemented around this subsystem plus external retrieval.
5. Curated knowledge assets
- dash/knowledge/tables/*.json captures table descriptions, use cases, and caveats.
- dash/knowledge/business/*.json stores metric definitions and business rules.
- dash/knowledge/queries/*.sql stores validated query patterns the agent can reuse.
- These files are versioned in the repo, then loaded into runtime storage by scripts.
6. Runtime schema introspection
- dash/tools/introspect.py provides live schema inspection.
- This is the “current state” boundary: it lets the agent adapt to schema changes that are not reflected in static knowledge.
- In the architecture, place this as a bridge from the agent to the operational database.
7. Learning and reuse
- dash/tools/save_query.py and the “learning” flow described in the README support the self-improving loop.
- Successful queries and discovered fixes become reusable knowledge; recurring failures become learned patterns.
- This is the key feedback path that makes the system improve without retraining.
8. Database layer
- db/session.py and db/url.py isolate database connectivity.
- The app’s working data, loaded knowledge, and learned artifacts are all expected to be stored behind this DB boundary.
- dash/scripts/load_data.py seeds the sample dataset; dash/scripts/load_knowledge.py imports the curated context into the system.
9. Evaluation harness
- dash/evals/test_cases.py, dash/evals/grader.py, and dash/evals/run_evals.py form an offline benchmark subsystem.
- This is separate from production serving and is used to validate question answering, SQL quality, and groundedness.
- In a diagram, keep evals outside the main request path.
10. Deployment and operations
- Dockerfile, compose.yaml, and scripts/* define local and production operations.
- railway.json and the Railway scripts show a deployment path to Railway.
- .github/workflows/validate.yml suggests CI validation of the repo before deployment.
11. External dependencies that matter
- OPENAI_API_KEY is required for the LLM-backed agent behavior.
- EXA_API_KEY is optional for external web search / institutional knowledge.
- The README also references the Agno ecosystem for learning behavior, which is part of the agent’s adaptive loop.
12. How data flows through the system
- User question enters via API or CLI.
- The agent retrieves static knowledge, learned patterns, and live schema context.
- It generates SQL, executes against the database, then interprets results into a useful answer.
- On success it may store reusable knowledge; on failure it stores a learning so the same mistake is less likely next time.
13. Good diagram boundaries
- Draw the core service boundary around dash/ plus app/.
- Draw the database as an external persistence boundary.
- Draw dash/knowledge/ as a repo-managed knowledge source feeding ingestion scripts.
- Draw dash/evals/ and scripts/ as offline/supporting systems, not part of the request runtime.
Main entry points: agent.py Agent loop · session.py DB session · run_evals.py Eval runner · main.py API server
Components 19
Runtime service
API and CLI entrypoints plus the core agent loop.
- API server · Runs Dash as a service endpoint.
app/main.py - CLI mode · Runs the same package in command-line mode.
dash/__main__.py - Agent loop · Coordinates question understanding, retrieval, SQL generation, execution, explanation, and memory.
dash/agent.py - Schema introspect · Inspects the live database schema to adapt to current state.
dash/tools/introspect.py - Save query · Persists successful queries and learned fixes for reuse.
dash/tools/save_query.py
Knowledge layer
Repo-managed semantic, business, and query assets that ground the agent.
- Semantic model · Maps raw schema into business concepts and metric meaning.
dash/context/semantic_model.py - Business rules · Encodes domain caveats and rules that constrain answers.
dash/context/business_rules.py - Table docs · Curated table descriptions, use cases, and caveats.
dash/knowledge/tables - Metric defs · Curated business metric definitions and rule metadata.
dash/knowledge/business/metrics.json - Query patterns · Validated SQL patterns that can be reused by the agent.
dash/knowledge/queries/common_queries.sql
Database boundary
Persistence and live operational schema access.
- DB session · Connection/session boundary for application persistence.
db/session.py - DB URL · Builds or resolves the database connection URL.
db/url.py - Operational DB · Stores working data, knowledge imports, and learned artifacts.
Support systems
Offline loading, evaluation, and deployment tooling.
- Load knowledge · Imports curated context assets into runtime storage.
dash/scripts/load_knowledge.py - Seed data · Loads the sample F1 dataset used by the agent and evals.
dash/scripts/load_data.py - Eval runner · Runs offline benchmark cases against the system.
dash/evals/run_evals.py - Grader · Scores answer quality, SQL validity, and groundedness.
dash/evals/grader.py - Test cases · Benchmark questions and expected behaviors.
dash/evals/test_cases.py - Deployment · Container, compose, Railway, and CI deployment boundary.
Connections 21
- API server → Agent loop: requests · API requests enter the core agent loop.
- CLI mode → Agent loop: invokes · CLI mode reuses the same agent implementation.
- Agent loop → Semantic model: grounds in · Uses semantic context to interpret tables and metrics.
- Agent loop → Business rules: applies · Constrains reasoning with domain rules and caveats.
- Agent loop → Table docs: retrieves · Pulls table-level documentation as grounding context.
- Agent loop → Metric defs: retrieves · Pulls metric definitions for domain meaning.
- Agent loop → Query patterns: reuses · Reuses validated SQL patterns when applicable.
- Agent loop → Schema introspect: inspects · Checks the live schema before generating SQL.
- Schema introspect → DB session: reads schema via · Schema inspection uses the database session boundary.
- Agent loop → DB session: executes against · Runs generated SQL and reads results from the database.
- DB session → DB URL: configured by · Session connectivity is built from the database URL config.
- DB session → Operational DB: connects to · Application state and data persist in the operational database.
- Save query → DB session: persists via · Writes learned queries and fixes back through the DB boundary.
- Agent loop → Save query: learns · Successful or corrected runs are stored for future reuse.
- Load knowledge → Operational DB: imports · Loads curated knowledge assets into runtime storage.
- Seed data → Operational DB: seeds · Populates the sample domain data.
- Eval runner → Test cases: uses · Evaluation runs are driven by benchmark cases.
- Eval runner → Grader: scores with · Results are judged by the grader.
- Grader → Agent loop: evaluates · Offline grading measures the behavior of the core agent.
- Deployment → API server: ships · Container and deployment tooling package the service entrypoint.
- Deployment → Eval runner: supports · Ops tooling also supports offline validation workflows.