[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-79914":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":13,"stars7d":13,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":17,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":30,"readmeContent":31,"aiSummary":32,"trendingCount":16,"starSnapshotCount":16,"syncStatus":14,"lastSyncTime":33,"discoverSource":34},79914,"byaan","byaan-ai\u002Fbyaan","byaan-ai","Open-Source data analyst your team actually owns. Ask in Slack, on Mac, or via MCP. Byaan learns your business. Read-only by design","https:\u002F\u002Fwww.byaan.ai\u002F",null,"Python",92,1,2,4,0,3,43.7,"MIT License",false,"main",true,[24,25,26,27,28,29],"ai","ai-agents","data-analytics","mcp","privacy","self-hosted","2026-06-12 04:01:25","\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Flogo.png\" alt=\"Byaan\" width=\"120\" \u002F>\n\u003C\u002Fp>\n\n\u003Ch1 align=\"center\">Byaan\u003C\u002Fh1>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>The AI data agent that actually learns your databases.\u003C\u002Fstrong>\u003Cbr\u002F>\n  \u003Csub>Ask questions in plain English, get interactive dashboards. Bring your own models. Keep your databases private.\u003C\u002Fsub>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"docs\u002Flicensing.md\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT%20%2B%20ELv2-blue.svg\" alt=\"MIT and Elastic License 2.0\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fbyaan-ai\u002Fbyaan\u002Freleases\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fbyaan-ai\u002Fbyaan\" alt=\"Latest Release\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fhub.docker.com\u002Fr\u002Fbyaan\u002Fself-hosted\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fdocker\u002Fpulls\u002Fbyaan\u002Fself-hosted\" alt=\"Docker Pulls\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fwww.byaan.ai\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fwebsite-byaan.ai-orange\" alt=\"Website\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fwww.byaan.ai\">Website\u003C\u002Fa> ·\n  \u003Ca href=\"#quick-start\">Quick Start\u003C\u002Fa> ·\n  \u003Ca href=\"docs\u002Fself-hosted\u002FREADME.md\">Self-Hosted Docs\u003C\u002Fa> ·\n  \u003Ca href=\"docs\u002Fsecurity\u002Fread-only-guardrails.md\">Read-Only Guardrails\u003C\u002Fa> ·\n  \u003Ca href=\"docs\u002Fsecurity\u002Fgithub-actions-hardening.md\">Actions Hardening\u003C\u002Fa> ·\n  \u003Ca href=\"CONTRIBUTING.md\">Contributing\u003C\u002Fa> ·\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fbyaan-ai\u002Fbyaan\u002Fissues\">Issues\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cbr \u002F>\n\n\u003Cp align=\"center\">\n  \u003Cvideo\n    src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fb2ffe92e-99b6-4ad9-8337-8a199da7c81c\"\n    autoplay\n    loop\n    muted\n    playsinline\n    width=\"800\"\n    poster=\"assets\u002Fhero.png\"\n  >\u003C\u002Fvideo>\n\u003C\u002Fp>\n\n---\n\n## What is Byaan?\n\nByaan is for teams and builders who want an AI analyst connected to their own data, not a generic chat box that forgets everything after each answer.\n\nUse Byaan to:\n\n- Ask questions across databases, files, and business context in plain English\n- Turn answers into inspectable queries, charts, dashboards, and scheduled reports\n- Let your data knowledge compound over time instead of rebuilding context in every conversation\n\nMost AI data tools fail for three reasons:\n\n1. **They lack business context.** What does \"revenue\" mean at your company? Which transactions to exclude? What's the fiscal year? Generic AI doesn't know.\n2. **They pick the wrong tables.** With dozens of data sources, AI guesses — and guesses wrong.\n3. **They don't learn.** Every session starts from scratch. Same question, same mistakes.\n\nByaan solves this by building persistent context around your data. It auto-discovers your schema, learns your metric definitions and business rules, and stores that knowledge so every conversation builds on the last. Connect it to your GitHub repos and it learns your codebase context too.\n\nThe result is an agent that can accumulate your data's tribal knowledge instead of treating every conversation as a stateless text-to-SQL prompt.\n\nWe believe your databases should stay private: on your laptop or within your organization's infrastructure. Byaan runs as a native Mac app or a self-hosted Docker container. In local and community deployments, Byaan connects directly to the model providers you configure instead of routing database traffic through Byaan-hosted infrastructure.\n\n## Privacy At A Glance\n\n| Deployment | Where Byaan runs | Auth | Best for | Internet exposure |\n| --- | --- | --- | --- | --- |\n| Mac App | Your Mac | Local app | Personal analysis | Not exposed |\n| Community Docker | Your machine\u002Fserver | No built-in auth | Local single-user or trusted private network use | Do not expose directly |\n| Team Version | Your server\u002FVPC | Users, invitations, RBAC | Teams and production use | Use HTTPS and least-privilege database users |\n\nIn all modes, query results and relevant schema\u002Fcontext may be sent to the model provider you configure when an AI workflow needs model assistance. Database traffic is not routed through Byaan-hosted infrastructure in local desktop or community deployments.\n\n## Key Features\n\n- **Multi-database support** — PostgreSQL, MongoDB, MySQL, SQLite, MSSQL, ODBC, plus CSV\u002FExcel\u002FParquet\u002FJSON file uploads\n- **Local file analysis** — DuckDB-powered analytical queries over CSV, Excel, Parquet, and JSON files, subject to local machine resources\n- **Natural language to SQL, Mongo, or other databases** — ask questions about your data, inspect generated queries, and review results\n- **Interactive dashboards** — AI-generated charts and tables with dynamic filters and live data\n- **Bring Your Own Model** — Claude, OpenAI, Azure OpenAI, AWS Bedrock, Groq, OpenRouter, xAI\n- **Read-only guardrails** — explicit validation layers block known write operations across SQL, MongoDB, DynamoDB, and DuckDB flows\n- **MCP Server** — works with Claude Code, Cursor, and other MCP-compatible tools\n- **Shared team knowledge** — schema annotations, saved queries, metric definitions, and corrections compound across the workspace\n- **Dashboard exports** — standalone HTML dashboards, PDFs, or shareable links\n- **Secure API skills** — connect third-party APIs with built-in secrets management and domain whitelisting — the agent only calls endpoints you explicitly approve\n- **Scheduled queries** — automate recurring reports and analyses\n- **Desktop app** — download the Mac app and analyze data from your own machine\n\n## Quick Start\n\n\u003Cp>\u003Ca href=\"#mac-app\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMac_App-Download-blue?style=for-the-badge\" \u002F>\u003C\u002Fa>\u003C\u002Fp>\n\u003Cp>\u003Ca href=\"#community-version\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCommunity_Version-Docker-green?style=for-the-badge\" \u002F>\u003C\u002Fa>\u003C\u002Fp>\n\u003Cp>\u003Ca href=\"#team-version\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTeam_Version-Docker-orange?style=for-the-badge\" \u002F>\u003C\u002Fa>\u003C\u002Fp>\n\n| You want… | Use this |\n|---|---|\n| Personal use on a Mac, especially Apple Silicon | [Mac App](#mac-app) |\n| A local Docker instance for one person or a trusted private network | [Community Version](#community-version) |\n| A production deployment for a team with auth, RBAC, Slack, HTTPS, and shared organizational knowledge | [Team Version](#team-version) - most teams want this |\n\n---\n\n### Mac App\n\nFor personal use on macOS, especially on Apple Silicon Macs, we recommend the native Mac app. Download it directly from [downloads.byaan.ai\u002Fstable\u002Farm64\u002FByaan.dmg](https:\u002F\u002Fdownloads.byaan.ai\u002Fstable\u002Farm64\u002FByaan.dmg), or visit [byaan.ai](https:\u002F\u002Fwww.byaan.ai) and click **Download for Mac**.\n\nOpen the app, connect a database, and start asking questions. No account needed — configure your preferred LLM provider from within the app.\n\n---\n\n### Community Version\n\n**Docker (fastest)**\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fbyaan-ai\u002Fbyaan.git\ncd byaan\ndocker compose up -d\n```\n\nOpen http:\u002F\u002Flocalhost:17434 and start querying.\n\nThe community version is intentionally simple and does not include built-in user authentication. Run it locally or behind your own private network controls. For an internet-facing deployment, use the [Team Version](#team-version).\n\n**Development**\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fbyaan-ai\u002Fbyaan.git\ncd byaan\nmake setup        # Build Docker images (community\u002FSQLite version)\nmake dev          # Start backend (port 17433) + frontend (port 17434) with logs\nmake dev-detach   # Start in background\nmake stop         # Stop services\n```\n\nIf you use Claude Code, Cursor, Codex CLI, or Gemini CLI, run `\u002Fbyaan:start` to automate the full setup: it installs dependencies, frees ports, starts services, analyzes your codebase, and configures MCP. Run `\u002Fbyaan:learn` after schema changes to re-analyze.\n\n| Command | What it does |\n| --- | --- |\n| `make setup` | Build Docker images (community version) |\n| `make dev` | Start community version (SQLite, ports 17433\u002F17434) with logs |\n| `make dev-detach` | Start community version in background |\n| `make stop` | Stop community version |\n| `\u002Fbyaan:start` | Full onboarding (dependencies, services, MCP, codebase analysis) |\n| `\u002Fbyaan:learn` | Re-analyze codebase after schema changes |\n\n---\n\n### Team Version\n\n\u003Cp align=\"center\">\n  \u003Cvideo\n    src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fe3c79173-bf57-4242-b8f1-51c735299e31\"\n    autoplay\n    loop\n    muted\n    playsinline\n    width=\"800\"\n  >\u003C\u002Fvideo>\n\u003C\u002Fp>\n\nThe full multi-user deployment for teams. One container ships PostgreSQL, the FastAPI backend, the React frontend, and Caddy. Live on port 8080 in five minutes.\n\nTeam Version is where Byaan's learning loop becomes most valuable. Every teammate can contribute corrections, schema annotations, saved queries, dashboard patterns, metric definitions, and business rules. That shared context compounds across the workspace, so the agent gets better at your organization's data instead of forcing every person to teach it the same things again.\n\n**Requirements:** Linux server (Ubuntu 20.04+, Debian 11+, or any Docker-compatible OS), 2 GB RAM (4 GB recommended), 10 GB disk, Docker installed, ports 80\u002F443 (or 8080) free.\n\n**1. Install** — drops `start.sh` and `.env` into a `byaan` directory:\n\n```bash\ncurl -fsSL https:\u002F\u002Fdownloads.byaan.ai\u002Fdocker\u002Finstall.sh | bash\ncd byaan\n```\n\n**2. Configure** — open `.env` and set the four required values. `APP_SECRET` is auto-generated.\n\n```bash\nMASTER_USER_EMAIL=admin@yourcompany.com\nMASTER_USER_PASSWORD=\u003C8+ characters>\nORG_NAME=YourCompany\nDOMAIN=app.yourcompany.com   # optional — enables Let's Encrypt HTTPS\n```\n\n**Recommended auth setup:** for team deployments, configure Google SSO and hide email\u002Fpassword login. Keep the master admin password as a break-glass credential, but have teammates sign in with Google.\n\nCreate a Google OAuth web client in Google Cloud Console, add your Byaan domain as an authorized JavaScript origin, then set:\n\n```bash\nGOOGLE_CLIENT_ID=\u003Cgoogle-oauth-client-id>\nGOOGLE_CLIENT_SECRET=\u003Cgoogle-oauth-client-secret>\nVITE_GOOGLE_CLIENT_ID=\u003Csame-google-oauth-client-id>\nHIDE_EMAIL_AUTH=true\n```\n\nTo send invitation and password-reset emails automatically, configure SMTP:\n\n```bash\nSMTP_HOST=smtp.gmail.com\nSMTP_PORT=587\nSMTP_USERNAME=admin@yourcompany.com\nSMTP_PASSWORD=\u003Cgmail-app-password-or-smtp-password>\nSMTP_FROM_EMAIL=admin@yourcompany.com\nSMTP_FROM_NAME=Byaan\nSMTP_USE_TLS=true\n```\n\n**3. Start:**\n\n```bash\n.\u002Fstart.sh\n```\n\nOpen `http:\u002F\u002Fyour-server:8080` (or your `DOMAIN`). Sign in as the master admin you just configured, then invite teammates from **Settings → Members → Invite**.\n\n> **Note:** SMTP is optional. Without it, invitations are still created and the admin shares the generated link manually from the Members page. To send invitation emails automatically, add `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_FROM_EMAIL`, and `SMTP_USE_TLS` to `.env`. See [`docs\u002Fself-hosted\u002Fenv.example`](docs\u002Fself-hosted\u002Fenv.example) for the full reference.\n\n**What you get:**\n\n- Multi-user auth with invitations and RBAC roles (SMTP optional — share invitation links manually if email isn't configured)\n- Recommended Google-only sign-in for teams (`HIDE_EMAIL_AUTH=true` after Google OAuth is configured)\n- Shared workspace knowledge that compounds across teammates, databases, dashboards, and repeated analyses\n- Reusable metric definitions, saved queries, schema annotations, and business rules for the whole team\n- Slack integration — add `@byaan` to any channel, answers post in-thread\n- Optional Google OAuth SSO (drop in client ID + secret)\n- Automatic HTTPS via Let's Encrypt when `DOMAIN` is set\n- Blue-green zero-downtime updates: `.\u002Fstart.sh update`\n- All data in a single Docker volume — easy `pg_dump` backups\n\n**Common commands:**\n\n| Command | What it does |\n| --- | --- |\n| `.\u002Fstart.sh` | Start Byaan |\n| `.\u002Fstart.sh stop` | Stop Byaan |\n| `.\u002Fstart.sh update` | Pull latest image and recreate container (blue-green, zero-downtime) |\n| `.\u002Fstart.sh status` | Check if running |\n| `.\u002Fstart.sh logs` | Tail logs from all services |\n| `.\u002Fstart.sh logs backend` | Tail FastAPI backend logs |\n| `.\u002Fstart.sh logs caddy` | Tail Caddy reverse-proxy logs |\n| `.\u002Fstart.sh logs postgres` | Tail PostgreSQL logs |\n| `.\u002Fstart.sh remove` | Remove container, keep data volume |\n| `.\u002Fstart.sh remove --data` | Remove container and wipe all data |\n\nFull reference: [docs\u002Fself-hosted\u002FREADME.md](docs\u002Fself-hosted\u002FREADME.md).\n\n**Development (contributors):**\n\n```bash\nmake hosted-build # Build images and start hosted version (ports 8000\u002F5173) in background\nmake hosted       # Start hosted version in background\nmake hosted-logs  # Start with visible logs\nmake hosted-stop  # Stop hosted services\n```\n\n| Command | What it does |\n| --- | --- |\n| `make hosted-build` | Build images and start hosted version (PostgreSQL, ports 8000\u002F5173) in background |\n| `make hosted` | Start hosted version (PostgreSQL, ports 8000\u002F5173) in background |\n| `make hosted-logs` | Start hosted version with logs |\n| `make hosted-stop` | Stop hosted version |\n\nOpen http:\u002F\u002Flocalhost:5173 (frontend) or http:\u002F\u002Flocalhost:8000 (backend API).\n\n## MCP Integration (Model Context Protocol)\n\nByaan exposes an MCP interface that lets AI coding assistants query your connected databases through natural language. MCP clients talk to your local or hosted Byaan instance; model-provider requests follow the provider configuration you choose in Byaan.\n\n### How it works\n\n1. Open Byaan and connect your databases (Datasources page)\n2. Configure an AI model (Profile menu > AI Models)\n3. Add the MCP server to your AI client using the instructions below\n\n### Desktop App (stdio)\n\nThe desktop app bundles an MCP stdio server. No API key needed — it connects directly to your local database. The bundled binary auto-detects its database and configuration.\n\nYou can copy the config from the MCP icon in the app, or use the examples below. The binary is at `~\u002FLibrary\u002FApplication Support\u002Fcom.byaan.desktop\u002Fruntime\u002Fcurrent\u002Fbackend\u002Fbackend` (the `runtime\u002Fcurrent` symlink is updated automatically on each app launch).\n\n**Claude Code:**\n```bash\nclaude mcp add-json byaan '{\"type\":\"stdio\",\"command\":\"'\"$HOME\"'\u002FLibrary\u002FApplication Support\u002Fcom.byaan.desktop\u002Fruntime\u002Fcurrent\u002Fbackend\u002Fbackend\",\"args\":[\"-m\",\"server.mcp.stdio_server\"]}' --scope user\n```\n\n**Cursor** (`~\u002F.cursor\u002Fmcp.json` or `.cursor\u002Fmcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"byaan\": {\n      \"command\": \"~\u002FLibrary\u002FApplication Support\u002Fcom.byaan.desktop\u002Fruntime\u002Fcurrent\u002Fbackend\u002Fbackend\",\n      \"args\": [\"-m\", \"server.mcp.stdio_server\"]\n    }\n  }\n}\n```\n\n**Codex CLI** (`~\u002F.codex\u002Fconfig.toml`):\n```toml\n[mcp_servers.byaan]\ncommand = \"~\u002FLibrary\u002FApplication Support\u002Fcom.byaan.desktop\u002Fruntime\u002Fcurrent\u002Fbackend\u002Fbackend\"\nargs = [\"-m\", \"server.mcp.stdio_server\"]\n```\n\n### Local \u002F Community Mode (stdio)\n\nWhen running Byaan locally via `make dev`, connect AI assistants using the `uv` command directly. Replace `\u003Cproject_root>` with your actual Byaan project path (e.g., `\u002FUsers\u002Fyou\u002Fbyaan`), or copy the config from the MCP setup modal in the app which fills in the path automatically.\n\n**Claude Code:**\n```bash\nclaude mcp add-json byaan '{\"type\":\"stdio\",\"command\":\"uv\",\"args\":[\"--directory\",\"\u003Cproject_root>\",\"run\",\"python\",\"-m\",\"server.mcp.stdio_server\"]}' --scope user\n```\n\n**Cursor** (`~\u002F.cursor\u002Fmcp.json` or `.cursor\u002Fmcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"byaan\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"\u003Cproject_root>\", \"run\", \"python\", \"-m\", \"server.mcp.stdio_server\"]\n    }\n  }\n}\n```\n\n**Codex CLI** (`~\u002F.codex\u002Fconfig.toml`):\n```toml\n[mcp_servers.byaan]\ncommand = \"uv\"\nargs = [\"--directory\", \"\u003Cproject_root>\", \"run\", \"python\", \"-m\", \"server.mcp.stdio_server\"]\n```\n\n### Byaan Cloud (HTTP)\n\nByaan Cloud is optional and separate from the open-source desktop, community, and self-hosted team deployments. If you use the managed cloud at analytics.byaan.ai, generate an MCP API key (Profile menu > MCP Keys) and use the HTTP endpoint:\n\n| Mode                        | URL                                  |\n| --------------------------- | ------------------------------------ |\n| Byaan Cloud (analytics.byaan.ai) | `https:\u002F\u002Fanalytics.byaan.ai\u002Fapi\u002Fmcp\u002F` |\n\n**Claude Code:**\n```bash\nclaude mcp add-json byaan '{\"type\":\"http\",\"url\":\"https:\u002F\u002Fanalytics.byaan.ai\u002Fapi\u002Fmcp\u002F\",\"headers\":{\"Authorization\":\"Bearer YOUR_BYAAN_API_KEY\"}}' --scope user\n```\n\n**Cursor** (`~\u002F.cursor\u002Fmcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"byaan\": {\n      \"url\": \"https:\u002F\u002Fanalytics.byaan.ai\u002Fapi\u002Fmcp\u002F\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_BYAAN_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n**Codex CLI** (`~\u002F.codex\u002Fconfig.toml`):\n```toml\n[mcp_servers.byaan]\nurl = \"https:\u002F\u002Fanalytics.byaan.ai\u002Fapi\u002Fmcp\u002F\"\nhttp_headers = { \"Authorization\" = \"Bearer YOUR_BYAAN_API_KEY\" }\n```\n\n### Testing the connection\n\nAfter configuring your client, try asking it to \"list all tables in my database\" or \"describe the schema.\" If Byaan is running, your client will receive results through the MCP tools.\n\n## Running Tests\n\n```bash\n# Run backend tests locally\ncd server && PYTHONPATH=..:tests uv run pytest\n\n# Run backend tests inside Docker\ndocker compose exec server uv run pytest\n```\n\n## Team Version Deployment\n\nFor production team deployments with PostgreSQL, Caddy, authentication, invitations, RBAC, Google OAuth, Slack integration, and shared dashboards, see the [Team Version setup above](#team-version) or the full reference at [docs\u002Fself-hosted\u002FREADME.md](docs\u002Fself-hosted\u002FREADME.md).\n\nFor local community development, use `make dev` and open http:\u002F\u002Flocalhost:17434.\n\n## What Leaves Your Machine?\n\nIn local desktop and community deployments:\n\n- Byaan connects directly to the databases and files you configure.\n- Query results and relevant schema\u002Fcontext may be sent to the model provider you configure when an AI workflow needs model assistance.\n- Database traffic is not routed through Byaan-hosted infrastructure.\n- LLM API keys are configured inside the app, not in environment files.\n\nFor hosted or team deployments, review your deployment configuration, model-provider settings, telemetry settings, and organizational policies before connecting production data.\n\n## Security And Read-Only Posture\n\nByaan is designed for read-only analytical workflows. It includes prompt rules and validation layers that block known write operations across SQL, MongoDB, DynamoDB, and DuckDB execution paths. See [docs\u002Fsecurity\u002Fread-only-guardrails.md](docs\u002Fsecurity\u002Fread-only-guardrails.md) for the current implementation details and limits.\n\nFor production databases, use a database user with read-only permissions. Application-level guardrails are a defense-in-depth layer, not a replacement for least-privilege database credentials.\n\n## Architecture\n\n### How the Agent Learns\n\nByaan isn't a stateless wrapper around an LLM. It maintains a persistent context layer that grows with every interaction:\n\n```\n  Ask a question\n        │\n        ▼\n┌─────────────────┐    ┌──────────────────────────────────┐\n│   Agent Core    │◄───│        Persistent Context        │\n│                 │    │                                  │\n│  • Parse query  │    │  Schema + annotations            │\n│  • Select DB    │    │  Saved queries & patterns        │\n│  • Generate SQL │    │  Workspace memory                │\n│  • Build charts │    │  User style preferences          │\n│                 │    │  Custom skills & API tools       │\n└────────┬────────┘    │  GitHub repo knowledge           │\n         │             └──────────────┬───────────────────┘\n         ▼                            │\n  Execute read-only                   │\n  query on your DB          ┌─────────┴─────────┐\n         │                  │   Learning Loop    │\n         ▼                  │                    │\n  Dashboard with            │ Corrections → memory\n  dynamic filters           │ Queries → saved patterns\n         │                  │ Annotations → schema context\n         ▼                  │ Skills → reusable tools\n  Export HTML \u002F PDF         └────────────────────┘\n```\n\nEvery correction you make, every successful query, every annotation — it all feeds back into the context for the next conversation. The agent compounds knowledge instead of resetting.\n\n### Context Layers\n\n| Layer                  | What it stores                                                         | How it learns                                                       |\n| ---------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------- |\n| **Schema annotations** | Table and column descriptions, business meaning, data quality notes    | You annotate or the agent discovers during schema exploration       |\n| **Workspace memory**   | Metric definitions, query patterns, data quirks, standing instructions | Agent saves corrections and successful approaches automatically     |\n| **Saved queries**      | Past SQL with output schemas, reusable across dashboards               | Every successful query becomes context for future conversations     |\n| **Custom skills**      | API integrations, reusable tools, org-shared capabilities              | You create skills with credentials; agent uses them across sessions |\n| **GitHub knowledge**   | Codebase structure, language breakdown, repo-linked analysis           | Connected repos are analyzed and fed into the agent's context       |\n\n### Deployment Modes\n\n```\nMac App            Tauri -> React 19 + FastAPI + SQLite (bundled, runs locally)\nCommunity Docker   Docker Compose -> React 19 + FastAPI + SQLite (local or trusted network)\nTeam Version       Docker -> Caddy + React 19 + FastAPI + PostgreSQL (single-container team deployment)\nMCP                Claude Code, Cursor, Codex, and other MCP clients -> Byaan tools\n```\n\n**Tech stack:** React 19 · TypeScript · FastAPI · SQLAlchemy · DuckDB · Tauri · Python 3.11+\n\n### MCP Server\n\nByaan exposes MCP tools so Claude Code, Cursor, Codex, and other MCP-compatible clients can query databases through the same Byaan context layer. Use the setup examples in [MCP Integration](#mcp-integration-model-context-protocol).\n\n## Environment Configuration\n\nTwo example environment files are provided:\n\n- **[`.env.example`](.env.example)** — for Docker and local development\n- **[`docs\u002Fself-hosted\u002Fenv.example`](docs\u002Fself-hosted\u002Fenv.example)** — for Byaan for Teams deployment (auth, domain, SMTP, OAuth)\n\nCopy the relevant file to `.env` and fill in your values. LLM API keys are configured inside the app, not in environment files.\n\n## Star History\n\nIf Byaan is useful to you, consider giving it a star — you'll get notified of new releases automatically.\n\n\u003C!-- Uncomment once you have traction:\n[![Star History Chart](https:\u002F\u002Fapi.star-history.com\u002Fsvg?repos=byaan-ai\u002Fbyaan&type=Date)](https:\u002F\u002Fstar-history.com\u002F#byaan-ai\u002Fbyaan&Date)\n-->\n\n## Contributing\n\nContributions are welcome! Whether it's bug fixes, new features, documentation, or feedback — every bit helps.\n\n1. Fork the repo and create a branch\n2. Make your changes\n3. Submit a pull request\n\nLook for issues labeled [`good first issue`](https:\u002F\u002Fgithub.com\u002Fbyaan-ai\u002Fbyaan\u002Flabels\u002Fgood%20first%20issue) if you're looking for a place to start.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\nContributor-only utilities, such as demo notebook export scripts, live under `server\u002Fscripts\u002F`.\n\n## Community\n\n- [GitHub Issues](https:\u002F\u002Fgithub.com\u002Fbyaan-ai\u002Fbyaan\u002Fissues) — bug reports and feature requests\n- [GitHub Discussions](https:\u002F\u002Fgithub.com\u002Fbyaan-ai\u002Fbyaan\u002Fdiscussions) — questions and ideas\n- [Website](https:\u002F\u002Fwww.byaan.ai) — product info and downloads\n\n## Support\n\nFor support boundaries, security reporting, and the split between community and teams features, see:\n\n- [SUPPORT.md](SUPPORT.md)\n- [SECURITY.md](SECURITY.md)\n- [docs\u002Flicensing.md](docs\u002Flicensing.md)\n\n## Contributors\n\nCreated by [Hadi Javeed](https:\u002F\u002Fgithub.com\u002Fhadijaveed), [Usama Javed](https:\u002F\u002Fgithub.com\u002Fraousama391), and [Soha Sarwar](https:\u002F\u002Fgithub.com\u002FSohaSarwar1).\n\n## Acknowledgements\n\nByaan is built on the shoulders of excellent open-source projects including [FastAPI](https:\u002F\u002Fgithub.com\u002Ftiangolo\u002Ffastapi), [React](https:\u002F\u002Fgithub.com\u002Ffacebook\u002Freact), [Tauri](https:\u002F\u002Fgithub.com\u002Ftauri-apps\u002Ftauri), [DuckDB](https:\u002F\u002Fgithub.com\u002Fduckdb\u002Fduckdb), [LiteLLM](https:\u002F\u002Fgithub.com\u002FBerriAI\u002Flitellm), and [SQLAlchemy](https:\u002F\u002Fgithub.com\u002Fsqlalchemy\u002Fsqlalchemy).\n\n## License\n\nByaan Community code is [MIT licensed](LICENSE). The `server\u002Fee\u002F` directory contains Byaan for Teams features under the [Elastic License 2.0](server\u002Fee\u002FLICENSE). See [docs\u002Flicensing.md](docs\u002Flicensing.md) for the practical split between community and teams code.\n","Byaan 是一个开源的数据分析助手，能够学习并理解你的业务数据。它支持通过 Slack、Mac 或 MCP 进行自然语言查询，并将结果转化为可交互的图表和仪表板。Byaan 采用 Python 开发，具有自动发现数据库模式、学习业务规则及指标定义的能力，确保每次对话都能基于之前的知识积累进行。其设计为只读模式，强调数据隐私与安全，适合需要在保持数据私密性的同时利用 AI 力量快速获取洞察的企业或团队使用。","2026-06-11 03:58:31","CREATED_QUERY"]