synth-ai 0.16.1.dev0__tar.gz → 0.16.1.dev1__tar.gz

{synth_ai-0.16.1.dev0/synth_ai.egg-info → synth_ai-0.16.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.16.1.dev0
+Version: 0.16.1.dev1
 Summary: Python-only SDK for Synth containers, tunnels, pools, and Research
 Author-email: Synth AI <josh@usesynth.ai>
 License-Expression: MIT
@@ -86,93 +86,97 @@ The CLI also reads `SYNTH_BACKEND_URL` and accepts `--backend-url`.
 
 ```python
 from synth_ai import SynthClient
+from synth_ai.core.research.public import SwarmSpec
 
-client = SynthClient()
-
-print(client.research.limits.get_typed().plan)
+with SynthClient() as client:
+    swarm = client.research.swarms.create(
+        SwarmSpec(objective="Assess this repository and produce a concise report.")
+    )
+    for event in swarm.events():
+        print(event.kind, event.telemetry.sequence)
+    result = swarm.wait(timeout_seconds=900)
+    print(result.swarm_id, result.state)
+    resolved = swarm.configuration()
+    print(resolved.config_version_id, resolved.snapshot_sha256)
+    usage = swarm.usage()
+    print(usage.money.nominal_pico_usd, usage.tokens.totals.input_tokens)
+    evidence = swarm.evidence()
+    print(evidence.artifacts, evidence.work_products)
 ```
 
-## Managed Research (hero SDK)
+`create` returns a durable handle immediately. `events()` yields typed events,
+including an explicit `UnknownSwarmEvent` for forward-compatible server events;
+`wait()` uses a monotonic deadline and returns the terminal typed `Swarm`.
+`configuration()` returns the immutable, versioned, secret-redacted launch
+snapshot bound to that swarm, so replay and audit do not depend on the
+project's current mutable configuration.
+`usage()` returns one typed cost, token, and actor-attribution projection plus
+its source, record count, observation time, and terminal-state freshness. It
+does not expose the legacy raw ledger-entry dictionaries.
+`evidence()` returns the complete durable artifact and WorkProduct index with
+strict counts and lifecycle freshness. Artifact and WorkProduct content reads
+use the same typed transport and return bytes; they do not expose storage
+authority.
 
-Install the research extra when you need hosted runs, projects, Factory Tag, or MCP:
+## Research SDK
 
-```bash
-uv add "synth-ai[research]"
-```
+The only customer entrypoint is `SynthClient().research`. Its stable namespaces
+are `projects`, `swarms`, and `factories`.
 
-Hero entrypoint — **`SynthClient().research`** only (no standalone control client in new code):
+Create a durable project when work needs reusable configuration:
 
 ```python
-import os
-
 from synth_ai import SynthClient
-from synth_ai.research import ResearchTagSessionCreateRequest, ResearchWorkMode
-
-client = SynthClient()
-research = client.research
-factory_id = os.environ["SYNTH_FACTORY_ID"]
-effort_id = os.environ["SYNTH_FACTORY_EFFORT_ID"]
-project_id = os.environ["SYNTH_RESEARCH_PROJECT_ID"]  # An existing, prepared project.
-
-# Org limits
-limits = research.limits.get_typed()
-print(limits.plan)
-
-# Authoritative economics reads; the client does not recompute allowances or discounts.
-plan = research.economics.plan()
-catalog = research.economics.catalog()
-entitlements = research.economics.entitlements()
-
-# Async Research Factory: inspect the experiment floor before launching work
-factory = research.factories.get(factory_id)
-floor = research.factories.status(factory.factory_id)
-preview = research.factories.preview_wake(factory.factory_id)
-# After reviewing preview.efforts, the SDK replays the resolved request_contract
-# with its opaque preview_token; callers do not reconstruct the write request.
-if preview.confirmation_required:
-    receipt = research.factories.wake_due(
-        factory.factory_id,
-        preview=preview,
+from synth_ai.core.research.public import EnvironmentKind, ProjectSpec, RuntimeKind, SwarmSpec
+
+with SynthClient() as client:
+    project = client.research.projects.create(
+        ProjectSpec(
+            name="Repository assessment",
+            pool_id="pool_default",
+            runtime_kind=RuntimeKind("python"),
+            environment_kind=EnvironmentKind("docker"),
+            orchestrator_profile_id="profile_orchestrator",
+            default_worker_profile_id="profile_worker",
+        )
+    )
+    swarm = client.research.swarms.create(
+        SwarmSpec(objective="Produce the assessment."),
+        project_id=project.project_id,
     )
+    print(swarm.wait().state)
+```
 
-# Factory Tag loop
-session = research.factories.tag.sessions.create(
-    ResearchTagSessionCreateRequest(
-        request="Improve rollout throughput",
-        factory_id=factory_id,
-        effort_id=effort_id,
+Factories provide a typed durable optimization loop with native sync/async
+parity:
+
+```python
+from synth_ai import SynthClient
+from synth_ai.core.research.public import EffortSpec, FactorySpec, ProjectId
+
+with SynthClient() as client:
+    factory = client.research.factories.create(
+        FactorySpec(name="Prompt optimizer")
+    )
+    effort = client.research.factories.efforts.create(
+        EffortSpec(
+            factory_id=factory.factory_id,
+            project_id=ProjectId("project_existing"),
+            name="Improve the system prompt",
+        )
     )
-)
-research.factories.tag.sessions.messages.send(session.session_id, "Status update")
-scope = research.factories.tag.scopes.get_default()
-
-# Launch against the explicitly selected pre-existing project.
-work_mode = ResearchWorkMode.DIRECTED_EFFORT
-preflight = research.runs.check_preflight(project_id, work_mode=work_mode)
-session = research.runs.create(
-    project_id,
-    objective="Produce a bounded repository assessment and a readable report.",
-    work_mode=work_mode,
-)
-
-# Run readouts (nested namespaces — never ``manderqueue`` on hero)
-session.snapshots.get(detail="control")
-progress = session.progress.get_typed()
-usage = session.usage.get()
-work_products = session.work_products.list()
-artifacts = session.artifacts.list()
-if work_products:
-    report = session.work_products.content.get(work_products[0].work_product_id)
-session.message_queue.messages.list()
-research.projects.objectives.list(project_id, run_id=session.run_id)
+    print(effort.effort_id, effort.state)
 ```
 
-CLI smoke:
+Limits, economics, secrets, Tag, rich evidence projections, and administrative
+resource APIs remain available under `client.research.advanced` while their
+contracts are stabilized. Advanced APIs are not covered by the stable surface
+guarantee.
+
+CLI discovery:
 
 ```bash
-synth-ai research limits get
-synth-ai research tag smoke
-synth-ai research smoke
+synth-ai research --help
 ```
 
 ## CLI
@@ -190,7 +194,7 @@ Use `SynthClient` as the front door:
 
 | Surface | Client namespace | Use it for |
 | --- | --- | --- |
-| **Managed Research / Factory** | `client.research` | Hosted research runs, projects, Factory Tag, limits, MCP (`synth-ai[research]`). |
+| **Research / Factory** | `client.research` | Typed hosted projects, swarms, Factory lifecycles, and Efforts. |
 | Containers | `client.containers` | Hosted container records and lifecycle operations. |
 | Tunnels | `client.tunnels` | Managed tunnel records, leases, health, and rotation. |
 | Pools | `client.pools` | Container pools, tasks, rollouts, artifacts, usage, and events. |
@@ -212,10 +216,8 @@ override grants are manual audit events rather than automatic resets.
 The canonical backend surfaces are `GET /smr/billing/catalog`,
 `GET /smr/billing/plan`, `GET /smr/billing/runs/{run_id}/drawdown`, and
 `GET /smr/billing/factory-efforts/{factory_effort_id}/drawdown`. In the Python
-SDK, use `client.research.economics.entitlements()` for the organization snapshot
-and `client.research.economics.plan()`, `.catalog()`, `.run_drawdown(run_id)`, or
-`.factory_effort_drawdown(factory_effort_id)` for canonical billing reads. Use
-`.project(project_id)` for project usage, budgets, and entitlements. Do not infer
+SDK, use `client.research.advanced.economics` for authoritative billing reads
+while the economics contract remains advanced. Do not infer
 allowance from legacy Autumn balances or local spend summaries, and do not
 recompute discounts in the client.
 

{synth_ai-0.16.1.dev0 → synth_ai-0.16.1.dev1}/README.md

@@ -50,93 +50,97 @@ The CLI also reads `SYNTH_BACKEND_URL` and accepts `--backend-url`.
 
 ```python
 from synth_ai import SynthClient
+from synth_ai.core.research.public import SwarmSpec
 
-client = SynthClient()
-
-print(client.research.limits.get_typed().plan)
+with SynthClient() as client:
+    swarm = client.research.swarms.create(
+        SwarmSpec(objective="Assess this repository and produce a concise report.")
+    )
+    for event in swarm.events():
+        print(event.kind, event.telemetry.sequence)
+    result = swarm.wait(timeout_seconds=900)
+    print(result.swarm_id, result.state)
+    resolved = swarm.configuration()
+    print(resolved.config_version_id, resolved.snapshot_sha256)
+    usage = swarm.usage()
+    print(usage.money.nominal_pico_usd, usage.tokens.totals.input_tokens)
+    evidence = swarm.evidence()
+    print(evidence.artifacts, evidence.work_products)
 ```
 
-## Managed Research (hero SDK)
+`create` returns a durable handle immediately. `events()` yields typed events,
+including an explicit `UnknownSwarmEvent` for forward-compatible server events;
+`wait()` uses a monotonic deadline and returns the terminal typed `Swarm`.
+`configuration()` returns the immutable, versioned, secret-redacted launch
+snapshot bound to that swarm, so replay and audit do not depend on the
+project's current mutable configuration.
+`usage()` returns one typed cost, token, and actor-attribution projection plus
+its source, record count, observation time, and terminal-state freshness. It
+does not expose the legacy raw ledger-entry dictionaries.
+`evidence()` returns the complete durable artifact and WorkProduct index with
+strict counts and lifecycle freshness. Artifact and WorkProduct content reads
+use the same typed transport and return bytes; they do not expose storage
+authority.
 
-Install the research extra when you need hosted runs, projects, Factory Tag, or MCP:
+## Research SDK
 
-```bash
-uv add "synth-ai[research]"
-```
+The only customer entrypoint is `SynthClient().research`. Its stable namespaces
+are `projects`, `swarms`, and `factories`.
 
-Hero entrypoint — **`SynthClient().research`** only (no standalone control client in new code):
+Create a durable project when work needs reusable configuration:
 
 ```python
-import os
-
 from synth_ai import SynthClient
-from synth_ai.research import ResearchTagSessionCreateRequest, ResearchWorkMode
-
-client = SynthClient()
-research = client.research
-factory_id = os.environ["SYNTH_FACTORY_ID"]
-effort_id = os.environ["SYNTH_FACTORY_EFFORT_ID"]
-project_id = os.environ["SYNTH_RESEARCH_PROJECT_ID"]  # An existing, prepared project.
-
-# Org limits
-limits = research.limits.get_typed()
-print(limits.plan)
-
-# Authoritative economics reads; the client does not recompute allowances or discounts.
-plan = research.economics.plan()
-catalog = research.economics.catalog()
-entitlements = research.economics.entitlements()
-
-# Async Research Factory: inspect the experiment floor before launching work
-factory = research.factories.get(factory_id)
-floor = research.factories.status(factory.factory_id)
-preview = research.factories.preview_wake(factory.factory_id)
-# After reviewing preview.efforts, the SDK replays the resolved request_contract
-# with its opaque preview_token; callers do not reconstruct the write request.
-if preview.confirmation_required:
-    receipt = research.factories.wake_due(
-        factory.factory_id,
-        preview=preview,
+from synth_ai.core.research.public import EnvironmentKind, ProjectSpec, RuntimeKind, SwarmSpec
+
+with SynthClient() as client:
+    project = client.research.projects.create(
+        ProjectSpec(
+            name="Repository assessment",
+            pool_id="pool_default",
+            runtime_kind=RuntimeKind("python"),
+            environment_kind=EnvironmentKind("docker"),
+            orchestrator_profile_id="profile_orchestrator",
+            default_worker_profile_id="profile_worker",
+        )
+    )
+    swarm = client.research.swarms.create(
+        SwarmSpec(objective="Produce the assessment."),
+        project_id=project.project_id,
     )
+    print(swarm.wait().state)
+```
 
-# Factory Tag loop
-session = research.factories.tag.sessions.create(
-    ResearchTagSessionCreateRequest(
-        request="Improve rollout throughput",
-        factory_id=factory_id,
-        effort_id=effort_id,
+Factories provide a typed durable optimization loop with native sync/async
+parity:
+
+```python
+from synth_ai import SynthClient
+from synth_ai.core.research.public import EffortSpec, FactorySpec, ProjectId
+
+with SynthClient() as client:
+    factory = client.research.factories.create(
+        FactorySpec(name="Prompt optimizer")
+    )
+    effort = client.research.factories.efforts.create(
+        EffortSpec(
+            factory_id=factory.factory_id,
+            project_id=ProjectId("project_existing"),
+            name="Improve the system prompt",
+        )
     )
-)
-research.factories.tag.sessions.messages.send(session.session_id, "Status update")
-scope = research.factories.tag.scopes.get_default()
-
-# Launch against the explicitly selected pre-existing project.
-work_mode = ResearchWorkMode.DIRECTED_EFFORT
-preflight = research.runs.check_preflight(project_id, work_mode=work_mode)
-session = research.runs.create(
-    project_id,
-    objective="Produce a bounded repository assessment and a readable report.",
-    work_mode=work_mode,
-)
-
-# Run readouts (nested namespaces — never ``manderqueue`` on hero)
-session.snapshots.get(detail="control")
-progress = session.progress.get_typed()
-usage = session.usage.get()
-work_products = session.work_products.list()
-artifacts = session.artifacts.list()
-if work_products:
-    report = session.work_products.content.get(work_products[0].work_product_id)
-session.message_queue.messages.list()
-research.projects.objectives.list(project_id, run_id=session.run_id)
+    print(effort.effort_id, effort.state)
 ```
 
-CLI smoke:
+Limits, economics, secrets, Tag, rich evidence projections, and administrative
+resource APIs remain available under `client.research.advanced` while their
+contracts are stabilized. Advanced APIs are not covered by the stable surface
+guarantee.
+
+CLI discovery:
 
 ```bash
-synth-ai research limits get
-synth-ai research tag smoke
-synth-ai research smoke
+synth-ai research --help
 ```
 
 ## CLI
@@ -154,7 +158,7 @@ Use `SynthClient` as the front door:
 
 | Surface | Client namespace | Use it for |
 | --- | --- | --- |
-| **Managed Research / Factory** | `client.research` | Hosted research runs, projects, Factory Tag, limits, MCP (`synth-ai[research]`). |
+| **Research / Factory** | `client.research` | Typed hosted projects, swarms, Factory lifecycles, and Efforts. |
 | Containers | `client.containers` | Hosted container records and lifecycle operations. |
 | Tunnels | `client.tunnels` | Managed tunnel records, leases, health, and rotation. |
 | Pools | `client.pools` | Container pools, tasks, rollouts, artifacts, usage, and events. |
@@ -176,10 +180,8 @@ override grants are manual audit events rather than automatic resets.
 The canonical backend surfaces are `GET /smr/billing/catalog`,
 `GET /smr/billing/plan`, `GET /smr/billing/runs/{run_id}/drawdown`, and
 `GET /smr/billing/factory-efforts/{factory_effort_id}/drawdown`. In the Python
-SDK, use `client.research.economics.entitlements()` for the organization snapshot
-and `client.research.economics.plan()`, `.catalog()`, `.run_drawdown(run_id)`, or
-`.factory_effort_drawdown(factory_effort_id)` for canonical billing reads. Use
-`.project(project_id)` for project usage, budgets, and entitlements. Do not infer
+SDK, use `client.research.advanced.economics` for authoritative billing reads
+while the economics contract remains advanced. Do not infer
 allowance from legacy Autumn balances or local spend summaries, and do not
 recompute discounts in the client.
 

{synth_ai-0.16.1.dev0 → synth_ai-0.16.1.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synth-ai"
-version = "0.16.1.dev0"
+version = "0.16.1.dev1"
 description = "Python-only SDK for Synth containers, tunnels, pools, and Research"
 authors = [{name = "Synth AI", email = "josh@usesynth.ai"}]
 license = "MIT"
@@ -17,9 +17,8 @@ dependencies = [
 
 [project.scripts]
 synth-ai = "synth_ai.cli:cli"
-synth-ai-managed-research-mcp = "synth_ai.managed_research.mcp.server:main"
-synth-ai-mcp-managed-research = "synth_ai.managed_research.mcp.server:main"
-synth-ai-research-factory-standup = "synth_ai.managed_research.factory_standup:main"
+synth-ai-research-mcp = "synth_ai.mcp.research.server:main"
+synth-ai-research-factory-standup = "synth_ai.cli.research_factory_standup:main"
 
 [project.optional-dependencies]
 schemas = []
@@ -83,10 +82,8 @@ include-package-data = true
 [tool.setuptools.package-data]
 "synth_ai" = [
     "py.typed",
-    "opencode/skill/*/SKILL.md",
-    "managed_research/py.typed",
-    "managed_research/factory_plans/*.json",
-    "managed_research/schemas/*",
+    "core/research/factory_plans/*.json",
+    "core/research/schemas/*",
 ]
 
 [tool.ruff]
@@ -132,8 +129,7 @@ include = ["synth_ai"]
 
 [[tool.ty.overrides]]
 include = [
-    "synth_ai/research/**",
-    "synth_ai/managed_research/sdk/tag.py",
+    "synth_ai/core/research/_legacy/sdk/tag.py",
 ]
 rules = { unresolved-import = "warn" }
 

{synth_ai-0.16.1.dev0 → synth_ai-0.16.1.dev1}/synth_ai/__init__.py

@@ -21,7 +21,7 @@ except PackageNotFoundError:
     try:
         import tomllib as _toml
     except ModuleNotFoundError:  # pragma: no cover
-        import tomli as _toml  # type: ignore[no-redef]
+        import tomli as _toml  # type: ignore[no-redef]  # ty: ignore[unresolved-import]
 
     try:
         pyproject_path = Path(__file__).resolve().parents[1] / "pyproject.toml"
@@ -44,17 +44,17 @@ __all__ = [
     "ContainerPoolsClient",
     "ContainersClient",
     "HorizonsPrivateClient",
-    "ManagedResearchClient",
-    "ManagedResearchError",
-    "ManagedResearchMcpServer",
+    "ResearchApiError",
     "ManagedAgentsAnthropicClient",
     "ManagedAgentRun",
     "OpenAIAgentsSdkClient",
     "ResearchClient",
     "ResearchConcurrentRunLimitExceededError",
-    "ResearchApiError",
     "ResearchInsufficientCreditsError",
     "ResearchLimitExceededError",
+    "ResearchProjectCreateRequest",
+    "ResearchSwarmLaunchRequest",
+    "ResearchSwarmState",
     "SynthClient",
     "SynthManagedAgents",
     "TunnelsClient",
@@ -63,37 +63,39 @@ __all__ = [
 ]
 
 _EXPORTS: dict[str, tuple[str, str]] = {
-    "ManagedResearchClient": (
-        "synth_ai.managed_research.sdk.client",
-        "ManagedResearchClient",
-    ),
-    "SmrControlClient": ("synth_ai.managed_research.sdk.client", "SmrControlClient"),
-    "ManagedResearchMcpServer": (
-        "synth_ai.managed_research.mcp.server",
-        "ManagedResearchMcpServer",
-    ),
-    "ManagedResearchError": ("synth_ai.managed_research.errors", "ManagedResearchError"),
-    "ResearchApiError": ("synth_ai.research.errors", "ResearchApiError"),
+    "ResearchApiError": ("synth_ai.core.research.errors", "ResearchApiError"),
     "ResearchConcurrentRunLimitExceededError": (
-        "synth_ai.research.errors",
+        "synth_ai.core.research.errors",
         "ResearchConcurrentRunLimitExceededError",
     ),
     "ResearchInsufficientCreditsError": (
-        "synth_ai.research.errors",
+        "synth_ai.core.research.errors",
         "ResearchInsufficientCreditsError",
     ),
-    "ResearchLimitExceededError": ("synth_ai.research.errors", "ResearchLimitExceededError"),
-    "SmrApiError": ("synth_ai.research.errors", "ResearchApiError"),
+    "ResearchLimitExceededError": ("synth_ai.core.research.errors", "ResearchLimitExceededError"),
+    "SmrApiError": ("synth_ai.core.research.errors", "ResearchApiError"),
     "SmrConcurrentRunLimitExceededError": (
-        "synth_ai.research.errors",
+        "synth_ai.core.research.errors",
         "ResearchConcurrentRunLimitExceededError",
     ),
     "SmrInsufficientCreditsError": (
-        "synth_ai.research.errors",
+        "synth_ai.core.research.errors",
         "ResearchInsufficientCreditsError",
     ),
-    "SmrLimitExceededError": ("synth_ai.research.errors", "ResearchLimitExceededError"),
-    "ResearchClient": ("synth_ai.research.client", "ResearchClient"),
+    "SmrLimitExceededError": ("synth_ai.core.research.errors", "ResearchLimitExceededError"),
+    "ResearchClient": ("synth_ai.core.research.facade", "ResearchClient"),
+    "ResearchProjectCreateRequest": (
+        "synth_ai.core.research.contracts",
+        "ResearchProjectCreateRequest",
+    ),
+    "ResearchSwarmLaunchRequest": (
+        "synth_ai.core.research.contracts",
+        "ResearchSwarmLaunchRequest",
+    ),
+    "ResearchSwarmState": (
+        "synth_ai.core.research.contracts",
+        "ResearchSwarmState",
+    ),
     "SynthClient": ("synth_ai.client", "SynthClient"),
     "AsyncSynthClient": ("synth_ai.client", "AsyncSynthClient"),
     "ContainersClient": ("synth_ai.sdk.containers", "ContainersClient"),

{synth_ai-0.16.1.dev0 → synth_ai-0.16.1.dev1}/synth_ai/cli/dev_envs.py

@@ -387,9 +387,9 @@ def _dev_environment_run_options(fn):
 
 
 def _client(api_key: str | None, backend_url: str | None):
-    from synth_ai.managed_research import ManagedResearchClient
+    from synth_ai.core.research.session.client import ResearchSession
 
-    return ManagedResearchClient(
+    return ResearchSession(
         api_key=_resolve_api_key(api_key),
         backend_base=_resolve_backend_url(backend_url),
     )