worldtree-sdk (1.3.0)
Installation
registry=https://gitea.phasefinal.com/api/packages/vh/npm/npm install worldtree-sdk@1.3.0"worldtree-sdk": "1.3.0"About this package
worldtree-sdk
Official consumer SDK for the Worldtree Conversation API. Two sibling
implementations off the same behavioral spec + the same fixture
corpus: TypeScript (src/, this repo root) and Python (python/),
Python-idiomatic per surface-design §6.
Status: both siblings SHIPPED at v1.0.0 GA (2026-07-19). TypeScript
worldtree-sdk@1.0.0 on the internal Gitea npm registry (213 tests); Python
worldtree-sdk==1.0.0 on the internal vh Gitea PyPI (133 tests, tag
python-v*). Governing contracts: docs/contracts/worldtree-sdk-v0.contract.md
(TS, rev 1.4) and docs/contracts/worldtree-sdk-python-v0.contract.md (Python,
rev 1.1); the fixture corpus is the shared conformance gate.
What governs what
| Artifact | Role |
|---|---|
docs/behavioral-spec.md |
The protocol rulebook (B-/D- rules) both spines implement |
docs/surface-design.md |
Ratified public-surface decisions (D1–D4) |
docs/parity-matrix.md |
Consumer migration gate (warts W-1..W-8, typed-error floor) |
docs/codegen-spike.md |
Codegen verdict: types-only via openapi-typescript |
docs/contracts/worldtree-sdk-v0.contract.md |
The TS implementation contract (SDK-INV-001..009) |
docs/contracts/worldtree-sdk-python-v0.contract.md |
The Python implementation contract (PY-INV-001..013) |
fixtures/ |
70 golden fixtures — the executable conformance floor; validate_corpus.py lints |
capture/ |
Live wire-capture harness (redacted transcripts → fixtures/captured/) |
vendor/ |
Frozen Worldtree API artifacts + SPEC-PIN.md (regen + bump procedure) |
Layout
src/generated/ openapi-typescript output (internal; regen via `npm run generate`)
src/shapes/ hand-authored response shapes (internal)
src/wire/ SSE spine: parser + resume orchestration (internal)
src/client/ the public facade — the ONLY public import surface
conformance/ TS corpus runner (gates publish)
python/ the Python sibling (uv project: `worldtree_sdk/` package + `tests/`)
Publishing
TypeScript: internal Gitea npm registry only (publishConfig in package.json);
zero runtime dependencies; Node ≥ 20 and evergreen browsers via native
fetch/ReadableStream. Python: internal vh Gitea PyPI (python/, tag
python-v*); sole runtime dep httpx; Python 3.11+, async-only.
Origin: Worldtree issue #371. The docs/fixtures family migrated from
Worldtree docs/sdk/ on 2026-07-18; Worldtree keeps a pointer.
Dependencies
Development Dependencies
| ID | Version |
|---|---|
| openapi-typescript | 7.13.0 |
| typescript | ^5.9.2 |
| vitest | ^3.2.0 |