columna-server 0.1.0__tar.gz

columna_server-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS / editor
+.DS_Store
+*.swp
+
+# Raw handoff bundle (provenance, not part of the deliverable)
+attachments/

columna_server-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to **columna-server** are recorded here
+([Keep a Changelog](https://keepachangelog.com/)).
+
+## [0.1.0] — the MCP server, the packaged demo, and the NL agent
+
+First release. The Columna MCP server and its two front doors, over one contract (ADR-032 D8 — the
+four moods as data; `contract_version` `"1"`).
+
+- **MCP server** (`columna-server mcp --manifolds <dir>`): five read-only tools —
+  `list_manifolds`, `describe_manifold`, `describe_measure`, `query`, `explain` — over a Manifold
+  store (`<id>/manifold.cml` + `data.toml`, parsed once at startup). stdio canonical;
+  `--http` gated by `COLUMNA_MCP_TOKEN` (constant-time `hmac.compare_digest`). No SQL, no writes.
+  The envelope grammar is parsed here; every expression is delegated to columna-core (one dialect).
+- **Packaged demo** (`columna-server demo [--play]`): the benchmark Manifold over a small bundled
+  warehouse (byte-identical to the core fixtures, drift-guarded), runnable with no path args.
+  `--play` prints the real clarify → refuse → disclose wire transcript.
+- **Natural-language agent** (`columna-server agent`, `[agent]` extra): a true MCP client — spawns
+  the server over stdio and speaks the protocol, never importing the engine. Natural language
+  becomes a *proposed* Frame-QL query; the four moods drive the conversation (clarifies relayed,
+  never auto-picked; every numeral verbatim from the wire — grounding is structural). Provider layer
+  (`anthropic` default via `COLUMNA_AGENT_MODEL`; `scripted` for tests).
+
+[0.1.0]: https://github.com/datumwise/columna

columna_server-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: columna-server
+Version: 0.1.0
+Summary: Columna MCP server — a library of Manifolds exposed to AI agents over MCP, one contract (the four moods as data).
+Author: Datumwise
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: columna-core>=0.7.8
+Requires-Dist: duckdb<2.0,>=1.0
+Requires-Dist: mcp>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: agent
+Requires-Dist: anthropic>=0.40; extra == 'agent'
+Provides-Extra: http
+Requires-Dist: starlette>=0.37; extra == 'http'
+Requires-Dist: uvicorn>=0.23; extra == 'http'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# columna-server
+
+The **Columna MCP server** (ADR-032 D8): a library of Manifolds exposed to AI agents over MCP, with
+**one contract** — every tool returns the same outcome/disclosure structure the Python API returns.
+This is the wedge product: the first metrics MCP server that can say *"it depends."*
+
+## Run
+
+```bash
+pip install columna-core columna-server
+columna-server demo --play                    # the packaged demo: clarify -> refuse -> disclose
+columna-server demo                           # serve the packaged demo over MCP stdio (no path args)
+columna-server mcp --manifolds <dir>          # serve your own manifolds dir over stdio
+columna-server mcp --manifolds <dir> --http :8000   # streamable-http, gated by COLUMNA_MCP_TOKEN
+
+# Natural-language agent (a true MCP client over the server); needs the [agent] extra + a key:
+pip install "columna-server[agent]"
+ANTHROPIC_API_KEY=... columna-server agent    # chat REPL over the packaged demo
+```
+
+The **agent** turns natural language into a *proposed* Frame-QL query, spawns the server over stdio,
+and lets the four moods drive the conversation — it never touches the engine in-process. The model
+proposes, the planner disposes, the human decides (clarifies are relayed, never auto-picked; every
+number comes verbatim from the wire). See [`demos/agent_transcript.md`](demos/agent_transcript.md).
+Model via `COLUMNA_AGENT_MODEL` (default `claude-opus-4-8`).
+
+**Richer run.** The packaged demo ships a small (~330 KB) warehouse. To run the same benchmark
+Manifold over the full 4.7 MB warehouse (299,934 transactions), point `--manifolds` at a directory
+whose `data.toml` warehouse path is the repo's `packages/columna-core/demos/warehouse`.
+
+> **From source (contributors):** `git clone https://github.com/datumwise/columna && cd columna`,
+> then `pip install -e packages/columna-core -e "packages/columna-server[test]"` and
+> `pytest packages/columna-server -q`.
+
+`<dir>` holds `<id>/manifold.cml` + `data.toml` (connector type + data path). Manifolds are parsed
+and connected once at startup.
+
+## Tools (five, read-only — no SQL, no writes)
+
+| tool | touches data? | returns |
+|---|---|---|
+| `list_manifolds()` | no | id, name, description, measure count, universes |
+| `describe_manifold(manifold_id)` | no | dimensions/levels, edges (+ lineage), universes (+ predicate), measure index |
+| `describe_measure(manifold_id, measure)` | no | family triple, per-member anchors, dtype, v-anchor `{universe, grain}`, m-anchor, provenance |
+| `query(manifold_id, frameql, universe?)` | yes | the wire contract (serve/disclose/clarify/refuse/error) |
+| `explain(manifold_id, frameql, universe?)` | **no** (`fetches_delta: 0`) | the would-be outcome + disclosures |
+
+`frameql` is `"<columns> @ <anchor>"` (e.g. `"rate: revenue / level.last @ store, day"`); the
+envelope is parsed here and every expression is delegated to columna-core — one expression dialect.
+
+## The contract
+
+Outcomes are data (the four moods), and disclosures are structured `{code, materiality, severity,
+category, detail, remedy, source, rel_error}` via `columna_core.disclosure_wire` — the same
+serialization every surface shares. Clarify alternatives are mechanically substitutable (a universe
+pin carries `apply: {"universe": U}`).
+
+See [`demos/mcp_claude_desktop.md`](demos/mcp_claude_desktop.md) for a Claude Desktop config and a
+real clarify → answer transcript.

columna_server-0.1.0/README.md

@@ -0,0 +1,59 @@
+# columna-server
+
+The **Columna MCP server** (ADR-032 D8): a library of Manifolds exposed to AI agents over MCP, with
+**one contract** — every tool returns the same outcome/disclosure structure the Python API returns.
+This is the wedge product: the first metrics MCP server that can say *"it depends."*
+
+## Run
+
+```bash
+pip install columna-core columna-server
+columna-server demo --play                    # the packaged demo: clarify -> refuse -> disclose
+columna-server demo                           # serve the packaged demo over MCP stdio (no path args)
+columna-server mcp --manifolds <dir>          # serve your own manifolds dir over stdio
+columna-server mcp --manifolds <dir> --http :8000   # streamable-http, gated by COLUMNA_MCP_TOKEN
+
+# Natural-language agent (a true MCP client over the server); needs the [agent] extra + a key:
+pip install "columna-server[agent]"
+ANTHROPIC_API_KEY=... columna-server agent    # chat REPL over the packaged demo
+```
+
+The **agent** turns natural language into a *proposed* Frame-QL query, spawns the server over stdio,
+and lets the four moods drive the conversation — it never touches the engine in-process. The model
+proposes, the planner disposes, the human decides (clarifies are relayed, never auto-picked; every
+number comes verbatim from the wire). See [`demos/agent_transcript.md`](demos/agent_transcript.md).
+Model via `COLUMNA_AGENT_MODEL` (default `claude-opus-4-8`).
+
+**Richer run.** The packaged demo ships a small (~330 KB) warehouse. To run the same benchmark
+Manifold over the full 4.7 MB warehouse (299,934 transactions), point `--manifolds` at a directory
+whose `data.toml` warehouse path is the repo's `packages/columna-core/demos/warehouse`.
+
+> **From source (contributors):** `git clone https://github.com/datumwise/columna && cd columna`,
+> then `pip install -e packages/columna-core -e "packages/columna-server[test]"` and
+> `pytest packages/columna-server -q`.
+
+`<dir>` holds `<id>/manifold.cml` + `data.toml` (connector type + data path). Manifolds are parsed
+and connected once at startup.
+
+## Tools (five, read-only — no SQL, no writes)
+
+| tool | touches data? | returns |
+|---|---|---|
+| `list_manifolds()` | no | id, name, description, measure count, universes |
+| `describe_manifold(manifold_id)` | no | dimensions/levels, edges (+ lineage), universes (+ predicate), measure index |
+| `describe_measure(manifold_id, measure)` | no | family triple, per-member anchors, dtype, v-anchor `{universe, grain}`, m-anchor, provenance |
+| `query(manifold_id, frameql, universe?)` | yes | the wire contract (serve/disclose/clarify/refuse/error) |
+| `explain(manifold_id, frameql, universe?)` | **no** (`fetches_delta: 0`) | the would-be outcome + disclosures |
+
+`frameql` is `"<columns> @ <anchor>"` (e.g. `"rate: revenue / level.last @ store, day"`); the
+envelope is parsed here and every expression is delegated to columna-core — one expression dialect.
+
+## The contract
+
+Outcomes are data (the four moods), and disclosures are structured `{code, materiality, severity,
+category, detail, remedy, source, rel_error}` via `columna_core.disclosure_wire` — the same
+serialization every surface shares. Clarify alternatives are mechanically substitutable (a universe
+pin carries `apply: {"universe": U}`).
+
+See [`demos/mcp_claude_desktop.md`](demos/mcp_claude_desktop.md) for a Claude Desktop config and a
+real clarify → answer transcript.

columna_server-0.1.0/demos/agent_nonexistent_measure_transcript.md

@@ -0,0 +1,31 @@
+# The agent on a metric that doesn't exist — a verbatim capture
+
+Real, unedited output from **`claude-opus-4-8`** driving `columna-server agent` over the packaged
+demo Manifold (captured live this session). It shows the honest-naming property: asked for a
+plausible-but-fake metric, the agent does **not** invent a measure — it asks which of the manifold's
+real measures is meant.
+
+The demo Manifold's measures are `revenue`, `orders`, `visitors`, `level` (family `sum`/`last`, on
+the `store_days` universe), `med_amount`, and `region_label`. There is **no** `sell_through_rate`
+measure — that name is only a *column label* one might give the ratio `revenue / level.last`.
+
+---
+
+**you:** now the sell-through rate by store and day
+
+**agent** *(verbatim, an `ASK` — no query proposed, no number invented)*:
+> I don't have a `sell_through_rate` measure in this manifold. I do have `revenue`, `orders`,
+> `visitors`, `level` (sum/last, on store_days), and `med_amount`. Which of these would you like by
+> store and day?
+
+---
+
+The model proposed neither a fabricated `sell_through_rate` measure nor a guessed number — it asked.
+And the backstop holds even if a model *did* fabricate one: a query naming an unknown measure is
+rejected by the engine (unknown column) and the system presents it as an invalid query, so no fake
+figure can ever reach the human. Both behaviors are covered by tests
+(`test_live_asks_on_a_plausible_but_fake_metric` and
+`test_engine_and_formatter_backstop_a_fabricated_measure`).
+
+> *Provenance: captured from a live `@pytest.mark.llm` run against `claude-opus-4-8` on 2026-07-09.
+> The API key used for that run has since been rotated; a fresh re-run needs a new `ANTHROPIC_API_KEY`.*

columna_server-0.1.0/demos/agent_transcript.md

@@ -0,0 +1,76 @@
+# The Columna query agent — the wedge in natural language
+
+`columna-server agent` is Columna's own natural-language front door, and it is **a true MCP client**:
+it spawns `columna-server` over stdio and speaks the protocol — it never touches the engine
+in-process. Natural language becomes a *proposed* Frame-QL query; the planner disposes; the four
+moods drive the conversation. The model proposes, the layer checks, the human decides.
+
+Run it against the packaged demo (needs `ANTHROPIC_API_KEY` and the agent extra —
+`pip install -e "packages/columna-server[agent]"`):
+
+```bash
+columna-server agent            # packaged demo Manifold, no path args
+```
+
+Below is a real conversation (the transcript the hermetic tests assert against, value rows elided).
+It walks through **all four moods** — serve → clarify → refuse → disclose — in one human exchange.
+Every number shown comes verbatim from the server's wire JSON; the agent never computes or restates
+a figure, so it can never state a wrong one.
+
+---
+
+**you:** what's revenue by region?
+
+**agent** *(serve)*:
+> Here is the answer:
+> revenue: region="south"=771240.4099999999; region="north"=601075.3299999996; region="east"=615704.5300000003; region="west"=224371.58999999994
+
+The agent proposed `QUERY: revenue @ region`; the server served it; the agent presents the values
+exactly as the wire returned them.
+
+---
+
+**you:** what's the sell-through rate by store and day?
+
+**agent** *(clarify — relayed to you, never auto-picked)*:
+> That question is ambiguous: ratio combines measures over different populations ['store_days',
+> 'transactions'] … which population should the rate be taken over?
+> Please choose:
+>   [1] express both numerator and denominator within universe 'store_days'
+>   [2] express both numerator and denominator within universe 'transactions'
+> Reply with the number of your choice.
+
+`revenue / level.last` spans two populations, so the rate has no single value. The server clarifies;
+the agent relays the alternatives and **waits for your choice**. It does not guess a population.
+
+---
+
+**you:** 1
+
+**agent** *(refuse — explained honestly)*:
+> That can't be answered: revenue is bound to universe 'transactions', not the pinned population
+> 'store_days' — it is not defined over that population
+
+Your choice is applied mechanically (the alternative's `apply` universe). Pinning `store_days` makes
+the numerator out-of-domain, so there is no faithful rate over that population — the server refuses,
+with the reason, and the agent invents nothing.
+
+---
+
+**you:** then just show revenue and inventory side by side by store and day
+
+**agent** *(disclose — served, with a material caveat)*:
+> Answer (with caveats):
+> rev: store="S001" day="2024-01-05"=218.18; … (rows elided)
+> inv: store="S001" day="2024-01-03"=5622.0; … (rows elided)
+> · disclosure [denominator_population, material]: frame spans multiple universes ['store_days',
+>   'transactions'] — population is ambiguous; pin it with ON UNIVERSE
+
+Reformulated as two separate columns over the union population, the numbers are served **with** a
+material coverage caveat riding on the frame — surfaced in the reply, not dropped.
+
+---
+
+**Four moods, one conversation.** The agent proposed queries and relayed a clarify; it never wrote a
+result number or picked a population. The engine decided answerability; you decided between genuine
+alternatives. One contract, one truth — now reachable in plain English.

columna_server-0.1.0/demos/mcp_claude_desktop.md

@@ -0,0 +1,124 @@
+# Columna MCP server — Claude Desktop config + the co-universe rate clarify → answer flow
+
+The Columna MCP server exposes a library of Manifolds to any MCP client (Claude Desktop, a local
+agent, or Columna's own NL agent) over **one contract**: the four moods — serve · disclose ·
+clarify · refuse — arrive as *data*, identical to the Python API. This is the first metrics MCP
+server that can say **"it depends."**
+
+## 1. Configure Claude Desktop
+
+Add the server to `claude_desktop_config.json` (macOS:
+`~/Library/Application Support/Claude/claude_desktop_config.json`). `stdio` is the canonical
+transport — Claude Desktop launches the process and speaks MCP over its stdin/stdout:
+
+```jsonc
+{
+  "mcpServers": {
+    "columna": {
+      "command": "columna-server",
+      "args": ["mcp", "--manifolds", "/abs/path/to/manifolds"]
+    }
+  }
+}
+```
+
+`--manifolds` points at a directory of `<id>/manifold.cml` + `data.toml` (connector type + data
+path). All Manifolds are parsed and connected **once** at startup; `list_manifolds` / `describe_*`
+never touch data, and `explain` executes nothing (`fetches_delta: 0`).
+
+Five read-only tools appear: `list_manifolds`, `describe_manifold`, `describe_measure`, `query`,
+`explain`. There is **no SQL** and **no write surface** of any kind.
+
+> Remote transport: `columna-server mcp --manifolds <dir> --http :8000`. When `COLUMNA_MCP_TOKEN`
+> is set, every request must carry `Authorization: Bearer <token>` (constant-time checked); when it
+> is unset, HTTP binds loopback-only and warns.
+
+## 2. Three moods in one flow: clarify → refuse → disclose
+
+The wedge: ask for a rate whose two measures live over *different populations* — `revenue` (over
+`transactions`) per `level.last` (a stock, over `store_days`). A SQL/metrics layer would silently
+emit a number. Columna **clarifies**, and the clarify is machine-actionable.
+
+### Query — "sell-through rate: revenue per unit of inventory, by store and day"
+
+```
+query(manifold_id="benchmark", frameql="sell_through_rate: revenue / level.last @ store, day")
+```
+
+→ `outcome: clarify` — the rate's population is ambiguous, and it names the candidate populations as
+**mechanically substitutable** alternatives (`apply.universe`):
+
+```json
+{
+  "contract_version": "1",
+  "outcome": "clarify",
+  "columns": [{
+    "name": "sell_through_rate", "status": "clarify",
+    "no_result": {
+      "kind": "clarify", "discriminator": "ambiguous", "reason": "co_anchor_ambiguous",
+      "detail": "ratio combines measures over different populations ['store_days', 'transactions'] … which population should the rate be taken over?",
+      "alternatives": [
+        {"token": "on_universe('store_days')",   "description": "express both numerator and denominator within universe 'store_days'",   "apply": {"universe": "store_days"}},
+        {"token": "on_universe('transactions')", "description": "express both numerator and denominator within universe 'transactions'", "apply": {"universe": "transactions"}}
+      ]
+    }
+  }]
+}
+```
+
+### Hop 1 — apply a pin token; the server is honest, not eager (→ refuse)
+
+```
+query(manifold_id="benchmark", frameql="sell_through_rate: revenue / level.last @ store, day", universe="store_days")
+```
+
+Pinning to `store_days` makes the numerator out-of-domain, so there is no faithful rate over that
+population — the server **refuses** with an informative reason (it does **not** invent a number):
+
+```json
+{
+  "outcome": "refuse",
+  "columns": [{
+    "name": "sell_through_rate", "status": "refuse",
+    "no_result": {
+      "kind": "refuse", "discriminator": "unsupported", "reason": "out_of_universe",
+      "detail": "revenue is bound to universe 'transactions', not the pinned population 'store_days' — it is not defined over that population"
+    }
+  }]
+}
+```
+
+### Hop 2 — reformulate per the clarify's detail; serve the numbers, disclosed (→ disclose)
+
+Following the clarify's guidance, the agent asks for the two measures as **separate columns** over
+the union population rather than as one rate. The server serves the numbers **and** rides the
+population caveat on the frame. Because that caveat is `material`, the wire outcome is **disclose**
+(materiality — not severity — is the serve/disclose discriminant):
+
+```
+query(manifold_id="benchmark", frameql="revenue: revenue, inv: level.last @ store, day")
+```
+
+```json
+{
+  "outcome": "disclose",
+  "frame": {
+    "rollup_severity": "info",
+    "disclosures": [
+      {"code": "denominator_population", "materiality": "material", "severity": "info",
+       "category": "coverage",
+       "detail": "frame spans multiple universes ['store_days', 'transactions'] — population is ambiguous; pin it with ON UNIVERSE"}
+    ]
+  },
+  "columns": [
+    {"name": "revenue", "status": "served", "population": "transactions",
+     "values": [{"store": "S001", "day": "2024-01-03", "value": 58.26}, "…"]},
+    {"name": "inv", "status": "served", "population": "store_days",
+     "values": [{"store": "S001", "day": "2024-01-01", "value": 5693.0}, "…"]}
+  ]
+}
+```
+
+**The point:** three of the four moods in one conversation — a *structured* clarify, an honest
+pin-**refuse**, and a served-and-**disclosed** answer — driven entirely by machine-readable fields.
+The ambiguity was never guessed away. One contract, every surface.

columna_server-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "columna-server"
+version = "0.1.0"
+description = "Columna MCP server — a library of Manifolds exposed to AI agents over MCP, one contract (the four moods as data)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Datumwise" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "columna-core>=0.7.8",
+    "mcp>=1.0",
+    "tomli>=2.0; python_version < '3.11'",
+    # store.py imports duckdb directly to load the connector's warehouse — declare it explicitly
+    # rather than rely on columna-core pulling it transitively (the WP-0 pyarrow lesson).
+    "duckdb>=1.0,<2.0",
+]
+
+[project.optional-dependencies]
+http = ["uvicorn>=0.23", "starlette>=0.37"]
+agent = ["anthropic>=0.40"]
+test = ["pytest>=8.0", "pytest-asyncio>=0.23"]
+
+[project.scripts]
+columna-server = "columna_server.cli:main"
+
+[tool.hatch.build.targets.wheel]
+# hatchling includes ALL files under the package dir (not just .py), so the packaged demo data
+# (src/columna_server/demo/**: manifold.cml + data.toml + the small bundled warehouse) ships in the
+# wheel automatically — no force-include needed. `columna-server demo` therefore runs with no path
+# args from a clean-venv wheel install (proven by the py3.10 wheel job in CI).
+packages = ["src/columna_server"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "demos", "README.md", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "llm: live test that calls a real LLM provider; needs ANTHROPIC_API_KEY, excluded from CI.",
+]
+
+[tool.ruff]
+line-length = 110
+
+[tool.ruff.lint]
+select = ["F", "E9"]

columna_server-0.1.0/src/columna_server/__init__.py

@@ -0,0 +1,2 @@
+"""Columna MCP server — a library of Manifolds exposed to AI agents over MCP (ADR-032 D8)."""
+__version__ = "0.1.0"

columna_server-0.1.0/src/columna_server/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

columna_server-0.1.0/src/columna_server/agent/__init__.py

@@ -0,0 +1,10 @@
+"""columna_server.agent — the natural-language query agent (a true MCP client; ADR-032 D8)."""
+from .conversation import AGENT, ENGINE, USER, Turn
+from .loop import Agent, load_system_prompt, prompt_example_queries, render_manifold_context
+from .providers import (AnthropicProvider, Provider, ProviderUnavailable, ScriptedProvider,
+                        make_provider)
+
+__all__ = ["Turn", "USER", "AGENT", "ENGINE", "Agent", "load_system_prompt",
+           "prompt_example_queries", "render_manifold_context",
+           "Provider", "ProviderUnavailable", "ScriptedProvider", "AnthropicProvider",
+           "make_provider"]

columna_server-0.1.0/src/columna_server/agent/conversation.py

@@ -0,0 +1,14 @@
+"""columna_server.agent.conversation — the shared turn model."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+USER = "user"      # a human message
+AGENT = "agent"    # the agent's proposed line (QUERY:/ASK:)
+ENGINE = "engine"  # a compact wire summary the system appends after each query
+
+
+@dataclass(frozen=True)
+class Turn:
+    role: str      # USER | AGENT | ENGINE
+    text: str