mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
## Description Adds a gateway turn contract to `POST /v1/compress`, allowing an API gateway to submit a complete provider request and later report the provider response. Requests without a top-level `gateway` object remain unchanged. ## Type of Change - [x] Bug fix (non-breaking change that fixes an issue) - [x] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - Adds the request half to `/v1/compress` and the response half at `/v1/compress/response`, including bounded pending turns, idempotent rounds, usage relay, and redrive obligations. - Adds a reusable six-stage compress-turn extension seam and turn-hook priority/provider-header support. - Keeps native tool-schema deferral in the licensed extension while sharing protocol-shape helpers with core. - Accepts Anthropic, OpenAI chat, OpenAI Responses, and Kong-shaped usage payloads. - Documents the gateway contract in `docs/content/docs/proxy.mdx` and `wiki/proxy.md`. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text tests/gateway + gateway unit + turn-hook seam + test_issue_746_tool_search: 358 passed ruff 0.16.3 lint/format and mypy on touched modules: clean Kong 3.9 Docker e2e (HEADROOM_KONG_E2E=1): 4 passed ``` ## Real Behavior Proof - Environment: Kong 3.9 Docker e2e and real-provider Claude Code through Kong on SWE-bench-mini. - Exact command / steps: `HEADROOM_KONG_E2E=1` gateway e2e; real-provider traffic through the gateway contract with usage relay and licensed native deferral. - Observed result: four Kong e2e tests passed; prefix cache remained intact with zero busts; relayed usage matched Anthropic token-for-token; licensed tool-search deferral reduced cache-read tokens per turn by 27–30%. - Not tested: production rollout at scale. ## Runtime Rollout Safety - Rollout-managed feature(s): gateway contract and in-process pending-turn registry. - Minimum rollout channel: controlled gateway deployment before broader enablement. - Stable/default behavior changed: only requests containing a top-level `gateway` object enter the new contract; ordinary `/v1/compress` bodies are unchanged. - Kill switch / disable path: set `HEADROOM_GATEWAY_CONTRACT=0`. - Unsafe override required: no. - Qualification impact: gateway callers must redeem advertised `redrive` and `relay_usage` obligations. - Rollback path: disable the contract with `HEADROOM_GATEWAY_CONTRACT=0` or revert the feature commit. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) Not applicable; this is an API contract change. ## Additional Notes Pending turns are process-local and bounded by `HEADROOM_GATEWAY_TURN_TTL_SECONDS`, `HEADROOM_GATEWAY_MAX_PENDING_TURNS`, and `HEADROOM_GATEWAY_MAX_REDRIVES`. Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
171 lines
5.7 KiB
Python
171 lines
5.7 KiB
Python
"""Deterministic sample payloads shared by the gateway contract tests.
|
|
|
|
Everything here is a pure function of its arguments so two calls produce
|
|
byte-identical JSON - the byte-stability invariants depend on that.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
from typing import Any
|
|
|
|
# --------------------------------------------------------------------------- #
|
|
# Conversations #
|
|
# --------------------------------------------------------------------------- #
|
|
|
|
|
|
def big_tool_history(n_items: int = 200, call_id: str = "c1") -> list[dict[str, Any]]:
|
|
"""A chat-completions conversation whose tool result is large enough to be
|
|
compressed (mirrors ``tests/test_compress_session_mode.py::_big_tool_history``)."""
|
|
items = [
|
|
{
|
|
"id": i,
|
|
"score": 0.99 if i % 30 == 0 else 0.6,
|
|
"msg": f"Result {i:03d}{' error' if i % 30 == 0 else ' ok'}",
|
|
"blob": f"payload-{i:04d}-" + "".join(chr(97 + (i * 7 + j) % 26) for j in range(240)),
|
|
}
|
|
for i in range(n_items)
|
|
]
|
|
return [
|
|
{"role": "user", "content": "Get items"},
|
|
{
|
|
"role": "assistant",
|
|
"content": None,
|
|
"tool_calls": [
|
|
{
|
|
"id": call_id,
|
|
"type": "function",
|
|
"function": {"name": "get_items", "arguments": "{}"},
|
|
}
|
|
],
|
|
},
|
|
{"role": "tool", "tool_call_id": call_id, "content": json.dumps(items)},
|
|
]
|
|
|
|
|
|
def anthropic_tool_history(n_items: int = 200) -> list[dict[str, Any]]:
|
|
"""The same conversation in Anthropic Messages shape."""
|
|
items = [
|
|
{"id": i, "msg": f"Result {i:03d}", "blob": f"payload-{i:04d}-" + "x" * 200}
|
|
for i in range(n_items)
|
|
]
|
|
return [
|
|
{"role": "user", "content": "Get items"},
|
|
{
|
|
"role": "assistant",
|
|
"content": [
|
|
{"type": "tool_use", "id": "toolu_1", "name": "get_items", "input": {}},
|
|
],
|
|
},
|
|
{
|
|
"role": "user",
|
|
"content": [
|
|
{"type": "tool_result", "tool_use_id": "toolu_1", "content": json.dumps(items)}
|
|
],
|
|
},
|
|
]
|
|
|
|
|
|
# --------------------------------------------------------------------------- #
|
|
# Tools #
|
|
# --------------------------------------------------------------------------- #
|
|
|
|
|
|
def _verbose_params(prefix: str) -> dict[str, Any]:
|
|
return {
|
|
"type": "object",
|
|
"properties": {
|
|
"query": {
|
|
"type": "string",
|
|
"description": (
|
|
f"The {prefix} query string. This description is deliberately long so "
|
|
"that the tool schema compaction pass has something to remove. " * 3
|
|
),
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Maximum number of results to return. " * 4,
|
|
"default": 10,
|
|
},
|
|
},
|
|
"required": ["query"],
|
|
"additionalProperties": False,
|
|
}
|
|
|
|
|
|
def openai_tools(deferred_prefix: str = "deferred_") -> list[dict[str, Any]]:
|
|
"""Chat-completions tools: one core tool plus two deferrable ones.
|
|
|
|
``deferred_prefix`` matches ``redrive_hook_ext.RedriveHook``'s default so a
|
|
test can register the hook with no arguments.
|
|
"""
|
|
return [
|
|
{
|
|
"type": "function",
|
|
"function": {
|
|
"name": "get_items",
|
|
"description": "Fetch the item list from the catalogue service.",
|
|
"parameters": _verbose_params("catalogue"),
|
|
},
|
|
},
|
|
{
|
|
"type": "function",
|
|
"function": {
|
|
"name": f"{deferred_prefix}create_issue",
|
|
"description": "Create a GitHub issue in the given repository.",
|
|
"parameters": _verbose_params("issue"),
|
|
},
|
|
},
|
|
{
|
|
"type": "function",
|
|
"function": {
|
|
"name": f"{deferred_prefix}query_db",
|
|
"description": "Run a read-only SQL query against Postgres.",
|
|
"parameters": _verbose_params("sql"),
|
|
},
|
|
},
|
|
]
|
|
|
|
|
|
def anthropic_tools(deferred_prefix: str = "deferred_") -> list[dict[str, Any]]:
|
|
"""The same three tools in Anthropic Messages shape."""
|
|
return [
|
|
{
|
|
"name": "get_items",
|
|
"description": "Fetch the item list from the catalogue service.",
|
|
"input_schema": _verbose_params("catalogue"),
|
|
},
|
|
{
|
|
"name": f"{deferred_prefix}create_issue",
|
|
"description": "Create a GitHub issue in the given repository.",
|
|
"input_schema": _verbose_params("issue"),
|
|
},
|
|
{
|
|
"name": f"{deferred_prefix}query_db",
|
|
"description": "Run a read-only SQL query against Postgres.",
|
|
"input_schema": _verbose_params("sql"),
|
|
},
|
|
]
|
|
|
|
|
|
def tool_names(tools: Any) -> list[str]:
|
|
"""Names of every tool in either provider shape (order preserved)."""
|
|
out: list[str] = []
|
|
for t in tools or []:
|
|
if not isinstance(t, dict):
|
|
continue
|
|
fn = t.get("function")
|
|
if isinstance(fn, dict) and fn.get("name"):
|
|
out.append(str(fn["name"]))
|
|
elif t.get("name"):
|
|
out.append(str(t["name"]))
|
|
return out
|
|
|
|
|
|
def canonical(value: Any) -> str:
|
|
"""The byte-stability yardstick: sorted-key JSON."""
|
|
return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
|
|
|
|
|
|
SYSTEM_PROMPT = "You are a terse assistant. Answer in one sentence."
|