Metadata-Version: 2.4
Name: billdogeng
Version: 1.0.0b1
Summary: Official BilldogEng server SDK for Python — Analytics, Feature Flags (remote + local eval), Surveys, Messaging, and LLM observability.
Project-URL: Homepage, https://billdog.io
Project-URL: Repository, https://github.com/billdog/billdogeng-python
Author: BillDog
License: MIT
Keywords: analytics,billdog,billdogeng,feature-flags,llm,messaging,server-sdk,surveys
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install billdogeng
```

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

## Quickstart

```python
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

| 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

```bash
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.
