ariadne-agent 0.2.0__tar.gz

ariadne_agent-0.2.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: ariadne-agent
+Version: 0.2.0
+Summary: Installable Ariadne Agent backend: fixed-role conversations over native Ariadne tools
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: ariadne-data>=0.2.0
+Requires-Dist: tau-ai==0.4.6
+Requires-Dist: tau-mcp>=0.1.0
+
+# ariadne-agent
+
+The installable Ariadne Agent backend: a fixed-role, in-memory conversation
+over **native Ariadne Python tools** — no CLI, no shell, no server, no raw SQL
+([spec 2026-09-29-0006](../project/specs/2026-09-29-0006-ariadne-agent-backend.md),
+[ADR-0014](../project/adr/0014-embedded-tau-agent-backend.md), issue #23).
+This revision ships the **Analyst** and **Authoring** roles plus optionally
+configured **role-restricted stdio MCP** tools (issue #25).
+
+## Install
+
+Depends on `ariadne-data` (never the unrelated PyPI `ariadne` GraphQL project),
+the verified Tau release `tau-ai==0.4.6`, whose embeddable
+`tau_agent.AgentHarness` / `tau_ai.OpenAICompatibleProvider` import paths this
+package uses, and the owned `tau-mcp` embeddable stdio MCP core. The `tau-ai`
+wheel also installs `tau_coding`'s files, but this package never imports or
+invokes `tau_coding` at runtime (the `tau_mcp.proxy` module is likewise not
+imported here because it is the Tau-extension flavor), and never launches a
+server — installing `ariadne-data` alone does not install the agent.
+
+Local development resolves `ariadne-data` from the repository checkout through
+`[tool.uv.sources]` in `pyproject.toml` (non-published tool configuration
+only; the published dependency metadata names the distribution); `tau-mcp`
+resolves the same way from its own repository checkout:
+
+```bash
+cd ariadne-agent && uv run pytest -q tests/test_analyst.py
+```
+
+## Use
+
+The host selects everything up front — project root, role, model, and a fully
+configured provider (model identity, endpoint and credentials are constructed
+outside user messages and data-project artifacts; the agent loads no global
+provider or MCP configuration):
+
+```python
+from ariadne_agent import AssistantText, ToolActivity, open_session
+from tau_ai import OpenAICompatibleProvider, OpenAICompatibleConfig
+
+provider = OpenAICompatibleProvider(OpenAICompatibleConfig(api_key=..., base_url=...))
+session = open_session(role="analyst", project="/path/to/project",
+                       model="your-model", provider=provider)
+async for event in session.send("gross margin by region?"):
+    match event:
+        case AssistantText(text=text):   print(text)
+        case ToolActivity(tool=tool):    print(f"[tool] {tool}")
+session.cancel()   # cooperative: ends subsequent model turns
+session.close()
+```
+
+## MCP (optional, role-restricted)
+
+Passing `mcp_settings` attaches ONE restricted MCP registry to that session,
+built from host-supplied configuration only — validated stdio server entries,
+a cache root, and each role's operator-approved qualified tool names. No
+`~/.tau/mcp.json` or any other ambient MCP configuration is ever loaded, and a
+model request can never alter server commands, the allowlist, or credentials:
+
+```python
+from ariadne_agent.mcp_tools import McpSettings
+from tau_mcp.config import ServerConfig
+
+mcp = McpSettings(
+    servers={"weather": ServerConfig(name="weather", command="...", args=(...))},
+    cache_root=Path("/var/cache/ariadne-mcp"),
+    role_tools={"analyst": ("weather__lookup",)},  # authoring absent => no MCP tools
+)
+session = open_session(role="analyst", ..., mcp_settings=mcp)
+```
+
+Permitted tools surface to the model as one `mcp` proxy tool (search and call
+by `server__tool` name); direct MCP registration stays a Tau extension and is
+not offered. The registry's frozen per-instance allowlist restricts discovery
+**and** dispatch, so a forbidden name the model supplies through the proxy is
+rejected before any spawn or call — the server never sees it. `close()` reaps
+every MCP child this session spawned; a call already executing finishes or
+times out under the MCP client's bounded request timeout (no immediate
+interruption is promised). Omit `mcp_settings` and the native tool surface is
+exactly as before.
+
+The project root selects one of the two runtime kinds (issue #38/G6): a
+**managed Git data project** — one carrying Ariadne's `.ariadne/` operator
+state — resolves through `QueryRuntime.open_project` and serves its pinned
+human-admitted snapshot (a missing admission is an explicit error naming the
+human `ariadne-admit` step, never a fallback to mutable files), while an
+**explicit legacy artifact-root project** must contain the served
+`semantic_layer/` and `context_layer/` directories and either a source
+registry (`ariadne.yaml`) or a `demo.db`; every path resolves against that
+root, never the ambient working directory. The legacy → new mapping lives in
+[docs/how-to/git-authoring.md](../docs/how-to/git-authoring.md).
+
+## Contract
+
+- **Typed async events**: assistant text, tool activity (verbatim JSON payload,
+  error flag), session errors, and run completion. Harness-internal event
+  types never leak through.
+- **One active run per session**; `send` while running raises. **Fixed**
+  role/project/model — a different one requires a new session, with no silent
+  transcript or tool-access transfer.
+- **In memory only**: a process restart loses the messages; there is no resume
+  operation, deliberately.
+- **Analyst tools** are exactly `ariadne.runtime.AriadneRuntime`'s six public
+  operations (`list_metrics`, `search_context`, `get_metric`, `list_datasets`,
+  `define_metric`, `resolve_term`) as thin native tools: values, Policy text
+  and citations, paths, and `governed` labels pass through verbatim. Term
+  resolution is read-only admitted-context guidance — an alias never
+  authorizes a join. No source approval, no promotion, no filesystem writes
+  beyond the runtime's own staging.
+- **Authoring tools** mirror `AuthoringProject`'s Git contract one-to-one —
+  `start_proposal`, `read_artifact`, `edit_proposal`, `propose_sources`,
+  `inputs`, `upload_document`, `validate_proposal`, `refresh_schema`,
+  `inspect_mapping`, `resolve_term`, `review_proposal` — with automatic
+  labeled-hypothesis saves through `edit_proposal` (no per-save prompt) and
+  restart-readable Git/evidence state. Source approval, admission,
+  reconciliation, legacy import/enrichment and Promotion are deliberately
+  absent: human-only, outside the agent.
+- **Guidance**: the version-matched packaged `ariadne/skill_assets/SKILL.md`
+  from the installed `ariadne-data`, plus a short native-tool mapping. No
+  global skill scans, no model-invocable skill scripts.
+- **Missing promoted catalog**: opening an Analyst session fails fast with an
+  actionable error naming the human step — Promotion for a legacy project,
+  `ariadne-admit` for a managed Git project. The failure is session-local — it
+  cannot block a later (e.g. Authoring) session.

ariadne_agent-0.2.0/README.md

@@ -0,0 +1,124 @@
+# ariadne-agent
+
+The installable Ariadne Agent backend: a fixed-role, in-memory conversation
+over **native Ariadne Python tools** — no CLI, no shell, no server, no raw SQL
+([spec 2026-09-29-0006](../project/specs/2026-09-29-0006-ariadne-agent-backend.md),
+[ADR-0014](../project/adr/0014-embedded-tau-agent-backend.md), issue #23).
+This revision ships the **Analyst** and **Authoring** roles plus optionally
+configured **role-restricted stdio MCP** tools (issue #25).
+
+## Install
+
+Depends on `ariadne-data` (never the unrelated PyPI `ariadne` GraphQL project),
+the verified Tau release `tau-ai==0.4.6`, whose embeddable
+`tau_agent.AgentHarness` / `tau_ai.OpenAICompatibleProvider` import paths this
+package uses, and the owned `tau-mcp` embeddable stdio MCP core. The `tau-ai`
+wheel also installs `tau_coding`'s files, but this package never imports or
+invokes `tau_coding` at runtime (the `tau_mcp.proxy` module is likewise not
+imported here because it is the Tau-extension flavor), and never launches a
+server — installing `ariadne-data` alone does not install the agent.
+
+Local development resolves `ariadne-data` from the repository checkout through
+`[tool.uv.sources]` in `pyproject.toml` (non-published tool configuration
+only; the published dependency metadata names the distribution); `tau-mcp`
+resolves the same way from its own repository checkout:
+
+```bash
+cd ariadne-agent && uv run pytest -q tests/test_analyst.py
+```
+
+## Use
+
+The host selects everything up front — project root, role, model, and a fully
+configured provider (model identity, endpoint and credentials are constructed
+outside user messages and data-project artifacts; the agent loads no global
+provider or MCP configuration):
+
+```python
+from ariadne_agent import AssistantText, ToolActivity, open_session
+from tau_ai import OpenAICompatibleProvider, OpenAICompatibleConfig
+
+provider = OpenAICompatibleProvider(OpenAICompatibleConfig(api_key=..., base_url=...))
+session = open_session(role="analyst", project="/path/to/project",
+                       model="your-model", provider=provider)
+async for event in session.send("gross margin by region?"):
+    match event:
+        case AssistantText(text=text):   print(text)
+        case ToolActivity(tool=tool):    print(f"[tool] {tool}")
+session.cancel()   # cooperative: ends subsequent model turns
+session.close()
+```
+
+## MCP (optional, role-restricted)
+
+Passing `mcp_settings` attaches ONE restricted MCP registry to that session,
+built from host-supplied configuration only — validated stdio server entries,
+a cache root, and each role's operator-approved qualified tool names. No
+`~/.tau/mcp.json` or any other ambient MCP configuration is ever loaded, and a
+model request can never alter server commands, the allowlist, or credentials:
+
+```python
+from ariadne_agent.mcp_tools import McpSettings
+from tau_mcp.config import ServerConfig
+
+mcp = McpSettings(
+    servers={"weather": ServerConfig(name="weather", command="...", args=(...))},
+    cache_root=Path("/var/cache/ariadne-mcp"),
+    role_tools={"analyst": ("weather__lookup",)},  # authoring absent => no MCP tools
+)
+session = open_session(role="analyst", ..., mcp_settings=mcp)
+```
+
+Permitted tools surface to the model as one `mcp` proxy tool (search and call
+by `server__tool` name); direct MCP registration stays a Tau extension and is
+not offered. The registry's frozen per-instance allowlist restricts discovery
+**and** dispatch, so a forbidden name the model supplies through the proxy is
+rejected before any spawn or call — the server never sees it. `close()` reaps
+every MCP child this session spawned; a call already executing finishes or
+times out under the MCP client's bounded request timeout (no immediate
+interruption is promised). Omit `mcp_settings` and the native tool surface is
+exactly as before.
+
+The project root selects one of the two runtime kinds (issue #38/G6): a
+**managed Git data project** — one carrying Ariadne's `.ariadne/` operator
+state — resolves through `QueryRuntime.open_project` and serves its pinned
+human-admitted snapshot (a missing admission is an explicit error naming the
+human `ariadne-admit` step, never a fallback to mutable files), while an
+**explicit legacy artifact-root project** must contain the served
+`semantic_layer/` and `context_layer/` directories and either a source
+registry (`ariadne.yaml`) or a `demo.db`; every path resolves against that
+root, never the ambient working directory. The legacy → new mapping lives in
+[docs/how-to/git-authoring.md](../docs/how-to/git-authoring.md).
+
+## Contract
+
+- **Typed async events**: assistant text, tool activity (verbatim JSON payload,
+  error flag), session errors, and run completion. Harness-internal event
+  types never leak through.
+- **One active run per session**; `send` while running raises. **Fixed**
+  role/project/model — a different one requires a new session, with no silent
+  transcript or tool-access transfer.
+- **In memory only**: a process restart loses the messages; there is no resume
+  operation, deliberately.
+- **Analyst tools** are exactly `ariadne.runtime.AriadneRuntime`'s six public
+  operations (`list_metrics`, `search_context`, `get_metric`, `list_datasets`,
+  `define_metric`, `resolve_term`) as thin native tools: values, Policy text
+  and citations, paths, and `governed` labels pass through verbatim. Term
+  resolution is read-only admitted-context guidance — an alias never
+  authorizes a join. No source approval, no promotion, no filesystem writes
+  beyond the runtime's own staging.
+- **Authoring tools** mirror `AuthoringProject`'s Git contract one-to-one —
+  `start_proposal`, `read_artifact`, `edit_proposal`, `propose_sources`,
+  `inputs`, `upload_document`, `validate_proposal`, `refresh_schema`,
+  `inspect_mapping`, `resolve_term`, `review_proposal` — with automatic
+  labeled-hypothesis saves through `edit_proposal` (no per-save prompt) and
+  restart-readable Git/evidence state. Source approval, admission,
+  reconciliation, legacy import/enrichment and Promotion are deliberately
+  absent: human-only, outside the agent.
+- **Guidance**: the version-matched packaged `ariadne/skill_assets/SKILL.md`
+  from the installed `ariadne-data`, plus a short native-tool mapping. No
+  global skill scans, no model-invocable skill scripts.
+- **Missing promoted catalog**: opening an Analyst session fails fast with an
+  actionable error naming the human step — Promotion for a legacy project,
+  `ariadne-admit` for a managed Git project. The failure is session-local — it
+  cannot block a later (e.g. Authoring) session.

ariadne_agent-0.2.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ariadne-agent"
+version = "0.2.0"
+description = "Installable Ariadne Agent backend: fixed-role conversations over native Ariadne tools"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    # Never bare `ariadne` — that is the unrelated PyPI GraphQL project (ADR-0014).
+    "ariadne-data>=0.2.0",
+    # The release whose embeddable tau_agent.AgentHarness / tau_ai.OpenAICompatibleProvider
+    # import paths were verified for this package (ADR-0014: pin what was tested).
+    "tau-ai==0.4.6",
+    # The owned embeddable stdio MCP core (spec 2026-09-29-0006; dependency
+    # contract legout/tau-mcp spec 2026-09-29-0002, accepted M2).
+    "tau-mcp>=0.1.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+]
+
+[tool.uv.sources]
+# Local development only: resolve ariadne-data from the repository checkout
+# without publishing it. This is uv tool configuration, never published
+# dependency metadata (issue #23).
+ariadne-data = { path = ".." }
+# Same non-published pattern for the owned tau-mcp core (issue #25): the
+# separate repository checkout, never a PyPI substitute.
+tau-mcp = { path = "/home/volker/coding/tau-mcp" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+extraPaths = ["..", "../src", "src"]
+executionEnvironments = [
+    { root = "tests", extraPaths = ["..", "../src", "src"] },
+    { root = "src", extraPaths = ["../src", "src"] },
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]

ariadne_agent-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ariadne_agent-0.2.0/src/ariadne_agent/__init__.py

@@ -0,0 +1,32 @@
+"""ariadne-agent: installable conversation backend over native Ariadne tools.
+
+A separately installable distribution (ADR-0014, spec 2026-09-29-0006): it
+depends on ``ariadne-data`` (never the unrelated PyPI ``ariadne`` GraphQL
+project) and ``tau-ai``, uses ``tau_agent.AgentHarness`` for the loop and
+``tau_ai`` providers for the model, and never imports or invokes ``tau_coding``
+at runtime, never launches a server, and never grants CLI, shell, or raw SQL
+tools. Analyst (issue #23) and Authoring (issue #24) roles in this revision;
+source approval and Promotion stay human-only, outside the agent.
+"""
+
+from ariadne_agent.session import (
+    ROLES,
+    AgentSession,
+    AgentSessionEvent,
+    AssistantText,
+    RunCompleted,
+    SessionError,
+    ToolActivity,
+    open_session,
+)
+
+__all__ = [
+    "ROLES",
+    "AgentSession",
+    "AgentSessionEvent",
+    "AssistantText",
+    "RunCompleted",
+    "SessionError",
+    "ToolActivity",
+    "open_session",
+]

ariadne_agent-0.2.0/src/ariadne_agent/analyst.py

@@ -0,0 +1,302 @@
+"""Analyst role tools: QueryRuntime's public operations as native tools.
+
+Thin wrappers only (spec 2026-09-29-0006 session/role interface): compilation,
+grain checks, read-only execution, context attachment, proposal staging and
+terminology resolution all live in ``ariadne-data``; nothing is reimplemented
+here. The tool set is DELIMITED to Ariadne's baseline query operations plus
+``resolve_term`` (issue #42/K2: shared terminology resolution over the pinned
+admitted context — read-only, no inspection/edit authority) and the two
+Context Layer browsing operations ``list_context_pages``/``read_context_page``
+(issue #60, spec 0015/ADR-0020: token-free listing and path-addressed reading
+of served and staged pages — read-only, draft-labeled): the wider Query
+surface that ariadne-data's MCP registrations expose (query_metrics/
+query_detail, Answer Examples) does NOT silently expand this session's
+permissions (issue #38/G6 — registrations are tool-surface separation).
+Which runtime the session wraps — a managed Git project's pinned admission through
+``QueryRuntime.open_project``, or an explicit legacy artifact root — is
+resolved once at session open by :func:`ariadne_agent.session._open_runtime`.
+Each tool's payload is the runtime's verbatim JSON envelope — values, served
+metric page, full Policy bodies and citations, staging paths, lifecycle
+``context_signals`` envelopes, and ``governed`` labels are never stripped or
+summarized. Runtime failures
+propagate with their verbatim message and are reported to the model as tool
+errors. No CLI, no shell, no server, no raw SQL, no source-approval,
+admission or Promotion tool.
+"""
+
+import json
+from collections.abc import Mapping
+
+from ariadne.query import QueryRuntime
+from tau_agent.messages import TextContent
+from tau_agent.tools import AgentTool, AgentToolResult, ToolExecutor
+
+TOOL_NAMES = (
+    "list_metrics",
+    "search_context",
+    "get_metric",
+    "list_datasets",
+    "define_metric",
+    "resolve_term",  # K2 (issue #42): alongside the five baseline tools
+    "list_context_pages",  # spec 0015 (issue #60): token-free page listing
+    "read_context_page",  # spec 0015 (issue #60): path-addressed page reading
+)
+
+
+def _payload(value: object) -> AgentToolResult:
+    """One verbatim JSON payload — the runtime envelope is the whole contract."""
+    return AgentToolResult(content=[TextContent(text=json.dumps(value, default=str))])
+
+
+def analyst_tools(runtime: QueryRuntime) -> list[AgentTool]:
+    """The Analyst tool set: Ariadne's five baseline query operations plus the
+    K2 read-only term resolver (issue #42) — nothing else."""
+
+    # Each wrapper mirrors the runtime's own signature and the routing language
+    # the ariadne-data MCP facade uses (spec rev 4 §8.12: fresh consuming agents
+    # discover the ad-hoc path through the facade itself).
+    async def list_metrics(
+        tool_call_id: str, arguments: Mapping, signal=None, on_update=None
+    ) -> AgentToolResult:
+        return _payload(await runtime.list_metrics())
+
+    async def search_context(
+        tool_call_id: str, arguments: Mapping, signal=None, on_update=None
+    ) -> AgentToolResult:
+        limit = arguments.get("limit", 10)
+        return _payload(await runtime.search_context(arguments["query"], limit))
+
+    async def get_metric(
+        tool_call_id: str, arguments: Mapping, signal=None, on_update=None
+    ) -> AgentToolResult:
+        return _payload(
+            await runtime.get_metric(
+                arguments["name"], arguments.get("dimensions"), arguments.get("range")
+            )
+        )
+
+    async def list_datasets(
+        tool_call_id: str, arguments: Mapping, signal=None, on_update=None
+    ) -> AgentToolResult:
+        return _payload(await runtime.list_datasets())
+
+    async def define_metric(
+        tool_call_id: str, arguments: Mapping, signal=None, on_update=None
+    ) -> AgentToolResult:
+        return _payload(await runtime.define_metric(arguments["definition"]))
+
+    async def resolve_term(
+        tool_call_id: str, arguments: Mapping, signal=None, on_update=None
+    ) -> AgentToolResult:
+        return _payload(
+            await runtime.resolve_term(arguments["request"], part=arguments.get("part", 1))
+        )
+
+    async def list_context_pages(
+        tool_call_id: str, arguments: Mapping, signal=None, on_update=None
+    ) -> AgentToolResult:
+        return _payload(await runtime.list_context_pages())
+
+    async def read_context_page(
+        tool_call_id: str, arguments: Mapping, signal=None, on_update=None
+    ) -> AgentToolResult:
+        return _payload(
+            await runtime.read_context_page(arguments["path"], draft=arguments.get("draft", False))
+        )
+
+    executor: dict[str, ToolExecutor] = {
+        "list_metrics": list_metrics,
+        "search_context": search_context,
+        "get_metric": get_metric,
+        "list_datasets": list_datasets,
+        "define_metric": define_metric,
+        "resolve_term": resolve_term,
+        "list_context_pages": list_context_pages,
+        "read_context_page": read_context_page,
+    }
+    descriptions = {
+        "list_metrics": (
+            "Governed metrics with descriptions and available dimensions; the list "
+            "ends with the explicit routing hint to the ad-hoc path. Start every "
+            "question here: if a governed metric answers it, query it governed."
+        ),
+        "search_context": (
+            "Search the Context Layer (OKF pages) for business rules; ranked "
+            "matches, each with its full page body. Search before any novel "
+            "question — the rule you are about to rediscover is probably already "
+            "a policy page. Includes auto-staged ad-hoc drafts, marked draft: true. "
+            "Each hit carries its page's context_signals advisory view (lifecycle "
+            "status, freshness, verification tier; a context_stale/context_deprecated "
+            "warning names that page)."
+        ),
+        "get_metric": (
+            "Rows plus compiled SQL for a named governed metric — never raw SQL. "
+            "The response carries a context field: the full served OKF metric "
+            "page plus the full bodies of every policy it cites. Report those "
+            "caveats and paths with every number. The context also carries a "
+            "context_signals advisory envelope whose warnings — context_stale "
+            "(reached expiry), context_deprecated (deprecated page), "
+            "context_unavailable (required metric/Policy context missing or "
+            "unreadable) — name consumed pages with lifecycle problems: when "
+            "the answer relies on warned context, add one brief caveat naming "
+            "the affected Policy/page. Absent optional expiry/verification "
+            "metadata is not a warning and needs no caveat; warnings never "
+            "change values, labels or permissions. The response also carries "
+            "a `data_signals` advisory view of SUPPLIED source-quality reports "
+            "on the metric's directly cited table pages (per-asset coverage; "
+            "per-report age/applicability/limitations, reported checks and "
+            "optional watermark; warnings such as data_report_failed/"
+            "data_report_expired): when the answer relies on an asset a "
+            "failed/expired report warning names, add ONE brief caveat naming "
+            "the report id and its as-of scope (reported outcome + report/"
+            "validity time). A supplied report is a claim reported as of its "
+            "observation/report time — never independent validation, execution "
+            "attestation or live source health; unknown applicability/partial "
+            "coverage stays unknown (a scope/version mismatch is never a "
+            "matching pass) and an event-time watermark is an event boundary, "
+            "not completeness or currency. Unrelated or absent optional "
+            "reports demand no caveat; data warnings never change values, "
+            "labels or permissions."
+        ),
+        "list_datasets": (
+            "List every queryable table in the attached sources with its columns "
+            "and types. Pairs with define_metric: pick tables here, then define "
+            "an ad-hoc metric for any question no governed metric answers. "
+            "Bounded RECORD selection (the latest N raw rows of one table, no "
+            "aggregation) is a separate operation this fixed toolset does not "
+            "expose — report such questions unsupported rather than aggregating "
+            "records away; ariadne-data's CLI/MCP facade serves it as query_records."
+        ),
+        "define_metric": (
+            "Define an ad-hoc metric for a question no governed metric answers: "
+            "compiled, executed read-only, auto-staged for human promotion. The "
+            "definition runs through the same compile/grain gate; success returns "
+            "rows, the compiled SQL, governed: false, and the staging paths of "
+            "the auto-staged proposal. Joins must be grain-preserving. This is an "
+            "AGGREGATION tool: a bounded record request (the latest N raw rows of "
+            "one table) is not a metric definition, and this fixed toolset has no "
+            "record operation — report record questions unsupported instead of "
+            "silently aggregating them; ariadne-data's CLI/MCP facade serves them as "
+            "query_records (governed: false, never staged)."
+        ),
+        "resolve_term": (
+            "Resolve a shared business term or an exact {resource, column} field "
+            "lookup against the admitted context: bounded concept/representation "
+            "matches with their exact field bindings, required scope, ambiguity "
+            "and claim/confirmation status (a mapping is confirmed ONLY by "
+            "recorded human admission evidence bound to the exact reviewed "
+            "assertion — hypotheses stay unconfirmed leads), plus the AS-OF "
+            "evidence freshness and page/source citations to report. Whole "
+            "aliases/phrases match case-insensitively, never substrings. "
+            "Read-only: a language alias never authorizes a join or "
+            "a transform."
+        ),
+        "list_context_pages": (
+            "List every Context Layer page — served and staged — without query "
+            "tokens: path, draft flag, title and each page's context_signals "
+            "advisory view, served before staged. Metadata only, never bodies. "
+            "The token-free discovery view for orientation and onboarding; "
+            "pair with read_context_page for full rule text."
+        ),
+        "read_context_page": (
+            "Read one exact Context Layer page by its bundle-relative POSIX path: "
+            "full content plus draft flag and context_signals. Follow "
+            "cross-references and known paths directly; staged drafts require "
+            "draft: true and are never verified guidance. An absolute, "
+            "escaping, non-markdown or unknown path is refused naming the path."
+        ),
+    }
+    schemas = {
+        "list_metrics": {"type": "object", "properties": {}, "additionalProperties": False},
+        "search_context": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string"},
+                "limit": {"type": "integer", "minimum": 1},
+            },
+            "required": ["query"],
+            "additionalProperties": False,
+        },
+        "get_metric": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "dimensions": {"type": "array", "items": {"type": "string"}},
+                "range": {
+                    "type": "object",
+                    "properties": {
+                        "start": {"type": "string"},
+                        "end": {"type": "string"},
+                    },
+                },
+            },
+            "required": ["name"],
+            "additionalProperties": False,
+        },
+        "list_datasets": {"type": "object", "properties": {}, "additionalProperties": False},
+        "define_metric": {
+            "type": "object",
+            "properties": {
+                "definition": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string"},
+                        "description": {"type": "string"},
+                        "source": {"type": "string"},
+                        "expression": {"type": "string"},
+                        "dimensions": {"type": "array", "items": {"type": "string"}},
+                        "time_field": {"type": "string"},
+                    },
+                    "required": ["name", "description", "source", "expression"],
+                }
+            },
+            "required": ["definition"],
+            "additionalProperties": False,
+        },
+        "resolve_term": {
+            "type": "object",
+            "properties": {
+                "request": {
+                    "anyOf": [
+                        {"type": "string", "minLength": 1},
+                        {
+                            "type": "object",
+                            "properties": {
+                                "resource": {"type": "string", "minLength": 1},
+                                "column": {"type": "string", "minLength": 1},
+                            },
+                            "required": ["resource", "column"],
+                            "additionalProperties": False,
+                        },
+                    ]
+                },
+                "part": {"type": "integer", "minimum": 1},
+            },
+            "required": ["request"],
+            "additionalProperties": False,
+        },
+        "list_context_pages": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        },
+        "read_context_page": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "minLength": 1},
+                "draft": {"type": "boolean"},
+            },
+            "required": ["path"],
+            "additionalProperties": False,
+        },
+    }
+    return [
+        AgentTool(
+            name=name,
+            label=name.replace("_", " ").title(),
+            description=descriptions[name],
+            parameters=schemas[name],
+            execute_fn=executor[name],
+        )
+        for name in TOOL_NAMES
+    ]