beaconhq 0.1.0__tar.gz

beaconhq-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Python build / cache artifacts — never commit
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtualenvs
+.venv/
+venv/

beaconhq-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skyware LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

beaconhq-0.1.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: beaconhq
+Version: 0.1.0
+Summary: Beacon Python client SDK — auto-capture HTTP request telemetry and ship it to the Beacon ingest API. FastAPI/Starlette, Flask, and Django adapters.
+Project-URL: Homepage, https://beacon.skyware.dev
+Project-URL: Documentation, https://beacon.skyware.dev/docs
+Project-URL: Repository, https://github.com/kb-gardner/HighHrothgar
+Project-URL: Issues, https://github.com/kb-gardner/HighHrothgar/issues
+Author: Skyware LLC
+License: MIT
+License-File: LICENSE
+Keywords: api-monitoring,apm,beacon,django,fastapi,flask,monitoring,observability,starlette,telemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: django>=3.2; extra == 'dev'
+Requires-Dist: flask>=2.0; extra == 'dev'
+Requires-Dist: httpx>=0.24; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: starlette>=0.27; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: starlette>=0.27; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# beaconhq — Beacon Python SDK
+
+Auto-capture HTTP request telemetry from your **FastAPI / Starlette**, **Flask**,
+or **Django** app and ship it to [Beacon](https://beacon.skyware.dev). This is the
+Python port of `@beaconhq/sdk` — same product, same ingest contract, idiomatic
+Python.
+
+> Full docs: <https://beacon.skyware.dev/docs>
+
+- **Distribution name:** `beaconhq` (`pip install beaconhq`)
+- **Import package:** `beaconhq` (`import beaconhq`)
+- **Zero required dependencies** for the core — it ships telemetry using only the
+  Python standard library (`urllib`, `threading`, `json`, `atexit`). Framework
+  support is opt-in via extras and imported lazily, so `import beaconhq` works with
+  no web framework installed.
+- **Python 3.9+.**
+
+## Install
+
+```bash
+pip install beaconhq                 # core only
+pip install "beaconhq[fastapi]"      # + Starlette/FastAPI adapter
+pip install "beaconhq[flask]"        # + Flask adapter
+pip install "beaconhq[django]"       # + Django adapter
+```
+
+## Quickstart
+
+You only need a project ingest key — the client defaults to Beacon's hosted ingest
+endpoint (`https://ingest.beacon.skyware.dev/v1/ingest`).
+
+```python
+from beaconhq import BeaconClient
+
+beacon = BeaconClient(ingest_key="your-per-project-ingest-key")
+```
+
+Or configure from the environment (`BEACON_INGEST_KEY`, optional `BEACON_INGEST_URL`,
+optional `BEACON_ENABLED`):
+
+```python
+from beaconhq import BeaconClient
+beacon = BeaconClient.from_env()
+```
+
+### FastAPI / Starlette
+
+```python
+from fastapi import FastAPI
+from beaconhq import BeaconClient
+from beaconhq.integrations.asgi import BeaconASGIMiddleware
+
+beacon = BeaconClient(ingest_key=KEY)
+
+app = FastAPI()
+app.add_middleware(BeaconASGIMiddleware, client=beacon, consumer_header="x-api-key")
+
+@app.get("/users/{user_id}")
+def get_user(user_id: int):
+    return {"id": user_id}
+# Captured route template: "/users/{user_id}"  (not the concrete "/users/123")
+```
+
+### Flask
+
+```python
+from flask import Flask
+from beaconhq import BeaconClient
+from beaconhq.integrations.flask import init_flask
+
+beacon = BeaconClient(ingest_key=KEY)
+
+app = Flask(__name__)
+init_flask(app, beacon, consumer_header="X-API-Key")
+
+@app.route("/users/<int:user_id>")
+def get_user(user_id):
+    return {"id": user_id}
+# Captured route template: "/users/<int:user_id>"
+```
+
+### Django
+
+```python
+# settings.py
+from beaconhq import BeaconClient
+
+BEACON_CLIENT = BeaconClient(ingest_key="your-per-project-ingest-key")
+BEACON_CONSUMER_HEADER = "X-API-Key"   # optional
+
+MIDDLEWARE = [
+    "beaconhq.integrations.django.BeaconDjangoMiddleware",   # put it near the top
+    # ... your other middleware ...
+]
+# Captured route template: "/users/<int:pk>"  (from request.resolver_match.route)
+```
+
+If `BEACON_CLIENT` is missing the middleware disables itself cleanly (Django
+`MiddlewareNotUsed`) rather than erroring.
+
+## Self-hosting / overriding the endpoint
+
+Point at your own Beacon ingest by passing `ingest_url` (a full endpoint, or a base
+URL to which `/v1/ingest` is appended):
+
+```python
+beacon = BeaconClient(
+    ingest_key=KEY,
+    ingest_url="https://beacon.internal.example.com",  # /v1/ingest appended if omitted
+)
+```
+
+## How it works
+
+`capture()` only appends to an in-memory buffer — it is **non-blocking** and adds
+negligible latency to your request path. A background daemon thread flushes the
+buffer to the ingest API every `flush_interval` seconds, or eagerly when it reaches
+`batch_size`. The client **never raises into your app**: serialization and network
+failures are caught, optionally reported via `on_error`, and the batch is re-queued
+(network error / 5xx) or dropped (4xx). Remaining events are flushed on interpreter
+exit via `atexit`.
+
+## Identifying the consumer (the "who called me" hook)
+
+`consumer` is the identity of the caller (an API-key id, user id, tenant…). The
+simplest option is to read a header:
+
+```python
+app.add_middleware(BeaconASGIMiddleware, client=beacon, consumer_header="x-api-key")
+```
+
+For anything richer, pass a `consumer_resolver` — a callable that receives the
+framework's request object and returns a string or `None`:
+
+```python
+def resolve_consumer(request) -> str | None:
+    # FastAPI/Starlette: `request` is the raw ASGI `scope` dict
+    # Flask:             `request` is `flask.request`
+    # Django:            `request` is the `HttpRequest`
+    return getattr(getattr(request, "state", None), "api_key_id", None)
+
+app.add_middleware(
+    BeaconASGIMiddleware, client=beacon, consumer_resolver=resolve_consumer
+)
+```
+
+You can also set a default resolver on the client itself
+(`BeaconClient(..., consumer_resolver=...)`) so every adapter uses it. Resolution
+precedence: adapter `consumer_resolver` → client `consumer_resolver` → header value.
+A resolver that raises is treated as "no consumer" — it never breaks the request.
+
+## Configuration reference
+
+`BeaconClient(...)` — option names are the snake_case translation of the JS
+`BeaconClientOptions`; defaults match `@beaconhq/sdk`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `ingest_key` | `str` | — (required) | Per-project ingest key, sent as `Authorization: Bearer`. The only required argument. |
+| `ingest_url` | `str` | `https://ingest.beacon.skyware.dev/v1/ingest` | Full endpoint or base URL (`/v1/ingest` appended). Override for self-hosted Beacon. |
+| `batch_size` | `int` | `100` | Buffered events that trigger an eager flush. |
+| `flush_interval` | `float` | `5.0` | Background flush cadence, **seconds** (JS uses 5000 ms). |
+| `max_buffer_size` | `int` | `10000` | Memory cap; oldest events dropped past this. |
+| `timeout` | `float` | `5.0` | Per-request HTTP timeout, seconds. |
+| `enabled` | `bool` | `True` | When `False`, `capture()` is a no-op. |
+| `dry_run` | `bool` | `False` | Buffer + "flush" to an in-memory sink; nothing leaves the process. |
+| `debug` | `bool` | `False` | Attach a default `on_error` that logs at WARNING. |
+| `on_error` | `Callable[[BaseException], None]` | no-op | Observability hook; never required, never re-raised. |
+| `consumer_resolver` | `Callable[[req], str \| None]` | `None` | Default consumer hook for all adapters. |
+| `transport` | `Transport` | HTTP | Inject a custom transport (tests). |
+| `register_atexit` | `bool` | `True` | Flush remaining events on interpreter exit. |
+
+Adapter options (`BeaconASGIMiddleware`, `init_flask`, and the Django settings
+`BEACON_CONSUMER_HEADER` / `BEACON_CONSUMER_RESOLVER`): `consumer_header` and
+`consumer_resolver`, as above.
+
+Environment variables (read by `BeaconClient.from_env()`): `BEACON_INGEST_KEY`
+(required), `BEACON_INGEST_URL` (optional — defaults to the hosted endpoint),
+`BEACON_ENABLED` (`0`/`false`/`no` disables).
+
+## Event payload
+
+Each captured request becomes one event in the batched `POST /v1/ingest` body
+(`{"events": [ ... ]}`). Field names and types match the ingest contract and the
+server's validation exactly:
+
+```json
+{
+  "ts": "2026-06-03T12:00:00.000+00:00",
+  "method": "GET",
+  "route": "/users/{id}",
+  "path": "/users/123",
+  "status": 200,
+  "duration_ms": 42,
+  "consumer": "acme",
+  "error": null
+}
+```
+
+`route` is the low-cardinality **template** (resolved from the framework's
+routing), which powers per-endpoint aggregation; `path` is the concrete request
+path. `consumer` and `error` are always sent (as `null` when absent), matching the
+JS SDK.
+
+## Graceful shutdown
+
+Buffered events are flushed automatically on interpreter exit. To flush explicitly
+(e.g. in a worker's shutdown hook):
+
+```python
+beacon.shutdown()   # stops the timer and flushes remaining events; idempotent
+```
+
+## Development & tests
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Core tests run against an in-memory mock transport (no network) and assert the
+exact payload shape, batching, interval/shutdown flush, and the
+never-raise/requeue behavior. Adapter smoke tests drive a real request through
+each framework and skip if the framework isn't installed.
+
+## License
+
+MIT © Skyware LLC

beaconhq-0.1.0/README.md

@@ -0,0 +1,229 @@
+# beaconhq — Beacon Python SDK
+
+Auto-capture HTTP request telemetry from your **FastAPI / Starlette**, **Flask**,
+or **Django** app and ship it to [Beacon](https://beacon.skyware.dev). This is the
+Python port of `@beaconhq/sdk` — same product, same ingest contract, idiomatic
+Python.
+
+> Full docs: <https://beacon.skyware.dev/docs>
+
+- **Distribution name:** `beaconhq` (`pip install beaconhq`)
+- **Import package:** `beaconhq` (`import beaconhq`)
+- **Zero required dependencies** for the core — it ships telemetry using only the
+  Python standard library (`urllib`, `threading`, `json`, `atexit`). Framework
+  support is opt-in via extras and imported lazily, so `import beaconhq` works with
+  no web framework installed.
+- **Python 3.9+.**
+
+## Install
+
+```bash
+pip install beaconhq                 # core only
+pip install "beaconhq[fastapi]"      # + Starlette/FastAPI adapter
+pip install "beaconhq[flask]"        # + Flask adapter
+pip install "beaconhq[django]"       # + Django adapter
+```
+
+## Quickstart
+
+You only need a project ingest key — the client defaults to Beacon's hosted ingest
+endpoint (`https://ingest.beacon.skyware.dev/v1/ingest`).
+
+```python
+from beaconhq import BeaconClient
+
+beacon = BeaconClient(ingest_key="your-per-project-ingest-key")
+```
+
+Or configure from the environment (`BEACON_INGEST_KEY`, optional `BEACON_INGEST_URL`,
+optional `BEACON_ENABLED`):
+
+```python
+from beaconhq import BeaconClient
+beacon = BeaconClient.from_env()
+```
+
+### FastAPI / Starlette
+
+```python
+from fastapi import FastAPI
+from beaconhq import BeaconClient
+from beaconhq.integrations.asgi import BeaconASGIMiddleware
+
+beacon = BeaconClient(ingest_key=KEY)
+
+app = FastAPI()
+app.add_middleware(BeaconASGIMiddleware, client=beacon, consumer_header="x-api-key")
+
+@app.get("/users/{user_id}")
+def get_user(user_id: int):
+    return {"id": user_id}
+# Captured route template: "/users/{user_id}"  (not the concrete "/users/123")
+```
+
+### Flask
+
+```python
+from flask import Flask
+from beaconhq import BeaconClient
+from beaconhq.integrations.flask import init_flask
+
+beacon = BeaconClient(ingest_key=KEY)
+
+app = Flask(__name__)
+init_flask(app, beacon, consumer_header="X-API-Key")
+
+@app.route("/users/<int:user_id>")
+def get_user(user_id):
+    return {"id": user_id}
+# Captured route template: "/users/<int:user_id>"
+```
+
+### Django
+
+```python
+# settings.py
+from beaconhq import BeaconClient
+
+BEACON_CLIENT = BeaconClient(ingest_key="your-per-project-ingest-key")
+BEACON_CONSUMER_HEADER = "X-API-Key"   # optional
+
+MIDDLEWARE = [
+    "beaconhq.integrations.django.BeaconDjangoMiddleware",   # put it near the top
+    # ... your other middleware ...
+]
+# Captured route template: "/users/<int:pk>"  (from request.resolver_match.route)
+```
+
+If `BEACON_CLIENT` is missing the middleware disables itself cleanly (Django
+`MiddlewareNotUsed`) rather than erroring.
+
+## Self-hosting / overriding the endpoint
+
+Point at your own Beacon ingest by passing `ingest_url` (a full endpoint, or a base
+URL to which `/v1/ingest` is appended):
+
+```python
+beacon = BeaconClient(
+    ingest_key=KEY,
+    ingest_url="https://beacon.internal.example.com",  # /v1/ingest appended if omitted
+)
+```
+
+## How it works
+
+`capture()` only appends to an in-memory buffer — it is **non-blocking** and adds
+negligible latency to your request path. A background daemon thread flushes the
+buffer to the ingest API every `flush_interval` seconds, or eagerly when it reaches
+`batch_size`. The client **never raises into your app**: serialization and network
+failures are caught, optionally reported via `on_error`, and the batch is re-queued
+(network error / 5xx) or dropped (4xx). Remaining events are flushed on interpreter
+exit via `atexit`.
+
+## Identifying the consumer (the "who called me" hook)
+
+`consumer` is the identity of the caller (an API-key id, user id, tenant…). The
+simplest option is to read a header:
+
+```python
+app.add_middleware(BeaconASGIMiddleware, client=beacon, consumer_header="x-api-key")
+```
+
+For anything richer, pass a `consumer_resolver` — a callable that receives the
+framework's request object and returns a string or `None`:
+
+```python
+def resolve_consumer(request) -> str | None:
+    # FastAPI/Starlette: `request` is the raw ASGI `scope` dict
+    # Flask:             `request` is `flask.request`
+    # Django:            `request` is the `HttpRequest`
+    return getattr(getattr(request, "state", None), "api_key_id", None)
+
+app.add_middleware(
+    BeaconASGIMiddleware, client=beacon, consumer_resolver=resolve_consumer
+)
+```
+
+You can also set a default resolver on the client itself
+(`BeaconClient(..., consumer_resolver=...)`) so every adapter uses it. Resolution
+precedence: adapter `consumer_resolver` → client `consumer_resolver` → header value.
+A resolver that raises is treated as "no consumer" — it never breaks the request.
+
+## Configuration reference
+
+`BeaconClient(...)` — option names are the snake_case translation of the JS
+`BeaconClientOptions`; defaults match `@beaconhq/sdk`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `ingest_key` | `str` | — (required) | Per-project ingest key, sent as `Authorization: Bearer`. The only required argument. |
+| `ingest_url` | `str` | `https://ingest.beacon.skyware.dev/v1/ingest` | Full endpoint or base URL (`/v1/ingest` appended). Override for self-hosted Beacon. |
+| `batch_size` | `int` | `100` | Buffered events that trigger an eager flush. |
+| `flush_interval` | `float` | `5.0` | Background flush cadence, **seconds** (JS uses 5000 ms). |
+| `max_buffer_size` | `int` | `10000` | Memory cap; oldest events dropped past this. |
+| `timeout` | `float` | `5.0` | Per-request HTTP timeout, seconds. |
+| `enabled` | `bool` | `True` | When `False`, `capture()` is a no-op. |
+| `dry_run` | `bool` | `False` | Buffer + "flush" to an in-memory sink; nothing leaves the process. |
+| `debug` | `bool` | `False` | Attach a default `on_error` that logs at WARNING. |
+| `on_error` | `Callable[[BaseException], None]` | no-op | Observability hook; never required, never re-raised. |
+| `consumer_resolver` | `Callable[[req], str \| None]` | `None` | Default consumer hook for all adapters. |
+| `transport` | `Transport` | HTTP | Inject a custom transport (tests). |
+| `register_atexit` | `bool` | `True` | Flush remaining events on interpreter exit. |
+
+Adapter options (`BeaconASGIMiddleware`, `init_flask`, and the Django settings
+`BEACON_CONSUMER_HEADER` / `BEACON_CONSUMER_RESOLVER`): `consumer_header` and
+`consumer_resolver`, as above.
+
+Environment variables (read by `BeaconClient.from_env()`): `BEACON_INGEST_KEY`
+(required), `BEACON_INGEST_URL` (optional — defaults to the hosted endpoint),
+`BEACON_ENABLED` (`0`/`false`/`no` disables).
+
+## Event payload
+
+Each captured request becomes one event in the batched `POST /v1/ingest` body
+(`{"events": [ ... ]}`). Field names and types match the ingest contract and the
+server's validation exactly:
+
+```json
+{
+  "ts": "2026-06-03T12:00:00.000+00:00",
+  "method": "GET",
+  "route": "/users/{id}",
+  "path": "/users/123",
+  "status": 200,
+  "duration_ms": 42,
+  "consumer": "acme",
+  "error": null
+}
+```
+
+`route` is the low-cardinality **template** (resolved from the framework's
+routing), which powers per-endpoint aggregation; `path` is the concrete request
+path. `consumer` and `error` are always sent (as `null` when absent), matching the
+JS SDK.
+
+## Graceful shutdown
+
+Buffered events are flushed automatically on interpreter exit. To flush explicitly
+(e.g. in a worker's shutdown hook):
+
+```python
+beacon.shutdown()   # stops the timer and flushes remaining events; idempotent
+```
+
+## Development & tests
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Core tests run against an in-memory mock transport (no network) and assert the
+exact payload shape, batching, interval/shutdown flush, and the
+never-raise/requeue behavior. Adapter smoke tests drive a real request through
+each framework and skip if the framework isn't installed.
+
+## License
+
+MIT © Skyware LLC

beaconhq-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+# PEP 621 packaging for the Beacon Python SDK.
+#
+# Distribution name: beaconhq   (pip install beaconhq)
+# Import package:    beaconhq   (import beaconhq)
+#
+# The core has ZERO required third-party dependencies — it ships telemetry to the
+# Beacon ingest API using only the standard library (urllib, threading, json,
+# atexit). Framework support is provided via optional extras that pull in the
+# matching web framework and are imported lazily, so `import beaconhq` works with
+# none of them installed.
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "beaconhq"
+version = "0.1.0"
+description = "Beacon Python client SDK — auto-capture HTTP request telemetry and ship it to the Beacon ingest API. FastAPI/Starlette, Flask, and Django adapters."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Skyware LLC" }]
+keywords = [
+  "beacon",
+  "observability",
+  "monitoring",
+  "telemetry",
+  "apm",
+  "api-monitoring",
+  "fastapi",
+  "starlette",
+  "flask",
+  "django",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: System :: Monitoring",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://beacon.skyware.dev"
+Documentation = "https://beacon.skyware.dev/docs"
+Repository = "https://github.com/kb-gardner/HighHrothgar"
+Issues = "https://github.com/kb-gardner/HighHrothgar/issues"
+
+[project.optional-dependencies]
+# Framework adapters. Each imports its framework lazily; install only what you use.
+fastapi = ["starlette>=0.27"]
+flask = ["flask>=2.0"]
+django = ["django>=3.2"]
+# Dev/test toolchain.
+dev = [
+  "pytest>=7.0",
+  "starlette>=0.27",
+  "httpx>=0.24",
+  "flask>=2.0",
+  "django>=3.2",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/beaconhq"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/beaconhq", "README.md", "pyproject.toml", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

beaconhq-0.1.0/src/beaconhq/__init__.py

@@ -0,0 +1,61 @@
+"""beaconhq — the Beacon Python client SDK.
+
+The core (:class:`BeaconClient`, :class:`BeaconEvent`) buffers and ships request
+events to the Beacon ingest API and depends only on the standard library. The
+framework adapters auto-capture method / route-template / status / latency from
+FastAPI/Starlette, Flask, and Django, and live in :mod:`beaconhq.integrations`.
+
+The raw HTTP contract in ``docs/ingest-contract.md`` is the language-agnostic
+source of truth; this SDK is the convenience wrapper for Python services and is a
+direct port of ``@beaconhq/sdk``.
+
+Importing ``beaconhq`` never imports a web framework. The adapters are exposed
+lazily here — accessing :data:`BeaconASGIMiddleware`, :data:`init_flask`, or
+:data:`BeaconDjangoMiddleware` imports the relevant ``beaconhq.integrations.*``
+module (which imports its framework) only on first use, so ``import beaconhq``
+works with zero framework dependencies installed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import DEFAULT_INGEST_URL, BeaconClient, utc_now_iso
+from .event import BeaconEvent
+from .transport import HttpTransport, MockTransport, SendResult, Transport
+
+__all__ = [
+    "BeaconClient",
+    "BeaconEvent",
+    "Transport",
+    "HttpTransport",
+    "MockTransport",
+    "SendResult",
+    "utc_now_iso",
+    "DEFAULT_INGEST_URL",
+    # Lazily resolved framework adapters (see __getattr__).
+    "BeaconASGIMiddleware",
+    "init_flask",
+    "BeaconDjangoMiddleware",
+]
+
+__version__ = "0.1.0"
+
+# Map of lazily-exposed adapter names -> (submodule, attribute). Resolved on
+# first attribute access so the core import stays framework-free.
+_LAZY_ATTRS = {
+    "BeaconASGIMiddleware": (".integrations.asgi", "BeaconASGIMiddleware"),
+    "init_flask": (".integrations.flask", "init_flask"),
+    "BeaconDjangoMiddleware": (".integrations.django", "BeaconDjangoMiddleware"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """PEP 562 module-level lazy attribute access for the framework adapters."""
+    target = _LAZY_ATTRS.get(name)
+    if target is None:
+        raise AttributeError(f"module 'beaconhq' has no attribute {name!r}")
+    from importlib import import_module
+
+    module = import_module(target[0], __name__)
+    return getattr(module, target[1])