billdogeng (Python)

Official BilldogEng server SDK for Python — the engagement suite for server-side use: Analytics, Feature Flags (remote + local evaluation), Surveys (data API), Messaging dispatch, and LLM observability.

This is the Python port of the canonical Node reference SDK; the wire protocol and method surface are identical across all billdogeng-* server SDKs.

Install

pip install billdogeng

Zero runtime dependencies (stdlib only). Requires Python 3.8+.

Quickstart

from billdogeng import BilldogEng

bd = BilldogEng("bd_test_xxx", local_evaluation=True)

# Analytics (batched + background flush + gzip + retry)
bd.capture("user-123", "order_completed", {"revenue": 49.99}, {"company": "acme"})
bd.identify("user-123", {"email": "a@b.com", "plan": "pro"})
bd.group_identify("company", "acme", {"seats": 50})
bd.alias("user-123", "anon-abc")

# Feature flags (local evaluation = deterministic murmurhash3 bucketing)
if bd.is_feature_enabled("new_checkout", "user-123"):
    ...
variant = bd.get_feature_flag("pricing_test", "user-123")
payload = bd.get_feature_flag_payload("pricing_test", "user-123")
all_flags = bd.get_all_flags("user-123")

# Surveys (data API — no rendering)
surveys = bd.surveys.list("user-123")
config = bd.surveys.fetch(survey_id, "user-123")
started = bd.surveys.start(survey_id, {"customer_id": "user-123"})
bd.surveys.submit(survey_id, [{"question_id": q, "answer_number": 9}],
                  {"respondent_id": started["respondent_id"]})

# Messaging dispatch (Bearer JWT auth)
bd.messaging.dispatch(
    project_id="…", channel="push",
    content={"title": "Hi", "body": "There"},
    access_token="<supabase-jwt>",
    targeting={"type": "all"},
    scheduling={"deliveryType": "immediate"},
)

# LLM observability
bd.llm.capture_trace(
    trace_id="t-1", span_id="s-1", model="claude-opus-4-8",
    input_text="…", output_text="…",
    prompt_tokens=10, completion_tokens=5, duration_ms=123, cost_usd=0.002,
)

bd.shutdown()  # flushes remaining events + stops the background timer

# Or as a context manager:
with BilldogEng("bd_test_xxx") as bd:
    bd.capture("user-123", "page_view")

Configuration

Auth: X-BillDog-API-Key: <apiKey> on every request (bd_test_* sandbox / bd_live_* live). Messaging dispatch authenticates with a Bearer JWT instead.

Tests

python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest -q

The suite covers: batching (10 captures → 1 POST), identify/group/alias event shapes, the 12 canonical murmurhash3 vectors + rollout/targeting/multivariate evaluation, 503-then-200 retry with backoff (local stub server), and the survey round-trip + messaging dispatch + LLM trace payload shapes.

BillDog Auth

Session-token verification is not available in this SDK yet. billdogeng-node is the only server SDK that can verify a BillDog Auth token offline today.

Until it lands here, either verify in a Node service, or call the auth-introspect endpoint over HTTP — that costs a network round-trip per check, and in exchange tells you whether the session is live right now rather than only that the token was valid when it was issued.