[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74159":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":17,"stars30d":14,"stars90d":16,"forks30d":16,"starsTrendScore":18,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":16,"starSnapshotCount":16,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},74159,"dash","agno-agi\u002Fdash","agno-agi","A self-learning data agent built with systems engineering principles. It grounds answers in 6 layers of context and improves with every query.","",null,"Python",2082,236,20,5,0,4,12,71.12,"Apache License 2.0",false,"main",true,[],"2026-06-12 04:01:13","# Dash\n\nA **self-learning data agent** built with systems engineering principles. It grounds answers in 6 layers of context and improves with every query.\n\nChat with Dash via Slack, the terminal, or the [AgentOS](https:\u002F\u002Fos.agno.com?utm_source=github&utm_medium=example-repo&utm_campaign=agent-example&utm_content=dash&utm_term=agentos) web UI.\n\n## Quick Start\n\n```sh\n# Clone the repo\ngit clone https:\u002F\u002Fgithub.com\u002Fagno-agi\u002Fdash.git && cd dash\n\ncp example.env .env\n# Edit .env and add your OPENAI_API_KEY\n\n# Start the system\ndocker compose up -d --build\n\n# Generate sample data and load knowledge\ndocker exec -it dash-api python scripts\u002Fgenerate_data.py\ndocker exec -it dash-api python scripts\u002Fload_knowledge.py\n```\n\nConfirm Dash is running at [http:\u002F\u002Flocalhost:8000\u002Fdocs](http:\u002F\u002Flocalhost:8000\u002Fdocs).\n\n### Connect to the Web UI\n\n1. Open [os.agno.com](https:\u002F\u002Fos.agno.com?utm_source=github&utm_medium=example-repo&utm_campaign=agent-example&utm_content=dash&utm_term=agentos) and login\n2. Add OS → Local → `http:\u002F\u002Flocalhost:8000`\n3. Click \"Connect\"\n\n**Try it** (SaaS metrics dataset):\n\n- What's our current MRR?\n- Which plan has the highest churn rate?\n- Show me revenue trends by plan over the last 6 months\n- Which customers are at risk of churning?\n\n## Deploy to Railway\n\nRailway deployment uses `.env.production` to keep production credentials separate from local dev.\n\n```sh\ncp example.env .env.production\n# Edit .env.production — set OPENAI_API_KEY\n```\n\n### Step 1: Deploy infrastructure\n\nThis creates the Railway project, database, and app service. The app will crash-loop until the JWT key is added in the next step — that's expected.\n\n```sh\nrailway login\n.\u002Fscripts\u002Frailway_up.sh\n```\n\n### Step 2: Get your JWT key\n\nProduction requires a `JWT_VERIFICATION_KEY` from [AgentOS](https:\u002F\u002Fos.agno.com?utm_source=github&utm_medium=example-repo&utm_campaign=agent-example&utm_content=dash&utm_term=agentos). You need the Railway domain from step 1 to set this up.\n\n1. Copy your Railway domain from the output of step 1 (e.g. `dash-production-xxxx.up.railway.app`)\n2. Open [os.agno.com](https:\u002F\u002Fos.agno.com?utm_source=github&utm_medium=example-repo&utm_campaign=agent-example&utm_content=dash&utm_term=agentos) and login\n3. Add OS → Live → paste your Railway URL\n4. Go to **Settings** and generate a key pair\n5. Add the public key to `.env.production` (wrap in single quotes):\n\n```bash\nJWT_VERIFICATION_KEY='-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----'\n```\n\n### Step 3: Push environment and redeploy\n\n```sh\n.\u002Fscripts\u002Frailway_env.sh\n.\u002Fscripts\u002Frailway_redeploy.sh\n```\n\n`railway_env.sh` reads `.env.production` and sets each variable on the Railway service. Safe to run repeatedly. Handles multiline values (PEM keys) correctly.\n\n### Production operations\n\nDatabase scripts must run inside Railway's network (the internal hostname `pgvector.railway.internal` isn't reachable from your local machine). Use SSH to connect to the running container:\n\n```sh\nrailway ssh --service dash\n# Inside the container:\npython scripts\u002Fgenerate_data.py\npython scripts\u002Fload_knowledge.py\n```\n\nOther operations run locally:\n\n```sh\nrailway logs --service dash\nrailway open\n```\n\n## Why Dash Exists\n\nAsk a question in English, get a correct, meaningful answer. That's the goal. But raw LLMs writing SQL hit a wall fast: schemas lack meaning, types are misleading, tribal knowledge is missing, there's no way to learn from mistakes, and results lack interpretation.\n\nThe root cause is missing context and missing memory. Dash solves this with **six layers of grounded context**, a **self-learning loop** that improves with every query, and a focus on delivering insights you can act on.\n\n## Architecture: Five Layers, One System\n\nAgentic software is just software with the business logic replaced by agents. Everything else is systems engineering. Dash is built across five layers that reinforce each other.\n\n```\nAgent Engineering     →  dash\u002Fteam.py + dash\u002Fagents\u002F\nData Engineering      →  knowledge\u002F + Agno Learning Machine + PostgreSQL\nSecurity Engineering  →  AgentOS auth + RBAC + read-only SQL enforcement\nInterface Engineering →  app\u002Fmain.py (FastAPI) + Slack + AgentOS\nInfrastructure        →  Dockerfile + compose.yaml + scripts\u002F\n```\n\n### 1. Agent Engineering\n\nThe agent team and execution flow. Model, instructions, tools, knowledge, and the self-learning loop.\n\n```\nAgentOS (app\u002Fmain.py)  [scheduler=True, tracing=True]\n ├── FastAPI \u002F Uvicorn\n ├── Slack Interface (optional)\n └── Dash Team (dash\u002Fteam.py, coordinate mode)\n     ├─ Analyst (dash\u002Fagents\u002Fanalyst.py)         reads public + dash\n     │  ├─ SQLTools (read-only)  → public schema (company data)\n     │  ├─ introspect_schema     → both schemas\n     │  ├─ save_validated_query  → knowledge base\n     │  └─ ReasoningTools\n     ├─ Engineer (dash\u002Fagents\u002Fengineer.py)       reads public, writes dash\n     │  ├─ SQLTools (full)       → dash schema (agent-managed)\n     │  ├─ introspect_schema     → both schemas\n     │  ├─ update_knowledge      → knowledge base (schema changes)\n     │  └─ ReasoningTools\n     │\n     Leader tools: SlackTools (optional)\n     Knowledge:    dash_knowledge (table schemas, queries, business rules, dash views)\n     Learnings:    dash_learnings (error patterns, type gotchas, fixes)\n```\n\n### 2. Data Engineering\n\nContext is data. Memory is data. Knowledge is data. All managed with data engineering principles: well-designed schemas, structured querying, databases for fast read\u002Fwrites.\n\n**Six layers of grounded context:**\n\n| Layer | Purpose | Source |\n|------|--------|--------|\n| **Table Usage** | Schema, columns, relationships | `knowledge\u002Ftables\u002F*.json` |\n| **Human Annotations** | Metrics, definitions, business rules | `knowledge\u002Fbusiness\u002F*.json` |\n| **Query Patterns** | SQL that is known to work | `knowledge\u002Fqueries\u002F*.sql` |\n| **Institutional Knowledge** | Docs, wikis, external references | MCP (optional) |\n| **Learnings** | Error patterns and discovered fixes | Agno `Learning Machine` |\n| **Runtime Context** | Live schema changes | `introspect_schema` tool |\n\n**The self-learning loop:**\n\n```\nUser Question\n     ↓\nRetrieve Knowledge + Learnings\n     ↓\nReason about intent\n     ↓\nGenerate grounded SQL\n     ↓\nExecute and interpret\n     ↓\n ┌────┴────┐\n ↓         ↓\nSuccess    Error\n ↓         ↓\n ↓         Diagnose → Fix → Save Learning\n ↓                           (never repeated)\n ↓\nReturn insight\n ↓\nOptionally save as Knowledge\n```\n\nTwo complementary systems:\n\n| System | Stores | How It Evolves |\n|------|--------|----------------|\n| **Knowledge** | Validated queries and business context | Curated by you + Dash |\n| **Learnings** | Error patterns and fixes | Managed by `Learning Machine` automatically |\n\n**Dual schema enforcement:** A structural boundary between company data and agent-managed data.\n\n| Schema | Owner | Access |\n|--------|-------|--------|\n| `public` | Company (loaded externally) | Read-only — never modified by agents |\n| `dash` | Engineer agent | Views, summary tables, computed data |\n\nThe Engineer builds reusable data assets (`dash.monthly_mrr`, `dash.customer_health_score`, `dash.churn_risk`) and records them to knowledge. The Analyst discovers and prefers these views over raw table queries.\n\n### 3. Security Engineering\n\nAuth uses RBAC with JWT verification in production. Every query is scoped to `user_id`. Read-only access is a tool configuration, not a prompt instruction. The Analyst agent's SQL tools are scoped to read-only at the system level.\n\nSee [Security](#security) for setup details.\n\n### 4. Interface Engineering\n\nOne agent definition, multiple surfaces. Dash is reachable via REST API (FastAPI), Slack threads, and the AgentOS web UI. Each surface has its own identity system: a Slack user ID maps to sessions via thread timestamps, the API uses JWT-backed auth.\n\n### 5. Infrastructure Engineering\n\nDockerfile, Docker Compose, one-command deployment. Scheduled tasks for proactive behavior. The infrastructure layer is boring on purpose. 95% of running an agent is identical to running any other service.\n\n## Slack\n\nDash can receive Slack DMs, @mentions, and thread replies, and can also post to channels proactively.\n\nQuick setup:\n1. Run Dash and give it a public URL (ngrok locally, or your Railway domain).\n2. Follow [docs\u002FSLACK_CONNECT.md](docs\u002FSLACK_CONNECT.md) to create and install the Slack app from the manifest.\n3. Set `SLACK_TOKEN` and `SLACK_SIGNING_SECRET`, then restart Dash.\n4. In Slack, confirm Event Subscriptions is verified and send a DM or `@mention` to test it.\n\nEach Slack thread maps to one Dash session. For the manifest, ngrok commands, Railway deployment, permissions, and troubleshooting, see [docs\u002FSLACK_CONNECT.md](docs\u002FSLACK_CONNECT.md).\n\n## Data Model (SaaS Metrics)\n\nSynthetic B2B SaaS dataset (~900 customers, 2 years of data):\n\n| Table | Description |\n|-------|-------------|\n| `customers` | Company info, industry, size, acquisition source, status |\n| `subscriptions` | Plan, MRR, seats, billing cycle, lifecycle status |\n| `plan_changes` | Upgrades, downgrades, cancellations with MRR impact |\n| `invoices` | Billing records, payment status, billing periods |\n| `usage_metrics` | Daily API calls, active users, storage, reports |\n| `support_tickets` | Priority, category, resolution time, satisfaction |\n\n## Adding Knowledge\n\nDash works best when it understands how your organization talks about data.\n\n```\nknowledge\u002F\n├── tables\u002F      # Table meaning and caveats\n├── queries\u002F     # Proven SQL patterns\n└── business\u002F    # Metrics and language\n```\n\n### Table Metadata\n\n```json\n{\n  \"table_name\": \"customers\",\n  \"table_description\": \"B2B SaaS customer accounts with company info and lifecycle status\",\n  \"use_cases\": [\"Churn analysis\", \"Cohort segmentation\", \"Acquisition reporting\"],\n  \"data_quality_notes\": [\n    \"signup_date is DATE (not TIMESTAMP) — no time component\",\n    \"status values: active, churned, trial\",\n    \"company_size is self-reported\"\n  ]\n}\n```\n\n### Query Patterns\n\n```sql\n-- \u003Cquery monthly_mrr>\n-- \u003Cdescription>Monthly MRR from active subscriptions\u003C\u002Fdescription>\n-- \u003Cquery>\nSELECT\n    DATE_TRUNC('month', started_at) AS month,\n    SUM(mrr) AS total_mrr\nFROM subscriptions\nWHERE ended_at IS NULL\nGROUP BY 1\nORDER BY 1 DESC\n-- \u003C\u002Fquery>\n```\n\n### Business Rules\n\n```json\n{\n  \"metrics\": [\n    {\n      \"name\": \"MRR\",\n      \"definition\": \"Sum of active subscriptions excluding trials\"\n    }\n  ],\n  \"common_gotchas\": [\n    {\n      \"issue\": \"Active subscription detection\",\n      \"solution\": \"Filter on ended_at IS NULL, not status column\"\n    }\n  ]\n}\n```\n\n### Load Knowledge\n\n```sh\npython scripts\u002Fload_knowledge.py            # Upsert changes\npython scripts\u002Fload_knowledge.py --recreate  # Fresh start\n```\n\n## Evaluations\n\nFive eval categories using Agno's eval framework:\n\n| Category | Eval Type | What It Tests |\n|----------|-----------|---------------|\n| accuracy | AccuracyEval (1-10) | Correct data and meaningful insights |\n| routing | ReliabilityEval | Team routes to correct agent\u002Ftools |\n| security | AgentAsJudgeEval (binary) | No credential or secret leaks |\n| governance | AgentAsJudgeEval (binary) | Refuses destructive SQL operations |\n| boundaries | AgentAsJudgeEval (binary) | Schema access boundaries respected |\n\n```sh\npython -m evals                      # Run all evals\npython -m evals --category accuracy  # Run specific category\npython -m evals --verbose            # Show response details\n```\n\n## Local Development\n\n```sh\n.\u002Fscripts\u002Fvenv_setup.sh && source .venv\u002Fbin\u002Factivate\ndocker compose up -d dash-db\npython scripts\u002Fgenerate_data.py\npython scripts\u002Fload_knowledge.py\npython -m dash            # CLI mode\npython -m app.main        # AgentOS mode (web UI at os.agno.com)\n```\n\n## Environment Variables\n\n| Variable | Required | Default | Purpose |\n|----------|----------|---------|---------|\n| `OPENAI_API_KEY` | Yes | — | OpenAI API key |\n| `SLACK_TOKEN` | No | `\"\"` | Slack bot token (interface + tools) |\n| `SLACK_SIGNING_SECRET` | No | `\"\"` | Slack signing secret (interface only) |\n| `DB_HOST` | No | `localhost` | PostgreSQL host |\n| `DB_PORT` | No | `5432` | PostgreSQL port |\n| `DB_USER` | No | `ai` | PostgreSQL user |\n| `DB_PASS` | No | `ai` | PostgreSQL password |\n| `DB_DATABASE` | No | `ai` | PostgreSQL database |\n| `PORT` | No | `8000` | API port |\n| `RUNTIME_ENV` | No | `prd` | `dev` enables hot reload |\n| `AGENTOS_URL` | No | `http:\u002F\u002F127.0.0.1:8000` | Scheduler callback URL (production) |\n| `JWT_VERIFICATION_KEY` | Production | — | RBAC public key from [os.agno.com](https:\u002F\u002Fos.agno.com?utm_source=github&utm_medium=example-repo&utm_campaign=agent-example&utm_content=dash&utm_term=agentos) |\n\n## Security\n\nProduction deployments require authentication via [Agno AgentOS](https:\u002F\u002Fdocs.agno.com\u002Fagent-os\u002Fsecurity\u002Foverview?utm_source=github&utm_medium=example-repo&utm_campaign=agent-example&utm_content=dash&utm_term=security). Dash enables [RBAC authorization](https:\u002F\u002Fdocs.agno.com\u002Fagent-os\u002Fsecurity\u002Frbac?utm_source=github&utm_medium=example-repo&utm_campaign=agent-example&utm_content=dash&utm_term=rbac) when `RUNTIME_ENV=prd` (the default). Without a valid `JWT_VERIFICATION_KEY`, production endpoints will reject all requests.\n\nLocal development (`RUNTIME_ENV=dev`, set by Docker Compose) runs without auth so you can iterate freely.\n\n### Auth Setup\n\nSee [Deploy to Railway](#deploy-to-railway) for the full setup flow, including how to get your `JWT_VERIFICATION_KEY` from AgentOS. The Agno control plane handles JWT issuance, session management, traces, metrics, and the web UI. See the [AgentOS Security docs](https:\u002F\u002Fdocs.agno.com\u002Fagent-os\u002Fsecurity\u002Foverview?utm_source=github&utm_medium=example-repo&utm_campaign=agent-example&utm_content=dash&utm_term=security) for details.\n\n### Schema-Level Enforcement\n\nBeyond API-level auth, Dash enforces data access at the database level:\n\n- **Analyst** connects with `default_transaction_read_only=on` — PostgreSQL rejects any write attempt\n- **Engineer** writes are scoped to the `dash` schema — a SQLAlchemy event listener blocks any DDL\u002FDML targeting `public`\n- **Leader** has no direct database access\n\nThese are infrastructure guardrails, not prompt instructions. They hold regardless of what the model generates.\n\n## Learn More\n\n- [OpenAI's In-House Data Agent](https:\u002F\u002Fopenai.com\u002Findex\u002Finside-our-in-house-data-agent\u002F) — the inspiration\n- [Self-Improving SQL Agent](https:\u002F\u002Fwww.ashpreetbedi.com\u002Farticles\u002Fsql-agent) — deep dive on an earlier architecture\n- [Agno Docs](https:\u002F\u002Fdocs.agno.com?utm_source=github&utm_medium=example-repo&utm_campaign=agent-example&utm_content=dash&utm_term=docs)\n\n\u003Cp align=\"center\">Built on \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fagno-agi\u002Fagno\">Agno\u003C\u002Fa> · the runtime for agentic software\u003C\u002Fp>","Dash是一个基于系统工程原则构建的自学习数据代理，它通过六层上下文来提供答案，并随着每次查询而不断改进。项目采用Python编写，核心功能包括多渠道接入（如Slack、终端和AgentOS网页界面）以及自动化的知识加载与更新机制，特别适合需要高效处理和分析数据的企业或团队使用，尤其是在监控SaaS指标方面表现优异，能够快速响应关于月度经常性收入(MRR)、客户流失率等关键业务问题。此外，该项目支持Docker容器化部署及Railway云平台托管，便于用户在不同环境下轻松搭建和管理自己的数据代理服务。",2,"2026-06-11 03:49:04","high_star"]