1 files changed, 82 insertions, 0 deletions
diff --git a/packages/sdk/python/README.md b/packages/sdk/python/README.md
new file mode 100644
index 000000000..a17c36ab3
--- /dev/null
+++ b/packages/sdk/python/README.md
@@ -0,0 +1,82 @@
+# Opencode Python SDK
+
+This package provides a Python SDK for the Opencode API. It is generated using openapi-python-client (not Stainless).
+
+
+Documentation
+- Full docs: see `mkdocs` site under `packages/sdk/python/docs/`
+- Preview locally:
+```bash
+uv run --project packages/sdk/python mkdocs serve -f packages/sdk/python/mkdocs.yml
+```
+
+Badges
+- PyPI: https://img.shields.io/pypi/v/opencode-ai?style=flat-square
+
+Requirements
+- Python 3.8+
+- uv (recommended) -> https://docs.astral.sh/uv/
+- openapi-python-client (invoked via `uvx`)
+
+Install uv
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Set up the environment (from this directory)
+```bash
+uv sync --dev
+```
+
+Generate client code (from CLI-generated spec)
+```bash
+# From repository root OR from this directory
+uv run python packages/sdk/python/scripts/generate.py --source cli
+```
+
+Alternatively, fetch spec from a running server
+```bash
+uv run python packages/sdk/python/scripts/generate.py --source server --server-url http://localhost:4096/doc
+```
+
+This will:
+1) Produce an OpenAPI spec from the local CLI or a running server
+2) Run openapi-python-client (via `uvx`) to generate client code
+3) Copy the generated Python package into src/opencode_ai
+
+Usage (after generation)
+```python
+from opencode_ai import OpenCodeClient
+
+client = OpenCodeClient(base_url="http://localhost:4096")
+print(client.get_config())
+
+# See examples/basic_usage.py for more details
+
+# Streaming events (sync)
+for event in client.subscribe_events():
+    print(event)
+    break
+
+# Error handling and retries
+# Set retries>0 to enable exponential backoff for transient errors like 429/5xx
+client = OpenCodeClient(retries=2, backoff_factor=0.1)
+
+# Async usage example
+# uv run --project packages/sdk/python python - <<'PY'
+# 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())
+# PY
+```
+
+Notes
+- We intentionally do not use Stainless for the Python SDK.
+- The generator targets OpenAPI 3.1 emitted by the opencode server at /doc.
+- See scripts/generate.py for details and customization points.