burdenoff-sdk-libs

Modular SDK library shared across all Burdenoff product SDKs (Python).

Each module under src/burdenoff_sdk_libs/modules/<name>/ exports an SdkModule (a dataclass with attach(ctx) -> API). Product SDKs (vibecontrols-sdk-python, botlit-sdk-python, etc.) become thin shells that pick which modules to mount. Sister to @burdenoff/sdk-libs (Node) and @burdenoff/cli-sdk.

Architecture

• Core (src/burdenoff_sdk_libs/core/): SdkContext, SdkModule Protocol, dual-gateway BaseGraphQLClient (workspace + global), AuthStore with pluggable TokenStore (InMemoryTokenStore, FileTokenStore, EnvTokenStore), error hierarchy with token redaction, structured logger, ModuleRegistry.
• Modules (src/burdenoff_sdk_libs/modules/<name>/): __init__.py exports SdkModule instance. operations.py holds hand-written GraphQL doc strings. api.py builds the API. Generated types land at src/burdenoff_sdk_libs/modules/<name>/__generated__/types.py (gitignored).
• PEP 562 lazy imports: top-level __getattr__ defers module loading until first access (lambda/edge cold-start friendly).
• Hard rules: Modules NEVER import each other directly — use ctx.modules.get('id'). Modules NEVER print, raise plain Exception, or log secrets unredacted.

Build & Commands

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest                            # unit tests
pytest --cov                      # with coverage
python scripts/codegen.py         # generate types from pinned supergraph
python scripts/parity_check.py    # cross-language manifest diff vs sdk-libs-node
python -m build                   # sdist + wheel

Adding a module

1. mkdir src/burdenoff_sdk_libs/modules/<id> with __init__.py, operations.py, api.py, types.py.
2. Export SdkModule instance from __init__.py (e.g. auth_module = AuthModule()).
3. Add to _LAZY_MODULES in top-level __init__.py if surfacing at package root.
4. Add manifest entry to schema/modules.yaml.
5. Mirror in ~/products/sdk-libs-node/ in the SAME PR pair.

Testing

• Unit (tests/test_*.py): pure logic. No HTTP. pytest, <5s.
• Integration: respx intercepts HTTP. Mock factories derived from __generated__/types.py.
• E2E: real svc + state, run nightly.
• Parity: same tests/parity/<scenario>.yaml run by node + python.

Reference

• ~/products/sdk-libs-node/ — sister Node library.
• ~/products/cli-sdk/ — sister CLI library.
• ~/products/vibecontrols/vibecontrols-sdk-python/ — first consumer (thin shell).
• ~/products/dev/audit/index/vibecontrols.md — 23-module ground-truth.
• docs/fluidgrids.md — the FluidGrids module: authentication, errors and misses, retries, following a run live, paging, secrets, quirks.