ignore: python sdk (#2779)

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

Author: Kking112

.github/publish-python-sdk.yml

@@ -0,0 +1,71 @@
+#
+# This file is intentionally in the wrong dir, will move and add later....
+#
+
+# name: publish-python-sdk
+
+# on:
+#   release:
+#     types: [published]
+#   workflow_dispatch:
+
+# jobs:
+#   publish:
+#     runs-on: ubuntu-latest
+#     permissions:
+#       contents: read
+#     steps:
+#       - name: Checkout repository
+#         uses: actions/checkout@v4
+
+#       - name: Setup Bun
+#         uses: oven-sh/setup-bun@v1
+#         with:
+#           bun-version: 1.2.21
+
+#       - name: Install dependencies (JS/Bun)
+#         run: bun install
+
+#       - name: Install uv
+#         shell: bash
+#         run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+#       - name: Generate Python SDK from OpenAPI (CLI)
+#         shell: bash
+#         run: |
+#           ~/.local/bin/uv run --project packages/sdk/python python packages/sdk/python/scripts/generate.py --source cli
+
+#       - name: Sync Python dependencies
+#         shell: bash
+#         run: |
+#           ~/.local/bin/uv sync --dev --project packages/sdk/python
+
+#       - name: Set version from release tag
+#         shell: bash
+#         run: |
+#           TAG="${GITHUB_REF_NAME:-}"
+#           if [ -z "$TAG" ]; then
+#             TAG="$(git describe --tags --abbrev=0 || echo 0.0.0)"
+#           fi
+#           echo "Using version: $TAG"
+#           VERSION="$TAG" ~/.local/bin/uv run --project packages/sdk/python python - <<'PY'
+# import os, re, pathlib
+# root = pathlib.Path('packages/sdk/python')
+# pt = (root / 'pyproject.toml').read_text()
+# version = os.environ.get('VERSION','0.0.0').lstrip('v')
+# pt = re.sub(r'(?m)^(version\s*=\s*")[^"]+("\s*)$', f"\\1{version}\\2", pt)
+# (root / 'pyproject.toml').write_text(pt)
+# # Also update generator config override for consistency
+# cfgp = root / 'openapi-python-client.yaml'
+# if cfgp.exists():
+#     cfg = cfgp.read_text()
+#     cfg = re.sub(r'(?m)^(package_version_override:\s*)\S+$', f"\\1{version}", cfg)
+#     cfgp.write_text(cfg)
+# PY
+
+#       - name: Build and publish to PyPI
+#         env:
+#           PYPI_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+#         shell: bash
+#         run: |
+#           ~/.local/bin/uv run --project packages/sdk/python python packages/sdk/python/scripts/publish.py

packages/plugin/package.json

@@ -24,4 +24,4 @@
     "typescript": "catalog:",
     "@typescript/native-preview": "catalog:"
   }
-}
+}

packages/sdk/js/package.json

@@ -26,4 +26,4 @@
   "publishConfig": {
     "directory": "dist"
   }
-}
+}

packages/sdk/python/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.build/
+build/
+dist/
+.coverage
+htmlcov/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+.conda/
+.env
+.DS_Store
+openapi.json
+site/
+
+
+# IDE
+.vscode/
+.idea/

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.

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`

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.

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
+```

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
+```

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
+```