datachat-agent 0.1.0__tar.gz

datachat_agent-0.1.0/.env.example

@@ -0,0 +1,73 @@
+# Copy this file to .env and fill in YOUR OWN values.
+# .env is git-ignored: your keys never leave your machine.
+
+# --- DataChat's own Postgres (needs the pgvector extension) ---
+DATABASE_URL=postgresql://datachat:datachat@localhost:5432/datachat
+REDIS_URL=redis://localhost:6379/0
+
+# Encrypts stored database passwords and LLM keys. Generate with: datachat-agent gen-secret
+SECRET_KEY=
+
+# --- LLM: bring your own key ---
+# Any OpenAI-compatible endpoint works. Pick ONE block and uncomment it.
+LLM_PROVIDER=openai_compatible
+
+# Groq (free tier): https://console.groq.com/keys
+# LLM_BASE_URL=https://api.groq.com/openai/v1
+# LLM_MODEL=llama-3.3-70b-versatile
+
+# Google Gemini (free tier): https://aistudio.google.com/apikey
+# LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
+# LLM_MODEL=gemini-3.6-flash   (names change often; check the models list in AI Studio)
+
+# OpenRouter (models ending in :free): https://openrouter.ai/keys
+# LLM_BASE_URL=https://openrouter.ai/api/v1
+# LLM_MODEL=qwen/qwen-2.5-coder-32b-instruct:free
+
+# Ollama (local, no key): https://ollama.com  then: ollama pull qwen2.5-coder:7b
+# LLM_BASE_URL=http://localhost:11434/v1
+# LLM_MODEL=qwen2.5-coder:7b
+
+# Claude: set LLM_PROVIDER=anthropic, leave LLM_BASE_URL empty
+# LLM_MODEL=claude-sonnet-5-5
+
+LLM_BASE_URL=
+LLM_MODEL=
+LLM_API_KEY=
+# Free tiers get overloaded: list backup models (same provider and key) to try in order.
+# LLM_FALLBACK_MODELS=gemini-3.5-flash,gemini-3.5-flash-lite
+# Thinking models (Gemini 3.x) are faster and use fewer tokens with less reasoning:
+# LLM_REASONING_EFFORT=low
+# LLM_TIMEOUT_SECONDS=30
+# LLM_MAX_RETRIES=1
+
+# --- Embeddings (local and free by default) ---
+# local: runs on your CPU, downloads ~70 MB once. openai_compatible: uses EMBED_BASE_URL/EMBED_API_KEY
+# (falls back to the LLM settings).
+EMBED_PROVIDER=local
+EMBED_MODEL=BAAI/bge-small-en-v1.5
+# Must match the model's vector size. Changing it later means re-creating the vector tables.
+EMBED_DIM=384
+# EMBED_BASE_URL=
+# EMBED_API_KEY=
+
+# --- Documents and background work ---
+# MAX_PDF_MB=20
+# sync: process uploads inside the request · inline: in the background of the API process (default)
+# arq: in a separate `datachat-agent worker` process via Redis (what docker-compose uses)
+# JOBS_BACKEND=inline
+
+# --- Abuse and cost limits ---
+# memory: per server process · redis: shared by all servers (use with several API servers)
+# RATE_LIMIT_BACKEND=memory
+# DEFAULT_RATE_LIMIT_PER_MINUTE=60
+# DEFAULT_MONTHLY_TOKEN_LIMIT=          (empty = no cap; per-tenant limits override it)
+
+# Replace emails, phone numbers, card, Aadhaar and PAN numbers with placeholders before data
+# is sent to the model; real values are put back into the answer.
+# MASK_PII=false
+
+# --- Limits on every query against a customer database ---
+# SQL_TIMEOUT_SECONDS=10
+# SQL_MAX_ROWS=500
+# SQL_MAX_RESPONSE_BYTES=5000000

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

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    services:
+      postgres:
+        image: pgvector/pgvector:pg17
+        env:
+          POSTGRES_USER: datachat
+          POSTGRES_PASSWORD: datachat
+          POSTGRES_DB: datachat
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd "pg_isready -U datachat"
+          --health-interval 5s --health-timeout 5s --health-retries 10
+      redis:
+        image: redis:7-alpine
+        ports: ["6379:6379"]
+      mysql:
+        image: mysql:8.4
+        env:
+          MYSQL_ROOT_PASSWORD: rootpass
+        ports: ["3307:3306"]
+        options: >-
+          --health-cmd "mysqladmin ping -h 127.0.0.1 -uroot -prootpass --silent"
+          --health-interval 5s --health-timeout 5s --health-retries 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: |
+          ruff check .
+          ruff format --check .
+      - name: Tests (unit + integration against Postgres and MySQL)
+        run: pytest -q -rs
+
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build the self-host image
+        run: docker build -t datachat-agent:ci .
+      - name: CLI starts inside the image
+        run: docker run --rm datachat-agent:ci datachat-agent --help
+
+  js:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: SDK (sdk-js)
+        working-directory: sdk-js
+        run: |
+          npm ci
+          npm test
+      - name: Widget (widget)
+        working-directory: widget
+        run: |
+          npm ci
+          npx tsc -p tsconfig.json
+          npm test
+          npm run build
+      - name: The widget served by the API is the freshly built one
+        run: cmp widget/dist/widget.js packages/datachat_agent/server/static/widget.js
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Build wheel and sdist
+        run: uv build
+      - name: Check package metadata
+        run: uvx twine check dist/*
+      - name: Wheel installs and starts
+        run: |
+          python -m venv /tmp/v && /tmp/v/bin/pip install dist/*.whl
+          /tmp/v/bin/datachat-agent --help
+          /tmp/v/bin/python -c "import datachat_agent, importlib.resources as r; assert r.files('datachat_agent').joinpath('server/static/widget.js').is_file()"

datachat_agent-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,104 @@
+name: Release
+
+# Push a tag like v0.1.0 to publish. The tag must match the version in pyproject.toml and
+# sdk-js/package.json. See docs/RELEASING.md for the one-time PyPI and npm setup.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.v.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: v
+        name: Tag, Python and npm versions agree
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          py=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          js=$(node -p "require('./sdk-js/package.json').version")
+          echo "tag=$tag python=$py npm=$js"
+          [ "$tag" = "$py" ] && [ "$tag" = "$js" ] || { echo "Versions differ"; exit 1; }
+          echo "version=$tag" >> "$GITHUB_OUTPUT"
+
+  pypi:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing: no PyPI password stored in GitHub
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - run: uvx twine check dist/*
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  npm:
+    needs: verify
+    # Off until npm is set up: Settings -> Secrets and variables -> Actions -> Variables ->
+    # PUBLISH_NPM = true (see docs/RELEASING.md).
+    if: vars.PUBLISH_NPM == 'true'
+    runs-on: ubuntu-latest
+    environment: npm
+    permissions:
+      id-token: write  # trusted publishing and provenance
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+      - run: npm install -g npm@latest  # trusted publishing needs npm 11.5+
+      - working-directory: sdk-js
+        run: |
+          npm ci
+          npm test
+          npm publish --provenance --access public
+
+  docker:
+    needs: verify
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/datachat-agent
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable=${{ !contains(github.ref_name, '-') }}
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+  github-release:
+    needs: [pypi, npm, docker]
+    # A skipped npm job (not set up yet) must not block the release; a failed one does.
+    if: >-
+      !cancelled() && needs.pypi.result == 'success' && needs.docker.result == 'success'
+      && needs.npm.result != 'failure'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          prerelease: ${{ contains(github.ref_name, '-') || startsWith(github.ref_name, 'v0.') }}
+          files: packages/datachat_agent/server/static/widget.js

datachat_agent-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Secrets: never commit real keys, even free ones
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Node (sdk-js, widget, console)
+node_modules/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Local data
+*.sqlite3
+uploads/

datachat_agent-0.1.0/Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
+
+COPY pyproject.toml README.md ./
+COPY packages ./packages
+RUN pip install --no-cache-dir .
+
+EXPOSE 8000
+CMD ["sh", "-c", "datachat-agent init-db && datachat-agent serve --host 0.0.0.0 --port 8000"]

datachat_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DataChat contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

datachat_agent-0.1.0/PKG-INFO

@@ -0,0 +1,353 @@
+Metadata-Version: 2.5
+Name: datachat-agent
+Version: 0.1.0
+Summary: Open-source AI agent that answers questions from your SQL database and PDFs
+Project-URL: Homepage, https://github.com/Ashish-devl/Data-chat-agent
+Project-URL: Issues, https://github.com/Ashish-devl/Data-chat-agent/issues
+Author: DataChat Agent contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,fastapi,llm,mcp,pdf,rag,text-to-sql
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.13
+Requires-Dist: arq>=0.26
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: cryptography>=43
+Requires-Dist: fastapi>=0.115
+Requires-Dist: fastembed>=0.4
+Requires-Dist: langchain-anthropic>=0.2
+Requires-Dist: langchain-openai>=0.2
+Requires-Dist: langgraph>=1.0
+Requires-Dist: mcp>=2.3
+Requires-Dist: pdfplumber>=0.11
+Requires-Dist: pgvector>=0.3
+Requires-Dist: psycopg[binary]>=3.2
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pymysql>=1.1
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: sqlalchemy[asyncio]>=2.0.30
+Requires-Dist: sqlglot>=25
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: reportlab>=4; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DataChat Agent
+
+An open-source AI agent that answers plain-English questions from your SQL database and your PDFs, and shows the SQL or page each answer came from.
+
+> Status: preview release 0.1.0 (week 6 of 8 toward v1.0). Not ready for production use yet.
+
+## Bring your own model key
+
+DataChat Agent never ships with an LLM key. You use your own, from any OpenAI-compatible provider or Claude:
+
+| Provider | Cost | Get a key |
+| --- | --- | --- |
+| Groq | Free tier | https://console.groq.com/keys |
+| Google Gemini | Free tier | https://aistudio.google.com/apikey |
+| OpenRouter (`:free` models) | Free | https://openrouter.ai/keys |
+| Ollama | Free, runs locally | https://ollama.com |
+| OpenAI, Claude | Paid | Their consoles |
+
+## Quickstart
+
+```bash
+git clone https://github.com/Ashish-devl/Data-chat-agent.git
+cd Data-chat-agent
+cp .env.example .env          # then fill in your LLM settings
+pip install -e ".[dev]"
+datachat-agent gen-secret           # paste the output into SECRET_KEY in .env
+datachat-agent check-llm            # confirms your model key works
+```
+
+Start Postgres (with pgvector) and Redis, then the API:
+
+```bash
+docker compose up -d db redis
+datachat-agent init-db
+datachat-agent create-tenant "My company"   # prints an admin API key, once
+datachat-agent serve
+```
+
+Or run everything in Docker: `docker compose up --build`.
+
+API docs: http://localhost:8000/docs
+
+```bash
+curl http://localhost:8000/v1/keys -H "Authorization: Bearer dc_live_..."
+```
+
+## Connect a database
+
+DataChat Agent only ever reads. Create a database user that can `SELECT` and nothing else; the
+connection test refuses users that can write.
+
+```bash
+KEY="Authorization: Bearer dc_live_..."
+curl -X POST localhost:8000/v1/connections -H "$KEY" -H "Content-Type: application/json"   -d '{"name": "erp", "dsn": "postgresql://readonly:pass@host:5432/erp"}'
+curl -X POST localhost:8000/v1/connections/<id>/test -H "$KEY"   # must say "ok"
+curl -X POST localhost:8000/v1/connections/<id>/scan -H "$KEY"   # reads tables and columns
+curl localhost:8000/v1/connections/<id>/schema -H "$KEY"
+```
+
+Describe or hide columns (hidden columns can never be queried):
+
+```bash
+curl -X PATCH localhost:8000/v1/schema-items/<item id> -H "$KEY"   -H "Content-Type: application/json" -d '{"hidden": true}'
+```
+
+Teach it your business language and give it worked examples:
+
+```bash
+curl -X POST localhost:8000/v1/connections/<id>/terms -H "$KEY" -H "Content-Type: application/json"   -d '{"term": "open PO", "definition": "a purchase order whose status is Open or Partially Received"}'
+curl -X POST localhost:8000/v1/connections/<id>/examples -H "$KEY" -H "Content-Type: application/json"   -d '{"question": "Suppliers in Ludhiana", "sql": "SELECT name FROM suppliers WHERE city = '"'"'Ludhiana'"'"'"}'
+```
+
+## Ask questions
+
+```bash
+curl -X POST localhost:8000/v1/ask -H "$KEY" -H "Content-Type: application/json"   -d '{"question": "Which production orders are delayed?", "session_id": "chat-1"}'
+```
+
+```json
+{
+  "answer": "There are 13 delayed production orders in total ...",
+  "route": "database",
+  "sql": "SELECT ... LIMIT 500",
+  "columns": ["style_no", "qty_behind"],
+  "rows": [{"style_no": "26C1740", "qty_behind": 1390}],
+  "chart": {"type": "bar", "x": "style_no", "y": "qty_behind"},
+  "session_id": "chat-1",
+  "latency_ms": 7126
+}
+```
+
+Send the same `session_id` for follow-ups ("which buyers are those for?"); read a conversation
+with `GET /v1/sessions/chat-1`. Pass `connection_id` when you have more than one database, and
+`user_context` (e.g. `{"user_company": 7}`) when the connection uses row filters. Keys need the
+`ask` scope.
+
+### Streaming
+
+`POST /v1/ask/stream` takes the same body and answers as Server-Sent Events, so a chat window can
+show the answer while it is being written:
+
+```text
+event: meta    data: {"session_id": "chat-1", "route": "database"}
+event: data    data: {"sql": "SELECT ...", "rows": [...], "row_count": 13}
+event: token   data: {"text": "There are 13 "}
+event: token   data: {"text": "delayed orders ..."}
+event: done    data: { ...the same body /v1/ask returns... }
+```
+
+### Feedback
+
+```bash
+curl -X POST localhost:8000/v1/feedback -H "$KEY" -H "Content-Type: application/json"   -d '{"query_id": "<from the answer>", "rating": "wrong", "comment": "Should include line 7"}'
+```
+
+### Limits and privacy
+
+- Each API key may make `DEFAULT_RATE_LIMIT_PER_MINUTE` requests a minute (60 by default; 429 with
+  `Retry-After` beyond that). Use `RATE_LIMIT_BACKEND=redis` when several servers share the load.
+- `DEFAULT_MONTHLY_TOKEN_LIMIT` caps model tokens per account per month. Operators set per-account
+  limits with `datachat-agent set-limits <tenant id> --per-minute 30 --monthly-tokens 500000` and
+  see them with `datachat-agent list-tenants`. `GET /v1/usage` shows an account its own use.
+- `MASK_PII=true` replaces emails, phone numbers, card, Aadhaar and PAN numbers with placeholders
+  before anything reaches the model; the real values are put back into the answer.
+
+## Upload PDFs
+
+```bash
+curl -X POST localhost:8000/v1/documents -H "$KEY" -F "file=@invoice.pdf;type=application/pdf"
+curl localhost:8000/v1/documents -H "$KEY"                    # status: queued → ready
+curl localhost:8000/v1/documents/<id>/items -H "$KEY"         # line items from its tables
+curl -o original.pdf localhost:8000/v1/documents/<id>/file -H "$KEY"
+```
+
+PDFs with a text layer up to 20 MB; the same file uploaded twice is stored once. Text is split
+into passages per page and searched by meaning and by keyword; tables become line items (item,
+qty, unit, rate, amount). Answers from documents cite the file and page:
+
+```json
+{
+  "answer": "The grand total of invoice KE/26-27/8231 is INR 773,550.00 [1].",
+  "route": "documents",
+  "citations": [{"ref": 1, "filename": "invoice_KE-26-27-8231.pdf", "page": 1,
+                 "url": "/v1/documents/<id>/file#page=1"}]
+}
+```
+
+One question can use both sources ("Which orders are delayed, and what carton weight does the
+manual allow?"). Uploads need a key with the `docs` scope. Scanned PDFs without a text layer are
+not supported yet. Generate made-up sample PDFs with `python eval/datasets/make_pdfs.py out/`.
+
+Processing runs in the background of the API by default. With Docker, a separate `worker`
+service does it (`JOBS_BACKEND=arq`), and it also re-scans every database schema nightly.
+
+Try the SQL step alone from the command line:
+
+```bash
+datachat-agent ask-sql <connection id> "Which production orders are delayed?"
+```
+
+### Safety: three separate layers
+
+1. The database user must be read-only (checked on test and before every scan).
+2. Every query is parsed: one `SELECT` only, allowed tables only, no hidden columns, no admin
+   functions, `LIMIT 500` at most.
+3. Queries run in a read-only transaction with a 10-second timeout.
+
+Per-user row filters (`"row_filters": {"orders": "company_id = :user_company"}`) are wrapped around
+every use of the table; a question without the user's context is refused.
+
+## Five ways to use it
+
+### 1. Python library (no server)
+
+```bash
+pip install datachat-agent
+```
+
+```python
+from datachat_agent import DataChat
+
+with DataChat("postgresql://readonly:secret@host/erp") as dc:
+    dc.scan_schema()  # refuses a user that can write
+    dc.hide("employees", "salary")  # never shown to the model, never queryable
+    dc.add_term("open PO", "status is Open or Partially Received")
+    dc.add_pdf("invoice_8231.pdf")
+    print(dc.ask("What is the total of invoice KE/26-27/8231?").answer)
+```
+
+It stores what it learns in its own Postgres with pgvector (`DATABASE_URL`, or
+`DataChat(..., storage_url=...)`). `ask` returns `answer`, `sql`, `rows`, `citations` and `chart`;
+`aask`, `ascan_schema` and `aadd_pdf` are the async versions.
+
+### 2. Inside your FastAPI app
+
+```python
+from datachat_agent import mount
+
+mount(app, prefix="/ai")  # serves /ai/v1/ask, /ai/v1/documents, ... and /ai/widget.js
+```
+
+Run `datachat-agent init-db` once to create its tables.
+
+### 3. Self-hosted server (Docker)
+
+`docker compose up --build` starts the API, a background worker, Postgres with pgvector and
+Redis. Configure it with `.env`.
+
+### 4. HTTP API, JavaScript SDK and chat widget
+
+The API is described above and at `/docs` on a running server. From JavaScript:
+
+```js
+import { DataChatClient } from "datachat-agent";   // npm install datachat-agent
+const dc = new DataChatClient({ baseUrl: "https://api.example.com", apiKey: "dc_live_..." });
+const a = await dc.ask("Which production orders are delayed?");
+```
+
+For a web page, create a **publishable** key that works only on your websites and can only ask:
+
+```bash
+curl -X POST localhost:8000/v1/keys -H "$KEY" -H "Content-Type: application/json"   -d '{"name": "website", "type": "publishable", "allowed_domains": ["erp.example.com"]}'
+```
+
+then add one line to the page:
+
+```html
+<script src="https://your-datachat-server/widget.js" data-key="dc_pub_..."
+        data-title="Ask about our data"></script>
+```
+
+Optional: `data-connection`, `data-position="left"`, `data-color="#0f766e"`,
+`data-placeholder`. The widget streams answers, shows a small table and the sources, and has
+Helpful / Wrong buttons. Publishable keys cannot send `user_context`, so a connection with row
+filters refuses widget questions rather than guessing whose rows to show.
+
+### 5. MCP server (Claude Desktop, IDEs)
+
+```bash
+datachat-agent mcp --api-key dc_live_...
+```
+
+Tools: `list_tables`, `describe_table`, `run_sql`, `search_documents`, `get_document_items` and
+`ask`, all read-only. In Claude Desktop's `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "datachat": {
+      "command": "datachat-agent",
+      "args": ["mcp"],
+      "env": {
+        "DATACHAT_API_KEY": "dc_live_...",
+        "DATABASE_URL": "postgresql://datachat:datachat@localhost:5432/datachat",
+        "SECRET_KEY": "...",
+        "LLM_BASE_URL": "...", "LLM_MODEL": "...", "LLM_API_KEY": "..."
+      }
+    }
+  }
+}
+```
+
+### Command line
+
+| Command | Does |
+| --- | --- |
+| `datachat-agent serve` / `worker` | API server / background worker |
+| `datachat-agent init-db` | Create or upgrade tables |
+| `datachat-agent create-tenant NAME` | New account and its first admin key |
+| `datachat-agent scan CONNECTION_ID` | Re-read a database schema |
+| `datachat-agent ingest TENANT_ID FILE...` | Upload and process PDFs |
+| `datachat-agent ask-sql CONNECTION_ID "question"` | Try the SQL step |
+| `datachat-agent mcp` | MCP server over stdio |
+| `datachat-agent list-tenants` / `set-limits` | Usage and limits |
+| `datachat-agent check-llm` / `gen-secret` | Test the model / make a SECRET_KEY |
+
+## Development
+
+```bash
+docker compose up -d db redis
+docker compose --profile dev up -d mysql     # optional: MySQL tests
+pytest                                       # unit + integration tests
+ruff check . && ruff format --check .
+```
+
+Integration tests create a throwaway `datachat_test` database and load `erp_demo`, a made-up
+garment-factory ERP (`eval/datasets/erp_demo.py`), into Postgres and MySQL. They are skipped when
+the databases are not running. Load the sample yourself to try the API:
+
+```bash
+python eval/datasets/erp_demo.py postgresql://datachat:datachat@localhost:5432/postgres
+# then connect with: postgresql://erp_readonly:erp_readonly@localhost:5432/erp_demo
+```
+
+After changing `server/models.py`, generate a migration with
+`datachat-agent make-migration "what changed"`.
+
+JavaScript parts: `cd sdk-js && npm ci && npm test`; `cd widget && npm ci && npm test && npm run build`,
+then copy `widget/dist/widget.js` to `packages/datachat_agent/server/static/` (CI checks they
+match). Releases: see [docs/RELEASING.md](docs/RELEASING.md).
+
+## Licence
+
+MIT