opencode-ide-plugin/packages/sdk/python/README.md

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:

  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

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Set up the environment (from this directory)

uv sync --dev

Generate client code (from CLI-generated spec)

# 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

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)

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.