moolabs 0.3.0__tar.gz

moolabs-0.3.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: moolabs
+Version: 0.3.0
+Summary: Moolabs API
+Home-page: https://github.com/moolabs-hq/moolabs-py
+Author: OpenAPI Generator community
+Author-email: team@openapitools.org
+License: Apache-2.0
+Keywords: OpenAPI,OpenAPI-Generator,Moolabs API
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: urllib3<3.0.0,>=1.25.3
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: pydantic>=2
+Requires-Dist: typing-extensions>=4.7.1
+Requires-Dist: opentelemetry-api==1.27.0
+Requires-Dist: opentelemetry-sdk==1.27.0
+Requires-Dist: SQLAlchemy<2.1,>=1.4.54
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+    Unified Moolabs SDK. Capability-based public surface stitched from internal service specs: bff, meter, arc, acute. Customers see capability namespaces (usage, billing, collections, etc.); the SDK routes per-operation internally.
+    

moolabs-0.3.0/README.md

@@ -0,0 +1,374 @@
+# Moolabs Python SDK
+
+Unified Python SDK for the Moolabs platform. One package, one client, one auth flow — covers both billing (CLS) and usage (Meter) operations.
+
+```python
+from moolabs import Moolabs
+
+client = Moolabs(api_key="moo_live_...")
+
+# Wallet and credit operations route to the correct backend automatically.
+wallet = client.wallets.create_wallet(...)
+grants = client.credits.list_grants(...)
+
+# Usage and subscription operations use capability namespaces.
+client.usage.ingest_events([...])
+meters = client.usage.list_meters()
+```
+
+## Install
+
+```bash
+pip install moolabs
+```
+
+Requires Python 3.10+.
+
+### Optional PostgreSQL DB-time attribution
+
+Install the supported SQLAlchemy and OpenTelemetry versions plus one supported
+PostgreSQL driver. This example uses psycopg 3:
+
+```bash
+pip install \
+  moolabs \
+  'SQLAlchemy>=1.4.54,<2.1' \
+  'opentelemetry-api==1.27.0' \
+  'opentelemetry-sdk==1.27.0' \
+  'psycopg[binary]>=3.1.18,<4'
+```
+
+The supported matrix is Python `>=3.10,<3.13`, SQLAlchemy
+`>=1.4.54,<2.1`, OpenTelemetry API and SDK exactly `1.27.0`, and one of:
+
+| SQLAlchemy driver | Supported version | Engine |
+|---|---|---|
+| `psycopg2` | `>=2.9.9,<3` | synchronous PostgreSQL `Engine` |
+| `psycopg` | `>=3.1.18,<4` | synchronous PostgreSQL `Engine` |
+| `asyncpg` | `>=0.29,<1` | real `AsyncEngine` |
+
+Configure the OpenTelemetry root sampler probability to equal the declared
+`sample_rate`. `AlwaysOnSampler` requires `sample_rate=1.0`; a sampled rate
+uses `TraceIdRatioBased` directly or as the root of `ParentBased`.
+
+```python
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.sampling import ParentBased, TraceIdRatioBased
+from sqlalchemy import create_engine
+
+provider = TracerProvider(
+    sampler=ParentBased(root=TraceIdRatioBased(0.10)),
+)
+orders = create_engine("postgresql+psycopg://...")
+
+handle = client.attribution.instrument_sqlalchemy(
+    orders,
+    service="checkout-api",
+    pool_key="orders-primary",
+    sample_rate=0.10,
+    tracer_provider=provider,
+)
+
+# At application shutdown, close the client (or this handle directly).
+client.close()
+```
+
+Register each engine once. `pool_key` is a stable logical name for the exact
+RDS/Aurora pool mapped in ACUTE; it is not a database URL or automatically
+discovered resource ID. The API key authenticates and binds every evidence
+batch to its tenant, so no tenant identifier is accepted from application
+code. Each query receives only an opaque comment shaped as
+`/*moolabs_db_time:v1;ob=<32 lowercase hex>*/`. SQL text, bind values,
+database URLs, raw request IDs, and raw thread IDs are never added to the
+dedicated span or evidence request.
+
+For prefork servers, create a child-owned Moolabs client and child-owned tracer provider,
+then call `instrument_sqlalchemy` after the worker process forks. Do
+not instrument in the preload or master process. If the SQLAlchemy engine was
+created before the fork, call `engine.dispose(close=False)` in each child before
+its first database use, or create the engine in the child instead. An inherited
+handle is inert. The SDK rejects providers it already registered in the parent
+and refuses a locked OpenTelemetry processor registrar without blocking, but it
+cannot prove that an otherwise unlocked, never-registered provider was inherited;
+never reuse a parent provider. Stateful use of an inherited client or attribution
+facade fails before taking parent-owned locks, while inherited `client.close()` is
+inert during child teardown.
+
+DB-time evidence must be paired with an explicit non-DB-time fallback signal
+in the ACUTE driver rule. Missing, zero-weight, dropped, gapped, or late
+DB-time evidence selects that fallback; the two sources are never blended.
+Call `client.close()` during application shutdown so listeners are removed,
+in-flight sampled statements receive the bounded grace period, and final
+windows drain. Closing instrumentation never closes the application engine or
+the global tracer provider.
+
+This integration supports SQLAlchemy event instrumentation only. PostgreSQL
+slow-query logs, normalized server-side query statistics, and other SQL
+collectors are not supported by this SDK surface.
+
+## Authentication
+
+Generate an API key in your Moolabs dashboard. The same key authenticates every capability; the SDK handles backend routing internally.
+
+```python
+from moolabs import Moolabs
+
+client = Moolabs(api_key="moo_live_...")
+```
+
+For staging or private deployments, override the base URLs:
+
+```python
+client = Moolabs(
+    api_key="moo_test_...",
+    base_url="staging.moolabs.com",
+)
+```
+
+## Capability namespaces
+
+The SDK exposes customer-facing capabilities directly. A capability can combine
+operations from several Moolabs services while routing each call to the correct
+backend.
+
+| Namespace | Purpose |
+|---|---|
+| `client.usage` | Event ingest and meter queries |
+| `client.customers` | Customers and their subjects |
+| `client.catalog` | Products, plans, features, and rate cards |
+| `client.subscriptions` | Subscription lifecycle |
+| `client.entitlements` | Feature-access checks and grants |
+| `client.wallets` | Wallet lifecycle, balances, and thresholds |
+| `client.credits` | Grants, ledger entries, and auto-topup |
+| `client.billing` | Invoicing, rating, and FX rates |
+| `client.collections` | Accounts receivable and collections |
+| `client.cost` | AI cost-event ingestion |
+| `client.notifications` | Notification channels and alerts |
+| `client.events` | Unified usage and cost event ingest |
+| `client.attribution` | Request context, propagation, and DB-time instrumentation |
+
+## Quickstart — typical usage flows
+
+### Ingest usage events
+
+```python
+client.usage.ingest_events([
+    {
+        "id": "evt_unique_id",
+        "type": "api.request",
+        "subject": "user_42",
+        "time": "2026-01-15T10:30:00Z",
+        "data": {"endpoint": "/v1/predict", "tokens": 1500},
+    }
+])
+```
+
+### Unified ergonomic ingest (recommended)
+
+The unified surface added in PR #439 lets you emit events with named
+kwargs instead of hand-rolling CloudEvent envelopes. The SDK builds the
+envelope, validates required fields synchronously (FR-6), and routes
+through the same buffer + retry path. Three methods cover the three
+shapes of event the platform accepts:
+
+```python
+# Usage-lane event — meter_slug + value required.
+client.usage.ingest_event(
+    event_type="ai.chat",
+    customer_id="cust_42",
+    entity_id="req_abc",           # threads to data.request_id on the wire
+    meter_slug="llm_tokens",
+    value=724,
+    source="my-app/v2.3.1",        # optional; defaults to "moolabs-sdk"
+    meta={"feature": "ai_chat"},   # optional; lands at data.meta nested
+)
+
+# Cost-lane event — per-span breakdown for AI cost intelligence.
+# Cost-lane spans MUST carry "provider" and "model" — the SDK rejects
+# spans missing either at the call site, since downstream cost
+# processing silently drops them otherwise.
+client.cost.ingest_event(
+    event_type="ai.chat.cost",
+    customer_id="cust_42",
+    entity_id="req_abc",           # same entity_id correlates the two
+    spans=[
+        {"span_id": "sp_chat", "provider": "openai", "model": "gpt-4o-mini",
+         "tokens": 724, "cost": 0.000724},
+    ],
+)
+
+# Dual-lane event — usage + cost emitted in one call.
+client.events.ingest(
+    event_type="ai.chat",
+    customer_id="cust_42",
+    entity_id="req_abc",
+    meter_slug="llm_tokens",
+    value=844,
+    spans=[{"span_id": "sp_embed", "provider": "openai",
+            "model": "text-embedding-3-small",
+            "tokens": 120, "cost": 0.00000018}],
+)
+```
+
+Each returns an `IngestResult` with `event_id`, `transport` (`"buffered"`
+when the G5 buffer enqueued the call non-blocking, `"sync"` when strict-
+sync mode posted inline), and a client-side `accepted_at` timestamp.
+
+`tenant_id` is intentionally NOT a kwarg — the server derives tenant
+identity from the API key.
+
+#### Canonical well-known data fields
+
+These seven AI-event fields are first-class kwargs and land at
+`data.<key>` directly on the wire (snake_case). Use them — don't bury
+them in `meta=`. Free-form fields keep going through `meta=` and nest
+at `data.meta.<key>`.
+
+| kwarg | wire | example |
+|---|---|---|
+| `provider` | `data.provider` | `"openai"` |
+| `model` | `data.model` | `"gpt-4o"` |
+| `total_input_tokens` | `data.total_input_tokens` | `1250` |
+| `total_output_tokens` | `data.total_output_tokens` | `3800` |
+| `total_tokens` | `data.total_tokens` | `5050` |
+| `latency_ms` | `data.latency_ms` | `2340` |
+| `status` | `data.status` | `"success"` |
+
+```python
+client.usage.ingest_event(
+    event_type="ai.completion",
+    customer_id="cust_acme_42",
+    entity_id="req_a1b2c3d4",
+    meter_slug="ai_tokens",
+    value=1,
+    provider="openai",
+    model="gpt-4o",
+    total_input_tokens=1250,
+    total_output_tokens=3800,
+    total_tokens=5050,
+    latency_ms=2340,
+    status="success",
+    meta={"feature_key": "ai_chat"},   # customer-defined → data.meta.feature_key
+)
+```
+
+Spans on the cost lane use `span_id` (snake_case) as the dedup grain
+moo-acute reads. Always emit `span_id` — not `spanId`.
+
+### Pointing the SDK at a non-default ingest host
+
+For self-hosted deployments, preview environments, or hybrid setups
+where the ingest endpoint differs from the canonical apex, set
+`MOOLABS_INGEST_HOST` and the SDK will use it instead of the F2 region
+fallback:
+
+```bash
+export MOOLABS_INGEST_HOST=meter.dev.moolabs.com     # bare host (https:// added)
+# OR
+export MOOLABS_INGEST_HOST=https://my-relay.example.com
+```
+
+Accepts a bare hostname (https:// auto-prefixed) or a full URL. Mirrored
+on TypeScript (`process.env.MOOLABS_INGEST_HOST`) and Go (`os.Getenv`).
+Empty string is treated as unset and the F2 chain runs normally.
+
+### Check entitlement
+
+```python
+result = client.entitlements.check_entitlement(
+    subject="user_42",
+    feature="ai-credits",
+)
+if result.granted:
+    # serve the request
+    ...
+```
+
+### Create a wallet + grant credits
+
+```python
+wallet = client.wallets.create_wallet(
+    tenant_id="tenant_xyz",
+    pool_id="pool_abc",
+    owner_type="USER",
+    owner_id="user_42",
+)
+
+client.credits.create_grant(
+    wallet_id=wallet.id,
+    amount="100.00",
+    expires_at="2026-12-31T23:59:59Z",
+)
+```
+
+## Error handling
+
+All errors inherit from `MoolabsError`. Specific subclasses for HTTP status families:
+
+```python
+from moolabs import (
+    Moolabs,
+    MoolabsError,
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    RetryableError,
+)
+
+client = Moolabs(api_key="moo_live_...")
+
+try:
+    wallet = client.wallets.create_wallet(...)
+except AuthenticationError:
+    # 401 — key invalid/expired
+    ...
+except ValidationError as e:
+    # 422 — field-level validation
+    print(e.errors)
+except RateLimitError:
+    # 429 — back off and retry
+    ...
+except RetryableError:
+    # 5xx that's safe to retry
+    ...
+except MoolabsError as e:
+    # any other API error
+    ...
+```
+
+## Webhook signature verification
+
+If you're consuming Moolabs webhooks (notifications, subscription state changes), verify the signature on each delivery:
+
+```python
+from moolabs import WebhookVerifier
+
+verifier = WebhookVerifier(signing_secret="whsec_...")
+
+# Raise on tampering; returns parsed body on success.
+event = verifier.verify(
+    body=request.body,
+    signature=request.headers["X-Moolabs-Signature"],
+)
+```
+
+## Resource cleanup
+
+Use the client as a context manager to release HTTP connections cleanly:
+
+```python
+with Moolabs(api_key="moo_live_...") as client:
+    client.usage.ingest_events([...])
+# Connections closed on exit.
+```
+
+Or call `client.close()` manually.
+
+## Source + issues
+
+- Source mirror: https://github.com/moolabs-hq/moolabs-py
+- Issues + feature requests: https://github.com/moolabs-hq/moolabs-py/issues
+
+This package is auto-generated from the Moolabs OpenAPI specs on every release. Direct edits to the mirror repo will be overwritten on next publish — file an issue or PR against the source if you spot a generation bug.