sediment-api 0.7.0__tar.gz → 0.7.1__tar.gz

{sediment_api-0.7.0 → sediment_api-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sediment-api
-Version: 0.7.0
+Version: 0.7.1
 Summary: Sediment ingest API: facts in through three doors
 Project-URL: Source, https://github.com/sediment-ai/sediment
 Project-URL: Documentation, https://github.com/sediment-ai/sediment/tree/main/docs
@@ -9,12 +9,12 @@ Project-URL: Changelog, https://github.com/sediment-ai/sediment/blob/main/CHANGE
 License-Expression: AGPL-3.0-or-later
 License-File: LICENSE
 Requires-Python: >=3.12
-Requires-Dist: anyio>=4.15.1
+Requires-Dist: anyio>=4.16.0
 Requires-Dist: fastapi>=0.142.2
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic-settings>=2.16.2
-Requires-Dist: sediment-capture==0.7.0
-Requires-Dist: sediment-core==0.7.0
-Requires-Dist: sediment-derive==0.7.0
-Requires-Dist: sediment-export==0.7.0
+Requires-Dist: sediment-capture==0.7.1
+Requires-Dist: sediment-core==0.7.1
+Requires-Dist: sediment-derive==0.7.1
+Requires-Dist: sediment-export==0.7.1
 Requires-Dist: uvicorn>=0.54.0

{sediment_api-0.7.0 → sediment_api-0.7.1}/pyproject.toml

@@ -1,21 +1,21 @@
 [project]
 name = "sediment-api"
-version = "0.7.0"
+version = "0.7.1"
 description = "Sediment ingest API: facts in through three doors"
 requires-python = ">=3.12"
 license = "AGPL-3.0-or-later"
 license-files = ["LICENSE"]
 dependencies = [
     # Security floor for HTTPX/Starlette, including installations from wheels.
-    "anyio>=4.15.1",
+    "anyio>=4.16.0",
     "fastapi>=0.142.2",
     "httpx>=0.27",
     "uvicorn>=0.54.0",
     "pydantic-settings>=2.16.2",
-    "sediment-core==0.7.0",
-    "sediment-capture==0.7.0",
-    "sediment-derive==0.7.0",
-    "sediment-export==0.7.0",
+    "sediment-core==0.7.1",
+    "sediment-capture==0.7.1",
+    "sediment-derive==0.7.1",
+    "sediment-export==0.7.1",
 ]
 
 [project.urls]

{sediment_api-0.7.0 → sediment_api-0.7.1}/sediment_api/__init__.py

@@ -3,4 +3,4 @@
 
 # Single source for the API version string — FastAPI's ``app.version``
 # (reported by /health) and GET /v1/me both read it, so the two cannot drift.
-__version__ = "0.7.0"
+__version__ = "0.7.1"

{sediment_api-0.7.0 → sediment_api-0.7.1}/sediment_api/deps.py

@@ -14,8 +14,7 @@ from __future__ import annotations
 import json
 import secrets
 from dataclasses import dataclass
-from typing import Literal
-from typing import Any
+from typing import Any, Literal
 
 from fastapi import Depends, Header, HTTPException, Request
 from sediment_capture import verify_signature

sediment_api-0.7.1/sediment_api/ingest_envelopes.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Typed response envelopes for the ingest doors (AGENTS.md §API Conventions).
+
+Routers return these instead of bare dicts so the generated OpenAPI names
+each outcome. The wire bodies stay exactly the documented shapes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Annotated, Literal
+
+from pydantic import ConfigDict, Field
+
+_CLOSED = ConfigDict(extra="forbid")
+
+
+@dataclass(frozen=True)
+class IngestReceipt:
+    """The retained Fact for one single-Fact ingest request."""
+
+    __pydantic_config__ = _CLOSED
+
+    fact_id: Annotated[
+        str,
+        Field(description="ID of the retained Fact, including on redelivery"),
+    ]
+    stored: Annotated[
+        bool,
+        Field(
+            description=(
+                "False when a redelivery collapsed on a UNIQUE index (ADR "
+                "0003); success, not an error"
+            )
+        ),
+    ]
+
+
+@dataclass(frozen=True)
+class IngestSkipped:
+    """A declined delivery that the sender shouldn't retry."""
+
+    __pydantic_config__ = _CLOSED
+
+    skipped: Literal[True]
+    reason: Annotated[
+        str, Field(description="Why the route stored nothing for this delivery")
+    ]
+
+
+@dataclass(frozen=True)
+class OTLPExportLogsResponse:
+    """The empty OTLP/HTTP JSON ExportLogsServiceResponse: full success."""
+
+    __pydantic_config__ = _CLOSED

{sediment_api-0.7.0 → sediment_api-0.7.1}/sediment_api/routers/ci_vendor.py

@@ -16,8 +16,6 @@ collapses redeliveries; ``stored: false`` means success, not an error.
 
 from __future__ import annotations
 
-from typing import Any
-
 from fastapi import APIRouter, Depends
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 from sediment_core import (
@@ -40,6 +38,7 @@ from sediment_core import (
 
 from ..config import settings
 from ..deps import get_store, verify_ingest_token
+from ..ingest_envelopes import IngestReceipt
 
 router = APIRouter(tags=["ci-vendor"])
 
@@ -121,7 +120,7 @@ def ingest_ci_vendor(
     body: VendorCIRequest,
     _: None = Depends(verify_ingest_token),
     store: FactStore = Depends(get_store),
-) -> dict[str, Any]:
+) -> IngestReceipt:
     outcome = CIOutcome(
         org_id=settings.org_id,
         provider=body.provider,
@@ -146,4 +145,4 @@ def ingest_ci_vendor(
         source_event_id=body.source_event_id,
     )
     receipt = store.store_ci_outcome_receipt(outcome)
-    return {"fact_id": receipt.fact_id, "stored": receipt.stored}
+    return IngestReceipt(fact_id=receipt.fact_id, stored=receipt.stored)

{sediment_api-0.7.0 → sediment_api-0.7.1}/sediment_api/routers/compute.py

@@ -17,8 +17,6 @@ not an error.
 
 from __future__ import annotations
 
-from typing import Any
-
 from fastapi import APIRouter, Depends
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 from sediment_core import (
@@ -31,6 +29,7 @@ from sediment_core import (
 
 from ..config import settings
 from ..deps import get_store, verify_ingest_token
+from ..ingest_envelopes import IngestReceipt
 
 router = APIRouter(tags=["compute"])
 
@@ -89,7 +88,7 @@ def ingest_compute_allocation(
     body: ComputeAllocationRequest,
     _: None = Depends(verify_ingest_token),
     store: FactStore = Depends(get_store),
-) -> dict[str, Any]:
+) -> IngestReceipt:
     allocation = ComputeAllocation(
         org_id=settings.org_id,
         session_id=body.session_id,
@@ -99,4 +98,4 @@ def ingest_compute_allocation(
         occurred_at=body.occurred_at,
     )
     receipt = store.store_compute_allocation_receipt(allocation)
-    return {"fact_id": receipt.fact_id, "stored": receipt.stored}
+    return IngestReceipt(fact_id=receipt.fact_id, stored=receipt.stored)

{sediment_api-0.7.0 → sediment_api-0.7.1}/sediment_api/routers/forge.py

@@ -2,8 +2,8 @@
 """
 GitHub webhook ingest routes, mounted under /ingest/github in main.py.
 
-One module for both routes: they share the HMAC intake and differ only in
-which parser/store pair the payload walks through. The signature is
+One module for all four routes: they share the HMAC intake and differ only
+in which parser/store pair the payload walks through. The signature is
 verified BEFORE the event type is examined: a wrong-secret delivery must
 401 even for event types a route skips, or GitHub's setup ping would
 green-light a misconfigured webhook. The push route stores the Push fact,
@@ -19,7 +19,6 @@ from __future__ import annotations
 import logging
 from collections import Counter
 from datetime import UTC, datetime
-from typing import Any
 
 from fastapi import APIRouter, BackgroundTasks, Depends, Header, Request
 from sediment_capture import (
@@ -53,6 +52,7 @@ from starlette.concurrency import run_in_threadpool
 
 from ..config import settings
 from ..deps import get_store, read_verified_webhook
+from ..ingest_envelopes import IngestReceipt, IngestSkipped
 
 logger = logging.getLogger("sediment.api.forge")
 router = APIRouter(tags=["forge"])
@@ -295,15 +295,15 @@ async def ingest_push(
     x_hub_signature_256: str | None = Header(None),
     x_github_event: str = Header(...),
     store: FactStore = Depends(get_store),
-) -> dict[str, Any]:
+) -> IngestReceipt | IngestSkipped:
     payload = await read_verified_webhook(request, x_hub_signature_256)
     # GitHub delivers every subscribed event (incl. ping) to the one URL;
     # the X-GitHub-Event header is the discriminator.
     if x_github_event != "push":
-        return {"skipped": True, "reason": "not a push event"}
+        return IngestSkipped(skipped=True, reason="not a push event")
     push = parse_push(payload, org_id=settings.org_id, github_host=settings.github_host)
     if push is None:
-        return {"skipped": True, "reason": "not a storable push"}
+        return IngestSkipped(skipped=True, reason="not a storable push")
     receipt = await run_in_threadpool(store.store_push_receipt, push)
     fetch_repo, fetch_clone_url = push.repo, push.clone_url
     push = receipt.fact
@@ -325,12 +325,11 @@ async def ingest_push(
             push, fetch_repo=fetch_repo, fetch_clone_url=fetch_clone_url
         )
         background.add_task(request.app.state.workers.wait_background, task)
-    return {"fact_id": push.push_id, "stored": stored}
+    return IngestReceipt(fact_id=push.push_id, stored=stored)
 
 
 @router.post(
     "/repository",
-    response_model=dict[str, Any],
     responses={
         503: {
             "description": "Mirror work capacity, storage, or execution budget exceeded."
@@ -343,11 +342,11 @@ async def ingest_repository(
     x_github_event: str = Header(...),
     x_github_delivery: str | None = Header(None),
     store: FactStore = Depends(get_store),
-) -> dict[str, Any]:
+) -> IngestReceipt | IngestSkipped:
     """Store an immutable rename receipt independently of mirror availability."""
     payload = await read_verified_webhook(request, x_hub_signature_256)
     if x_github_event != "repository":
-        return {"skipped": True, "reason": "not a repository event"}
+        return IngestSkipped(skipped=True, reason="not a repository event")
     rename, reason = parse_repository_rename(
         payload,
         org_id=settings.org_id,
@@ -356,12 +355,12 @@ async def ingest_repository(
     )
     if rename is None:
         assert reason is not None
-        return {"skipped": True, "reason": reason.value}
+        return IngestSkipped(skipped=True, reason=reason.value)
     receipt = await run_in_threadpool(store.store_repository_rename_receipt, rename)
     logger.info(
         "repository_rename_stored fact_id=%s stored=%s", receipt.fact_id, receipt.stored
     )
-    return {"fact_id": receipt.fact_id, "stored": receipt.stored}
+    return IngestReceipt(fact_id=receipt.fact_id, stored=receipt.stored)
 
 
 @router.post("/ci")
@@ -371,10 +370,10 @@ async def ingest_ci(
     x_github_event: str = Header(...),
     x_github_delivery: str | None = Header(None),
     store: FactStore = Depends(get_store),
-) -> dict[str, Any]:
+) -> IngestReceipt | IngestSkipped:
     payload = await read_verified_webhook(request, x_hub_signature_256)
     if x_github_event != "workflow_run":
-        return {"skipped": True, "reason": "not a workflow_run event"}
+        return IngestSkipped(skipped=True, reason="not a workflow_run event")
     outcome = parse_workflow_run(
         payload,
         org_id=settings.org_id,
@@ -382,7 +381,7 @@ async def ingest_ci(
         github_host=settings.github_host,
     )
     if outcome is None:
-        return {"skipped": True, "reason": "not a completed workflow_run"}
+        return IngestSkipped(skipped=True, reason="not a completed workflow_run")
     receipt = await run_in_threadpool(store.store_ci_outcome_receipt, outcome)
     outcome = receipt.fact
     stored = receipt.stored
@@ -393,7 +392,7 @@ async def ingest_ci(
         outcome.repo,
         outcome.result,
     )
-    return {"fact_id": outcome.outcome_id, "stored": stored}
+    return IngestReceipt(fact_id=outcome.outcome_id, stored=stored)
 
 
 @router.post("/pull-request")
@@ -403,10 +402,10 @@ async def ingest_pull_request(
     x_github_event: str = Header(...),
     x_github_delivery: str | None = Header(None),
     store: FactStore = Depends(get_store),
-) -> dict[str, Any]:
+) -> IngestReceipt | IngestSkipped:
     payload = await read_verified_webhook(request, x_hub_signature_256)
     if x_github_event != "pull_request":
-        return {"skipped": True, "reason": "not a pull_request event"}
+        return IngestSkipped(skipped=True, reason="not a pull_request event")
     if payload.get("action") == "closed":
         merge = parse_pull_request_merge(
             payload,
@@ -415,7 +414,7 @@ async def ingest_pull_request(
             github_host=settings.github_host,
         )
         if merge is None:
-            return {"skipped": True, "reason": "not a merged pull_request"}
+            return IngestSkipped(skipped=True, reason="not a merged pull_request")
         receipt = await run_in_threadpool(store.store_pull_request_merge_receipt, merge)
         merge = receipt.fact
         stored = receipt.stored
@@ -426,7 +425,7 @@ async def ingest_pull_request(
             merge.repo,
             merge.pr_number,
         )
-        return {"fact_id": merge.merge_id, "stored": stored}
+        return IngestReceipt(fact_id=merge.merge_id, stored=stored)
 
     revision, skip_reason = parse_pull_request_revision(
         payload,
@@ -436,7 +435,7 @@ async def ingest_pull_request(
     )
     if revision is None:
         assert skip_reason is not None
-        return {"skipped": True, "reason": skip_reason.value}
+        return IngestSkipped(skipped=True, reason=skip_reason.value)
     receipt = await run_in_threadpool(
         store.store_pull_request_revision_receipt, revision
     )
@@ -449,4 +448,4 @@ async def ingest_pull_request(
         revision.repo,
         revision.pr_number,
     )
-    return {"fact_id": revision.revision_id, "stored": stored}
+    return IngestReceipt(fact_id=revision.revision_id, stored=stored)

{sediment_api-0.7.0 → sediment_api-0.7.1}/sediment_api/routers/gateway.py

@@ -20,6 +20,7 @@ from sediment_core.models import AwareDatetime
 
 from ..config import settings
 from ..deps import get_store, verify_ingest_token
+from ..ingest_envelopes import IngestReceipt, IngestSkipped
 
 logger = logging.getLogger("sediment.api.gateway")
 router = APIRouter(tags=["gateway"])
@@ -57,7 +58,7 @@ def ingest_gateway(
     body: GatewayIngestRequest,
     _: None = Depends(verify_ingest_token),
     store: FactStore = Depends(get_store),
-) -> dict[str, Any]:
+) -> IngestReceipt | IngestSkipped:
     adapter = ADAPTERS.get(body.provider)
     if adapter is None:
         raise HTTPException(
@@ -85,7 +86,7 @@ def ingest_gateway(
                 body.provider,
                 body.payload.get("litellm_call_id"),
             )
-            return {"skipped": True, "reason": "no_session"}
+            return IngestSkipped(skipped=True, reason="no_session")
 
     try:
         inference_call = adapter.normalize(
@@ -134,4 +135,4 @@ def ingest_gateway(
         receipt.fact_id,
         receipt.stored,
     )
-    return {"fact_id": receipt.fact_id, "stored": receipt.stored}
+    return IngestReceipt(fact_id=receipt.fact_id, stored=receipt.stored)

{sediment_api-0.7.0 → sediment_api-0.7.1}/sediment_api/routers/otlp.py

@@ -12,7 +12,6 @@ from __future__ import annotations
 
 import json
 import logging
-from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Request
 from sediment_capture import parse_otlp_logs
@@ -21,6 +20,7 @@ from starlette.concurrency import run_in_threadpool
 
 from ..config import settings
 from ..deps import get_store, verify_ingest_token
+from ..ingest_envelopes import OTLPExportLogsResponse
 
 logger = logging.getLogger("sediment.api.otlp")
 router = APIRouter(tags=["otlp"])
@@ -31,7 +31,7 @@ async def ingest_otlp_logs(
     request: Request,
     _: None = Depends(verify_ingest_token),
     store: FactStore = Depends(get_store),
-) -> dict[str, Any]:
+) -> OTLPExportLogsResponse:
     try:
         payload = await request.json()
     except HTTPException:
@@ -98,7 +98,7 @@ async def ingest_otlp_logs(
         },
     )
     # Empty ExportLogsServiceResponse = full success (OTLP/HTTP JSON).
-    return {}
+    return OTLPExportLogsResponse()
 
 
 def _store_translated_facts(

sediment_api-0.7.1/tests/test_ingest_envelopes.py

@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Ingest response envelopes: the committed OpenAPI names each outcome, and
+representative stored, duplicate, and skipped bodies validate against it
+while keeping their exact wire shapes (AGENTS.md §API Conventions)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import httpx
+import pytest
+import yaml
+from fastapi.testclient import TestClient
+from jsonschema import Draft202012Validator
+from sediment_capture import sign_payload
+
+from sediment_api.config import settings
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+FIXTURES = REPO_ROOT / "packages/capture/tests/fixtures"
+SPEC = yaml.safe_load((REPO_ROOT / "openapi.yaml").read_text(encoding="utf-8"))
+RECEIPT = "#/components/schemas/IngestReceipt"
+SKIPPED = "#/components/schemas/IngestSkipped"
+OTLP = "#/components/schemas/OTLPExportLogsResponse"
+
+
+def _ok_schema(path: str) -> dict[str, Any]:
+    response = SPEC["paths"][path]["post"]["responses"]["200"]
+    return response["content"]["application/json"]["schema"]
+
+
+def _assert_matches_spec(path: str, response: httpx.Response) -> None:
+    assert response.status_code == 200
+    schema = {**_ok_schema(path), "components": SPEC["components"]}
+    Draft202012Validator(schema).validate(response.json())
+
+
+@pytest.mark.parametrize(
+    ("path", "refs"),
+    [
+        ("/ingest/gateway", [RECEIPT, SKIPPED]),
+        ("/ingest/github/push", [RECEIPT, SKIPPED]),
+        ("/ingest/github/repository", [RECEIPT, SKIPPED]),
+        ("/ingest/github/ci", [RECEIPT, SKIPPED]),
+        ("/ingest/github/pull-request", [RECEIPT, SKIPPED]),
+        ("/ingest/ci", [RECEIPT]),
+        ("/ingest/compute", [RECEIPT]),
+        ("/v1/logs", [OTLP]),
+    ],
+)
+def test_each_ingest_route_names_its_envelopes(path: str, refs: list[str]) -> None:
+    schema = _ok_schema(path)
+    options = schema.get("anyOf", [schema])
+    assert [option["$ref"] for option in options] == refs
+
+
+def test_envelope_schemas_are_closed() -> None:
+    schemas = SPEC["components"]["schemas"]
+    receipt, skipped, otlp = (
+        schemas[name]
+        for name in ("IngestReceipt", "IngestSkipped", "OTLPExportLogsResponse")
+    )
+    assert receipt["required"] == ["fact_id", "stored"]
+    assert receipt["properties"]["fact_id"]["type"] == "string"
+    assert receipt["properties"]["stored"]["type"] == "boolean"
+    assert skipped["required"] == ["skipped", "reason"]
+    assert skipped["properties"]["skipped"]["const"] is True
+    assert otlp["properties"] == {}
+    for schema in (receipt, skipped, otlp):
+        assert schema["additionalProperties"] is False
+
+
+def _bearer() -> dict[str, str]:
+    return {"Authorization": f"Bearer {settings.api_bearer_token}"}
+
+
+def _webhook(
+    client: TestClient, path: str, event: str, payload: dict[str, Any]
+) -> httpx.Response:
+    body = json.dumps(payload).encode()
+    return client.post(
+        path,
+        content=body,
+        headers={
+            "X-Hub-Signature-256": sign_payload(body, settings.github_webhook_secret),
+            "X-GitHub-Event": event,
+            "X-GitHub-Delivery": "delivery-envelopes",
+            "Content-Type": "application/json",
+        },
+    )
+
+
+def test_gateway_stored_duplicate_and_skipped_bodies(client: TestClient) -> None:
+    payload = json.loads(
+        (FIXTURES / "litellm_standard_logging_object.json").read_text()
+    )
+    body = {"provider": "litellm", "session_id": "sess-envelope", "payload": payload}
+
+    first = client.post("/ingest/gateway", json=body, headers=_bearer())
+    again = client.post("/ingest/gateway", json=body, headers=_bearer())
+    skipped = client.post(
+        "/ingest/gateway",
+        json={"provider": "litellm", "payload": {"litellm_call_id": "no-session"}},
+        headers=_bearer(),
+    )
+
+    for response in (first, again, skipped):
+        _assert_matches_spec("/ingest/gateway", response)
+    fact_id = first.json()["fact_id"]
+    assert first.json() == {"fact_id": fact_id, "stored": True}
+    assert again.json() == {"fact_id": fact_id, "stored": False}
+    assert skipped.json() == {"skipped": True, "reason": "no_session"}
+
+
+def test_webhook_stored_duplicate_and_skipped_bodies(client: TestClient) -> None:
+    push = json.loads((FIXTURES / "github_push.json").read_text())
+
+    first = _webhook(client, "/ingest/github/push", "push", push)
+    again = _webhook(client, "/ingest/github/push", "push", push)
+    skipped = _webhook(client, "/ingest/github/push", "ping", {"zen": "ok"})
+
+    for response in (first, again, skipped):
+        _assert_matches_spec("/ingest/github/push", response)
+    fact_id = first.json()["fact_id"]
+    assert first.json() == {"fact_id": fact_id, "stored": True}
+    assert again.json() == {"fact_id": fact_id, "stored": False}
+    assert skipped.json() == {"skipped": True, "reason": "not a push event"}
+
+
+def test_otlp_success_stays_empty(client: TestClient) -> None:
+    [fixture] = sorted(FIXTURES.glob("otlp/claude_code/tool_decision_accept_user.json"))
+    payload = json.loads(fixture.read_text())
+
+    for _ in range(2):
+        response = client.post("/v1/logs", json=payload, headers=_bearer())
+        _assert_matches_spec("/v1/logs", response)
+        assert response.content == b"{}"

{sediment_api-0.7.0 → sediment_api-0.7.1}/tests/test_v1.py

@@ -101,7 +101,7 @@ def test_me_happy_path(client: TestClient) -> None:
     assert resp.status_code == 200
     assert resp.json() == {
         "org_id": ORG,
-        "version": "0.7.0",
+        "version": "0.7.1",
         "authority": "operator",
         "client_id": "operator",
     }