feat: Python SDK for Koine gateway

[matthew-petty]

Summary

Implements a complete Python SDK for Koine gateway, closing #2.

• Full API parity with TypeScript SDK — generate_text, generate_object, stream_text
• Type-safe — Pydantic models, full type hints, pyright strict mode
• Well-tested — 20 tests with coverage reporting
• CI integrated — Linting (ruff), type checking (pyright), and tests run on every PR

Features

Text Generation

from koine_sdk import KoineConfig, generate_text

config = KoineConfig(
    base_url="http://localhost:3100",
    auth_key="your-api-key",
    timeout=300.0,
)

result = await generate_text(config, prompt="Hello!")
print(result.text)

Streaming (with async context manager for resource safety)

from koine_sdk import stream_text

async with stream_text(config, prompt="Write a story") as result:
    async for chunk in result.text_stream:
        print(chunk, end="")
    
    usage = await result.usage()

Structured Output

from pydantic import BaseModel
from koine_sdk import generate_object

class Person(BaseModel):
    name: str
    age: int

result = await generate_object(config, prompt="Extract: John is 30", schema=Person)
print(result.object.name)  # "John"

Changes

New Files

• packages/sdks/python/ — Complete Python SDK package
  • src/koine_sdk/ — Client, types, errors modules
  • tests/ — Comprehensive test suite
  • pyproject.toml — Package configuration with ruff, pyright, pytest

Documentation Updates

• docs/sdk-guide.md — Added Python examples alongside TypeScript
• docs/README.md — Added Python SDK quick start
• docs/examples/python/ — Runnable examples (hello, stream, conversation, extract_recipe)
• packages/sdks/python/README.md — SDK documentation
• CONTRIBUTING.md — Marked Python SDK as complete in roadmap
• README.md — Added Python SDK to packages table

CI Updates

• .github/workflows/ci.yml — Added Python linting and testing with uv caching

Test plan

• All 20 Python SDK tests pass locally
• TypeScript tests still pass
• Linting passes (ruff check, ruff format, pyright)
• Examples work against running gateway
• CI passes on this PR

Related Issues

• Closes Create Python SDK #2 (Python SDK)
• Created Move SDK examples into respective SDK package directories #40 (Move examples to SDK directories - future work)
• Created Streaming endpoint returns 0 tokens for usage stats #41 (Streaming token usage returns 0 - gateway issue)

[codecov]

Codecov Report

❌ Patch coverage is 93.53448% with 15 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/sdks/python/src/koine_sdk/client.py	90.13%	15 Missing ⚠️

📢 Thoughts on this report? Let us know!