synth-ai 0.22.0.dev664__tar.gz → 0.22.1.dev668__tar.gz

{synth_ai-0.22.0.dev664/synth_ai.egg-info → synth_ai-0.22.1.dev668}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.22.0.dev664
+Version: 0.22.1.dev668
 Summary: Python SDK, CLI and MCP servers for Synth Index search and Swarms
 Author-email: Synth AI <josh@usesynth.ai>
 License-Expression: MIT
@@ -30,9 +30,9 @@ Dynamic: license-file
 
 # Synth AI SDK
 
-<!-- CI release pins: PyPI-0.22.0-orange synth-ai==0.22.0 -->
+<!-- CI release pins: PyPI-0.22.1-orange synth-ai==0.22.1 -->
 
-> 0.22.0 is the Index v0.2 release (typed QA/lifecycle APIs, CLI and MCP tools).
+> The 0.22.1 development candidate completes Index v0.2 client coverage for revision rights and research corrections. Stable 0.22.0 remains published.
 
 [![PyPI version](https://img.shields.io/pypi/v/synth-ai.svg)](https://pypi.org/project/synth-ai/)
 [![License](https://img.shields.io/pypi/l/synth-ai.svg)](https://pypi.org/project/synth-ai/)

{synth_ai-0.22.0.dev664 → synth_ai-0.22.1.dev668}/README.md

@@ -1,8 +1,8 @@
 # Synth AI SDK
 
-<!-- CI release pins: PyPI-0.22.0-orange synth-ai==0.22.0 -->
+<!-- CI release pins: PyPI-0.22.1-orange synth-ai==0.22.1 -->
 
-> 0.22.0 is the Index v0.2 release (typed QA/lifecycle APIs, CLI and MCP tools).
+> The 0.22.1 development candidate completes Index v0.2 client coverage for revision rights and research corrections. Stable 0.22.0 remains published.
 
 [![PyPI version](https://img.shields.io/pypi/v/synth-ai.svg)](https://pypi.org/project/synth-ai/)
 [![License](https://img.shields.io/pypi/l/synth-ai.svg)](https://pypi.org/project/synth-ai/)

{synth_ai-0.22.0.dev664 → synth_ai-0.22.1.dev668}/openapi/index-v1.json

@@ -7756,6 +7756,164 @@
         "title": "RewardReverseSpec",
         "type": "object"
       },
+      "RightsAttestationSpec": {
+        "additionalProperties": false,
+        "description": "Rights owner's exact claim; every digest must match the sealed revision.",
+        "properties": {
+          "descriptor_digest": {
+            "pattern": "^[0-9a-f]{64}$",
+            "title": "Descriptor Digest",
+            "type": "string"
+          },
+          "licenses": {
+            "items": {
+              "maxLength": 256,
+              "minLength": 1,
+              "type": "string"
+            },
+            "maxItems": 64,
+            "minItems": 1,
+            "title": "Licenses",
+            "type": "array"
+          },
+          "manifest_digest": {
+            "pattern": "^[0-9a-f]{64}$",
+            "title": "Manifest Digest",
+            "type": "string"
+          },
+          "notices_digest": {
+            "pattern": "^[0-9a-f]{64}$",
+            "title": "Notices Digest",
+            "type": "string"
+          },
+          "rights_decision_ref": {
+            "maxLength": 512,
+            "minLength": 1,
+            "title": "Rights Decision Ref",
+            "type": "string"
+          }
+        },
+        "required": [
+          "manifest_digest",
+          "descriptor_digest",
+          "rights_decision_ref",
+          "licenses",
+          "notices_digest"
+        ],
+        "title": "RightsAttestationSpec",
+        "type": "object"
+      },
+      "RightsAttestationView": {
+        "additionalProperties": false,
+        "properties": {
+          "attested_at": {
+            "format": "date-time",
+            "title": "Attested At",
+            "type": "string"
+          },
+          "attester_org_id": {
+            "anyOf": [
+              {
+                "format": "uuid",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Attester Org Id"
+          },
+          "attester_user_id": {
+            "format": "uuid",
+            "title": "Attester User Id",
+            "type": "string"
+          },
+          "authority": {
+            "$ref": "#/components/schemas/RightsAuthority"
+          },
+          "descriptor_digest": {
+            "pattern": "^[0-9a-f]{64}$",
+            "title": "Descriptor Digest",
+            "type": "string"
+          },
+          "licenses": {
+            "items": {
+              "maxLength": 256,
+              "minLength": 1,
+              "type": "string"
+            },
+            "title": "Licenses",
+            "type": "array"
+          },
+          "manifest_digest": {
+            "pattern": "^[0-9a-f]{64}$",
+            "title": "Manifest Digest",
+            "type": "string"
+          },
+          "notices_digest": {
+            "pattern": "^[0-9a-f]{64}$",
+            "title": "Notices Digest",
+            "type": "string"
+          },
+          "queue": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/RightsQueue"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "revision_id": {
+            "title": "Revision Id",
+            "type": "string"
+          },
+          "rights_decision_ref": {
+            "maxLength": 512,
+            "minLength": 1,
+            "title": "Rights Decision Ref",
+            "type": "string"
+          },
+          "schema_version": {
+            "default": "research-rights-attestation-v1",
+            "title": "Schema Version",
+            "type": "string"
+          }
+        },
+        "required": [
+          "revision_id",
+          "authority",
+          "queue",
+          "attester_user_id",
+          "attester_org_id",
+          "manifest_digest",
+          "descriptor_digest",
+          "rights_decision_ref",
+          "licenses",
+          "notices_digest",
+          "attested_at"
+        ],
+        "title": "RightsAttestationView",
+        "type": "object"
+      },
+      "RightsAuthority": {
+        "description": "Who may attest; mirrors ``index_rights_attestations.authority`` (SYN-3437).\n\nSynth-origin work is attested by the queue rights owner. Any other origin is\nattested by an OWNER/ADMIN of the contributing org, who holds the rights.",
+        "enum": [
+          "queue_rights_owner",
+          "contributing_org_admin"
+        ],
+        "title": "RightsAuthority",
+        "type": "string"
+      },
+      "RightsQueue": {
+        "description": "Queues whose owner may attest rights; mirrors ``index_rights_owners.queue``.",
+        "enum": [
+          "index-corpus-qa"
+        ],
+        "title": "RightsQueue",
+        "type": "string"
+      },
       "RunPreflightSpec": {
         "additionalProperties": false,
         "properties": {
@@ -11958,6 +12116,109 @@
         ]
       }
     },
+    "/api/v1/index/contributions/{contribution_id}/revisions/{revision_id}/research-registration": {
+      "post": {
+        "description": "Bind a resealed export bundle to a research correction child draft.",
+        "operationId": "index.contributions.research.correction_registration",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "contribution_id",
+            "required": true,
+            "schema": {
+              "maxLength": 128,
+              "minLength": 1,
+              "title": "Contribution Id",
+              "type": "string"
+            }
+          },
+          {
+            "in": "path",
+            "name": "revision_id",
+            "required": true,
+            "schema": {
+              "maxLength": 128,
+              "minLength": 1,
+              "title": "Revision Id",
+              "type": "string"
+            }
+          },
+          {
+            "in": "header",
+            "name": "Idempotency-Key",
+            "required": true,
+            "schema": {
+              "maxLength": 128,
+              "minLength": 1,
+              "pattern": "^[a-zA-Z0-9_.-]+$",
+              "title": "Idempotency-Key",
+              "type": "string"
+            }
+          },
+          {
+            "in": "header",
+            "name": "Synth-Acceptance-Context",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Synth-Acceptance-Context"
+            }
+          },
+          {
+            "in": "header",
+            "name": "Synth-Acceptance-Signature",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Synth-Acceptance-Signature"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateResearchContributionSpec"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "204": {
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Register Correction",
+        "tags": [
+          "index-contributions"
+        ]
+      }
+    },
     "/api/v1/index/contributions/{contribution_id}/revisions/{revision_id}/reviews": {
       "post": {
         "operationId": "index.contributions.reviews.create",
@@ -12065,6 +12326,70 @@
         ]
       }
     },
+    "/api/v1/index/contributions/{contribution_id}/revisions/{revision_id}/rights-attestation": {
+      "post": {
+        "description": "The rights holder attests one exact sealed revision; separate from consent.\n\nSynth-origin: this environment's current ``index_queue_policies`` rights\nowner, read in the same transaction; an unset queue refuses\n(``queue_policy_unset``). Other origins: an OWNER/ADMIN of the\ncontributing org (SYN-3437), which needs no queue policy.",
+        "operationId": "index.research.rights_attestation.create",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "contribution_id",
+            "required": true,
+            "schema": {
+              "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$",
+              "title": "Contribution Id",
+              "type": "string"
+            }
+          },
+          {
+            "in": "path",
+            "name": "revision_id",
+            "required": true,
+            "schema": {
+              "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$",
+              "title": "Revision Id",
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RightsAttestationSpec"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RightsAttestationView"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Attest Revision Rights",
+        "tags": [
+          "index-research"
+        ]
+      }
+    },
     "/api/v1/index/contributions/{contribution_id}/revisions/{revision_id}/submit": {
       "post": {
         "operationId": "index.contributions.submit",

{synth_ai-0.22.0.dev664 → synth_ai-0.22.1.dev668}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synth-ai"
-version = "0.22.0.dev664"
+version = "0.22.1.dev668"
 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.0.dev664 → synth_ai-0.22.1.dev668}/synth_ai/sdk/index/client.py

@@ -13,7 +13,7 @@ from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass
 from datetime import datetime
 from hashlib import sha256
-from typing import Awaitable, Any
+from typing import Any, Awaitable
 from uuid import UUID, uuid4
 
 from synth_ai.core.errors import SynthError
@@ -117,6 +117,7 @@ from .retry import (
     is_transient_search_failure,
     search_id_from_error,
 )
+from .rights import RightsAttestationSpec, RightsAttestationView
 from .search import (
     ContentsResult,
     ContentsSpec,
@@ -164,6 +165,9 @@ OPERATIONS: Mapping[str, tuple[str, str]] = {
     "index.contents.retrieve": ("POST", f"{_P}/contents"),
     "index.contributions.create": ("POST", f"{_P}/contributions"),
     "index.contributions.research.create": ("POST", f"{_P}/contributions/research"),
+    "index.contributions.research.correction_registration": (
+        "POST", f"{_R}/research-registration"
+    ),
     "index.qa.cases.create": ("POST", _P + "/qa/cases"),
     "index.qa.cases.get": ("GET", _P + "/qa/cases/{case_id}"),
     "index.qa.events.list": ("GET", _P + "/qa/cases/{case_id}/events"),
@@ -217,6 +221,7 @@ OPERATIONS: Mapping[str, tuple[str, str]] = {
     "index.research.binding.create": ("POST", f"{_R}/research-binding"),
     "index.research.consent.create": ("POST", f"{_R}/release-consent"),
     "index.research.reproduction.create": ("POST", f"{_R}/reproduction-attestations"),
+    "index.research.rights_attestation.create": ("POST", f"{_R}/rights-attestation"),
     "index.research.disclosure.revoke": ("POST", f"{_R}/disclosure-revocation"),
     "index.reviews.list": ("GET", f"{_P}/reviews"),
     "index.tags.list": ("GET", f"{_P}/tags"),
@@ -1530,6 +1535,52 @@ class ContributionsAPI(_Resource):
             )
         )
 
+    def register_research_correction(
+        self,
+        reference: ContributionReference,
+        spec: ResearchDraftSpec,
+        *,
+        idempotency_key: str,
+    ) -> None | Awaitable[None]:
+        """Bind a resealed export bundle to an existing private correction draft.
+
+        See sibling backend/notes/specifications/synth-index/research-export-bundle.md.
+
+        Args:
+            reference: Exact existing child Contribution revision to register.
+            spec: Resealed bundle digest and immutable research source proof.
+            idempotency_key: Explicit key reused only with the identical request.
+
+        Returns:
+            None on acknowledgement, or an awaitable for an async client.
+
+        The backend requires research-import authority and verifies the child's
+        parent/source lineage. This operation grants no rights, consent, QA
+        approval or publication; those remain separate backend decisions.
+
+        Raises:
+            ValueError: Request identifiers/key or acknowledgement are invalid.
+
+        Example:
+            client.index.contributions.register_research_correction(
+                reference, spec, idempotency_key="repair-registration-1"
+            )
+        """
+
+        def acknowledge(payload: object) -> None:
+            if payload != {}:
+                raise ValueError("Research correction acknowledgement must be empty")
+
+        return self._run(
+            _Call(
+                "index.contributions.research.correction_registration",
+                acknowledge,
+                path_parameters=_revision(reference),
+                json_body=_body(spec),
+                headers=_key(idempotency_key, required="Research correction registration"),
+            )
+        )
+
     def retrieve(self, contribution_id: str) -> Any:
         """Contribution, its current revision and revision history (404 when hidden)."""
         return self._run(
@@ -1544,6 +1595,44 @@ class ContributionsAPI(_Resource):
             )
         )
 
+    def attest_rights(
+        self, reference: ContributionReference, spec: RightsAttestationSpec
+    ) -> RightsAttestationView | Awaitable[RightsAttestationView]:
+        """Record a rights claim for the exact sealed revision.
+
+        Args:
+            reference: Contribution and revision whose immutable bytes are attested.
+            spec: Manifest, descriptor, licenses and notices supporting this claim.
+
+        Returns:
+            The exact stored rights fact, or its awaitable for an async client.
+
+        The backend requires the configured queue owner for Synth-origin work,
+        or a contributing-org owner/admin without QA staff authority for external
+        work. This records neither release consent nor QA/publication approval.
+        Repeating the identical claim is safe; a changed claim conflicts.
+
+        Example:
+            fact = client.index.contributions.attest_rights(reference, spec)
+        """
+        return self._run(
+            _Call(
+                "index.research.rights_attestation.create",
+                _bound(
+                    RightsAttestationView,
+                    lambda view: view.revision_id == reference.revision_id
+                    and view.manifest_digest == spec.manifest_digest
+                    and view.descriptor_digest == spec.descriptor_digest
+                    and view.notices_digest == spec.notices_digest
+                    and view.licenses == spec.licenses
+                    and view.rights_decision_ref == spec.rights_decision_ref,
+                    "Rights response does not bind the requested sealed revision",
+                ),
+                path_parameters=_revision(reference),
+                json_body=_body(spec),
+            )
+        )
+
     def prepare_upload(self, draft: ContributionDraft, spec: ContributionUploadSpec) -> Any:
         """Prepare transfer instructions only; reuse the publication ID for retries."""
         reference = draft.reference

synth_ai-0.22.1.dev668/synth_ai/sdk/index/rights.py

@@ -0,0 +1,65 @@
+"""Exact revision rights claims; the backend alone decides attester authority.
+
+See backend notes/specifications/synth-index/research-rights-attestation.md.
+Rights attestation is separate from consent, QA acceptance and publication.
+"""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Annotated
+from uuid import UUID
+
+from pydantic import Field, StringConstraints, field_validator
+
+from .contracts import IndexContract
+
+Digest = Annotated[str, StringConstraints(pattern=r"^[0-9a-f]{64}$")]
+LicenseExpression = Annotated[str, StringConstraints(min_length=1, max_length=256)]
+DecisionReference = Annotated[str, StringConstraints(min_length=1, max_length=512)]
+
+
+class RightsQueue(StrEnum):
+    """The configured queue for Synth-origin rights claims."""
+
+    INDEX_CORPUS_QA = "index-corpus-qa"
+
+
+class RightsAuthority(StrEnum):
+    """Authority selected by the backend from the sealed contribution origin."""
+
+    QUEUE_RIGHTS_OWNER = "queue_rights_owner"
+    CONTRIBUTING_ORG_ADMIN = "contributing_org_admin"
+
+
+class RightsAttestationSpec(IndexContract):
+    """Exact rights claim for sealed bytes, without granting publication permission."""
+
+    manifest_digest: Digest
+    descriptor_digest: Digest
+    rights_decision_ref: DecisionReference
+    licenses: tuple[LicenseExpression, ...] = Field(min_length=1, max_length=64)
+    notices_digest: Digest
+
+    @field_validator("licenses")
+    @classmethod
+    def _canonical_licenses(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if len(set(value)) != len(value):
+            raise ValueError("licenses must be distinct")
+        return tuple(sorted(value))
+
+
+class RightsAttestationView(IndexContract):
+    """A stored rights fact bound to one exact revision; never a publication decision."""
+
+    schema_version: str = "research-rights-attestation-v1"
+    revision_id: str
+    authority: RightsAuthority
+    queue: RightsQueue | None
+    attester_user_id: UUID
+    attester_org_id: UUID | None
+    manifest_digest: Digest
+    descriptor_digest: Digest
+    rights_decision_ref: DecisionReference
+    licenses: tuple[LicenseExpression, ...]
+    notices_digest: Digest
+    attested_at: datetime

{synth_ai-0.22.0.dev664 → synth_ai-0.22.1.dev668/synth_ai.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.22.0.dev664
+Version: 0.22.1.dev668
 Summary: Python SDK, CLI and MCP servers for Synth Index search and Swarms
 Author-email: Synth AI <josh@usesynth.ai>
 License-Expression: MIT
@@ -30,9 +30,9 @@ Dynamic: license-file
 
 # Synth AI SDK
 
-<!-- CI release pins: PyPI-0.22.0-orange synth-ai==0.22.0 -->
+<!-- CI release pins: PyPI-0.22.1-orange synth-ai==0.22.1 -->
 
-> 0.22.0 is the Index v0.2 release (typed QA/lifecycle APIs, CLI and MCP tools).
+> The 0.22.1 development candidate completes Index v0.2 client coverage for revision rights and research corrections. Stable 0.22.0 remains published.
 
 [![PyPI version](https://img.shields.io/pypi/v/synth-ai.svg)](https://pypi.org/project/synth-ai/)
 [![License](https://img.shields.io/pypi/l/synth-ai.svg)](https://pypi.org/project/synth-ai/)

{synth_ai-0.22.0.dev664 → synth_ai-0.22.1.dev668}/synth_ai.egg-info/SOURCES.txt

@@ -114,6 +114,7 @@ synth_ai/sdk/index/qa_preflight.py
 synth_ai/sdk/index/qa_reviews.py
 synth_ai/sdk/index/research_intake.py
 synth_ai/sdk/index/retry.py
+synth_ai/sdk/index/rights.py
 synth_ai/sdk/index/scope_errors.py
 synth_ai/sdk/index/scopes.py
 synth_ai/sdk/index/search.py