Starweaver Python

starweaver is the in-process Python SDK and binding package for Starweaver. It keeps the Rust runtime as the canonical agent loop while exposing Python ergonomics for agents, tools, models, sessions, streams, resources, media, and deterministic tests.

Python tools are injected directly as native Starweaver runtime tools. They do not use MCP, stdio, or another binary protocol.

Supported Python versions are CPython 3.11 through 3.13. Local development and single-version CI jobs default to Python 3.13.

Quickstart

import asyncio

from starweaver import create_agent, tool
from starweaver.testing import TestModel


@tool
async def add(left: int, right: int) -> dict[str, int]:
    return {"total": left + right}


async def main() -> None:
    model = TestModel.responses(
        [
            TestModel.tool_call_response(
                [{"id": "call_add", "name": "add", "arguments": {"left": 2, "right": 3}}]
            ),
            {"text": "done"},
        ]
    )
    result = await create_agent(model=model, tools=[add]).run("Add two numbers")
    print(result.output)


asyncio.run(main())

Core Surfaces

create_agent() builds a Python facade over the Rust runtime.
@tool, raw callables, and BaseTool register in-process tools.
Independent tool calls run in parallel by default; use sequential=True for ordered side effects.
Toolset, ToolSearchToolset, and ToolProxyToolset compose grouped tools.
ProviderModel, TestModel, and FunctionModel cover production providers, deterministic scripts, and callback-backed tests.
OutputSchema, OutputPolicy, validators, and output functions handle final output.
AgentSession and SessionArchive preserve reusable session state.
EnvironmentProvider, ResourceRef, SkillRegistry, and MediaUploader expose environment, resource, skill, and media boundaries.

Stream Boundary

run_stream() currently returns AgentRun, an async iterator over canonical StreamEvent records plus a Python facade for recv(), join(), result(), status(), recoverable_state(), interrupt(), active messages, steering, and streamed HITL helpers. The stable portable contract is the canonical StreamEvent.raw record sequence and collected run result. Python live-control ergonomics are the current facade, not a separately frozen live-handle protocol.

AgentStream remains a compatibility alias for AgentRun.

Documentation

Start with docs/python-sdk.md in the repository. The Python docs are organized by feature:

docs/python/agents.md
docs/python/tools.md
docs/python/toolsets.md
docs/python/models.md
docs/python/output.md
docs/python/sessions-streams.md
docs/python/environments-skills.md
docs/python/media.md
docs/python/testing.md
docs/python/examples.md
docs/python/stability.md

Runnable examples live in examples/python/.

Validation

From the repository root:

make py-sync
make py-lint
make py-rust-check
make py-test
make py-wheel-smoke
make py-check

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

starweaver-0.8.1.tar.gz (1.3 MB view details)

Uploaded Jul 16, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

starweaver-0.8.1-cp313-cp313-win_amd64.whl (14.5 MB view details)

Uploaded Jul 16, 2026 CPython 3.13Windows x86-64

starweaver-0.8.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (15.4 MB view details)

Uploaded Jul 16, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64

starweaver-0.8.1-cp313-cp313-macosx_11_0_arm64.whl (14.1 MB view details)

Uploaded Jul 16, 2026 CPython 3.13macOS 11.0+ ARM64

starweaver-0.8.1-cp313-cp313-macosx_10_12_x86_64.whl (14.6 MB view details)

Uploaded Jul 16, 2026 CPython 3.13macOS 10.12+ x86-64

starweaver-0.8.1-cp312-cp312-win_amd64.whl (14.5 MB view details)

Uploaded Jul 16, 2026 CPython 3.12Windows x86-64

starweaver-0.8.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (15.4 MB view details)

Uploaded Jul 16, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64

starweaver-0.8.1-cp312-cp312-macosx_11_0_arm64.whl (14.1 MB view details)

Uploaded Jul 16, 2026 CPython 3.12macOS 11.0+ ARM64

starweaver-0.8.1-cp312-cp312-macosx_10_12_x86_64.whl (14.6 MB view details)

Uploaded Jul 16, 2026 CPython 3.12macOS 10.12+ x86-64

starweaver-0.8.1-cp311-cp311-win_amd64.whl (14.5 MB view details)

Uploaded Jul 16, 2026 CPython 3.11Windows x86-64

starweaver-0.8.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (15.4 MB view details)

Uploaded Jul 16, 2026 CPython 3.11manylinux: glibc 2.17+ x86-64

starweaver-0.8.1-cp311-cp311-macosx_11_0_arm64.whl (14.1 MB view details)

Uploaded Jul 16, 2026 CPython 3.11macOS 11.0+ ARM64

starweaver-0.8.1-cp311-cp311-macosx_10_12_x86_64.whl (14.6 MB view details)

Uploaded Jul 16, 2026 CPython 3.11macOS 10.12+ x86-64

File details

Details for the file starweaver-0.8.1.tar.gz.

File metadata

Download URL: starweaver-0.8.1.tar.gz
Upload date: Jul 16, 2026
Size: 1.3 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for starweaver-0.8.1.tar.gz
Algorithm	Hash digest
SHA256	`b171f61685d47bab1debf431d58374cb331edbc06414332d7319709f6bd6d333`
MD5	`220f0ab42f9dc7c8ff9a8b5c4fb77fde`
BLAKE2b-256	`5ded10b5f176fd8254b6e8ace57fbfe4f1e30f8df4af9c2b970af950b658899d`

See more details on using hashes here.

File details

Details for the file starweaver-0.8.1-cp313-cp313-win_amd64.whl.

File metadata

Download URL: starweaver-0.8.1-cp313-cp313-win_amd64.whl
Upload date: Jul 16, 2026
Size: 14.5 MB
Tags: CPython 3.13, Windows x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for starweaver-0.8.1-cp313-cp313-win_amd64.whl
Algorithm	Hash digest
SHA256	`81ddafac760fbb80b94925242ca14602a4e86945fd39c46ddbb549c7f9c9890f`
MD5	`18b9254eea9fabc0ff3d0f517bf91c00`
BLAKE2b-256	`e7fe056b342baad9d051a9b0c88457505c617b1cdf557e76c2b19d77d029646f`

See more details on using hashes here.

File details

Details for the file starweaver-0.8.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: starweaver-0.8.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Jul 16, 2026
Size: 15.4 MB
Tags: CPython 3.13, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for starweaver-0.8.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`e1c2a6961ab79e22e73e3fdfb23ccb76418224c14533223222e489a122c9df49`
MD5	`e84bb0380d3e071053dd945d24fd7cf6`
BLAKE2b-256	`0b080b272f44cb4349c0a21057ca3dbdf454da08debb33363bc3fc96c9d53c6a`

See more details on using hashes here.

File details

Details for the file starweaver-0.8.1-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

Download URL: starweaver-0.8.1-cp313-cp313-macosx_11_0_arm64.whl
Upload date: Jul 16, 2026
Size: 14.1 MB
Tags: CPython 3.13, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for starweaver-0.8.1-cp313-cp313-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`80e72a1a7c55eb2c9902ea4e75c1e9a0e85dc97888b2213b249c5cac720c16f6`
MD5	`91ddb4f72a842240463f68701e0d0952`
BLAKE2b-256	`2268db6d91a450f28871b318c9cca4bf38d79150fceebebc5fea2a5f9f86ec9b`

See more details on using hashes here.

File details

Details for the file starweaver-0.8.1-cp313-cp313-macosx_10_12_x86_64.whl.

File metadata

Download URL: starweaver-0.8.1-cp313-cp313-macosx_10_12_x86_64.whl
Upload date: Jul 16, 2026
Size: 14.6 MB
Tags: CPython 3.13, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for starweaver-0.8.1-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`4898c569f8edd4715c45999684daea9084815da51e85d205dc2987206dd190f8`
MD5	`33c48c912282e564f3f349d121d3d678`
BLAKE2b-256	`1fdf19e45bbf1027353a4e61c95b28c7040d8b7a2b7bc78ff8452724102c1ce8`

See more details on using hashes here.

File details

Details for the file starweaver-0.8.1-cp312-cp312-win_amd64.whl.

File metadata

Download URL: starweaver-0.8.1-cp312-cp312-win_amd64.whl
Upload date: Jul 16, 2026
Size: 14.5 MB
Tags: CPython 3.12, Windows x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for starweaver-0.8.1-cp312-cp312-win_amd64.whl
Algorithm	Hash digest
SHA256	`5e6f3983e45182cbb6a8ccc1a16992bf1b6267da2263aa2879c9fe97d1a9d3d1`
MD5	`a2e6d7e8f2c1aa683237f55fa296cef7`
BLAKE2b-256	`ae88a49dfc873e42c6a30b20015711c61448611e22af7227133aa9c00ae2c88a`

See more details on using hashes here.

File details

Details for the file starweaver-0.8.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: starweaver-0.8.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Jul 16, 2026
Size: 15.4 MB
Tags: CPython 3.12, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for starweaver-0.8.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`396f87e97cdb96e44db7999585a248c5e0e5a6a1380da444f6d5dc87313eb291`
MD5	`62c730faf9077afb7c04505a2a3111ef`
BLAKE2b-256	`bb4a431137a733c16441f920558e7588732d08c0b9c0cf4578264ca59f0a9599`

See more details on using hashes here.

File details

Details for the file starweaver-0.8.1-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

Download URL: starweaver-0.8.1-cp312-cp312-macosx_11_0_arm64.whl
Upload date: Jul 16, 2026
Size: 14.1 MB
Tags: CPython 3.12, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for starweaver-0.8.1-cp312-cp312-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`fd988f29318bb217d339cbfbd4ec4cb02952c2e71ec5b6e570b963f739fa699a`
MD5	`913cb7bd9ebdf635b2fe5f1afca55b46`
BLAKE2b-256	`4ac40ac56b306eaf33c2e415a5587c1a4e9083c79de7f6e563a08881e86a75e8`

See more details on using hashes here.

File details

Details for the file starweaver-0.8.1-cp312-cp312-macosx_10_12_x86_64.whl.

File metadata

Download URL: starweaver-0.8.1-cp312-cp312-macosx_10_12_x86_64.whl
Upload date: Jul 16, 2026
Size: 14.6 MB
Tags: CPython 3.12, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for starweaver-0.8.1-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`7f7495110f302db880ad6ee25ac6e478471a3b420f0437b332112ea61f4ae95e`
MD5	`a8750fdb0a64f8d66ec14da9684cc394`
BLAKE2b-256	`7abf027fbd3dabd4bb356bd705f0f41e0859894587b1a46fc053724eacb974c2`

See more details on using hashes here.

File details

Details for the file starweaver-0.8.1-cp311-cp311-win_amd64.whl.

File metadata

Download URL: starweaver-0.8.1-cp311-cp311-win_amd64.whl
Upload date: Jul 16, 2026
Size: 14.5 MB
Tags: CPython 3.11, Windows x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for starweaver-0.8.1-cp311-cp311-win_amd64.whl
Algorithm	Hash digest
SHA256	`533a73d55d0c9e9d4c562040aa20c74a49dc446c050c25268033a32cce139425`
MD5	`ab81a35e893c61a02d9e12968b8ddf7f`
BLAKE2b-256	`0f4382535866231ec8c945898153d44a07b9fd785c0d3a052ca266d02138f560`

See more details on using hashes here.

File details

Details for the file starweaver-0.8.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: starweaver-0.8.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Jul 16, 2026
Size: 15.4 MB
Tags: CPython 3.11, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for starweaver-0.8.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`5eecfb611038641c947fba4fbc936794c172becd50de87a5c2aab31d1a4c9fe7`
MD5	`7b52f182408de474cf85af0db2506a7e`
BLAKE2b-256	`a242f4cb636c31c6531f2436ccd4a10c59db4956fb7ebd0b427a65b04bd567b4`

See more details on using hashes here.

File details

Details for the file starweaver-0.8.1-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

Download URL: starweaver-0.8.1-cp311-cp311-macosx_11_0_arm64.whl
Upload date: Jul 16, 2026
Size: 14.1 MB
Tags: CPython 3.11, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for starweaver-0.8.1-cp311-cp311-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`82c2acefeec008d8f976daf6aa81417ce5585df75d491365f90ab26418ea9092`
MD5	`afb49c7c21ae69997a0a01f79c43baa1`
BLAKE2b-256	`a8c4ad15bb669f786e4d2cf7e2272cd2222f7800dabb335f9231ec49ae7df993`

See more details on using hashes here.

File details

Details for the file starweaver-0.8.1-cp311-cp311-macosx_10_12_x86_64.whl.

File metadata

Download URL: starweaver-0.8.1-cp311-cp311-macosx_10_12_x86_64.whl
Upload date: Jul 16, 2026
Size: 14.6 MB
Tags: CPython 3.11, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for starweaver-0.8.1-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`c09aa7fa99f7a87d9ddb93cf02703e9cde27e20d5aaa94ae997bc55d7bdff0f3`
MD5	`ff7509f60f39ec7e160ee79ae66c5f30`
BLAKE2b-256	`6eb774356d61e91fbf5c7111d3868f8eec3fd85f8e6e7775515be58f44dd445e`