cluebase-backend-sdk

Shared Python backend core for Cluebase SDK wrappers (Django, FastAPI, Celery). Events flow through an OTel TracerProvider + ConsentSpanProcessor + ObservationSourceEventExporter and the shared delivery queue to /api/v1/ingest/backend.

Minimal integration

The SDK exposes a single cluebase namespace with eight methods (init / identify / group / reset / track / set_consent / flush / close). This mirrors the cross-SDK contract documented in docs/system/contracts/sdk/public-api.md §1.6.

import asyncio
from cluebase_backend_sdk import cluebase

cluebase.init({
    "project_key": "...",
    "api_key": "...",
    "service_key": "backend-api",
})

cluebase.identify("user_42", {"name": "Alice", "email": "alice@example.com"})
cluebase.group("organization", "org_7", {"name": "Acme Inc"})
cluebase.track("order_placed", {"product_name": "shirt", "amount": 100})
cluebase.set_consent("granted")

# Shutdown idiom — both are coroutines for cross-SDK parity.
asyncio.run(cluebase.flush())
asyncio.run(cluebase.close())

Do not pass environment or service_name in the MVP setup path. Cluebase derives dev/prod from the project key prefix, and service_key is the single literal customer-facing backend service label.

endpoint is optional and defaults to https://api.cluebase.io. Set CLUEBASE_API_BASE_URL only when the SDK must send to another Cluebase API base URL, such as a local environment.

cluebase.track custom event names must match ^[A-Za-z0-9_.:-]{1,128}$. Invalid names are ignored and do not emit a source-signal custom track intent. cluebase.set_consent only records local SDK state in the MVP backend SDK; it does not emit consent transition events.

Framework wrappers and runtime helpers are imported from their owning modules. The package root is intentionally small: customer-facing lifecycle methods plus stable setup helpers. Direct event builders are not public extension points.

Architecture boundary

The Python SDK contains a shared instrumentation core and framework/provider adapters. Adapters register native hooks and extract framework/provider facts; the shared SDK core owns span lifecycle, request-scoped correlation context, privacy handling, common attributes, failure status, and delivery batching. The exporter serializes raw source signals, and the Cluebase backend ingest core performs canonical classification, normalization, privacy projection, and raw-ingest shaping.

Python framework / library hook
  -> native facts passed to shared SDK instrumentation core
  -> OTel source signal
  -> ObservationSourceEventExporter
  -> /api/v1/ingest/backend
  -> apps/api/src/modules/ingest canonical core

Rules:

• Keep adapters limited to native hook registration, native fact extraction, and calls into the shared SDK core.
• Keep run/step tracking, common span lifecycle, context projection, privacy policy, failure classification, and request delivery timing outside framework/provider adapters.
• Keep canonical event classification in the backend ingest core so every SDK language uses the same event rules.
• Preserve interaction_id, request_span_id, request_id, and trace_id whenever they are available through the shared SDK core.
• Run pnpm sdk:architecture:check when changing SDK source. CI runs this gate across every SDK registered in the descriptor.

The stable boundary contract is architecture-gates.md.

Privacy and PII handling

1. Hard-deny: PII / secrets are stripped before transport

The SDK strips a built-in set of property keys before the event leaves the customer process. Caller-supplied denied_keys are added on top of DEFAULT_DENIED_KEYS — they cannot remove a default-denied key.

Hard-deny categories (case- and separator-insensitive — userEmail, user-email, USER_EMAIL, email_address all match):

• Auth credentials: authorization, cookie, set-cookie, password, passwd, secret, token, access_token, refresh_token, session, session_token, api_key, apikey, private_key
• PII categories: email, phone, credit_card, ssn

This list is a strict superset of the server-side ingest hard-deny (@cluebase/shared INGEST_HARD_DENY_KEYS), enforced by the tests/test_privacy_parity.py cross-SDK parity test.

2. HTTP request values

This SDK does not read HTTP request or response bodies. The value surface it can observe is the request query, and its values are masked by default. A value is sent in plaintext only when the customer names that field on the Cluebase screen; the decision is delivered to the SDK and re-checked by ingest. Hard-denied keys such as email can never be released, whatever the screen says. See docs/system/architecture/sdk/backend-sdk.md for the boundary and for what would be required to bring bodies into scope.

3. Analysis projection and later registration

Properties that pass the hard-deny gate are projected by default unless a cardinality, free-text, or complex-value guard keeps them out of the analysis index. Guarded non-private values remain available in analysisProperties.raw_only so they can be registered and promoted later. The map stores each original value as JSON so its type can be restored. Hard-denied values are dropped and never stored in raw_only. After a privacy review, use the project service allowlist to promote a guarded non-private property into the analysis projection.

4. Identity traits stay privacy-safe

cluebase.identify(user_id, traits={...}) accepts profile traits such as name, email, and avatarUrl. Other customer-defined values remain generic subject traits instead of becoming fixed Cluebase profile fields. Use a stable opaque user_id; the SDK converts email into privacy-safe contact-derived fields before canonical identity events leave the process.

Build / test

The wheel bundles the compiled Rust core (crates/cluebase-sdk-core-py) as cluebase_backend_sdk._native through maturin, so building from source needs a Rust toolchain. Published wheels already contain the extension; installing one needs nothing beyond pip.

rustup toolchain install stable
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[test]'
python -m pytest