> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usesynth.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK & CLI Changelog

> Technical release notes for synth-ai, synth-optimizers, MCP tools, and hosted optimizer APIs.

Technical release notes for developers: package versions, API and CLI changes,
MCP tool updates, and migration snippets.

<Note>
  **Product launches** (promos, new surfaces, plan changes) live on the
  [product changelog](https://www.usesynth.ai/changelog). This page is for
  SDK, CLI, and API detail only.
</Note>

## Packages covered

| Package            | Local detail               | Notes                                                                                                                  |
| ------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `synth-optimizers` | `optimizers/changelog.log` | Summarize here at PyPI publish                                                                                         |
| `synth-ai`         | this page                  | Canonical Python platform SDK; Research SDK, models, and MCP ship here and are public through `SynthClient().research` |
| `managed-research` | this page                  | Deprecated compatibility shim only; new installs use `synth-ai[research]`                                              |

## Entries

Add new sections with Mintlify `<Update>` blocks (newest first). Include:
version, breaking vs additive, copy-paste migration when imports or CLI flags
change, and links to updated quickstart pages.

<Update label="2026-07-21" tags={["synth-ai", "0.16.0", "managed-swarms", "research-factory"]}>
  **synth-ai `0.16.0`** — Managed Swarms and the complete Research launch facade.

  * `client.research.swarms` is the canonical public surface for bounded multi-agent executions; `research.runs` remains a deprecated one-release compatibility alias.
  * Adds typed Swarm launch/wait/retry, Factory lifecycle/usage/events, account and API-key lifecycle, experiments, knowledge, wiki, project notes, and Git-server reads.
  * Provider keys are sealed before transport, real billing-denial codes map to `ResearchInsufficientCreditsError`, and the vendored backend OpenAPI is refreshed.

  ```bash theme={null}
  pip install "synth-ai[research]==0.16.0"
  ```
</Update>

<Update label="2026-07-17" tags={["synth-ai", "0.15.2", "research-factory", "schema-parity"]}>
  **synth-ai `0.15.2`** — Research Factory runtime-authority schema parity.

  * **Fixed:** the packaged SMR OpenAPI and public-model snapshots now include
    `runtime_authority_source_version`, matching the backend-owned authority
    readout contract.
  * **Unchanged:** the public Research Factory preview/confirm API introduced in
    0.15.1 remains additive and source-compatible.
  * **Source:** release head
    [`5eb40685`](https://github.com/synth-laboratories/synth-ai/commit/5eb40685b508097eb0f9427d6da0353be646a5e5).

  ```bash theme={null}
  pip install "synth-ai[research]==0.15.2"
  ```

  See [Research Factory Quickstart](/managed-research/factory-quickstart).
</Update>

<Update label="2026-07-17" tags={["synth-ai", "0.15.1", "research-factory", "preview-confirm"]}>
  **synth-ai `0.15.1`** — Confirmed Research Factory wakes and public launch
  authority.

  * **Added:** `SynthClient().research.factories.list`, `get`, `status`, `preview_wake`, and `wake_due`. Confirmation replays the backend-authored request contract and opaque preview token.
  * **Added:** public Research launch-authority models, typed Factory Tag context, and runnable-project `runtime_artifact_release_id` preservation.
  * **Changed:** Factory wake preview is WRITE-scoped because the backend dry-run route may persist scheduler and admission metadata.
  * **Changed:** product CloudDeployments require an explicit provider-neutral `host_kind`; internal CloudDevSlot identities remain in `synth-dev`.
  * **Added:** fail-closed promotion-discount preview read models with `enforcement_status="not_implemented"`; no activation or debit path is added.
  * **Source:** release head [`7c40a4ca`](https://github.com/synth-laboratories/synth-ai/commit/7c40a4cac0d769071cc2e039d73ddfa3fcb3e719).

  ```bash theme={null}
  pip install "synth-ai[research]==0.15.1"
  ```

  See [Research Factory Quickstart](/managed-research/factory-quickstart).
</Update>

<Update label="2026-07-13" tags={["synth-ai", "0.15.0", "research-factory", "cloud-deployments"]}>
  **synth-ai `0.15.0`** — Research Factory evidence, typed maintenance runs,
  project-bound CloudDeployments, hosted artifacts, and run-to-Effort graduation.

  * **Added:** typed Factory proof readiness, accepted actor outputs, experiment history/comparison, and candidate/Tag evidence.
  * **Added:** `EffortsAPI.launch_maintenance(...)`, research vs maintenance run kinds, and the orchestrator maintenance role.
  * **Added:** project-bound CloudDeployments with matching MCP tools and exact-name confirmation for VM deletion.
  * **Added:** `SynthClient().research.hosted_artifacts`, run-handle hosted-artifact readouts, and `SynthClient().research.efforts` graduation helpers.
  * **Additive release:** existing one-off Managed Research run code remains valid.
  * **Known boundaries:** 24/7 reliability and Factory-to-PR code delivery are not part of this release.
  * **Acceptance:** FactoryBench passed 12/12 lifecycle gates with reward `1.0`; the immutable winner scored held-out mean reward `1.16` and benchmark score `0.0303`.

  ```bash theme={null}
  pip install "synth-ai[research]==0.15.0"
  ```

  See [Research Factory Quickstart](/managed-research/factory-quickstart).
</Update>

<Update label="2026-06-26" tags={["synth-optimizers", "hosted", "gelo", "gamebench"]}>
  **synth-optimizers `0.2.6.dev20260626`** — GELO 72-hour promo and GameBench Rust smoke presets.

  * **Added:** `craftax_gamebench_rust_smoke` and `rogue_gamebench_rust_smoke` presets for hosted GELO submits against tunneled GameBench Rust task containers.
  * **Changed:** hosted GELO docs now describe the June 26 72-hour promo campaign id `gelo_free_72h_20260626`.
  * **Clarified:** SFT is invite-only beta; RLVR and OPSD remain private-evaluation or waitlist lanes.

  See [Hosted Optimizers](/sdk/hosted-optimizers#gelo-launch-promo).
</Update>

<Update label="2026-06-25" tags={["synth-ai", "research", "tag", "mcp"]}>
  **synth-ai `0.13.0`** — Synth Tag beta SDK + MCP surface.

  * **Added:** `SynthClient().research.factories.tag.sessions` with `create`, `get`, and `messages.send`.
  * **Added:** MCP tools `tag_create_session`, `tag_get_session`, and `tag_send_message`.
  * **Added:** `examples/tag_delegate_smoke.py` for delegate, steer, and receipt smoke checks.
  * **Pairs with:** backend `/api/tag/v1` routes and the `tag_steward` runbook.
  * **Status:** Prod receipt proof is green: verification run `af08fbc5-fbab-4706-8dbc-85a311035b4d`, session `af1e520d-e4e2-45f2-8393-35732cb5f217`, run `d7fa20d1-73bd-4cdc-b76f-0b706be24a5d`, artifact `/smr/work-products/3d0b11ae-97da-531d-8741-765cd517d512/content`.

  ```bash theme={null}
  pip install "synth-ai[research]==0.13.0"
  ```

  See [Synth Tag](/managed-research/tag).
</Update>

<Update label="2026-06-25" tags={["synth-ai", "research", "xai", "grok"]}>
  **synth-ai `0.11.7`** — Grok Build + direct xAI Grok catalog.

  * **Added:** `SmrAgentModel.X_AI_GROK_BUILD` (`x-ai/grok-build`) for hosted SMR runs on xAI Grok Build via direct **xAI** (`codex_xai_grok_build`).
  * **Changed:** Public Grok enum consolidates on **`x-ai/grok-4.3`** (direct xAI). Removed `x-ai/grok-4.1-fast` and `x-ai/grok-4.20-beta` from the SDK enum; backend aliases legacy ids to grok-4.3.
  * **Fixed:** xAI chat payload compatibility (no penalty fields that break streaming on Grok paths). OpenAPI synced from backend `smr_openapi.yaml`.

  ```bash theme={null}
  pip install "synth-ai[research]==0.11.7"
  ```
</Update>

<Update label="2026-06-24" tags={["synth-ai", "research", "promotions"]}>
  **synth-ai `0.11.6`** — promotions registry SDK.

  * **Added:** `client.promotions` namespace — `list_public()`, `mine()`, and `claim(campaign_id)` mapping to `GET /smr/promotions`, `GET /smr/promotions/mine`, and `POST /smr/promotions/{campaign_id}/claim`; admin helpers `list_admin_campaigns()`, `upsert_admin_campaign(...)`, and `retire_admin_campaign(campaign_id)`.
  * **Pairs with:** the backend promotions registry routes on the same deploy train. OpenAPI synced from backend `smr_openapi.yaml`.

  ```bash theme={null}
  pip install "synth-ai[research]==0.11.6"
  ```
</Update>

<Update label="2026-06-24" tags={["synth-ai", "research", "billing"]}>
  **synth-ai `0.11.5`** — billing SDK.

  * **Added:** `client.billing` namespace — `get_catalog()`, `get_plan()`, `get_run_drawdown(run_id)`, `preflight_run(...)`, factory-effort drawdown/preflight, and admin grant helpers matching `GET /smr/billing/plan`, `GET /smr/billing/catalog`, run drawdown, and preflight routes.
  * **Pairs with:** the backend billing routes on the same deploy train; no Factory surface changes.

  ```bash theme={null}
  pip install "synth-ai[research]==0.11.5"
  ```
</Update>

<Update label="2026-06-24" tags={["synth-ai", "research", "catalog"]}>
  **synth-ai `0.11.4`** — GLM 5.2 enum, public catalog sunset, MCP honesty fix.

  * **Added:** `SmrAgentModel.BASETEN_ZAI_ORG_GLM_5_2` (`baseten/zai-org/GLM-5.2`); run-policy accepts `groq` credential provider and `openrouter` inference provider.
  * **Changed:** Trinity Large Thinking, `gpt-oss-120b`, `gpt-5.4-nano`, and DeepSeek v4 flash/pro are no longer on the public catalog (`GET /smr/agent-models`). Enum ids remain importable but fail backend preflight — use `gpt-5.4-mini`, `gpt-5.4`, or GLM 5.2.
  * **Fixed:** Removed dead MCP tool `smr_get_project_economics`. **Errata for 0.11.3:** that tool was listed in release notes but had no live backend route; use `smr_get_project_usage` / `smr_get_run_usage` instead.

  ```bash theme={null}
  pip install "synth-ai[research]==0.11.4"
  ```
</Update>

<Update label="2026-06-22" tags={["synth-ai", "research", "mcp"]}>
  **synth-ai `0.11.3`** — Launch MCP package for the 222-tool Managed Research surface.

  * Project economics and GitHub setup MCP tools targeted for this release: `smr_get_project_economics`, `smr_setup_github_status`, `smr_setup_github_start_oauth`, `smr_setup_github_list_repos`, `smr_setup_github_disconnect`.
  * **Note (0.11.4 errata):** `smr_get_project_economics` was removed in 0.11.4 — use usage/billing tools instead.

  ```bash theme={null}
  pip install "synth-ai[research]==0.11.3"
  ```
</Update>

<Update label="2026-06-16" tags={["synth-ai", "research", "breaking"]}>
  **synth-ai `0.11.2`** — Managed Research SDK reconciled to the shipped backend contract.

  * **Added:** `SynthClient().research`, MCP entrypoint `synth-ai-managed-research-mcp`, optional extra `synth-ai[research]`.
  * **Removed (breaking vs 0.11.1):** Objective/milestone/experiment CRUD helpers, deprecated project economics wrappers, legacy GitHub setup modules, standalone `managed-research` as the primary install story.
  * **Migration:** `pip install "synth-ai[research]==0.11.2"`; `from synth_ai import SynthClient` → `client.research`.

  See [Managed Research SDK Quickstart](/managed-research/sdk-quickstart).
</Update>

<Update label="2026-06-11" tags={["synth-optimizers", "hosted", "gelo"]}>
  **synth-optimizers hosted GELO launch promo** - Hosted optimizer docs now document the first-20 GELO promo, GPT-family proposer policy, claim/status endpoints, and hosted proposer-spend grant.

  See [Hosted Optimizers](/sdk/hosted-optimizers#gelo-launch-promo).
</Update>

<Update label="2026-06-11" tags={["synth-ai", "research", "migration"]}>
  **synth-ai `0.11.1`** — Managed Research SDK and MCP now ship inside `synth-ai[research]`.

  Migration:

  ```bash theme={null}
  pip install "synth-ai[research]"
  ```

  ```python theme={null}
  from synth_ai import SynthClient

  research = SynthClient().research
  ```

  MCP entrypoint: `synth-ai-managed-research-mcp`. Hosted HTTP MCP server name: `synth-managed-research`.

  The `managed-research` PyPI package remains a temporary shim with DeprecationWarning and should not be used for new installs.

  See [Managed Research SDK Quickstart](/managed-research/sdk-quickstart).
</Update>

<Update label="2026-06-10" tags={["synth-optimizers", "hosted"]}>
  **synth-optimizers `0.2.1.20260610`** — Hosted GELO CLI (`gelo submit`, `gelo watch`), hosted GEPA submit/watch via `HostedOptimizerClient`, privacy-first usage registration opt-outs.

  See [Hosted Optimizers](/sdk/hosted-optimizers) for current quickstart commands.
</Update>

## Contributing

* **Product-facing** copy → `frontend/content/changelog/*.mdx`
* **This page** → semver, deprecations, MCP/CLI/API deltas
* **Launch proof** → `Jstack/.jstack/records/releases/` and `records/launches/`

Policy: `Jstack/.jstack/daily_notes/2026-06-10/release_launch_cadence.md`
(§ Changelog Placement).