opencode-py 0.1.0__tar.gz

opencode_py-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/opencode-py/
+
+    permissions:
+      contents: read
+      id-token: write  # for Trusted Publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

opencode_py-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Test
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Run unit tests
+        run: pytest tests/ -v

opencode_py-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.egg
+.pytest_cache/

opencode_py-0.1.0/AGENTS.md

@@ -0,0 +1,335 @@
+# Opencode Python SDK — AGENTS.md
+
+## Project Overview
+
+Python SDK for [Opencode](https://opencode.ai) — a PyPI package (`opencode-py`) that launches an `opencode serve` subprocess and provides both high-level and low-level APIs.
+
+**Current version**: 0.1.0 (unreleased)
+**Python**: >=3.10
+**Dependencies**: only `httpx>=0.27.0`
+**Build**: hatchling
+
+## Repository
+
+- `C:\Code\opencode-py\` (local)
+- GitHub: https://github.com/[user]/opencode-py
+- Upstream opencode: https://github.com/anomalyco/opencode
+  - OpenAPI spec: `packages/sdk/openapi.json` (committed)
+  - Raw URL: `https://raw.githubusercontent.com/anomalyco/opencode/dev/packages/sdk/openapi.json`
+  - Local copy of this repo: `C:\Code\opencode\`
+
+## File Structure
+
+```
+opencode-py/
+├── src/opencode/
+│   ├── __init__.py            # Public API exports
+│   ├── __main__.py            # python -m opencode "question"
+│   ├── _opencode.py           # Opencode class + opencode() convenience fn
+│   ├── _async_opencode.py     # AsyncOpendcode class + async_opencode()
+│   ├── _client.py             # OpencodeClient — sync REST (528 lines)
+│   ├── _async_client.py       # AsyncOpendcodeClient — async REST
+│   ├── _server.py             # OpencodeServer — subprocess lifecycle
+│   ├── _session.py            # Session — sync conversation management
+│   ├── _async_session.py      # AsyncSession — async conversation management
+│   ├── _binary.py             # Binary find in PATH + GitHub download
+│   ├── _process.py            # Cross-platform process termination
+│   ├── _models.py             # TypedDict types (OutputFormatJsonSchema, etc.)
+│   ├── _tools.py              # ToolExecutor — run tools locally with permissions
+│   └── _errors.py             # OpencodeError, ApiError, BinaryNotFound
+├── tests/
+│   ├── test_client.py         # 11 unit tests (sync, httpx MockTransport)
+│   ├── test_async_client.py   # 11 unit tests (async, httpx MockTransport)
+│   └── test_opencode.py       # 9 tests (resolve_model, keep, structured, format)
+├── scripts/
+│   └── check-upstream.py      # Compare openapi.json with upstream GitHub
+├── demo.py                    # Live demo (38 endpoint checks)
+├── live.py                    # Interactive multi-turn dialog (sync)
+├── live_async.py              # Interactive multi-turn dialog (async)
+├── live_streaming.py          # Streaming interactive dialog
+├── test_live.py               # Live integration test
+├── web/
+│   ├── server.py              # Start opencode + proxy for web UI
+│   └── index.html             # Chat interface (vanilla JS)
+├── AGENTS.md                  # This file
+├── README.md
+├── README.ru.md
+├── pyproject.toml
+├── .gitignore
+└── docs/
+    └── opencode-docs-ru.md    # Russian docs from opencode.ai
+```
+
+## Current State (commit history)
+
+```
+ad54a39 feat(web): add zero-dependency web UI with proxy server
+b8d205f feat(sdk): add auto_tools mode with ToolExecutor and permissions
+2fd170c docs: update AGENTS.md with keep mode and live.py
+67ae119 feat(sdk): add keep parameter for multi-turn conversations
+514b0a2 fix(session): use V1 sync prompt with model support instead of V2
+4323247 fix: resolve npm .cmd wrappers to real .exe binary on Windows
+fb4b884 feat: initial Python SDK for Opencode
+```
+
+### What works
+- Server starts/stops via subprocess (`opencode serve`)
+- Binary auto-detection: PATH -> `~/.opencode/bin/` -> GitHub download
+- Full REST API coverage (V1 + V2):
+  - Global, config, sessions, files, VCS, find, MCP, auth, providers, models, LSP, formatter, tools, permissions, questions, PTY, worktree, workspace, sync, TUI
+- Session prompt via V1 sync API (V2 `v2_session_wait` is broken, replaced with V1 `POST /session/:id/message`)
+- `Opencode(config={"model": "opencode/big-pickle"}).ask("...")` — works end-to-end with free model
+- `opencode(prompt, keep=True)` — multi-turn conversation in same session
+- `opencode(prompt, auto_tools=True)` — agentic tool execution (bash, write, edit, read, glob, grep) with permission system
+- `async_opencode(prompt, keep=True)` — async version of `opencode()`
+- Structured output — `format={"type": "json_schema", "schema": {...}}` on `ask()` / `prompt()` / `opencode()`
+- Async full support — `AsyncOpendcode`, `AsyncOpendcodeClient`, `AsyncSession`
+- Streaming — `ask_stream()` (sync + async) via `/event` SSE, works with `big-pickle` (non-streaming model) and streaming models
+- `scripts/check-upstream.py` — fetches upstream openapi.json, flags needed changes
+- 38/38 live endpoints tested against opencode v1.17.13
+- 31/31 unit tests passing (sync + async)
+- Python 3.10 compatibility (`NotRequired` via `typing_extensions`)
+- `live.py` (sync), `live_async.py`, `live_streaming.py` — interactive dialog scripts with `atexit` cleanup
+
+### Known issues to fix
+
+1. **Delivery enum mismatch** — npm v1.17.13 uses `"steer"/"queue"`, but upstream `dev` branch source also uses `"steer"/"queue"`. The local clone (`C:\Code\opencode`) has been modified to use `"immediate"/"deferred"` but this is NOT yet upstream. When upstream switches, update `_client.py:delivery="queue"` and `_async_client.py` to `"deferred"`. Run `scripts/check-upstream.py` to monitor.
+
+2. ~~**Config format** — `Opencode(config={"model": "anthropic/..."})` fails because config expects `provider.{id}.options.apiKey` format.~~ **PARTIALLY RESOLVED**: The free `opencode` provider models work without API keys, but `OPENCODE_CONFIG_CONTENT={"model": "opencode/big-pickle"}` crashes the server with "ServeError" in v1.17.13. The model should be specified in the V1 prompt request body instead of server config. `Opencode` class works by passing `model` per-request, not via server config. **FIXED**: `opencode(model=...)` no longer puts model in server config — passes it per-request.
+
+3. **`v2_session_wait` broken** — `POST /api/session/{sessionID}/wait` returns "Session wait is not available yet" in v1.17.13. **FIXED**: `Session.prompt()` now polls `v2_session_context()` until an assistant message appears (see `_session.py:_poll_response`).
+
+4. ~~**No async support** — `OpencodeClient` is sync-only. `httpx.AsyncClient` not wired up.~~ **DONE**: `AsyncOpendcodeClient`, `AsyncSession`, `AsyncOpendcode`, `async_opencode()` all implemented.
+
+5. **Streaming** — `ask_stream()` reads SSE events via `/event` but delta format may differ between server versions.
+
+6. ~~**No upstream monitoring** — No script to compare local `openapi.json` with upstream.~~ **DONE**: `scripts/check-upstream.py` fetches upstream, checks delivery enum + structured output.
+
+## Architecture
+
+### Opencode (high-level, context manager)
+```
+Opencode.__enter__()
+  → OpencodeServer.start()          # subprocess: opencode serve --port=N
+  → OpencodeClient(base_url, ...)   # httpx client
+  → return self
+Opencode.ask(prompt)
+  → create_session()
+  → Session.prompt(text)
+    → v2_session_prompt(delivery="queue")  # send prompt
+    → v2_session_context()                  # poll until assistant message
+  → _extract_text(message)                  # extract text content
+Opencode.__exit__()
+  → OpencodeClient.close()
+  → OpencodeServer.close()          # taskkill /T /F (win32) or SIGTERM (unix)
+```
+
+### opencode() — convenience function with keep
+```
+_opencode_state = {"ai": ..., "session": ..., "config": ...}
+opencode(prompt, keep=True)
+  → reuse existing session.prompt(prompt)
+  → return _extract_text(msg)            # server stays alive
+opencode(prompt)            # keep=False by default
+  → Opencode.__enter__()
+  → create_session().prompt(prompt)
+  → _extract_text(msg)
+  → Opencode.__exit__()                  # server closed
+```
+When `keep=True`, state is reused across calls (same session, same server).
+Warns if different config/model passed. Clean up with `atexit` in scripts.
+
+### async_opencode() — async convenience function
+Identical to `opencode()` but uses `AsyncOpendcode` and `await`.
+Module-level `_async_opencode_state` for server/session reuse.
+```python
+r1 = await async_opencode("hello", keep=True)
+r2 = await async_opencode("what's my name?", keep=True)
+r3 = await async_opencode("bye")
+```
+
+### OpencodeClient (low-level)
+All HTTP methods follow the pattern:
+```
+_request("GET"|"POST"|"DELETE"|"PATCH", path, params, json_body)
+```
+with automatic `directory`/`workspace` query param injection via `_merge_params()`.
+
+### Correct API paths (OpenAPI spec)
+V2 session operations:
+```
+POST /api/session/{sessionID}/prompt    — send prompt
+POST /api/session/{sessionID}/wait      — wait for idle (204, BROKEN in v1.17.13)
+GET  /api/session/{sessionID}/context   — get context messages (used for polling)
+GET  /api/session/{sessionID}/message   — list messages (paginated)
+POST /api/session/{sessionID}/compact   — compact
+GET  /api/session                       — list sessions
+```
+
+All other endpoints use V1 paths (see AGENTS.md of the upstream repo or inline comments in `_client.py`).
+
+### Tool Execution
+```
+Session.ask(text, tool_executor=ToolExecutor())
+  → send user message (POST /session/:id/message)
+  → if tool-use parts: execute via ToolExecutor, send results, loop
+  → if no tool-use and not confirmed: auto-confirm "Exit plan mode"
+  → if no tool-use and confirmed: return text
+
+ToolExecutor:
+  - permissions: allow/ask/deny per tool
+  - default: bash=ask, others=allow
+  - tools: bash, write, edit, read, glob, grep
+```
+
+### Structured Output
+```
+prompt() / ask() / opencode() / async_opencode()
+  accept: format={"type": "json_schema", "schema": {...}, "retryCount": 2}
+  → body["format"] = format  (passed to V1 POST /session/:id/message)
+  → server injects StructuredOutput tool with toolChoice: "required"
+  → response may include "structured" field with parsed JSON
+  → _extract_text() returns JSON string when structured present
+
+Schema: opencode/big-pickle (DeepSeek) does NOT support tool_choice="required"
+        Need Claude/GPT-4 with API key.
+```
+
+## Binary Management
+
+```python
+# Resolution order:
+1. find_in_path() — shutil.which("opencode")
+   - On Windows: resolves .cmd wrappers to actual .exe via _resolve_wrapper()
+2. find_local()  — ~/.opencode/bin/opencode
+3. download_opencode() — GitHub releases
+```
+
+**Key Windows fix**: `shutil.which("opencode")` returns `opencode.cmd` (npm wrapper). `_resolve_wrapper()` reads the .cmd file and extracts the `.exe` path from the line `"%dp0%\node_modules\opencode-ai\bin\opencode.exe"`.
+
+Platform detection for download:
+- `win32-x64`, `win32-arm64`, `darwin-x64`, `darwin-arm64`, `linux-x64`, `linux-arm64`
+
+## Testing
+
+```bash
+# Install
+pip install -e ".[dev]"
+
+# Unit tests (no server needed)
+pytest tests/ -v
+
+# Check upstream openapi for changes
+python scripts/check-upstream.py
+
+# Live test (requires opencode in PATH or npm global install)
+python test_live.py
+
+# Demo
+python demo.py
+
+# Interactive dialog
+python live.py          # sync
+python live_async.py    # async
+python live_streaming.py
+
+# Web UI (zero deps, opens browser)
+python web/server.py
+```
+
+## Next Steps (priority order)
+
+### Step B: Test `ask()` with free model (Big Pickle) ✅ DONE
+1. Figure out correct config for free model usage
+   - Check `/api/provider` on running server for "big-pickle" or free providers
+   - Check if Big Pickle works without any API key/config
+2. Test `Session.prompt()` with delivery="queue" + `v2_session_wait()`
+3. Test `Opencode().ask()` end-to-end
+4. Fix any response parsing issues
+5. Add `keep=True` for multi-turn conversations in `opencode()` convenience function
+   - Module-level `_opencode_state` for server/session reuse
+   - `atexit` cleanup in `live.py`
+   - 6 unit tests for `keep` / `_resolve_model`
+
+### Step C: Publish v0.1.0 to PyPI
+1. ~~Create `scripts/check-upstream.py` — fetches openapi.json, diffs with local~~ ✅ DONE
+2. ~~Create GitHub Actions CI (tests on push)~~ ✅ DONE
+3. Publish to TestPyPI first, then PyPI
+   - `pip install build twine`
+   - `python -m build`
+   - `twine upload --repository testpypi dist/*` (check first)
+   - `twine upload dist/*`
+   - Or: push tag `v0.1.0` → GitHub Actions publishes via Trusted Publishing
+
+### Step D: Async support ✅ DONE
+1. `AsyncOpendcodeClient` using `httpx.AsyncClient` ✅
+2. `AsyncSession` with `async prompt()` ✅
+3. `AsyncOpendcode` with `async def ask()` ✅
+4. `async_opencode()` convenience function ✅
+5. 11 unit tests for async client ✅
+
+### Step E: Streaming improvements
+1. Better SSE parsing in `ask_stream()`
+2. Handle `message.part.delta` and `message.updated` events
+
+### Step F: Structured output ✅ DONE
+1. `format` parameter on `prompt()` / `ask()` / `opencode()` / `async_opencode()` ✅
+2. `_extract_text()` handles `structured` field ✅
+3. 3 unit tests ✅
+
+### Step G: Upstream monitoring ✅ DONE
+1. `scripts/check-upstream.py` checks delivery enum + structured output ✅
+
+## Style Guide
+
+- Keep in one function unless composable/reusable
+- No single-use helpers preemptively
+- Avoid try/except where possible
+- Prefer httpx over urllib/requests (HTTP client), except for `_binary.py` which uses `urllib.request` for download (stdlib, no extra deps)
+- Method naming: snake_case, category prefix (e.g., `v2_session_*`, `file_*`, `config_*`)
+- Type hints everywhere
+- Avoid `Any` where possible — use `TypedDict` from `_models.py`
+
+## Commit Convention
+
+```
+type(scope): summary
+```
+
+Types: feat, fix, docs, chore, refactor, test
+Always include package scope.
+
+Examples:
+```
+feat(server): add async context manager support
+fix(binary): resolve npm .cmd wrappers to real .exe on Windows
+refactor(client): extract error handling to _handle()
+```
+
+## Quick Reference for New Agent
+
+```
+# Setup
+git clone <repo>  # or cd C:\Code\opencode-py
+pip install -e ".[dev]"
+
+# Check opencode availability
+opencode serve --help           # should work
+python -c "from opencode._binary import ensure_opencode; print(ensure_opencode())"
+
+# Run live test
+python test_live.py
+
+# Run demo
+python demo.py
+
+# Try a simple interactive test
+python -c "
+from opencode import OpencodeClient, create_opencode_server
+s = create_opencode_server(port=4097)
+c = OpencodeClient(base_url=s.url)
+print('Health:', c.health())
+c.close()
+s.close()
+"
+```

opencode_py-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: opencode-py
+Version: 0.1.0
+Summary: Python SDK for Opencode — the open source AI coding agent
+Project-URL: Homepage, https://opencode.ai
+Project-URL: Repository, https://github.com/anomalyco/opencode
+Project-URL: Documentation, https://opencode.ai/docs
+Author-email: Anomaly <hello@opencode.ai>
+License: MIT
+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.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
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Opencode Python SDK
+
+Python SDK for [Opencode](https://opencode.ai) — the open source AI coding agent.
+
+```bash
+pip install opencode-py
+```
+
+## Quick start
+
+### 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}")
+```
+
+### Multi-turn (keep mode)
+
+```python
+from opencode import opencode
+
+# keep=True — server and session stay alive between calls
+r1 = opencode("My name is Alice", keep=True)
+r2 = opencode("What's my name?", keep=True)   # remembers the conversation
+r3 = opencode("That's all", keep=False)        # keep=False closes the server
+```
+
+### 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"}),
+    )
+```
+
+### Low-level API (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"})
+```
+
+### 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`.
+
+### Configuration
+
+```python
+with Opencode(
+    model="claude-sonnet-4-20250514",
+    directory="/path/to/project",
+    port=4096,
+) as ai:
+    ...
+```
+
+## Async API
+
+```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)
+```
+
+## Development
+
+```bash
+# Install in editable mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Build
+python -m build --wheel
+```