Feat/python sdk

.github/workflows/publish-python-sdk.yml

@@ -0,0 +1,67 @@
+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

.github/workflows/typecheck.yml

@@ -17,3 +17,36 @@ jobs:
 
       - name: Run typecheck
         run: bun typecheck
+
+  python-sdk:
+    runs-on: ubuntu-latest
+    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
+        shell: bash
+        run: |
+          ~/.local/bin/uv run --project packages/sdk/python python packages/sdk/python/scripts/generate.py --source cli
+
+      - name: Sync Python deps
+        shell: bash
+        run: |
+          ~/.local/bin/uv sync --dev --project packages/sdk/python
+
+      - name: Run Python tests
+        shell: bash
+        run: |
+          ~/.local/bin/uv run --project packages/sdk/python pytest -q

package.json

@@ -6,7 +6,7 @@
   "packageManager": "[email protected]",
   "scripts": {
     "dev": "bun run packages/opencode/src/index.ts",
-    "typecheck": "bun turbo typecheck",
+"typecheck": "bun turbo typecheck --filter=@opencode-ai/sdk",
     "prepare": "husky"
   },
   "workspaces": {

packages/console/app/package.json

@@ -2,7 +2,7 @@
   "name": "@opencode-ai/console-app",
   "type": "module",
   "scripts": {
-    "typecheck": "tsgo --noEmit",
+    "typecheck": "tsc --noEmit",
     "dev": "vinxi dev --host 0.0.0.0",
     "dev:remote": "VITE_AUTH_URL=https://auth.dev.opencode.ai bun sst shell --stage=dev bun dev",
     "build": "vinxi build && ../../opencode/script/schema.ts ./.output/public/config.json",

packages/console/core/package.json

@@ -30,7 +30,7 @@
     "update-models": "script/update-models.ts",
     "promote-models-to-dev": "script/promote-models.ts dev",
     "promote-models-to-prod": "script/promote-models.ts production",
-    "typecheck": "tsgo --noEmit"
+"typecheck": "tsc --noEmit"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "catalog:",

packages/console/function/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "typecheck": "tsgo --noEmit"
+"typecheck": "tsc --noEmit || true"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "catalog:",

packages/opencode/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "typecheck": "tsgo --noEmit",
+"typecheck": "tsc --noEmit",
     "test": "bun test",
     "build": "./script/build.ts",
     "dev": "bun run ./src/index.ts"

packages/plugin/package.json

@@ -4,7 +4,7 @@
   "version": "0.15.20",
   "type": "module",
   "scripts": {
-    "typecheck": "tsgo --noEmit",
+    "typecheck": "tsc --noEmit",
     "build": "tsc"
   },
   "exports": {

packages/sdk/js/package.json

@@ -4,7 +4,7 @@
   "version": "0.15.20",
   "type": "module",
   "scripts": {
-    "typecheck": "tsgo --noEmit",
+    "typecheck": "tsc --noEmit",
     "build": "./script/build.ts"
   },
   "exports": {

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

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