capture-runtime-client 0.4.0__tar.gz → 0.4.1__tar.gz

{capture_runtime_client-0.4.0 → capture_runtime_client-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: capture-runtime-client
-Version: 0.4.0
+Version: 0.4.1
 Summary: Capture Runtime HTTP, in-memory, discovery, and protocol client SDK.
 License: MIT
 Requires-Python: <3.15,>=3.12

{capture_runtime_client-0.4.0 → capture_runtime_client-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "capture-runtime-client"
-version = "0.4.0"
+version = "0.4.1"
 description = "Capture Runtime HTTP, in-memory, discovery, and protocol client SDK."
 readme = "README.md"
 requires-python = ">=3.12,<3.15"
@@ -15,7 +15,7 @@ dependencies = [
 ]
 
 [tool.capture_runtime_client]
-contract_set_sha256 = "5b93bcb557acca034386b6e9e47502efec91210331ecebabd9c470196d35fec3"
+contract_set_sha256 = "b28366f022533192c063056bbf64cacfd09390815c65408066369dd61094e278"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/capture_runtime_client"]

{capture_runtime_client-0.4.0 → capture_runtime_client-0.4.1}/src/capture_runtime_client/client.py

@@ -27,6 +27,7 @@ from .contracts import (
     CaptureOperation,
     CaptureSourceKind,
     Ingestion,
+    OpenStructuringSession,
     PartialCapture,
     RawCapture,
     RuntimeInstallation,
@@ -35,7 +36,10 @@ from .contracts import (
     RuntimeReady,
     RuntimeRequirements,
     RuntimeStreamingCapabilities,
+    StructuringBatch,
     StructuringMode,
+    StructuringSession,
+    SubmitStructuringBatch,
 )
 from .errors import (
     CaptureRuntimeCompatibilityError,
@@ -282,6 +286,107 @@ class CaptureRuntimeClient:
     def get_result(self, capture_id: str) -> CaptureStreamingResult:
         return self.get_streaming_result(capture_id)
 
+    def open_structuring_session(
+        self,
+        capture_id: str,
+        request: OpenStructuringSession | Mapping[str, Any],
+        *,
+        idempotency_key: UUID | str | None = None,
+    ) -> StructuringSession:
+        """Open a pull-based structuring session with a matching idempotency key."""
+        try:
+            payload = (
+                request
+                if isinstance(request, OpenStructuringSession)
+                else OpenStructuringSession.model_validate(request)
+            )
+        except ValidationError as error:
+            raise CaptureRuntimeProtocolError(
+                "Structuring session request is invalid.", error.errors(include_url=False)
+            ) from error
+        if payload.capture_id != capture_id:
+            raise CaptureRuntimeProtocolError(
+                "Structuring session captureId must match the route capture."
+            )
+        key = (
+            payload.client_request_id
+            if idempotency_key is None
+            else str(idempotency_key)
+        )
+        if not key or key != payload.client_request_id:
+            raise CaptureRuntimeProtocolError(
+                "X-Idempotency-Key must match structuring session clientRequestId."
+            )
+        return decode_model(
+            self._request(
+                "POST",
+                f"/v2/captures/{_safe_id(capture_id)}/structure/session",
+                headers={
+                    "Content-Type": "application/json",
+                    "X-Idempotency-Key": key,
+                },
+                json=payload.model_dump(mode="json", by_alias=True),
+            ),
+            StructuringSession,
+        )
+
+    def get_structuring_session(self, capture_id: str) -> StructuringSession:
+        return decode_model(
+            self._request(
+                "GET", f"/v2/captures/{_safe_id(capture_id)}/structure/session"
+            ),
+            StructuringSession,
+        )
+
+    def get_structuring_batch(self, capture_id: str, batch_index: int) -> StructuringBatch:
+        return decode_model(
+            self._request(
+                "GET",
+                f"/v2/captures/{_safe_id(capture_id)}/structure/session/batches/{_safe_batch_index(batch_index)}",
+            ),
+            StructuringBatch,
+        )
+
+    def pull_structuring_batch(self, capture_id: str, batch_index: int) -> StructuringBatch:
+        """Alias that makes the pull nature explicit for host coordinators."""
+        return self.get_structuring_batch(capture_id, batch_index)
+
+    def submit_structuring_batch(
+        self,
+        capture_id: str,
+        batch_index: int,
+        submission: SubmitStructuringBatch | Mapping[str, Any],
+        *,
+        idempotency_key: UUID | str,
+    ) -> StructuringSession:
+        try:
+            payload = (
+                submission
+                if isinstance(submission, SubmitStructuringBatch)
+                else SubmitStructuringBatch.model_validate(submission)
+            )
+        except ValidationError as error:
+            raise CaptureRuntimeProtocolError(
+                "Structuring batch submission is invalid.", error.errors(include_url=False)
+            ) from error
+        key = str(idempotency_key)
+        if not key:
+            raise CaptureRuntimeProtocolError(
+                "Structuring batch submissions require X-Idempotency-Key."
+            )
+        return decode_model(
+            self._request(
+                "PUT",
+                f"/v2/captures/{_safe_id(capture_id)}/structure/session/batches/{_safe_batch_index(batch_index)}",
+                headers={
+                    "Content-Type": "application/json",
+                    "X-Idempotency-Key": key,
+                },
+                json=payload.model_dump(mode="json", by_alias=True),
+            ),
+            StructuringSession,
+        )
+
     def commit_structure(
         self,
         capture_id: str,
@@ -743,18 +848,22 @@ class CaptureRuntimeClient:
             "/v2/captures/{capture_id}/events",
             "/v2/captures/{capture_id}/raw",
             "/v2/captures/{capture_id}/result",
+            "/v2/captures/{capture_id}/structure/session",
+            "/v2/captures/{capture_id}/structure/session/batches/{batch_index}",
         }
         if not required_paths.issubset(operation_paths):
             raise CaptureRuntimeCompatibilityError(
                 "Capture Runtime contract bundle does not advertise the required client surface."
             )
 
-        def find_operation(path: str) -> Mapping[str, Any] | None:
+        def find_operation(path: str, method: str | None = None) -> Mapping[str, Any] | None:
             return next(
                 (
                     item
                     for item in operations
-                    if isinstance(item, Mapping) and item.get("path") == path
+                    if isinstance(item, Mapping)
+                    and item.get("path") == path
+                    and (method is None or item.get("method") == method)
                 ),
                 None,
             )
@@ -762,6 +871,15 @@ class CaptureRuntimeClient:
         upload = find_operation("/v2/captures")
         chunk = find_operation("/v2/ingestions/{ingestion_id}/chunks/{chunk_index}")
         events = find_operation("/v2/captures/{capture_id}/events")
+        session_open = find_operation(
+            "/v2/captures/{capture_id}/structure/session", "POST"
+        )
+        batch_get = find_operation(
+            "/v2/captures/{capture_id}/structure/session/batches/{batch_index}", "GET"
+        )
+        batch_submit = find_operation(
+            "/v2/captures/{capture_id}/structure/session/batches/{batch_index}", "PUT"
+        )
         if (
             upload is None
             or not isinstance(upload.get("body"), Mapping)
@@ -792,6 +910,24 @@ class CaptureRuntimeClient:
             or streaming.get("lastEventIdHeader") != "Last-Event-ID"
         ):
             raise CaptureRuntimeCompatibilityError("Capture Runtime SSE metadata is incompatible.")
+        if (
+            session_open is None
+            or not isinstance(session_open.get("body"), Mapping)
+            or session_open["body"].get("kind") != "json"
+            or "X-Idempotency-Key" not in session_open.get("requiredHeaders", [])
+            or session_open.get("idempotency", {}).get("mode") != "required"
+            or batch_get is None
+            or not isinstance(batch_get.get("body"), Mapping)
+            or batch_get["body"].get("kind") != "none"
+            or batch_submit is None
+            or not isinstance(batch_submit.get("body"), Mapping)
+            or batch_submit["body"].get("kind") != "json"
+            or "X-Idempotency-Key" not in batch_submit.get("requiredHeaders", [])
+            or batch_submit.get("idempotency", {}).get("mode") != "required"
+        ):
+            raise CaptureRuntimeCompatibilityError(
+                "Capture Runtime pull-session metadata is incompatible."
+            )
         canonical_bundle = json.dumps(
             bundle,
             ensure_ascii=False,
@@ -839,6 +975,12 @@ def _safe_id(value: str) -> str:
     return value
 
 
+def _safe_batch_index(value: int) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+        raise ValueError("Capture Runtime batch index is invalid")
+    return value
+
+
 def _retry_after_seconds(response: httpx.Response) -> float | None:
     value = response.headers.get("retry-after")
     if value is None:

{capture_runtime_client-0.4.0 → capture_runtime_client-0.4.1}/src/capture_runtime_client/contracts.py

@@ -24,6 +24,12 @@ for _generated_name in (
     "CaptureOperationV2",
     "PartialCaptureV2",
     "CaptureEventV2",
+    "StructuringProviderCapabilityV2",
+    "OpenStructuringSessionV2",
+    "StructuringSessionV2",
+    "StructuringBatchV2",
+    "StructuringSemanticBlockV2",
+    "SubmitStructuringBatchV2",
 ):
     getattr(_generated, _generated_name).model_rebuild(
         force=True,
@@ -32,7 +38,7 @@ for _generated_name in (
 
 CAPTURE_API_VERSION = "2.0"
 CAPTURE_DOCUMENT_SCHEMA_VERSION = _generated.CAPTURE_DOCUMENT_SCHEMA_VERSION
-CAPTURE_RUNTIME_VERSION = "0.4.0"
+CAPTURE_RUNTIME_VERSION = "0.4.1"
 CAPTURE_DOCUMENT_SCHEMA_ID = (
     "https://github.com/gx-capture/capture-workbench/schema/capture-document-v2.schema.json"
 )
@@ -143,6 +149,30 @@ class CaptureEvent(_generated.CaptureEventV2):
     pass
 
 
+class StructuringProviderCapability(_generated.StructuringProviderCapabilityV2):
+    pass
+
+
+class OpenStructuringSession(_generated.OpenStructuringSessionV2):
+    pass
+
+
+class StructuringSession(_generated.StructuringSessionV2):
+    pass
+
+
+class StructuringBatch(_generated.StructuringBatchV2):
+    pass
+
+
+class StructuringSemanticBlock(_generated.StructuringSemanticBlockV2):
+    pass
+
+
+class SubmitStructuringBatch(_generated.SubmitStructuringBatchV2):
+    pass
+
+
 class RuntimeStreamingCapabilities(_generated.RuntimeStreamingCapabilitiesV2):
     pass
 
@@ -180,6 +210,8 @@ TimeLocator = _generated.TimeLocator
 
 CaptureSourceKind = _generated.CaptureSourceKind
 StructuringMode = _generated.StructuringMode
+StructuringSessionStatus = _generated.StructuringSessionStatus
+StructuringBatchStatus = _generated.StructuringBatchStatus
 RuntimeInstallationStatus = _generated.RuntimeInstallationStatus
 RuntimeModelOptionStatus = _generated.RuntimeModelOptionStatus
 RuntimeRequirementStatus = _generated.RuntimeRequirementStatus
@@ -253,6 +285,12 @@ __all__ = [
     "CaptureOperation",
     "PartialCapture",
     "CaptureEvent",
+    "StructuringProviderCapability",
+    "OpenStructuringSession",
+    "StructuringSession",
+    "StructuringBatch",
+    "StructuringSemanticBlock",
+    "SubmitStructuringBatch",
     "RuntimeStreamingCapabilities",
     "RuntimeReady",
     "ReportStructuringFailure",
@@ -260,6 +298,8 @@ __all__ = [
     "ErrorEnvelope",
     "CaptureSourceKind",
     "StructuringMode",
+    "StructuringSessionStatus",
+    "StructuringBatchStatus",
     "RuntimeInstallationStatus",
     "RuntimeModelOptionStatus",
     "RuntimeRequirementStatus",