forgesight-clickhouse 0.1.0__tar.gz

forgesight_clickhouse-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# venv / tooling
+.venv/
+venv/
+.uv/
+uv.lock
+
+# test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# secrets / local env (never commit)
+.env
+.env.*
+
+# editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# local-only session working state (per the workspace pipeline)
+.claude/state/
+
+# local-only launch planning (not part of the published repo)
+/launch/

forgesight_clickhouse-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: forgesight-clickhouse
+Version: 0.1.0
+Summary: ForgeSight ClickHouse exporter — columnar batch insert of immutable records into a denormalized MergeTree.
+Project-URL: Homepage, https://github.com/Scaffoldic/forgesight
+Project-URL: Repository, https://github.com/Scaffoldic/forgesight
+Project-URL: Issues, https://github.com/Scaffoldic/forgesight/issues
+Project-URL: Changelog, https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md
+Author: kjoshi
+License-Expression: Apache-2.0
+Keywords: ai-agents,analytics,clickhouse,columnar,forgesight,observability
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: clickhouse-connect>=0.7
+Requires-Dist: forgesight-core
+Description-Content-Type: text/markdown
+
+# forgesight-clickhouse
+
+The ClickHouse exporter for [ForgeSight](https://github.com/Scaffoldic/forgesight).
+Writes each ForgeSight record as one row in a **denormalized single-table MergeTree**,
+batched columnar — so a platform team can *query* its agent telemetry in SQL: spend by
+team, p99 LLM latency by model, tokens per workflow over 90 days.
+
+```bash
+pip install forgesight-clickhouse
+```
+
+```python
+import forgesight
+from forgesight_clickhouse import ClickHouseExporter
+
+forgesight.configure(exporters=[
+    ClickHouseExporter(
+        dsn="clickhouse://user:pass@ch-host:8443/agents?secure=true",
+        table="agentforge_records",
+        create_table=True,   # dev convenience; production runs the shipped migration
+    ),
+])
+```
+
+Or by name: `exporters: [{name: clickhouse, config: {dsn: "${FORGESIGHT_CLICKHOUSE_DSN}"}}]`.
+
+## Why a columnar exporter
+
+A Record is written once and never updated (OTel's immutable span model), so trace-level
+**business metadata is denormalized onto every row** — no join table, so analytical
+queries never pay a join:
+
+```sql
+SELECT agent_name, quantile(0.99)(duration_ms)
+FROM agentforge_records WHERE kind = 'llm' GROUP BY agent_name;
+
+SELECT metadata.team, sum(cost_usd)
+FROM agentforge_records
+WHERE kind = 'llm' AND start_time >= now() - INTERVAL 30 DAY
+GROUP BY metadata.team;
+```
+
+Inserts are **batched** by the SDK's export pipeline (ClickHouse hates row-at-a-time): one
+columnar INSERT per batch, on the export worker, fault-isolated. A ClickHouse outage makes
+`export()` return `FAILURE` (counted, never raised — P6); it never blocks the agent.
+
+## Schema & migrations
+
+The DDL ships in the package (`migrations/0001_init.sql`). `create_table=True` runs
+`CREATE TABLE IF NOT EXISTS` on first export for dev; production applies the migration
+out-of-band. New domain fields arrive as new nullable columns via numbered migrations —
+old queries keep working.
+
+## Configuration
+
+| Key | Env | Default |
+|---|---|---|
+| `dsn` | `FORGESIGHT_CLICKHOUSE_DSN` | — (required) |
+| `table` | `FORGESIGHT_CLICKHOUSE_TABLE` | `agentforge_records` |
+| `batch_size` | `FORGESIGHT_CLICKHOUSE_BATCH_SIZE` | `512` (clamped to the pipeline max) |
+| `async_insert` | `FORGESIGHT_CLICKHOUSE_ASYNC_INSERT` | `true` |
+| `wait_for_async_insert` | `FORGESIGHT_CLICKHOUSE_WAIT_ASYNC` | `false` |
+| `create_table` | `FORGESIGHT_CLICKHOUSE_CREATE_TABLE` | `false` |
+
+Constructor kwargs win over env (FR-12). Prompt/response **content is never stored** in
+the base table; it is gated SDK-wide by `capture_content` (off by default, P7).
+
+## License
+
+Apache-2.0

forgesight_clickhouse-0.1.0/README.md

@@ -0,0 +1,70 @@
+# forgesight-clickhouse
+
+The ClickHouse exporter for [ForgeSight](https://github.com/Scaffoldic/forgesight).
+Writes each ForgeSight record as one row in a **denormalized single-table MergeTree**,
+batched columnar — so a platform team can *query* its agent telemetry in SQL: spend by
+team, p99 LLM latency by model, tokens per workflow over 90 days.
+
+```bash
+pip install forgesight-clickhouse
+```
+
+```python
+import forgesight
+from forgesight_clickhouse import ClickHouseExporter
+
+forgesight.configure(exporters=[
+    ClickHouseExporter(
+        dsn="clickhouse://user:pass@ch-host:8443/agents?secure=true",
+        table="agentforge_records",
+        create_table=True,   # dev convenience; production runs the shipped migration
+    ),
+])
+```
+
+Or by name: `exporters: [{name: clickhouse, config: {dsn: "${FORGESIGHT_CLICKHOUSE_DSN}"}}]`.
+
+## Why a columnar exporter
+
+A Record is written once and never updated (OTel's immutable span model), so trace-level
+**business metadata is denormalized onto every row** — no join table, so analytical
+queries never pay a join:
+
+```sql
+SELECT agent_name, quantile(0.99)(duration_ms)
+FROM agentforge_records WHERE kind = 'llm' GROUP BY agent_name;
+
+SELECT metadata.team, sum(cost_usd)
+FROM agentforge_records
+WHERE kind = 'llm' AND start_time >= now() - INTERVAL 30 DAY
+GROUP BY metadata.team;
+```
+
+Inserts are **batched** by the SDK's export pipeline (ClickHouse hates row-at-a-time): one
+columnar INSERT per batch, on the export worker, fault-isolated. A ClickHouse outage makes
+`export()` return `FAILURE` (counted, never raised — P6); it never blocks the agent.
+
+## Schema & migrations
+
+The DDL ships in the package (`migrations/0001_init.sql`). `create_table=True` runs
+`CREATE TABLE IF NOT EXISTS` on first export for dev; production applies the migration
+out-of-band. New domain fields arrive as new nullable columns via numbered migrations —
+old queries keep working.
+
+## Configuration
+
+| Key | Env | Default |
+|---|---|---|
+| `dsn` | `FORGESIGHT_CLICKHOUSE_DSN` | — (required) |
+| `table` | `FORGESIGHT_CLICKHOUSE_TABLE` | `agentforge_records` |
+| `batch_size` | `FORGESIGHT_CLICKHOUSE_BATCH_SIZE` | `512` (clamped to the pipeline max) |
+| `async_insert` | `FORGESIGHT_CLICKHOUSE_ASYNC_INSERT` | `true` |
+| `wait_for_async_insert` | `FORGESIGHT_CLICKHOUSE_WAIT_ASYNC` | `false` |
+| `create_table` | `FORGESIGHT_CLICKHOUSE_CREATE_TABLE` | `false` |
+
+Constructor kwargs win over env (FR-12). Prompt/response **content is never stored** in
+the base table; it is gated SDK-wide by `capture_content` (off by default, P7).
+
+## License
+
+Apache-2.0

forgesight_clickhouse-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "forgesight-clickhouse"
+version = "0.1.0"
+description = "ForgeSight ClickHouse exporter — columnar batch insert of immutable records into a denormalized MergeTree."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "kjoshi" }]
+keywords = ["observability", "clickhouse", "analytics", "ai-agents", "forgesight", "columnar"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Topic :: System :: Monitoring",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["forgesight-core", "clickhouse-connect>=0.7"]
+
+[project.entry-points."forgesight.exporters"]
+clickhouse = "forgesight_clickhouse.exporter:ClickHouseExporter"
+
+[project.urls]
+Homepage = "https://github.com/Scaffoldic/forgesight"
+Repository = "https://github.com/Scaffoldic/forgesight"
+Issues = "https://github.com/Scaffoldic/forgesight/issues"
+Changelog = "https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forgesight_clickhouse"]
+
+[tool.uv.sources]
+forgesight-core = { workspace = true }

forgesight_clickhouse-0.1.0/src/forgesight_clickhouse/__init__.py

@@ -0,0 +1,17 @@
+"""ForgeSight ClickHouse exporter — columnar batch insert into a denormalized MergeTree."""
+
+from __future__ import annotations
+
+from .exporter import COLUMNS, ClickHouseClient, ClickHouseExporter
+from .testing import InMemoryClickHouseClient, InsertCall
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "COLUMNS",
+    "ClickHouseClient",
+    "ClickHouseExporter",
+    "InMemoryClickHouseClient",
+    "InsertCall",
+    "__version__",
+]

forgesight_clickhouse-0.1.0/src/forgesight_clickhouse/exporter.py

@@ -0,0 +1,297 @@
+"""``ClickHouseExporter`` — columnar batch insert of immutable records into ClickHouse.
+
+A :class:`~forgesight_api.TelemetryExporter` (so it resolves via the
+``forgesight.exporters`` entry point and passes the conformance suite) that writes each
+:class:`~forgesight_api.Record` as one row in a **denormalized single-table MergeTree**.
+Because a Record is written once and never updated (OTel's immutable span model),
+trace-level business metadata is denormalized onto every row — no join table, so
+analytical queries (``sum(cost_usd) GROUP BY team``) never pay a join.
+
+It runs on the export worker (feat-003), never the hot path: ``export()`` receives a
+batch already sized by the pipeline and issues **one** columnar INSERT per ``batch_size``
+chunk. ``export`` never raises (P6): a ClickHouse outage returns ``ExportResult.FAILURE``,
+counted by the pipeline, invisible to the agent.
+
+The vendor driver (``clickhouse-connect``) is imported lazily and built from the DSN on
+first export, so construction never touches the network. Tests inject a client double
+(:class:`~forgesight_clickhouse.testing.InMemoryClickHouseClient`).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from collections.abc import Mapping, Sequence
+from importlib.resources import files
+from typing import Protocol, cast, runtime_checkable
+
+from forgesight_api import ExportResult, Kind, Record, RunStatus
+
+_log = logging.getLogger("forgesight.clickhouse")
+
+DEFAULT_TABLE = "agentforge_records"
+DEFAULT_BATCH_SIZE = 512
+DEFAULT_MAX_EXPORT_BATCH_SIZE = 512  # pipeline default (exporter-pipeline.md §4.8)
+
+# operation.name values (gen_ai.operation.name) — kept local; no forgesight-otel dep (P1)
+_OP_INVOKE_AGENT = "invoke_agent"
+_OP_INVOKE_WORKFLOW = "invoke_workflow"
+_OP_CHAT = "chat"
+_OP_EXECUTE_TOOL = "execute_tool"
+_MCP_TOOLS_CALL = "tools/call"
+
+# structured keys feat-002 stashes in Record.attributes — lifted to their own columns,
+# so they are not duplicated into the denormalized `metadata` JSON blob.
+_AGENT_VERSION_KEY = "agent.version"
+_PARENT_RUN_ID_KEY = "parent.run_id"
+_CONTEXT_ID_KEY = "context.id"
+_STRUCTURED_KEYS = frozenset({_AGENT_VERSION_KEY, _PARENT_RUN_ID_KEY, _CONTEXT_ID_KEY})
+
+_OK_STATUSES = frozenset({RunStatus.OK, RunStatus.RUNNING})
+_ENV_PREFIX = "FORGESIGHT_CLICKHOUSE_"
+# table name (optionally db-qualified), validated to keep it out of the INSERT verbatim.
+_IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$")
+
+# Column order — must match migrations/0001_init.sql exactly.
+COLUMNS: tuple[str, ...] = (
+    "run_id",
+    "trace_id",
+    "parent_run_id",
+    "context_id",
+    "kind",
+    "op",
+    "agent_name",
+    "agent_version",
+    "provider",
+    "model",
+    "tool_name",
+    "mcp_server",
+    "mcp_method",
+    "input_tokens",
+    "output_tokens",
+    "cache_read_tokens",
+    "cache_creation_tokens",
+    "reasoning_tokens",
+    "total_tokens",
+    "cost_usd",
+    "status",
+    "error_type",
+    "start_time",
+    "end_time",
+    "duration_ms",
+    "metadata",
+)
+
+
+@runtime_checkable
+class ClickHouseClient(Protocol):
+    """The slice of the ``clickhouse-connect`` client this exporter uses."""
+
+    def insert(
+        self,
+        table: str,
+        data: Sequence[Sequence[object]],
+        *,
+        column_names: Sequence[str],
+        settings: Mapping[str, object],
+    ) -> object: ...
+
+    def command(self, statement: str) -> object: ...
+
+    def close(self) -> None: ...
+
+
+def _env(key: str) -> str | None:
+    return os.environ.get(f"{_ENV_PREFIX}{key}")
+
+
+def _env_bool(key: str, default: bool) -> bool:
+    raw = _env(key)
+    if raw is None:
+        return default
+    return raw.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _env_int(key: str, default: int) -> int:
+    raw = _env(key)
+    return int(raw) if raw is not None else default
+
+
+def _op(record: Record) -> str:
+    kind = record.kind
+    if kind is Kind.AGENT:
+        return _OP_INVOKE_AGENT
+    if kind is Kind.WORKFLOW:
+        return _OP_INVOKE_WORKFLOW
+    if kind is Kind.LLM:
+        return _OP_CHAT
+    if kind is Kind.TOOL:
+        return _OP_EXECUTE_TOOL
+    if kind is Kind.MCP and record.mcp is not None and record.mcp.method == _MCP_TOOLS_CALL:
+        return _OP_EXECUTE_TOOL
+    return ""  # STEP, or a non-tools/call MCP method: no GenAI operation
+
+
+def _error_type(record: Record) -> str | None:
+    if record.error is not None:
+        return record.error.error_type
+    if record.status not in _OK_STATUSES:
+        return record.status.value
+    return None
+
+
+def _chunks(rows: list[list[object]], size: int) -> list[list[list[object]]]:
+    return [rows[i : i + size] for i in range(0, len(rows), size)]
+
+
+class ClickHouseExporter:
+    """Columnar batch insert of immutable Records into a denormalized MergeTree table."""
+
+    def __init__(
+        self,
+        *,
+        dsn: str | None = None,
+        table: str | None = None,
+        batch_size: int | None = None,
+        async_insert: bool | None = None,
+        wait_for_async_insert: bool | None = None,
+        create_table: bool | None = None,
+        max_export_batch_size: int = DEFAULT_MAX_EXPORT_BATCH_SIZE,
+        client: ClickHouseClient | None = None,
+    ) -> None:
+        self._dsn = dsn if dsn is not None else _env("DSN")
+        self._client = client
+        if self._client is None and not self._dsn:
+            raise ValueError(
+                "ClickHouseExporter requires a dsn (or FORGESIGHT_CLICKHOUSE_DSN), "
+                "e.g. clickhouse://user:pass@host:8443/db"
+            )
+
+        self._table = table if table is not None else (_env("TABLE") or DEFAULT_TABLE)
+        if not _IDENT.match(self._table):
+            raise ValueError(f"invalid ClickHouse table identifier {self._table!r}")
+
+        size = batch_size if batch_size is not None else _env_int("BATCH_SIZE", DEFAULT_BATCH_SIZE)
+        if size < 1:
+            raise ValueError(f"batch_size must be >= 1, got {size}")
+        if size > max_export_batch_size:
+            _log.warning(
+                "batch_size %d exceeds pipeline max_export_batch_size %d; clamping",
+                size,
+                max_export_batch_size,
+            )
+            size = max_export_batch_size
+        self._batch_size = size
+
+        self._async_insert = (
+            async_insert if async_insert is not None else _env_bool("ASYNC_INSERT", True)
+        )
+        self._wait = (
+            wait_for_async_insert
+            if wait_for_async_insert is not None
+            else _env_bool("WAIT_ASYNC", False)
+        )
+        self._create_table = (
+            create_table if create_table is not None else _env_bool("CREATE_TABLE", False)
+        )
+        self._table_ready = False
+
+    # --- TelemetryExporter Protocol --------------------------------------
+    def export(self, records: Sequence[Record]) -> ExportResult:
+        if not records:
+            return ExportResult.SUCCESS
+        try:
+            client = self._get_client()
+            self._ensure_table(client)
+            rows = [self._to_row(record) for record in records]
+            settings: dict[str, object] = {
+                "async_insert": 1 if self._async_insert else 0,
+                "wait_for_async_insert": 1 if self._wait else 0,
+            }
+            for chunk in _chunks(rows, self._batch_size):
+                client.insert(self._table, chunk, column_names=COLUMNS, settings=settings)
+        except Exception:  # export must never raise (P6) — a CH outage is counted, not raised
+            _log.warning("clickhouse export failed", exc_info=True)
+            return ExportResult.FAILURE
+        return ExportResult.SUCCESS
+
+    def force_flush(self, timeout_millis: int = 30_000) -> bool:
+        # No client-side buffer: rows are handed to the server per export(); with
+        # async_insert the server owns the buffer. Nothing to flush, so this can't fail.
+        return True
+
+    def shutdown(self, timeout_millis: int = 30_000) -> None:
+        client = self._client
+        if client is None:
+            return
+        try:
+            client.close()
+        except Exception:  # pragma: no cover - best-effort close, must never raise
+            _log.warning("clickhouse client close failed", exc_info=True)
+
+    # --- internals --------------------------------------------------------
+    def _get_client(self) -> ClickHouseClient:
+        if self._client is None:
+            import clickhouse_connect  # type: ignore[import-untyped]  # pragma: no cover
+
+            self._client = cast(  # pragma: no cover
+                ClickHouseClient, clickhouse_connect.get_client(dsn=self._dsn)
+            )
+        return self._client
+
+    def _ensure_table(self, client: ClickHouseClient) -> None:
+        if self._table_ready:
+            return
+        if self._create_table:
+            client.command(_load_ddl(self._table))
+        self._table_ready = True
+
+    def _to_row(self, record: Record) -> list[object]:
+        attrs = record.attributes
+        llm = record.llm
+        tool = record.tool
+        mcp = record.mcp
+        usage = llm.usage if llm is not None else None
+        metadata = {key: value for key, value in attrs.items() if key not in _STRUCTURED_KEYS}
+        return [
+            record.run_id,
+            record.trace_id,
+            _opt_str(attrs.get(_PARENT_RUN_ID_KEY)),
+            _opt_str(attrs.get(_CONTEXT_ID_KEY)),
+            record.kind.value,
+            _op(record),
+            record.name if record.kind is Kind.AGENT else "",
+            _opt_str(attrs.get(_AGENT_VERSION_KEY)),
+            llm.provider if llm is not None else None,
+            (llm.response_model or llm.request_model) if llm is not None else None,
+            tool.name if tool is not None else (mcp.tool if mcp is not None else None),
+            mcp.server if mcp is not None else None,
+            mcp.method if mcp is not None else None,
+            usage.input if usage is not None else None,
+            usage.output if usage is not None else None,
+            usage.cache_read if usage is not None else None,
+            usage.cache_creation if usage is not None else None,
+            usage.reasoning if usage is not None else None,
+            usage.total if usage is not None else None,
+            llm.cost_usd if llm is not None else None,
+            record.status.value,
+            _error_type(record),
+            record.start_unix_nanos,
+            record.end_unix_nanos,
+            record.duration_ms,
+            json.dumps(metadata, default=str, sort_keys=True),
+        ]
+
+
+def _opt_str(value: object) -> str | None:
+    return None if value is None else str(value)
+
+
+def _load_ddl(table: str) -> str:
+    """Read the shipped DDL, retargeted at ``table`` (default ``agentforge_records``)."""
+    sql = (files("forgesight_clickhouse") / "migrations" / "0001_init.sql").read_text(
+        encoding="utf-8"
+    )
+    return sql.replace(DEFAULT_TABLE, table) if table != DEFAULT_TABLE else sql

forgesight_clickhouse-0.1.0/src/forgesight_clickhouse/migrations/0001_init.sql

@@ -0,0 +1,37 @@
+-- forgesight-clickhouse — initial schema (feat-014).
+--
+-- One denormalized, immutable, MergeTree table: a Record is written once and never
+-- updated, so trace-level business metadata is denormalized onto every row (no join
+-- table, so analytical queries never pay a join). `${TABLE}` is substituted by the
+-- exporter with the configured table name (default `agentforge_records`).
+CREATE TABLE IF NOT EXISTS agentforge_records (
+    run_id           String,                       -- ULID
+    trace_id         String,                       -- W3C trace id
+    parent_run_id    Nullable(String),
+    context_id       Nullable(String),
+    kind             LowCardinality(String),       -- workflow|agent|step|llm|tool|mcp
+    op               LowCardinality(String),       -- gen_ai.operation.name (chat|execute_tool|…)
+    agent_name       LowCardinality(String),
+    agent_version    Nullable(String),
+    provider         LowCardinality(Nullable(String)),  -- gen_ai.provider.name
+    model            LowCardinality(Nullable(String)),  -- request/response model
+    tool_name        Nullable(String),
+    mcp_server       Nullable(String),
+    mcp_method       LowCardinality(Nullable(String)),
+    input_tokens     Nullable(UInt32),
+    output_tokens    Nullable(UInt32),
+    cache_read_tokens     Nullable(UInt32),
+    cache_creation_tokens Nullable(UInt32),
+    reasoning_tokens Nullable(UInt32),
+    total_tokens     Nullable(UInt32),
+    cost_usd         Nullable(Float64),            -- forgesight.usage.cost_usd
+    status           LowCardinality(String),       -- running|ok|error|cancelled|budget_exceeded|guardrail
+    error_type       Nullable(String),
+    start_time       DateTime64(9),                -- start_unix_nanos
+    end_time         Nullable(DateTime64(9)),
+    duration_ms      Nullable(Float64),
+    metadata         JSON                          -- denormalized business metadata (FR-5)
+)
+ENGINE = MergeTree
+PARTITION BY toYYYYMM(start_time)
+ORDER BY (trace_id, start_time, run_id);

forgesight_clickhouse-0.1.0/src/forgesight_clickhouse/testing.py

@@ -0,0 +1,73 @@
+"""A client double for testing the ClickHouse exporter without a live server.
+
+:class:`InMemoryClickHouseClient` satisfies the ``ClickHouseClient`` protocol and records
+every INSERT / command so a test (or a consuming team's pipeline test) can assert the rows,
+the column order, the per-insert settings, and that a batch became **one** columnar INSERT —
+never row-at-a-time.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class InsertCall:
+    """One captured ``insert()`` — a whole pipeline batch as a single columnar INSERT."""
+
+    table: str
+    rows: list[list[object]]
+    column_names: list[str]
+    settings: dict[str, object]
+
+
+class InMemoryClickHouseClient:
+    """In-memory stand-in for a ``clickhouse-connect`` client. For tests/local inspection."""
+
+    def __init__(self) -> None:
+        self.inserts: list[InsertCall] = []
+        self.commands: list[str] = []
+        self.closed = False
+
+    def insert(
+        self,
+        table: str,
+        data: Sequence[Sequence[object]],
+        *,
+        column_names: Sequence[str],
+        settings: Mapping[str, object],
+    ) -> object:
+        self.inserts.append(
+            InsertCall(
+                table=table,
+                rows=[list(row) for row in data],
+                column_names=list(column_names),
+                settings=dict(settings),
+            )
+        )
+        return None
+
+    def command(self, statement: str) -> object:
+        self.commands.append(statement)
+        return None
+
+    def close(self) -> None:
+        self.closed = True
+
+    # --- convenience accessors -------------------------------------------
+    @property
+    def rows(self) -> list[list[object]]:
+        """Every inserted row across all INSERTs, in arrival order."""
+        return [row for call in self.inserts for row in call.rows]
+
+    def rows_as_dicts(self) -> list[dict[str, object]]:
+        """Rows zipped with their column names — for readable assertions."""
+        out: list[dict[str, object]] = []
+        for call in self.inserts:
+            for row in call.rows:
+                out.append(dict(zip(call.column_names, row, strict=True)))
+        return out
+
+
+__all__ = ["InMemoryClickHouseClient", "InsertCall"]

forgesight_clickhouse-0.1.0/tests/test_exporter.py

@@ -0,0 +1,376 @@
+"""Tests for the ClickHouse exporter: mapping, denormalization, batching, conformance."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from forgesight_api import (
+    ErrorInfo,
+    ExportResult,
+    Kind,
+    LLMCall,
+    MCPCall,
+    Record,
+    RunStatus,
+    TokenUsage,
+    ToolCall,
+)
+from forgesight_clickhouse import ClickHouseExporter, InMemoryClickHouseClient
+from forgesight_clickhouse.exporter import COLUMNS, _load_ddl
+from forgesight_core import configure, reset_runtime, telemetry
+from forgesight_core.testing.conformance import run_exporter_conformance
+
+TRACE = "4bf92f3577b34da6a3ce929d0e0e4736"
+DSN = "clickhouse://user:pass@host:8443/agents"
+
+
+def _exporter(**kw: object) -> tuple[ClickHouseExporter, InMemoryClickHouseClient]:
+    client = InMemoryClickHouseClient()
+    return ClickHouseExporter(client=client, **kw), client
+
+
+def _llm_record(span: str = "00f067aa0ba902b7") -> Record:
+    return Record(
+        kind=Kind.LLM,
+        run_id="01J9Z3K7P8QF2R5V6W7X8Y9Z0A",
+        trace_id=TRACE,
+        span_id=span,
+        parent_span_id="aaaaaaaaaaaaaaaa",
+        name="claude-sonnet-4-5",
+        status=RunStatus.OK,
+        start_unix_nanos=1_000_000_000,
+        end_unix_nanos=3_000_000_000,
+        llm=LLMCall(
+            provider="anthropic",
+            request_model="claude-sonnet-4-5",
+            response_model="claude-sonnet-4-5-20990101",
+            usage=TokenUsage(input=100, output=50, cache_read=10, reasoning=5),
+            cost_usd=0.01,
+        ),
+    )
+
+
+# --- construction / validation ------------------------------------------------
+def test_requires_dsn_or_client() -> None:
+    with pytest.raises(ValueError, match="requires a dsn"):
+        ClickHouseExporter()
+
+
+def test_invalid_table_rejected() -> None:
+    with pytest.raises(ValueError, match="invalid ClickHouse table"):
+        ClickHouseExporter(dsn=DSN, table="bad table; DROP")
+
+
+def test_batch_size_must_be_positive() -> None:
+    with pytest.raises(ValueError, match="batch_size must be"):
+        ClickHouseExporter(dsn=DSN, batch_size=0)
+
+
+def test_batch_size_clamped_to_pipeline_max(caplog: pytest.LogCaptureFixture) -> None:
+    exporter, _ = _exporter(batch_size=5000, max_export_batch_size=512)
+    assert exporter._batch_size == 512
+    assert any("clamping" in r.message for r in caplog.records)
+
+
+# --- conformance --------------------------------------------------------------
+def test_conformance() -> None:
+    run_exporter_conformance(lambda: ClickHouseExporter(client=InMemoryClickHouseClient()))
+
+
+# --- record → column mapping --------------------------------------------------
+def test_llm_record_maps_to_columns() -> None:
+    exporter, client = _exporter()
+    assert exporter.export([_llm_record()]) is ExportResult.SUCCESS
+    [row] = client.rows_as_dicts()
+    assert row["kind"] == "llm"
+    assert row["op"] == "chat"
+    assert row["provider"] == "anthropic"
+    assert row["model"] == "claude-sonnet-4-5-20990101"  # response model wins
+    assert row["input_tokens"] == 100
+    assert row["output_tokens"] == 50
+    assert row["cache_read_tokens"] == 10
+    assert row["reasoning_tokens"] == 5
+    assert row["total_tokens"] == 165
+    assert row["cost_usd"] == 0.01  # forgesight.usage.cost_usd
+    assert row["status"] == "ok"
+    assert row["start_time"] == 1_000_000_000
+    assert row["end_time"] == 3_000_000_000
+    assert row["duration_ms"] == 2000.0
+
+
+def test_tool_and_mcp_and_step_mapping() -> None:
+    exporter, client = _exporter()
+    tool = Record(
+        kind=Kind.TOOL,
+        run_id="r",
+        trace_id=TRACE,
+        span_id="1111111111111111",
+        parent_span_id=None,
+        name="search",
+        status=RunStatus.OK,
+        start_unix_nanos=1,
+        end_unix_nanos=2,
+        tool=ToolCall(name="search"),
+    )
+    mcp = Record(
+        kind=Kind.MCP,
+        run_id="r",
+        trace_id=TRACE,
+        span_id="2222222222222222",
+        parent_span_id=None,
+        name="tools/call",
+        status=RunStatus.OK,
+        start_unix_nanos=1,
+        end_unix_nanos=2,
+        mcp=MCPCall(server="files", method="tools/call", tool="read_file"),
+    )
+    step = Record(
+        kind=Kind.STEP,
+        run_id="r",
+        trace_id=TRACE,
+        span_id="3333333333333333",
+        parent_span_id=None,
+        name="react-1",
+        status=RunStatus.OK,
+        start_unix_nanos=1,
+        end_unix_nanos=2,
+    )
+    exporter.export([tool, mcp, step])
+    by_kind = {row["kind"]: row for row in client.rows_as_dicts()}
+    assert by_kind["tool"]["tool_name"] == "search"
+    assert by_kind["tool"]["op"] == "execute_tool"
+    assert by_kind["mcp"]["mcp_server"] == "files"
+    assert by_kind["mcp"]["mcp_method"] == "tools/call"
+    assert by_kind["mcp"]["tool_name"] == "read_file"  # tools/call lifts the tool name
+    assert by_kind["mcp"]["op"] == "execute_tool"
+    assert by_kind["step"]["op"] == ""  # a step has no GenAI operation
+    assert by_kind["step"]["tool_name"] is None
+
+
+def test_error_record_carries_error_type() -> None:
+    exporter, client = _exporter()
+    rec = Record(
+        kind=Kind.AGENT,
+        run_id="r",
+        trace_id=TRACE,
+        span_id="4444444444444444",
+        parent_span_id=None,
+        name="classifier",
+        status=RunStatus.ERROR,
+        start_unix_nanos=1,
+        end_unix_nanos=2,
+    )
+    exporter.export([rec])
+    [row] = client.rows_as_dicts()
+    assert row["status"] == "error"
+    assert row["error_type"] == "error"  # status fallback when no ErrorInfo
+
+
+def test_error_info_error_type_wins_over_status() -> None:
+    exporter, client = _exporter()
+    rec = Record(
+        kind=Kind.TOOL,
+        run_id="r",
+        trace_id=TRACE,
+        span_id="5555555555555555",
+        parent_span_id=None,
+        name="search",
+        status=RunStatus.ERROR,
+        start_unix_nanos=1,
+        end_unix_nanos=2,
+        tool=ToolCall(name="search", status=RunStatus.ERROR),
+        error=ErrorInfo(error_type="TimeoutError", message="boom"),
+    )
+    exporter.export([rec])
+    [row] = client.rows_as_dicts()
+    assert row["error_type"] == "TimeoutError"  # ErrorInfo wins over the status fallback
+
+
+def test_workflow_record_maps_op() -> None:
+    exporter, client = _exporter()
+    rec = Record(
+        kind=Kind.WORKFLOW,
+        run_id="r",
+        trace_id=TRACE,
+        span_id="6666666666666666",
+        parent_span_id=None,
+        name="nightly",
+        status=RunStatus.OK,
+        start_unix_nanos=1,
+        end_unix_nanos=2,
+    )
+    exporter.export([rec])
+    [row] = client.rows_as_dicts()
+    assert row["op"] == "invoke_workflow"
+    assert row["agent_name"] == ""  # only AGENT records carry an agent name
+    assert client.rows[0][0] == "r"  # raw-row accessor: run_id is the first column
+
+
+# --- denormalization (the headline) ------------------------------------------
+def test_business_metadata_denormalized_onto_child_rows() -> None:
+    exporter, client = _exporter()
+    configure(exporters=[exporter], sync_export=True)
+    try:
+        with telemetry.agent_run("classifier", version="1.2.0") as run:
+            run.set_metadata(team="payments")
+            with run.llm_call("anthropic", "claude-sonnet-4-5") as call:
+                call.record_usage(input=1000, output=500)
+    finally:
+        reset_runtime()
+
+    rows = client.rows_as_dicts()
+    assert rows, "expected exported rows"
+    # every row — run AND the child llm call — carries the denormalized team
+    for row in rows:
+        meta = json.loads(str(row["metadata"]))
+        assert meta["team"] == "payments"
+    agent_row = next(r for r in rows if r["kind"] == "agent")
+    assert agent_row["agent_name"] == "classifier"
+    assert agent_row["agent_version"] == "1.2.0"
+    # the structured fields are lifted to columns, not duplicated into metadata JSON
+    assert "agent.version" not in json.loads(str(agent_row["metadata"]))
+
+
+def test_parent_run_id_and_context_id_lift_to_columns() -> None:
+    exporter, client = _exporter()
+    configure(exporters=[exporter], sync_export=True)
+    try:
+        with (
+            telemetry.agent_run("outer"),
+            telemetry.agent_run("inner", context_id="conv-7"),
+        ):
+            pass
+    finally:
+        reset_runtime()
+    inner = next(r for r in client.rows_as_dicts() if r["agent_name"] == "inner")
+    assert inner["context_id"] == "conv-7"
+    assert inner["parent_run_id"] is not None
+
+
+# --- batching -----------------------------------------------------------------
+def test_one_insert_per_batch_not_row_at_a_time() -> None:
+    exporter, client = _exporter()
+    exporter.export([_llm_record(span=f"{i:016x}") for i in range(50)])
+    assert len(client.inserts) == 1  # one columnar INSERT for the whole batch
+    assert len(client.inserts[0].rows) == 50
+    assert client.inserts[0].column_names == list(COLUMNS)
+
+
+def test_oversized_batch_chunks_by_batch_size() -> None:
+    exporter, client = _exporter(batch_size=10, max_export_batch_size=512)
+    exporter.export([_llm_record(span=f"{i:016x}") for i in range(25)])
+    assert [len(c.rows) for c in client.inserts] == [10, 10, 5]
+
+
+def test_async_insert_settings_passed() -> None:
+    exporter, client = _exporter(async_insert=True, wait_for_async_insert=False)
+    exporter.export([_llm_record()])
+    settings = client.inserts[0].settings
+    assert settings["async_insert"] == 1
+    assert settings["wait_for_async_insert"] == 0
+
+
+def test_empty_batch_is_a_noop() -> None:
+    exporter, client = _exporter()
+    assert exporter.export([]) is ExportResult.SUCCESS
+    assert client.inserts == []
+
+
+# --- create_table / migrations ------------------------------------------------
+def test_create_table_runs_ddl_once() -> None:
+    exporter, client = _exporter(create_table=True)
+    exporter.export([_llm_record()])
+    exporter.export([_llm_record()])
+    assert len(client.commands) == 1  # DDL emitted once, on first export
+    assert "CREATE TABLE IF NOT EXISTS agentforge_records" in client.commands[0]
+
+
+def test_create_table_false_emits_no_ddl() -> None:
+    exporter, client = _exporter(create_table=False)
+    exporter.export([_llm_record()])
+    assert client.commands == []
+
+
+def test_load_ddl_retargets_table_name() -> None:
+    sql = _load_ddl("custom_records")
+    assert "CREATE TABLE IF NOT EXISTS custom_records" in sql
+    assert "agentforge_records" not in sql
+    # column contract intact after retarget
+    assert "cost_usd" in sql
+    assert "ORDER BY (trace_id, start_time, run_id)" in sql
+
+
+def test_custom_table_used_in_insert_and_ddl() -> None:
+    exporter, client = _exporter(table="my_db.records", create_table=True)
+    exporter.export([_llm_record()])
+    assert client.inserts[0].table == "my_db.records"
+    assert "my_db.records" in client.commands[0]
+
+
+# --- fault isolation (P6) -----------------------------------------------------
+class _FailingClient:
+    def __init__(self) -> None:
+        self.closed = False
+
+    def insert(self, *args: object, **kwargs: object) -> object:
+        raise ConnectionError("clickhouse unreachable")
+
+    def command(self, statement: str) -> object:
+        raise ConnectionError("clickhouse unreachable")
+
+    def close(self) -> None:
+        self.closed = True
+
+
+def test_clickhouse_outage_is_isolated() -> None:
+    exporter = ClickHouseExporter(client=_FailingClient())
+    assert exporter.export([_llm_record()]) is ExportResult.FAILURE  # counted, never raised
+
+
+# --- lifecycle ----------------------------------------------------------------
+def test_shutdown_closes_client_and_is_idempotent() -> None:
+    exporter, client = _exporter()
+    exporter.shutdown()
+    assert client.closed is True
+    exporter.shutdown()  # idempotent, must not raise
+
+
+def test_force_flush_returns_true() -> None:
+    exporter, _ = _exporter()
+    assert exporter.force_flush() is True
+
+
+def test_shutdown_without_a_built_client_is_a_noop() -> None:
+    exporter = ClickHouseExporter(dsn=DSN)  # never exported ⇒ no client built
+    exporter.shutdown()  # must not raise
+
+
+# --- config: env resolution ---------------------------------------------------
+def test_env_resolves_dsn_table_and_flags(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("FORGESIGHT_CLICKHOUSE_DSN", DSN)
+    monkeypatch.setenv("FORGESIGHT_CLICKHOUSE_TABLE", "env_records")
+    monkeypatch.setenv("FORGESIGHT_CLICKHOUSE_BATCH_SIZE", "64")
+    monkeypatch.setenv("FORGESIGHT_CLICKHOUSE_ASYNC_INSERT", "false")
+    monkeypatch.setenv("FORGESIGHT_CLICKHOUSE_CREATE_TABLE", "true")
+    exporter = ClickHouseExporter()
+    assert exporter._dsn == DSN
+    assert exporter._table == "env_records"
+    assert exporter._batch_size == 64
+    assert exporter._async_insert is False
+    assert exporter._create_table is True
+
+
+def test_kwargs_win_over_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("FORGESIGHT_CLICKHOUSE_TABLE", "env_records")
+    exporter, _ = _exporter(table="explicit_records")
+    assert exporter._table == "explicit_records"
+
+
+# --- resolves by entry-point name ---------------------------------------------
+def test_resolves_by_name() -> None:
+    from forgesight_core.config import resolve
+
+    exporter = resolve("exporters", "clickhouse", {"dsn": DSN})
+    assert isinstance(exporter, ClickHouseExporter)