synth-ai 0.22.2.dev689__tar.gz → 0.22.2.dev690__tar.gz

{synth_ai-0.22.2.dev689/synth_ai.egg-info → synth_ai-0.22.2.dev690}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.22.2.dev689
+Version: 0.22.2.dev690
 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.dev689 → synth_ai-0.22.2.dev690}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synth-ai"
-version = "0.22.2.dev689"
+version = "0.22.2.dev690"
 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.dev689 → synth_ai-0.22.2.dev690}/synth_ai/core/http/async_transport.py

@@ -38,12 +38,13 @@ class AsyncHttpTransport:
     """One native async transport for JSON, bytes, and SSE operations."""
 
     base_url: str
-    headers: Mapping[str, str]
+    headers: Mapping[str, str] = field(repr=False)
     timeout_seconds: float = 30.0
     retry_policy: RetryPolicy = field(default_factory=RetryPolicy)
     error_handler: ErrorHandler = raise_http_error
     exception_handler: ExceptionHandler = raise_transport_exception
     decode_error_handler: DecodeErrorHandler = raise_json_decode_error
+    follow_redirects: bool = True
     client: httpx.AsyncClient = field(init=False, repr=False)
 
     def __post_init__(self) -> None:
@@ -52,7 +53,7 @@ class AsyncHttpTransport:
             headers=dict(self.headers),
             timeout=self.timeout_seconds,
             limits=httpx.Limits(max_keepalive_connections=0),
-            follow_redirects=True,
+            follow_redirects=self.follow_redirects,
         )
 
     async def close(self) -> None:

{synth_ai-0.22.2.dev689 → synth_ai-0.22.2.dev690}/synth_ai/core/http/transport.py

@@ -124,7 +124,7 @@ def _declares_runtime_unavailable(decoded: JsonValue | None) -> bool:
         return False
     nested = decoded.get("detail")
     return any(
-        source.get(key) in RUNTIME_UNAVAILABLE_CODES
+        isinstance(source.get(key), str) and source.get(key) in RUNTIME_UNAVAILABLE_CODES
         for source in (nested, decoded)
         if isinstance(source, dict)
         for key in ("error_code", "code", "error")
@@ -425,12 +425,13 @@ class HttpTransport:
     """One strict sync transport for JSON, bytes, and SSE operations."""
 
     base_url: str
-    headers: Mapping[str, str]
+    headers: Mapping[str, str] = field(repr=False)
     timeout_seconds: float = 30.0
     retry_policy: RetryPolicy = field(default_factory=RetryPolicy)
     error_handler: ErrorHandler = raise_http_error
     exception_handler: ExceptionHandler = raise_transport_exception
     decode_error_handler: DecodeErrorHandler = raise_json_decode_error
+    follow_redirects: bool = True
     db_backpressure_policy: DbBackpressureRetryPolicy = field(
         default_factory=DbBackpressureRetryPolicy
     )
@@ -445,7 +446,7 @@ class HttpTransport:
             headers=dict(self.headers),
             timeout=self.timeout_seconds,
             limits=httpx.Limits(max_keepalive_connections=0),
-            follow_redirects=True,
+            follow_redirects=self.follow_redirects,
         )
 
     def close(self) -> None:

{synth_ai-0.22.2.dev689 → synth_ai-0.22.2.dev690}/synth_ai/mcp/research/tools/__init__.py

@@ -7,6 +7,7 @@ from synth_ai.mcp.research.tools.factories import build_factory_tools
 from synth_ai.mcp.research.tools.files import build_file_tools
 from synth_ai.mcp.research.tools.image_releases import build_image_release_tools
 from synth_ai.mcp.research.tools.intern_program import build_intern_program_tools
+from synth_ai.mcp.research.tools.local_files import SelectedFileReader
 from synth_ai.mcp.research.tools.models import build_model_tools
 from synth_ai.mcp.research.tools.outputs import build_output_tools
 from synth_ai.mcp.research.tools.progress import build_progress_tools
@@ -21,6 +22,7 @@ from synth_ai.mcp.research.tools.visuals import build_visual_tools
 from synth_ai.mcp.research.tools.workspace_inputs import build_workspace_input_tools
 
 __all__ = [
+    "SelectedFileReader",
     "build_dataset_tools",
     "build_environment_tools",
     "build_export_tools",

synth_ai-0.22.2.dev690/synth_ai/sdk/research/__init__.py

@@ -0,0 +1,69 @@
+"""Dependency-clean implementation of the public Synth Research SDK."""
+
+from synth_ai.sdk.research.client import AsyncClient, Client
+from synth_ai.sdk.research.contracts.resource_reads import (
+    DataPoolReadReference,
+    DatasetRevisionReadReference,
+    ProjectDataPoolDescriptor,
+    ProjectDataPoolInventory,
+)
+from synth_ai.sdk.research.facade import ResearchClient
+from synth_ai.sdk.research.hierarchy import AsyncHierarchyClient, HierarchyClient
+from synth_ai.sdk.research.hierarchy_models import (
+    EntityKey,
+    HierarchyCommand,
+    HierarchyOriginal,
+    HierarchyRead,
+    HierarchyScope,
+)
+from synth_ai.sdk.research.operations import RESEARCH_OPERATIONS, research_operation
+from synth_ai.sdk.research.owner_reads import (
+    AsyncOwnerReadClient,
+    OwnerReadAccess,
+    OwnerReadAccessExpired,
+    OwnerReadAccessExpiredError,
+    OwnerReadClient,
+    OwnerReadScope,
+)
+from synth_ai.sdk.research.planning_reads import (
+    AsyncPlanningReads,
+    PlanningGraphRead,
+    PlanningReadPosition,
+    PlanningReads,
+    PlanningTaskPage,
+    PlanningTaskRead,
+)
+
+AsyncResearchClient = AsyncClient
+
+__all__ = [
+    "AsyncHierarchyClient",
+    "HierarchyClient",
+    "HierarchyScope",
+    "HierarchyCommand",
+    "HierarchyRead",
+    "HierarchyOriginal",
+    "EntityKey",
+    "AsyncClient",
+    "AsyncResearchClient",
+    "AsyncOwnerReadClient",
+    "AsyncPlanningReads",
+    "Client",
+    "DataPoolReadReference",
+    "DatasetRevisionReadReference",
+    "ProjectDataPoolDescriptor",
+    "ProjectDataPoolInventory",
+    "OwnerReadAccess",
+    "OwnerReadAccessExpired",
+    "OwnerReadAccessExpiredError",
+    "OwnerReadClient",
+    "OwnerReadScope",
+    "PlanningGraphRead",
+    "PlanningReadPosition",
+    "PlanningReads",
+    "PlanningTaskPage",
+    "PlanningTaskRead",
+    "RESEARCH_OPERATIONS",
+    "ResearchClient",
+    "research_operation",
+]

{synth_ai-0.22.2.dev689 → synth_ai-0.22.2.dev690}/synth_ai/sdk/research/advanced_swarms.py

@@ -46,6 +46,16 @@ class _ResearchSession(Protocol):
 
     def run(self, project_id: str, run_id: str) -> _RunHandle: ...
 
+    def get_run_results(self, project_id: str, run_id: str) -> dict[str, Any]: ...
+
+    def get_run_logs(
+        self, project_id: str, run_id: str, *, limit: int | None = None, cursor: str | None = None
+    ) -> dict[str, Any]: ...
+
+    def get_run_execution(self, project_id: str, run_id: str, **kwargs: Any) -> Any: ...
+
+    def get_run_orchestrator(self, project_id: str, run_id: str) -> dict[str, Any]: ...
+
 
 def _session_project(project: ProjectSelector | str | None) -> str | None:
     if isinstance(project, ProjectSelector):
@@ -588,13 +598,16 @@ class ResearchRunsAPI:
         from synth_ai.sdk.pagination import page_from_wire
 
         payload = self.logs(project_id, run_id, limit=limit, cursor=cursor)
+        if isinstance(payload, dict) and "items" not in payload and "data" not in payload:
+            for field_name in ("entries", "logs", "records"):
+                if field_name in payload:
+                    payload = {
+                        "items": payload[field_name],
+                        "next_cursor": payload.get("next_cursor"),
+                        "has_more": payload.get("has_more", False),
+                    }
+                    break
         raw_items, next_cursor, has_more = page_from_wire(payload)
-        if isinstance(payload, dict) and isinstance(payload.get("entries"), list):
-            raw_items = payload["entries"]
-        elif isinstance(payload, dict) and isinstance(payload.get("logs"), list):
-            raw_items = payload["logs"]
-        elif isinstance(payload, dict) and isinstance(payload.get("records"), list):
-            raw_items = payload["records"]
         normalized = [cast(dict[str, Any], item) for item in raw_items if isinstance(item, dict)]
         return SyncPage(items=normalized, next_cursor=next_cursor, has_more=has_more)
 

{synth_ai-0.22.2.dev689 → synth_ai-0.22.2.dev690}/synth_ai/sdk/research/client.py

@@ -11,17 +11,26 @@ from synth_ai.core.utils.urls import BACKEND_URL_BASE, normalize_backend_base
 from synth_ai.sdk.research.container_pools.api import ContainerPoolsAPI
 from synth_ai.sdk.research.environments import AsyncEnvironmentsAPI, EnvironmentsAPI
 from synth_ai.sdk.research.factories import AsyncFactoriesAPI, FactoriesAPI
+from synth_ai.sdk.research.hierarchy import AsyncHierarchyClient, HierarchyClient
+from synth_ai.sdk.research.hierarchy_models import HierarchyPermission, HierarchyScope
 from synth_ai.sdk.research.image_releases import (
     AsyncImageReleasesAPI,
     ImageReleasesAPI,
 )
+from synth_ai.sdk.research.owner_reads import (
+    AsyncOwnerReadClient,
+    Owner,
+    OwnerReadAccess,
+    OwnerReadClient,
+    OwnerReadScope,
+)
 from synth_ai.sdk.research.projects import AsyncProjectsAPI, ProjectsAPI
 from synth_ai.sdk.research.research_intern import (
     AsyncResearchInternAPI,
     ResearchInternAPI,
 )
+from synth_ai.sdk.research.scientific_records import AsyncScientificRecordsAPI, ScientificRecordsAPI
 from synth_ai.sdk.research.swarms import AsyncSwarmsAPI, SwarmsAPI
-from synth_ai.sdk.research.scientific_records import ScientificRecordsAPI, AsyncScientificRecordsAPI
 from synth_ai.sdk.research.traces import AsyncResearchTracesAPI, ResearchTracesAPI
 from synth_ai.sdk.research.visuals import AsyncVisualsAPI, VisualsAPI
 
@@ -103,6 +112,29 @@ class Client:
         """Close the underlying HTTP transport."""
         self._transport.close()
 
+    def hierarchy(
+        self, *, scope: HierarchyScope, permissions: tuple[HierarchyPermission, ...] = ("read",)
+    ) -> HierarchyClient:
+        """Direct project owner API; see testing/specifications/sdk/hierarchy_owner.md."""
+        return HierarchyClient(self._transport, scope=scope, permissions=permissions)
+
+    def owner_reads(self, *, owner: Owner, scope: OwnerReadScope) -> OwnerReadClient:
+        """Issue separate scoped read access; see testing/specifications/sdk/owner_reads.md."""
+        value = self._transport.request_json(
+            "POST",
+            "/auth/capabilities/owner-read",
+            json_body={
+                "owner": owner,
+                "scope": {
+                    "organization_id": scope.organization_id,
+                    "project_id": scope.project_id,
+                    "stream_id": scope.run_id,
+                },
+            },
+        )
+        access = OwnerReadAccess.from_response(value, owner=owner, scope=scope)
+        return OwnerReadClient(owner=owner, base_url=access.origin, access=access)
+
     def __enter__(self) -> Client:
         return self
 
@@ -143,6 +175,29 @@ class AsyncClient:
         """The shared typed async HTTP transport every namespace routes through."""
         return self._transport
 
+    def hierarchy(
+        self, *, scope: HierarchyScope, permissions: tuple[HierarchyPermission, ...] = ("read",)
+    ) -> AsyncHierarchyClient:
+        """Direct async project owner API; see testing/specifications/sdk/hierarchy_owner.md."""
+        return AsyncHierarchyClient(self._transport, scope=scope, permissions=permissions)
+
+    async def owner_reads(self, *, owner: Owner, scope: OwnerReadScope) -> AsyncOwnerReadClient:
+        """Issue separate scoped read access; see testing/specifications/sdk/owner_reads.md."""
+        value = await self._transport.request_json(
+            "POST",
+            "/auth/capabilities/owner-read",
+            json_body={
+                "owner": owner,
+                "scope": {
+                    "organization_id": scope.organization_id,
+                    "project_id": scope.project_id,
+                    "stream_id": scope.run_id,
+                },
+            },
+        )
+        access = OwnerReadAccess.from_response(value, owner=owner, scope=scope)
+        return AsyncOwnerReadClient(owner=owner, base_url=access.origin, access=access)
+
     @property
     def economics(self) -> AsyncEconomicsAPI:
         """Advanced async economics operations, loaded only on access."""

synth_ai-0.22.2.dev690/synth_ai/sdk/research/execution_reads.py

@@ -0,0 +1,260 @@
+"""Direct Orchestra execution snapshots and journal pages.
+
+# See: testing/specifications/sdk/owner_reads.md
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
+
+from synth_ai.core.contracts.json_value import JsonObject, JsonValue
+from synth_ai.sdk.research.contracts._wire import object_value
+
+if TYPE_CHECKING:
+    from synth_ai.sdk.research.owner_reads import (
+        AsyncOwnerReadClient,
+        OwnerReadClient,
+        OwnerReadScope,
+    )
+
+_SCHEMA = "orchestra.owner.run-execution.v1"
+_PORT_SCHEMA = "orchestra.execution-public-view.v1"
+_SCHEMAS = frozenset({_SCHEMA, _PORT_SCHEMA})
+_VIEW = "run_execution"
+_DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z")
+
+
+def _integer(value: JsonValue, *, maximum: int = 2**64 - 1) -> int:
+    if type(value) is not int or not 0 <= value <= maximum:
+        raise ValueError("execution owner position outside wire bounds")
+    return value
+
+
+def _object(value: JsonValue, fields: set[str]) -> JsonObject:
+    result = object_value(value, operation_id="execution owner read")
+    if set(result) != fields:
+        raise ValueError("execution owner response fields drifted")
+    return result
+
+
+def _scope(scope: OwnerReadScope) -> JsonObject:
+    return {
+        "organization_id": scope.organization_id,
+        "project_id": scope.project_id,
+        "stream_id": scope.run_id,
+    }
+
+
+def _schema(value: JsonValue) -> str:
+    if not isinstance(value, str) or value not in _SCHEMAS:
+        raise ValueError("execution owner view schema unsupported")
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionReadCursor:
+    """A position in one Orchestra view, independent of Sublinear publication."""
+
+    scope: OwnerReadScope
+    sequence: int
+    schema: str = _SCHEMA
+
+    def __post_init__(self) -> None:
+        _integer(self.sequence)
+        _schema(self.schema)
+
+    @classmethod
+    def from_wire(cls, value: JsonValue, scope: OwnerReadScope) -> ExecutionReadCursor:
+        body = _object(value, {"scope", "sequence", "view", "schema"})
+        if body["scope"] != _scope(scope) or body["view"] != _VIEW:
+            raise ValueError("execution owner cursor scope or view mismatch")
+        return cls(scope, _integer(body["sequence"]), _schema(body["schema"]))
+
+    def wire(self) -> JsonObject:
+        return {"scope": _scope(self.scope), "sequence": self.sequence, "view": _VIEW, "schema": self.schema}
+
+    def event_id(self) -> str:
+        """Return the exact canonical cursor accepted by the owner HTTP API."""
+        return json.dumps(self.wire(), sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionReadRetention:
+    floor_sequence: int
+    head_sequence: int
+    anchor: JsonObject
+
+    @classmethod
+    def from_wire(cls, value: JsonValue) -> ExecutionReadRetention:
+        body = _object(value, {"floor_sequence", "head_sequence", "anchor"})
+        floor, head = _integer(body["floor_sequence"]), _integer(body["head_sequence"])
+        anchor = _object(body["anchor"], {"owner", "schema", "reference", "sha256"})
+        if floor > head or not all(isinstance(v, str) and v for v in anchor.values()):
+            raise ValueError("execution owner retention invalid")
+        digest = anchor["sha256"]
+        if not isinstance(digest, str) or not _DIGEST.fullmatch(digest):
+            raise ValueError("execution owner retention anchor digest invalid")
+        return cls(floor, head, anchor)
+
+    def contains(self, position: ExecutionReadCursor) -> None:
+        if not self.floor_sequence <= position.sequence <= self.head_sequence:
+            raise ValueError("execution owner cursor outside retained range")
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionReadValue:
+    """Owner public view with its original JSON spelling and verified digest."""
+
+    position: ExecutionReadCursor
+    raw_json: str
+    sha256: str
+    value: JsonObject
+
+    @classmethod
+    def from_wire(
+        cls, payload: JsonValue, position: ExecutionReadCursor, *, kind: str
+    ) -> ExecutionReadValue:
+        body = _object(payload, {"kind", "schema", "canonical_json", "sha256"})
+        raw = body["canonical_json"]
+        if body["kind"] != "inline" or body["schema"] != position.schema or not isinstance(raw, str):
+            raise ValueError("execution owner public view payload invalid")
+        encoded = raw.encode("utf-8")
+        digest = "sha256:" + hashlib.sha256(encoded).hexdigest()
+        if len(encoded) > 131072 or body["sha256"] != digest:
+            raise ValueError("execution owner public view digest mismatch")
+        value = object_value(cast(JsonValue, json.loads(raw)), operation_id="execution public view")
+        if position.schema == _PORT_SCHEMA:
+            fields = {"schema_version", "kind", "sequence", "generation"}
+            fields |= {"scope", "execution"} if kind == "snapshot" else {"input_sha256", "input_bytes"}
+            value = _object(value, fields)
+            _integer(value.get("generation"))
+            if kind == "position":
+                original_digest = value.get("input_sha256")
+                if (
+                    not isinstance(original_digest, str)
+                    or not _DIGEST.fullmatch(original_digest)
+                    or _integer(value.get("input_bytes")) == 0
+                ):
+                    raise ValueError("execution owner position original invalid")
+            else:
+                object_value(value.get("execution"), operation_id="execution public view state")
+        if (
+            value.get("schema_version") != position.schema
+            or value.get("kind") != kind
+            or (
+                value.get("scope") != _scope(position.scope)
+                and not (
+                    position.schema == _PORT_SCHEMA
+                    and kind == "position"
+                    and "scope" not in value
+                )
+            )
+            or _integer(value.get("sequence")) != position.sequence
+        ):
+            raise ValueError("execution owner public view binding mismatch")
+        return cls(position, raw, digest, value)
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionSnapshot:
+    snapshot: ExecutionReadValue
+    retention: ExecutionReadRetention
+
+    @classmethod
+    def from_wire(cls, value: JsonValue, scope: OwnerReadScope) -> ExecutionSnapshot:
+        body = _object(value, {"scope", "cursor", "snapshot", "retention"})
+        if body["scope"] != _scope(scope):
+            raise ValueError("execution owner snapshot scope mismatch")
+        position = ExecutionReadCursor.from_wire(body["cursor"], scope)
+        retention = ExecutionReadRetention.from_wire(body["retention"])
+        retention.contains(position)
+        return cls(ExecutionReadValue.from_wire(body["snapshot"], position, kind="snapshot"), retention)
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionEventPage:
+    events: tuple[ExecutionReadValue, ...]
+    next: ExecutionReadCursor
+    retention: ExecutionReadRetention
+
+    @classmethod
+    def from_wire(
+        cls, value: JsonValue, after: ExecutionReadCursor, limit: int
+    ) -> ExecutionEventPage:
+        body = _object(value, {"scope", "items", "next", "retention"})
+        if body["scope"] != _scope(after.scope):
+            raise ValueError("execution owner page scope mismatch")
+        rows = body["items"]
+        if not isinstance(rows, list) or len(rows) > limit:
+            raise ValueError("execution owner page exceeds requested bound")
+        retention = ExecutionReadRetention.from_wire(body["retention"])
+        retention.contains(after)
+        next_cursor = ExecutionReadCursor.from_wire(body["next"], after.scope)
+        if next_cursor.schema != after.schema:
+            raise ValueError("execution owner page changed view schema")
+        retention.contains(next_cursor)
+        events: list[ExecutionReadValue] = []
+        previous = after.sequence
+        for row in rows:
+            item = _object(row, {"cursor", "body"})
+            position = ExecutionReadCursor.from_wire(item["cursor"], after.scope)
+            if position.schema != after.schema:
+                raise ValueError("execution owner event changed view schema")
+            retention.contains(position)
+            if position.sequence <= previous:
+                raise ValueError("execution owner page did not advance")
+            events.append(ExecutionReadValue.from_wire(item["body"], position, kind="position"))
+            previous = position.sequence
+        if next_cursor.sequence != previous:
+            raise ValueError("execution owner continuation differs from last item")
+        return cls(tuple(events), next_cursor, retention)
+
+
+def _query(after: ExecutionReadCursor, scope: OwnerReadScope, limit: int) -> JsonObject:
+    if after.scope != scope:
+        raise ValueError("execution owner cursor differs from reader scope")
+    if _integer(limit, maximum=256) == 0:
+        raise ValueError("execution owner page limit must be positive")
+    return {"after": after.event_id(), "limit": limit}
+
+
+class ExecutionReads:
+    """Owner execution views; see testing/specifications/sdk/owner_reads.md."""
+
+    def __init__(self, reader: OwnerReadClient) -> None:
+        if reader.access.owner != "orchestra":
+            raise ValueError("execution reads require Orchestra owner access")
+        self._reader = reader
+
+    def snapshot(self) -> ExecutionSnapshot:
+        return ExecutionSnapshot.from_wire(
+            self._reader.read_json("/snapshot", query={"view": _VIEW}), self._reader.access.scope
+        )
+
+    def events(self, after: ExecutionReadCursor, *, limit: int = 128) -> ExecutionEventPage:
+        query = _query(after, self._reader.access.scope, limit)
+        return ExecutionEventPage.from_wire(self._reader.read_json("/events", query=query), after, limit)
+
+
+class AsyncExecutionReads:
+    """Native async owner views; see testing/specifications/sdk/owner_reads.md."""
+
+    def __init__(self, reader: AsyncOwnerReadClient) -> None:
+        if reader.access.owner != "orchestra":
+            raise ValueError("execution reads require Orchestra owner access")
+        self._reader = reader
+
+    async def snapshot(self) -> ExecutionSnapshot:
+        return ExecutionSnapshot.from_wire(
+            await self._reader.read_json("/snapshot", query={"view": _VIEW}), self._reader.access.scope
+        )
+
+    async def events(self, after: ExecutionReadCursor, *, limit: int = 128) -> ExecutionEventPage:
+        query = _query(after, self._reader.access.scope, limit)
+        return ExecutionEventPage.from_wire(
+            await self._reader.read_json("/events", query=query), after, limit
+        )

{synth_ai-0.22.2.dev689 → synth_ai-0.22.2.dev690}/synth_ai/sdk/research/facade.py

@@ -11,8 +11,11 @@ from synth_ai.sdk.research.container_pools.api import ContainerPoolsAPI
 from synth_ai.sdk.research.environments import EnvironmentsAPI
 from synth_ai.sdk.research.experiments import ResearchExperimentsAPI
 from synth_ai.sdk.research.factories import FactoriesAPI
+from synth_ai.sdk.research.hierarchy import HierarchyClient
+from synth_ai.sdk.research.hierarchy_models import HierarchyPermission, HierarchyScope
 from synth_ai.sdk.research.image_releases import ImageReleasesAPI
 from synth_ai.sdk.research.knowledge import ResearchKnowledgeAPI
+from synth_ai.sdk.research.owner_reads import Owner, OwnerReadClient, OwnerReadScope
 from synth_ai.sdk.research.projects import ResearchProjectsAPI
 from synth_ai.sdk.research.research_intern import ResearchInternAPI
 from synth_ai.sdk.research.scientific_records import ScientificRecordsAPI
@@ -145,6 +148,16 @@ class Client:
             )
         return self._session
 
+    def hierarchy(
+        self, *, scope: HierarchyScope, permissions: tuple[HierarchyPermission, ...] = ("read",)
+    ) -> HierarchyClient:
+        """Direct project owner API; see testing/specifications/sdk/hierarchy_owner.md."""
+        return self._core.hierarchy(scope=scope, permissions=permissions)
+
+    def owner_reads(self, *, owner: Owner, scope: OwnerReadScope) -> OwnerReadClient:
+        """Open scoped owner reads; see testing/specifications/sdk/owner_reads.md."""
+        return self._core.owner_reads(owner=owner, scope=scope)
+
     @property
     def advanced(self) -> ResearchAdvancedAPI:
         """Explicitly unstable operator capabilities outside the hero workflow."""