Metadata-Version: 2.4
Name: pyb-agent-sdk
Version: 0.2.2
Summary: Python client SDK for PYB Agent — engine launcher included (auto-discover or spawn `pyb web`)
Author: PYB-XC
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"

# PYB Agent SDK (Python)

Python client SDK for the PYB Agent engine — with a built-in engine launcher:
`pip install` is all you need; the SDK auto-discovers or spawns the engine on
first use (zero-prerequisite install on platforms with a bundled wheel).

## Install

```powershell
pip install pyb-agent-sdk
```

- Windows x64: a platform wheel with the bundled engine is selected
  automatically (`py3-none-win_amd64`, ~67MB) — no other setup needed.
- Other platforms: the pure wheel installs the launcher, which reuses a
  running engine at `http://localhost:4096` or spawns the `pyb` command from
  PATH (`npm install -g pybao-xc-sdk` provides it).

## Quick start

```python
import asyncio
from pyb_agent_sdk import PybAgentClient, ClientOptions

async def main():
    async with PybAgentClient(
        "http://localhost:4096",          # probed first; auto-spawn if dead
        options=ClientOptions(cwd="D:/proj"),
    ) as client:
        async for event in client.query("hello"):
            if event.type == "content_delta":
                print(event.text, end="")

asyncio.run(main())
```

## First-run model configuration

The engine starts without credentials, but conversations require a model API
key. Two options:

1. **Interactive**: run `pyb` once in a terminal and complete model setup —
   stored in `~/.pyb/model-config-v2.sqlite`.
2. **Environment**: set `ANTHROPIC_AUTH_TOKEN=<your key>` before starting
   your Python process.

GLM keys: <https://open.bigmodel.cn> (the engine's default model family).

Without a key, the first `query()` fails with an actionable message pointing
here (the engine's `/health` stays green — key issues surface per-turn, not
at startup).

## Engine version lock

The launcher validates the spawned engine's `--version` against a known-good
floor (currently 1.5.281) and fails fast with upgrade guidance if the binary
is older — instead of mysterious mid-conversation protocol errors.

## Session pinning (shared live context)

Pass `session_id=` to the constructor to attach to an existing session — all
clients on the same session share live context (server-side broadcast), e.g.
ESP32 voice input and terminal CLI in one conversation.

## API surface

- `PybAgentClient(base_url, *, session_id=None, options=None, can_use_tool=None)`
- `await client.start() → session_id` / `await client.resume(session_id)`
- `async for event in client.query(text)` — `content_delta` / terminal events
- `await client.interrupt()` — abort the running turn
- `SessionLostError` — first-class: raised when the server lost the session
