soyaos

Official Python SDK for SoyaOS. Pure-Python, no required runtime dependencies, works on CPython 3.10+ and PyPy.

Install

pip install soyaos
# or, with uv
uv add soyaos

Two clients

from soyaos import SoyaOSClient, ControlClient
from soyaos.openai_compat import ChatCompletionRequest, ChatMessage

# 1) Talk to soya:* virtual models (OpenAI-compatible surface).
ai = SoyaOSClient(
    base_url="https://api.soyaos.ai/v1",
    api_key="sk-...",
)

resp = ai.chat.completions.create(
    ChatCompletionRequest(
        model="soya:echo",
        messages=[ChatMessage(role="user", content="hello")],
    )
)

# 2) Drive the control plane (Agents, keys, Scope events).
ctl = ControlClient(
    base_url="https://api.soyaos.ai",
    api_key="sk-...",
)
agents = ctl.agents.list()

There is also an async variant: from soyaos import AsyncSoyaOSClient.

Because SoyaOS speaks the OpenAI HTTP wire format, you can also point the official openai Python package at it. This SDK exists for callers who want typed access to SoyaOS-specific metadata such as soya_trace_id.

中文 Quickstart

soyaos 是 SoyaOS 的官方 Python SDK，纯 Python 实现，零运行时依赖：

pip install soyaos

from soyaos import SoyaOSClient
from soyaos.openai_compat import ChatCompletionRequest, ChatMessage

client = SoyaOSClient(
    base_url="https://api.soyaos.ai/v1",
    api_key="sk-xxx",
)

resp = client.chat.completions.create(
    ChatCompletionRequest(
        model="soya:echo",
        messages=[ChatMessage(role="user", content="你好")],
    )
)
print(resp.choices[0].message.content)

异步用户改用 AsyncSoyaOSClient；ControlClient 用来管理 Agent / Key / 订阅 Scope 事件。0.1.0a0 仅含类型签名，实际 RPC 在 0.1.0a1 接通。

Development

uv sync --all-extras
uv run ruff check .
uv run mypy
uv run pytest

Release & publish

PyPI publishing is automated by .github/workflows/publish-pypi.yml. To cut a release:

1. Bump project.version in pyproject.toml (PEP 440) and update CHANGELOG.md.
2. Commit, tag vX.Y.Z (must match project.version), and push the tag.
3. Create a GitHub Release from the tag. Publishing the release triggers the workflow, which builds an sdist + wheel, verifies the tag/pyproject versions match, and uploads to PyPI via the PYPI_API_TOKEN repository secret.

The first release of this package is the placeholder 0.0.0.dev0, published to reserve the soyaos name on PyPI (see APP-433). Real SDK releases start at 0.1.0a0; pip install soyaos resolves to the highest non-pre-release version, so the dev0 placeholder does not block normal installs.

Status

0.1.0a0 ships types + signatures only. Calls raise NotImplementedError. Real RPCs land in 0.1.0a1 — see CHANGELOG.md.

License

MIT — © 2026 SoyaOS Contributors.