hedit 0.7.11.dev3__tar.gz → 0.7.11.dev6__tar.gz

{hedit-0.7.11.dev3/hedit.egg-info → hedit-0.7.11.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hedit
-Version: 0.7.11.dev3
+Version: 0.7.11.dev6
 Summary: Multi-agent system for HED annotation generation and validation
 Author-email: Annotation Garden Initiative <info@annotation.garden>
 License-Expression: MIT

{hedit-0.7.11.dev3 → hedit-0.7.11.dev6}/README.md

@@ -67,6 +67,7 @@ Config files are stored in `~/.config/hedit/`:
 - **Image Annotation**: Annotate visual stimuli directly from image files
 - **Multi-Stage Validation**: AI agents generate, validate, evaluate, and refine annotations
 - **Claude-Powered**: Anthropic Claude models (Haiku 4.5 default, Sonnet 5 optional); bring your own Anthropic key if you prefer your own billing
+- **Cost Transparency**: Every annotation reports its token use and how much prompt caching saved (typically ~80% of input cost after the first request)
 - **JSON Output**: Easy integration with scripts and pipelines
 - **HED Schema Support**: Works with official HED schemas (8.x)
 
@@ -83,6 +84,9 @@ The agents work in feedback loops, automatically refining the annotation until i
 
 ## Documentation
 
+- [Changelog](CHANGELOG.md) - What changed in each release
+- [Prompt Caching and Usage Reporting](docs/prompt-caching.md) - What HEDit caches, what it saves, and where to see the numbers
+- [Extended Thinking](docs/reasoning.md) - Measured effect of reasoning per agent role, and how to tune it
 - [HED Standard](https://hedtags.org) - Learn about HED annotations
 - [GitHub Issues](https://github.com/Annotation-Garden/HEDit/issues) - Report bugs or request features
 
@@ -234,6 +238,7 @@ uvicorn src.api.main:app --reload --host 0.0.0.0 --port 38427
 - `POST /annotate`: Generate HED annotation from natural language
 - `POST /validate`: Validate HED annotation
 - `GET /health`: Health check
+- `GET /metrics`: Token use, cost, and prompt-cache savings since startup (server API key required)
 - API URL: `http://localhost:38427`
 
 ## Development

{hedit-0.7.11.dev3 → hedit-0.7.11.dev6/hedit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hedit
-Version: 0.7.11.dev3
+Version: 0.7.11.dev6
 Summary: Multi-agent system for HED annotation generation and validation
 Author-email: Annotation Garden Initiative <info@annotation.garden>
 License-Expression: MIT

{hedit-0.7.11.dev3 → hedit-0.7.11.dev6}/hedit.egg-info/SOURCES.txt

@@ -56,6 +56,7 @@ src/utils/hed_comprehensive_guide.py
 src/utils/hed_docs_loader.py
 src/utils/image_processing.py
 src/utils/json_schema_loader.py
+src/utils/llm_usage.py
 src/utils/schema_loader.py
 src/validation/__init__.py
 src/validation/hed_lsp.py
@@ -67,6 +68,7 @@ tests/test_cli_client.py
 tests/test_cli_config.py
 tests/test_cli_integration.py
 tests/test_cli_main.py
+tests/test_cli_usage_report.py
 tests/test_comprehensive_guide.py
 tests/test_error_remediation.py
 tests/test_feedback_integration.py
@@ -76,6 +78,7 @@ tests/test_github_client.py
 tests/test_hed_docs_loader.py
 tests/test_integration_anthropic.py
 tests/test_json_schema_loader.py
+tests/test_llm_usage.py
 tests/test_no_extend_propagation.py
 tests/test_schema_loader.py
 tests/test_security.py

{hedit-0.7.11.dev3 → hedit-0.7.11.dev6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hedit"
-version = "0.7.11.dev3"
+version = "0.7.11.dev6"
 description = "Multi-agent system for HED annotation generation and validation"
 readme = "PKG_README.md"
 requires-python = ">=3.12"

{hedit-0.7.11.dev3 → hedit-0.7.11.dev6}/src/api/main.py

@@ -10,6 +10,7 @@ import logging
 import os
 import time
 from contextlib import asynccontextmanager
+from datetime import UTC, datetime
 from pathlib import Path
 
 import anthropic
@@ -31,13 +32,21 @@ from src.api.models import (
     HealthResponse,
     ImageAnnotationRequest,
     ImageAnnotationResponse,
+    MetricsResponse,
+    UsageSummary,
     ValidationRequest,
     ValidationResponse,
 )
 from src.api.security import api_key_auth, audit_logger
 from src.lsp import HedLspClient
 from src.telemetry import LocalFileStorage, TelemetryCollector, TelemetryEvent
-from src.utils.anthropic_llm import DEFAULT_MODEL, create_anthropic_llm, normalize_model
+from src.utils.anthropic_llm import (
+    DEFAULT_MODEL,
+    annotation_thinking,
+    create_anthropic_llm,
+    normalize_model,
+)
+from src.utils.llm_usage import UsageLedger, process_ledger, usage_scope
 from src.utils.schema_loader import HedSchemaLoader
 from src.validation.hed_validator import HedPythonValidator
 
@@ -56,6 +65,7 @@ lsp_client: HedLspClient | None = None
 
 # Telemetry collector (initialized in lifespan)
 telemetry_collector: TelemetryCollector | None = None
+_startup_time: str = datetime.now(UTC).isoformat()
 
 # Cache for BYOK configuration
 _byok_config: dict = {}
@@ -100,6 +110,41 @@ def _describe_llm_error(exc: Exception) -> tuple[int, str, str]:
 _USE_GLOBAL_LSP: HedLspClient = object()  # type: ignore[assignment]
 
 
+def _usage_summary(ledger: UsageLedger) -> UsageSummary | None:
+    """Build the response's usage figures from a request's usage ledger.
+
+    Returns None when no LLM call was recorded (a fully cached or failed
+    request), so clients can tell "no calls" from "zero cost".
+
+    Args:
+        ledger: Ledger collected for one request
+
+    Returns:
+        UsageSummary, or None when nothing was recorded
+    """
+    totals = ledger.total()
+    if totals.calls == 0:
+        return None
+    return UsageSummary(**totals.as_dict())
+
+
+def _override_header(req: Request, name: str) -> str | None:
+    """Read a per-request override header, preferring the X-Anthropic-* spelling.
+
+    The X-OpenRouter-* names are the wire spelling from before the Anthropic
+    migration. They remain accepted indefinitely so that cached frontends and
+    third-party clients keep working; current clients send X-Anthropic-*.
+
+    Args:
+        req: Incoming request
+        name: Header suffix, e.g. "model" for X-Anthropic-Model
+
+    Returns:
+        Header value, or None when neither spelling is present
+    """
+    return req.headers.get(f"x-anthropic-{name}") or req.headers.get(f"x-openrouter-{name}")
+
+
 def _resolve_lsp_client(
     explicit: HedLspClient | None,
 ) -> HedLspClient | None:
@@ -160,13 +205,16 @@ def create_anthropic_workflow(
     normalize_model(actual_eval_model)
 
     # Create LLMs.
-    # The annotation LLM keeps reasoning enabled — that's the model
-    # doing the actual HED tag synthesis where extended thinking
-    # measurably improves first-attempt quality.
+    # Annotation thinks: measured over the benchmark descriptions, a 2048-token
+    # budget took first-attempt validity from 5/15 to 13/15 and cut total LLM
+    # calls by a third, for 24% more cost and about twice the latency. See
+    # annotation_thinking() and docs/prompt-caching.md.
     annotation_llm = create_anthropic_llm(
         model=actual_annotation_model,
         api_key=api_key,
         temperature=actual_temperature,
+        thinking=annotation_thinking(actual_annotation_model),
+        role="annotation",
     )
     # Evaluation / assessment / feedback / keyword extraction are short
     # structured tasks; reasoning adds 5-10 s per call without
@@ -176,18 +224,21 @@ def create_anthropic_workflow(
         api_key=api_key,
         temperature=actual_temperature,
         disable_reasoning=True,
+        role="evaluation",
     )
     assessment_llm = create_anthropic_llm(
         model=actual_eval_model,
         api_key=api_key,
         temperature=actual_temperature,
         disable_reasoning=True,
+        role="assessment",
     )
     feedback_llm = create_anthropic_llm(
         model=actual_eval_model,
         api_key=api_key,
         temperature=actual_temperature,
         disable_reasoning=True,
+        role="feedback",
     )
     # Keyword extraction (#148): use the fast annotation model with
     # reasoning explicitly disabled and a small token cap. The
@@ -199,6 +250,7 @@ def create_anthropic_workflow(
         temperature=actual_temperature,
         max_tokens=200,
         disable_reasoning=True,
+        role="keyword",
     )
 
     # Create and return workflow
@@ -283,6 +335,7 @@ def create_vision_agent(
         model=actual_model,
         api_key=api_key,
         temperature=actual_temperature,
+        role="vision",
     )
 
     return VisionAgent(llm=vision_llm)
@@ -477,6 +530,9 @@ async def lifespan(app: FastAPI):
             exc_info=True,
         )
 
+    global _startup_time
+    _startup_time = datetime.now(UTC).isoformat()
+
     # Initialize telemetry collector
     global telemetry_collector
     # Use /app/telemetry in Docker, otherwise use local .hedit/telemetry
@@ -555,13 +611,18 @@ app.add_middleware(
         "X-Requested-With",
         "X-API-Key",
         "X-Anthropic-Key",  # BYOK mode (Anthropic API key)
-        "X-OpenRouter-Key",  # Legacy BYOK header (still accepted as transport)
-        "X-OpenRouter-Model",  # Model override
-        "X-OpenRouter-Vision-Model",  # Vision model override
+        "X-Anthropic-Model",  # Model override
+        "X-Anthropic-Eval-Model",  # Eval model override
+        "X-Anthropic-Vision-Model",  # Vision model override
+        "X-Anthropic-Temperature",  # Temperature override
+        # Legacy X-OpenRouter-* spellings, still accepted as transport
+        "X-OpenRouter-Key",
+        "X-OpenRouter-Model",
+        "X-OpenRouter-Vision-Model",
         "X-OpenRouter-Vision-Provider",  # Legacy, ignored
         "X-OpenRouter-Provider",  # Legacy, ignored
-        "X-OpenRouter-Temperature",  # Temperature override
-        "X-OpenRouter-Eval-Model",  # Eval model override
+        "X-OpenRouter-Temperature",
+        "X-OpenRouter-Eval-Model",
         "X-OpenRouter-Eval-Provider",  # Legacy, ignored
         "X-User-Id",  # Legacy, ignored
     ],
@@ -646,9 +707,9 @@ async def annotate(
     """
     # Determine which workflow to use
     # Check for model override headers (from frontend dropdown or CLI)
-    model_override = request.model or req.headers.get("x-openrouter-model")
-    eval_model_override = req.headers.get("x-openrouter-eval-model")
-    temp_header = req.headers.get("x-openrouter-temperature")
+    model_override = request.model or _override_header(req, "model")
+    eval_model_override = _override_header(req, "eval-model")
+    temp_header = _override_header(req, "temperature")
     temperature = request.temperature
     if temperature is None and temp_header:
         try:
@@ -658,7 +719,7 @@ async def annotate(
 
     if api_key == "byok":
         # BYOK mode: Create workflow with user's Anthropic key
-        byok_key = req.headers.get("x-anthropic-key") or req.headers.get("x-openrouter-key")
+        byok_key = _override_header(req, "key")
         if not byok_key:
             raise HTTPException(status_code=401, detail="Missing X-Anthropic-Key header")
 
@@ -707,14 +768,15 @@ async def annotate(
         config = {"recursion_limit": 50}
 
         start_time = time.time()
-        final_state = await active_workflow.run(
-            input_description=request.description,
-            schema_version=request.schema_version,
-            max_validation_attempts=request.max_validation_attempts,
-            run_assessment=request.run_assessment,
-            no_extend=request.no_extend,
-            config=config,
-        )
+        with usage_scope() as usage:
+            final_state = await active_workflow.run(
+                input_description=request.description,
+                schema_version=request.schema_version,
+                max_validation_attempts=request.max_validation_attempts,
+                run_assessment=request.run_assessment,
+                no_extend=request.no_extend,
+                config=config,
+            )
         latency_ms = int((time.time() - start_time) * 1000)
 
         # Determine overall status
@@ -728,12 +790,12 @@ async def annotate(
             # Get model info from request body, BYOK headers, or server config
             model_name = (
                 request.model
-                or req.headers.get("x-openrouter-model")
+                or _override_header(req, "model")
                 or os.getenv("ANNOTATION_MODEL", DEFAULT_MODEL)
             )
             temperature = request.temperature
             if temperature is None:
-                temp_header = req.headers.get("x-openrouter-temperature")
+                temp_header = _override_header(req, "temperature")
                 if temp_header is not None:
                     try:
                         temperature = float(temp_header)
@@ -753,6 +815,7 @@ async def annotate(
                 temperature=temperature,
                 latency_ms=latency_ms,
                 source="api",
+                usage=usage.total(),
             )
             await telemetry_collector.collect(event)
 
@@ -767,6 +830,7 @@ async def annotate(
             evaluation_feedback=final_state["evaluation_feedback"],
             assessment_feedback=final_state["assessment_feedback"],
             status=status,
+            usage=_usage_summary(usage),
         )
 
     except Exception as e:
@@ -803,10 +867,10 @@ async def annotate_from_image(
     """
     # Determine which workflow and vision agent to use
     # Check for model override headers (from frontend dropdown or CLI)
-    model_override = request.model or req.headers.get("x-openrouter-model")
-    vision_model_override = request.vision_model or req.headers.get("x-openrouter-vision-model")
-    eval_model_override = req.headers.get("x-openrouter-eval-model")
-    temp_header = req.headers.get("x-openrouter-temperature")
+    model_override = request.model or _override_header(req, "model")
+    vision_model_override = request.vision_model or _override_header(req, "vision-model")
+    eval_model_override = _override_header(req, "eval-model")
+    temp_header = _override_header(req, "temperature")
     temperature = request.temperature
     if temperature is None and temp_header:
         try:
@@ -816,7 +880,7 @@ async def annotate_from_image(
 
     if api_key == "byok":
         # BYOK mode: Create workflow and vision agent with user's Anthropic key
-        byok_key = req.headers.get("x-anthropic-key") or req.headers.get("x-openrouter-key")
+        byok_key = _override_header(req, "key")
         if not byok_key:
             raise HTTPException(status_code=401, detail="Missing X-Anthropic-Key header")
 
@@ -878,26 +942,29 @@ async def annotate_from_image(
     try:
         start_time = time.time()
 
-        # Step 1: Generate image description using vision model
-        vision_result = await active_vision_agent.describe_image(
-            image_data=request.image,
-            custom_prompt=request.prompt,
-        )
+        # The vision call and the annotation workflow share one usage scope
+        # so the reported figures cover the whole request.
+        with usage_scope() as usage:
+            # Step 1: Generate image description using vision model
+            vision_result = await active_vision_agent.describe_image(
+                image_data=request.image,
+                custom_prompt=request.prompt,
+            )
 
-        image_description = vision_result["description"]
-        image_metadata = vision_result["metadata"]
+            image_description = vision_result["description"]
+            image_metadata = vision_result["metadata"]
 
-        # Step 2: Pass description through HED annotation workflow
-        config = {"recursion_limit": 50}
+            # Step 2: Pass description through HED annotation workflow
+            config = {"recursion_limit": 50}
 
-        final_state = await active_workflow.run(
-            input_description=image_description,
-            schema_version=request.schema_version,
-            max_validation_attempts=request.max_validation_attempts,
-            run_assessment=request.run_assessment,
-            no_extend=request.no_extend,
-            config=config,
-        )
+            final_state = await active_workflow.run(
+                input_description=image_description,
+                schema_version=request.schema_version,
+                max_validation_attempts=request.max_validation_attempts,
+                run_assessment=request.run_assessment,
+                no_extend=request.no_extend,
+                config=config,
+            )
         latency_ms = int((time.time() - start_time) * 1000)
 
         # Determine overall status
@@ -909,12 +976,12 @@ async def annotate_from_image(
             # Get model info from request body, BYOK headers, or server config
             model_name = (
                 request.model
-                or req.headers.get("x-openrouter-model")
+                or _override_header(req, "model")
                 or os.getenv("ANNOTATION_MODEL", DEFAULT_MODEL)
             )
             temperature = request.temperature
             if temperature is None:
-                temp_header = req.headers.get("x-openrouter-temperature")
+                temp_header = _override_header(req, "temperature")
                 if temp_header is not None:
                     try:
                         temperature = float(temp_header)
@@ -934,6 +1001,7 @@ async def annotate_from_image(
                 temperature=temperature,
                 latency_ms=latency_ms,
                 source="api-image",  # Distinguish from text-based annotation
+                usage=usage.total(),
             )
             await telemetry_collector.collect(event)
 
@@ -950,6 +1018,7 @@ async def annotate_from_image(
             assessment_feedback=final_state["assessment_feedback"],
             status=status,
             image_metadata=image_metadata,
+            usage=_usage_summary(usage),
         )
 
     except Exception as e:
@@ -965,6 +1034,7 @@ async def _collect_stream_telemetry(
     start_time: float,
     source: str,
     description: str,
+    usage: UsageLedger | None = None,
 ) -> None:
     """Collect telemetry for streaming endpoints.
 
@@ -978,6 +1048,7 @@ async def _collect_stream_telemetry(
         start_time: Workflow start time (from time.time())
         source: Telemetry source identifier (e.g., "api-stream", "api-image-stream")
         description: Input description text (or image description for image endpoints)
+        usage: Usage ledger for this request, when one was collected
     """
     if not request.telemetry_enabled or not telemetry_collector:
         return
@@ -987,12 +1058,12 @@ async def _collect_stream_telemetry(
     # Get model info from request body, BYOK headers, or server config
     model_name = (
         request.model
-        or req.headers.get("x-openrouter-model")
+        or _override_header(req, "model")
         or os.getenv("ANNOTATION_MODEL", DEFAULT_MODEL)
     )
     temperature = request.temperature
     if temperature is None:
-        temp_header = req.headers.get("x-openrouter-temperature")
+        temp_header = _override_header(req, "temperature")
         if temp_header is not None:
             try:
                 temperature = float(temp_header)
@@ -1012,6 +1083,7 @@ async def _collect_stream_telemetry(
         temperature=temperature,
         latency_ms=latency_ms,
         source=source,
+        usage=usage.total() if usage is not None else None,
     )
     await telemetry_collector.collect(event)
 
@@ -1044,9 +1116,9 @@ async def annotate_stream(
     from src.agents.state import create_initial_state
 
     # Determine which workflow to use (same logic as /annotate)
-    model_override = request.model or req.headers.get("x-openrouter-model")
-    eval_model_override = req.headers.get("x-openrouter-eval-model")
-    temp_header = req.headers.get("x-openrouter-temperature")
+    model_override = request.model or _override_header(req, "model")
+    eval_model_override = _override_header(req, "eval-model")
+    temp_header = _override_header(req, "temperature")
     temperature = request.temperature
     if temperature is None and temp_header:
         try:
@@ -1055,7 +1127,7 @@ async def annotate_stream(
             pass  # Invalid header value, use default temperature
 
     if api_key == "byok":
-        byok_key = req.headers.get("x-anthropic-key") or req.headers.get("x-openrouter-key")
+        byok_key = _override_header(req, "key")
         if not byok_key:
             raise HTTPException(status_code=401, detail="Missing X-Anthropic-Key header")
         try:
@@ -1112,7 +1184,7 @@ async def annotate_stream(
         "assess": ("assessing", "Running final assessment..."),
     }
 
-    async def event_generator():
+    async def event_generator(usage: UsageLedger):
         """Generate SSE events for workflow progress using LangGraph streaming."""
 
         def send_event(event_type: str, data: dict) -> str:
@@ -1211,6 +1283,9 @@ async def annotate_stream(
                 "assessment_feedback": current_state.get("assessment_feedback", ""),
                 "status": status,
             }
+            usage_summary = _usage_summary(usage)
+            if usage_summary is not None:
+                result["usage"] = usage_summary.model_dump()
 
             yield send_event("result", result)
 
@@ -1223,6 +1298,7 @@ async def annotate_stream(
                     start_time=start_time,
                     source="api-stream",
                     description=request.description,
+                    usage=usage,
                 )
             except Exception:
                 logging.warning("Telemetry collection failed for streaming request", exc_info=True)
@@ -1244,13 +1320,25 @@ async def annotate_stream(
                     start_time=start_time,
                     source="api-stream",
                     description=request.description,
+                    usage=usage,
                 )
             except Exception:
                 logging.warning("Telemetry collection failed on error", exc_info=True)
             yield send_event("done", {"message": "Workflow ended with error"})
 
+    async def streamed_events():
+        """Hold one usage scope open for the whole stream.
+
+        The scope lives outside the generator that runs the workflow so that
+        every LLM call made while the response streams is attributed to this
+        request.
+        """
+        with usage_scope() as usage:
+            async for chunk in event_generator(usage):
+                yield chunk
+
     return StreamingResponse(
-        event_generator(),
+        streamed_events(),
         media_type="text/event-stream",
         headers={
             "Cache-Control": "no-cache",
@@ -1289,10 +1377,10 @@ async def annotate_from_image_stream(
     from src.agents.state import create_initial_state
 
     # Determine which workflow and vision agent to use (same logic as /annotate-from-image)
-    model_override = request.model or req.headers.get("x-openrouter-model")
-    vision_model_override = request.vision_model or req.headers.get("x-openrouter-vision-model")
-    eval_model_override = req.headers.get("x-openrouter-eval-model")
-    temp_header = req.headers.get("x-openrouter-temperature")
+    model_override = request.model or _override_header(req, "model")
+    vision_model_override = request.vision_model or _override_header(req, "vision-model")
+    eval_model_override = _override_header(req, "eval-model")
+    temp_header = _override_header(req, "temperature")
     temperature = request.temperature
     if temperature is None and temp_header:
         try:
@@ -1301,7 +1389,7 @@ async def annotate_from_image_stream(
             pass
 
     if api_key == "byok":
-        byok_key = req.headers.get("x-anthropic-key") or req.headers.get("x-openrouter-key")
+        byok_key = _override_header(req, "key")
         if not byok_key:
             raise HTTPException(status_code=401, detail="Missing X-Anthropic-Key header")
         try:
@@ -1365,7 +1453,7 @@ async def annotate_from_image_stream(
         "assess": ("assessing", "Running final assessment..."),
     }
 
-    async def event_generator():
+    async def event_generator(usage: UsageLedger):
         """Generate SSE events for image annotation workflow progress."""
 
         def send_event(event_type: str, data: dict) -> str:
@@ -1496,6 +1584,9 @@ async def annotate_from_image_stream(
                 "status": status,
                 "image_metadata": image_metadata,
             }
+            usage_summary = _usage_summary(usage)
+            if usage_summary is not None:
+                result["usage"] = usage_summary.model_dump()
 
             yield send_event("result", result)
 
@@ -1508,6 +1599,7 @@ async def annotate_from_image_stream(
                     start_time=start_time,
                     source="api-image-stream",
                     description=image_description,
+                    usage=usage,
                 )
             except Exception:
                 logging.debug(
@@ -1531,13 +1623,25 @@ async def annotate_from_image_stream(
                     start_time=start_time,
                     source="api-image-stream",
                     description=image_description or "image-annotation-failed",
+                    usage=usage,
                 )
             except Exception:
                 logging.warning("Telemetry collection failed on image error", exc_info=True)
             yield send_event("done", {"message": "Workflow ended with error"})
 
+    async def streamed_events():
+        """Hold one usage scope open for the whole stream.
+
+        The scope lives outside the generator that runs the workflow so that
+        every LLM call made while the response streams is attributed to this
+        request.
+        """
+        with usage_scope() as usage:
+            async for chunk in event_generator(usage):
+                yield chunk
+
     return StreamingResponse(
-        event_generator(),
+        streamed_events(),
         media_type="text/event-stream",
         headers={
             "Cache-Control": "no-cache",
@@ -1608,7 +1712,6 @@ async def submit_feedback(request: FeedbackRequest) -> FeedbackResponse:
     Returns:
         FeedbackResponse with feedback ID and status
     """
-    from datetime import datetime
     from uuid import uuid4
 
     try:
@@ -1683,6 +1786,7 @@ async def submit_feedback(request: FeedbackRequest) -> FeedbackResponse:
                     model=model,
                     temperature=0.1,
                     max_tokens=1000,
+                    role="triage",
                 )
 
                 # Create and run triage agent
@@ -1737,6 +1841,39 @@ async def submit_feedback(request: FeedbackRequest) -> FeedbackResponse:
         ) from e
 
 
+@app.get("/metrics", response_model=MetricsResponse)
+async def metrics(api_key: str = Depends(api_key_auth)) -> MetricsResponse:
+    """Report LLM token usage, cost, and prompt-cache savings since startup.
+
+    These are server-wide operator figures, so BYOK callers are refused: a
+    BYOK request gets its own numbers in the ``usage`` field of its
+    annotation response instead.
+
+    Args:
+        api_key: Authentication result (injected by dependency)
+
+    Returns:
+        Totals since startup, broken down by agent role and by model
+
+    Raises:
+        HTTPException: 403 when authenticated via BYOK
+    """
+    if api_key == "byok":
+        raise HTTPException(
+            status_code=403,
+            detail="Server metrics require a server API key; "
+            "per-request usage is returned in the annotation response.",
+        )
+
+    snapshot = process_ledger().snapshot()
+    return MetricsResponse(
+        since=_startup_time,
+        total=UsageSummary(**snapshot["total"]),
+        by_role={role: UsageSummary(**totals) for role, totals in snapshot["by_role"].items()},
+        by_model={model: UsageSummary(**totals) for model, totals in snapshot["by_model"].items()},
+    )
+
+
 @app.get("/version")
 async def get_version():
     """Get API version information.