opencode-py 0.2.1__tar.gz → 0.3.0__tar.gz

opencode_py-0.3.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+## v0.3.0 (2026-07-05)
+
+- feat(client): add typed Pydantic response models (`cast_to`) to all ~75 client methods
+- feat(client): add 30+ response model classes (AgentResponse, CommandResponse, ConfigResponse, FileNode, FindMatch, VcsInfo, PtyResponse, WorktreeResponse, WorkspaceResponse, etc.)
+- feat(client): `_construct_type` handles generic `list[X]` via `get_origin/get_args` and `{"data": [...]}` response format
+- fix(client): `AgentResponse.permission` changed from `dict` to `Any` (server returns list)
+- fix(scripts): resolve mypy `no-any-return` in check-upstream.py
+- fix(docs): correct web UI port in VERIFY.md (3000, not 8000)
+- fix(tests): import SessionMessage from `_models`, not `_session`
+- chore(lint): suppress N815 camelCase warnings for `_response_models.py`
+- chore(docs): add VERIFY.md release checklist
+
+## v0.2.2 (2026-07-04)
+
+- docs: comprehensive README documentation in EN and RU (CLI flags, structured output, session methods, error hierarchy, ToolExecutor, binary management, OpencodeServer, config reference, async API, response models)
+- fix(demo): Pydantic model compatibility
+- fix(scripts): mypy errors in check-upstream.py
+- docs(readme): clarify binary auto-download behavior (NOT system-wide, NOT in PATH)
+
+## v0.2.1 (2026-07-04)
+
+- fix: rename entry point to `opencode-py` to avoid conflict with the real `opencode` binary
+
+## v0.2.0 (2026-07-03)
+
+- feat: Pydantic response models (HealthResponse, SessionResponse, FileContentResponse, V1SessionResponse)
+- feat: retry logic with exponential backoff and jitter
+- feat: typed error hierarchy (15+ classes)
+- feat: logging via OPENCODE_LOG env var
+- feat: async full support (AsyncOpendcodeClient, AsyncSession, AsyncOpendcode)
+- feat: streaming (ask_stream sync + async)
+- feat: auto_tools mode with ToolExecutor and permissions
+- feat: web UI with proxy server (zero dependencies)
+- feat: structured output (format parameter)
+- feat: OpencodeServer lifecycle management
+- feat: binary auto-download (PATH → ~/.opencode/bin/ → GitHub)
+- feat: check-upstream.py script for monitoring openapi.json changes
+- feat: `.copy()` / `.with_options()` for immutable client cloning
+- feat: py.typed marker for PEP 561 compliance
+
+## v0.1.1 (2026-07-03)
+
+- chore: add keywords to pyproject.toml and .gitattributes
+- docs: add badges to README and MIT license file
+- feat(tests): add Docker smoke test for clean-machine scenario
+- chore: use importlib.metadata for `__version__`
+- chore: bump version to 0.1.1 for author/URLs fix
+- fix(publish): set author to Sergey Kislyakov, fix URLs
+
+## v0.1.0 (2026-06-30)
+
+- feat: initial Python SDK for Opencode
+- fix: resolve npm .cmd wrappers to real .exe binary on Windows
+- fix(session): use V1 sync prompt with model support instead of V2
+- feat(sdk): add keep parameter for multi-turn conversations
+- feat(sdk): add auto_tools mode with ToolExecutor and permissions
+- feat(web): add zero-dependency web UI with proxy server
+- feat(async): add AsyncOpendcodeClient, AsyncSession, AsyncOpendcode
+- feat(stream): add live_streaming.py, SSE streaming via ask_stream
+- feat(sdk): add async_opencode, structured output, check-upstream

opencode_py-0.3.0/PKG-INFO

@@ -0,0 +1,502 @@
+Metadata-Version: 2.4
+Name: opencode-py
+Version: 0.3.0
+Summary: Python SDK for Opencode — the open source AI coding agent
+Project-URL: Homepage, https://github.com/skislyakow/opencode-py
+Project-URL: Repository, https://github.com/skislyakow/opencode-py
+Project-URL: Documentation, https://github.com/skislyakow/opencode-py
+Project-URL: Changelog, https://github.com/skislyakow/opencode-py/blob/main/CHANGELOG.md
+Author-email: Sergey Kislyakov <s.kislyakov84@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,coding-agent,llm,opencode,python-sdk,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Opencode Python SDK
+
+<p align="center">
+  <a href="https://pypi.org/project/opencode-py/"><img src="https://img.shields.io/pypi/v/opencode-py" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/opencode-py/"><img src="https://img.shields.io/pypi/pyversions/opencode-py" alt="Python versions"></a>
+  <a href="https://github.com/skislyakow/opencode-py/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/opencode-py" alt="License"></a>
+  <a href="https://pypi.org/project/opencode-py/"><img src="https://img.shields.io/pypi/dm/opencode-py" alt="Downloads"></a>
+  <a href="https://github.com/skislyakow/opencode-py/actions/workflows/test.yml"><img src="https://github.com/skislyakow/opencode-py/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
+  <img src="https://img.shields.io/badge/build-hatchling-4051b5" alt="Hatchling">
+  <img src="https://img.shields.io/badge/http-httpx-blue" alt="httpx">
+  <img src="https://img.shields.io/badge/models-pydantic-E92063" alt="pydantic">
+</p>
+
+Python SDK for [Opencode](https://opencode.ai) — the open source AI coding agent.
+
+```bash
+pip install opencode-py
+```
+
+**Do I need Opencode pre-installed?** No. The SDK automatically downloads the
+`opencode` binary for your OS (Windows/macOS/Linux, x64/arm64) on first use to
+`~/.opencode/bin/`. The binary is only used internally by the SDK — it is NOT
+added to PATH, NOT registered system-wide, and NOT shown in the Start Menu.
+
+**What if I install the official Opencode later?** If you install Opencode
+via `npm install -g opencode-ai` or another method, the SDK will use the
+PATH version instead — no conflict.
+
+*See [Binary management](#binary-management) for details.*
+
+## CLI
+
+After installation, the `opencode-py` command is available **system-wide** from any directory:
+
+```bash
+opencode-py "What is the capital of France?"   # one-shot prompt
+echo "What is the capital of France?" | opencode-py  # via pipe
+opencode-py --help                              # show all options
+```
+
+All CLI flags:
+
+| Flag | Description |
+|------|-------------|
+| `prompt` (positional) | Prompt text or read from stdin |
+| `--model` / `-m` | Model name (e.g. `opencode/big-pickle`) |
+| `--keep` / `-k` | Keep session alive between calls |
+| `--auto-tools` | Enable agentic tool execution |
+| `--directory` / `-d` | Working directory |
+| `--port` / `-p` | Server port (default: 4096) |
+
+You can also use `python -m opencode`:
+
+```bash
+python -m opencode "Explain dependency injection"
+python -m opencode --model "opencode/big-pickle" "Hello"
+```
+
+## Client library reference
+
+### One-shot (spawns server, asks, cleans up)
+
+```python
+from opencode import opencode
+
+answer = opencode("What is the capital of France?")
+print(answer)
+```
+
+### Context manager (recommended)
+
+```python
+from opencode import Opencode
+
+with Opencode() as ai:
+    answer = ai.ask("Explain dependency injection")
+    print(answer)
+```
+
+### Streaming
+
+```python
+with Opencode() as ai:
+    for chunk in ai.ask_stream("Write a Python function"):
+        print(chunk, end="")
+```
+
+### Conversations
+
+```python
+with Opencode() as ai:
+    session = ai.create_session()
+    msg1 = session.prompt("Suggest a project name")
+    print(f"AI: {msg1}")
+    msg2 = session.prompt("Now write a tagline for it")
+    print(f"AI: {msg2}")
+```
+
+### Session methods
+
+Every `Session` object provides additional methods:
+
+```python
+with Opencode() as ai:
+    session = ai.create_session()
+    session.prompt("Hello")
+
+    # Get conversation history
+    ctx = session.context()        # list of all messages
+    msgs = session.messages()      # paginated message list
+
+    # Control
+    session.abort()                # abort current generation
+    session.compact()              # compact conversation
+    session.fork()                 # fork into new session
+
+    # Inspect
+    session.diff()                 # file changes made by AI
+    session.todo()                 # remaining TODOs
+```
+
+### Multi-turn (keep mode)
+
+Reuses server and session across calls:
+
+```python
+from opencode import opencode
+
+r1 = opencode("My name is Alice", keep=True)
+r2 = opencode("What's my name?", keep=True)   # remembers conversation
+r3 = opencode("That's all", keep=False)        # closes server
+
+# Also accepts: model, format, port, directory, config, agent
+```
+
+### Auto-tools (agentic tool execution)
+
+```python
+r = opencode("Create a file called hello.txt", auto_tools=True)
+```
+
+Available tools: `bash`, `write`, `edit`, `read`, `glob`, `grep`.
+
+By default `bash` asks for permission in the console, all others run without prompting.
+
+Custom permissions via `Session.ask()`:
+
+```python
+from opencode import Opencode, ToolExecutor
+
+with Opencode() as ai:
+    session = ai.create_session()
+    msg = session.ask(
+        "Write test.py with print('hello')",
+        tool_executor=ToolExecutor(
+            permissions={"write": "allow"},
+            workdir="/path/to/sandbox",      # restrict file operations
+        ),
+        max_tool_rounds=25,                    # safety limit
+        quiet=True,                            # suppress tool logs
+    )
+```
+
+The first AI response in `ask()` enters plan mode — the SDK auto-confirms with
+`"Exit plan mode and proceed"` to make the model execute tools immediately.
+
+### Low-level client (any endpoint)
+
+```python
+with Opencode() as ai:
+    content = ai.client.file_read("src/main.py")
+    diff = ai.client.vcs_diff("HEAD~3")
+    config = ai.client.config_get()
+    session = ai.client.session_create()
+    ai.client.v2_session_prompt(session.id, {"text": "Hello"})
+```
+
+All client methods return typed Pydantic models — IDE autocomplete,
+`.model_dump()`, `.model_dump_json()`.
+
+#### Connecting to an existing server
+
+Skip subprocess management by pointing at a running `opencode serve`:
+
+```python
+from opencode import OpencodeClient
+
+client = OpencodeClient(base_url="http://127.0.0.1:4096", directory=".")
+health = client.health()
+```
+
+```python
+from opencode import AsyncOpendcodeClient
+
+async with AsyncOpendcodeClient(base_url="http://127.0.0.1:4096") as client:
+    health = await client.health()
+```
+
+#### Cloning a client
+
+```python
+client2 = client.copy(base_url="http://other:4096", timeout=60.0)
+
+# Or via with_options:
+faster = client.with_options(timeout=10.0, max_retries=0)
+```
+
+### Retry & error handling
+
+Typed exception hierarchy. All errors are importable from `opencode`:
+
+```python
+from opencode import OpencodeClient, RateLimitError, InternalServerError
+
+client = OpencodeClient(max_retries=3)  # exponential backoff with jitter
+
+try:
+    health = client.health()
+    print(health.version)
+except RateLimitError:
+    print("too many requests — retried but failed")
+except InternalServerError:
+    print("server error")
+```
+
+Full error class hierarchy:
+
+| Class | HTTP status | When raised |
+|-------|-------------|-------------|
+| `OpencodeError` | — | Base for all SDK errors |
+| `APIConnectionError` | — | Network / connection failure |
+| `APITimeoutError` | — | Request timed out |
+| `APIResponseValidationError` | — | Response doesn't match schema |
+| `APIStatusError` | 4xx/5xx | Base for HTTP error responses |
+| `BadRequestError` | 400 | Malformed request |
+| `AuthenticationError` | 401 | Invalid or missing API key |
+| `PermissionDeniedError` | 403 | Access denied |
+| `NotFoundError` | 404 | Resource not found |
+| `ConflictError` | 409 | Resource conflict |
+| `UnprocessableEntityError` | 422 | Validation error in request body |
+| `RateLimitError` | 429 | Rate limit exceeded |
+| `InternalServerError` | 500+ | Server-side error |
+| `BinaryNotFoundError` | — | `opencode` binary not on PATH |
+| `ServerStartupTimeoutError` | — | Server didn't start in time |
+
+Retry policy: 408, 409, 429, 5xx and timeouts are retried with exponential
+backoff + jitter. `Retry-After` and `retry-after-ms` headers are respected.
+
+### Structured output
+
+```python
+with Opencode(model="anthropic/claude-sonnet-4") as ai:
+    result = ai.ask(
+        "Generate a user profile",
+        format={
+            "type": "json_schema",
+            "schema": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "age": {"type": "integer"},
+                },
+                "required": ["name", "age"],
+            },
+        },
+    )
+    # result is a JSON string matching the schema
+```
+
+Works with `opencode()`, `async_opencode()`, `Session.prompt()`, and `Session.ask()`.
+
+Requires a model that supports `tool_choice="required"` (Claude, GPT-4).
+The free `opencode/big-pickle` (DeepSeek) does NOT support this.
+
+### Debug logging
+
+```bash
+# Linux / macOS (bash/zsh)
+OPENCODE_LOG=debug python my_script.py
+
+# Windows (PowerShell)
+$env:OPENCODE_LOG="debug"; python my_script.py
+
+# Windows (cmd)
+set OPENCODE_LOG=debug && python my_script.py
+```
+
+Shows all HTTP requests/responses with timing.
+
+### Web UI (zero dependencies)
+
+```bash
+python web/server.py
+# → open http://127.0.0.1:3000
+```
+
+Built-in HTTP server + proxy to `opencode serve` — no extra dependencies.
+
+### Interactive dialog
+
+```bash
+python live.py
+```
+
+Multi-turn dialog with `keep=True`, server cleaned up on exit via `atexit`.
+
+### ToolExecutor reference
+
+```python
+from opencode import ToolExecutor
+
+# Default permissions:
+#   bash → "ask"   (prompts in console)
+#   write → "allow"
+#   edit  → "allow"
+#   read  → "allow"
+#   glob  → "allow"
+#   grep  → "allow"
+
+executor = ToolExecutor(
+    permissions={
+        "bash": "allow",      # always allow
+        "write": "deny",       # always deny
+        "grep": "ask",         # ask each time
+    },
+    workdir="/path/to/sandbox",  # restrict file operations here
+    confirm=lambda name, inp: name != "bash",  # custom confirm function
+)
+
+# Use with Session.ask():
+session.ask("Create a project", tool_executor=executor)
+```
+
+### Binary management
+
+When `opencode` is not on PATH, the SDK auto-downloads it to
+`~/.opencode/bin/opencode`.
+
+Resolution order:
+1. `PATH` — `shutil.which("opencode")`
+2. `~/.opencode/bin/opencode` — previously downloaded copy
+3. GitHub releases — download for current platform
+
+Supported platforms: `win32-x64`, `win32-arm64`, `darwin-x64`, `darwin-arm64`,
+`linux-x64`, `linux-arm64`.
+
+Override the binary path directly:
+
+```python
+with Opencode(opencode_binary="/custom/path/opencode") as ai:
+    ...
+```
+
+### OpencodeServer (low-level server control)
+
+```python
+from opencode import OpencodeServer, create_opencode_server
+
+server = create_opencode_server(
+    port=4096,
+    hostname="127.0.0.1",
+    timeout=30.0,
+    config={"model": "opencode/big-pickle"},
+    opencode_binary="/path/to/opencode",
+)
+print(server.url)  # "http://127.0.0.1:4096"
+
+# Later:
+server.close()  # kills the subprocess
+```
+
+## Configuration reference
+
+All parameters for `Opendcode()` / `AsyncOpendcode()`:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `model` | `None` | Model name, e.g. `"opencode/big-pickle"` or `"provider/model"` |
+| `hostname` | `"127.0.0.1"` | Bind address for the server |
+| `port` | `4096` | Port for the server |
+| `directory` | `None` | Working directory passed to all API calls |
+| `workspace` | `None` | Workspace directory for the session |
+| `server_timeout` | `30.0` | Seconds to wait for server startup |
+| `client_timeout` | `300.0` | Seconds before HTTP request timeout |
+| `config` | `None` | Server config dict (see opencode docs) |
+| `opencode_binary` | `None` | Path to opencode binary (auto-downloaded if not set) |
+
+All parameters are keyword-only.
+
+## Async API
+
+### Basic
+
+```python
+import asyncio
+from opencode import AsyncOpendcode
+
+async def main():
+    async with AsyncOpendcode() as ai:
+        answer = await ai.ask("Explain async/await in Python")
+        print(answer)
+
+asyncio.run(main())
+```
+
+### Async streaming
+
+```python
+async with AsyncOpendcode() as ai:
+    async for chunk in ai.ask_stream("Write a poem"):
+        print(chunk, end="")
+```
+
+### Async conversations
+
+```python
+async with AsyncOpendcode() as ai:
+    session = await ai.create_session()
+    msg1 = await session.prompt("Suggest a project name")
+    msg2 = await session.prompt("Now write a tagline for it")
+```
+
+### Async low-level client
+
+```python
+from opencode import AsyncOpendcodeClient
+
+async with AsyncOpendcodeClient() as client:
+    health = await client.health()
+    print(health.version)  # typed Pydantic model
+```
+
+### Async convenience function
+
+```python
+from opencode import async_opencode
+
+result = await async_opencode("Hello", keep=True)
+result2 = await async_opencode("Still there?", keep=True)
+result3 = await async_opencode("Bye")
+
+# Also accepts: model, format, port, directory, config, agent, auto_tools
+```
+
+## OpenAPI response models
+
+```python
+from opencode._response_models import HealthResponse, SessionResponse, FileContentResponse
+
+# These are Pydantic BaseModel classes with:
+#   .model_dump() -> dict
+#   .model_dump_json() -> str
+#   .model_validate(dict) -> classmethod
+```
+
+## Development
+
+```bash
+# Install in editable mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Build
+python -m build --wheel
+```