synth-ai 0.22.2.dev678__tar.gz → 0.22.2.dev680__tar.gz

{synth_ai-0.22.2.dev678/synth_ai.egg-info → synth_ai-0.22.2.dev680}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.22.2.dev678
+Version: 0.22.2.dev680
 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.22.2.dev678 → synth_ai-0.22.2.dev680}/openapi/research-v1.json

@@ -22119,6 +22119,131 @@
         "title": "SmrOpenEndedQuestionInlineCreateRequest",
         "type": "object"
       },
+      "SmrOrchestraActionAnswerRequest": {
+        "additionalProperties": false,
+        "description": "Answer one Orchestra ``pending_questions[]`` action (``action_answer``).",
+        "properties": {
+          "idempotency_key": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Idempotency Key"
+          },
+          "response_text": {
+            "minLength": 1,
+            "title": "Response Text",
+            "type": "string"
+          }
+        },
+        "required": [
+          "response_text"
+        ],
+        "title": "SmrOrchestraActionAnswerRequest",
+        "type": "object"
+      },
+      "SmrOrchestraOperationReceiptResponse": {
+        "additionalProperties": false,
+        "description": "Orchestra's write receipt for a public answer/steer (HTTP 202).\n\n``status`` is Orchestra's: ``accepted`` for a new write, ``duplicate`` for\na replay of the same ``operation_id`` with the same request.",
+        "properties": {
+          "action_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Action Id"
+          },
+          "control_seq": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Control Seq"
+          },
+          "interaction_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Interaction Id"
+          },
+          "kind": {
+            "enum": [
+              "action_answer",
+              "steer"
+            ],
+            "title": "Kind",
+            "type": "string"
+          },
+          "operation_id": {
+            "title": "Operation Id",
+            "type": "string"
+          },
+          "run_id": {
+            "title": "Run Id",
+            "type": "string"
+          },
+          "status": {
+            "enum": [
+              "accepted",
+              "duplicate"
+            ],
+            "title": "Status",
+            "type": "string"
+          }
+        },
+        "required": [
+          "run_id",
+          "operation_id",
+          "kind",
+          "status"
+        ],
+        "title": "SmrOrchestraOperationReceiptResponse",
+        "type": "object"
+      },
+      "SmrOrchestraSteerRequest": {
+        "additionalProperties": false,
+        "description": "Steer an orchestra-authority run (Orchestra ``RunControl::Steer``).",
+        "properties": {
+          "idempotency_key": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Idempotency Key"
+          },
+          "message": {
+            "minLength": 1,
+            "title": "Message",
+            "type": "string"
+          }
+        },
+        "required": [
+          "message"
+        ],
+        "title": "SmrOrchestraSteerRequest",
+        "type": "object"
+      },
       "SmrPatchVisualRequest": {
         "properties": {
           "summary": {
@@ -50558,6 +50683,78 @@
         ]
       }
     },
+    "/smr/runs/{run_id}/actions/{action_id}/answer": {
+      "post": {
+        "description": "Answer an Orchestra ``pending_questions[]`` action on an orchestra run.",
+        "operationId": "answer_run_action",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "run_id",
+            "required": true,
+            "schema": {
+              "title": "Run Id",
+              "type": "string"
+            }
+          },
+          {
+            "in": "path",
+            "name": "action_id",
+            "required": true,
+            "schema": {
+              "minLength": 1,
+              "title": "Action Id",
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SmrOrchestraActionAnswerRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "202": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SmrOrchestraOperationReceiptResponse"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "404": {
+            "description": "Run not found in the caller's organization."
+          },
+          "409": {
+            "description": "run_not_orchestra_authority | terminal_run | answer_conflict | idempotency_conflict | orchestra_run_not_launched | project_archived"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          },
+          "503": {
+            "description": "orchestra_in_doubt | orchestra_unavailable (retryable)"
+          }
+        },
+        "summary": "Answer Run Action",
+        "tags": [
+          "smr"
+        ]
+      }
+    },
     "/smr/runs/{run_id}/activity": {
       "get": {
         "description": "Return typed bounded execution activity for a swarm.",
@@ -52050,6 +52247,68 @@
         ]
       }
     },
+    "/smr/runs/{run_id}/steer": {
+      "post": {
+        "description": "Steer an orchestra-authority run (Orchestra ``RunControl::Steer``).",
+        "operationId": "steer_run",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "run_id",
+            "required": true,
+            "schema": {
+              "title": "Run Id",
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SmrOrchestraSteerRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "202": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SmrOrchestraOperationReceiptResponse"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "404": {
+            "description": "Run not found in the caller's organization."
+          },
+          "409": {
+            "description": "run_not_orchestra_authority | terminal_run | answer_conflict | idempotency_conflict | orchestra_run_not_launched | project_archived"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          },
+          "503": {
+            "description": "orchestra_in_doubt | orchestra_unavailable (retryable)"
+          }
+        },
+        "summary": "Steer Run",
+        "tags": [
+          "smr"
+        ]
+      }
+    },
     "/smr/runs/{run_id}/stop": {
       "post": {
         "operationId": "stop_run",

{synth_ai-0.22.2.dev678 → synth_ai-0.22.2.dev680}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synth-ai"
-version = "0.22.2.dev678"
+version = "0.22.2.dev680"
 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.22.2.dev678 → synth_ai-0.22.2.dev680}/synth_ai/sdk/index/contributions.py

@@ -13,6 +13,7 @@ from uuid import UUID
 from pydantic import BeforeValidator, Field, StringConstraints, field_validator, model_validator
 
 from synth_ai.sdk.research.contracts.forge.contracts import ExactReference, Identifier
+from synth_ai.sdk.research.contracts.forge.operations import RevisionReference
 
 from .artifacts import ArtifactPublicationPrepareResponse, ArtifactUuid
 from .contracts import ContributionReference, IndexContract
@@ -112,13 +113,36 @@ class ForgeResearchSource(IndexContract):
         return self
 
 
+ARCHIVE_V3 = "forge.private-archive.v3"
+
+
 class ForgePublicResearchSource(ForgeResearchSource):
-    """Exact private archive plus safe proposed public credit; backend decides release."""
+    """Exact private archive plus safe proposed public credit; backend decides release.
+
+    Mirrors backend ``packages/contributions/forge_release.py``. ``revision_reference``
+    (Forge decision 0001, ``forge.revision-reference.v1``) binds the selected export's
+    producer, operation and time, not only its payload; ``archive_schema_version`` names
+    the private archive version that carries those references (v3). The backend public
+    review policy refuses a Forge-origin public source that omits either
+    (``forge_revision_reference_required``, ``forge_archive_v3_required``); they stay
+    optional on the wire so older private registrations still decode.
+    """
 
     schema_version: Literal["synth.index.forge-source.v2"] = "synth.index.forge-source.v2"
     archive_publication_id: ArtifactUuid
     archive_manifest_digest_sha256: Digest
     public_provenance: PublicScientificProvenance
+    revision_reference: RevisionReference | None = None
+    archive_schema_version: Literal["forge.private-archive.v3"] | None = None
+
+    @model_validator(mode="after")
+    def provenance_pin_names_the_export(self):
+        if (
+            self.revision_reference is not None
+            and self.revision_reference.reference != self.export
+        ):
+            raise ValueError("revision reference must name the exported revision")
+        return self
 
 
 def _legacy_source_version(value):

{synth_ai-0.22.2.dev678 → synth_ai-0.22.2.dev680}/synth_ai/sdk/research/contracts/__init__.py

@@ -428,6 +428,7 @@ from synth_ai.sdk.research.contracts.runtime_stream_snapshot import (
     RuntimeWorkersSnapshot,
     SwarmRuntimeSnapshot,
 )
+from synth_ai.sdk.research.contracts.swarm_controls import SwarmControlReceipt
 from synth_ai.sdk.research.contracts.swarms import (
     ActiveActorModel,
     ActorHarness,
@@ -610,6 +611,7 @@ def __getattr__(name: str) -> object:
 
 
 __all__ = [
+    "SwarmControlReceipt",
     "AiCacheMode",
     "AiCachePolicy",
     "ActiveActorModel",

{synth_ai-0.22.2.dev678 → synth_ai-0.22.2.dev680}/synth_ai/sdk/research/contracts/forge/operations.py

@@ -10,6 +10,7 @@ from .contracts import (
     Contract,
     Digest,
     ExactReference,
+    ForgeError,
     Identifier,
     Producer,
     Scope,
@@ -67,6 +68,35 @@ class RecordRevision(Contract):
     recorded_at: AwareDatetime
 
 
+REVISION_REFERENCE_V1 = "forge.revision-reference.v1"
+
+
+class RevisionReference(Contract):
+    """Exact identity of one complete retained revision, provenance included.
+
+    See docs/decisions/0001. ``reference.digest_sha256`` keeps its payload-only
+    meaning; ``document_digest_sha256`` binds producer, operation and time too.
+    It proves the document Forge recorded, not external producer attestation.
+    """
+
+    schema_version: Literal["forge.revision-reference.v1"] = REVISION_REFERENCE_V1
+    reference: ExactReference
+    document_digest_sha256: Digest
+
+
+def revision_reference(record: RecordRevision) -> RevisionReference:
+    record = RecordRevision.model_validate(record.model_dump(mode="json"))
+    if (
+        record.reference.authority != "forge"
+        or record.reference.kind != record.payload.kind
+        or record.reference.digest_sha256 != contract_digest(record.payload)
+    ):
+        raise ForgeError("reference_conflict", "record differs from exact source bytes")
+    return RevisionReference(
+        reference=record.reference, document_digest_sha256=contract_digest(record)
+    )
+
+
 class PublicWrite(Contract):
     """Public intent; backend supplies authenticated producer and canonical scope."""
 

synth_ai-0.22.2.dev680/synth_ai/sdk/research/contracts/swarm_controls.py

@@ -0,0 +1,55 @@
+"""Receipts for backend-owned native Swarm answer and steer operations.
+
+# See: openapi/research-v1.json SmrOrchestraOperationReceiptResponse
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, cast
+
+from synth_ai.core.contracts.json_value import JsonValue
+from synth_ai.sdk.research.contracts._wire import object_value, optional_text, required_text
+from synth_ai.sdk.research.contracts.common import SwarmId
+
+ControlKind = Literal["action_answer", "steer"]
+ControlStatus = Literal["accepted", "duplicate"]
+
+
+@dataclass(frozen=True, slots=True)
+class SwarmControlReceipt:
+    """Durable acceptance acknowledgement; execution delivery remains asynchronous."""
+
+    swarm_id: SwarmId
+    operation_id: str
+    kind: ControlKind
+    status: ControlStatus
+    action_id: str | None = None
+    interaction_id: str | None = None
+    control_seq: int | None = None
+
+    @classmethod
+    def from_wire(cls, value: JsonValue) -> SwarmControlReceipt:
+        payload = object_value(value, operation_id="swarm control receipt")
+        required = {"run_id", "operation_id", "kind", "status"}
+        allowed = required | {"action_id", "interaction_id", "control_seq"}
+        if required - payload.keys() or payload.keys() - allowed:
+            raise ValueError("swarm control receipt fields drifted")
+        kind, status = required_text(payload, "kind"), required_text(payload, "status")
+        if kind not in ("action_answer", "steer") or status not in ("accepted", "duplicate"):
+            raise ValueError("swarm control receipt vocabulary drifted")
+        sequence = payload.get("control_seq")
+        if sequence is not None and (type(sequence) is not int or sequence < 0):
+            raise ValueError("swarm control sequence must be a non-negative integer")
+        return cls(
+            SwarmId(required_text(payload, "run_id")),
+            required_text(payload, "operation_id"),
+            cast(ControlKind, kind),
+            cast(ControlStatus, status),
+            optional_text(payload, "action_id"),
+            optional_text(payload, "interaction_id"),
+            cast(int | None, sequence),
+        )
+
+
+__all__ = ["SwarmControlReceipt"]

{synth_ai-0.22.2.dev678 → synth_ai-0.22.2.dev680}/synth_ai/sdk/research/operations.py

@@ -22,6 +22,16 @@ def _operation(
 RESEARCH_OPERATIONS = {
     operation.operation_id: operation
     for operation in (
+        _operation(
+            "steer_run", HttpMethod.POST, "/smr/runs/{run_id}/steer", mutation=True, idempotent=True
+        ),
+        _operation(
+            "answer_run_action",
+            HttpMethod.POST,
+            "/smr/runs/{run_id}/actions/{action_id}/answer",
+            mutation=True,
+            idempotent=True,
+        ),
         _operation(
             "getExactDatasetRevision",
             HttpMethod.GET,

{synth_ai-0.22.2.dev678 → synth_ai-0.22.2.dev680}/synth_ai/sdk/research/swarms.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 import time
 from collections.abc import AsyncIterator, Iterator, Mapping
+from urllib.parse import quote
 
 from synth_ai.core.contracts.json_value import JsonObject, JsonValue
 from synth_ai.core.errors import SynthError
@@ -19,6 +20,7 @@ from synth_ai.sdk.research.contracts.common import (
     ProjectId,
     SwarmId,
     WorkProductId,
+    require_text,
 )
 from synth_ai.sdk.research.contracts.evidence import (
     ContentDisposition,
@@ -26,6 +28,7 @@ from synth_ai.sdk.research.contracts.evidence import (
 )
 from synth_ai.sdk.research.contracts.resource_settlement import RunResourceSettlement
 from synth_ai.sdk.research.contracts.status import SwarmStatus
+from synth_ai.sdk.research.contracts.swarm_controls import SwarmControlReceipt
 from synth_ai.sdk.research.contracts.swarm_rollouts import SwarmRollout, swarm_rollouts_from_wire
 from synth_ai.sdk.research.contracts.swarms import (
     BranchResult,
@@ -100,6 +103,31 @@ def _stream_timeout(timeout_seconds: float | None) -> float | None:
     return timeout_seconds
 
 
+def _control_body(field: str, text: str, idempotency_key: str | None) -> JsonObject:
+    if not isinstance(text, str) or not text.strip() or len(text.encode("utf-8")) > 16_384:
+        raise ValueError(f"{field} must be nonblank and at most 16384 UTF-8 bytes")
+    body: JsonObject = {field: text}
+    if idempotency_key is not None:
+        key = require_text(idempotency_key, field_name="idempotency_key")
+        if len(key) > 255:
+            raise ValueError("idempotency_key must be at most 255 characters")
+        body["idempotency_key"] = key
+    return body
+
+
+def _control_receipt(
+    value: JsonValue, swarm_id: SwarmId, kind: str, action_id: str | None = None
+) -> SwarmControlReceipt:
+    receipt = SwarmControlReceipt.from_wire(value)
+    if (
+        receipt.swarm_id != swarm_id
+        or receipt.kind != kind
+        or (action_id is not None and receipt.action_id != action_id)
+    ):
+        raise ValueError("swarm control receipt does not match the request scope")
+    return receipt
+
+
 class SwarmHandle:
     """Handle returned when creating a Swarm."""
 
@@ -281,6 +309,18 @@ class SwarmHandle:
             timeout_seconds=timeout_seconds,
         )
 
+    def steer(self, message: str, *, idempotency_key: str | None = None) -> SwarmControlReceipt:
+        """Request native steering; acceptance is distinct from execution delivery."""
+        return self._api.steer(self.swarm_id, message, idempotency_key=idempotency_key)
+
+    def answer_action(
+        self, action_id: str, response_text: str, *, idempotency_key: str | None = None
+    ) -> SwarmControlReceipt:
+        """Answer the correlated action exposed by authoritative native history."""
+        return self._api.answer_action(
+            self.swarm_id, action_id, response_text, idempotency_key=idempotency_key
+        )
+
 
 class SwarmsAPI:
     """Swarm lifecycle operations."""
@@ -731,6 +771,38 @@ class SwarmsAPI:
         ):
             yield decode_swarm_event(event)
 
+    def steer(
+        self, swarm_id: SwarmId, message: str, *, idempotency_key: str | None = None
+    ) -> SwarmControlReceipt:
+        """Steer through the backend's native control ledger; reuse a key for retries."""
+        value = self._transport.execute(
+            _request(
+                "steer_run",
+                f"/smr/runs/{swarm_id}/steer",
+                body=_control_body("message", message, idempotency_key),
+            )
+        )
+        return _control_receipt(value, swarm_id, "steer")
+
+    def answer_action(
+        self,
+        swarm_id: SwarmId,
+        action_id: str,
+        response_text: str,
+        *,
+        idempotency_key: str | None = None,
+    ) -> SwarmControlReceipt:
+        """Answer a native action; changed bytes with the same key conflict server-side."""
+        action = require_text(action_id, field_name="action_id")
+        value = self._transport.execute(
+            _request(
+                "answer_run_action",
+                f"/smr/runs/{swarm_id}/actions/{quote(action, safe='')}/answer",
+                body=_control_body("response_text", response_text, idempotency_key),
+            )
+        )
+        return _control_receipt(value, swarm_id, "action_answer", action)
+
 
 class AsyncSwarmHandle:
     """Handle returned when creating a Swarm."""
@@ -918,6 +990,20 @@ class AsyncSwarmHandle:
         ):
             yield event
 
+    async def steer(
+        self, message: str, *, idempotency_key: str | None = None
+    ) -> SwarmControlReceipt:
+        """Request native steering; acceptance is distinct from execution delivery."""
+        return await self._api.steer(self.swarm_id, message, idempotency_key=idempotency_key)
+
+    async def answer_action(
+        self, action_id: str, response_text: str, *, idempotency_key: str | None = None
+    ) -> SwarmControlReceipt:
+        """Answer the correlated action exposed by authoritative native history."""
+        return await self._api.answer_action(
+            self.swarm_id, action_id, response_text, idempotency_key=idempotency_key
+        )
+
 
 class AsyncSwarmsAPI:
     """Swarm lifecycle operations."""
@@ -1340,6 +1426,38 @@ class AsyncSwarmsAPI:
         ):
             yield decode_swarm_event(event)
 
+    async def steer(
+        self, swarm_id: SwarmId, message: str, *, idempotency_key: str | None = None
+    ) -> SwarmControlReceipt:
+        """Steer through the backend's native control ledger; reuse a key for retries."""
+        value = await self._transport.execute(
+            _request(
+                "steer_run",
+                f"/smr/runs/{swarm_id}/steer",
+                body=_control_body("message", message, idempotency_key),
+            )
+        )
+        return _control_receipt(value, swarm_id, "steer")
+
+    async def answer_action(
+        self,
+        swarm_id: SwarmId,
+        action_id: str,
+        response_text: str,
+        *,
+        idempotency_key: str | None = None,
+    ) -> SwarmControlReceipt:
+        """Answer a native action; changed bytes with the same key conflict server-side."""
+        action = require_text(action_id, field_name="action_id")
+        value = await self._transport.execute(
+            _request(
+                "answer_run_action",
+                f"/smr/runs/{swarm_id}/actions/{quote(action, safe='')}/answer",
+                body=_control_body("response_text", response_text, idempotency_key),
+            )
+        )
+        return _control_receipt(value, swarm_id, "action_answer", action)
+
 
 ResearchSwarmHandle = SwarmHandle
 ResearchSwarmsAPI = SwarmsAPI

{synth_ai-0.22.2.dev678 → synth_ai-0.22.2.dev680/synth_ai.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.22.2.dev678
+Version: 0.22.2.dev680
 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.22.2.dev678 → synth_ai-0.22.2.dev680}/synth_ai.egg-info/SOURCES.txt

@@ -276,6 +276,7 @@ synth_ai/sdk/research/contracts/smr_runtime_kinds.py
 synth_ai/sdk/research/contracts/smr_tool_providers.py
 synth_ai/sdk/research/contracts/smr_work_modes.py
 synth_ai/sdk/research/contracts/status.py
+synth_ai/sdk/research/contracts/swarm_controls.py
 synth_ai/sdk/research/contracts/swarm_rollouts.py
 synth_ai/sdk/research/contracts/swarms.py
 synth_ai/sdk/research/contracts/tag.py