Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

feat(providers): add Cortex Code (Snowflake CoCo) as a supported agent (#1190)

sfc-gh-nashuklad9d0bf4b79f5
diff --git a/README.md b/README.md
index 95a52ee32..34e07ae60 100644
--- a/README.md
+++ b/README.md
@@ -189,14 +189,15 @@ shows an **Output Tokens Saved** card next to input compression, labelled
## Agent compatibility matrix
-| Agent | `headroom wrap` | Notes |
-|-------------|:---------------:|----------------------------------|
-| Claude Code | ✅ | `--memory` · `--code-graph` |
-| Codex | ✅ | shares memory with Claude |
-| Cursor | ✅ | prints config — paste once |
-| Aider | ✅ | starts proxy + launches |
-| Copilot CLI | ✅ | starts proxy + launches |
-| OpenClaw | ✅ | installs as ContextEngine plugin |
+| Agent | `headroom wrap` | Notes |
+|--------------|:---------------:|----------------------------------|
+| Claude Code | ✅ | `--memory` · `--code-graph` |
+| Codex | ✅ | shares memory with Claude |
+| Cursor | ✅ | prints config — paste once |
+| Aider | ✅ | starts proxy + launches |
+| Copilot CLI | ✅ | starts proxy + launches |
+| OpenClaw | ✅ | installs as ContextEngine plugin |
+| Cortex Code | ✅ | 60–65% savings · library mode |
Any OpenAI-compatible client works via `headroom proxy`. MCP-native: `headroom mcp install`.
diff --git a/docs/cortex-code.md b/docs/cortex-code.md
new file mode 100644
index 000000000..3d93d7afe
--- /dev/null
+++ b/docs/cortex-code.md
@@ -0,0 +1,247 @@
+# Cortex Code + Headroom — Integration Guide
+
+Headroom compresses the context Cortex Code (CoCo) sends to `claude-sonnet-4-6`
+before it reaches the Snowflake Cortex inference endpoint. The result is 60–65%
+fewer prompt tokens billed, with the same answers.
+
+## Benchmark (measured, not estimated)
+
+Token counts are from `usage.prompt_tokens` in the actual Snowflake Cortex API
+response — not headroom's local estimate.
+
+| Payload | Before | After | Saved |
+|---|---:|---:|---:|
+| Full CoCo session (tables + dbt + search) | 17,827 | 6,781 | **62%** |
+| `INFORMATION_SCHEMA` tables (79 rows) | 10,161 | 3,979 | **61%** |
+| `dbt` run-results (40 models) | 4,968 | 1,927 | **61%** |
+| Cortex Search results (15 docs) | 2,764 | 956 | **65%** |
+
+At 1,000 calls/day: **~$16/day saved**, **~$6,000/year saved**.
+
+> Numbers above are per-call averages across the four benchmark payloads.
+> The full-session payload alone saves ~$33/1,000 calls/day.
+
+## How it works
+
+```
+CoCo (cortex CLI)
+ │ OPENAI_BASE_URL=http://127.0.0.1:8787/v1
+ ▼
+Headroom proxy (local, your data never leaves your machine)
+ │ SmartCrusher compresses JSON context
+ │ CacheAligner stabilises KV-cache prefixes
+ ▼
+Snowflake Cortex /api/v2/cortex/inference:complete
+ │ claude-sonnet-4-6
+ ▼
+Response (same answer, fewer billed tokens)
+```
+
+Headroom's **SmartCrusher** targets the large JSON blobs that CoCo produces:
+`INFORMATION_SCHEMA` query results, `dbt` run-results, Cortex Search payloads,
+and schema introspection output. These are highly repetitive structures that
+compress 60–99% without any loss of information.
+
+## Quick start
+
+```bash
+pip install "headroom-ai[all]"
+headroom wrap cortex-code # starts proxy + prints the env var to set
+```
+
+`headroom wrap cortex-code` starts the local proxy and prints:
+
+```
+ Headroom proxy is running. Configure Cortex Code (CoCo):
+
+ Set the following environment variable before launching cortex:
+ OPENAI_BASE_URL=http://127.0.0.1:8787/v1
+```
+
+Then in a new shell:
+
+```bash
+OPENAI_BASE_URL=http://127.0.0.1:8787/v1 cortex
+```
+
+Or add it to your shell profile so it applies to every CoCo session:
+
+```bash
+# ~/.zshrc or ~/.bashrc
+export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
+```
+
+## Manual proxy startup
+
+If you prefer to manage the proxy lifecycle yourself:
+
+```bash
+# Terminal 1 — start the proxy
+headroom proxy --port 8787
+
+# Terminal 2 — launch CoCo through the proxy
+OPENAI_BASE_URL=http://127.0.0.1:8787/v1 cortex
+```
+
+Point the proxy at your Snowflake Cortex endpoint explicitly with
+`--openai-api-url`:
+
+```bash
+headroom proxy \
+ --port 8787 \
+ --openai-api-url https://<account>.snowflakecomputing.com
+```
+
+## Library mode (inline, no proxy)
+
+If you are building an application on top of the Snowflake Cortex REST API
+and want to compress context before every call:
+
+```python
+from headroom import compress
+import json, urllib.request
+
+# Build your messages (large JSON tool results, search results, etc.)
+messages = [
+ {"role": "system", "content": json.dumps(cortex_search_results, indent=2)},
+ {"role": "assistant", "content": "I have reviewed the context."},
+ {"role": "user", "content": "What is failing and how do I fix it?"},
+]
+
+# Compress before sending — local, no API call, no data leaves your machine
+result = compress(messages, model="claude-sonnet-4-6")
+print(f"Saved {result.tokens_saved} tokens ({result.tokens_saved / result.tokens_before:.0%})")
+
+# Send compressed messages to Snowflake Cortex REST API
+response = call_cortex(result.messages, token=sf_token)
+```
+
+### What to put in the system message
+
+The Snowflake Cortex REST API supports `system`, `user`, and `assistant` roles.
+For maximum compression, inject large retrieved context into `system`:
+
+```python
+# Query results, search results, schema — these compress 60–99%
+system_context = {
+ "tables": json.loads(show_tables_result),
+ "search_results": cortex_search_results,
+ "schema": describe_table_result,
+ "dbt_results": dbt_run_results_json,
+}
+messages = [
+ {"role": "system", "content": json.dumps(system_context, indent=2)},
+ {"role": "assistant", "content": "Context loaded."},
+ {"role": "user", "content": user_question},
+]
+result = compress(messages, model="claude-sonnet-4-6")
+```
+
+## Authentication
+
+Cortex Code authenticates using your Snowflake connection. Headroom sits
+between CoCo and the Cortex endpoint and forwards auth headers unchanged —
+it never reads or stores your credentials.
+
+If you use `snowflake-connector-python` directly, keep the connection open
+while making API calls; closing it invalidates the OAuth session token:
+
+```python
+import snowflake.connector, sys, io
+
+# Suppress connector's browser-auth console output
+_s = sys.stdout; sys.stdout = io.StringIO()
+conn = snowflake.connector.connect(connection_name="my_connection")
+token = conn.rest.token
+sys.stdout = _s
+
+# Make all API calls while conn is open, then:
+conn.close()
+```
+
+## Per-project savings attribution
+
+Use `headroom wrap cortex-code --project <name>` to attribute savings to a
+specific project in the headroom dashboard:
+
+```bash
+headroom wrap cortex-code --project my-dbt-project
+```
+
+The dashboard at `http://127.0.0.1:8787` shows per-project token and cost
+savings across all your CoCo sessions.
+
+## Verifying savings
+
+After a CoCo session, check what headroom saved:
+
+```bash
+headroom perf # token savings for the last session
+headroom perf --hours 24 # last 24 hours
+```
+
+Or run the included end-to-end benchmark against your own Snowflake account:
+
+```bash
+# Measures real usage.prompt_tokens from claude-sonnet-4-6
+python3 tests/e2e_cortex_savings.py
+```
+
+## Testing
+
+Unit tests for the provider slice:
+
+```bash
+uv run --with pytest pytest tests/test_provider_cortex_code.py -v
+```
+
+Compression benchmark (no API key needed — local only):
+
+```bash
+uv run --with pytest pytest tests/test_cortex_code_compression.py -v -s
+```
+
+Real E2E test against Snowflake Cortex (requires Snowflake connection):
+
+```bash
+python3 tests/e2e_cortex_savings.py
+```
+
+## How the provider is implemented
+
+Cortex Code routes through headroom's OpenAI-compatible pipeline. The provider
+slice lives in `headroom/providers/cortex_code/`:
+
+| File | Purpose |
+|---|---|
+| `runtime.py` | `proxy_base_url(port)` → `http://127.0.0.1:{port}/v1`; `default_api_url()` reads `SNOWFLAKE_HOST` / `SNOWFLAKE_ACCOUNT` |
+| `install.py` | `build_install_env()` → `{"OPENAI_BASE_URL": ...}`; `render_setup_lines()` |
+| `__init__.py` | Public exports |
+
+Registered in `headroom/providers/install_registry.py` under the key
+`"cortex-code"`, which is what `headroom wrap cortex-code` resolves to.
+
+## Limitations
+
+- The Snowflake Cortex REST API at `/api/v2/cortex/inference:complete` does not
+ support `role: "tool"` messages or OpenAI-style `tool_calls`. Use the
+ `system` message to inject large retrieved context (where SmartCrusher
+ achieves the highest compression ratios).
+
+- The headroom proxy cannot rewrite the Cortex inference path
+ (`/api/v2/cortex/inference:complete` ≠ `/v1/chat/completions`), so
+ **library mode** (`from headroom import compress`) is required when calling
+ the Cortex REST API directly. The proxy mode works for any
+ OpenAI-compatible client that points at Cortex via a gateway that exposes
+ `/v1/chat/completions`.
+
+- Output-token reduction (`HEADROOM_OUTPUT_SHAPER=1`) is supported in proxy
+ mode. In library mode only input compression applies.
+
+## See also
+
+- [Architecture](ARCHITECTURE.md)
+- [Proxy configuration](proxy.md)
+- [CCR — reversible compression](ccr.md)
+- [Claude Code + Vertex](claude-code-vertex-headroom.md)
+- [Benchmarks](benchmarks.md)
diff --git a/headroom/providers/cortex_code/__init__.py b/headroom/providers/cortex_code/__init__.py
new file mode 100644
index 000000000..67dd498d0
--- /dev/null
+++ b/headroom/providers/cortex_code/__init__.py
@@ -0,0 +1,12 @@
+"""Cortex Code provider helpers."""
+
+from .install import build_install_env, render_setup_lines
+from .runtime import SNOWFLAKE_ACCOUNT_ENV, default_api_url, proxy_base_url
+
+__all__ = [
+ "SNOWFLAKE_ACCOUNT_ENV",
+ "build_install_env",
+ "default_api_url",
+ "proxy_base_url",
+ "render_setup_lines",
+]
diff --git a/headroom/providers/cortex_code/install.py b/headroom/providers/cortex_code/install.py
new file mode 100644
index 000000000..c0da2ee51
--- /dev/null
+++ b/headroom/providers/cortex_code/install.py
@@ -0,0 +1,30 @@
+"""Cortex Code install-time helpers."""
+
+from __future__ import annotations
+
+from .runtime import build_launch_env, proxy_base_url
+
+
+def build_install_env(*, port: int, backend: str) -> dict[str, str]:
+ """Build the persistent install environment for Cortex Code."""
+ del backend
+ return {"OPENAI_BASE_URL": proxy_base_url(port)}
+
+
+def render_setup_lines(port: int, project: str | None = None) -> list[str]:
+ """Render the Cortex Code setup instructions for the local proxy."""
+ _, env_lines = build_launch_env(port=port, environ={}, project=project)
+ lines = [
+ " Headroom proxy is running. Configure Cortex Code (CoCo):",
+ "",
+ " Set the following environment variable before launching cortex:",
+ ]
+ lines += [f" {line}" for line in env_lines]
+ if project:
+ lines += [
+ "",
+ f" Dashboard savings will be attributed to project '{project}'",
+ " (the directory this command was run from). Re-run from another",
+ " project directory to get that project's URL.",
+ ]
+ return lines
diff --git a/headroom/providers/cortex_code/runtime.py b/headroom/providers/cortex_code/runtime.py
new file mode 100644
index 000000000..a88c814b6
--- /dev/null
+++ b/headroom/providers/cortex_code/runtime.py
@@ -0,0 +1,52 @@
+"""Runtime helpers for Cortex Code (CoCo) integrations."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from headroom.proxy.project_context import with_project_prefix
+
+SNOWFLAKE_ACCOUNT_ENV = "SNOWFLAKE_ACCOUNT"
+SNOWFLAKE_HOST_ENV = "SNOWFLAKE_HOST"
+_FALLBACK_API_URL = "https://app.snowflake.com"
+
+
+def default_api_url(environ: Mapping[str, str] | None = None) -> str:
+ """Return the upstream Snowflake Cortex API URL.
+
+ Reads SNOWFLAKE_HOST first, then SNOWFLAKE_ACCOUNT, and constructs
+ a ``https://<host>.snowflakecomputing.com`` base URL. Falls back to
+ ``https://app.snowflake.com`` when neither variable is set.
+ """
+ env = environ or os.environ
+ host = env.get(SNOWFLAKE_HOST_ENV) or env.get(SNOWFLAKE_ACCOUNT_ENV, "")
+ if host:
+ if host.startswith("https://"):
+ return host
+ if ".snowflakecomputing.com" in host:
+ return f"https://{host}"
+ return f"https://{host}.snowflakecomputing.com"
+ return _FALLBACK_API_URL
+
+
+def proxy_base_url(port: int) -> str:
+ """Return the local proxy base URL for OpenAI-compatible Cortex requests."""
+ return f"http://127.0.0.1:{port}/v1"
+
+
+def build_launch_env(
+ port: int,
+ environ: Mapping[str, str] | None = None,
+ project: str | None = None,
+) -> tuple[dict[str, str], list[str]]:
+ """Build the environment variables that redirect Cortex Code through the proxy.
+
+ Returns a ``(env_dict, printed_lines)`` tuple. ``env_dict`` is a copy of
+ *environ* with ``OPENAI_BASE_URL`` set to the local proxy endpoint.
+ ``printed_lines`` is the ``KEY=VALUE`` form shown to the user on launch.
+ """
+ env = dict(environ or os.environ)
+ base_url = with_project_prefix(proxy_base_url(port), project)
+ env["OPENAI_BASE_URL"] = base_url
+ return env, [f"OPENAI_BASE_URL={base_url}"]
diff --git a/headroom/providers/install_registry.py b/headroom/providers/install_registry.py
index 99526435e..b866b333b 100644
--- a/headroom/providers/install_registry.py
+++ b/headroom/providers/install_registry.py
@@ -25,6 +25,9 @@ from headroom.providers.codex.install import (
from headroom.providers.copilot.install import (
build_install_env as _build_copilot_install_env,
)
+from headroom.providers.cortex_code.install import (
+ build_install_env as _build_cortex_code_install_env,
+)
from headroom.providers.cursor.install import build_install_env as _build_cursor_install_env
from headroom.providers.openclaw.install import (
apply_provider_scope as _apply_openclaw_provider_scope,
@@ -42,6 +45,7 @@ _ENV_BUILDERS: dict[str, _InstallEnvBuilder] = {
"copilot": _build_copilot_install_env,
"codex": _build_codex_install_env,
"aider": _build_aider_install_env,
+ "cortex-code": _build_cortex_code_install_env,
"cursor": _build_cursor_install_env,
}
diff --git a/tests/e2e_cortex_savings.py b/tests/e2e_cortex_savings.py
new file mode 100644
index 000000000..948274e02
--- /dev/null
+++ b/tests/e2e_cortex_savings.py
@@ -0,0 +1,460 @@
+#!/usr/bin/env python3
+"""
+Real end-to-end token-savings test for Cortex Code + Headroom.
+
+Makes ACTUAL REST API calls to Snowflake Cortex (claude-sonnet-4-6) and
+measures the REAL token counts from the LLM's usage.prompt_tokens field.
+
+Three test patterns:
+
+ 1. System-message context (Snowflake Cortex compatible)
+ Large JSON blobs (query results, search results, schema) in the system
+ message → headroom's SmartCrusher compresses them.
+
+ 2. OpenAI tool-result format (if OPENAI_API_KEY is set)
+ Standard role:"tool" messages compressed via SmartCrusher.
+
+ 3. Anthropic messages format (if ANTHROPIC_API_KEY is set)
+ Claude tool_result blocks compressed.
+
+Usage (Snowflake Cortex only — no extra API keys needed):
+ SF_CONN=<your-connection-name> python3 tests/e2e_cortex_savings.py
+
+ # SF_HOST is auto-derived from the connection; override if needed:
+ SF_CONN=my_conn SF_HOST=myaccount.snowflakecomputing.com python3 tests/e2e_cortex_savings.py
+
+ # Additional backends (optional):
+ SF_CONN=my_conn OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... python3 tests/e2e_cortex_savings.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+# ── Bootstrap: make headroom importable from the project venv ─────────────────
+REPO_ROOT = Path(__file__).resolve().parent.parent
+_VENV_SITE = REPO_ROOT / ".venv" / "lib"
+try:
+ from headroom import compress as _hc_check # noqa: F401
+except ImportError:
+ sys.path.insert(0, str(REPO_ROOT))
+ for _d in _VENV_SITE.glob("python*/site-packages"):
+ sys.path.insert(0, str(_d))
+
+# Snowflake Cortex pricing USD/1M tokens (as of 2025)
+_INPUT_PRICE_PER_1M = 3.00
+
+# ── Snowflake connection settings ─────────────────────────────────────────────
+# Override via env vars:
+# SF_HOST=<account>.snowflakecomputing.com
+# SF_CONN=<connection-name-from-connections.toml>
+# SF_MODEL=<cortex-model-id>
+_SF_HOST = os.environ.get("SF_HOST", "")
+_SF_CONN = os.environ.get("SF_CONN", "")
+_SF_MODEL = os.environ.get("SF_MODEL", "claude-sonnet-4-6")
+
+# ── Payload builders ──────────────────────────────────────────────────────────
+
+
+def _tables_json() -> str:
+ rows = [
+ {
+ "TABLE_CATALOG": "PROD_DB",
+ "TABLE_SCHEMA": "ANALYTICS",
+ "TABLE_NAME": f"FACT_ORDERS_{i:03d}",
+ "TABLE_TYPE": "BASE TABLE",
+ "ROW_COUNT": i * 1_423_001,
+ "BYTES": i * 8_192_000,
+ "CREATED": "2024-01-15",
+ "LAST_ALTERED": "2025-06-10",
+ "COMMENT": f"Daily order fact partition {i:03d}",
+ }
+ for i in range(1, 80)
+ ]
+ return json.dumps(rows, indent=2)
+
+
+def _dbt_json() -> str:
+ return json.dumps(
+ {
+ "metadata": {"dbt_version": "1.8.0"},
+ "results": [
+ {
+ "unique_id": f"model.analytics.fct_{i:03d}",
+ "status": "success" if i % 7 != 0 else "error",
+ "execution_time": round(0.8 + i * 0.12, 3),
+ "rows_affected": i * 12_500,
+ "compiled_code": f"SELECT * FROM raw.orders_{i:03d} WHERE status='active'",
+ "failures": None
+ if i % 7 != 0
+ else [{"message": f"Invalid col_{i}", "line": i % 40}],
+ "adapter_response": {"query_id": f"01b{i:06x}", "rows_produced": i * 12_500},
+ }
+ for i in range(40)
+ ],
+ },
+ indent=2,
+ )
+
+
+def _search_json() -> str:
+ return json.dumps(
+ [
+ {
+ "rank": i + 1,
+ "score": round(0.98 - i * 0.02, 4),
+ "document_id": f"doc_{i:04d}",
+ "source": "PROD_DB.DOCS.ENGINEERING_WIKI",
+ "content": (
+ "The revenue pipeline processes 2.3 million orders per day. "
+ "product_family column was renamed to product_group in Q3 2024. "
+ "Migration: update all references in models/marts/revenue/ and "
+ "run dbt run --full-refresh --select fct_revenue. "
+ "The rename was tracked in JIRA-4892 and deployed on 2024-09-15."
+ ),
+ "metadata": {"author": f"eng_{i % 6}@company.com", "updated": "2025-05-20"},
+ }
+ for i in range(15)
+ ],
+ indent=2,
+ )
+
+
+# ── Message builders for each API format ─────────────────────────────────────
+
+
+def build_system_msgs(system_content: str) -> list[dict]:
+ """Snowflake Cortex-compatible format (system + user/assistant)."""
+ return [
+ {"role": "system", "content": system_content},
+ {"role": "assistant", "content": "I have reviewed the context above."},
+ {
+ "role": "user",
+ "content": "Based on the data above, what is failing and how do I fix it?",
+ },
+ ]
+
+
+def build_tool_msgs(tool_content: str) -> list[dict]:
+ """OpenAI tool-result format (for OpenAI / proxy)."""
+ return [
+ {"role": "user", "content": "Analyze the fct_revenue dbt model failure."},
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "c1",
+ "type": "function",
+ "function": {
+ "name": "snowflake_query",
+ "arguments": '{"sql":"SELECT * FROM INFORMATION_SCHEMA.TABLES"}',
+ },
+ }
+ ],
+ },
+ {"role": "tool", "tool_call_id": "c1", "content": tool_content},
+ {"role": "user", "content": "What is the root cause?"},
+ ]
+
+
+# ── API call helpers ──────────────────────────────────────────────────────────
+
+
+def _sf_call(messages: list[dict], token: str, host: str) -> dict:
+ body = json.dumps(
+ {
+ "model": _SF_MODEL,
+ "messages": messages,
+ "max_tokens": 64,
+ "stream": False,
+ }
+ ).encode()
+ req = urllib.request.Request(
+ f"https://{host}/api/v2/cortex/inference:complete",
+ data=body,
+ headers={"Authorization": f'Snowflake Token="{token}"', "Content-Type": "application/json"},
+ method="POST",
+ )
+ with urllib.request.urlopen(req, timeout=60) as r:
+ resp = json.loads(r.read())
+ if "error_code" in resp:
+ raise RuntimeError(f"Cortex {resp['error_code']}: {resp.get('message')}")
+ return resp
+
+
+def _oai_call(messages: list[dict], api_key: str, base_url: str = "https://api.openai.com") -> dict:
+ body = json.dumps({"model": "gpt-4o-mini", "messages": messages, "max_tokens": 64}).encode()
+ req = urllib.request.Request(
+ f"{base_url.rstrip('/')}/v1/chat/completions",
+ data=body,
+ headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+ method="POST",
+ )
+ with urllib.request.urlopen(req, timeout=60) as r:
+ return json.loads(r.read())
+
+
+def _ant_call(messages: list[dict], api_key: str) -> dict:
+ body = json.dumps(
+ {"model": "claude-haiku-4-5", "messages": messages, "max_tokens": 64}
+ ).encode()
+ req = urllib.request.Request(
+ "https://api.anthropic.com/v1/messages",
+ data=body,
+ headers={
+ "x-api-key": api_key,
+ "anthropic-version": "2023-06-01",
+ "Content-Type": "application/json",
+ },
+ method="POST",
+ )
+ with urllib.request.urlopen(req, timeout=60) as r:
+ return json.loads(r.read())
+
+
+def _tokens(resp: dict, is_anthropic: bool = False) -> tuple[int, int]:
+ u = resp.get("usage", {})
+ if is_anthropic:
+ return u.get("input_tokens", 0), u.get("output_tokens", 0)
+ return u.get("prompt_tokens", 0), u.get("completion_tokens", 0)
+
+
+# ── Benchmark ─────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class R:
+ label: str
+ before_p: int
+ after_p: int
+ before_c: int
+ after_c: int
+ compress_ms: float
+ direct_ms: float
+ compr_call_ms: float
+
+ @property
+ def saved(self) -> int:
+ return self.before_p - self.after_p
+
+ @property
+ def pct(self) -> float:
+ return self.saved / max(self.before_p, 1) * 100
+
+ @property
+ def usd_saved(self) -> float:
+ return self.saved / 1_000_000 * _INPUT_PRICE_PER_1M
+
+
+def run(label: str, msgs: list[dict], call_fn, is_anthropic: bool = False) -> R:
+ from headroom import compress
+
+ t0 = time.perf_counter()
+ direct = call_fn(msgs)
+ dm = (time.perf_counter() - t0) * 1000
+ bp, bc = _tokens(direct, is_anthropic)
+
+ t0 = time.perf_counter()
+ compressed = compress(msgs, model="claude-sonnet-4-5-20250929")
+ cm = (time.perf_counter() - t0) * 1000
+
+ t0 = time.perf_counter()
+ compr_resp = call_fn(compressed.messages)
+ com = (time.perf_counter() - t0) * 1000
+ ap, ac = _tokens(compr_resp, is_anthropic)
+
+ return R(
+ label=label,
+ before_p=bp,
+ after_p=ap,
+ before_c=bc,
+ after_c=ac,
+ compress_ms=cm,
+ direct_ms=dm,
+ compr_call_ms=com,
+ )
+
+
+def _bar(pct: float, w: int = 24) -> str:
+ n = int(pct / 100 * w)
+ return "█" * n + "░" * (w - n)
+
+
+def _show(r: R) -> None:
+ sym = "✓" if r.saved > 0 else "·"
+ print(f"\n {sym} {r.label}")
+ print(
+ f" Prompt tokens : {r.before_p:>7,} → {r.after_p:>7,} "
+ f"│ saved {r.saved:>6,} ({r.pct:.1f}%)"
+ )
+ print(f" {_bar(r.pct)} ${r.usd_saved:.5f} saved / call")
+ print(
+ f" Timing : direct {r.direct_ms:.0f}ms │ "
+ f"compress {r.compress_ms:.0f}ms + compressed-call {r.compr_call_ms:.0f}ms"
+ )
+
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+
+def main() -> int:
+ print()
+ print("╔══════════════════════════════════════════════════════════╗")
+ print("║ Cortex Code × Headroom — Real REST API savings ║")
+ print("║ usage.prompt_tokens measured directly from the LLM ║")
+ print("╚══════════════════════════════════════════════════════════╝")
+
+ results: list[R] = []
+
+ # ── 1. Snowflake Cortex (system-message pattern) ──────────────────────────
+ print("\n▶ Snowflake Cortex /api/v2/cortex/inference:complete")
+ try:
+ import io
+
+ import snowflake.connector # noqa: F401
+
+ if not _SF_CONN:
+ raise RuntimeError(
+ "Set SF_CONN=<your-connection-name> (from ~/.snowflake/connections.toml)"
+ )
+ _s = sys.stdout
+ sys.stdout = io.StringIO()
+ try:
+ _conn = snowflake.connector.connect(connection_name=_SF_CONN)
+ _tok = _conn.rest.token
+ # Derive host: prefer SF_HOST env var, then try account locator
+ # (conn.host may be the org-format name which can fail SSL validation)
+ if _SF_HOST:
+ sf_host = _SF_HOST
+ else:
+ cs = _conn.cursor()
+ cs.execute("SELECT CURRENT_ACCOUNT_LOCATOR()")
+ locator = cs.fetchone()[0].lower()
+ sf_host = f"{locator}.snowflakecomputing.com"
+ finally:
+ sys.stdout = _s
+
+ print(f" Model: {_SF_MODEL} │ Host: {sf_host}")
+
+ def sf_call(m: list[dict]) -> dict:
+ return _sf_call(m, _tok, sf_host)
+
+ # Combined context: tables + dbt + search results in system message
+ full_ctx = json.dumps(
+ {
+ "tables": json.loads(_tables_json()),
+ "dbt_results": json.loads(_dbt_json()),
+ "search_results": json.loads(_search_json()),
+ },
+ indent=2,
+ )
+
+ payloads = [
+ ("Cortex — full context (tables + dbt + search)", build_system_msgs(full_ctx)),
+ ("Cortex — INFORMATION_SCHEMA tables (79 rows)", build_system_msgs(_tables_json())),
+ ("Cortex — dbt run-results (40 models)", build_system_msgs(_dbt_json())),
+ ("Cortex — Cortex Search results (15 docs)", build_system_msgs(_search_json())),
+ ]
+
+ for label, msgs in payloads:
+ approx = len(json.dumps(msgs)) // 4
+ print(f"\n {label}")
+ print(f" Payload: ~{approx:,} tokens ...", end=" ", flush=True)
+ r = run(label, msgs, sf_call)
+ results.append(r)
+ print(f"saved {r.saved:,} tokens ({r.pct:.0f}%)")
+ _show(r)
+
+ _conn.close()
+
+ except Exception as e:
+ print(f"\n ✗ Snowflake Cortex skipped: {e}")
+
+ # ── 2. OpenAI (tool-result format) ───────────────────────────────────────
+ oai_key = os.environ.get("OPENAI_API_KEY", "")
+ if oai_key:
+ print("\n\n▶ OpenAI /v1/chat/completions (gpt-4o-mini)")
+ for label, content in [
+ ("OpenAI — tables JSON (79 rows)", _tables_json()),
+ ("OpenAI — Cortex Search (15 docs)", _search_json()),
+ ]:
+ msgs = build_tool_msgs(content)
+ approx = len(json.dumps(msgs)) // 4
+ print(f"\n {label} (~{approx:,} tokens) ...", end=" ", flush=True)
+
+ def _oai(m: list[dict]) -> dict:
+ return _oai_call(m, oai_key)
+
+ r = run(label, msgs, _oai)
+ results.append(r)
+ print(f"saved {r.saved:,} ({r.pct:.0f}%)")
+ _show(r)
+ else:
+ print("\n▶ OpenAI — skipped (export OPENAI_API_KEY to enable)")
+
+ # ── 3. Anthropic ─────────────────────────────────────────────────────────
+ ant_key = os.environ.get("ANTHROPIC_API_KEY", "")
+ if ant_key:
+ print("\n\n▶ Anthropic /v1/messages (claude-haiku-4-5)")
+ for label, content in [
+ ("Anthropic — tables JSON (79 rows)", _tables_json()),
+ ("Anthropic — Cortex Search (15 docs)", _search_json()),
+ ]:
+ msgs = build_tool_msgs(content)
+ approx = len(json.dumps(msgs)) // 4
+ print(f"\n {label} (~{approx:,} tokens) ...", end=" ", flush=True)
+
+ def _ant(m: list[dict]) -> dict:
+ return _ant_call(m, ant_key)
+
+ r = run(label, msgs, _ant, is_anthropic=True)
+ results.append(r)
+ print(f"saved {r.saved:,} ({r.pct:.0f}%)")
+ _show(r)
+ else:
+ print("\n▶ Anthropic — skipped (export ANTHROPIC_API_KEY to enable)")
+
+ # ── Summary ───────────────────────────────────────────────────────────────
+ if not results:
+ print("\n No results. Is snowflake-connector-python installed?")
+ return 1
+
+ tb = sum(r.before_p for r in results)
+ ta = sum(r.after_p for r in results)
+ ts = tb - ta
+ tp = ts / max(tb, 1) * 100
+ tu = sum(r.usd_saved for r in results)
+
+ print()
+ print("╔══════════════════════════════════════════════════════════╗")
+ print("║ SUMMARY — real usage.prompt_tokens from LLM ║")
+ print("╠══════════════════════════════════════════════════════════╣")
+ print(f" {'Payload':<40} {'Before':>7} {'After':>7} {'Saved':>5}")
+ print(f" {'─' * 40} {'─' * 7} {'─' * 7} {'─' * 5}")
+ for r in results:
+ m = "✓" if r.saved > 0 else "·"
+ print(f" {m} {r.label[:39]:<39} {r.before_p:>7,} {r.after_p:>7,} {r.pct:>4.0f}%")
+ print(f" {'─' * 40} {'─' * 7} {'─' * 7} {'─' * 5}")
+ print(f" {'TOTAL':<40} {tb:>7,} {ta:>7,} {tp:>4.0f}%")
+ print()
+ avg_saved_per_call = ts / max(len(results), 1)
+ avg_usd_per_call = tu / max(len(results), 1)
+ print(f" Tokens saved : {ts:>8,} prompt tokens ({len(results)} calls)")
+ print(f" Avg per call : {avg_saved_per_call:>8,.0f} tokens / ${avg_usd_per_call:.5f}")
+ print(
+ f" At 1k/day : ${avg_usd_per_call * 1_000:.2f}/day │ ${avg_usd_per_call * 365_000:,.0f}/year"
+ )
+ print("╚══════════════════════════════════════════════════════════╝")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tests/test_cortex_code_compression.py b/tests/test_cortex_code_compression.py
new file mode 100644
index 000000000..388968533
--- /dev/null
+++ b/tests/test_cortex_code_compression.py
@@ -0,0 +1,679 @@
+#!/usr/bin/env python3
+"""End-to-end token-savings test for Cortex Code (CoCo) + Headroom.
+
+Simulates a real Cortex Code session using JSON-format tool results —
+the format Snowflake's Python connector and most tool wrappers actually
+emit. Headroom's SmartCrusher compresses JSON natively without any ML
+model, so this test works with the base install (no [ml] extra needed).
+
+No API key required. Compression runs fully local.
+
+Usage:
+ # Benchmark (pretty-printed report):
+ cd headroom && uv run python tests/test_cortex_code_compression.py
+
+ # Pytest (CI-friendly assertions):
+ cd headroom && uv run --with pytest pytest tests/test_cortex_code_compression.py -v -s
+"""
+
+from __future__ import annotations
+
+import json
+import time
+
+MODEL = "claude-sonnet-4-5-20250929"
+
+# ── Realistic CoCo JSON payload builders ─────────────────────────────────────
+
+
+def snowflake_tables_json() -> str:
+ """JSON array returned by INFORMATION_SCHEMA.TABLES — SmartCrusher target."""
+ rows = [
+ {
+ "TABLE_CATALOG": "PROD_DB",
+ "TABLE_SCHEMA": "ANALYTICS",
+ "TABLE_NAME": f"FACT_ORDERS_{i:03d}",
+ "TABLE_TYPE": "BASE TABLE",
+ "ROW_COUNT": i * 1_423_001,
+ "BYTES": i * 8_192_000,
+ "CREATED": "2024-01-15T08:00:00Z",
+ "LAST_ALTERED": "2025-06-10T14:22:00Z",
+ "COMMENT": f"Daily order fact partition {i:03d}",
+ }
+ for i in range(1, 80)
+ ]
+ return json.dumps(rows, indent=2)
+
+
+def snowflake_schema_json() -> str:
+ """JSON array from DESCRIBE TABLE — repeated structure SmartCrusher loves."""
+ base = [
+ {
+ "COLUMN_NAME": "order_id",
+ "DATA_TYPE": "VARCHAR",
+ "LENGTH": 36,
+ "NULLABLE": False,
+ "PRIMARY_KEY": True,
+ "COMMENT": "UUID primary key",
+ },
+ {
+ "COLUMN_NAME": "order_date",
+ "DATA_TYPE": "DATE",
+ "LENGTH": None,
+ "NULLABLE": False,
+ "PRIMARY_KEY": False,
+ "COMMENT": "Order placement date",
+ },
+ {
+ "COLUMN_NAME": "customer_id",
+ "DATA_TYPE": "VARCHAR",
+ "LENGTH": 36,
+ "NULLABLE": False,
+ "PRIMARY_KEY": False,
+ "COMMENT": "FK to dim_customers",
+ },
+ {
+ "COLUMN_NAME": "region",
+ "DATA_TYPE": "VARCHAR",
+ "LENGTH": 50,
+ "NULLABLE": False,
+ "PRIMARY_KEY": False,
+ "COMMENT": "Sales region code",
+ },
+ {
+ "COLUMN_NAME": "product_category",
+ "DATA_TYPE": "VARCHAR",
+ "LENGTH": 100,
+ "NULLABLE": False,
+ "PRIMARY_KEY": False,
+ "COMMENT": "Top-level product category",
+ },
+ {
+ "COLUMN_NAME": "product_sku",
+ "DATA_TYPE": "VARCHAR",
+ "LENGTH": 50,
+ "NULLABLE": False,
+ "PRIMARY_KEY": False,
+ "COMMENT": "FK to dim_products",
+ },
+ {
+ "COLUMN_NAME": "quantity",
+ "DATA_TYPE": "NUMBER",
+ "LENGTH": None,
+ "NULLABLE": False,
+ "PRIMARY_KEY": False,
+ "COMMENT": "Units ordered",
+ },
+ {
+ "COLUMN_NAME": "unit_price",
+ "DATA_TYPE": "NUMBER",
+ "LENGTH": None,
+ "NULLABLE": False,
+ "PRIMARY_KEY": False,
+ "COMMENT": "Price per unit USD",
+ },
+ {
+ "COLUMN_NAME": "discount_pct",
+ "DATA_TYPE": "NUMBER",
+ "LENGTH": None,
+ "NULLABLE": False,
+ "PRIMARY_KEY": False,
+ "COMMENT": "Discount percentage 0-100",
+ },
+ {
+ "COLUMN_NAME": "status",
+ "DATA_TYPE": "VARCHAR",
+ "LENGTH": 20,
+ "NULLABLE": False,
+ "PRIMARY_KEY": False,
+ "COMMENT": "Order lifecycle status",
+ },
+ {
+ "COLUMN_NAME": "net_revenue",
+ "DATA_TYPE": "NUMBER",
+ "LENGTH": None,
+ "NULLABLE": True,
+ "PRIMARY_KEY": False,
+ "COMMENT": "qty * price * (1-disc)",
+ },
+ {
+ "COLUMN_NAME": "gross_profit",
+ "DATA_TYPE": "NUMBER",
+ "LENGTH": None,
+ "NULLABLE": True,
+ "PRIMARY_KEY": False,
+ "COMMENT": "net_revenue - COGS",
+ },
+ {
+ "COLUMN_NAME": "customer_tier",
+ "DATA_TYPE": "VARCHAR",
+ "LENGTH": 20,
+ "NULLABLE": True,
+ "PRIMARY_KEY": False,
+ "COMMENT": "Gold/Silver/Bronze",
+ },
+ {
+ "COLUMN_NAME": "acquisition_channel",
+ "DATA_TYPE": "VARCHAR",
+ "LENGTH": 50,
+ "NULLABLE": True,
+ "PRIMARY_KEY": False,
+ "COMMENT": "How customer was acquired",
+ },
+ {
+ "COLUMN_NAME": "created_at",
+ "DATA_TYPE": "TIMESTAMP_NTZ",
+ "LENGTH": None,
+ "NULLABLE": False,
+ "PRIMARY_KEY": False,
+ "COMMENT": "Row creation timestamp",
+ },
+ {
+ "COLUMN_NAME": "updated_at",
+ "DATA_TYPE": "TIMESTAMP_NTZ",
+ "LENGTH": None,
+ "NULLABLE": False,
+ "PRIMARY_KEY": False,
+ "COMMENT": "Last modified timestamp",
+ },
+ {
+ "COLUMN_NAME": "_dbt_scd_id",
+ "DATA_TYPE": "VARCHAR",
+ "LENGTH": 36,
+ "NULLABLE": True,
+ "PRIMARY_KEY": False,
+ "COMMENT": "dbt SCD type-2 surrogate key",
+ },
+ {
+ "COLUMN_NAME": "_dbt_updated_at",
+ "DATA_TYPE": "TIMESTAMP_NTZ",
+ "LENGTH": None,
+ "NULLABLE": True,
+ "PRIMARY_KEY": False,
+ "COMMENT": "dbt update marker",
+ },
+ {
+ "COLUMN_NAME": "_dbt_valid_from",
+ "DATA_TYPE": "TIMESTAMP_NTZ",
+ "LENGTH": None,
+ "NULLABLE": True,
+ "PRIMARY_KEY": False,
+ "COMMENT": "SCD validity start",
+ },
+ {
+ "COLUMN_NAME": "_dbt_valid_to",
+ "DATA_TYPE": "TIMESTAMP_NTZ",
+ "LENGTH": None,
+ "NULLABLE": True,
+ "PRIMARY_KEY": False,
+ "COMMENT": "SCD validity end",
+ },
+ ]
+ # Three tables introspected in sequence — same schema, different table names
+ result = []
+ for table in ["stg_orders", "int_orders_enriched", "fct_revenue"]:
+ for col in base:
+ result.append({**col, "TABLE_NAME": table})
+ return json.dumps(result, indent=2)
+
+
+def dbt_run_results_json() -> str:
+ """JSON run-results.json from a dbt invocation — realistic CoCo tool output."""
+ nodes = [
+ {
+ "unique_id": f"model.analytics.{'stg_' if i < 10 else 'fct_'}model_{i:03d}",
+ "status": "success" if i % 7 != 0 else "error",
+ "execution_time": round(0.8 + i * 0.12, 3),
+ "rows_affected": i * 12_500,
+ "compiled_code": f"SELECT * FROM raw.orders_{i:03d} WHERE status = 'active'",
+ "failures": None
+ if i % 7 != 0
+ else [{"message": f"Invalid identifier 'col_{i}' in select list", "line": i % 40 + 1}],
+ "adapter_response": {
+ "query_id": f"01b{i:06x}-0000-0001-0000-000300000001",
+ "rows_produced": i * 12_500,
+ "bytes_scanned": i * 8_192,
+ "compilation_time": 0.05,
+ "execution_time": round(0.8 + i * 0.12, 3),
+ },
+ }
+ for i in range(40)
+ ]
+ return json.dumps(
+ {"metadata": {"dbt_version": "1.8.0", "invocation_id": "abc123"}, "results": nodes},
+ indent=2,
+ )
+
+
+def rag_cortex_search_json() -> str:
+ """JSON results from a Cortex Search query — common in CoCo sessions."""
+ docs = [
+ {
+ "rank": i + 1,
+ "score": round(0.98 - i * 0.02, 4),
+ "document_id": f"doc_{i:04d}",
+ "source_table": "PROD_DB.DOCS.ENGINEERING_WIKI",
+ "chunk_index": i % 5,
+ "content": (
+ "The revenue pipeline processes approximately 2.3 million orders per day "
+ "across 14 regional data centers. Each order record contains pricing "
+ "information, customer segmentation data, and fulfillment status. "
+ "The dbt transformation layer applies discount calculations and joins "
+ "to the customer dimension table to derive net revenue and gross profit "
+ "metrics. Incremental models refresh every 4 hours using Snowflake "
+ "dynamic tables as the upstream source. Known issue: the product_family "
+ "column was renamed to product_group in Q3 2024; models referencing "
+ "the old column name will fail with SQL compilation error 001003. "
+ "Migration guide: update all references from product_family to product_group "
+ "in models/marts/revenue/ and run dbt run --full-refresh."
+ ),
+ "metadata": {
+ "author": f"engineer_{i % 8}@company.com",
+ "last_updated": "2025-05-20",
+ "tags": ["dbt", "revenue", "snowflake", "migration"],
+ },
+ }
+ for i in range(15)
+ ]
+ return json.dumps(docs, indent=2)
+
+
+def build_coco_session_messages() -> list[dict]:
+ """Multi-turn CoCo session: diagnose a failing dbt model via Snowflake tools.
+
+ Turn structure mirrors what CoCo actually does:
+ 1. User asks to fix fct_revenue
+ 2. CoCo queries table catalog (→ large JSON tool result)
+ 3. CoCo introspects schema (→ large JSON tool result)
+ 4. CoCo runs dbt, reads results (→ large JSON tool result)
+ 5. CoCo searches the wiki (→ large JSON tool result)
+ 6. User asks follow-up
+ """
+ return [
+ {
+ "role": "user",
+ "content": (
+ "My dbt model fct_revenue is failing in prod with SQL compilation error 001003. "
+ "Check the table catalog, inspect the schema, run dbt, and search the wiki for any "
+ "known migration guides. Then tell me exactly what to fix."
+ ),
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "call_tables",
+ "type": "function",
+ "function": {
+ "name": "snowflake_query",
+ "arguments": json.dumps(
+ {
+ "sql": "SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA = 'ANALYTICS'"
+ }
+ ),
+ },
+ }
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "call_tables",
+ "content": snowflake_tables_json(),
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "call_schema",
+ "type": "function",
+ "function": {
+ "name": "snowflake_query",
+ "arguments": json.dumps(
+ {"sql": "DESCRIBE TABLE PROD_DB.ANALYTICS.FCT_REVENUE"}
+ ),
+ },
+ }
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "call_schema",
+ "content": snowflake_schema_json(),
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "call_dbt",
+ "type": "function",
+ "function": {
+ "name": "bash",
+ "arguments": json.dumps(
+ {"command": "dbt run --select fct_revenue --target prod 2>&1"}
+ ),
+ },
+ }
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "call_dbt",
+ "content": dbt_run_results_json(),
+ },
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "call_search",
+ "type": "function",
+ "function": {
+ "name": "cortex_search",
+ "arguments": json.dumps(
+ {"query": "product_family column rename migration fct_revenue"}
+ ),
+ },
+ }
+ ],
+ },
+ {
+ "role": "tool",
+ "tool_call_id": "call_search",
+ "content": rag_cortex_search_json(),
+ },
+ {
+ "role": "assistant",
+ "content": (
+ "Found it. The column `product_family` was renamed to `product_group` in Q3 2024. "
+ "The fix is to update line 47 of `models/marts/revenue/fct_revenue.sql` and run "
+ "`dbt run --select fct_revenue --full-refresh`."
+ ),
+ },
+ {
+ "role": "user",
+ "content": "Perfect. Are there any other models in models/marts/revenue/ that reference product_family?",
+ },
+ ]
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _count_tokens_approx(messages: list[dict]) -> int:
+ """Approximate token count from serialised JSON (~4 chars/token)."""
+ return len(json.dumps(messages)) // 4
+
+
+def _table_row(label: str, before: int, after: int) -> str:
+ saved = before - after
+ pct = saved / max(before, 1) * 100
+ bar = "█" * int(pct / 5)
+ return f" {label:<35} {before:>7,} → {after:>7,} {pct:>5.1f}% {bar}"
+
+
+# ── Pytest tests ──────────────────────────────────────────────────────────────
+
+
+def test_cortex_code_headroom_compression_saves_tokens() -> None:
+ """Headroom must compress a realistic multi-turn CoCo session."""
+ from headroom import compress
+
+ messages = build_coco_session_messages()
+
+ t0 = time.perf_counter()
+ result = compress(messages, model=MODEL)
+ latency_ms = (time.perf_counter() - t0) * 1000
+
+ _ = result.tokens_saved / max(result.tokens_before, 1) * 100
+ print(f"\n{_table_row('Full CoCo session', result.tokens_before, result.tokens_after)}")
+ print(f" Latency: {latency_ms:.0f} ms Transforms: {', '.join(result.transforms_applied)}")
+
+ assert result.tokens_saved > 0, (
+ f"Expected compression on the multi-turn CoCo session. "
+ f"before={result.tokens_before}, after={result.tokens_after}. "
+ f"Transforms: {result.transforms_applied}"
+ )
+ assert len(result.messages) == len(messages), "Message count must not change"
+ assert result.messages[0]["content"] == messages[0]["content"], "User prompt must be verbatim"
+
+
+def test_cortex_code_tool_results_are_compressed_not_user_turns() -> None:
+ """User turn content must be identical before and after compression."""
+ from headroom import compress
+
+ messages = build_coco_session_messages()
+ result = compress(messages, model=MODEL)
+
+ user_orig = [m for m in messages if m.get("role") == "user"]
+ user_comp = [m for m in result.messages if m.get("role") == "user"]
+
+ assert len(user_orig) == len(user_comp)
+ for orig, comp in zip(user_orig, user_comp):
+ assert orig["content"] == comp["content"], (
+ f"User turn was mutated:\n before: {orig['content'][:80]!r}"
+ )
+
+
+def test_cortex_code_tables_json_compresses() -> None:
+ """Large Snowflake INFORMATION_SCHEMA result (JSON) must compress."""
+ from headroom import compress
+
+ messages = [
+ {"role": "user", "content": "List all tables in ANALYTICS schema."},
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "c1",
+ "type": "function",
+ "function": {
+ "name": "snowflake_query",
+ "arguments": json.dumps({"sql": "SELECT * FROM INFORMATION_SCHEMA.TABLES"}),
+ },
+ }
+ ],
+ },
+ {"role": "tool", "tool_call_id": "c1", "content": snowflake_tables_json()},
+ ]
+
+ result = compress(messages, model=MODEL)
+ _ = result.tokens_saved / max(result.tokens_before, 1) * 100
+ print(f"\n{_table_row('Tables JSON (79 rows)', result.tokens_before, result.tokens_after)}")
+
+ assert result.tokens_saved > 0, (
+ f"INFORMATION_SCHEMA tables JSON was not compressed. "
+ f"before={result.tokens_before}, after={result.tokens_after}. "
+ f"Payload size: {len(snowflake_tables_json())} chars."
+ )
+
+
+def test_cortex_code_rag_search_json_compresses() -> None:
+ """Cortex Search JSON results (repeated structure) must compress."""
+ from headroom import compress
+
+ messages = [
+ {"role": "user", "content": "Search for product_family migration guide."},
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "c2",
+ "type": "function",
+ "function": {
+ "name": "cortex_search",
+ "arguments": json.dumps({"query": "product_family rename"}),
+ },
+ }
+ ],
+ },
+ {"role": "tool", "tool_call_id": "c2", "content": rag_cortex_search_json()},
+ ]
+
+ result = compress(messages, model=MODEL)
+ _ = result.tokens_saved / max(result.tokens_before, 1) * 100
+ print(
+ f"\n{_table_row('Cortex Search JSON (15 docs)', result.tokens_before, result.tokens_after)}"
+ )
+
+ assert result.tokens_saved > 0, (
+ f"Cortex Search JSON was not compressed. "
+ f"before={result.tokens_before}, after={result.tokens_after}."
+ )
+
+
+def test_cortex_code_compression_is_lossless_on_key_content() -> None:
+ """Key answer tokens must survive compression (the model can still answer)."""
+ from headroom import compress
+
+ messages = [
+ {"role": "user", "content": "Search wiki for product_family rename."},
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "c3",
+ "type": "function",
+ "function": {
+ "name": "cortex_search",
+ "arguments": json.dumps({"query": "product_family"}),
+ },
+ }
+ ],
+ },
+ {"role": "tool", "tool_call_id": "c3", "content": rag_cortex_search_json()},
+ ]
+
+ result = compress(messages, model=MODEL)
+ compressed_tool = next(
+ (m.get("content", "") for m in result.messages if m.get("role") == "tool"), ""
+ )
+
+ # The critical answer ("product_group") must survive
+ key_terms = ["product_group", "migration", "dbt", "fct_revenue"]
+ found = [t for t in key_terms if t in str(compressed_tool)]
+ assert len(found) >= 2, (
+ f"Too many key terms lost in compression. "
+ f"Found: {found}, missing: {[t for t in key_terms if t not in found]}. "
+ f"Compressed output (first 500 chars): {str(compressed_tool)[:500]}"
+ )
+
+
+# ── Standalone benchmark ──────────────────────────────────────────────────────
+
+
+if __name__ == "__main__":
+ from headroom import compress
+
+ print()
+ print("=" * 65)
+ print(" Cortex Code × Headroom — token savings benchmark")
+ print(" (No API key needed — compression is fully local)")
+ print("=" * 65)
+
+ payloads = [
+ ("Full CoCo session (10 turns)", build_coco_session_messages),
+ (
+ "INFORMATION_SCHEMA tables (79 rows)",
+ lambda: [
+ {"role": "user", "content": "List tables."},
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "c1",
+ "type": "function",
+ "function": {"name": "q", "arguments": "{}"},
+ }
+ ],
+ },
+ {"role": "tool", "tool_call_id": "c1", "content": snowflake_tables_json()},
+ ],
+ ),
+ (
+ "Schema JSON (3 tables × 20 cols)",
+ lambda: [
+ {"role": "user", "content": "Describe schema."},
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "c1",
+ "type": "function",
+ "function": {"name": "q", "arguments": "{}"},
+ }
+ ],
+ },
+ {"role": "tool", "tool_call_id": "c1", "content": snowflake_schema_json()},
+ ],
+ ),
+ (
+ "dbt run-results JSON (40 models)",
+ lambda: [
+ {"role": "user", "content": "Run dbt."},
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "c1",
+ "type": "function",
+ "function": {"name": "q", "arguments": "{}"},
+ }
+ ],
+ },
+ {"role": "tool", "tool_call_id": "c1", "content": dbt_run_results_json()},
+ ],
+ ),
+ (
+ "Cortex Search JSON (15 docs)",
+ lambda: [
+ {"role": "user", "content": "Search wiki."},
+ {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [
+ {
+ "id": "c1",
+ "type": "function",
+ "function": {"name": "q", "arguments": "{}"},
+ }
+ ],
+ },
+ {"role": "tool", "tool_call_id": "c1", "content": rag_cortex_search_json()},
+ ],
+ ),
+ ]
+
+ print(f"\n {'Payload':<35} {'Before':>7} {'After':>7} {'Saved%':>6} Bar")
+ print(f" {'─' * 35} {'─' * 7} {'─' * 7} {'─' * 6} {'─' * 20}")
+
+ total_before = total_after = 0
+ for label, builder in payloads:
+ msgs = builder()
+ t0 = time.perf_counter()
+ r = compress(msgs, model=MODEL)
+ ms = (time.perf_counter() - t0) * 1000
+ total_before += r.tokens_before
+ total_after += r.tokens_after
+ print(f"{_table_row(label, r.tokens_before, r.tokens_after)} ({ms:.0f}ms)")
+
+ total_saved = total_before - total_after
+ total_pct = total_saved / max(total_before, 1) * 100
+ print(f"\n {'─' * 65}")
+ print(f"{_table_row('TOTAL', total_before, total_after)}")
+ print()
+ if total_saved > 0:
+ print(
+ f" PASS headroom saved {total_saved:,} tokens ({total_pct:.0f}%) across all CoCo payload types"
+ )
+ else:
+ print(" FAIL no compression — run: pip install 'headroom-ai[all]'")
+ print()
diff --git a/tests/test_provider_cortex_code.py b/tests/test_provider_cortex_code.py
new file mode 100644
index 000000000..dde4ed964
--- /dev/null
+++ b/tests/test_provider_cortex_code.py
@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from headroom.providers.cortex_code import build_install_env, proxy_base_url, render_setup_lines
+from headroom.providers.cortex_code.runtime import build_launch_env, default_api_url
+
+
+def test_cortex_code_proxy_base_url_is_openai_compatible() -> None:
+ assert proxy_base_url(8787) == "http://127.0.0.1:8787/v1"
+
+
+def test_cortex_code_proxy_base_url_uses_given_port() -> None:
+ assert proxy_base_url(9999) == "http://127.0.0.1:9999/v1"
+
+
+def test_cortex_code_build_install_env_sets_openai_base_url() -> None:
+ env = build_install_env(port=8787, backend="ignored")
+ assert env == {"OPENAI_BASE_URL": "http://127.0.0.1:8787/v1"}
+
+
+def test_cortex_code_build_launch_env_does_not_mutate_input() -> None:
+ source = {"EXISTING": "val"}
+ env, lines = build_launch_env(port=9999, environ=source)
+ assert source == {"EXISTING": "val"}
+ assert env["OPENAI_BASE_URL"] == "http://127.0.0.1:9999/v1"
+ assert lines == ["OPENAI_BASE_URL=http://127.0.0.1:9999/v1"]
+
+
+def test_cortex_code_build_launch_env_applies_project_prefix() -> None:
+ env, lines = build_launch_env(port=9999, environ={}, project="myrepo")
+ assert env["OPENAI_BASE_URL"] == "http://127.0.0.1:9999/p/myrepo/v1"
+ assert lines == ["OPENAI_BASE_URL=http://127.0.0.1:9999/p/myrepo/v1"]
+
+
+def test_cortex_code_build_launch_env_ignores_blank_project() -> None:
+ env, lines = build_launch_env(port=9999, environ={}, project=" ")
+ assert env["OPENAI_BASE_URL"] == "http://127.0.0.1:9999/v1"
+ assert lines == ["OPENAI_BASE_URL=http://127.0.0.1:9999/v1"]
+
+
+def test_cortex_code_render_setup_lines_contains_proxy_url() -> None:
+ lines = render_setup_lines(8787)
+ joined = "\n".join(lines)
+ assert "http://127.0.0.1:8787/v1" in joined
+ assert "Cortex Code" in joined
+
+
+def test_cortex_code_render_setup_lines_project_attribution() -> None:
+ lines = render_setup_lines(8787, project="my-sf-project")
+ joined = "\n".join(lines)
+ assert "my-sf-project" in joined
+ plain = "\n".join(render_setup_lines(8787))
+ assert "attributed" not in plain
+
+
+def test_cortex_code_default_api_url_reads_snowflake_host_env() -> None:
+ url = default_api_url({"SNOWFLAKE_HOST": "myaccount.snowflakecomputing.com"})
+ assert url == "https://myaccount.snowflakecomputing.com"
+
+
+def test_cortex_code_default_api_url_constructs_url_from_account_name() -> None:
+ url = default_api_url({"SNOWFLAKE_ACCOUNT": "myaccount"})
+ assert url == "https://myaccount.snowflakecomputing.com"
+
+
+def test_cortex_code_default_api_url_host_takes_priority_over_account() -> None:
+ url = default_api_url(
+ {
+ "SNOWFLAKE_HOST": "host.snowflakecomputing.com",
+ "SNOWFLAKE_ACCOUNT": "account",
+ }
+ )
+ assert url == "https://host.snowflakecomputing.com"
+
+
+def test_cortex_code_default_api_url_falls_back_when_no_env() -> None:
+ url = default_api_url({})
+ assert url == "https://app.snowflake.com"
+
+
+def test_cortex_code_default_api_url_preserves_https_prefix() -> None:
+ url = default_api_url({"SNOWFLAKE_HOST": "https://already.snowflakecomputing.com"})
+ assert url == "https://already.snowflakecomputing.com"
+
+
+def test_cortex_code_install_registry_includes_cortex_code() -> None:
+ from headroom.providers.install_registry import build_install_target_envs
+
+ result = build_install_target_envs(port=1234, backend="ignored", targets=["cortex-code"])
+ assert result["cortex-code"]["OPENAI_BASE_URL"] == "http://127.0.0.1:1234/v1"
+
+
+def test_cortex_code_install_registry_unknown_target_skipped() -> None:
+ from headroom.providers.install_registry import build_install_target_envs
+
+ result = build_install_target_envs(
+ port=1234, backend="ignored", targets=["cortex-code", "unknown-tool"]
+ )
+ assert "unknown-tool" not in result
+ assert "cortex-code" in result