ignore: python sdk (#2779)

Co-authored-by: Aiden Cline <[email protected]>

10 files changed, 208 insertions, 0 deletions

diff --git a/packages/sdk/python/docs/generation.md b/packages/sdk/python/docs/generation.md
new file mode 100644
index 000000000..f949760a1
--- /dev/null
+++ b/packages/sdk/python/docs/generation.md
@@ -0,0 +1,19 @@
+# Generation workflow
+
+The SDK is generated from the Opencode server's OpenAPI 3.1 spec.
+
+Two source modes are supported:
+- CLI (default): runs `bun dev generate` to emit the OpenAPI JSON
+- Server: fetches `http://localhost:4096/doc` from a running server
+
+Generator command
+```bash
+# From repo root
+uv run --project packages/sdk/python python packages/sdk/python/scripts/generate.py --source cli
+# Or
+uv run --project packages/sdk/python python packages/sdk/python/scripts/generate.py --source server --server-url http://localhost:4096/doc
+```
+
+Post-generation
+- The generator injects `extras.py` (OpenCodeClient) and patches `__init__.py` to export it
+- Code is formatted with `ruff` (imports) and `black`
diff --git a/packages/sdk/python/docs/index.md b/packages/sdk/python/docs/index.md
new file mode 100644
index 000000000..bc7b550f9
--- /dev/null
+++ b/packages/sdk/python/docs/index.md
@@ -0,0 +1,11 @@
+# Opencode Python SDK
+
+The official Python client for the Opencode API, generated from the OpenAPI spec and extended with ergonomic helpers.
+
+Highlights
+- Provider-agnostic client generated from OpenAPI 3.1
+- Thin convenience wrapper (OpenCodeClient) for common tasks
+- Sync and async SSE streaming for live event feeds
+- First-class uv support for development
+
+If you're new, start with Quickstart or Installation in the navigation.
diff --git a/packages/sdk/python/docs/installation.md b/packages/sdk/python/docs/installation.md
new file mode 100644
index 000000000..f66e217ae
--- /dev/null
+++ b/packages/sdk/python/docs/installation.md
@@ -0,0 +1,27 @@
+# Installation
+
+Requirements
+- Python 3.8+
+- uv (recommended) -> https://docs.astral.sh/uv/
+
+Install uv
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Project setup
+```bash
+# From repo root or this directory
+uv sync --dev --project packages/sdk/python
+```
+
+Using pip (alternative)
+```bash
+pip install opencode-ai
+```
+
+Preview docs locally
+```bash
+# From repo root
+uv run --project packages/sdk/python mkdocs serve -f packages/sdk/python/mkdocs.yml
+```
diff --git a/packages/sdk/python/docs/publishing.md b/packages/sdk/python/docs/publishing.md
new file mode 100644
index 000000000..c598baa88
--- /dev/null
+++ b/packages/sdk/python/docs/publishing.md
@@ -0,0 +1,24 @@
+# Publishing (maintainers)
+
+Automated publishing runs on GitHub Releases.
+
+Workflow
+- Create a new Release (the tag value becomes the package version)
+- The `publish-python-sdk` workflow will:
+  - Generate the SDK from OpenAPI (CLI path)
+  - Set the version in `pyproject.toml` and generator config
+  - Build wheel/sdist and upload to PyPI
+
+Prerequisites
+- Repository secret: `PYPI_API_TOKEN`
+
+Manual publish
+```bash
+# TestPyPI
+REPOSITORY=testpypi PYPI_TOKEN=$TEST_PYPI_API_TOKEN \
+uv run --project packages/sdk/python python packages/sdk/python/scripts/publish.py
+
+# PyPI
+REPOSITORY=pypi PYPI_TOKEN=$PYPI_API_TOKEN \
+uv run --project packages/sdk/python python packages/sdk/python/scripts/publish.py
+```
diff --git a/packages/sdk/python/docs/quickstart.md b/packages/sdk/python/docs/quickstart.md
new file mode 100644
index 000000000..97465c203
--- /dev/null
+++ b/packages/sdk/python/docs/quickstart.md
@@ -0,0 +1,22 @@
+# Quickstart
+
+Create a client and make your first calls.
+
+```python
+from opencode_ai import OpenCodeClient
+
+client = OpenCodeClient(base_url="http://localhost:4096")
+
+# List projects
+for p in client.list_projects() or []:
+    print(p.id, p.directory)
+
+# Get path info
+path = client.get_path()
+print(path.directory)
+
+# Stream events (sync)
+for event in client.subscribe_events():
+    print(event)
+    break
+```
diff --git a/packages/sdk/python/docs/testing.md b/packages/sdk/python/docs/testing.md
new file mode 100644
index 000000000..3119035d0
--- /dev/null
+++ b/packages/sdk/python/docs/testing.md
@@ -0,0 +1,15 @@
+# Testing
+
+Run unit, mock, and integration tests.
+
+```bash
+# Sync dev dependencies
+uv sync --dev --project packages/sdk/python
+
+# Run tests
+uv run --project packages/sdk/python pytest -q
+```
+
+Notes
+- Integration test starts a headless opencode server via Bun in a subprocess
+- SSE behavior is validated using real streaming from the server
diff --git a/packages/sdk/python/docs/usage/configuration.md b/packages/sdk/python/docs/usage/configuration.md
new file mode 100644
index 000000000..f5e0c60bb
--- /dev/null
+++ b/packages/sdk/python/docs/usage/configuration.md
@@ -0,0 +1,21 @@
+# Configuration
+
+OpenCodeClient accepts common options for auth, timeouts, and retries.
+
+```python
+from opencode_ai import OpenCodeClient
+
+client = OpenCodeClient(
+    base_url="http://localhost:4096",
+    token="pypi-or-other-token",
+    auth_header_name="Authorization",
+    auth_prefix="Bearer",
+    timeout=30.0,  # seconds
+    retries=2,
+    backoff_factor=0.2,  # exponential backoff
+)
+```
+
+- Auth: sets the header `{auth_header_name}: {auth_prefix} {token}` when `token` is provided
+- Retries: retry on transient httpx.RequestError and 429/5xx
+- Timeouts: passed to httpx.Timeout
diff --git a/packages/sdk/python/docs/usage/files_projects.md b/packages/sdk/python/docs/usage/files_projects.md
new file mode 100644
index 000000000..47f255e5a
--- /dev/null
+++ b/packages/sdk/python/docs/usage/files_projects.md
@@ -0,0 +1,22 @@
+# Files & Projects
+
+Access file status and project information.
+
+```python
+from opencode_ai import OpenCodeClient
+
+client = OpenCodeClient()
+
+# Projects
+for p in client.list_projects() or []:
+    print(p.id, p.directory)
+
+# Current path
+pinfo = client.get_path()
+print(pinfo.directory)
+
+# File status
+files = client.file_status() or []
+for f in files:
+    print(f.path, f.type)
+```
diff --git a/packages/sdk/python/docs/usage/sessions.md b/packages/sdk/python/docs/usage/sessions.md
new file mode 100644
index 000000000..61f5b9889
--- /dev/null
+++ b/packages/sdk/python/docs/usage/sessions.md
@@ -0,0 +1,18 @@
+# Sessions
+
+List sessions and inspect them. The wrapper exposes a convenience method while the generated API remains available under `opencode_ai.api.default`.
+
+```python
+from opencode_ai import OpenCodeClient
+from opencode_ai.api.default import session_list as generated
+
+client = OpenCodeClient()
+
+# Wrapper
+sessions = client.list_sessions() or []
+
+# Generated function
+sessions2 = generated.sync(client=client.client)
+
+print(len(sessions), len(sessions2))
+```
diff --git a/packages/sdk/python/docs/usage/streaming.md b/packages/sdk/python/docs/usage/streaming.md
new file mode 100644
index 000000000..31066e8de
--- /dev/null
+++ b/packages/sdk/python/docs/usage/streaming.md
@@ -0,0 +1,29 @@
+# Streaming (SSE)
+
+Subscribe to the event stream. The wrapper provides both sync and async interfaces.
+
+```python
+from opencode_ai import OpenCodeClient
+
+client = OpenCodeClient()
+
+# Sync streaming
+for event in client.subscribe_events():
+    print(event)
+    break
+```
+
+Async variant:
+
+```python
+import asyncio
+from opencode_ai import OpenCodeClient
+
+async def main():
+    client = OpenCodeClient()
+    async for event in client.subscribe_events_async():
+        print(event)
+        break
+
+asyncio.run(main())
+```