cluebase-backend-sdk 0.0.1__py3-none-any.whl

cluebase_backend_sdk/__init__.py

@@ -0,0 +1,484 @@
+"""Cluebase Backend SDK (Python) public API.
+
+The package exposes a single ``cluebase`` namespace object with ten methods:
+``init`` / ``identify`` / ``group`` / ``reset`` / ``track`` / ``set_consent`` /
+``link`` / ``flush`` / ``close`` / ``get_diagnostics``. Python options use
+snake_case names.
+
+Idiomatic usage::
+
+    from cluebase_backend_sdk import cluebase
+
+    cluebase.init({
+        "endpoint": "https://api.example.com",
+        "project_key": "pk_prod_...",
+        "api_key": "cluebasesk_...",
+        "service_key": "backend-api",
+    })
+    cluebase.identify("user_123", {"name": "Alice", "email": "alice@example.com"})
+    cluebase.group("organization", "org_42", {"name": "Acme"})
+    cluebase.track("checkout_completed", {"plan": "pro"})
+    cluebase.set_consent("granted")
+    await cluebase.flush()
+    await cluebase.close()
+
+Framework integrations import runtime helpers from their owning modules; the
+package root is the customer-facing facade plus stable setup helpers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Literal, TypeAlias, TypedDict
+
+from ._init_options import (
+    CluebaseInitInput,
+    CluebaseInitOptions,
+    CluebaseSdkCollectionMode,
+    _resolve_init_options,
+    _validate_init_options,
+)
+from ._internal_log import get_logger
+from ._version import __version__
+from .exporter.client import CluebasePythonClient
+from .exporter.diagnostics import DiagnosticSnapshot
+from .exporter.privacy import (
+    DEFAULT_DENIED_KEYS,
+    JsonValue,
+    build_mask_token,
+    safe_sanitize_object,
+)
+from .instrumentation.celery import instrument_celery_signals
+from .instrumentation.httpx import instrument_httpx, reset_httpx_instrumentation
+from .instrumentation.orm import instrument_django_orm, instrument_sqlalchemy_orm
+from .instrumentation.requests import (
+    instrument_requests,
+    reset_requests_instrumentation,
+)
+from .provider.bootstrap import (
+    CluebasePythonBootstrapConfig,
+    build_otel_environment,
+    configure_opentelemetry_environment,
+    default_traces_endpoint_from_ingest_endpoint,
+    initialize_opentelemetry,
+    load_bootstrap_config,
+    require_opentelemetry,
+)
+from .provider.resources import (
+    CluebasePythonResourceConfig,
+    build_resource_attributes,
+    serialize_resource_attributes,
+)
+from .provider.runtime import (
+    CluebaseCommand,
+    CluebasePythonSettings,
+    CluebaseStateTransition,
+    CluebaseSetOperationDiscriminator,
+    CluebaseToolCall,
+    annotate_current_otel_span,
+    build_settings,
+    clear_configured_settings,
+    close_shared_clients,
+    configure_settings,
+    create_client,
+    create_request_context,
+    emit_sdk_initialized,
+    enqueue_client_events,
+    flush_shared_clients,
+    get_current_client,
+    get_current_consent,
+    get_current_context,
+    load_settings,
+    reset_current_state,
+    set_current_state,
+)
+from .provider.runtime import (
+    CluebaseIdentify as _internal_identify,
+)
+from .provider.runtime import (
+    CluebaseLink as _internal_link,
+)
+from .provider.runtime import (
+    CluebaseLogout as _internal_logout,
+)
+from .provider.runtime import (
+    CluebaseSetOrganization as _internal_set_organization,
+)
+from .provider.runtime import (
+    CluebaseTrack as _internal_track,
+)
+from .provider.runtime import (
+    clear_current_state as _clear_current_state,
+)
+from .provider.runtime import (
+    get_diagnostics as _get_runtime_diagnostics,
+)
+from .provider.runtime import (
+    set_consent as _set_runtime_consent,
+)
+
+_logger = get_logger("public")
+
+
+# ---------------------------------------------------------------------------
+# Public namespace types (= mirror the Frontend SDK's `CluebaseGroupType` /
+# `CluebaseGroupTraits` / `CluebaseConsentState`).
+# ---------------------------------------------------------------------------
+
+
+CluebaseGroupType = Literal["organization"]
+"""MVP group taxonomy. Customer company grouping is represented as
+``organization``. ``account`` / ``workspace`` are future concepts and are not
+public ``cluebase.group`` inputs for MVP."""
+
+
+CluebaseConsentState = Literal["granted", "denied", "unknown"]
+"""Process-wide collection consent state."""
+
+"""SDK collection mode accepted by ``cluebase.init``."""
+
+CluebasePublicTraits: TypeAlias = Mapping[str, object]
+"""Free-form customer traits accepted by ``cluebase.identify`` and ``cluebase.group``."""
+
+CluebasePublicProperties: TypeAlias = Mapping[str, object]
+"""Free-form customer event properties accepted by ``cluebase.track``."""
+
+CluebasePublicMetrics: TypeAlias = Mapping[str, object]
+"""Free-form customer event metrics accepted by ``cluebase.track``."""
+
+
+class CluebaseGroupTraits(TypedDict, total=False):
+    """Optional traits attached to ``cluebase.group(...)``. ``name`` is recommended
+    (human-readable label used downstream by analysis surfaces); other keys are
+    free-form and forwarded as event properties subject to ``denied_keys``."""
+
+    name: str
+
+
+class CluebaseLinkSubject(TypedDict):
+    type: CluebaseGroupType
+    id: str
+
+
+class CluebaseExternalIdentity(TypedDict):
+    namespace: str
+    id: str
+
+
+class CluebaseLinkInput(TypedDict):
+    subject: CluebaseLinkSubject
+    external: CluebaseExternalIdentity
+
+
+class CluebaseSubjectTraits(TypedDict, total=False):
+    """Optional traits attached to ``cluebase.identify(user_id, traits)``. The
+    ``name`` field is *strongly* recommended because analysis surfaces must not
+    display the raw user_id as a person label. ``email`` is converted to
+    privacy-safe contact-derived fields before transport.
+
+    Field naming exception: keys are **camelCase** even on the Python SDK
+    (``avatarUrl``), not the usual Python ``snake_case``.
+    This honours the cross-SDK customer-facing contract documented in
+    ``docs/contracts/sdk/public-api.md`` §1.6 — every SDK
+    (Browser / Node / Python) accepts the same trait keys so customers can
+    copy idiomatic examples between languages without renaming fields.
+    The ingest core normalizes these values after receiving SDK source signals."""
+
+    name: str
+    email: str
+    emailAddress: str
+    displayName: str
+    avatarUrl: str
+
+
+
+
+"""Runtime input accepted by ``cluebase.init``; mapping form preserves public SDK flexibility."""
+
+
+# ---------------------------------------------------------------------------
+# Safe-call helpers — the SDK guarantees never to crash the host application,
+# even if a hot path raises. We log the swallowed exception via the SDK's
+# internal diagnostic logger so operators can opt-in to debug output.
+# ---------------------------------------------------------------------------
+
+
+def _report_public_sdk_error(operation: str, error: BaseException) -> None:
+    _ = error
+    # `_logger` は `SafeLogger` で、記録に失敗しても自分で飲み込みます
+    # （`_safe_logger.py`）。ここで受け口を重ねても、通ることがありません
+    _logger.warning(
+        "cluebase.sdk public operation failed operation=%s code=public_operation_failed",
+        operation,
+    )
+
+
+def _safe_call(operation: str, callback: Callable[[], object]) -> None:
+    try:
+        callback()
+    except BaseException as exc:  # noqa: BLE001 — last-resort host protection
+        _report_public_sdk_error(operation, exc)
+
+
+async def _safe_async_call(
+    operation: str, callback: Callable[[], Awaitable[object]]
+) -> None:
+    try:
+        await callback()
+    except BaseException as exc:  # noqa: BLE001 — last-resort host protection
+        _report_public_sdk_error(operation, exc)
+
+
+# ---------------------------------------------------------------------------
+# `cluebase.init` maps Python setup options onto runtime bootstrap settings.
+# ---------------------------------------------------------------------------
+
+
+
+
+
+
+
+
+
+
+# ``allowed_value_paths`` used to let the caller name the request/response
+# fields that may leave the process in clear text. That choice now belongs to
+# the Cluebase privacy screen and reaches the SDK through the delivered privacy
+# policy, so the option has nothing left to apply to.
+
+
+
+
+# ---------------------------------------------------------------------------
+# `cluebase` namespace — module-level singleton facade. The object is module-level
+# so multiple imports in the same process share state, exactly like the
+# Frontend SDK's ``globalThis.__cluebase_frontend_sdk_singleton__`` pattern.
+# ---------------------------------------------------------------------------
+
+
+class _Cluebase:
+    """Cluebase Backend SDK public namespace.
+
+    Ten methods mirror the cross-SDK contract documented in
+    ``docs/contracts/sdk/public-api.md`` §1.6. Every method
+    swallows exceptions and reports them via the SDK internal logger; the SDK
+    is contractually forbidden from crashing the host application.
+    """
+
+    __slots__ = ()
+
+    def _allows_collection(self) -> bool:
+        return get_current_consent() != "denied"
+
+    def init(self, options: CluebaseInitInput) -> None:
+        """Initialise the SDK. ``endpoint``, ``project_key``, ``api_key``, and
+        ``service_key`` are required; a missing one raises ``ValueError`` rather
+        than leaving the SDK collecting nothing. Calling ``init`` twice is a
+        no-op (= the bootstrap layer guards against duplicate TracerProvider
+        wiring)."""
+
+        # Raised before ``_safe_call`` so the caller actually sees it; see
+        # ``_validate_init_options``.
+        _validate_init_options(options)
+
+        def _do_init() -> None:
+            bootstrap_config, settings = _resolve_init_options(options)
+            require_opentelemetry(bootstrap_config)
+            configure_settings(settings)
+            emit_sdk_initialized(settings)
+
+        _safe_call("init", _do_init)
+
+    def identify(
+        self,
+        user_id: str,
+        traits: CluebasePublicTraits | None = None,
+    ) -> None:
+        """Bind the caller-supplied subject identity to subsequent events.
+        ``traits['name']`` is strongly recommended because analysis surfaces must
+        not display the raw user_id as a person label. ``traits['email']`` is
+        converted to privacy-safe contact-derived fields before transport."""
+
+        if not self._allows_collection():
+            return
+
+        _safe_call("identify", lambda: _internal_identify(user_id, traits or {}))
+
+    def group(
+        self,
+        group_type: str,
+        group_key: str,
+        traits: CluebasePublicTraits | None = None,
+    ) -> None:
+        """Associate the caller with a customer company."""
+
+        def _dispatch() -> None:
+            resolved_traits = traits or {}
+            if group_type != "organization":
+                raise ValueError(
+                    f"cluebase.group: unsupported group_type {group_type!r}; "
+                    "expected 'organization'"
+                )
+            if not self._allows_collection():
+                return
+
+            _internal_set_organization(group_key, resolved_traits)
+
+        _safe_call("group", _dispatch)
+
+    def reset(self) -> None:
+        """Clear identity state. ``logout`` and the in-memory reset are wrapped
+        in independent ``_safe_call`` invocations so one failing does not
+        short-circuit the other (= state must be cleared as best-effort)."""
+
+        if self._allows_collection():
+            _safe_call("reset", lambda: _internal_logout())
+        _safe_call("reset", _clear_current_state)
+
+    def link(self, link_input: CluebaseLinkInput | Mapping[str, object]) -> None:
+        """Record a canonical organization to external identifier fact."""
+
+        if not self._allows_collection():
+            return
+        _safe_call("link", lambda: _internal_link(link_input))
+
+    def track(
+        self,
+        event_name: str,
+        properties: CluebasePublicProperties | None = None,
+        metrics: CluebasePublicMetrics | None = None,
+    ) -> None:
+        """Emit a custom event with the same
+        ``track(event_name, properties=None, metrics=None)`` public contract as
+        the Browser and Node SDKs."""
+
+        if not self._allows_collection():
+            return
+
+        _safe_call("track", lambda: _internal_track(event_name, properties, metrics))
+
+    def set_operation_discriminator(self, value: str) -> None:
+        """Annotate the active backend operation with a mechanical branch key."""
+
+        _safe_call(
+            "set_operation_discriminator",
+            lambda: CluebaseSetOperationDiscriminator(value),
+        )
+
+    def set_consent(self, consent: str) -> None:
+        """Record the caller's analytics consent state. Accepted values
+        (Literal): ``"granted"`` / ``"denied"`` / ``"unknown"``. ``denied``
+        makes later collection calls no-op; changing back to ``granted`` or
+        ``unknown`` resumes collection."""
+
+        def _set_state() -> None:
+            if consent not in ("granted", "denied", "unknown"):
+                raise ValueError(
+                    f"cluebase.set_consent: unsupported value {consent!r}; "
+                    "expected one of 'granted' / 'denied' / 'unknown'"
+                )
+            _set_runtime_consent(consent)
+
+        _safe_call("set_consent", _set_state)
+
+    async def flush(self) -> None:
+        """Force-flush every buffered shared client. Awaited so callers can
+        ``await cluebase.flush()`` before shutdown — the underlying flush is
+        synchronous but we expose it as a coroutine for cross-SDK signature
+        parity (= Frontend SDK is async)."""
+
+        async def _run() -> None:
+            await asyncio.to_thread(flush_shared_clients)
+
+        await _safe_async_call("flush", _run)
+
+    async def close(self) -> None:
+        """Stop capture and close the canonical delivery lifecycle."""
+
+        async def _run() -> None:
+            await asyncio.to_thread(close_shared_clients)
+
+        await _safe_async_call("close", _run)
+
+    def get_diagnostics(self) -> DiagnosticSnapshot:
+        """Return a defensive, privacy-safe runtime diagnostics snapshot."""
+
+        return _get_runtime_diagnostics()
+
+
+cluebase = _Cluebase()
+"""Module-level singleton. Import as ``from cluebase_backend_sdk import cluebase``."""
+
+CluebaseIdentify = _internal_identify
+CluebaseLink = _internal_link
+CluebaseLogout = _internal_logout
+CluebaseSetOrganization = _internal_set_organization
+CluebaseTrack = _internal_track
+
+
+# ---------------------------------------------------------------------------
+# Helper exports for framework integrations.
+__all__ = [
+    "DEFAULT_DENIED_KEYS",
+    "CluebaseCommand",
+    "CluebaseConsentState",
+    "CluebaseGroupTraits",
+    "CluebaseGroupType",
+    "CluebaseIdentify",
+    "CluebaseExternalIdentity",
+    "CluebaseLink",
+    "CluebaseInitInput",
+    "CluebaseInitOptions",
+    "CluebaseLinkInput",
+    "CluebaseLinkSubject",
+    "CluebaseLogout",
+    "CluebasePublicMetrics",
+    "CluebasePublicProperties",
+    "CluebasePublicTraits",
+    "CluebasePythonBootstrapConfig",
+    "CluebasePythonClient",
+    "CluebasePythonResourceConfig",
+    "CluebasePythonSettings",
+    "CluebaseSdkCollectionMode",
+    "CluebaseSetOrganization",
+    "CluebaseSetOperationDiscriminator",
+    "CluebaseStateTransition",
+    "CluebaseSubjectTraits",
+    "CluebaseToolCall",
+    "CluebaseTrack",
+    "JsonValue",
+    "__version__",
+    "annotate_current_otel_span",
+    "build_mask_token",
+    "build_otel_environment",
+    "build_resource_attributes",
+    "build_settings",
+    "clear_configured_settings",
+    "cluebase",
+    "configure_opentelemetry_environment",
+    "configure_settings",
+    "create_client",
+    "create_request_context",
+    "default_traces_endpoint_from_ingest_endpoint",
+    "emit_sdk_initialized",
+    "enqueue_client_events",
+    "flush_shared_clients",
+    "get_current_client",
+    "get_current_context",
+    "initialize_opentelemetry",
+    "instrument_celery_signals",
+    "instrument_django_orm",
+    "instrument_httpx",
+    "instrument_requests",
+    "instrument_sqlalchemy_orm",
+    "load_bootstrap_config",
+    "load_settings",
+    "reset_current_state",
+    "reset_httpx_instrumentation",
+    "reset_requests_instrumentation",
+    "safe_sanitize_object",
+    "serialize_resource_attributes",
+    "set_current_state",
+]

cluebase_backend_sdk/_cluebase_authored_attributes.py

@@ -0,0 +1,37 @@
+"""配る部品**自身が測った値**を封筒に載せる時の、属性の名前。
+
+顧客が ``track`` で付けた項目は ``cluebase.properties.<綴り>`` /
+``cluebase.metrics.<綴り>`` という封筒で運ばれます。**配る部品も同じ封筒を使う**
+ため、封筒を開けた受け口から見ると、顧客が名付けた業務項目と、部品が測った値の
+区別が付きません。
+
+実際にそれが起きました。分析が ``duration_ms`` を顧客の業務項目だと解釈し、
+利用者へ**「duration_ms を測りました」**と答えました（実測 2026-08-15）。
+
+そこで、部品が測った値は封筒の中で**予約された名前**（``cluebase.`` で始まる）を
+名乗ります。顧客の項目がこの接頭辞を持つことはないため、封筒を開けた時点で
+混ざりません。**顧客が偶然 ``queue_name`` という業務項目を送ってきても、それは
+顧客のものとして扱われます。**
+
+**顧客が渡した項目には使いません。** 顧客の綴りをここへ通すと、その項目が
+仕組みのものとして扱われ、分析に出なくなります。
+"""
+
+from __future__ import annotations
+
+RESERVED_FIELD_KEY_PREFIX = "cluebase."
+
+_PROPERTY_ENVELOPE_PREFIX = "cluebase.properties."
+_METRIC_ENVELOPE_PREFIX = "cluebase.metrics."
+
+
+def cluebase_authored_property_attribute(name: str) -> str:
+    """部品自身が測った値（文字列など）の属性名。"""
+
+    return f"{_PROPERTY_ENVELOPE_PREFIX}{RESERVED_FIELD_KEY_PREFIX}{name}"
+
+
+def cluebase_authored_metric_attribute(name: str) -> str:
+    """部品自身が測った値（数値）の属性名。"""
+
+    return f"{_METRIC_ENVELOPE_PREFIX}{RESERVED_FIELD_KEY_PREFIX}{name}"

cluebase_backend_sdk/_generated/__init__.py

@@ -0,0 +1,11 @@
+"""自動生成です。**手で編集しないでください。**
+
+正本: packages/cluebase-shared/src/ingest/ingest-privacy-policy.v1.json
+出し直す: node scripts/generate-shared-contract-tables.mjs
+
+正本を直したらこの file も一緒に commit してください。CI が
+``node scripts/generate-shared-contract-tables.mjs --check`` で照合し、ずれていれば落とします。
+"""
+
+#: 生成物を出し直す命令。**この綴りを他所へ写さないでください。**
+REGENERATE_COMMAND = "node scripts/generate-shared-contract-tables.mjs"

cluebase_backend_sdk/_generated/correlation_attribute_keys.py

@@ -0,0 +1,37 @@
+"""自動生成です。**手で編集しないでください。**
+
+正本: packages/cluebase-backend-contract/src/delivery/correlation-attribute-keys.v1.json
+出し直す: node scripts/generate-shared-contract-tables.mjs
+
+正本を直したらこの file も一緒に commit してください。CI が
+``node scripts/generate-shared-contract-tables.mjs --check`` で照合し、ずれていれば落とします。
+"""
+
+from __future__ import annotations
+
+#: 伏せる処理を通しても残す、相関のための属性名。
+CLUEBASE_CORRELATION_ATTRIBUTE_KEYS: frozenset[str] = frozenset((
+    "cluebase.actor.anonymous_id",
+    "cluebase.actor.user_id",
+    "cluebase.interaction.id",
+    "cluebase.interaction_id",
+    "cluebase.organization.id",
+    "cluebase.organization_id",
+    "cluebase.origin_frontend_interaction.id",
+    "cluebase.parent_request_span_id",
+    "cluebase.parent_span_id",
+    "cluebase.request.id",
+    "cluebase.request_id",
+    "cluebase.request_span_id",
+    "cluebase.session.id",
+    "cluebase.session_id",
+    "cluebase.span_id",
+    "cluebase.subject.organization_id",
+    "cluebase.tab.id",
+    "cluebase.tab_id",
+    "cluebase.trace_id",
+    "enduser.id",
+    "mcp.client.name",
+    "mcp.client.version",
+    "mcp.session.id",
+))

cluebase_backend_sdk/_generated/identity_pii_policy.py

@@ -0,0 +1,62 @@
+"""自動生成です。**手で編集しないでください。**
+
+正本: packages/cluebase-shared/src/ingest/identity-pii-policy.v1.json
+出し直す: node scripts/generate-shared-contract-tables.mjs
+
+正本を直したらこの file も一緒に commit してください。CI が
+``node scripts/generate-shared-contract-tables.mjs --check`` で照合し、ずれていれば落とします。
+"""
+
+from __future__ import annotations
+
+#: 見る順序。先に当たった種類を返します。
+PII_CATEGORY_ORDER: tuple[str, ...] = (
+    "email",
+    "ssn",
+    "phone",
+    "credit_card",
+)
+
+#: 電子メールの形。
+PII_EMAIL_PATTERN = "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$"
+
+#: 社会保障番号の形。
+PII_SSN_PATTERN = "^\\d{3}-\\d{2}-\\d{4}$"
+
+#: 電話とみなす桁数の範囲と、見た目・求める区切り。
+PII_PHONE_MIN_DIGITS = 7
+PII_PHONE_MAX_DIGITS = 15
+PII_PHONE_SHAPE_PATTERN = "^[+()0-9.\\-\\s]+$"
+PII_PHONE_SEPARATOR_PATTERN = "[+().\\-\\s]"
+
+#: 支払い用の番号とみなす桁数の範囲と見た目。Luhn の検算を必ず通します。
+PII_CREDIT_CARD_MIN_DIGITS = 13
+PII_CREDIT_CARD_MAX_DIGITS = 19
+PII_CREDIT_CARD_SHAPE_PATTERN = "^[0-9\\s\\-]+$"
+
+#: 伏せた値の形。同じ入力なら配る部品 3 つとも同じ値になります。
+PII_HASH_PREFIX = "cluebase_pii_hashed:"
+PII_HASH_HEX_LENGTH = 32
+
+#: どの面の規則か（読み手が取り違えないため）。
+PII_SURFACE = "whole_value_is_pii"
+
+
+def passes_luhn(digits: str) -> bool:
+    """Luhn の検算。支払い用の番号らしさを、無作為な数字の並びと分けます。
+
+    **手順もここから出します。** 桁数と綴りだけを正本化して手順を手書きで
+    残すと、同じ算法が 4 か所に残ります。実際に残っていました。
+    """
+
+    total = 0
+    alt = False
+    for ch in reversed(digits):
+        n = int(ch)
+        if alt:
+            n *= 2
+            if n > 9:
+                n -= 9
+        total += n
+        alt = not alt
+    return total % 10 == 0