From a6a6dab81789a572be47aef129b9df022b7fa642 Mon Sep 17 00:00:00 2001 From: Bryant Date: Thu, 9 Jul 2026 09:36:04 +0800 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=9D=20(readme):=20Document=20--pre?= =?UTF-8?q?=20for=20pre-release=20install?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every live PyPI release of agent-assembly is a pre-release (rc3) and the only final release (0.0.2) is yanked, so `pip install agent-assembly` resolves to nothing for a first-time user. Add `--pre` to the pip install commands and a note explaining it can be dropped once a stable release exists. Refs AAASM-4332 --- README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f6524dd9..f4e7bb2e 100644 --- a/README.md +++ b/README.md @@ -78,10 +78,14 @@ version (`agent-assembly==0.0.x`) if you need a stable contract. The package is published on PyPI as [`agent-assembly`](https://pypi.org/project/agent-assembly/): ```bash -pip install agent-assembly # pure-Python SDK -pip install 'agent-assembly[runtime]' # SDK + bundled aasm runtime binary (platform wheel) +pip install --pre agent-assembly # pure-Python SDK +pip install --pre 'agent-assembly[runtime]' # SDK + bundled aasm runtime binary (platform wheel) ``` +> **`--pre` is required for now.** Agent Assembly is currently published only as a +> pre-release on PyPI, and `pip` skips pre-releases unless you pass `--pre`. Drop the +> flag once a stable (non-pre-release) version is published. + `agent-assembly[runtime]` pulls a platform wheel (`manylinux`, `macosx`) that bundles the `aasm` sidecar binary, so you don't need a separate runtime install. Plain `agent-assembly` is the pure-Python client and expects an `aasm` runtime to be reachable some other way. @@ -127,7 +131,7 @@ The pure-Python SDK works without the native extension — `maturin develop` is A governed LangChain ReAct agent that runs offline against a mock LLM. The example imports LangChain in addition to the SDK, so install both: ```bash -pip install agent-assembly langchain langchain-community +pip install --pre agent-assembly langchain langchain-community ``` ```python From 16f0cc712177c8d1a12ffb73ea4f6ecc714e72b7 Mon Sep 17 00:00:00 2001 From: Bryant Date: Thu, 9 Jul 2026 09:36:48 +0800 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=9D=20(docs):=20Document=20--pre?= =?UTF-8?q?=20for=20pre-release=20install?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add --pre to the install-command macro source (docs_macros.py, which drives quick-start, release-process, and preparing-the-runtime-environment) and to the literal framework-composed install lines in the compatibility, examples, type-checking, and troubleshooting docs. Add a pre-release note to the quick-start install section. Same root cause as the README fix: agent-assembly only publishes pre-releases today, so pip needs --pre. Refs AAASM-4332 --- docs/compatibility/frameworks.md | 2 +- docs/development/docs-macros.md | 2 +- docs/examples/framework-support.md | 2 +- docs/guides/type-checking.md | 2 +- docs/quick-start.md | 5 +++++ docs/troubleshooting.md | 2 +- docs_macros.py | 4 ++-- 7 files changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/compatibility/frameworks.md b/docs/compatibility/frameworks.md index 3e212705..730e3d4d 100644 --- a/docs/compatibility/frameworks.md +++ b/docs/compatibility/frameworks.md @@ -135,7 +135,7 @@ your agent already uses, alongside the SDK, and the matching adapter activates automatically: ```bash -pip install agent-assembly langchain # or crewai, pydantic-ai, mcp, openai-agents, smolagents, ... +pip install --pre agent-assembly langchain # or crewai, pydantic-ai, mcp, openai-agents, smolagents, ... ``` The SDK deliberately does **not** declare these frameworks as `pip install diff --git a/docs/development/docs-macros.md b/docs/development/docs-macros.md index 6f12174d..02c5753e 100644 --- a/docs/development/docs-macros.md +++ b/docs/development/docs-macros.md @@ -80,7 +80,7 @@ Report bugs on the [issue tracker]({{ aa.urls.issues }}). pinning pattern rather than the current version. - **One-off framework-composed install commands** where the readability cost of `{{ aa.commands.install_pip }} langchain` exceeds the drift risk of - `pip install agent-assembly langchain`. Templating everything is not the + `pip install --pre agent-assembly langchain`. Templating everything is not the goal; the goal is to keep the **current-state, high-drift** values in sync. If in doubt, ask: *"When we cut the next release, will this line become diff --git a/docs/examples/framework-support.md b/docs/examples/framework-support.md index ed3524c3..2b05bc79 100644 --- a/docs/examples/framework-support.md +++ b/docs/examples/framework-support.md @@ -68,7 +68,7 @@ A governed LangChain ReAct agent that runs **offline** against a mock LLM — no and no network calls. Install the SDK plus LangChain: ```bash -pip install agent-assembly langchain langchain-community +pip install --pre agent-assembly langchain langchain-community ``` ```python diff --git a/docs/guides/type-checking.md b/docs/guides/type-checking.md index bc2cc432..6843bf81 100644 --- a/docs/guides/type-checking.md +++ b/docs/guides/type-checking.md @@ -34,7 +34,7 @@ care about. Use any PEP 561-aware checker. With mypy: ```bash -pip install agent-assembly mypy +pip install --pre agent-assembly mypy mypy your_app.py ``` diff --git a/docs/quick-start.md b/docs/quick-start.md index 20943538..2dfa3a26 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -23,6 +23,11 @@ The package is published on PyPI as {{ aa.commands.install_uv }} ``` +!!! note "`--pre` is required for now" + Agent Assembly is currently published only as a pre-release on PyPI, and `pip` + skips pre-releases unless you pass `--pre` (already included above). Drop the flag + once a stable (non-pre-release) version is published. + `{{ aa.python_sdk.package_name }}` is the pure-Python client. `{{ aa.python_sdk.package_name }}[runtime]` additionally pulls a platform wheel (`manylinux`, `macosx`) that bundles the `{{ aa.python_sdk.cli_name }}` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 27f0669a..7f5ccfb5 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -51,7 +51,7 @@ still works. To enable it: ```bash -pip install 'agent-assembly[runtime]' # bundled platform wheel, or +pip install --pre 'agent-assembly[runtime]' # bundled platform wheel, or uv tool run maturin develop --manifest-path native/aa-ffi-python/Cargo.toml --release # build locally (needs Rust) ``` diff --git a/docs_macros.py b/docs_macros.py index c01429f8..9cfe3b63 100644 --- a/docs_macros.py +++ b/docs_macros.py @@ -61,8 +61,8 @@ def define_env(env: Any) -> None: }, "commands": { "install_uv": "uv add agent-assembly", - "install_pip": "pip install agent-assembly", - "install_pip_runtime": "pip install 'agent-assembly[runtime]'", + "install_pip": "pip install --pre agent-assembly", + "install_pip_runtime": "pip install --pre 'agent-assembly[runtime]'", }, } From db51873a40146bce98c67cf12c2746361e3b2cce Mon Sep 17 00:00:00 2001 From: Bryant Date: Thu, 9 Jul 2026 09:40:23 +0800 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=90=9B=20(core):=20Fix=20non-existent?= =?UTF-8?q?=20[cli]=20extra=20in=20auto-start=20hint?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The auto-start ConfigurationError told users to run `pip install agent-assembly[cli]`, but no `cli` extra exists (only `runtime` and `all`); pip warns and installs nothing. The `aasm` binary ships via the `runtime` extra (the `aasm` console script itself is an always-installed [project.scripts] entry). Point the hint at `agent-assembly[runtime]`. (pre-commit's pinned black also joined a pre-existing split string literal on line 73 when the file was staged.) Refs AAASM-4332 --- agent_assembly/core/gateway_resolver.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/agent_assembly/core/gateway_resolver.py b/agent_assembly/core/gateway_resolver.py index 80d75d7e..3d6ccb5b 100644 --- a/agent_assembly/core/gateway_resolver.py +++ b/agent_assembly/core/gateway_resolver.py @@ -70,8 +70,7 @@ def _warn_if_world_readable(path: Path) -> None: return if mode & 0o077: logger.warning( - "Config file %s has group/other-readable permissions (mode %o); " - "run `chmod 600 %s` to secure it.", + "Config file %s has group/other-readable permissions (mode %o); " "run `chmod 600 %s` to secure it.", path, mode, path, @@ -183,7 +182,7 @@ def _auto_start_gateway( if aasm_path is None: raise ConfigurationError( f"No gateway found at {base_url} and 'aasm' is not on PATH. " - "Install it with: pip install agent-assembly[cli]" + "Install it with: pip install 'agent-assembly[runtime]'" ) subprocess.Popen(