PR-B4 (ADR 0008 Phase B): Python SDK — kakeya.Client + kakeya.Session

[FluffyAIcode]

⚠️ Stacked PR

Depends on PR #46 (PR-B3). The diff against main shows both
PRs; once #46 merges, this auto-rebases to a clean PR-B4-only
diff.

What

Second-to-last PR of ADR 0008 Phase B. Ships
sdks/python/kakeya/ — the Python SDK matching the ADR §3.1
example exactly:

from kakeya import Client

with Client("localhost:50051") as client:
    with client.create_session(eos_token_ids=[151645]) as session:
        session.append([10, 20, 30])
        for token_id in session.generate(max_tokens=64):
            print(token_id)

Sync, not async

PR-B4 ships sync only (grpc.insecure_channel + sync stubs).
Three reasons:

1. The ADR §3.1 example is sync.
2. v0.3 target audience (REPL, scripts, agent harnesses on a
   single Mac) prefers sync — async adds friction without payoff
   under max_concurrent=1.
3. Async can be added later (AsyncClient / AsyncSession)
   without breaking this surface; the runtime is wire-compatible.

Tokenization is NOT in the SDK

Per ADR §2.4 / §3.4: the runtime treats token ids as opaque
integers; rendering messages → tokens is the application's
responsibility. The SDK ships zero chat-template logic.
sdks/python/examples/ (a future PR) will demonstrate the
apply_chat_template pattern as opt-in usage.

Surface

Module	Symbol	Role
kakeya.client	Client	Connection to the runtime; create_session / close / context manager
kakeya.session	Session	One server-side session; append / generate / info / close / context manager
kakeya.session	SessionInfo	Read-only snapshot returned by Session.info()
kakeya.errors	KakeyaError (+6 subclasses)	Typed exception hierarchy mapping every gRPC status

Error mapping (per ADR §2.6 / §2.10, no graceful degradation):

gRPC StatusCode	SDK exception
NOT_FOUND	SessionNotFoundError
INVALID_ARGUMENT	InvalidArgumentError
FAILED_PRECONDITION	InvariantViolationError
RESOURCE_EXHAUSTED	ResourceExhaustedError
UNIMPLEMENTED	UnimplementedError
CANCELLED	RpcCancelledError
(unknown)	KakeyaError (base, with .rpc_code)

SessionClosedError is client-side only (raised when methods are
called on a closed Session instance) and never crosses the wire.

Tests (tests/sdk/python/)

File	Tests	Focus
test_errors.py	20	Every status → typed-exception mapping; .rpc_code carry; unknown-status fallback.
test_client.py	13	Construction, properties, idempotent close, context manager, create_session with all argument combinations, end-to-end RESOURCE_EXHAUSTED → ResourceExhaustedError.
test_session.py	33	All 5 RPC methods, all error paths, last_* metadata fields, HistoryTruncated → .last_history_truncated_dropped, greedy-only contract via InvalidArgumentError, double-close idempotency, SessionInfo standalone surface.
Total	66	All against a real grpc.aio server in a background thread (see conftest.py).

The fixture's notable choices (worth one read by reviewers):

• The async server is constructed inside the worker thread's
  event loop, not the main thread. Constructing in the main thread
  and using in another thread's loop produces grpcio's "Future
  attached to a different loop" errors.
• Shutdown uses server.wait_for_termination() rather than
  cancelling tasks. wait_for_termination() returns cleanly once
  server.stop() is invoked, which lets run_until_complete()
  exit without a cancellation tantrum.

Files

Status	Path	Notes
add	sdks/python/kakeya/__init__.py	Public API entry point (re-exports).
add	sdks/python/kakeya/client.py (~130 lines)	Client.
add	sdks/python/kakeya/session.py (~300 lines)	Session + SessionInfo.
add	sdks/python/kakeya/errors.py (~130 lines)	Typed exception hierarchy + _wrap_grpc_error.
add	tests/sdk/python/conftest.py (~200 lines)	Background-thread async-server fixture.
add	tests/sdk/python/test_*.py (66 tests)
add	scripts/review_pr_b4_on_mac.sh (Mac reviewer aid).
mod	.github/workflows/ci.yaml	PYTHONPATH=.:sdks/python; tests/sdk/python/; --cov=kakeya; import smoke for kakeya / client / session / errors.

Linux verification

PYTHONPATH=.:sdks/python pytest <Linux CI gate set> --cov-fail-under=100
695 passed (was 629 + 66 new), coverage 100.00 % on 1694 stmts

bash scripts/review_pr_b4_on_mac.sh
  SDK tests       : 66 tests, cov=173/173=100%
  Runtime smoke   : 10/10
  Appender smoke  : 10/10
  Generator smoke : 10/10

Per ADR 0008 §9

Linux-only-path carve-out invoked: zero MLX runtime code; the SDK
is pure Python over grpcio (sync). The review_pr_b4_on_mac.sh
runner is a review affordance for users who want to see the SDK
work on Apple Silicon end-to-end, but is not a §9 mandatory
report.

The next PR with mandatory §9 Mac M4 testing is PR-B5
(TypeScript SDK) — but that one is also platform-neutral; the
mandatory §9 gate doesn't return until v0.4 multi-tenant or any
new MLX-touching code lands.

Reviewer checklist

• Public API matches ADR §3.1 example exactly: from kakeya import Client; with Client(...) as client: with client.create_session() as s: ... works as documented.
• No tokenization in SDK core (grep -ri "apply_chat_template\|tokenizer" sdks/python/kakeya/ returns no production hits, only docstrings).
• Error mapping is exhaustive: every documented gRPC status in _CODE_TO_EXCEPTION is exercised by test_errors.py::TestWrapGrpcError.
• Streaming semantics: session.generate(...) is a sync generator; last_* metadata populated only after iteration completes.
• Context manager pair: Client.__exit__ closes channel; Session.__exit__ closes session.
• Local close-tracking distinct from runtime state: SessionClosedError (local) vs. SessionNotFoundError (runtime); test_session.py exercises both.
• No new MLX runtime paths (git diff main inference_engine/backends/).
• PYTHONPATH layout documented in CI yaml comments.

Next PR

PR-B5: TypeScript SDK at sdks/typescript/ — Node.js 20+ /
Electron 30+ / Bun 1.1+. Generates stubs from
proto/kakeya/v1/runtime.proto via protoc-gen-ts_proto. After
PR-B5, Phase B is complete.