cleanlib-sdk 0.4.4

CleanLibrary Python SDK — HttpVerdictClient + HttpRemediationClient + HttpEnrichClient triad (sister-shape with @cleanstart/cleanlib-sdk v0.4.4)

cleanlib-sdk

CleanLibrary Python SDK — asyncio + httpx; mirrors the Rust cleanlib-client HTTP surface.

Status: v0.4.3 — production-ready.

Install

pip install cleanlib-sdk

Usage

import asyncio
from cleanlib_sdk import Client, PolicyDenyError, RiskAcceptanceRequiredError

async def main() -> None:
    async with Client(
        endpoint="https://cleanapp.clnstrt.dev",
        api_key="clk_std_...",   # opaque CleanLibrary access key
    ) as c:
        try:
            v = await c.fetch_verdict("npm", "lodash", "4.17.21")
            print(f"{v.decision} composite_score={v.composite_score}")
            print(f"reasoning: {v.reasoning}")
        except PolicyDenyError as e:
            print(f"DENIED [{e.reason_code}]: {e.message}")
        except RiskAcceptanceRequiredError as e:
            print(f"RISK ACCEPT REQUIRED: {e.message}")
            if e.docs_url:
                print(f"see: {e.docs_url}")

asyncio.run(main())

Error hierarchy

All errors descend from CleanLibraryError. Subclasses:

Exception	HTTP	Triggered by
PolicyDenyError	403 / 451	POLICY_DENY_VERDICT / POLICY_DENY_RULE_EXPLICIT
IntegrityFailureError	403	INTEGRITY_FAILURE
RateLimitExceededError	429	tier-throttled; carries retry_after_seconds
RiskAcceptanceRequiredError	403	RISK_ACCEPTANCE_REQUIRED
AuthenticationError	401 / 403	KEY_INVALID / KEY_EXPIRED / KEY_SCOPE_INSUFFICIENT
InsufficientDataError	403	INSUFFICIENT_DATA_FAIL_CLOSED
PackageNotFoundError	404	not in catalog + ingest declined
ServerError	5xx	retryable on 502/503/504
TransportError	—	network / TLS / timeout / DNS
ParseError	—	response body shape mismatch

Development

pip install -e ".[dev]"
pytest
ruff check .

Cross-references

• CleanLibrary docs — customer documentation portal
• Rust SDK: cleanlib-client — reference implementation
• Go SDK: cleanlib-sdk-go
• JavaScript SDK: @cleanstart/cleanlib-sdk

License

Proprietary — CleanStart.