synth-ai 0.21.2.dev658__tar.gz → 0.21.3.dev660__tar.gz

{synth_ai-0.21.2.dev658/synth_ai.egg-info → synth_ai-0.21.3.dev660}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.21.2.dev658
+Version: 0.21.3.dev660
 Summary: Python SDK, CLI and MCP servers for Synth Index search and Swarms
 Author-email: Synth AI <josh@usesynth.ai>
 License-Expression: MIT

{synth_ai-0.21.2.dev658 → synth_ai-0.21.3.dev660}/openapi/research-v1.json

@@ -2087,6 +2087,7 @@
           "enterprise",
           "demo_internal",
           "private_alpha",
+          "internal_test",
           "other"
         ],
         "title": "BillingProfileCode",
@@ -23071,7 +23072,7 @@
                 "type": "null"
               }
             ],
-            "description": "Override one shared agent model for this run. Shared top-level values are 'baseten/moonshotai/Kimi-K3', 'baseten/zai-org/GLM-5.2', 'cursor/composer-2.5', 'deepseek/deepseek-v4-flash', 'deepseek/deepseek-v4-flash-direct', 'deepseek/deepseek-v4-pro', 'deepseek/deepseek-v4-pro-direct', 'gpt-5.4', 'gpt-5.4-mini', 'gpt-5.5', 'gpt-5.6-luna', 'modal/moonshotai/Kimi-K3', 'openrouter/openai/gpt-5.6-luna', 'openrouter/poolside/laguna-s-2.1', 'poolside/laguna-s-2.1', 'synth_internal/laguna-s-2.1-nvfp4', 'x-ai/grok-4.3', 'x-ai/grok-build'. Use actor_model_overrides for actor-specific model selection."
+            "description": "Override one shared agent model for this run. Shared top-level values are 'baseten/moonshotai/Kimi-K3', 'baseten/zai-org/GLM-5.2', 'cursor/composer-2.5', 'deepseek/deepseek-v4-flash', 'deepseek/deepseek-v4-flash-direct', 'deepseek/deepseek-v4-pro', 'deepseek/deepseek-v4-pro-direct', 'gpt-5.4', 'gpt-5.4-mini', 'gpt-5.5', 'gpt-5.6-luna', 'modal/moonshotai/Kimi-K3', 'openrouter/openai/gpt-5.6-luna', 'openrouter/poolside/laguna-s-2.1', 'poolside/laguna-s-2.1', 'synth_internal/laguna-s-2.1-nvfp4'. Use actor_model_overrides for actor-specific model selection."
           },
           "agent_model_params": {
             "anyOf": [

{synth_ai-0.21.2.dev658 → synth_ai-0.21.3.dev660}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synth-ai"
-version = "0.21.2.dev658"
+version = "0.21.3.dev660"
 description = "Python SDK, CLI and MCP servers for Synth Index search and Swarms"
 keywords = ["synth", "index", "search", "citations", "research", "swarms", "mcp", "sdk"]
 authors = [{name = "Synth AI", email = "josh@usesynth.ai"}]

{synth_ai-0.21.2.dev658 → synth_ai-0.21.3.dev660}/synth_ai/client.py

@@ -29,10 +29,18 @@ def _resolve_base_url(base_url: str | None) -> str:
 
 
 class SynthClient:
-    """Sync client for Managed Research and hosted optimizers.
+    """Synchronous entry point for Index, Research, Messaging and hosted optimizers.
 
-    Use ``research`` for hosted projects, swarms, and Factory lifecycles. That
-    Use ``optimizers`` for hosted training model discovery and saved LoRAs.
+    Namespaces and their transports are created lazily. Closing the client closes
+    all transports that it opened. Factory APIs remain available for compatibility.
+
+    Example:
+        ```python
+        from synth_ai import SynthClient
+
+        with SynthClient(api_key="YOUR_SYNTH_API_KEY") as client:
+            index = client.index
+        ```
     """
 
     def __init__(
@@ -42,6 +50,14 @@ class SynthClient:
         base_url: str | None = None,
         timeout_seconds: float | None = None,
     ) -> None:
+        """Configure credentials, endpoint and transport timeouts without making requests.
+
+        Args:
+            api_key: Explicit Synth API credential; None uses the configured credential resolver.
+            base_url: Backend URL override; None uses the SDK's configured backend base URL.
+            timeout_seconds: Transport timeout in seconds. None uses 30 seconds for
+                Research, Messaging and Optimizers, and the Index transport default for Index.
+        """
         self.api_key = _resolve_api_key(api_key)
         self.base_url = _resolve_base_url(base_url)
         self.timeout_seconds = 30.0 if timeout_seconds is None else timeout_seconds
@@ -56,7 +72,11 @@ class SynthClient:
 
     @property
     def index(self) -> IndexAPI:
-        """Unreleased fast research search and exact-reference contents namespace."""
+        """Return the lazily initialized Index namespace.
+
+        Returns:
+            IndexAPI using this client's credential, backend URL and Index timeout.
+        """
         if self._index_api is None:
             from synth_ai.core.http.transport import HttpTransport
             from synth_ai.sdk.index.client import IndexAPI
@@ -71,7 +91,11 @@ class SynthClient:
 
     @property
     def messaging(self) -> MessagingClient:
-        """Typed threads, history and explicit Workshop device grants."""
+        """Return the lazily initialized Messaging namespace.
+
+        Returns:
+            MessagingClient for typed threads, history and explicit Workshop device grants.
+        """
         if self._messaging_client is None:
             from synth_ai.sdk.messaging import MessagingClient
 
@@ -84,7 +108,11 @@ class SynthClient:
 
     @property
     def research(self) -> ResearchClient:
-        """Research hero namespace (projects, swarms, and factories)."""
+        """Return the lazily initialized Research namespace.
+
+        Returns:
+            ResearchClient for hosted projects and swarms, with compatibility Factory APIs.
+        """
         if self._research_client is None:
             from synth_ai.sdk.research.facade import ResearchClient
 
@@ -113,7 +141,11 @@ class SynthClient:
 
     @property
     def optimizers(self) -> OptimizersClient:
-        """Hosted training models and searchable saved-LoRA lineage."""
+        """Return the lazily initialized hosted Optimizers namespace.
+
+        Returns:
+            OptimizersClient for hosted training model discovery and saved-LoRA lineage.
+        """
         if self._optimizers_client is None:
             from synth_ai.sdk.optimizers import OptimizersClient
 
@@ -132,7 +164,17 @@ class SynthClient:
 
 
 class AsyncSynthClient:
-    """Async client for Managed Research and hosted optimizers."""
+    """Asynchronous entry point with lazily initialized SDK namespaces.
+
+    Example:
+        ```python
+        from synth_ai import AsyncSynthClient
+
+        async def inspect_namespace():
+            async with AsyncSynthClient(api_key="YOUR_SYNTH_API_KEY") as client:
+                index = client.index
+        ```
+    """
 
     def __init__(
         self,
@@ -141,6 +183,14 @@ class AsyncSynthClient:
         base_url: str | None = None,
         timeout_seconds: float | None = None,
     ) -> None:
+        """Configure credentials, endpoint and transport timeouts without making requests.
+
+        Args:
+            api_key: Explicit Synth API credential; None uses the configured credential resolver.
+            base_url: Backend URL override; None uses the SDK's configured backend base URL.
+            timeout_seconds: Transport timeout in seconds. None uses 30 seconds for
+                Research, Messaging and Optimizers, and the Index transport default for Index.
+        """
         self.api_key = _resolve_api_key(api_key)
         self.base_url = _resolve_base_url(base_url)
         self.timeout_seconds = 30.0 if timeout_seconds is None else timeout_seconds
@@ -156,7 +206,11 @@ class AsyncSynthClient:
 
     @property
     def index(self) -> AsyncIndexAPI:
-        """Unreleased asynchronous fast search and exact-reference contents."""
+        """Return the lazily initialized asynchronous Index namespace.
+
+        Returns:
+            AsyncIndexAPI using this client's credential, backend URL and Index timeout.
+        """
         if self._index_api is None:
             from synth_ai.core.http.async_transport import AsyncHttpTransport
             from synth_ai.sdk.index.client import AsyncIndexAPI
@@ -171,7 +225,11 @@ class AsyncSynthClient:
 
     @property
     def messaging(self) -> AsyncMessagingClient:
-        """Asynchronous threads, history and explicit Workshop device grants."""
+        """Return the lazily initialized asynchronous Messaging namespace.
+
+        Returns:
+            AsyncMessagingClient for threads, history and explicit Workshop device grants.
+        """
         if self._async_messaging_client is None:
             from synth_ai.sdk.messaging import AsyncMessagingClient
 
@@ -184,7 +242,11 @@ class AsyncSynthClient:
 
     @property
     def research(self) -> AsyncResearchClient:
-        """Native asynchronous Research namespace."""
+        """Return the lazily initialized asynchronous Research namespace.
+
+        Returns:
+            AsyncResearchClient using this client's credential, backend URL and timeout.
+        """
         if self._async_research_client is None:
             from synth_ai.sdk.research import AsyncResearchClient
 
@@ -216,7 +278,11 @@ class AsyncSynthClient:
 
     @property
     def async_research(self) -> AsyncResearchClient:
-        """Deprecated alias for :attr:`research`."""
+        """Deprecated alias for :attr:`research`.
+
+        Returns:
+            The same AsyncResearchClient instance as research, after a deprecation warning.
+        """
         warnings.warn(
             "AsyncSynthClient.async_research is deprecated; use .research.",
             DeprecationWarning,
@@ -253,7 +319,11 @@ class AsyncSynthClient:
 
     @property
     def optimizers(self) -> AsyncOptimizersClient:
-        """Native asynchronous hosted optimizer namespace."""
+        """Return the lazily initialized asynchronous hosted Optimizers namespace.
+
+        Returns:
+            AsyncOptimizersClient using this client's credential, backend URL and timeout.
+        """
         if self._async_optimizers_client is None:
             from synth_ai.sdk.optimizers import AsyncOptimizersClient
 

{synth_ai-0.21.2.dev658 → synth_ai-0.21.3.dev660}/synth_ai/sdk/index/public_search.py

@@ -143,6 +143,15 @@ class PublicSearchRateLimitedError(PublicSearchError):
         failure: SynthFailure | None = None,
         status: int | None = 429,
     ) -> None:
+        """Preserve the rate-limit scope and server retry guidance.
+
+        Args:
+            message: Human-readable server failure message.
+            scope: Server rate-limit scope, or None when the server omits it.
+            retry_after_s: Server retry delay in seconds, or None when unavailable.
+            failure: Structured Synth failure envelope, when available.
+            status: HTTP status associated with the failure; defaults to 429.
+        """
         super().__init__(message, failure=failure, status=status)
         self.scope = scope
         self.retry_after_s = retry_after_s
@@ -181,6 +190,15 @@ class PublicSearchBudgetExhaustedError(PublicSearchUnavailableError):
         failure: SynthFailure | None = None,
         status: int | None = 503,
     ) -> None:
+        """Preserve the exhausted budget scope and server retry guidance.
+
+        Args:
+            message: Human-readable server failure message.
+            scope: Known exhausted budget scope, or None when the server omits it.
+            retry_after_s: Server retry delay in seconds, or None when unavailable.
+            failure: Structured Synth failure envelope, when available.
+            status: HTTP status associated with the failure; defaults to 503.
+        """
         super().__init__(message, failure=failure, status=status)
         self.scope = scope
         self.retry_after_s = retry_after_s
@@ -836,6 +854,13 @@ def public_search_result_payload(result: PublicSearchResult) -> dict[str, Any]:
 
     Carries no search token. ``route`` names the anonymous public route so a
     caller can tell it from a keyed (paid) result without inspecting charges.
+
+    Args:
+        result: Delivered public search envelope to project into JSON-compatible values.
+
+    Returns:
+        Public route, search identity, status, response, citations and charge metadata,
+        excluding the per-search credential.
     """
     return {
         "route": "public",

{synth_ai-0.21.2.dev658 → synth_ai-0.21.3.dev660}/synth_ai/sdk/research/contracts/evidence.py

@@ -281,6 +281,7 @@ class EvidenceFreshness:
     run_is_terminal: bool
     # Backend SmrSwarmEvidenceFreshnessResponse.tool_call_count (default 0);
     # older backends omit it, so it is accepted but not required.
+    #: Non-negative recorded tool-call count; defaults to zero for older backend responses.
     tool_call_count: int = 0
 
     @classmethod
@@ -312,6 +313,7 @@ class EvidenceFreshness:
 
 
 class SwarmToolCallStatus(StrEnum):
+    """Durable MCP invocation outcomes, including unresolved tool names."""
     SUCCEEDED = "succeeded"
     FAILED = "failed"
     UNKNOWN_TOOL = "unknown_tool"
@@ -341,23 +343,58 @@ class SwarmToolCallEvidence:
 
     Mirrors backend ``SmrSwarmToolCallEvidenceResponse``; arguments are only a
     digest, never the values.
+
+    ```python
+    from synth_ai.sdk.research.contracts.evidence import SwarmToolCallEvidence
+
+    from datetime import datetime, timezone
+    from synth_ai.sdk.research.contracts.evidence import SwarmToolCallStatus
+
+    call = SwarmToolCallEvidence(
+        tool_call_id="call-1", actor_role="worker", tool_name="search",
+        arguments_digest="sha256:" + "0" * 64,
+        status=SwarmToolCallStatus.SUCCEEDED, retryable=False,
+        duration_ms=10, occurred_at=datetime.now(timezone.utc),
+    )
+    assert SwarmToolCallEvidence.from_wire(call.to_wire()) == call
+    ```
     """
 
+    #: Identity of the durable MCP invocation outcome.
     tool_call_id: str
+    #: Role of the invoking actor.
     actor_role: str
+    #: Invoked MCP tool name.
     tool_name: str
+    #: Digest of invocation arguments; raw argument values are not included.
     arguments_digest: str
+    #: Recorded invocation outcome.
     status: SwarmToolCallStatus
+    #: Backend indication that the failed invocation can be retried.
     retryable: bool
+    #: Non-negative invocation duration in milliseconds.
     duration_ms: int
+    #: Timestamp of the invocation outcome.
     occurred_at: datetime
+    #: Stable identity of the invoking actor, when recorded.
     stable_actor_key: str | None = None
+    #: Invocation correlation key, when recorded.
     correlation_id: str | None = None
+    #: MCP bundle containing the tool, when recorded.
     bundle_name: str | None = None
+    #: Backend failure code, when recorded.
     error_code: str | None = None
 
     @classmethod
     def from_wire(cls, value: JsonValue) -> SwarmToolCallEvidence:
+        """Parse the backend wire representation of SwarmToolCallEvidence.
+
+        Args:
+            value: Backend response object to validate and convert.
+
+        Returns:
+            The parsed SwarmToolCallEvidence with backend values preserved.
+        """
         payload = _exact_object(
             value, label="retrieve_swarm_evidence.tool_calls", fields=_TOOL_CALL_FIELDS
         )
@@ -377,6 +414,11 @@ class SwarmToolCallEvidence:
         )
 
     def to_wire(self) -> JsonObject:
+        """Serialize this contract to its backend JSON representation.
+
+        Returns:
+            A new JSON object using backend field names and enum values.
+        """
         return {
             "tool_call_id": self.tool_call_id,
             "stable_actor_key": self.stable_actor_key,
@@ -400,6 +442,7 @@ class SwarmEvidence:
     artifacts: tuple[EvidenceArtifact, ...]
     work_products: tuple[EvidenceWorkProduct, ...]
     freshness: EvidenceFreshness
+    #: Durable run-scoped MCP invocation outcomes containing argument digests, never argument values.
     tool_calls: tuple[SwarmToolCallEvidence, ...] = ()
 
     def __post_init__(self) -> None:

{synth_ai-0.21.2.dev658 → synth_ai-0.21.3.dev660}/synth_ai/sdk/research/contracts/intern_blockers.py

@@ -19,54 +19,90 @@ class _Contract(BaseModel):
 
 
 class InternBlockerOpenSyncRequest(_Contract):
+    """Idempotent request to open an operator handoff without resolving the blocker."""
+    #: Caller retry key for opening this handoff; 1–512 characters.
     idempotency_key: str = Field(min_length=1, max_length=512)
 
 
 class InternBlockerHandoffContext(_Contract):
+    """Versioned snapshot of the blocked Async action for operator intervention."""
+    #: Version discriminator for the async-blocker handoff context.
     schema_version: Literal["smr.intern-async-blocker-handoff-context.v1"] = (
         "smr.intern-async-blocker-handoff-context.v1"
     )
+    #: Blocked action whose context is being handed off.
     blocker_id: str
+    #: Async assignment that owns the blocked action.
     async_assignment_id: str
+    #: Runtime binding carried into the operator handoff.
     binding: InternRuntimeBinding
+    #: Schema version of the blocked action.
     action_schema_version: str
+    #: Kind of action requiring operator intervention.
     action_kind: str
+    #: 64-character lowercase SHA-256 hex digest of the action.
     action_digest: str = Field(pattern=r"^[0-9a-f]{64}$")
+    #: Operator-facing description of the blocked action; at most 2,000 characters.
     summary: str = Field(min_length=1, max_length=2000)
+    #: Reason for the handoff; at most 4,000 characters.
     rationale: str = Field(min_length=1, max_length=4000)
+    #: Preauthorization rule associated with the blocked action.
     preauthorization_rule: str
+    #: Produced-resource references supporting the handoff.
     evidence_resources: tuple[InternProducedResourceReference, ...] = ()
+    #: Capability required of the operator handling this action.
     required_operator_capability: str
 
 
 class InternBlockerHandoffReceipt(_Contract):
+    """Durable evidence tying an Async blocker to its operator Sync session."""
+    #: Version discriminator for the durable handoff receipt.
     schema_version: Literal["smr.intern-async-blocker-handoff-receipt.v1"] = (
         "smr.intern-async-blocker-handoff-receipt.v1"
     )
+    #: Identity of the durable handoff receipt.
     handoff_receipt_id: str
+    #: Blocker associated with this receipt.
     blocker_id: str
+    #: Organization that owns the handoff.
     org_id: str
+    #: Sync session opened for operator intervention.
     sync_session_id: str
+    #: User recorded as opening the handoff.
     opened_by_user_id: str
+    #: Retry key used to open this handoff.
     idempotency_key: str
+    #: Snapshot of the blocked action and its runtime binding.
     context: InternBlockerHandoffContext
+    #: 64-character lowercase SHA-256 hex digest of the context.
     context_digest: str = Field(pattern=r"^[0-9a-f]{64}$")
+    #: Backend timestamp when the handoff receipt was created.
     created_at: datetime
 
 
 class InternBlockerOpenSyncResponse(_Contract):
+    """Opened operator handoff, its Sync session, and durable context receipt."""
+    #: Version discriminator for the open-sync response.
     schema_version: Literal["smr.intern-async-blocker-open-sync.v1"] = (
         "smr.intern-async-blocker-open-sync.v1"
     )
+    #: Blocker after the handoff was opened; opening alone does not resolve it.
     blocker: InternAsyncBlocker
+    #: Sync session available for the operator handoff.
     sync_session: InternSyncSession
+    #: Durable receipt tying the blocker, context, and Sync session together.
     handoff_receipt: InternBlockerHandoffReceipt
 
 
 class InternBlockerResolveRequest(_Contract):
+    """Explicit blocker disposition with optional supporting receipts."""
+    #: Caller retry key for this resolution; 1–512 characters.
     idempotency_key: str = Field(min_length=1, max_length=512)
+    #: Explicit completed, denied, or superseded disposition.
     outcome: Literal["completed", "denied", "superseded"]
+    #: Optional operator explanation; at most 4,000 characters.
     comment: str | None = Field(default=None, max_length=4000)
+    #: Up to 128 unique, non-blank supporting receipt IDs, each at most 512 characters.
     supporting_receipt_ids: tuple[str, ...] = Field(default=(), max_length=128)
 
     @model_validator(mode="after")
@@ -79,8 +115,12 @@ class InternBlockerResolveRequest(_Contract):
 
 
 class InternBlockerResolveResponse(_Contract):
+    """Resolved blocker and durable continuation-command receipt."""
+    #: Version discriminator for the resolution response.
     schema_version: Literal["smr.intern-async-blocker-resolution.v1"] = (
         "smr.intern-async-blocker-resolution.v1"
     )
+    #: Blocker carrying the durable resolution receipt.
     blocker: InternAsyncBlocker
+    #: Durable command receipt for continuation of the owning Async assignment.
     continuation_command: InternAsyncCommandReceipt

{synth_ai-0.21.2.dev658 → synth_ai-0.21.3.dev660}/synth_ai/sdk/research/contracts/intern_resources.py

@@ -22,14 +22,23 @@ InternRuntimeClosureKind = Literal[
 
 
 class InternResourceDisposition(BaseModel):
+    """Ownership relation and recorded cleanup disposition for one registered resource."""
     model_config = ConfigDict(extra="forbid", frozen=True)
+    #: Registered resource type.
     resource_kind: str
+    #: Identity of the registered resource.
     resource_id: str
+    #: Run responsible for cleanup, when known.
     cleanup_owner_run_id: str | None = None
+    #: Ownership relation to this runtime: self, owned, borrowed, shared, or retained.
     relation: Literal["self", "owned", "borrowed", "shared", "retained"]
+    #: Recorded cleanup disposition; unknown and pending do not mean settled.
     disposition: InternResourceDispositionValue
+    #: Backend explanation for the recorded disposition.
     reason: str
+    #: Cleanup owner label, when recorded.
     cleanup_owner: str | None = None
+    #: Non-negative admission epoch associated with the resource, when known.
     epoch: int | None = Field(default=None, ge=0)
 
 
@@ -37,9 +46,12 @@ class InternResourceStopEffect(BaseModel):
     """An effect actually performed when a runtime epoch closed."""
 
     model_config = ConfigDict(extra="forbid", frozen=True)
+    #: Resource type affected by runtime closure.
     resource_kind: str
+    #: Identity of the resource affected by closure.
     resource_id: str
     # Close-time effects, then the real outcome of each internal run stop.
+    #: Recorded closure effect or actual internal-run stop outcome.
     effect: Literal[
         "stop_requested",
         "already_settled",
@@ -50,7 +62,9 @@ class InternResourceStopEffect(BaseModel):
         "stop_accepted",
         "stop_failed",
     ]
+    #: Owner recorded for this effect, when available.
     owner: str | None = None
+    #: Backend explanation of the closure effect.
     reason: str
 
 
@@ -58,32 +72,76 @@ class InternRuntimeResourceEpoch(BaseModel):
     """One admission epoch; closed epochs remain enumerated for recovery."""
 
     model_config = ConfigDict(extra="forbid", frozen=True)
+    #: Non-negative admission epoch number.
     epoch: int = Field(ge=0)
+    #: Whether the epoch accepts new resources.
     admission: Literal["open", "closed"]
+    #: Reason admission closed; absent while no closure is recorded.
     closure_kind: InternRuntimeClosureKind | None = None
+    #: Timestamp when the admission epoch opened.
     opened_at: datetime
+    #: Timestamp when admission closed, if recorded.
     closed_at: datetime | None = None
+    #: Effects recorded when this epoch closed, including internal-run stop outcomes.
     effects: list[InternResourceStopEffect] = Field(default_factory=list)
     # Null while the backend re-drive pass is still converging this epoch.
+    #: Cleanup settlement timestamp; null while backend recovery is still converging.
     cleanup_settled_at: datetime | None = None
 
 
 class InternResourceInventory(BaseModel):
+    """Runtime resource observation; creator coverage and cleanup completeness are separate.
+
+    ```python
+    from synth_ai.sdk.research.contracts.intern_resources import InternResourceInventory
+
+    inventory = InternResourceInventory.from_wire({
+        "runtime_kind": "sync", "runtime_id": "session-1",
+        "observed_at": "2026-09-29T12:00:00+00:00",
+        "coverage": "registered-runtime-resources-v1",
+        "coverage_complete": False, "resources": [],
+    })
+    assert not inventory.disposition_complete
+    ```
+    """
+
     model_config = ConfigDict(extra="forbid", frozen=True)
+    #: Sync session or Async assignment inventory kind.
     runtime_kind: Literal["sync", "async"]
+    #: Identity of the session or assignment whose resources were observed.
     runtime_id: str
+    #: Backend timestamp of this inventory observation.
     observed_at: datetime
+    #: Inventory contract discriminator: registered-runtime-resources-v1.
     coverage: Literal["registered-runtime-resources-v1"]
+    #: Whether creator coverage is complete; separate from resource cleanup.
     coverage_complete: StrictBool
+    #: Backend reasons creator coverage is incomplete.
     incomplete_reasons: list[str] = Field(default_factory=list)
+    #: Registered resources and their individual dispositions.
     resources: list[InternResourceDisposition]
+    #: Recorded creator-set identifier, when available.
     creator_set: str | None = None
+    #: Inventory profile recorded by the backend, when available.
     profile: str | None = None
+    #: Whether cleanup is complete; cannot be true with incomplete creator coverage.
     disposition_complete: StrictBool = False
+    #: Admission epochs retained for recovery, including closed epochs.
     epochs: list[InternRuntimeResourceEpoch] = Field(default_factory=list)
 
     @classmethod
-    def from_wire(cls, value):
+    def from_wire(cls, value: object) -> "InternResourceInventory":
+        """Parse the backend wire representation of InternResourceInventory.
+
+        Args:
+            value: Backend response object to validate and convert.
+
+        Returns:
+            The parsed InternResourceInventory with backend values preserved.
+
+        Raises:
+            ValueError: Cleanup is reported complete despite incomplete creator coverage.
+        """
         inventory = cls.model_validate(value)
         # A complete cleanup can never rest on incomplete creator coverage.
         if inventory.disposition_complete and not inventory.coverage_complete: