billdogeng 1.0.0b1

Official BilldogEng server SDK for Python — Analytics, Feature Flags (remote + local eval), Surveys, Messaging, and LLM observability.

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": "[e-mail]", "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

Option	Default	Description
host	https://api.billdog.io/v1	Base URL for all requests
flush_at	20	Batch size that triggers a flush
flush_interval	10000	Background flush cadence (ms)
max_queue_size	1000	Max queued events before oldest are dropped
gzip	True	Gzip request bodies large enough to benefit
local_evaluation	False	Enable local (server-side) flag evaluation
request_timeout	10000	Per-request timeout (ms)
max_retries	3	Retry attempts for 5xx / network errors
group_type_index	None	Stable group-type → positional index map

Auth: x-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.