datahub-analytics-agent 0.1.0__tar.gz

datahub_analytics_agent-0.1.0/.env.example

@@ -0,0 +1,58 @@
+# DataHub — referenced via ${VAR} substitution in config.yaml context_platforms
+DATAHUB_GMS_URL=http://localhost:8080
+DATAHUB_GMS_TOKEN=
+
+# LLM — set LLM_PROVIDER to "openai", "anthropic", "google", or "bedrock"
+LLM_PROVIDER=openai
+
+# OpenAI (used when LLM_PROVIDER=openai)
+OPENAI_API_KEY=
+# LLM_MODEL=gpt-4o          # optional override; default: gpt-4o
+# CHART_LLM_MODEL=gpt-4o-mini
+
+# Anthropic (used when LLM_PROVIDER=anthropic)
+ANTHROPIC_API_KEY=
+# LLM_MODEL=claude-opus-4-7  # optional override; default: claude-opus-4-7
+# CHART_LLM_MODEL=claude-haiku-4-5
+
+# Bedrock (used when LLM_PROVIDER=bedrock) — Anthropic models on AWS Bedrock.
+# Auth uses the standard AWS credential chain (env vars, ~/.aws/credentials,
+# IAM role) by default. Set AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY below
+# to override with explicit keys. AWS_SESSION_TOKEN is optional (STS).
+AWS_REGION=us-west-2
+# AWS_ACCESS_KEY_ID=
+# AWS_SECRET_ACCESS_KEY=
+# AWS_SESSION_TOKEN=
+# Model IDs on Bedrock differ from native Anthropic IDs — use the full
+# inference-profile ID (e.g. "us.anthropic.claude-sonnet-4-5-20250929-v1:0").
+# LLM_MODEL=us.anthropic.claude-sonnet-4-5-20250929-v1:0
+# CHART_LLM_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0
+
+# Database (pluggable)
+# PostgreSQL (production):
+# DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/talk_to_data
+# SQLite (local dev):
+DATABASE_URL=sqlite+aiosqlite:///./data/dev.db
+
+# Engine config
+ENGINES_CONFIG=./config.yaml
+SQL_ROW_LIMIT=500
+
+# App
+LOG_LEVEL=INFO
+SSE_KEEPALIVE_INTERVAL=15
+
+# Observability — OTEL tracing (no-op if endpoint is blank)
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317   # Jaeger / Grafana Tempo / any OTLP collector
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
+# OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=YOUR_API_KEY
+# OTEL_SERVICE_NAME=talkster
+
+# Snowflake (if using snowflake engine)
+SNOWFLAKE_ACCOUNT=
+SNOWFLAKE_WAREHOUSE=
+SNOWFLAKE_DATABASE=
+SNOWFLAKE_SCHEMA=
+SNOWFLAKE_USER=
+SNOWFLAKE_PASSWORD=
+# SNOWFLAKE_PRIVATE_KEY=   # base64-encoded PEM: base64 -i key.p8 | tr -d '\n'

datahub_analytics_agent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,120 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # ── Python backend ──────────────────────────────────────────────────────────
+  backend-lint:
+    name: Backend — lint & typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Ruff lint
+        run: uv run ruff check backend/src tests
+
+      - name: Ruff format check
+        run: uv run ruff format --check backend/src tests
+
+      - name: Mypy typecheck
+        run: uv run mypy backend/src/analytics_agent
+
+  backend-test:
+    name: Backend — unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run unit tests
+        run: uv run pytest tests/unit -v
+
+  # ── Playwright e2e ──────────────────────────────────────────────────────────
+  e2e:
+    name: E2E — Playwright
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install Python dependencies
+        run: uv sync
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: latest
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+          cache-dependency-path: frontend/pnpm-lock.yaml
+
+      - name: Install frontend dependencies
+        run: cd frontend && pnpm install --frozen-lockfile
+
+      - name: Build frontend
+        run: cd frontend && pnpm build
+
+      - name: Install Playwright browsers
+        run: cd frontend && npx playwright install chromium --with-deps
+
+      - name: Run e2e tests
+        run: npx --prefix frontend playwright test --config tests/e2e/playwright.config.ts
+
+  # ── Frontend ────────────────────────────────────────────────────────────────
+  frontend-lint:
+    name: Frontend — typecheck & lint
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: latest
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+          cache-dependency-path: frontend/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: TypeScript typecheck + build
+        run: pnpm build
+
+      - name: ESLint
+        run: pnpm lint

datahub_analytics_agent-0.1.0/.github/workflows/docker.yml

@@ -0,0 +1,57 @@
+name: Build & push Docker image
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*.*.*"]
+  pull_request:
+    branches: [main]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha,prefix=sha-,format=short
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: docker/Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

datahub_analytics_agent-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,67 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/datahub-analytics-agent
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

datahub_analytics_agent-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+*.env
+!.env.example
+.env.quickstart
+config.yaml
+!config.yaml.example
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+data/
+*.db
+
+# Frontend
+node_modules/
+frontend/dist/
+frontend/.vite/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+
+# Logs
+*.log
+nohup.out
+
+# Playwright MCP test artifacts
+.playwright-mcp/
+*.png

datahub_analytics_agent-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.6
+    hooks:
+      - id: ruff              # lint + auto-fix
+        args: [--fix]
+        files: ^(backend/src|tests)/
+      - id: ruff-format       # format
+        files: ^(backend/src|tests)/

datahub_analytics_agent-0.1.0/AGENTS.md

@@ -0,0 +1,290 @@
+# AGENTS.md — Analytics Agent Codebase Guide
+
+This file is written for AI coding agents (Claude Code, Cursor, Copilot, etc.) working on the Analytics Agent codebase. Read it before making changes.
+
+---
+
+## Project in one sentence
+
+Analytics Agent is a LangGraph-based chat agent that uses **DataHub** tools for metadata context and pluggable **SQL engines** (Snowflake first) to answer natural-language data questions, with Vega-Lite charts rendered inline in a React + Vite UI served by the same FastAPI process.
+
+---
+
+## Running the stack
+
+A `justfile` at the repo root covers all common tasks. Install `just` once (`brew install just`), then:
+
+```bash
+just install          # uv sync + pnpm install
+just start            # build frontend if stale, start backend at :8100
+just port=8102 start  # same on a custom port
+just stop             # kill the backend
+just nuke             # wipe the DB (start from scratch / re-trigger wizard)
+just start-remote     # start + print DataHub connection status
+just logs             # tail /tmp/analytics_agent.log
+just test             # unit tests
+just build            # force frontend rebuild
+```
+
+`just start` automatically detects whether `frontend/src` is newer than `frontend/dist` and rebuilds only when needed.
+
+### Without just (manual)
+
+```bash
+uv sync
+cd frontend && pnpm install && pnpm build && cd ..
+uv run uvicorn analytics_agent.main:app --reload --port 8101
+# → http://localhost:8101
+# The setup wizard handles LLM key + connections on first run.
+# Optional: cp .env.example .env to pre-configure credentials.
+```
+
+### Two-process mode (frontend hot reload)
+
+```bash
+# Terminal 1 — backend (dev)
+uv run uvicorn analytics_agent.main:app --reload --port 8101
+
+# Terminal 2 — Vite dev server with HMR
+cd frontend && pnpm dev
+# → http://localhost:5173 (proxies /api/* to :8101)
+```
+
+**DataHub credentials**: run `datahub init --sso --host https://your-instance.acryl.io/gms` once. The app reads `~/.datahubenv` automatically; or set `DATAHUB_GMS_URL` + `DATAHUB_GMS_TOKEN` in `config.yaml` / `.env`.
+
+**Database**: SQLite at `./data/dev.db` by default. Alembic runs automatically on startup. For Postgres set `DATABASE_URL=postgresql+asyncpg://...`.
+
+---
+
+## Key file map
+
+| Path | What it does |
+|------|-------------|
+| `backend/src/analytics_agent/main.py` | FastAPI app factory + lifespan (runs Alembic, seeds integrations, mounts SPA) |
+| `backend/src/analytics_agent/agent/graph.py` | LangGraph `StateGraph`: ReAct agent → conditional chart node |
+| `backend/src/analytics_agent/agent/streaming.py` | `astream_events` → SSE event dicts; handles `on_tool_error` |
+| `backend/src/analytics_agent/agent/history.py` | Reconstructs LangChain message history from DB rows; pads orphaned tool calls |
+| `backend/src/analytics_agent/agent/chart_tool.py` | `create_chart` LangChain tool; stores spec in `_pending_charts` side-channel |
+| `backend/src/analytics_agent/agent/chart_generator.py` | `chart_node`: runs after SQL results; calls chart LLM → updates `pending_chart` state |
+| `backend/src/analytics_agent/api/chat.py` | `POST /api/conversations/{id}/messages` → `StreamingResponse` (SSE) |
+| `backend/src/analytics_agent/api/settings.py` | Connection CRUD + test + tool toggles + prompt + display settings |
+| `backend/src/analytics_agent/api/oauth.py` | SSO browser flow, PAT storage, OAuth popup flow, credential encryption |
+| `backend/src/analytics_agent/context/datahub.py` | Builds DataHub LangChain tools via `datahub_agent_context.build_langchain_tools()` |
+| `backend/src/analytics_agent/engines/resolver.py` | **Single credential resolution point** — loads Integration + credential from DB |
+| `backend/src/analytics_agent/engines/snowflake/engine.py` | Snowflake `QueryEngine`: execute_sql, list_tables, get_schema, preview_table; SSO/key-pair/PAT auth |
+| `backend/src/analytics_agent/engines/factory.py` | Engine registry; `register_engine` / `unregister_engine` for dynamic connections |
+| `backend/src/analytics_agent/db/models.py` | SQLAlchemy models: Conversation, Message, Integration, IntegrationCredential, Setting |
+| `backend/src/analytics_agent/db/repository.py` | Repos: ConversationRepo, MessageRepo, SettingsRepo, IntegrationRepo, CredentialRepo |
+| `backend/src/analytics_agent/prompts/system_prompt.md` | Agent system prompt (edit here — loaded at runtime) |
+| `frontend/src/components/Chat/ChatView.tsx` | Chat shell; handles welcome-screen → new conversation flow |
+| `frontend/src/components/Chat/WelcomeView.tsx` | Landing screen with LLM greeting, suggestion chips, engine selector |
+| `frontend/src/components/Settings/SnowflakeAuthSection.tsx` | Segmented auth selector: Password / Private Key / SSO / PAT / OAuth |
+| `frontend/src/store/conversations.ts` | Zustand: conversations, messages, engines, streaming state |
+| `frontend/src/store/display.ts` | Zustand: app name, logo, cached LLM greeting |
+
+---
+
+## Integrations + credential architecture
+
+Connections are stored in two DB tables:
+
+- **`integrations`** — connection topology (account, warehouse, database, user). `source="yaml"` for `config.yaml` connections, `source="ui"` for UI-created ones.
+- **`integration_credentials`** — encrypted auth per connection: `auth_type` ∈ `{sso_externalbrowser, private_key, pat, oauth, password}`.
+
+**Credential resolution** happens in `engines/resolver.py::resolve_engine(engine_name, session)`:
+1. Looks up `integration_credentials` for the engine
+2. Decrypts the credential and returns a configured engine clone
+3. Falls back to env vars for `source="yaml"` connections (backwards compat)
+
+**Never thread individual credential fields** (`oauth_token`, `sso_user`, etc.) through `graph.py` or agent code. Pass the engine object returned by `resolve_engine`.
+
+```python
+# chat.py — the only place credentials are resolved
+engine = await resolve_engine(engine_name, session)
+graph = build_graph(engine=engine, engine_name=engine_name, ...)
+```
+
+### Connection write wire format — `{config, secrets}`
+
+`PUT /api/settings/connections/{name}` and `POST /api/settings/connections`
+accept a single wire shape:
+
+```jsonc
+{
+  "config":  { "account": "...", "warehouse": "...", "database": "...", "user": "..." },
+  "secrets": { "password": "..." }
+}
+```
+
+- `config` values are merged directly into `integrations.config` (DB) for engines,
+  or into the context-platform's config JSON for DataHub.
+- `secrets` keys are validated against each engine's own
+  `QueryEngine.secret_env_vars` allow-list (e.g.
+  `SnowflakeQueryEngine.secret_env_vars = {"password": "SNOWFLAKE_PASSWORD", ...}`)
+  and translated to env-var names before being written to `.env` and
+  `os.environ`. Unknown secret keys are rejected with **HTTP 400**. The API
+  layer stays ignorant of any particular engine's credential fields.
+- `_upsert_env_vars` always double-quotes every value so PEM blocks and passwords
+  with special characters (`#`, `$`, `\`, spaces) round-trip correctly.
+
+**How the frontend splits values** — each `ConnectionField` returned by
+`GET /connections` has an optional `secret_key` attribute. If present, the field's
+value is routed to `body.secrets[secret_key]`; otherwise it goes to
+`body.config[key]`. See `splitConnectionValues` in `frontend/src/api/settings.ts`.
+
+**Staged follow-up steps (tracked):**
+
+- **1 - route `body.secrets` to `integration_credentials`** (encrypted, per-connection).
+  Adds a `password` auth_type and a `password` branch in `resolver.py`, plus
+  `with_password` on `SnowflakeQueryEngine`. After 1 lands, `.env` stops accumulating
+  per-connection secrets and two Snowflake connections with different passwords can
+  coexist without collision.
+- **2 - `GET /api/settings/connections/schemas/{type}`** + frontend renders forms
+  generically from the schema. Promotes `QueryEngine.secret_env_vars` into a full
+  typed schema (fields, labels, placeholders, required flags) shared with the
+  frontend; handler becomes validate -> dispatch.
+
+---
+
+## SSE event flow
+
+```
+POST /api/conversations/{id}/messages
+  └─ chat.py: _event_stream()
+       ├─ resolve_engine(engine_name, session) → configured engine
+       ├─ load conversation history → build_history() → LangChain messages
+       ├─ build_graph(engine=engine, ...) → LangGraph compiled graph
+       └─ stream_graph_events(graph, ...)
+            ├─ on_chat_model_stream  → TEXT event
+            ├─ on_tool_start        → TOOL_CALL event (skipped for create_chart)
+            ├─ on_tool_end          → SQL / TOOL_RESULT / CHART
+            ├─ on_tool_error        → TOOL_RESULT (is_error=True)
+            ├─ on_chain_end         → captures final_state for chart_node charts
+            └─ end of stream        → CHART (fallback) + COMPLETE
+```
+
+Frontend consumes SSE via `stream.ts` (fetch + ReadableStream, **not** EventSource — needs POST).
+
+---
+
+## LangGraph agent design
+
+```
+START → agent (create_react_agent) → conditional → chart → END
+                                          ↓ (no SQL rows)
+                                         END
+```
+
+- Use `create_agent` from `langchain.agents` (**not** `create_react_agent` from `langgraph.prebuilt`)
+- System prompt loaded from `prompts/system_prompt.md` at runtime (editable without restart)
+- Tools: DataHub tools (search_documents, search, get_entities, …) + engine tools + `create_chart`
+- `chart_node` fires when `get_last_sql_result(state)` finds an `execute_sql` ToolMessage with rows
+
+---
+
+## Chart generation — two paths
+
+| Path | Trigger | How spec reaches frontend |
+|------|---------|--------------------------|
+| `create_chart` tool | Agent calls tool | `_pending_charts[chart_id]` → `on_tool_end` → CHART event |
+| `chart_node` | SQL returned rows | `state.pending_chart` → `on_chain_end` → CHART event |
+| Text fallback | Model writes spec as ```json``` | `_extract_chart_from_text` regex → CHART event |
+
+`chart_emitted` flag prevents duplicates across all three paths.
+
+---
+
+## Dynamic connections (UI-created)
+
+Users can add connections via **Settings → Add Connection** without editing `config.yaml`:
+
+1. `POST /api/settings/connections` → creates `Integration` in DB + calls `register_engine()`
+2. `DELETE /api/settings/connections/{name}` → removes from DB + calls `unregister_engine()`
+3. On server restart, `_seed_integrations()` in `main.py` reloads all integrations from DB
+
+The Snowflake engine supports `with_sso_user()`, `with_private_key()`, `with_pat_token()`, `with_oauth_token()` clone methods — these are called by `resolver.py`, never from agent code.
+
+---
+
+## Multi-turn conversation history
+
+`build_history()` in `agent/history.py` converts DB rows to LangChain messages:
+
+- **User TEXT** → `HumanMessage`
+- **TOOL_CALL + TOOL_RESULT pairs** → `AIMessage(tool_calls=[...])` + `ToolMessage`
+- Tool calls always use `tc["id"]` for `tool_call_id` (not the result's stored ID) — avoids Anthropic "unexpected tool_use_id" rejections from orphaned DB records
+- Turns with no useful content → **skipped** (avoids consecutive HumanMessages)
+
+---
+
+## Serving the frontend
+
+`main.py` mounts the built React SPA after registering all API routes:
+
+```python
+_dist = Path(os.getenv("FRONTEND_DIST", "")) or Path(__file__).parents[3] / "frontend" / "dist"
+
+if _dist.exists():
+    app.mount("/assets", StaticFiles(directory=_dist / "assets"), name="spa-assets")
+
+    @app.get("/{full_path:path}", include_in_schema=False)
+    async def _spa_fallback(full_path: str) -> FileResponse:
+        return FileResponse(_dist / "index.html", media_type="text/html")
+```
+
+- If `dist/` is absent (dev mode), the server runs API-only and Vite handles the frontend
+- `FRONTEND_DIST` env var overrides the default path (useful in Docker)
+- The catch-all **must be the last route** — FastAPI matches in registration order
+
+---
+
+## Adding a new query engine
+
+1. Create `engines/<name>/engine.py` implementing `QueryEngine`:
+   - Expose four tools: `execute_sql`, `list_tables`, `get_schema`, `preview_table`
+   - All tools must catch exceptions and return `{"error": str(e)}` — never raise
+2. Register in `engines/factory.py` → `_engine_cls()` dict
+3. Add connection config to `config.yaml` OR let users add via the Settings UI
+4. Add tool list to `api/settings.py` → `_KNOWN_TOOLS`
+
+---
+
+## Changing the system prompt
+
+Edit `prompts/system_prompt.md`. The prompt is loaded at runtime — no restart needed for changes made via the Settings UI (stored in DB). The `{engine_name}` placeholder is substituted at graph build time.
+
+---
+
+## Docker
+
+```bash
+# Build (multistage: Node builds frontend, Python 3.12 serves everything)
+docker build -f docker/Dockerfile -t analytics-agent .
+
+# Run
+docker run -p 8100:8100 --env-file .env analytics-agent
+```
+
+GitHub Actions (`.github/workflows/docker.yml`) builds and pushes to GHCR on every push to `main` and version tags.
+
+---
+
+## Common pitfalls
+
+**Do not** use `create_react_agent` from `langgraph.prebuilt` — deprecated in LangGraph v1. Use `create_agent` from `langchain.agents` with `system_prompt=` (string).
+
+**Do not** pass `temperature=0` to `ChatAnthropic` with `claude-opus-4-7` — sampling parameters are removed on this model.
+
+**Do not** use `EventSource` in the frontend — the chat endpoint is a POST. Use `fetch()` + `ReadableStream` (`frontend/src/api/stream.ts`).
+
+**Do not** thread credential fields through `graph.py` — use `resolver.py` to get a pre-configured engine and pass the engine object.
+
+**Do not** store chart Vega-Lite specs as the tool return value — use the `_pending_charts` side-channel.
+
+**Do not** start the backend without loading `.env` — `main.py` calls `load_dotenv()` automatically so this is handled, but env vars must be in `.env`.
+
+**The DB engine is lazy**: `db/base.py` creates the SQLAlchemy async engine on first use. This prevents the sync Alembic migration from deadlocking with the async engine at startup.
+
+**`chat.py` uses its own session**: `_event_stream` opens a fresh `AsyncSession` independent of the `Depends(get_session)` session — FastAPI closes `Depends` sessions before `StreamingResponse` iterates the generator.
+
+**Snowflake Decimal/date types**: `_run_query` in `snowflake/engine.py` coerces `Decimal` → `int`/`float` and `datetime` → ISO string before serialisation. Do not remove this — `orjson` rejects `Decimal`.