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

capture_runtime_client/private/generated_models.py

@@ -0,0 +1,627 @@
+# Generated by packages/capture-runtime/scripts/generate_contracts.py. Do not edit.
+
+"""Generated host-side Pydantic models for the Capture Runtime v2 API."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Annotated, Any, Final, Literal, Self
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StringConstraints,
+    field_validator,
+    model_validator,
+)
+from pydantic.alias_generators import to_camel
+
+API_VERSION: Final = "2.0"
+RUNTIME_VERSION: Final = "0.4.0"
+CAPTURE_DOCUMENT_SCHEMA_VERSION: Final = "2"
+
+NonEmptyString = Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
+CaptureText = Annotated[
+    str, StringConstraints(strip_whitespace=True, min_length=1, max_length=2_000_000)
+]
+ProjectedText = Annotated[
+    str, StringConstraints(strip_whitespace=True, min_length=1, max_length=8_000_000)
+]
+WarningText = Annotated[str, StringConstraints(strip_whitespace=True, max_length=500)]
+Sha256Hex = Annotated[str, StringConstraints(pattern=r"^[0-9a-f]{64}$")]
+EngineDigest = Annotated[str, StringConstraints(pattern=r"^sha256:[0-9a-f]{64}$")]
+
+
+class StrictModel(BaseModel):
+    """Reject unexpected wire fields and expose camelCase JSON aliases."""
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        extra="forbid",
+        populate_by_name=True,
+        str_strip_whitespace=True,
+    )
+
+
+def _require_aware(value: datetime) -> datetime:
+    if value.tzinfo is None or value.utcoffset() is None:
+        raise ValueError("timestamp must include a timezone")
+    return value
+
+
+class CaptureSourceKind(StrEnum):
+    PDF = "pdf"
+    IMAGE = "image"
+    AUDIO = "audio"
+
+
+class StructuringMode(StrEnum):
+    RUNTIME = "runtime"
+    HOST = "host"
+
+
+class RuntimeInstallationStatus(StrEnum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    MANUAL_ACTION_REQUIRED = "manual_action_required"
+
+
+class RuntimeModelOptionStatus(StrEnum):
+    NOT_INSTALLED = "not-installed"
+    INSTALLED = "installed"
+    ACTIVE = "active"
+
+
+class RuntimeRequirementStatus(StrEnum):
+    READY = "ready"
+    MISSING = "missing"
+    INSTALLABLE = "installable"
+    MANUAL_ACTION_REQUIRED = "manual_action_required"
+    UNAVAILABLE = "unavailable"
+
+
+CaptureRequirementId = Literal[
+    "windowsml-ocr",
+    "whisper-primary",
+    "ollama-runtime",
+    "capture-ollama-model",
+]
+
+
+class PageLocator(StrictModel):
+    kind: Literal["page"] = "page"
+    page: int = Field(ge=1)
+    bounding_box: tuple[float, float, float, float] | None = None
+
+
+class TimeLocator(StrictModel):
+    kind: Literal["time"] = "time"
+    start_ms: int = Field(ge=0)
+    end_ms: int = Field(gt=0)
+
+    @model_validator(mode="after")
+    def validate_interval(self) -> Self:
+        if self.end_ms <= self.start_ms:
+            raise ValueError("endMs must be greater than startMs")
+        return self
+
+
+CaptureLocator = Annotated[PageLocator | TimeLocator, Field(discriminator="kind")]
+
+
+class CaptureSource(StrictModel):
+    sha256: Sha256Hex
+    file_name: Annotated[
+        str, StringConstraints(strip_whitespace=True, min_length=1, max_length=255)
+    ]
+    media_type: NonEmptyString
+    bytes: int = Field(ge=1)
+
+
+class CaptureEngine(StrictModel):
+    engine: NonEmptyString
+    model: NonEmptyString
+    digest: EngineDigest
+    device: NonEmptyString | None = None
+
+
+class RawCaptureSegment(StrictModel):
+    segment_id: NonEmptyString
+    order: int = Field(ge=0)
+    locator: CaptureLocator
+    text: CaptureText
+
+
+def project_source_text(segments: list[RawCaptureSegment]) -> str:
+    return "\n".join(segment.text for segment in segments)
+
+
+class RawCapture(StrictModel):
+    schema_version: Literal["2"] = CAPTURE_DOCUMENT_SCHEMA_VERSION
+    diagnostic_only: Literal[True] = True
+    source: CaptureSource
+    segments: list[RawCaptureSegment] = Field(min_length=1, max_length=10_000)
+    source_text: ProjectedText
+    extraction_engine: CaptureEngine
+    warnings: list[WarningText] = Field(default_factory=list, max_length=1_000)
+    created_at: datetime
+
+    _aware_created_at = field_validator("created_at")(_require_aware)
+
+    @model_validator(mode="after")
+    def validate_projection(self) -> Self:
+        expected_orders = list(range(len(self.segments)))
+        if [segment.order for segment in self.segments] != expected_orders:
+            raise ValueError("raw segment order must be contiguous and match list order")
+        if self.source_text != project_source_text(self.segments):
+            raise ValueError("sourceText must be the exact raw segment projection")
+        identifiers = [segment.segment_id for segment in self.segments]
+        if len(identifiers) != len(set(identifiers)):
+            raise ValueError("raw segmentId values must be unique")
+        return self
+
+
+class CaptureBlock(StrictModel):
+    block_id: NonEmptyString
+    order: int = Field(ge=0)
+    type: Literal["heading", "paragraph", "list-item", "table", "quote", "transcript"]
+    source_segment_id: NonEmptyString
+    locator: CaptureLocator
+    source_text: CaptureText
+    target_text: CaptureText
+
+
+class CaptureDocument(StrictModel):
+    schema_version: Literal["2"] = CAPTURE_DOCUMENT_SCHEMA_VERSION
+    source: CaptureSource
+    raw_segments: list[RawCaptureSegment] = Field(min_length=1, max_length=10_000)
+    blocks: list[CaptureBlock] = Field(min_length=1, max_length=10_000)
+    source_text: ProjectedText
+    target_text: ProjectedText
+    extraction_engine: CaptureEngine
+    structuring_engine: CaptureEngine
+    warnings: list[WarningText] = Field(default_factory=list, max_length=1_000)
+    created_at: datetime
+    completed_at: datetime
+
+    _aware_created_at = field_validator("created_at")(_require_aware)
+    _aware_completed_at = field_validator("completed_at")(_require_aware)
+
+    @model_validator(mode="after")
+    def validate_document(self) -> Self:
+        if self.completed_at < self.created_at:
+            raise ValueError("completedAt must not precede createdAt")
+        if [segment.order for segment in self.raw_segments] != list(range(len(self.raw_segments))):
+            raise ValueError("raw segment order must be contiguous and match list order")
+        if [block.order for block in self.blocks] != list(range(len(self.blocks))):
+            raise ValueError("block order must be contiguous and match list order")
+        segment_ids = [segment.segment_id for segment in self.raw_segments]
+        if len(segment_ids) != len(set(segment_ids)):
+            raise ValueError("raw segmentId values must be unique")
+        block_ids = [block.block_id for block in self.blocks]
+        if len(block_ids) != len(set(block_ids)):
+            raise ValueError("blockId values must be unique")
+        segments_by_id = {segment.segment_id: segment for segment in self.raw_segments}
+        if len(self.blocks) != len(self.raw_segments):
+            raise ValueError("blocks must cover every raw segment exactly once")
+        for index, block in enumerate(self.blocks):
+            expected_segment = self.raw_segments[index]
+            segment = segments_by_id.get(block.source_segment_id)
+            if segment is None:
+                raise ValueError("every block must reference a raw source segment")
+            if block.source_segment_id != expected_segment.segment_id:
+                raise ValueError("block sequence must follow raw segment order")
+            if block.locator != segment.locator:
+                raise ValueError("block locator must equal its raw source segment locator")
+            if block.source_text != segment.text:
+                raise ValueError("block sourceText must equal its raw source segment text")
+        if self.source_text != project_source_text(self.raw_segments):
+            raise ValueError("sourceText must be the exact raw segment projection")
+        expected_target = "\n".join(block.target_text for block in self.blocks)
+        if self.target_text != expected_target:
+            raise ValueError("targetText must be the exact block target projection")
+        return self
+
+
+class RuntimeArtifactDescriptorV2(StrictModel):
+    artifact_url: NonEmptyString
+    artifact_file_name: NonEmptyString
+    bytes: int = Field(ge=1, le=536_870_912)
+    sha256: Sha256Hex
+
+
+class RuntimeRequirementV2(StrictModel):
+    requirement_id: CaptureRequirementId
+    kind: NonEmptyString
+    display_name: NonEmptyString
+    status: RuntimeRequirementStatus
+    required_for: list[str]
+    install_strategy: NonEmptyString
+    detail: str | None = None
+    artifact: RuntimeArtifactDescriptorV2 | None = None
+
+
+class RuntimeRequirementsV2(StrictModel):
+    items: list[RuntimeRequirementV2]
+
+
+class StartRuntimeInstallationV2(StrictModel):
+    requirement_id: CaptureRequirementId
+    consent: Literal[True]
+
+
+class RuntimeModelOptionV2(StrictModel):
+    option_id: NonEmptyString
+    display_name: NonEmptyString
+    model_reference: NonEmptyString
+    expected_digest: Sha256Hex | None = None
+    expected_bytes: int | None = Field(default=None, ge=1)
+    profile_id: NonEmptyString
+    profile_spec_sha256: Sha256Hex
+    status: RuntimeModelOptionStatus
+
+
+class RuntimeModelOptionsV2(StrictModel):
+    catalog_sha256: Sha256Hex
+    items: list[RuntimeModelOptionV2]
+
+
+class StartRuntimeModelInstallationV2(StrictModel):
+    option_id: NonEmptyString
+    consent: Literal[True]
+
+
+class RuntimeModelInstallationV2(StrictModel):
+    installation_id: str
+    option_id: NonEmptyString
+    status: RuntimeInstallationStatus
+    progress: float = Field(ge=0, le=1)
+    error: CaptureFailureV2 | None = None
+    created_at: datetime
+    updated_at: datetime
+    completed_at: datetime | None = None
+
+    _aware_times = field_validator("created_at", "updated_at", "completed_at")(
+        lambda value: None if value is None else _require_aware(value)
+    )
+
+
+class RuntimeModelInstallationsV2(StrictModel):
+    items: list[RuntimeModelInstallationV2]
+
+
+class RuntimeInstallationV2(StrictModel):
+    installation_id: str
+    requirement_id: CaptureRequirementId
+    status: RuntimeInstallationStatus
+    progress: float = Field(ge=0, le=1)
+    error: CaptureFailureV2 | None = None
+    created_at: datetime
+    updated_at: datetime
+    completed_at: datetime | None = None
+
+    _aware_times = field_validator("created_at", "updated_at", "completed_at")(
+        lambda value: None if value is None else _require_aware(value)
+    )
+
+
+class RuntimeInstallationsV2(StrictModel):
+    items: list[RuntimeInstallationV2]
+
+
+class StreamingIngestionMode(StrEnum):
+    FILE = "file"
+
+
+class StreamingIngestionStatus(StrEnum):
+    OPEN = "open"
+    FINALIZING = "finalizing"
+    READY = "ready"
+    CANCELLED = "cancelled"
+    FAILED = "failed"
+    EXPIRED = "expired"
+
+
+class StreamingCaptureStatus(StrEnum):
+    CREATED = "created"
+    WAITING_INPUT = "waiting_input"
+    EXTRACTING = "extracting"
+    AWAITING_STRUCTURING = "awaiting_structuring"
+    STRUCTURING = "structuring"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class StreamingEventType(StrEnum):
+    ACCEPTED = "accepted"
+    INPUT_CHECKPOINT = "input_checkpoint"
+    HEARTBEAT = "heartbeat"
+    SEGMENT = "segment"
+    CHECKPOINT = "checkpoint"
+    RESYNC_REQUIRED = "resync_required"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class OpenIngestionV2(StrictModel):
+    protocol_version: Literal["2"] = "2"
+    kind: CaptureSourceKind = CaptureSourceKind.AUDIO
+    mode: StreamingIngestionMode = StreamingIngestionMode.FILE
+    client_request_id: NonEmptyString
+    file_name: Annotated[
+        str, StringConstraints(strip_whitespace=True, min_length=1, max_length=255)
+    ]
+    media_type: NonEmptyString
+    total_bytes: int = Field(gt=0)
+    source_sha256: Sha256Hex | None = None
+
+
+class IngestionV2(StrictModel):
+    protocol_version: Literal["2"] = "2"
+    kind: CaptureSourceKind = CaptureSourceKind.AUDIO
+    ingestion_id: NonEmptyString
+    status: StreamingIngestionStatus
+    file_name: Annotated[
+        str, StringConstraints(strip_whitespace=True, min_length=1, max_length=255)
+    ]
+    media_type: NonEmptyString
+    total_bytes: int = Field(gt=0)
+    received_bytes: int = Field(ge=0)
+    contiguous_bytes: int = Field(ge=0)
+    next_chunk_index: int = Field(ge=0)
+    next_offset: int = Field(ge=0)
+    source_sha256: Sha256Hex | None = None
+    finalized_sha256: Sha256Hex | None = None
+    expires_at: datetime
+
+    _aware_expires_at = field_validator("expires_at")(_require_aware)
+
+    @model_validator(mode="after")
+    def validate_progress(self) -> Self:
+        if self.received_bytes > self.total_bytes:
+            raise ValueError("receivedBytes must not exceed totalBytes")
+        if self.contiguous_bytes > self.received_bytes:
+            raise ValueError("contiguousBytes must not exceed receivedBytes")
+        if self.next_offset != self.contiguous_bytes:
+            raise ValueError("nextOffset must equal contiguousBytes")
+        if self.status is StreamingIngestionStatus.READY:
+            if self.received_bytes != self.total_bytes or self.finalized_sha256 is None:
+                raise ValueError("ready ingestion must be complete and checksummed")
+        return self
+
+
+class StartCaptureV2(StrictModel):
+    protocol_version: Literal["2"] = "2"
+    client_request_id: NonEmptyString
+    ingestion_id: NonEmptyString
+    structuring_mode: StructuringMode
+    target_language: str | None = None
+    start_policy: Literal["eager"] = "eager"
+
+    @field_validator("target_language")
+    @classmethod
+    def validate_target_language(cls, value: str | None) -> str | None:
+        if value is not None and not 1 <= len(value) <= 64:
+            raise ValueError("targetLanguage must be 1 to 64 characters")
+        return value
+
+
+class FinalizeIngestionV2(StrictModel):
+    protocol_version: Literal["2"] = "2"
+    total_bytes: int = Field(gt=0)
+    sha256: Sha256Hex
+
+
+class CaptureFailureV2(StrictModel):
+    code: Annotated[str, StringConstraints(pattern=r"^[a-z][a-z0-9_]{1,63}$")]
+    message: Annotated[str, StringConstraints(strip_whitespace=True, min_length=1, max_length=500)]
+    stage: NonEmptyString | None = None
+    retryable: bool = False
+
+
+class ReportStructuringFailureV2(StrictModel):
+    protocol_version: Literal["2"] = "2"
+    code: Annotated[str, StringConstraints(pattern=r"^[a-z][a-z0-9_]{1,63}$")]
+    message: Annotated[str, StringConstraints(strip_whitespace=True, min_length=1, max_length=500)]
+
+
+class CaptureOperationV2(StrictModel):
+    protocol_version: Literal["2"] = "2"
+    capture_id: NonEmptyString
+    ingestion_id: NonEmptyString
+    kind: CaptureSourceKind = CaptureSourceKind.AUDIO
+    status: StreamingCaptureStatus
+    progress: float | None = Field(default=None, ge=0, le=1)
+    partial_revision: int = Field(ge=0)
+    last_event_sequence: int = Field(ge=0)
+    source: CaptureSource | None = None
+    error: CaptureFailureV2 | None = None
+    created_at: datetime
+    updated_at: datetime
+    completed_at: datetime | None = None
+
+    _aware_times = field_validator("created_at", "updated_at", "completed_at")(
+        lambda value: None if value is None else _require_aware(value)
+    )
+
+    @model_validator(mode="after")
+    def validate_state(self) -> Self:
+        terminal = {
+            StreamingCaptureStatus.COMPLETED,
+            StreamingCaptureStatus.FAILED,
+            StreamingCaptureStatus.CANCELLED,
+        }
+        if (self.status in terminal) != (self.completed_at is not None):
+            raise ValueError("terminal streaming captures must have completedAt")
+        return self
+
+
+class CaptureStreamingResult(StrictModel):
+    operation: CaptureOperationV2
+    raw: RawCapture
+    result: CaptureDocument
+
+    @model_validator(mode="after")
+    def validate_source_identity(self) -> Self:
+        if self.raw.source != self.result.source:
+            raise ValueError("raw and structured result source identity must match")
+        if self.operation.source is not None and self.operation.source != self.raw.source:
+            raise ValueError("operation and result source identity must match")
+        return self
+
+
+class PartialCaptureV2(StrictModel):
+    protocol_version: Literal["2"] = "2"
+    capture_id: NonEmptyString
+    source: CaptureSource
+    revision: int = Field(ge=0)
+    covered_until_ms: int = Field(ge=0)
+    segments: list[RawCaptureSegment] = Field(default_factory=list, max_length=10_000)
+    source_text: Annotated[str, StringConstraints(max_length=8_000_000)] = ""
+    extraction_engine: CaptureEngine | None = None
+    updated_at: datetime
+
+    _aware_updated_at = field_validator("updated_at")(_require_aware)
+
+    @model_validator(mode="after")
+    def validate_projection(self) -> Self:
+        if [segment.order for segment in self.segments] != list(range(len(self.segments))):
+            raise ValueError("partial segment order must be contiguous")
+        expected_text = project_source_text(self.segments) if self.segments else ""
+        if self.source_text != expected_text:
+            raise ValueError("sourceText must be the exact partial segment projection")
+        return self
+
+
+class CaptureEventV2(StrictModel):
+    protocol_version: Literal["2"] = "2"
+    event_id: NonEmptyString
+    sequence: int = Field(ge=0)
+    capture_id: NonEmptyString
+    kind: CaptureSourceKind = CaptureSourceKind.AUDIO
+    event_type: StreamingEventType
+    stage: NonEmptyString
+    progress: float | None = Field(default=None, ge=0, le=1)
+    partial_revision: int | None = Field(default=None, ge=0)
+    covered_until_ms: int | None = Field(default=None, ge=0)
+    segments: list[RawCaptureSegment] = Field(default_factory=list, max_length=1_000)
+    error: CaptureFailureV2 | None = None
+    created_at: datetime
+
+    _aware_created_at = field_validator("created_at")(_require_aware)
+
+    @model_validator(mode="after")
+    def validate_event_payload(self) -> Self:
+        if self.event_type is StreamingEventType.SEGMENT and not self.segments:
+            raise ValueError("segment events must contain at least one segment")
+        if self.event_type is StreamingEventType.FAILED and self.error is None:
+            raise ValueError("failed events must contain an error")
+        if self.event_type is not StreamingEventType.FAILED and self.error is not None:
+            raise ValueError("only failed events may contain an error")
+        return self
+
+
+class RuntimeStreamingCapabilitiesV2(StrictModel):
+    protocol_version: Literal["2"] = "2"
+    capture_kinds: list[CaptureSourceKind] = Field(
+        default_factory=lambda: [
+            CaptureSourceKind.PDF,
+            CaptureSourceKind.IMAGE,
+            CaptureSourceKind.AUDIO,
+        ],
+        min_length=1,
+    )
+    supports_progressive_audio: bool = True
+    max_chunk_bytes: int = Field(gt=0, le=4 * 1024 * 1024)
+    checkpoint_interval_ms: int = Field(gt=0)
+    heartbeat_interval_ms: int = Field(gt=0)
+    stall_timeout_ms: int = Field(gt=0)
+
+
+class RuntimeReady(StrictModel):
+    """General v2 readiness payload shared by runtime clients."""
+
+    ready: bool
+    service: Literal["capture-runtime"] = "capture-runtime"
+    api_version: Literal["2.0"] = API_VERSION
+    runtime_version: Literal["0.4.0"] = RUNTIME_VERSION
+    capture_document_schema_version: Literal["2"] = CAPTURE_DOCUMENT_SCHEMA_VERSION
+    capture_document_schema_sha256: Sha256Hex | None = None
+    schema_sha256: Sha256Hex | None = None
+    contract_set_version: Literal["2"] = "2"
+    capabilities: dict[str, Any] = Field(default_factory=dict)
+    message: str | None = None
+
+
+class ErrorBodyV2(StrictModel):
+    code: NonEmptyString
+    message: NonEmptyString
+    details: dict[str, Any] | None = None
+
+
+class ErrorEnvelopeV2(StrictModel):
+    error: ErrorBodyV2
+
+
+# Generated public names. Do not edit.
+__all__ = [
+    'StrictModel',
+    'NonEmptyString',
+    'CaptureText',
+    'ProjectedText',
+    'WarningText',
+    'Sha256Hex',
+    'EngineDigest',
+    'CaptureLocator',
+    'CaptureRequirementId',
+    'project_source_text',
+    'PageLocator',
+    'TimeLocator',
+    'CaptureSource',
+    'CaptureEngine',
+    'RawCaptureSegment',
+    'RawCapture',
+    'CaptureBlock',
+    'CaptureDocument',
+    'RuntimeArtifactDescriptorV2',
+    'RuntimeRequirementV2',
+    'RuntimeRequirementsV2',
+    'StartRuntimeInstallationV2',
+    'RuntimeModelOptionV2',
+    'RuntimeModelOptionsV2',
+    'StartRuntimeModelInstallationV2',
+    'RuntimeModelInstallationV2',
+    'RuntimeModelInstallationsV2',
+    'RuntimeInstallationV2',
+    'RuntimeInstallationsV2',
+    'OpenIngestionV2',
+    'IngestionV2',
+    'StartCaptureV2',
+    'FinalizeIngestionV2',
+    'CaptureFailureV2',
+    'ReportStructuringFailureV2',
+    'CaptureOperationV2',
+    'CaptureStreamingResult',
+    'PartialCaptureV2',
+    'CaptureEventV2',
+    'RuntimeStreamingCapabilitiesV2',
+    'RuntimeReady',
+    'ErrorBodyV2',
+    'ErrorEnvelopeV2',
+    'CaptureSourceKind',
+    'StructuringMode',
+    'RuntimeInstallationStatus',
+    'RuntimeModelOptionStatus',
+    'RuntimeRequirementStatus',
+    'StreamingIngestionMode',
+    'StreamingIngestionStatus',
+    'StreamingCaptureStatus',
+    'StreamingEventType',
+]

capture_runtime_client/private/schemas/__init__.py

@@ -0,0 +1 @@
+"""Private generated schemas used by strict SDK validation."""