worldtree-sdk cutover — adopt the Python SDK for the consumer client layer #20

New Issue

2026-07-18T23:15:04-07:00

vh commented

2026-07-18 23:15:04 -07:00

Decision

Operator-ruled (2026-07-18): ratatoskr adopts worldtree-sdk (Python) 1.0.0 for its consumer client layer, retiring its hand-rolled httpx wrappers (sessions.py/sse_client.py/tier3.py). Adopt-canonical over stay-independent. The SDK is the GA Python client ratatoskr's own parity pass shaped.

Design (locked, vor-cross'd with worldtree-codex, heid-panel-reviewed)

Contract: docs/contracts/worldtree_sdk_cutover.contract.md. Six decisions:

DEC-1 retire wire contracts #2/#15 → one SDK-adapter contract (two-phase: supersede now, delete files at teardown); first_message stays ratatoskr-owned.
DEC-2 thin semantic error adapter (SDK ApiError floor → ratatoskr exceptions; see the § Error map table — route is the discriminator, default → SessionApiFailed).
DEC-3 no shims — delete old wrappers + update call-sites.
DEC-4 incremental route-family slices + live-smoke (with an acceptance bar) per slice; no soak.
DEC-5 pin worldtree-sdk==1.0.0 from the internal gitea PyPI. CLEARED — registry live.
DEC-6 minor bump at ship (operator approval).

Scope

Consumer client layer ONLY (→ ratatoskr.wt adapter, caller-injected transport). CLI/TUI/Starlette web external behavior preserved. Bifrost PROVIDER planes (memory/affect, ADR-0009) untouched.

Slice plan

1 Foundation → 2 Sessions/turn → 3 Persona+history → 4 Agents (folds in the pending tier3 model→role) → 5 Characters/me/caps/models → 6 Admin → 7 Teardown.

Multi-session migration. Tracks all slices to done.

## Decision Operator-ruled (2026-07-18): ratatoskr **adopts worldtree-sdk (Python) 1.0.0** for its consumer client layer, retiring its hand-rolled httpx wrappers (`sessions.py`/`sse_client.py`/`tier3.py`). Adopt-canonical over stay-independent. The SDK is the GA Python client ratatoskr's own parity pass shaped. ## Design (locked, vor-cross'd with worldtree-codex, heid-panel-reviewed) Contract: `docs/contracts/worldtree_sdk_cutover.contract.md`. Six decisions: - DEC-1 retire wire contracts #2/#15 → one SDK-adapter contract (two-phase: supersede now, delete files at teardown); `first_message` stays ratatoskr-owned. - DEC-2 thin semantic error adapter (SDK `ApiError` floor → ratatoskr exceptions; see the § Error map table — route is the discriminator, default → `SessionApiFailed`). - DEC-3 no shims — delete old wrappers + update call-sites. - DEC-4 incremental route-family slices + live-smoke (with an acceptance bar) per slice; no soak. - DEC-5 pin `worldtree-sdk==1.0.0` from the internal gitea PyPI. **CLEARED — registry live.** - DEC-6 minor bump at ship (operator approval). ## Scope Consumer client layer ONLY (→ `ratatoskr.wt` adapter, caller-injected transport). CLI/TUI/Starlette web external behavior preserved. Bifrost PROVIDER planes (memory/affect, ADR-0009) untouched. ## Slice plan 1 Foundation → 2 Sessions/turn → 3 Persona+history → 4 Agents (folds in the pending tier3 model→role) → 5 Characters/me/caps/models → 6 Admin → 7 Teardown. Multi-session migration. Tracks all slices to done.

vh referenced this issue from a commit

2026-07-19 08:17:14 -07:00

docs(contract): worldtree-sdk cutover — SDK-adapter contract (refs #20)

vh referenced this issue from a commit

2026-07-19 08:17:14 -07:00

memory: /snapshot — worldtree-sdk cutover decided (#20), slice-1 next

vh referenced this issue from a commit

2026-07-19 08:17:14 -07:00

build(deps): integrate worldtree-sdk==1.0.0 (DEC-5 verified) — #20 slice-1

vh referenced this issue from a commit

2026-07-19 08:17:14 -07:00

feat(#20): worldtree-sdk adapter foundation — ratatoskr.wt (slice-1)