datacharter 0.3.3__tar.gz → 0.4.0__tar.gz

{datacharter-0.3.3 → datacharter-0.4.0}/.github/workflows/test.yml

@@ -71,6 +71,8 @@ jobs:
         run: cd ui && npm ci
       - name: Typecheck + build
         run: cd ui && npm run build
+      - name: Unit test UI
+        run: cd ui && npm test
 
   package:
     runs-on: ubuntu-latest

{datacharter-0.3.3 → datacharter-0.4.0}/CHANGELOG.md

@@ -5,6 +5,39 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-25
+
+### Added
+
+- **Connect Claude Code:** run the chat agent on your local Claude Code subscription (no
+  API key) instead of an OpenAI-wire LLM — surfaced beside "Connect an LLM". Data stays
+  governed (Claude reaches it only through datacharter's read-only, PII-masked tools via a
+  loopback bridge), and the connection is refused, fail-closed, unless the tool sandbox
+  verifies (auto-denying any non-governed tools). Requires a Claude Pro/Max subscription +
+  Claude Code installed.
+- **Per-field agent-access toggles (left panel):** control per field / table / source
+  whether the agent sees real values or masked (`•••`) ones, persisted to the contract
+  (`agent_access:`). PII (declared or auto-detected) defaults to masked; everything else to
+  real; an explicit toggle wins. Enforced on the agent surface only (agent, MCP, Claude
+  Code) — the human SQL editor is never masked. "Agent view" mirrors the toggles.
+- Remove snapshots and uploaded tables directly from the sidebar (a ✕ on `local.*` and
+  uploaded rows), via `DELETE /api/snapshot/{name}` and `DELETE /api/uploads/{name}`.
+
+### Fixed
+
+- The sidebar listed each attached-source table twice — once correctly and once as a fake
+  "upload" — because the engine's internal `<source>__<table>` compatibility views were
+  included in the catalog listing. They're now hidden.
+
+## [0.3.4] - 2026-07-24
+
+### Added
+
+- Empty workspaces get an "add your data" first-run launchpad (add a source / drop a
+  CSV / load the demo dataset) instead of the demo feature-tour, which now auto-shows
+  only when the workspace has sources. New `POST /api/demo` loads the demo `store` as a
+  normal, deletable source.
+
 ## [0.3.3] - 2026-07-24
 
 ### Fixed

{datacharter-0.3.3 → datacharter-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datacharter
-Version: 0.3.3
+Version: 0.4.0
 Summary: Charter your data — contract-governed local data exploration, powered by DuckDB
 Project-URL: Homepage, https://github.com/datacharter/datacharter
 Project-URL: Repository, https://github.com/datacharter/datacharter

{datacharter-0.3.3 → datacharter-0.4.0}/src/datacharter/__init__.py

@@ -1,3 +1,3 @@
 """DataCharter — contract-governed local data exploration."""
 
-__version__ = "0.3.3"
+__version__ = "0.4.0"

datacharter-0.4.0/src/datacharter/agent/claude_code.py

@@ -0,0 +1,201 @@
+"""Drive the local Claude Code (headless, subscription) as datacharter's agent backend.
+
+Governance: every invocation is locked down (strict MCP config + a deny-list settings file +
+`--permission-mode dontAsk`) and gated by a fail-closed tool-surface assertion. Claude reaches
+data only through the governed `datacharter mcp --serve-url` proxy. Never uses `--bare` — that
+disables subscription auth. Design: docs/superpowers/specs/2026-07-24-claude-code-agent-backend-design.md
+"""  # noqa: E501
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shutil
+import sys
+import tempfile
+from collections.abc import AsyncIterator, Iterable, Iterator
+from pathlib import Path
+
+GOVERNED_TOOLS = [
+    "mcp__datacharter__query",
+    "mcp__datacharter__list_tables",
+    "mcp__datacharter__list_sources",
+    "mcp__datacharter__describe_table",
+]
+
+# Best-effort removal of built-ins. The connect-time assertion is the real guarantee;
+# extend this from a clean-env `init.tools` list if the assertion reports a stray built-in.
+_DENY = [
+    "Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch", "Agent",
+    "Workflow", "Skill", "ToolSearch", "TaskCreate", "TaskGet", "TaskList", "TaskUpdate",
+    "TaskStop", "TaskOutput", "ScheduleWakeup", "CronCreate", "CronDelete", "CronList",
+    "SendMessage", "NotebookEdit", "Monitor", "WaitForMcpServers", "Artifact",
+    "AskUserQuestion", "EnterPlanMode", "ExitPlanMode", "ReportFindings",
+    "DesignSync", "EnterWorktree", "ExitWorktree", "PushNotification", "RemoteTrigger",
+]
+
+
+class ClaudeGovernanceError(RuntimeError):
+    """Raised when Claude Code exposes tools beyond the governed set — connection refused."""
+
+
+def claude_available() -> bool:
+    return shutil.which("claude") is not None
+
+
+def _dc_bin() -> str:
+    # Must be the SAME datacharter that's serving (it needs `mcp --serve-url`); prefer the
+    # console script next to the running interpreter over whatever is first on PATH.
+    sibling = Path(sys.executable).parent / "datacharter"
+    if sibling.exists():
+        return str(sibling)
+    return shutil.which("datacharter") or "datacharter"
+
+
+def tool_surface_ok(tools: list[str]) -> bool:
+    return set(tools).issubset(set(GOVERNED_TOOLS))
+
+
+def build_configs(
+    serve_url: str, dc_bin: str, tmpdir: Path, deny: list[str] | None = None
+) -> tuple[Path, Path]:
+    settings = tmpdir / "settings.json"
+    mcp = tmpdir / "mcp.json"
+    settings.write_text(
+        json.dumps(
+            {
+                "defaultMode": "dontAsk",
+                "permissions": {"allow": GOVERNED_TOOLS, "deny": deny or _DENY},
+            }
+        )
+    )
+    mcp.write_text(
+        json.dumps(
+            {
+                "mcpServers": {
+                    "datacharter": {"command": dc_bin, "args": ["mcp", "--serve-url", serve_url]}
+                }
+            }
+        )
+    )
+    return settings, mcp
+
+
+def _base_flags(settings: Path, mcp: Path) -> list[str]:
+    return [
+        "--strict-mcp-config", "--mcp-config", str(mcp),
+        "--settings", str(settings), "--permission-mode", "dontAsk",
+    ]
+
+
+def _env() -> dict:
+    env = dict(os.environ)
+    env.pop("ANTHROPIC_API_KEY", None)  # force subscription auth
+    return env
+
+
+def parse_stream(lines: Iterable[str]) -> Iterator[dict]:
+    """Map claude `stream-json` NDJSON lines to `{kind, ...}` events.
+
+    kinds: `session` (init: session_id + tools), `tool_call` (governed tool + SQL),
+    `text` (assistant delta), `result` (final text + session_id + is_error)."""
+    for raw in lines:
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            m = json.loads(raw)
+        except json.JSONDecodeError:
+            continue
+        mtype = m.get("type")
+        if mtype == "system" and m.get("subtype") == "init":
+            yield {
+                "kind": "session",
+                "session_id": m.get("session_id"),
+                "tools": m.get("tools", []),
+            }
+        elif mtype == "stream_event":
+            ev = m.get("event", {}) or {}
+            name = str(ev.get("name", ""))
+            if ev.get("type") == "tool_use" and name.startswith("mcp__datacharter__"):
+                label = ev["name"].removeprefix("mcp__datacharter__")
+                sql = (ev.get("input") or {}).get("sql")
+                yield {"kind": "tool_call", "tool": f"{label}: {sql}" if sql else label}
+            delta = ev.get("delta") or {}
+            if delta.get("type") == "text_delta" and delta.get("text"):
+                yield {"kind": "text", "text": delta["text"]}
+        elif mtype == "result":
+            yield {
+                "kind": "result",
+                "session_id": m.get("session_id"),
+                "text": m.get("result", ""),
+                "is_error": m.get("is_error", False),
+            }
+
+
+async def probe_tools(
+    serve_url: str, dc_bin: str | None = None, deny: list[str] | None = None
+) -> list[str]:
+    """Spawn a locked-down claude and return the tool names it actually exposes (init.tools)."""
+    dc_bin = dc_bin or _dc_bin()
+    with tempfile.TemporaryDirectory(prefix="dc-claude-") as td:
+        settings, mcp = build_configs(serve_url, dc_bin, Path(td), deny)
+        proc = await asyncio.create_subprocess_exec(
+            "claude", "-p", "ok", "--output-format", "stream-json", "--verbose",
+            *_base_flags(settings, mcp),
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.DEVNULL, env=_env(),
+        )
+        out, _ = await proc.communicate()
+        for ev in parse_stream(out.decode().splitlines()):
+            if ev["kind"] == "session":
+                return ev.get("tools", [])
+    return []
+
+
+async def assert_tool_surface(serve_url: str, dc_bin: str | None = None) -> list[str]:
+    """Fail-closed: probe Claude's tool surface, auto-deny any non-governed tools it finds,
+    and re-probe until only the governed tools remain — returning the effective deny-list.
+    Raises `ClaudeGovernanceError` if a non-governed tool cannot be disabled."""
+    dc_bin = dc_bin or _dc_bin()
+    deny = list(_DENY)
+    extras: list[str] = []
+    for _ in range(4):
+        tools = await probe_tools(serve_url, dc_bin, deny)
+        extras = sorted(set(tools) - set(GOVERNED_TOOLS))
+        if not extras:
+            return deny
+        deny += [t for t in extras if t not in deny]  # deny only removes; loop converges
+    raise ClaudeGovernanceError(
+        "Refusing to connect: Claude Code exposes non-governed tools that could not be "
+        "disabled: " + ", ".join(extras)
+    )
+
+
+async def run_turn(
+    question: str,
+    serve_url: str,
+    session_id: str | None = None,
+    dc_bin: str | None = None,
+    deny: list[str] | None = None,
+) -> AsyncIterator[dict]:
+    """Run one chat turn; yield parsed stream events. Resumes `session_id` for context.
+    `deny` is the effective deny-list from the connect-time assertion."""
+    dc_bin = dc_bin or _dc_bin()
+    with tempfile.TemporaryDirectory(prefix="dc-claude-") as td:
+        settings, mcp = build_configs(serve_url, dc_bin, Path(td), deny)
+        args = [
+            "claude", "-p", question, "--output-format", "stream-json",
+            "--verbose", "--include-partial-messages",
+            *_base_flags(settings, mcp),
+        ]
+        if session_id:
+            args += ["--resume", session_id]
+        proc = await asyncio.create_subprocess_exec(
+            *args, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.DEVNULL, env=_env()
+        )
+        assert proc.stdout is not None
+        async for line in proc.stdout:
+            for ev in parse_stream([line.decode()]):
+                yield ev
+        await proc.wait()

datacharter-0.4.0/src/datacharter/agent/remote_tools.py

@@ -0,0 +1,24 @@
+"""A ToolBox-shaped facade that forwards tool calls to a running `datacharter serve`.
+
+Lets the stdio MCP server (`datacharter mcp --serve-url`) expose the governed tools without
+opening a second engine, which would deadlock on the workspace state-DB lock. Governance is
+the serve process's — `/api/tool` runs the same guarded, PII-masking toolbox as `/api/query`.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+
+class RemoteToolBox:
+    def __init__(
+        self, serve_url: str, *, _transport: httpx.AsyncBaseTransport | None = None
+    ) -> None:
+        self._url = serve_url.rstrip("/") + "/api/tool"
+        self._transport = _transport
+
+    async def run(self, name: str, arguments: str) -> str:
+        async with httpx.AsyncClient(transport=self._transport, timeout=120) as client:
+            resp = await client.post(self._url, json={"name": name, "arguments": arguments or "{}"})
+            resp.raise_for_status()
+            return resp.json()["result"]

{datacharter-0.3.3 → datacharter-0.4.0}/src/datacharter/agent/tools.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 from typing import Any
 
+from datacharter.contracts.access import resolve_masked
 from datacharter.engine.session import Engine
 from datacharter.models import QueryResult, Source
 
@@ -63,13 +64,18 @@ _MAX_TOOL_ROWS = 50
 class ToolBox:
     """Executes tool calls against the engine; masks PII columns in returned data."""
 
-    def __init__(self, engine: Engine, sources: list[Source]) -> None:
+    def __init__(
+        self, engine: Engine, sources: list[Source], *, auto_pii: set[str] | None = None
+    ) -> None:
         self._engine = engine
         # Column names flagged PII in any source's contract, matched case-insensitively.
         self._pii: set[str] = set()
         for src in sources:
             for cols in src.pii.values():
                 self._pii.update(c.lower() for c in cols)
+        self._auto_pii = auto_pii or set()
+        # Per-source agent-access overrides (on=real, off=masked).
+        self._overrides = {s.name: s.agent_access for s in sources if s.agent_access}
 
     async def run(self, name: str, arguments: str) -> str:
         try:
@@ -111,17 +117,51 @@ class ToolBox:
         if not _is_safe_relation(relation):
             return "Error: invalid relation name."
         result = await self._engine.query(f"DESCRIBE {relation}", timeout_s=30)
-        return self._render(result)
+        return self._render(result, set())  # schema is always visible; values masked only in query
 
     async def _query(self, args: dict) -> str:
         sql = str(args.get("sql", ""))
         result = await self._engine.query(sql, row_limit=_MAX_TOOL_ROWS)
-        return self._render(result)
-
-    def _render(self, result: QueryResult) -> str:
-        mask_idx = {
-            i for i, col in enumerate(result.columns) if col.lower() in self._pii
-        }
+        return self._render(result, self._mask_indices(result))
+
+    def _masked(self, source: str, table: str, column: str) -> bool:
+        return resolve_masked(
+            source, table, column,
+            declared_pii=self._pii, auto_pii=self._auto_pii, overrides=self._overrides,
+        )
+
+    def _mask_indices(self, result: QueryResult) -> set[int]:
+        """Which output columns to mask. Prefer per-column lineage; when it's missing
+        (e.g. SELECT *), resolve each column against the query's touched relations so
+        agent-access overrides still apply; last resort is a name-based PII check."""
+        prov = result.provenance or {}
+        lineage = prov.get("lineage") or {}
+        rels = []
+        for r in prov.get("relations") or []:
+            parts = str(r).split(".")
+            if len(parts) >= 2:
+                rels.append((parts[-2], parts[-1]))  # (source, table)
+        idx = set()
+        for i, outcol in enumerate(result.columns):
+            srcs = lineage.get(outcol)
+            if srcs:
+                if any(self._lineage_masked(s) for s in srcs):
+                    idx.add(i)
+            elif rels:
+                if any(self._masked(s, t, outcol) for (s, t) in rels):
+                    idx.add(i)
+            elif outcol.lower() in self._pii or outcol.lower() in self._auto_pii:
+                idx.add(i)
+        return idx
+
+    def _lineage_masked(self, qualified: str) -> bool:
+        parts = qualified.split(".")
+        if len(parts) >= 3:
+            return self._masked(parts[-3], parts[-2], parts[-1])
+        name = parts[-1].lower()
+        return name in self._pii or name in self._auto_pii
+
+    def _render(self, result: QueryResult, mask_idx: set[int]) -> str:
         rows = [
             [MASKED if i in mask_idx else v for i, v in enumerate(row)]
             for row in result.rows

{datacharter-0.3.3 → datacharter-0.4.0}/src/datacharter/cli.py

@@ -7,6 +7,7 @@ import sys
 from pathlib import Path
 
 from datacharter import __version__
+from datacharter.demo import write_demo_data
 
 CHARTER_TEMPLATE = """\
 # DataCharter workspace — https://github.com/datacharter/datacharter
@@ -72,7 +73,7 @@ def _cmd_init(args: argparse.Namespace) -> int:
     (ws / "queries").mkdir(exist_ok=True)
     _ensure_gitignore(ws)
     if args.demo:
-        _write_demo_data(ws)
+        write_demo_data(ws)
     print(f"Workspace initialized in {ws}.")
     if args.demo:
         print("Demo data in demo/ — try: datacharter serve")
@@ -87,35 +88,6 @@ def _ensure_gitignore(ws: Path) -> None:
         gi.write_text(existing + joiner + GITIGNORE_BLOCK)
 
 
-def _write_demo_data(ws: Path) -> None:
-    import sqlite3
-
-    demo = ws / "demo"
-    demo.mkdir(exist_ok=True)
-    con = sqlite3.connect(str(demo / "store.db"))
-    try:
-        con.execute("CREATE TABLE customers (id INTEGER, email TEXT, tier TEXT)")
-        con.executemany(
-            "INSERT INTO customers VALUES (?, ?, ?)",
-            [
-                (1, "ada@example.com", "pro"),
-                (2, "grace@example.com", "free"),
-                (3, "edsger@example.com", "pro"),
-            ],
-        )
-        con.execute("CREATE TABLE orders (customer_id INTEGER, total REAL, placed_on TEXT)")
-        con.executemany(
-            "INSERT INTO orders VALUES (?, ?, ?)",
-            [
-                ((i % 3) + 1, round((i * 37 % 200) + i * 0.5, 2), f"2026-01-{(i % 28) + 1:02d}")
-                for i in range(90)
-            ],
-        )
-        con.commit()
-    finally:
-        con.close()
-
-
 def _resolve_serve_workspace(directory: str) -> Path:
     """Workspace for serve; ephemeral demo when no charter.yaml (D3, no surprise writes)."""
     ws = Path(directory).resolve()
@@ -125,7 +97,7 @@ def _resolve_serve_workspace(directory: str) -> Path:
 
     demo_ws = Path(tempfile.mkdtemp(prefix="datacharter-demo-"))
     (demo_ws / "charter.yaml").write_text(DEMO_CHARTER)
-    _write_demo_data(demo_ws)
+    write_demo_data(demo_ws)
     print(f"No charter.yaml in {ws} — serving an ephemeral demo workspace ({demo_ws}).")
     print("Run `datacharter init` here to start a real workspace.")
     return demo_ws
@@ -188,7 +160,8 @@ def _cmd_serve(args: argparse.Namespace) -> int:
     ws = _resolve_serve_workspace(args.directory)
     llm = None if args.offline else (_local_llm(args.model) if args.local else None)
     app = create_app(
-        ws, allow_spill=not args.no_spill, llm=llm, host=args.host, offline=args.offline
+        ws, allow_spill=not args.no_spill, llm=llm, host=args.host, port=args.port,
+        offline=args.offline,
     )
     if args.offline:
         _print_attestation(ws, args.host, args.port)
@@ -231,9 +204,17 @@ def _cmd_secrets(args: argparse.Namespace) -> int:
 def _cmd_mcp(args: argparse.Namespace) -> int:
     import asyncio
 
+    from datacharter.mcp.server import serve_stdio
+
+    if args.serve_url:
+        from datacharter.agent.remote_tools import RemoteToolBox
+
+        print(f"datacharter MCP proxy → {args.serve_url}", file=sys.stderr)
+        asyncio.run(serve_stdio(RemoteToolBox(args.serve_url)))
+        return 0
+
     from datacharter.agent.tools import ToolBox
     from datacharter.contracts import load_charter
-    from datacharter.mcp.server import serve_stdio
 
     ws = Path(args.directory).resolve()
     if not (ws / "charter.yaml").exists():
@@ -282,29 +263,9 @@ def _cmd_diff(args: argparse.Namespace) -> int:
 
 async def _scan_pii(engine) -> dict[str, list[str]]:
     """Suggest PII columns per relation: by name, then by sampled values."""
-    from datacharter.contracts.pii import classify_pii, detect_value_pii
-
-    tables = await engine.query("SHOW ALL TABLES", timeout_s=30)
-    idx = {c: i for i, c in enumerate(tables.columns)}
-    suggestions: dict[str, list[str]] = {}
-    for row in tables.rows:
-        db = row[idx["database"]]
-        if db in ("system", "temp"):
-            continue
-        table = row[idx["name"]]
-        relation = table if db == "memory" else f"{db}.{table}"
-        columns = list(row[idx["column_names"]])
-        flagged = set(classify_pii(columns))
-        remaining = [c for c in columns if c not in flagged]
-        if remaining and all(ch.isalnum() or ch in "._" for ch in relation):
-            sample = await engine.query(f"SELECT * FROM {relation} LIMIT 25", timeout_s=30)
-            pos = {c: i for i, c in enumerate(sample.columns)}
-            for col in remaining:
-                if col in pos and detect_value_pii([r[pos[col]] for r in sample.rows]):
-                    flagged.add(col)
-        if flagged:
-            suggestions[relation] = [c for c in columns if c in flagged]
-    return suggestions
+    from datacharter.contracts.pii import detect_pii
+
+    return await detect_pii(engine)
 
 
 def _cmd_scan(args: argparse.Namespace) -> int:
@@ -629,6 +590,11 @@ def main(argv: list[str] | None = None) -> int:
         "mcp", help="Run an MCP server over stdio exposing the governed query tools"
     )
     p_mcp.add_argument("directory", nargs="?", default=".")
+    p_mcp.add_argument(
+        "--serve-url",
+        default=None,
+        help="Proxy tools to a running `datacharter serve` instead of opening a local engine",
+    )
     p_mcp.set_defaults(func=_cmd_mcp)
 
     p_diff = sub.add_parser("diff", help="Diff two relations (rows only in each + common count)")

datacharter-0.4.0/src/datacharter/contracts/access.py

@@ -0,0 +1,31 @@
+"""Resolve whether an agent-facing column is masked (access OFF) or real (ON).
+
+Precedence: field override -> table override -> source override -> default (masked iff the
+column is PII: declared or auto-detected). In the contract, `on` = real, `off` = masked.
+"""
+
+from __future__ import annotations
+
+
+def resolve_masked(
+    source: str,
+    table: str,
+    column: str,
+    *,
+    declared_pii: set[str],
+    auto_pii: set[str],
+    overrides: dict,
+) -> bool:
+    """True if the agent should see this column masked (`•••`), False for real values."""
+    src_ov = overrides.get(source) or {}
+    columns = src_ov.get("columns") or {}
+    key = f"{table}.{column}"
+    if key in columns:
+        return not columns[key]  # on -> not masked
+    tables = src_ov.get("tables") or {}
+    if table in tables:
+        return not tables[table]
+    if "source" in src_ov:
+        return not src_ov["source"]
+    col = column.lower()
+    return col in declared_pii or col in auto_pii  # default: PII masked, else real

{datacharter-0.3.3 → datacharter-0.4.0}/src/datacharter/contracts/loader.py

@@ -121,6 +121,7 @@ def _build_source(name: str, body: Any, resolver: SecretResolver, warnings: list
             path=path_value,
             tables=list(body.get("tables") or []),
             pii={k: list(v) for k, v in (body.get("pii") or {}).items()},
+            agent_access=dict(body.get("agent_access") or {}),
             max_rows=max_rows,
         )
     except ValidationError as exc:

{datacharter-0.3.3 → datacharter-0.4.0}/src/datacharter/contracts/pii.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 
 import re
 
-__all__ = ["classify_pii", "detect_value_pii", "PII_TOKENS"]
+__all__ = ["classify_pii", "detect_value_pii", "detect_pii", "PII_TOKENS"]
 
 # High-precision value patterns only — distinctive enough that matching most of a
 # column's sampled values is strong evidence, without the false positives a loose
@@ -79,3 +79,28 @@ def detect_value_pii(values: list, *, threshold: float = 0.6) -> str | None:
         if sum(1 for s in samples if pattern.match(s)) / len(samples) >= threshold:
             return kind
     return None
+
+
+async def detect_pii(engine) -> dict[str, list[str]]:
+    """Suggest PII columns per relation: by name, then by sampled values."""
+    tables = await engine.query("SHOW ALL TABLES", timeout_s=30)
+    idx = {c: i for i, c in enumerate(tables.columns)}
+    suggestions: dict[str, list[str]] = {}
+    for row in tables.rows:
+        db = row[idx["database"]]
+        if db in ("system", "temp"):
+            continue
+        table = row[idx["name"]]
+        relation = table if db == "memory" else f"{db}.{table}"
+        columns = list(row[idx["column_names"]])
+        flagged = set(classify_pii(columns))
+        remaining = [c for c in columns if c not in flagged]
+        if remaining and all(ch.isalnum() or ch in "._" for ch in relation):
+            sample = await engine.query(f"SELECT * FROM {relation} LIMIT 25", timeout_s=30)
+            pos = {c: i for i, c in enumerate(sample.columns)}
+            for col in remaining:
+                if col in pos and detect_value_pii([r[pos[col]] for r in sample.rows]):
+                    flagged.add(col)
+        if flagged:
+            suggestions[relation] = [c for c in columns if c in flagged]
+    return suggestions

{datacharter-0.3.3 → datacharter-0.4.0}/src/datacharter/contracts/writer.py

@@ -64,6 +64,31 @@ def remove_source(workspace: Path, name: str) -> None:
     _write(path, y, data)
 
 
+def set_agent_access(
+    workspace: Path, source: str, table: str | None, column: str | None, value: bool
+) -> None:
+    """Persist one agent-access override (on=real, off=masked) at field/table/source level.
+
+    Touches only the source's `agent_access` block; everything else is preserved verbatim."""
+    path = workspace / CHARTER_FILE
+    y, data = _load(path)
+    sources = data.get("sources") or {}
+    if source not in sources:
+        raise ContractWriteError(f"Source '{source}' is not in the charter.")
+    entry = sources[source]
+    aa = entry.get("agent_access")
+    if aa is None:
+        aa = {}
+        entry["agent_access"] = aa
+    if column is not None and table is not None:
+        aa.setdefault("columns", {})[f"{table}.{column}"] = value
+    elif table is not None:
+        aa.setdefault("tables", {})[table] = value
+    else:
+        aa["source"] = value
+    _write(path, y, data)
+
+
 def set_pii(workspace: Path, source: str, table: str, columns: list[str]) -> None:
     """Merge PII column names into one source's pii map (round-trip).
 

datacharter-0.4.0/src/datacharter/demo.py

@@ -0,0 +1,46 @@
+"""The demo dataset: a small sqlite `store` (customers + orders) for onboarding."""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+# Descriptor for registering the demo as a real, deletable source (see POST /api/demo).
+DEMO_SOURCE = {
+    "name": "store",
+    "type": "sqlite",
+    "path": "demo/store.db",
+    "tables": ["customers", "orders"],
+    "pii": {"customers": ["email"]},
+}
+
+
+def write_demo_data(workspace: Path) -> None:
+    """Write the demo `store.db` (customers + orders) under `<workspace>/demo/`."""
+    demo = workspace / "demo"
+    demo.mkdir(exist_ok=True)
+    con = sqlite3.connect(str(demo / "store.db"))
+    try:
+        # Idempotent: a prior demo may have been loaded then deleted, leaving store.db.
+        con.execute("DROP TABLE IF EXISTS customers")
+        con.execute("DROP TABLE IF EXISTS orders")
+        con.execute("CREATE TABLE customers (id INTEGER, email TEXT, tier TEXT)")
+        con.executemany(
+            "INSERT INTO customers VALUES (?, ?, ?)",
+            [
+                (1, "ada@example.com", "pro"),
+                (2, "grace@example.com", "free"),
+                (3, "edsger@example.com", "pro"),
+            ],
+        )
+        con.execute("CREATE TABLE orders (customer_id INTEGER, total REAL, placed_on TEXT)")
+        con.executemany(
+            "INSERT INTO orders VALUES (?, ?, ?)",
+            [
+                ((i % 3) + 1, round((i * 37 % 200) + i * 0.5, 2), f"2026-01-{(i % 28) + 1:02d}")
+                for i in range(90)
+            ],
+        )
+        con.commit()
+    finally:
+        con.close()