billdogeng 1.0.0b1__tar.gz

billdogeng-1.0.0b1/.gitignore

@@ -0,0 +1,48 @@
+# billdogeng-* SDK fleet — build & dependency artifacts (do not commit)
+
+# JS / TS (node, react, vue, next, svelte, angular, nuxt, astro, capacitor-eng)
+**/node_modules/
+**/dist/
+**/.next/
+**/.nuxt/
+**/.svelte-kit/
+**/.astro/
+**/*.tsbuildinfo
+
+# Python
+**/__pycache__/
+**/.venv/
+**/*.egg-info/
+**/.pytest_cache/
+**/build/
+**/.mypy_cache/
+
+# PHP
+php/vendor/
+**/composer.lock
+
+# Ruby
+ruby/.bundle/
+**/Gemfile.lock
+**/*.gem
+
+# Java / Gradle
+**/.gradle/
+java/build/
+**/*.class
+
+# Rust
+rust/target/
+**/Cargo.lock
+
+# .NET
+**/bin/
+**/obj/
+
+# Elixir
+elixir/_build/
+elixir/deps/
+**/*.ez
+
+# Go
+**/*.test

billdogeng-1.0.0b1/PKG-INFO

@@ -0,0 +1,116 @@
+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.

billdogeng-1.0.0b1/README.md

@@ -0,0 +1,96 @@
+# 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.

billdogeng-1.0.0b1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "billdogeng"
+version = "1.0.0-beta.1"
+description = "Official BilldogEng server SDK for Python — Analytics, Feature Flags (remote + local eval), Surveys, Messaging, and LLM observability."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "BillDog" }]
+requires-python = ">=3.8"
+keywords = [
+    "billdog",
+    "billdogeng",
+    "analytics",
+    "feature-flags",
+    "surveys",
+    "messaging",
+    "llm",
+    "server-sdk",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://billdog.io"
+Repository = "https://github.com/billdog/billdogeng-python"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/billdogeng"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/billdogeng", "README.md", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

billdogeng-1.0.0b1/src/billdogeng/__init__.py

@@ -0,0 +1,51 @@
+"""billdogeng -- Official BilldogEng server SDK for Python.
+
+Engagement suite: Analytics + Feature Flags (remote + local eval) + Surveys +
+Messaging + LLM observability.
+"""
+
+from __future__ import annotations
+
+from .analytics import Analytics
+from .client import BilldogEng
+from .errors import BilldogEngError
+from .flags import Flags
+from .llm import Llm
+from .messaging import Messaging
+from .murmur import bucket_of, murmurhash3
+from .surveys import Surveys
+from .types import (
+    FeatureFlagDefinition,
+    FlagVariant,
+    Groups,
+    LlmTraceParams,
+    MessagingScheduling,
+    MessagingTargeting,
+    Properties,
+    SurveyContext,
+    TargetingRule,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "BilldogEng",
+    "BilldogEngError",
+    "murmurhash3",
+    "bucket_of",
+    "Analytics",
+    "Flags",
+    "Surveys",
+    "Messaging",
+    "Llm",
+    "FeatureFlagDefinition",
+    "FlagVariant",
+    "TargetingRule",
+    "SurveyContext",
+    "MessagingTargeting",
+    "MessagingScheduling",
+    "LlmTraceParams",
+    "Properties",
+    "Groups",
+    "__version__",
+]

billdogeng-1.0.0b1/src/billdogeng/analytics.py

@@ -0,0 +1,174 @@
+"""Analytics client: capture/identify/groupIdentify/alias + batching.
+
+Mirrors the Node reference ``analytics.ts``. Events accumulate in an in-memory
+queue and are flushed as a single batched POST to ``/ingest-events`` when:
+  - the queue reaches ``flush_at``,
+  - the background timer fires every ``flush_interval``, or
+  - ``flush()`` / ``shutdown()`` is called.
+
+A failed flush re-queues its batch (front of the queue) so events are never
+lost on a single transient failure; the :class:`Transport` also retries with
+backoff before a flush is considered failed.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Dict, List, Optional
+
+from .transport import Transport
+from .types import Groups, Properties
+
+
+class Analytics:
+    def __init__(self, transport: Transport, api_key: str, options: Dict[str, Any]) -> None:
+        self._transport = transport
+        self._api_key = api_key
+        self._opts = options
+        self._queue: List[Dict[str, Any]] = []
+        self._queue_lock = threading.Lock()
+        #: Serializes flushes so re-queued batches don't interleave.
+        self._flush_lock = threading.Lock()
+        self._timer: Optional[threading.Timer] = None
+        self._stopped = False
+        self._start_timer()
+
+    def _log(self, *args: Any) -> None:
+        if self._opts.get("enable_logging"):
+            print("[BilldogEng:analytics]", *args)
+
+    # --- Public API ---------------------------------------------------------
+
+    def capture(
+        self,
+        distinct_id: str,
+        event: str,
+        properties: Optional[Properties] = None,
+        groups: Optional[Groups] = None,
+    ) -> None:
+        self._enqueue(
+            distinct_id, event, self._with_groups(properties or {}, groups or {})
+        )
+
+    def identify(self, distinct_id: str, properties: Optional[Properties] = None) -> None:
+        props = properties or {}
+        merged: Properties = {"$set": props}
+        merged.update(props)
+        self._enqueue(distinct_id, "$identify", merged)
+
+    def group_identify(
+        self, group_type: str, group_key: str, properties: Optional[Properties] = None
+    ) -> None:
+        self._enqueue(
+            group_key,
+            "$groupidentify",
+            {
+                "$group_type": group_type,
+                "$group_key": group_key,
+                "$group_set": properties or {},
+            },
+        )
+
+    def alias(self, distinct_id: str, alias: str) -> None:
+        self._enqueue(distinct_id, "$create_alias", {"alias": alias, "distinct_id": distinct_id})
+
+    def flush(self) -> None:
+        """Force-flush the queue immediately.
+
+        Raises :class:`BilldogEngError` if the flush ultimately fails (after
+        retries); the batch is re-queued in that case.
+        """
+        with self._flush_lock:
+            self._do_flush()
+
+    def stop_timer(self) -> None:
+        self._stopped = True
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+
+    def shutdown(self) -> None:
+        self.stop_timer()
+        self.flush()
+
+    @property
+    def queue_length(self) -> int:
+        with self._queue_lock:
+            return len(self._queue)
+
+    # --- Internals ----------------------------------------------------------
+
+    def _start_timer(self) -> None:
+        interval = self._opts.get("flush_interval", 10000) / 1000.0
+        self._timer = threading.Timer(interval, self._on_timer)
+        self._timer.daemon = True  # don't keep the process alive
+        self._timer.start()
+
+    def _on_timer(self) -> None:
+        try:
+            with self._flush_lock:
+                self._do_flush()
+        except Exception as e:  # noqa: BLE001 - background flush must not crash
+            self._log("background flush failed:", e)
+        finally:
+            if not self._stopped:
+                self._start_timer()
+
+    def _with_groups(self, properties: Properties, groups: Groups) -> Properties:
+        if not groups:
+            return dict(properties)
+        out: Properties = dict(properties)
+        out["$groups"] = dict(groups)
+        index_map = self._opts.get("group_type_index")
+        if index_map:
+            for gtype, gkey in groups.items():
+                idx = index_map.get(gtype)
+                if isinstance(idx, int) and 0 <= idx <= 4:
+                    out[f"$group_{idx}"] = gkey
+        return out
+
+    def _enqueue(self, distinct_id: str, event_name: str, properties: Properties) -> None:
+        wire_event = {
+            "event_name": event_name,
+            "event_timestamp": int(time.time() * 1000),
+            "properties": properties,
+            "user_id": distinct_id,
+        }
+        should_flush = False
+        with self._queue_lock:
+            self._queue.append(wire_event)
+            max_size = self._opts.get("max_queue_size", 1000)
+            if len(self._queue) > max_size:
+                dropped = len(self._queue) - max_size
+                del self._queue[0:dropped]
+                self._log(f"max queue size exceeded, dropped {dropped} oldest event(s)")
+            if len(self._queue) >= self._opts.get("flush_at", 20):
+                should_flush = True
+
+        if should_flush:
+            try:
+                self.flush()
+            except Exception as e:  # noqa: BLE001 - auto-flush must not crash caller
+                self._log("auto-flush failed:", e)
+
+    def _do_flush(self) -> None:
+        with self._queue_lock:
+            if not self._queue:
+                return
+            batch = self._queue
+            self._queue = []
+
+        body = {"api_key": self._api_key, "events": batch}
+
+        try:
+            self._transport.request(
+                "/ingest-events", body=body, headers={"x-api-key": self._api_key}
+            )
+            self._log(f"flushed {len(batch)} event(s)")
+        except Exception as err:
+            # Re-queue the batch at the front so it is retried on the next flush.
+            with self._queue_lock:
+                self._queue = batch + self._queue
+            self._log(f"flush failed, re-queued {len(batch)} event(s): {err}")
+            raise