opencode-py 0.2.2__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.2.2 → opencode_py-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-py
-Version: 0.2.2
+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
@@ -52,6 +52,17 @@ Python SDK for [Opencode](https://opencode.ai) — the open source AI coding age
 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:

{opencode_py-0.2.2 → opencode_py-0.3.0}/README.md

@@ -17,6 +17,17 @@ Python SDK for [Opencode](https://opencode.ai) — the open source AI coding age
 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:

{opencode_py-0.2.2 → opencode_py-0.3.0}/README.ru.md

@@ -16,6 +16,17 @@ Python SDK для [Opencode](https://opencode.ai) — open source AI coding agen
 pip install opencode-py
 ```
 
+**Нужен ли предустановленный Opencode?** Нет. SDK автоматически скачивает
+бинарник `opencode` под вашу ОС (Windows/macOS/Linux, x64/arm64) при первом
+запуске в `~/.opencode/bin/`. Бинарник используется только внутри SDK — он
+НЕ добавляется в PATH, НЕ устанавливается системно и НЕ появляется в меню Пуск.
+
+**Что если позже установить официальный Opencode?** Если вы установите opencode
+через `npm install -g opencode-ai` или другим способом, SDK будет использовать
+версию из PATH — конфликтов нет.
+
+*Подробнее в разделе [Управление бинарником](#управление-бинарником).*
+
 ## CLI
 
 После установки команда `opencode-py` доступна **общесистемно** из любой директории:

{opencode_py-0.2.2 → opencode_py-0.3.0}/RELEASE.md

@@ -48,7 +48,9 @@ git push
 
 | Version | Date | Highlights |
 |---------|------|------------|
-| 0.2.2   | 2025-07-04 | Comprehensive README documentation, Pydantic fixes in demo.py, mypy fixes in check-upstream.py |
-| 0.2.1   | 2025-07-04 | Fix: rename entry point to `opencode-py` to avoid conflict with the real `opencode` binary |
-| 0.2.0   | 2025-07-03 | Pydantic models, retry, typed errors, logging, async, streaming, auto-tools, web UI |
-| 0.1.1   | —    | Initial PyPI release |
+| 0.3.0   | 2026-07-05 | Typed Pydantic models for all client methods (cast_to), 30+ new model classes, _construct_type handles list[X] generics and {"data": [...]} format |
+| 0.2.2   | 2026-07-04 | Comprehensive README documentation (EN/RU), Pydantic fixes in demo.py, mypy fixes |
+| 0.2.1   | 2026-07-04 | Fix: rename entry point to `opencode-py` to avoid conflict with the real `opencode` binary |
+| 0.2.0   | 2026-07-03 | Pydantic models, retry, typed errors, logging, async, streaming, auto-tools, web UI |
+| 0.1.1   | 2026-07-03 | Fix author/URLs, add keywords, Docker smoke test, badges |
+| 0.1.0   | 2026-06-30 | Initial PyPI release |

opencode_py-0.3.0/VERIFY.md

@@ -0,0 +1,84 @@
+# Verification Checklist — v0.3.0-dev
+
+Перед повышением версии и публикацией нужно проверить:
+
+## 1. Unit-тесты (без сервера)
+
+```bash
+pytest tests/ -v
+```
+
+Ожидается: **31 passed**.
+
+## 2. Линтер и типы
+
+```bash
+ruff check src/ tests/
+mypy src/
+```
+
+Ожидается: `ruff` — All checks passed, `mypy` — Success.
+
+## 3. Демо
+
+```bash
+python demo.py
+```
+
+Должен пройти все 12 шагов без ошибок, завершиться "SDK is working correctly!".
+
+## 4. Живой тест
+
+```bash
+python test_live.py
+```
+
+Запускает `opencode serve`, проходит 38 endpoint-чеков.
+
+## 5. Интерактивный режим
+
+```bash
+python live.py
+```
+
+Проверить multi-turn (Ctrl+C для выхода).
+
+## 6. Streaming
+
+```bash
+python live_streaming.py
+```
+
+## 7. Web UI
+
+```bash
+python web/server.py
+```
+
+Открыть браузер на `http://localhost:3000`.
+
+## 8. Async
+
+```bash
+python live_async.py
+```
+
+## 9. Проверка upstream
+
+```bash
+python scripts/check-upstream.py
+```
+
+Ожидается: "No SDK changes needed" (если upstream не менялся).
+
+---
+
+После успешной проверки скажи — я подниму версию в `pyproject.toml`, сделаю тег `v0.3.0` и опубликую:
+
+```bash
+git tag v0.3.0
+git push origin master --tags
+python -m build
+twine check dist/*
+twine upload dist/*
+```

{opencode_py-0.2.2 → opencode_py-0.3.0}/demo.py

@@ -3,8 +3,6 @@
 
 from __future__ import annotations
 
-import json
-
 from opencode import OpencodeClient, create_opencode_server
 
 print("=" * 60)
@@ -13,7 +11,7 @@ print("=" * 60)
 
 # 1. Start the server
 print("\n[1] Starting opencode serve...")
-server = create_opencode_server(port=4098)
+server = create_opencode_server(port=4097)
 print(f"    Server at {server.url} (pid={server.pid})")
 
 client = OpencodeClient(base_url=server.url)
@@ -24,7 +22,7 @@ print(f"\n[2] Server: version={h.version}, healthy={h.healthy}")
 
 # 3. Current project
 pj = client.project_current()
-print(f"\n[3] Project: id={pj['id'][:12]}... vcs={pj['vcs']}")
+print(f"\n[3] Project: id={pj.id[:12]}... vcs={pj.vcs}")
 
 # 4. Session management
 print("\n[4] Creating session...")
@@ -40,25 +38,20 @@ print(f"    File: {len(f.content)} chars")
 # 6. VCS info
 print("\n[6] VCS status...")
 vcs = client.vcs_status()
-print(f"    {json.dumps(vcs, indent=2, ensure_ascii=False)[:200]}")
+n = len(vcs) if vcs else 0
+print(f"    {n} changed files")
 
 # 7. Available models
 print("\n[7] Available models...")
 models = client.v2_model_list()
+providers = sorted(set(m.providerID for m in models if m.providerID))
 print(f"    Format: {type(models).__name__}")
-data = models.get("data", models) if isinstance(models, dict) else models
-data = data if isinstance(data, list) else []
-providers = [m.get("id", str(m)[:20]) for m in data[:5]]
-print(f"    Providers/models: {providers}")
+print(f"    Providers/models: {providers[:5]}")
 
 # 8. Code search
 print("\n[8] Searching text...")
 found = client.find_text("create_opencode")
-n = (
-    len(found)
-    if isinstance(found, list)
-    else (len(found.get("data", [])) if isinstance(found, dict) else "?")
-)
+n = len(found) if isinstance(found, list) else "?"
 print(f"    Found: {n}")
 
 # 9. Send prompt (no LLM — queue only)
@@ -67,11 +60,7 @@ try:
     msg = client.v2_session_prompt(
         sid, {"text": "Hello! Answer in one word."}, delivery="queue"
     )
-    data = msg.get("data", [{}])
-    if isinstance(data, list):
-        resp_type = data[0].get("type", "?")
-    else:
-        resp_type = type(msg).__name__
+    resp_type = getattr(msg, "type", type(msg).__name__)
     print(f"    Response: type={resp_type}")
     print("    Prompt queued for processing")
 except Exception as e:
@@ -80,23 +69,15 @@ except Exception as e:
 # 10. Session context messages
 print("\n[10] Session messages...")
 ctx = client.v2_session_context(sid)
-count = (
-    len(ctx.get("data", []))
-    if isinstance(ctx, dict)
-    else len(ctx)
-    if isinstance(ctx, list)
-    else "?"
-)
-print(f"     Messages: {count}")
+items = ctx.get("data", []) if isinstance(ctx, dict) else ctx if isinstance(ctx, list) else []
+print(f"     Messages: {len(items)}")
 
 # 11. Extra capabilities
 print("\n[11] Additional:")
 path = client.path_get()
-print(f"     Working directory: {path.get('worktree', '?')}")
+print(f"     Working directory: {path.worktree}")
 cmds = client.command_list()
-print(
-    f"     Opencode commands: {len(cmds) if isinstance(cmds, list) else '?'}"
-)
+print(f"     Opencode commands: {len(cmds) if isinstance(cmds, list) else '?'}")
 agents = client.app_agents()
 print(f"     Agents: {len(agents) if isinstance(agents, list) else '?'}")
 

{opencode_py-0.2.2 → opencode_py-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "opencode-py"
-version = "0.2.2"
+version = "0.3.0"
 description = "Python SDK for Opencode — the open source AI coding agent"
 readme = "README.md"
 long_description_content_type = "text/markdown"
@@ -62,6 +62,9 @@ src = ["src"]
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "W", "UP"]
 
+[tool.ruff.lint.per-file-ignores]
+"src/opencode/_response_models.py" = ["N815"]
+
 [tool.mypy]
 python_version = "3.10"
 strict = true

{opencode_py-0.2.2 → opencode_py-0.3.0}/scripts/check-release.py

@@ -1,95 +1,95 @@
-"""Check if a new PyPI release is needed.
-
-Compares the version in pyproject.toml with the latest git tag.
-Exits with code 0 if no release needed, 1 if a release is recommended.
-
-Usage:
-    python scripts/check-release.py
-    python scripts/check-release.py --verbose
-"""
-
-from __future__ import annotations
-
-import re
-import subprocess
-import sys
-from pathlib import Path
-
-
-def get_current_version() -> str:
-    pyproject = Path(__file__).parent.parent / "pyproject.toml"
-    text = pyproject.read_text()
-    m = re.search(r'^version\s*=\s*"([^"]+)"', text, re.MULTILINE)
-    if m:
-        return m.group(1)
-    raise RuntimeError("Could not find version in pyproject.toml")
-
-
-def get_latest_tag() -> str | None:
-    result = subprocess.run(
-        ["git", "tag", "--list", "v*", "--sort=-version:refname"],
-        capture_output=True, text=True, cwd=Path(__file__).parent.parent,
-    )
-    tags = [t.strip() for t in result.stdout.splitlines() if t.strip()]
-    return tags[0] if tags else None
-
-
-def get_commit_count_since_tag(tag: str) -> int:
-    result = subprocess.run(
-        ["git", "rev-list", f"{tag}..HEAD", "--count"],
-        capture_output=True, text=True, cwd=Path(__file__).parent.parent,
-    )
-    return int(result.stdout.strip() or "0")
-
-
-def main() -> int:
-    verbose = "--verbose" in sys.argv or "-v" in sys.argv
-
-    current = get_current_version()
-    latest_tag = get_latest_tag()
-
-    print(f"Current version (pyproject.toml): {current}")
-
-    if latest_tag is None:
-        print("No git tags found — this would be the first release.")
-        return 0
-
-    tag_version = latest_tag.lstrip("v")
-    print(f"Latest git tag:                  {latest_tag}")
-
-    commits_since = get_commit_count_since_tag(latest_tag)
-
-    if current == tag_version:
-        if commits_since > 0:
-            print(f"\n==> {commits_since} commit(s) since {latest_tag}, "
-                  f"but version hasn't been bumped ({current}).")
-            if verbose:
-                result = subprocess.run(
-                    ["git", "log", f"{latest_tag}..HEAD", "--oneline"],
-                    capture_output=True, text=True,
-                    cwd=Path(__file__).parent.parent,
-                )
-                print("\nUnreleased commits:")
-                for line in result.stdout.splitlines():
-                    print(f"  {line}")
-            print("\n=> Run `python -m build` and publish when ready:")
-            print("  python -m build")
-            print("  twine upload dist/*")
-            return 1
-        else:
-            print("\n[ok] Everything is up to date. No release needed.")
-            return 0
-    else:
-        print(f"\n=> Version in pyproject.toml ({current}) differs from "
-              f"latest tag ({tag_version}).")
-        print("  A new release may be ready to publish.")
-        if verbose:
-            print("\n  To publish:")
-            print("  git tag v" + current)
-            print("  git push origin v" + current)
-            print("  python -m build && twine upload dist/*")
-        return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())
+"""Check if a new PyPI release is needed.
+
+Compares the version in pyproject.toml with the latest git tag.
+Exits with code 0 if no release needed, 1 if a release is recommended.
+
+Usage:
+    python scripts/check-release.py
+    python scripts/check-release.py --verbose
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+def get_current_version() -> str:
+    pyproject = Path(__file__).parent.parent / "pyproject.toml"
+    text = pyproject.read_text()
+    m = re.search(r'^version\s*=\s*"([^"]+)"', text, re.MULTILINE)
+    if m:
+        return m.group(1)
+    raise RuntimeError("Could not find version in pyproject.toml")
+
+
+def get_latest_tag() -> str | None:
+    result = subprocess.run(
+        ["git", "tag", "--list", "v*", "--sort=-version:refname"],
+        capture_output=True, text=True, cwd=Path(__file__).parent.parent,
+    )
+    tags = [t.strip() for t in result.stdout.splitlines() if t.strip()]
+    return tags[0] if tags else None
+
+
+def get_commit_count_since_tag(tag: str) -> int:
+    result = subprocess.run(
+        ["git", "rev-list", f"{tag}..HEAD", "--count"],
+        capture_output=True, text=True, cwd=Path(__file__).parent.parent,
+    )
+    return int(result.stdout.strip() or "0")
+
+
+def main() -> int:
+    verbose = "--verbose" in sys.argv or "-v" in sys.argv
+
+    current = get_current_version()
+    latest_tag = get_latest_tag()
+
+    print(f"Current version (pyproject.toml): {current}")
+
+    if latest_tag is None:
+        print("No git tags found — this would be the first release.")
+        return 0
+
+    tag_version = latest_tag.lstrip("v")
+    print(f"Latest git tag:                  {latest_tag}")
+
+    commits_since = get_commit_count_since_tag(latest_tag)
+
+    if current == tag_version:
+        if commits_since > 0:
+            print(f"\n==> {commits_since} commit(s) since {latest_tag}, "
+                  f"but version hasn't been bumped ({current}).")
+            if verbose:
+                result = subprocess.run(
+                    ["git", "log", f"{latest_tag}..HEAD", "--oneline"],
+                    capture_output=True, text=True,
+                    cwd=Path(__file__).parent.parent,
+                )
+                print("\nUnreleased commits:")
+                for line in result.stdout.splitlines():
+                    print(f"  {line}")
+            print("\n=> Run `python -m build` and publish when ready:")
+            print("  python -m build")
+            print("  twine upload dist/*")
+            return 1
+        else:
+            print("\n[ok] Everything is up to date. No release needed.")
+            return 0
+    else:
+        print(f"\n=> Version in pyproject.toml ({current}) differs from "
+              f"latest tag ({tag_version}).")
+        print("  A new release may be ready to publish.")
+        if verbose:
+            print("\n  To publish:")
+            print("  git tag v" + current)
+            print("  git push origin v" + current)
+            print("  python -m build && twine upload dist/*")
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{opencode_py-0.2.2 → opencode_py-0.3.0}/scripts/check-upstream.py

@@ -17,14 +17,17 @@ UPSTREAM_URL = "https://raw.githubusercontent.com/anomalyco/opencode/dev/package
 
 def fetch_json(url: str) -> dict[str, Any]:
     with urllib.request.urlopen(url, timeout=15) as resp:
-        return cast(dict[str, Any], json.loads(resp.read().decode()))
+        data: dict[str, Any] = json.loads(resp.read().decode())
+        return data
 
 
 def get_inline_delivery_enum(spec: dict[str, Any]) -> list[str] | None:
     """Extract the delivery enum from the v2 prompt endpoint."""
     try:
         prompt = spec["paths"]["/api/session/{sessionID}/prompt"]["post"]
-        props = prompt["requestBody"]["content"]["application/json"]["schema"]["properties"]
+        props = prompt["requestBody"]["content"]["application/json"]["schema"][
+            "properties"
+        ]
         delivery = props["delivery"]
         return cast(list[str] | None, delivery.get("enum"))
     except Exception:
@@ -40,7 +43,9 @@ def main() -> None:
         return
 
     info = upstream.get("info", {})
-    print(f"Upstream info: title={info.get('title')}, version={info.get('version')}")
+    print(
+        f"Upstream info: title={info.get('title')}, version={info.get('version')}"
+    )
 
     # Check 1: delivery enum
     delivery = get_inline_delivery_enum(upstream)
@@ -62,7 +67,9 @@ def main() -> None:
         elif "queue" in delivery:
             print("  => No change needed (still 'queue' compatible).")
     else:
-        changes_needed.append("Delivery enum not found in spec — endpoint may have changed.")
+        changes_needed.append(
+            "Delivery enum not found in spec — endpoint may have changed."
+        )
 
     # Check 2: structured output format
     schemas = upstream.get("components", {}).get("schemas", {})
@@ -71,11 +78,15 @@ def main() -> None:
         # Check inline in V1 session/message endpoint
         try:
             v1 = upstream["paths"]["/session/{sessionID}/message"]["post"]
-            props = v1["requestBody"]["content"]["application/json"]["schema"]["properties"]
+            props = v1["requestBody"]["content"]["application/json"]["schema"][
+                "properties"
+            ]
             has_structured = "format" in props
         except Exception:
             pass
-    print(f"\nStructured output (format field): {'PRESENT' if has_structured else 'MISSING'}")
+    print(
+        f"\nStructured output (format field): {'PRESENT' if has_structured else 'MISSING'}"
+    )
     if not has_structured:
         changes_needed.append(
             "'format' field in V1 prompt endpoint missing — structured output may have changed."