zoowork 0.1.0__tar.gz

zoowork-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install -e '.[dev]'
+      - run: python -m pytest
+      - run: python -m ruff check .
+      - run: python -m mypy src
+      - run: python -m build
+      - run: python -m twine check dist/*

zoowork-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+          cache: pip
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v5
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/zoowork/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

zoowork-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+htmlcov/
+e2e/.state/

zoowork-0.1.0/AGENTS.md

@@ -0,0 +1,13 @@
+# ZooWork Python SDK
+
+This repository is the official Python client for the public ZooWork Managed Agents API.
+
+- Keep the runtime surface aligned with `zoowork-sdk-typescript`; API behavior comes from the public gateway contract, not Python-specific invention.
+- Public methods use Python `snake_case`; request and response field names remain the API's original spelling.
+- Treat identifiers and unknown response fields as opaque. Preserve server error codes verbatim in `ZooworkError`.
+- Never put API keys, staging credentials, private payloads, or recorded customer data in source, fixtures, logs, or documentation.
+- Unit tests and CI are offline. Live staging checks belong under `e2e/` and must be run explicitly before publication.
+- The package is Python 3.10+ and uses `httpx` for async HTTP and streaming. Avoid adding runtime dependencies without a concrete public-SDK need.
+- Run `python -m pytest`, `python -m ruff check .`, `python -m mypy src`, and `python -m build` before committing.
+- Publishing is performed by `.github/workflows/release.yml` through PyPI Trusted Publishing. Do not add a long-lived PyPI token.
+- Do not bump the package version or publish unless the user explicitly requests a release.

zoowork-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Initial Python SDK for ZooWork Managed Agents.
+- Async HTTP client, paginated agent listing, durable event history and SSE streaming.
+- Agent, channel, skill, session, approval, artifact, schedule, wake, exec and Environment operations.
+- PyPI Trusted Publishing workflow.

zoowork-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SerendipityOneInc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zoowork-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: zoowork
+Version: 0.1.0
+Summary: Official Python SDK for the ZooWork Managed Agents API
+Project-URL: Documentation, https://github.com/SerendipityOneInc/zoowork-agents-docs
+Project-URL: Repository, https://github.com/SerendipityOneInc/zoowork-sdk-python
+Project-URL: Issues, https://github.com/SerendipityOneInc/zoowork-sdk-python/issues
+Author: SerendipityOneInc
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,llm,sdk,sse,streaming,zoowork
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# zoowork
+
+Official Python SDK for the [ZooWork Managed Agents API](https://github.com/SerendipityOneInc/zoowork-agents-docs). Developer Preview.
+
+The client is asynchronous, typed, and built on `httpx`. Request and response fields retain the public API's wire spelling, while methods use Python `snake_case`.
+
+```bash
+pip install zoowork
+```
+
+## Quickstart
+
+Create an organization API key (`zct_...`) in ZooWork under **Settings → API Keys** and keep it on your server. It authenticates as the organization, not as one end user.
+
+```python
+import asyncio
+import os
+
+from zoowork import assistant_text, create_zoowork_client, is_run_finished
+
+
+async def main() -> None:
+    async with create_zoowork_client(os.environ["ZOOWORK_API_KEY"]) as client:
+        models = await client.list_models()
+        agent = await client.create_agent(
+            {"name": "research-agent", "model": {"primary": models[0]["model"]}}
+        )
+        agent_id = agent["agent_id"]
+
+        await client.start_agent(agent_id)
+        await client.wait_until_running(agent_id)
+        session = await client.create_session(
+            agent_id,
+            {"initial_events": [{"type": "user.message", "content": "What can you do?"}]},
+        )
+
+        async for event in client.stream_events(agent_id, session["session_id"]):
+            print(assistant_text(event), end="", flush=True)
+            if is_run_finished(event):
+                break
+
+
+asyncio.run(main())
+```
+
+Set `ZOOWORK_API_KEY` and call `create_zoowork_client()` with no argument if you prefer. The client uses the production API by default; `ZOOWORK_BASE_URL` or `base_url=` selects another deployment.
+
+## Pagination
+
+`list_agents()` returns one `AgentPage`. Iterate the page to continue lazily through every remaining page while retaining the original filters:
+
+```python
+page = await client.list_agents(labels={"project": "research"})
+print(page.data, page.total, page.next_page)
+
+async for agent in page:
+    print(agent["agent_id"])
+```
+
+Use `await page.get_next_page()` for manual navigation or `client.iter_agents()` when you do not need the first page's metadata.
+
+## Durable events
+
+The event stream is session-scoped and does not close when one turn ends. Break on `is_run_finished(event)`. Save `event.cursor` after consuming an event and pass it back as `cursor=` when reconnecting.
+
+```python
+async for event in client.stream_events(agent_id, session_id, cursor=last_cursor):
+    if event.cursor is not None:
+        last_cursor = event.cursor
+    if is_run_finished(event):
+        break
+```
+
+`list_events()` reads one durable page. `list_all_events()` follows cursor pagination, with a safe fallback for older deployments.
+
+## API surface
+
+The runtime client follows the TypeScript SDK's public capabilities:
+
+- agents, lifecycle, models and paginated listing;
+- channels and guided Feishu/WeCom/WeChat setup;
+- skill upload, versioning and agent attachment;
+- sessions, events and SSE streaming;
+- approvals, artifacts and system prompts;
+- schedules, wake and sandbox exec;
+- Environments and immutable Environment versions.
+
+Methods return dictionaries containing the API response unchanged unless the SDK must normalize pagination or events. Unknown fields are intentionally preserved.
+
+## Errors
+
+Every non-successful response raises `ZooworkError`. Match `error.type` or `error.status`, never the human-readable message. Diagnostic fields include `content_type`, `body_snippet`, `cf_ray`, `request_id`, and `retryable`.
+
+## Development
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest
+python -m ruff check .
+python -m mypy src
+python -m build
+python -m twine check dist/*
+```
+
+Unit tests are offline. The live staging procedure is documented in [`e2e/README.md`](e2e/README.md) and is never run by CI.

zoowork-0.1.0/README.md

@@ -0,0 +1,107 @@
+# zoowork
+
+Official Python SDK for the [ZooWork Managed Agents API](https://github.com/SerendipityOneInc/zoowork-agents-docs). Developer Preview.
+
+The client is asynchronous, typed, and built on `httpx`. Request and response fields retain the public API's wire spelling, while methods use Python `snake_case`.
+
+```bash
+pip install zoowork
+```
+
+## Quickstart
+
+Create an organization API key (`zct_...`) in ZooWork under **Settings → API Keys** and keep it on your server. It authenticates as the organization, not as one end user.
+
+```python
+import asyncio
+import os
+
+from zoowork import assistant_text, create_zoowork_client, is_run_finished
+
+
+async def main() -> None:
+    async with create_zoowork_client(os.environ["ZOOWORK_API_KEY"]) as client:
+        models = await client.list_models()
+        agent = await client.create_agent(
+            {"name": "research-agent", "model": {"primary": models[0]["model"]}}
+        )
+        agent_id = agent["agent_id"]
+
+        await client.start_agent(agent_id)
+        await client.wait_until_running(agent_id)
+        session = await client.create_session(
+            agent_id,
+            {"initial_events": [{"type": "user.message", "content": "What can you do?"}]},
+        )
+
+        async for event in client.stream_events(agent_id, session["session_id"]):
+            print(assistant_text(event), end="", flush=True)
+            if is_run_finished(event):
+                break
+
+
+asyncio.run(main())
+```
+
+Set `ZOOWORK_API_KEY` and call `create_zoowork_client()` with no argument if you prefer. The client uses the production API by default; `ZOOWORK_BASE_URL` or `base_url=` selects another deployment.
+
+## Pagination
+
+`list_agents()` returns one `AgentPage`. Iterate the page to continue lazily through every remaining page while retaining the original filters:
+
+```python
+page = await client.list_agents(labels={"project": "research"})
+print(page.data, page.total, page.next_page)
+
+async for agent in page:
+    print(agent["agent_id"])
+```
+
+Use `await page.get_next_page()` for manual navigation or `client.iter_agents()` when you do not need the first page's metadata.
+
+## Durable events
+
+The event stream is session-scoped and does not close when one turn ends. Break on `is_run_finished(event)`. Save `event.cursor` after consuming an event and pass it back as `cursor=` when reconnecting.
+
+```python
+async for event in client.stream_events(agent_id, session_id, cursor=last_cursor):
+    if event.cursor is not None:
+        last_cursor = event.cursor
+    if is_run_finished(event):
+        break
+```
+
+`list_events()` reads one durable page. `list_all_events()` follows cursor pagination, with a safe fallback for older deployments.
+
+## API surface
+
+The runtime client follows the TypeScript SDK's public capabilities:
+
+- agents, lifecycle, models and paginated listing;
+- channels and guided Feishu/WeCom/WeChat setup;
+- skill upload, versioning and agent attachment;
+- sessions, events and SSE streaming;
+- approvals, artifacts and system prompts;
+- schedules, wake and sandbox exec;
+- Environments and immutable Environment versions.
+
+Methods return dictionaries containing the API response unchanged unless the SDK must normalize pagination or events. Unknown fields are intentionally preserved.
+
+## Errors
+
+Every non-successful response raises `ZooworkError`. Match `error.type` or `error.status`, never the human-readable message. Diagnostic fields include `content_type`, `body_snippet`, `cf_ray`, `request_id`, and `retryable`.
+
+## Development
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest
+python -m ruff check .
+python -m mypy src
+python -m build
+python -m twine check dist/*
+```
+
+Unit tests are offline. The live staging procedure is documented in [`e2e/README.md`](e2e/README.md) and is never run by CI.

zoowork-0.1.0/e2e/README.md

@@ -0,0 +1,21 @@
+# Staging E2E
+
+This check installs the candidate package and exercises one real Agent and Session against an explicitly selected staging deployment. It may create a billable model turn.
+
+Do not put the staging key in the repository, shell history, CI or test output. Read it without echoing, install the built wheel into an isolated environment, and run the smoke test only when a release candidate is ready:
+
+```bash
+python -m build
+candidate_venv="$(mktemp -d)/venv"
+python -m venv "$candidate_venv"
+"$candidate_venv/bin/python" -m pip install dist/zoowork-*.whl
+read -r -s ZOOWORK_API_KEY
+export ZOOWORK_API_KEY
+export ZOOWORK_BASE_URL=https://staging.example/service/v1
+"$candidate_venv/bin/python" e2e/smoke.py
+unset ZOOWORK_API_KEY
+```
+
+`ZOOWORK_BASE_URL` is required so this release check cannot silently target production. The script creates an Agent, waits on `status.desired_state`, sends one message, waits for `run.finished`, verifies assistant text, and best-effort deletes the Agent in `finally`.
+
+Passing this check does not publish the package. Publish the exact wheel that was tested; rebuild or source changes invalidate the result.

zoowork-0.1.0/e2e/smoke.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import uuid
+
+from zoowork import assistant_text, create_zoowork_client, is_run_finished, run_outcome
+
+
+async def main() -> None:
+    api_key = os.getenv("ZOOWORK_API_KEY")
+    base_url = os.getenv("ZOOWORK_BASE_URL")
+    if not api_key or not base_url:
+        raise SystemExit("Set ZOOWORK_API_KEY and an explicit staging ZOOWORK_BASE_URL")
+
+    async with create_zoowork_client(api_key, base_url=base_url) as client:
+        models = await client.list_models()
+        if not models or not isinstance(models[0].get("model"), str):
+            raise RuntimeError("Staging returned no usable model")
+        agent = await client.create_agent(
+            {
+                "name": f"python-sdk-e2e-{uuid.uuid4().hex[:10]}",
+                "model": {"primary": models[0]["model"]},
+                "labels": {"purpose": "python-sdk-release-e2e"},
+            },
+            idempotency_key=str(uuid.uuid4()),
+        )
+        agent_id = str(agent["agent_id"])
+        try:
+            await client.start_agent(agent_id)
+            await client.wait_until_running(agent_id)
+            session = await client.create_session(
+                agent_id,
+                {
+                    "initial_events": [
+                        {"type": "user.message", "content": "Reply with exactly: python sdk ok"}
+                    ]
+                },
+                idempotency_key=str(uuid.uuid4()),
+            )
+            text = ""
+            outcome: str | None = None
+            async for event in client.stream_events(agent_id, str(session["session_id"])):
+                text += assistant_text(event)
+                if is_run_finished(event):
+                    outcome = run_outcome(event)
+                    break
+            if outcome != "succeeded" or "python sdk ok" not in text.lower():
+                raise RuntimeError(f"Unexpected turn result: outcome={outcome!r}, text={text!r}")
+        finally:
+            await client.delete_agent(agent_id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

zoowork-0.1.0/examples/quickstart.py

@@ -0,0 +1,31 @@
+import asyncio
+
+from zoowork import assistant_text, create_zoowork_client, is_run_finished
+
+
+async def main() -> None:
+    async with create_zoowork_client() as client:
+        models = await client.list_models()
+        if not models:
+            raise RuntimeError("This deployment returned no models")
+        agent = await client.create_agent(
+            {"name": "python-sdk-example", "model": {"primary": models[0]["model"]}}
+        )
+        agent_id = agent["agent_id"]
+        try:
+            await client.start_agent(agent_id)
+            await client.wait_until_running(agent_id)
+            session = await client.create_session(
+                agent_id,
+                {"initial_events": [{"type": "user.message", "content": "Say hello."}]},
+            )
+            async for event in client.stream_events(agent_id, session["session_id"]):
+                print(assistant_text(event), end="", flush=True)
+                if is_run_finished(event):
+                    break
+        finally:
+            await client.delete_agent(agent_id)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

zoowork-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zoowork"
+version = "0.1.0"
+description = "Official Python SDK for the ZooWork Managed Agents API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "SerendipityOneInc" }]
+keywords = ["zoowork", "agents", "sdk", "llm", "sse", "streaming"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "mypy>=1.13",
+  "pytest>=8.3",
+  "pytest-asyncio>=0.24",
+  "ruff>=0.8",
+  "twine>=6",
+]
+
+[project.urls]
+Documentation = "https://github.com/SerendipityOneInc/zoowork-agents-docs"
+Repository = "https://github.com/SerendipityOneInc/zoowork-sdk-python"
+Issues = "https://github.com/SerendipityOneInc/zoowork-sdk-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zoowork"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["zoowork"]

zoowork-0.1.0/src/zoowork/__init__.py

@@ -0,0 +1,48 @@
+"""Official Python SDK for ZooWork Managed Agents."""
+
+from ._version import __version__
+from .client import (
+    DEFAULT_BASE_URL,
+    AgentPage,
+    JsonObject,
+    ZooworkClient,
+    ZooworkError,
+    create_zoowork_client,
+)
+from .events import (
+    PUBLIC_INPUT_EVENT_TYPES,
+    SESSION_EVENT_TYPES,
+    SessionEvent,
+    ToolCall,
+    assistant_text,
+    is_run_finished,
+    message_text,
+    normalize_event,
+    run_outcome,
+    thinking_text,
+    tool_call,
+)
+from .sse import SSEMessage, parse_sse
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "PUBLIC_INPUT_EVENT_TYPES",
+    "SESSION_EVENT_TYPES",
+    "AgentPage",
+    "JsonObject",
+    "SSEMessage",
+    "SessionEvent",
+    "ToolCall",
+    "ZooworkClient",
+    "ZooworkError",
+    "__version__",
+    "assistant_text",
+    "create_zoowork_client",
+    "is_run_finished",
+    "message_text",
+    "normalize_event",
+    "parse_sse",
+    "run_outcome",
+    "thinking_text",
+    "tool_call",
+]

zoowork-0.1.0/src/zoowork/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"