Add SDK source, config, CI, and documentation

[solwyn-ai]

Summary

Standalone Python SDK extracted from the Solwyn monorepo, fully configured for independent development, testing, and PyPI publishing.

The Solwyn SDK is a drop-in wrapper for OpenAI, Anthropic, and Google LLM clients that adds budget enforcement, circuit breaking, and usage tracking. It never sees customer prompts — the SDK only reports metadata (token counts, latency, model name) to the Solwyn API after each call. Pricing and budget logic live on the server, so pricing updates never require an SDK release.

What's in this repo

SDK source (src/solwyn/)

• Solwyn / AsyncSolwyn — drop-in wrappers for sync and async provider clients
• BudgetEnforcer — cloud budget check with local fallback + fail-open default
• CircuitBreaker — local-only circuit breaker state machine with failover
• MetadataReporter — non-blocking background queue (threading for sync, asyncio.create_task for async)
• Provider adapters for OpenAI, Anthropic, Google — lazy-loaded via a registry
• Stream wrappers that report usage after the stream completes without blocking the caller
• Privacy firewall (_privacy.py) — the only module allowed to touch prompt content, enforced by structural tests

Testing (tests/)

• 297 unit tests in tests/unit/ — all marked @pytest.mark.unit, run in CI with -m unit
• 10 integration tests in tests/integration/ — auto-bootstraps test credentials via the API (signup → project creation → API key). CI opt-in via run-integration label or workflow_dispatch
• 5 pytest markers registered: unit, integration, chaos, performance, stress
• Full async coverage: AsyncBudgetEnforcer, AsyncMetadataReporter lifecycle, AsyncSolwyn non-streaming path
• Structural tests for privacy (no prompt content logged), no-production-asserts (Python -O safe), and stream non-blocking behavior
• BudgetCheckResponse.denied_by_period is required (no silent default=None) — contract drift fails loudly

Tooling

• Makefile — make check, make test, make install-hooks as single entry points
• scripts/pre-commit — runs make check (ruff + format + mypy strict)
• GitHub Actions CI on Python 3.11/3.12 with -m unit filtering
• PyPI publish workflow via OIDC trusted publishing
• CLAUDE.md files at root, src/solwyn/, and tests/ for development context (excluded from the wheel)
• Pydantic v2 throughout — ConfigDict, @model_validator, .model_dump()

Developer experience

make install          # install in dev mode
make install-hooks    # install pre-commit hook
make check            # lint + format + typecheck
make test             # run unit tests
make test-integration # run integration tests (needs API at localhost:8080)

Environment variable discovery for credentials (matches openai-python / stripe-python conventions):

export SOLWYN_API_KEY="sk_solwyn_..."
export SOLWYN_PROJECT_ID="proj_abc12345"

client = Solwyn(OpenAI())  # auto-loads from env

Test plan

• make check passes (ruff + format + mypy strict)
• uv run pytest tests/ -m unit passes (297 passed)
• uv run pytest tests/ -m integration passes against local API (10 passed)
• hatch build produces a clean wheel with no CLAUDE.md, no test files, no solwyn_shared
• CI passes on this PR (Python 3.11 + 3.12)
• pip install solwyn from wheel works in clean venv