opencode-py 0.1.0__tar.gz → 0.2.0__tar.gz

opencode_py-0.2.0/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+indent_style = space
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

opencode_py-0.2.0/.gitattributes

@@ -0,0 +1,36 @@
+* text=auto eol=lf
+
+# Python
+*.py text
+*.pyi text
+*.pyw text
+
+# Markdown
+*.md text
+*.mdx text
+
+# Config
+*.toml text
+*.ini text
+*.cfg text
+*.yml text
+*.yaml text
+*.json text
+
+# Git
+.gitattributes text
+.gitignore text
+
+# Batch scripts (Windows needs CRLF)
+*.bat text eol=crlf
+*.cmd text eol=crlf
+
+# Shell scripts (must stay LF)
+*.sh text eol=lf
+
+# Binaries
+*.png binary
+*.jpg binary
+*.ico binary
+*.exe binary
+*.dll binary

opencode_py-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,29 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+labels: ["bug"]
+
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Minimal code or commands to reproduce.
+      render: python
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: |
+        - OS: [e.g. Windows 11, Ubuntu 22.04]
+        - Python version:
+        - opencode-py version:
+        - opencode version (if relevant):

opencode_py-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,26 @@
+name: Feature Request
+description: Suggest an idea for this project
+labels: ["enhancement"]
+
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How would you like it to work?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives
+      description: What alternatives have you considered?

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

@@ -0,0 +1,62 @@
+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: Lint with ruff
+        run: ruff check .
+
+      - name: Type check with mypy
+        run: mypy src/
+
+      - name: Run unit tests
+        run: pytest tests/ -v
+
+  integration-docker:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel
+        run: |
+          pip install build
+          python -m build --wheel
+
+      - name: Build Docker image
+        run: docker build -t opencode-py-test tests/docker/
+
+      - name: Run smoke test
+        run: |
+          docker run --rm \
+            -v "${{ github.workspace }}/dist:/dist" \
+            opencode-py-test \
+            bash -c "pip install /dist/*.whl && python test_smoke.py"

opencode_py-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        args: [src/]
+        additional_dependencies: [httpx]
+        pass_filenames: false

{opencode_py-0.1.0 → opencode_py-0.2.0}/AGENTS.md

@@ -4,9 +4,9 @@
 
 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)
+**Current version**: 0.2.0-dev
 **Python**: >=3.10
-**Dependencies**: only `httpx>=0.27.0`
+**Dependencies**: `httpx>=0.27.0`, `pydantic>=2.0.0`, `typing-extensions>=4.6.0`
 **Build**: hatchling
 
 ## Repository
@@ -23,20 +23,24 @@ Python SDK for [Opencode](https://opencode.ai) — a PyPI package (`opencode-py`
 ```
 opencode-py/
 ├── src/opencode/
-│   ├── __init__.py            # Public API exports
+│   ├── __init__.py            # Public API exports, calls setup_logging()
 │   ├── __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
+│   ├── _client.py             # OpencodeClient — sync REST (typed models, retry)
+│   ├── _async_client.py       # AsyncOpendcodeClient — async REST (typed models, retry)
 │   ├── _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.)
+│   ├── _models.py             # TypedDict types (SessionMessage, etc.)
+│   ├── _response_models.py    # Pydantic BaseModel response types (all endpoints)
+│   ├── _types.py              # NotGiven sentinel
+│   ├── _logs.py               # Logging via OPENCODE_LOG env var
 │   ├── _tools.py              # ToolExecutor — run tools locally with permissions
-│   └── _errors.py             # OpencodeError, ApiError, BinaryNotFound
+│   ├── _errors.py             # Typed exception hierarchy (10+ classes)
+│   └── py.typed               # PEP 561 marker for type checkers
 ├── tests/
 │   ├── test_client.py         # 11 unit tests (sync, httpx MockTransport)
 │   ├── test_async_client.py   # 11 unit tests (async, httpx MockTransport)
@@ -90,20 +94,26 @@ fb4b884 feat: initial Python SDK for Opencode
 - 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
+- **Pydantic response models** — `HealthResponse`, `SessionResponse`, `FileContentResponse`, `ProviderResponse`, `V1SessionResponse` and more
+- **Retry logic** — exponential backoff with jitter, retries on 408/409/429/5xx and timeouts
+- **Typed error hierarchy** — `APIStatusError` → `BadRequestError`, `RateLimitError`, `InternalServerError`, etc.
+- **Logging** — `OPENCODE_LOG=debug` enables httpx debug logging
+- **`py.typed` marker** — PEP 561 compliance for type checkers
+- **`copy()`/`with_options()`** — immutable client cloning with overrides
 
 ### 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.
+2. ~~**Config format** — `Opencode(config={"model": "anthropic/..."})` fails because config expects `provider.{id}.options.apiKey` format.~~ **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`).
+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.
 
-4. ~~**No async support** — `OpencodeClient` is sync-only. `httpx.AsyncClient` not wired up.~~ **DONE**: `AsyncOpendcodeClient`, `AsyncSession`, `AsyncOpendcode`, `async_opencode()` all implemented.
+4. ~~**No async support** — `OpencodeClient` is sync-only.~~ **DONE**: Full async support.
 
 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.
+6. ~~**No upstream monitoring**~~ **DONE**: `scripts/check-upstream.py` fetches upstream.
 
 ## Architecture
 
@@ -280,6 +290,44 @@ python web/server.py
 ### Step G: Upstream monitoring ✅ DONE
 1. `scripts/check-upstream.py` checks delivery enum + structured output ✅
 
+## Next Steps
+
+### Step H: Complete typed model coverage
+1. Add `cast_to` to remaining client methods (vcs, config, project, etc.)
+2. Add `with_raw_response` pattern for raw HTTP access
+3. Consider `model_construct()` for faster deserialization (skip validation)
+
+### Step I: Release v0.2.0
+1. Bump version in `pyproject.toml` to `0.2.0`
+2. Publish to PyPI via Trusted Publishing
+
+## Release Process
+
+Run `python scripts/check-release.py` to check if a new PyPI release is needed.
+The script compares the version in `pyproject.toml` with the latest git tag
+and reports unreleased commits.
+
+**Release checklist:**
+- [ ] `python scripts/check-release.py -v` — confirms release is due
+- [ ] `git log --oneline v0.2.0..HEAD` — review unreleased changes
+- [ ] Version bumped in `pyproject.toml`
+- [ ] CI green on master
+- [ ] `python -m build && twine check dist/*` — wheel is valid
+
+**Proactive behavior**: 
+- At the start of each session, I will run `python scripts/check-release.py`
+  automatically and alert you if a release is due (commits since last tag
+  without version bump).
+- **Before every commit**, I will check if the staged changes include anything
+  "user-facing" (feat, fix, refactor, or dependency changes — anything beyond
+  chore/docs/style). If there has been no version bump since the last tagged
+  release, I will warn you and ask whether to bump the version before
+  committing.
+
+### Step J: Compare with official SDK
+1. Evaluate `opencode-ai` (official Stainless SDK) for low-level layer
+2. Consider using their client as base with our high-level wrapper
+
 ## Style Guide
 
 - Keep in one function unless composable/reusable
@@ -288,7 +336,7 @@ python web/server.py
 - 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`
+- Avoid `Any` where possible — use Pydantic models from `_response_models.py`
 
 ## Commit Convention
 

opencode_py-0.2.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 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.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,63 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**s.kislyakov84@gmail.com**. All complaints will be reviewed and investigated
+promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

opencode_py-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+## Development setup
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Code style
+
+- Type hints everywhere
+- Avoid `Any` where possible — use `TypedDict` from `_models.py`
+- Avoid single-use helper functions
+- Prefer httpx over urllib/requests
+- Method naming: snake_case with category prefix (e.g., `v2_session_*`, `file_*`)
+- No comments unless absolutely necessary
+
+## Testing
+
+```bash
+# Unit tests (no server needed)
+pytest tests/ -v
+
+# Live integration test (requires opencode in PATH)
+python test_live.py
+```
+
+## Commit convention
+
+```
+type(scope): summary
+```
+
+Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`
+
+## Pre-commit checks
+
+Before committing, run:
+
+```bash
+ruff check .
+mypy src/
+pytest tests/ -v
+```

opencode_py-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergey Kislyakov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opencode_py-0.1.0/README.md → opencode_py-0.2.0/PKG-INFO

@@ -1,5 +1,51 @@
+Metadata-Version: 2.4
+Name: opencode-py
+Version: 0.2.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
@@ -88,9 +134,35 @@ with Opencode() as ai:
     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"})
+    ai.client.v2_session_prompt(session.id, {"text": "Hello"})
+```
+
+All client methods return typed Pydantic models — IDE autocomplete, validation, `.model_dump()`, `.model_dump_json()`.
+
+### Retry & error handling
+
+```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")
 ```
 
+### Debug logging
+
+```bash
+OPENCODE_LOG=debug python my_script.py
+```
+
+Shows all HTTP requests/responses with timing.
+
 ### Web UI (zero dependencies)
 
 ```bash
@@ -157,7 +229,7 @@ from opencode import AsyncOpendcodeClient
 
 async with AsyncOpendcodeClient() as client:
     health = await client.health()
-    print(health)
+    print(health.version)  # typed Pydantic model
 ```
 
 ## Development

opencode_py-0.1.0/PKG-INFO → opencode_py-0.2.0/README.md

@@ -1,32 +1,16 @@
-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
 
+<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
@@ -115,9 +99,35 @@ with Opencode() as ai:
     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"})
+    ai.client.v2_session_prompt(session.id, {"text": "Hello"})
+```
+
+All client methods return typed Pydantic models — IDE autocomplete, validation, `.model_dump()`, `.model_dump_json()`.
+
+### Retry & error handling
+
+```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")
 ```
 
+### Debug logging
+
+```bash
+OPENCODE_LOG=debug python my_script.py
+```
+
+Shows all HTTP requests/responses with timing.
+
 ### Web UI (zero dependencies)
 
 ```bash
@@ -184,7 +194,7 @@ from opencode import AsyncOpendcodeClient
 
 async with AsyncOpendcodeClient() as client:
     health = await client.health()
-    print(health)
+    print(health.version)  # typed Pydantic model
 ```
 
 ## Development