capture-runtime-client 0.4.0__py3-none-any.whl

capture_runtime_client/codec.py

@@ -0,0 +1,124 @@
+"""Private wire codecs shared by HTTP and in-memory adapters."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from .errors import (
+    CaptureAuthenticationError,
+    CaptureRemoteError,
+    CaptureRuntimeProtocolError,
+)
+
+
+def decode_model[ModelT: BaseModel](response: httpx.Response, model: type[ModelT]) -> ModelT:
+    payload = decode_json(response)
+    try:
+        return model.model_validate(payload)
+    except ValidationError as error:
+        raise CaptureRuntimeProtocolError(
+            f"Capture Runtime returned invalid {model.__name__} data.",
+            error.errors(include_url=False),
+        ) from error
+
+
+def decode_json(response: httpx.Response) -> Any:
+    if response.status_code >= 400:
+        try:
+            envelope = response.json()
+        except ValueError:
+            envelope = None
+        error = envelope.get("error") if isinstance(envelope, dict) else None
+        error_map = error if isinstance(error, dict) else {}
+        code = str(error_map.get("code", f"http_{response.status_code}"))
+        message = str(
+            error_map.get("message", f"Capture Runtime request failed ({response.status_code}).")
+        )
+        details = error_map.get("details")
+        details_map = details if isinstance(details, dict) else {}
+        category = error_map.get("category", details_map.get("category"))
+        retryable = error_map.get(
+            "retryable", details_map.get("retryable", response.status_code >= 500)
+        )
+        issues = error_map.get("issues", details_map.get("issues"))
+        request_id = (
+            response.headers.get("x-request-id")
+            or response.headers.get("x-correlation-id")
+            or _optional_text(error_map.get("requestId", details_map.get("requestId")))
+        )
+        if response.status_code in {401, 403} or code in {"unauthorized", "authentication_failed"}:
+            raise CaptureAuthenticationError(
+                message,
+                status_code=response.status_code,
+                details=details,
+                request_id=request_id,
+            )
+        raise CaptureRemoteError(
+            status_code=response.status_code,
+            code=code,
+            message=message,
+            category=_optional_text(category),
+            retryable=bool(retryable),
+            details=details,
+            issues=issues if isinstance(issues, list) else None,
+            request_id=request_id,
+        )
+    if response.status_code == 204:
+        return None
+    try:
+        return response.json()
+    except ValueError as error:
+        raise CaptureRuntimeProtocolError("Capture Runtime returned invalid JSON.") from error
+
+
+def iter_sse(lines: Iterator[bytes]) -> Iterator[dict[str, str]]:
+    event: dict[str, str] = {}
+    data: list[str] = []
+    buffer = ""
+
+    def consume(line: str) -> dict[str, str] | None:
+        nonlocal event, data
+        if not line:
+            if data:
+                result = {**event, "data": "\n".join(data)}
+                event = {}
+                data = []
+                return result
+            event = {}
+            data = []
+            return None
+        if line.startswith(":"):
+            return None
+        key, separator, value = line.partition(":")
+        if separator and value.startswith(" "):
+            value = value[1:]
+        if key == "data":
+            data.append(value)
+        elif key in {"id", "event"}:
+            event[key] = value
+        return None
+
+    for raw in lines:
+        buffer += raw.decode("utf-8")
+        while "\n" in buffer:
+            line, buffer = buffer.split("\n", 1)
+            result = consume(line[:-1] if line.endswith("\r") else line)
+            if result is not None:
+                yield result
+    if buffer:
+        result = consume(buffer[:-1] if buffer.endswith("\r") else buffer)
+        if result is not None:
+            yield result
+    if data:
+        yield {**event, "data": "\n".join(data)}
+
+
+__all__ = ["decode_json", "decode_model", "iter_sse"]
+
+
+def _optional_text(value: Any) -> str | None:
+    return value if isinstance(value, str) and value else None

capture_runtime_client/contracts.py

@@ -0,0 +1,272 @@
+"""Public v2 contract DTOs backed by private generated wire models.
+
+The generated module is an SDK build input only. Consumers receive deliberate
+canonical names from this module; generated identifiers never form part of the
+package's public surface.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from importlib.resources import files
+from typing import Any, cast
+
+from pydantic import Field
+
+from .private import generated_models as _generated
+
+for _generated_name in (
+    "RuntimeModelInstallationV2",
+    "RuntimeModelInstallationsV2",
+    "RuntimeInstallationV2",
+    "RuntimeInstallationsV2",
+    "CaptureOperationV2",
+    "PartialCaptureV2",
+    "CaptureEventV2",
+):
+    getattr(_generated, _generated_name).model_rebuild(
+        force=True,
+        _types_namespace=vars(_generated),
+    )
+
+CAPTURE_API_VERSION = "2.0"
+CAPTURE_DOCUMENT_SCHEMA_VERSION = _generated.CAPTURE_DOCUMENT_SCHEMA_VERSION
+CAPTURE_RUNTIME_VERSION = "0.4.0"
+CAPTURE_DOCUMENT_SCHEMA_ID = (
+    "https://github.com/gx-capture/capture-workbench/schema/capture-document-v2.schema.json"
+)
+CAPTURE_DOCUMENT_SCHEMA_SHA256 = "850afd212d049c25da41d3867ba5477451a6a2c6c7e41f116fe60f26b6a35335"
+_CONTRACT_SET_ASSETS = files("capture_runtime_client.private.assets")
+CAPTURE_CONTRACT_SET_SHA256 = _CONTRACT_SET_ASSETS.joinpath(
+    "contract-set.sha256"
+).read_text(encoding="ascii").strip()
+if hashlib.sha256(
+    _CONTRACT_SET_ASSETS.joinpath("contract-set.json").read_bytes()
+).hexdigest() != CAPTURE_CONTRACT_SET_SHA256:
+    raise RuntimeError("Packaged contract-set asset does not match its SHA-256 allowlist.")
+
+
+# Public v2 DTOs.  These subclasses intentionally create a stable public seam
+# without exporting the generated module or its model names.  Pydantic keeps
+# inherited strict/alias validation, while each class has a canonical v2 name
+# for consumers and package introspection.
+class CaptureSource(_generated.CaptureSource):
+    pass
+
+
+class CaptureEngine(_generated.CaptureEngine):
+    pass
+
+
+class RawCaptureSegment(_generated.RawCaptureSegment):
+    pass
+
+
+class CaptureBlock(_generated.CaptureBlock):
+    pass
+
+
+class CaptureFailure(_generated.CaptureFailureV2):
+    pass
+
+
+class CaptureDocument(_generated.CaptureDocument):
+    pass
+
+
+class RawCapture(_generated.RawCapture):
+    pass
+
+
+class RuntimeArtifactDescriptor(_generated.RuntimeArtifactDescriptorV2):
+    pass
+
+
+class RuntimeRequirement(_generated.RuntimeRequirementV2):
+    pass
+
+
+class RuntimeRequirements(_generated.RuntimeRequirementsV2):
+    pass
+
+
+class RuntimeModelOption(_generated.RuntimeModelOptionV2):
+    pass
+
+
+class RuntimeModelOptions(_generated.RuntimeModelOptionsV2):
+    pass
+
+
+class RuntimeModelInstallation(_generated.RuntimeModelInstallationV2):
+    pass
+
+
+class RuntimeModelInstallations(_generated.RuntimeModelInstallationsV2):
+    pass
+
+
+class RuntimeInstallation(_generated.RuntimeInstallationV2):
+    pass
+
+
+class RuntimeInstallations(_generated.RuntimeInstallationsV2):
+    pass
+
+
+class OpenIngestion(_generated.OpenIngestionV2):
+    pass
+
+
+class Ingestion(_generated.IngestionV2):
+    pass
+
+
+class StartCapture(_generated.StartCaptureV2):
+    pass
+
+
+class FinalizeIngestion(_generated.FinalizeIngestionV2):
+    pass
+
+
+class CaptureOperation(_generated.CaptureOperationV2):
+    pass
+
+
+class PartialCapture(_generated.PartialCaptureV2):
+    pass
+
+
+class CaptureEvent(_generated.CaptureEventV2):
+    pass
+
+
+class RuntimeStreamingCapabilities(_generated.RuntimeStreamingCapabilitiesV2):
+    pass
+
+
+class RuntimeReady(_generated.StrictModel):
+    """General v2 readiness payload shared by discovery clients."""
+
+    ready: bool
+    service: str
+    api_version: str
+    runtime_version: str
+    capture_document_schema_version: str
+    capture_document_schema_sha256: str | None = None
+    schema_sha256: str | None = None
+    contract_set_version: str = "2"
+    capabilities: dict[str, Any] = Field(default_factory=dict)
+    message: str | None = None
+
+
+class ReportStructuringFailure(_generated.ReportStructuringFailureV2):
+    pass
+
+
+class ErrorBody(_generated.ErrorBodyV2):
+    pass
+
+
+class ErrorEnvelope(_generated.ErrorEnvelopeV2):
+    pass
+
+
+CaptureLocator = _generated.CaptureLocator
+PageLocator = _generated.PageLocator
+TimeLocator = _generated.TimeLocator
+
+CaptureSourceKind = _generated.CaptureSourceKind
+StructuringMode = _generated.StructuringMode
+RuntimeInstallationStatus = _generated.RuntimeInstallationStatus
+RuntimeModelOptionStatus = _generated.RuntimeModelOptionStatus
+RuntimeRequirementStatus = _generated.RuntimeRequirementStatus
+StreamingIngestionMode = _generated.StreamingIngestionMode
+StreamingIngestionStatus = _generated.StreamingIngestionStatus
+StreamingCaptureStatus = _generated.StreamingCaptureStatus
+StreamingEventType = _generated.StreamingEventType
+CaptureRequirementId = _generated.CaptureRequirementId
+project_source_text = _generated.project_source_text
+
+
+def _load_contract_schema(name: str) -> dict[str, Any]:
+    filename = {
+        "RawCapture": "raw-capture.schema.json",
+        "CaptureDocument": "capture-document.schema.json",
+    }.get(name)
+    if filename is None:
+        raise ValueError(f"Unknown generated contract schema: {name}")
+    return cast(
+        dict[str, Any],
+        json.loads(files("capture_runtime_client.private.schemas").joinpath(filename).read_text()),
+    )
+
+
+def _load_contract_manifest() -> dict[str, Any]:
+    return {
+        "manifestVersion": "1",
+        "packageVersion": CAPTURE_RUNTIME_VERSION,
+        "runtimeVersion": CAPTURE_RUNTIME_VERSION,
+        "apiVersion": CAPTURE_API_VERSION,
+        "captureDocumentSchemaVersion": CAPTURE_DOCUMENT_SCHEMA_VERSION,
+        "captureDocumentSchemaId": CAPTURE_DOCUMENT_SCHEMA_ID,
+        "captureDocumentSchemaSha256": CAPTURE_DOCUMENT_SCHEMA_SHA256,
+    }
+
+
+def _load_contract_constraints() -> dict[str, Any]:
+    return {"invariants": []}
+
+
+__all__ = [
+    "CAPTURE_API_VERSION",
+    "CAPTURE_DOCUMENT_SCHEMA_ID",
+    "CAPTURE_DOCUMENT_SCHEMA_SHA256",
+    "CAPTURE_CONTRACT_SET_SHA256",
+    "CAPTURE_DOCUMENT_SCHEMA_VERSION",
+    "CAPTURE_RUNTIME_VERSION",
+    "CaptureLocator",
+    "PageLocator",
+    "TimeLocator",
+    "CaptureSource",
+    "CaptureEngine",
+    "RawCaptureSegment",
+    "CaptureBlock",
+    "CaptureFailure",
+    "CaptureDocument",
+    "RawCapture",
+    "RuntimeArtifactDescriptor",
+    "RuntimeRequirement",
+    "RuntimeRequirements",
+    "RuntimeModelOption",
+    "RuntimeModelOptions",
+    "RuntimeModelInstallation",
+    "RuntimeModelInstallations",
+    "RuntimeInstallation",
+    "RuntimeInstallations",
+    "OpenIngestion",
+    "Ingestion",
+    "StartCapture",
+    "FinalizeIngestion",
+    "CaptureOperation",
+    "PartialCapture",
+    "CaptureEvent",
+    "RuntimeStreamingCapabilities",
+    "RuntimeReady",
+    "ReportStructuringFailure",
+    "ErrorBody",
+    "ErrorEnvelope",
+    "CaptureSourceKind",
+    "StructuringMode",
+    "RuntimeInstallationStatus",
+    "RuntimeModelOptionStatus",
+    "RuntimeRequirementStatus",
+    "StreamingIngestionMode",
+    "StreamingIngestionStatus",
+    "StreamingCaptureStatus",
+    "StreamingEventType",
+    "CaptureRequirementId",
+    "project_source_text",
+]

capture_runtime_client/errors.py

@@ -0,0 +1,170 @@
+"""Stable, credential-safe client exception types."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_BEARER = re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/=-]+")
+_SECRET_FIELD = re.compile(r"(?:token|authorization|credential|secret|password)", re.I)
+
+
+def redact_text(value: str) -> str:
+    return _BEARER.sub("Bearer [redacted]", value)[:500]
+
+
+def redact_value(value: Any, *, depth: int = 0) -> Any:
+    if depth > 4:
+        return "[redacted]"
+    if isinstance(value, str):
+        return redact_text(value)
+    if isinstance(value, list):
+        return [redact_value(item, depth=depth + 1) for item in value]
+    if isinstance(value, dict):
+        return {
+            str(key)[:128]: "[redacted]"
+            if _SECRET_FIELD.search(str(key))
+            else redact_value(item, depth=depth + 1)
+            for key, item in value.items()
+        }
+    return value
+
+
+class CaptureRuntimeError(RuntimeError):
+    """Base error with stable, redacted wire diagnostics.
+
+    ``CaptureRemoteError`` and the narrower taxonomy subclasses below preserve
+    the fields emitted by a runtime error envelope.  The historical
+    ``CaptureRuntime*`` names remain available as compatibility aliases.
+    """
+
+    category = "runtime"
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: str,
+        message: str,
+        details: Any = None,
+        category: str | None = None,
+        retryable: bool = False,
+        issues: list[dict[str, Any]] | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.runtime_message = redact_text(message)
+        self.details = redact_value(details)
+        self.category = category or self.category
+        self.retryable = retryable
+        self.issues = redact_value(issues) if issues is not None else []
+        self.request_id = request_id
+        super().__init__(f"Capture Runtime request failed ({code}): {self.runtime_message}")
+
+
+class CaptureTransportError(CaptureRuntimeError):
+    category = "transport"
+
+    def __init__(self, message: str, details: Any = None, *, code: str = "transport_error") -> None:
+        super().__init__(
+            status_code=0,
+            code=code,
+            message=message,
+            details=details,
+            category=self.category,
+            retryable=True,
+        )
+
+
+class CaptureAuthenticationError(CaptureRuntimeError):
+    category = "authentication"
+
+    def __init__(
+        self,
+        message: str = "Capture Runtime authentication failed.",
+        *,
+        status_code: int = 401,
+        details: Any = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(
+            status_code=status_code,
+            code="unauthorized",
+            message=message,
+            details=details,
+            category=self.category,
+            request_id=request_id,
+        )
+
+
+class CaptureCompatibilityError(CaptureRuntimeError):
+    category = "compatibility"
+
+    def __init__(self, message: str, details: Any = None) -> None:
+        super().__init__(
+            status_code=0,
+            code="incompatible_runtime",
+            message=message,
+            details=details,
+            category=self.category,
+        )
+
+
+class CaptureProtocolError(CaptureRuntimeError):
+    category = "protocol"
+
+    def __init__(self, message: str, details: Any = None) -> None:
+        super().__init__(
+            status_code=0,
+            code="protocol_error",
+            message=message,
+            details=details,
+            category=self.category,
+        )
+
+
+class CaptureRemoteError(CaptureRuntimeError):
+    category = "remote"
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: str,
+        message: str,
+        category: str | None = None,
+        retryable: bool = False,
+        details: Any = None,
+        issues: list[dict[str, Any]] | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(
+            status_code=status_code,
+            code=code,
+            message=message,
+            details=details,
+            category=category or self.category,
+            retryable=retryable,
+            issues=issues,
+            request_id=request_id,
+        )
+
+
+# Compatibility names used by the first SDK preview.
+CaptureRuntimeProtocolError = CaptureProtocolError
+CaptureRuntimeCompatibilityError = CaptureCompatibilityError
+
+
+__all__ = [
+    "CaptureAuthenticationError",
+    "CaptureCompatibilityError",
+    "CaptureProtocolError",
+    "CaptureRemoteError",
+    "CaptureTransportError",
+    "CaptureRuntimeCompatibilityError",
+    "CaptureRuntimeError",
+    "CaptureRuntimeProtocolError",
+    "redact_text",
+    "redact_value",
+]

capture_runtime_client/private/__init__.py

@@ -0,0 +1 @@
+"""Private generated SDK inputs; do not import from consumer applications."""

capture_runtime_client/private/assets/__init__.py

@@ -0,0 +1 @@
+"""Packaged canonical runtime contract-set assets."""