prinvox 0.1.0__tar.gz

prinvox-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/

prinvox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amin Sayegh
+
+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.

prinvox-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.5
+Name: prinvox
+Version: 0.1.0
+Summary: Official PrinVox Margin Guard SDK: report AI usage events (OpenAI, Anthropic, Google Gemini) from your Python server.
+Project-URL: Homepage, https://www.prinvox.com
+Project-URL: Documentation, https://www.prinvox.com/en/docs
+License: MIT
+License-File: LICENSE
+Keywords: ai,anthropic,cost,gemini,gross-margin,llm,margin-guard,openai,prinvox,usage
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# prinvox (Python SDK)
+
+Official Python SDK for **PrinVox Margin Guard**. It reports your AI usage (OpenAI, Anthropic, Google Gemini) to PrinVox so you see revenue, AI cost and gross margin per customer, plan and feature.
+
+> **Version 0.1.0.** The SDK is a thin wrapper over the PrinVox ingestion HTTP API, documented at [prinvox.com/en/docs](https://www.prinvox.com/en/docs), which you can also call directly.
+
+```bash
+pip install prinvox
+```
+
+Python **3.10+**. One dependency: [`httpx`](https://www.python-httpx.org/). Synchronous API: `track` blocks (network I/O, retries), so never call it directly on an asyncio event loop — use a worker thread or a background task (see FastAPI below). An async client is a planned follow-up.
+
+## What it needs — and what it never needs
+
+The SDK uses **one secret: your PrinVox ingestion key** (`mgik_…`, created under *Margin Guard → Connections*, one per provider). It sends usage **metadata** (model, token counts, your customer and feature labels).
+
+PrinVox does **not** need, and the SDK never touches, your OpenAI, Anthropic or Google (Gemini) API key. You keep calling those providers with their own SDKs and then report what they told you. Prices live on the server: the SDK contains none.
+
+**Server-side only.** Never put `PRINVOX_INGESTION_KEY` in browser code, a frontend bundle or a mobile app.
+
+## Quick start
+
+```python
+import os
+from prinvox import PrinVox
+
+client = PrinVox(api_key=os.environ["PRINVOX_INGESTION_KEY"])
+
+result = client.track(
+    provider="openai",
+    model="gpt-4.1",
+    event_id=response.id,        # idempotency key, see below
+    feature_key="assistant",
+    customer_ref="cus_123",
+    input_tokens=1000,
+    output_tokens=500,
+)
+print(result.status)  # "processed" or "duplicate"
+```
+
+`track` takes keyword arguments only, returns a `TrackResult` or raises a [`PrinVoxError`](#errors).
+
+### OpenAI
+
+```python
+from openai import OpenAI
+from prinvox import PrinVox
+
+openai_client = OpenAI()  # your own key, PrinVox never sees it
+prinvox = PrinVox(api_key=os.environ["PRINVOX_INGESTION_KEY_OPENAI"])
+MODEL = "gpt-4.1-mini"  # send the alias you requested, not a dated snapshot name
+
+response = openai_client.responses.create(model=MODEL, input="Summarize: ...")
+
+try:
+    prinvox.track(
+        provider="openai",
+        model=MODEL,
+        event_id=response.id,
+        feature_key="summarize",
+        customer_ref=app_customer_id,
+        input_tokens=response.usage.input_tokens if response.usage else None,
+        output_tokens=response.usage.output_tokens if response.usage else None,
+    )
+except Exception:
+    pass  # telemetry must never break your product (log it if you like)
+```
+
+### Anthropic
+
+```python
+import anthropic
+
+claude = anthropic.Anthropic()  # your own key
+message = claude.messages.create(model="claude-haiku-4-5", max_tokens=512, messages=[{"role": "user", "content": question}])
+
+prinvox.track(  # a PrinVox client created with the ingestion key for Anthropic
+    provider="anthropic",
+    model="claude-haiku-4-5",
+    event_id=message.id,
+    feature_key="support-answer",
+    customer_ref=app_customer_id,
+    input_tokens=message.usage.input_tokens,
+    output_tokens=message.usage.output_tokens,
+)
+```
+
+### Google Gemini
+
+The canonical provider value is `google_gemini` (a bare `google` is refused). Thinking tokens are billed as output, so add them. The 2.5 Flash family bills audio input higher, so say how much of the prompt was audio — `0` for text-only calls. **Without `input_audio_tokens` the cost of those models is stored as UNKNOWN** (never silently priced as text), and the report shows that figure as incomplete.
+
+```python
+import uuid
+from google import genai
+
+gemini = genai.Client()  # your own key
+response = gemini.models.generate_content(model="gemini-2.5-flash", contents=prompt)
+u = response.usage_metadata
+audio = sum((d.token_count or 0) for d in (u.prompt_tokens_details or []) if str(d.modality).endswith("AUDIO"))
+
+prinvox.track(  # a PrinVox client created with the ingestion key for Google Gemini
+    provider="google_gemini",
+    model="gemini-2.5-flash",
+    event_id=response.response_id or str(uuid.uuid4()),
+    feature_key="ai-chat",
+    customer_ref=app_customer_id,
+    input_tokens=u.prompt_token_count,
+    input_audio_tokens=audio,
+    output_tokens=(u.candidates_token_count or 0) + (u.thoughts_token_count or 0),
+)
+```
+
+### FastAPI (server-side)
+
+`track` is synchronous. Run it as a background task so it runs after the response and in a worker thread, never on the event loop.
+
+```python
+import os
+from fastapi import BackgroundTasks, FastAPI
+from prinvox import PrinVox
+
+app = FastAPI()
+prinvox = PrinVox(api_key=os.environ["PRINVOX_INGESTION_KEY_OPENAI"])  # read from the server's environment only
+
+
+def report(response_id: str, customer_id: str, usage) -> None:
+    try:
+        prinvox.track(
+            provider="openai", model="gpt-4.1-mini", event_id=response_id, feature_key="chat", customer_ref=customer_id,
+            input_tokens=usage.input_tokens, output_tokens=usage.output_tokens,
+        )
+    except Exception:
+        pass  # never fail the user's request over telemetry
+
+
+@app.post("/chat")
+def chat(prompt: str, customer_id: str, background: BackgroundTasks):
+    response = openai_client.responses.create(model="gpt-4.1-mini", input=prompt)
+    background.add_task(report, response.id, customer_id, response.usage)
+    return {"text": response.output_text}
+```
+
+## Event fields
+
+| Argument | Required | Notes |
+|---|---|---|
+| `provider` | yes | `"openai"`, `"anthropic"`, `"google_gemini"` (other strings are passed through). The server accepts the Gemini aliases `gemini`, `google-ai`, `google_ai`; a bare `google` is refused. |
+| `model` | yes | The exact alias you requested. An unpriced model is **stored with an unknown cost**, never an invented price. |
+| `event_id` | yes | Unique per provider request. **This is the idempotency key** (sent as `provider_request_id`). |
+| `feature_key` | yes | Your name for the AI feature. |
+| `input_tokens`, `output_tokens` | no | Omit them if the provider reported no usage — the cost is then unknown, not zero. |
+| `input_audio_tokens` | Gemini 2.5 Flash family | A subset of `input_tokens`; `0` if none. |
+| `customer_ref` | no | Your own id for the end customer (`external_customer_id`). Without it the cost is *Unattributed*. |
+| `stripe_customer_id` | no | The `cus_…` id in your connected Stripe account — the only link between usage and Stripe revenue. |
+| `timestamp` | no | A `datetime` (naive means UTC) or an ISO 8601 string. Defaults to now. Reports show the trailing 30 days by default. |
+
+There is no `metadata` field: the ingestion API does not store one.
+
+## Idempotency and retries
+
+`event_id` makes every call safe to repeat: the same `event_id` for the same provider is stored once and answered `duplicate`. The SDK therefore retries **only** transient failures — network errors, timeouts and 500/502/503/504 — up to `max_retries` (default 2, max 5) with bounded, jittered exponential backoff, always re-sending the identical body. It never retries 4xx, and never retries 429 (`Retry-After` is 60 s, far longer than a telemetry call should wait): you get a `PrinVoxRateLimitError` with `retry_after` and can resend later **with the same `event_id`**. `max_retries=0` disables retries.
+
+There is no automatic `event_id`: a random id would defeat idempotency across your own retries. Use the provider's response id.
+
+## Errors
+
+`track` raises `PrinVoxError` or a subclass — never anything carrying your key, the Authorization header or the event body:
+
+| Class | `code` | When |
+|---|---|---|
+| `PrinVoxValidationError` | `invalid_event`, `invalid_options` | Rejected locally; nothing was sent. |
+| `PrinVoxValidationError` | `invalid_request` | The server refused it (400 `invalid_body` / `provider_mismatch`, 413, …). See `api_error`. |
+| `PrinVoxAuthenticationError` | `authentication`, `forbidden` | 401 (wrong, missing or replaced key) / 403. |
+| `PrinVoxError` | `payment_required` | 402 — the free evaluation ended. |
+| `PrinVoxError` | `quota_exceeded` | 429 `trial_event_limit` — the evaluation's event quota is used up. Final: subscribe instead of resending. |
+| `PrinVoxRateLimitError` | `rate_limited` | 429 throttle — see `retry_after`; resend later with the same `event_id`. |
+| `PrinVoxError` | `server_error` | 5xx after retries. |
+| `PrinVoxConnectionError` | `network`, `timeout` | No answer. |
+| `PrinVoxError` | `invalid_response` | An answer the SDK cannot interpret (including an unexpected 2xx such as 202/204 from a proxy). The event may be stored; resending the same `event_id` is safe. |
+
+Attributes: `code`, `message`, `status_code`, `api_error`, `retry_after`, `request_id`; `to_dict()` is safe to log.
+
+## Options
+
+```python
+PrinVox(
+    api_key,                 # required
+    base_url=None,           # default https://www.prinvox.com — point it at a Preview environment to test
+    timeout=None,            # seconds for connecting and for each read, default 10
+    max_retries=2,
+    retry_delay=0.25,        # backoff base in seconds
+    http_client=None,        # your own httpx.Client (proxies, tests); you keep ownership of it
+)
+```
+
+`base_url` must be `https` (plain `http` only for `localhost`). To try the SDK without touching production data, use a Preview deployment's URL together with that environment's own ingestion key. The client holds a connection pool: reuse one instance, or use it as a context manager (`with PrinVox(...) as client:`). Its `repr()` redacts the key and it cannot be pickled or copied.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e . pytest ruff mypy build
+pytest && ruff check . && mypy && python -m build
+```
+
+## Versioning
+
+The ingestion API has no version prefix today; the SDK wraps it as it is. New optional fields will be added without breaking existing calls.
+
+## License
+
+The PrinVox SDK is licensed under the MIT License. This license applies to this SDK package only and does not license the PrinVox SaaS platform or other proprietary PrinVox source code.

prinvox-0.1.0/README.md

@@ -0,0 +1,212 @@
+# prinvox (Python SDK)
+
+Official Python SDK for **PrinVox Margin Guard**. It reports your AI usage (OpenAI, Anthropic, Google Gemini) to PrinVox so you see revenue, AI cost and gross margin per customer, plan and feature.
+
+> **Version 0.1.0.** The SDK is a thin wrapper over the PrinVox ingestion HTTP API, documented at [prinvox.com/en/docs](https://www.prinvox.com/en/docs), which you can also call directly.
+
+```bash
+pip install prinvox
+```
+
+Python **3.10+**. One dependency: [`httpx`](https://www.python-httpx.org/). Synchronous API: `track` blocks (network I/O, retries), so never call it directly on an asyncio event loop — use a worker thread or a background task (see FastAPI below). An async client is a planned follow-up.
+
+## What it needs — and what it never needs
+
+The SDK uses **one secret: your PrinVox ingestion key** (`mgik_…`, created under *Margin Guard → Connections*, one per provider). It sends usage **metadata** (model, token counts, your customer and feature labels).
+
+PrinVox does **not** need, and the SDK never touches, your OpenAI, Anthropic or Google (Gemini) API key. You keep calling those providers with their own SDKs and then report what they told you. Prices live on the server: the SDK contains none.
+
+**Server-side only.** Never put `PRINVOX_INGESTION_KEY` in browser code, a frontend bundle or a mobile app.
+
+## Quick start
+
+```python
+import os
+from prinvox import PrinVox
+
+client = PrinVox(api_key=os.environ["PRINVOX_INGESTION_KEY"])
+
+result = client.track(
+    provider="openai",
+    model="gpt-4.1",
+    event_id=response.id,        # idempotency key, see below
+    feature_key="assistant",
+    customer_ref="cus_123",
+    input_tokens=1000,
+    output_tokens=500,
+)
+print(result.status)  # "processed" or "duplicate"
+```
+
+`track` takes keyword arguments only, returns a `TrackResult` or raises a [`PrinVoxError`](#errors).
+
+### OpenAI
+
+```python
+from openai import OpenAI
+from prinvox import PrinVox
+
+openai_client = OpenAI()  # your own key, PrinVox never sees it
+prinvox = PrinVox(api_key=os.environ["PRINVOX_INGESTION_KEY_OPENAI"])
+MODEL = "gpt-4.1-mini"  # send the alias you requested, not a dated snapshot name
+
+response = openai_client.responses.create(model=MODEL, input="Summarize: ...")
+
+try:
+    prinvox.track(
+        provider="openai",
+        model=MODEL,
+        event_id=response.id,
+        feature_key="summarize",
+        customer_ref=app_customer_id,
+        input_tokens=response.usage.input_tokens if response.usage else None,
+        output_tokens=response.usage.output_tokens if response.usage else None,
+    )
+except Exception:
+    pass  # telemetry must never break your product (log it if you like)
+```
+
+### Anthropic
+
+```python
+import anthropic
+
+claude = anthropic.Anthropic()  # your own key
+message = claude.messages.create(model="claude-haiku-4-5", max_tokens=512, messages=[{"role": "user", "content": question}])
+
+prinvox.track(  # a PrinVox client created with the ingestion key for Anthropic
+    provider="anthropic",
+    model="claude-haiku-4-5",
+    event_id=message.id,
+    feature_key="support-answer",
+    customer_ref=app_customer_id,
+    input_tokens=message.usage.input_tokens,
+    output_tokens=message.usage.output_tokens,
+)
+```
+
+### Google Gemini
+
+The canonical provider value is `google_gemini` (a bare `google` is refused). Thinking tokens are billed as output, so add them. The 2.5 Flash family bills audio input higher, so say how much of the prompt was audio — `0` for text-only calls. **Without `input_audio_tokens` the cost of those models is stored as UNKNOWN** (never silently priced as text), and the report shows that figure as incomplete.
+
+```python
+import uuid
+from google import genai
+
+gemini = genai.Client()  # your own key
+response = gemini.models.generate_content(model="gemini-2.5-flash", contents=prompt)
+u = response.usage_metadata
+audio = sum((d.token_count or 0) for d in (u.prompt_tokens_details or []) if str(d.modality).endswith("AUDIO"))
+
+prinvox.track(  # a PrinVox client created with the ingestion key for Google Gemini
+    provider="google_gemini",
+    model="gemini-2.5-flash",
+    event_id=response.response_id or str(uuid.uuid4()),
+    feature_key="ai-chat",
+    customer_ref=app_customer_id,
+    input_tokens=u.prompt_token_count,
+    input_audio_tokens=audio,
+    output_tokens=(u.candidates_token_count or 0) + (u.thoughts_token_count or 0),
+)
+```
+
+### FastAPI (server-side)
+
+`track` is synchronous. Run it as a background task so it runs after the response and in a worker thread, never on the event loop.
+
+```python
+import os
+from fastapi import BackgroundTasks, FastAPI
+from prinvox import PrinVox
+
+app = FastAPI()
+prinvox = PrinVox(api_key=os.environ["PRINVOX_INGESTION_KEY_OPENAI"])  # read from the server's environment only
+
+
+def report(response_id: str, customer_id: str, usage) -> None:
+    try:
+        prinvox.track(
+            provider="openai", model="gpt-4.1-mini", event_id=response_id, feature_key="chat", customer_ref=customer_id,
+            input_tokens=usage.input_tokens, output_tokens=usage.output_tokens,
+        )
+    except Exception:
+        pass  # never fail the user's request over telemetry
+
+
+@app.post("/chat")
+def chat(prompt: str, customer_id: str, background: BackgroundTasks):
+    response = openai_client.responses.create(model="gpt-4.1-mini", input=prompt)
+    background.add_task(report, response.id, customer_id, response.usage)
+    return {"text": response.output_text}
+```
+
+## Event fields
+
+| Argument | Required | Notes |
+|---|---|---|
+| `provider` | yes | `"openai"`, `"anthropic"`, `"google_gemini"` (other strings are passed through). The server accepts the Gemini aliases `gemini`, `google-ai`, `google_ai`; a bare `google` is refused. |
+| `model` | yes | The exact alias you requested. An unpriced model is **stored with an unknown cost**, never an invented price. |
+| `event_id` | yes | Unique per provider request. **This is the idempotency key** (sent as `provider_request_id`). |
+| `feature_key` | yes | Your name for the AI feature. |
+| `input_tokens`, `output_tokens` | no | Omit them if the provider reported no usage — the cost is then unknown, not zero. |
+| `input_audio_tokens` | Gemini 2.5 Flash family | A subset of `input_tokens`; `0` if none. |
+| `customer_ref` | no | Your own id for the end customer (`external_customer_id`). Without it the cost is *Unattributed*. |
+| `stripe_customer_id` | no | The `cus_…` id in your connected Stripe account — the only link between usage and Stripe revenue. |
+| `timestamp` | no | A `datetime` (naive means UTC) or an ISO 8601 string. Defaults to now. Reports show the trailing 30 days by default. |
+
+There is no `metadata` field: the ingestion API does not store one.
+
+## Idempotency and retries
+
+`event_id` makes every call safe to repeat: the same `event_id` for the same provider is stored once and answered `duplicate`. The SDK therefore retries **only** transient failures — network errors, timeouts and 500/502/503/504 — up to `max_retries` (default 2, max 5) with bounded, jittered exponential backoff, always re-sending the identical body. It never retries 4xx, and never retries 429 (`Retry-After` is 60 s, far longer than a telemetry call should wait): you get a `PrinVoxRateLimitError` with `retry_after` and can resend later **with the same `event_id`**. `max_retries=0` disables retries.
+
+There is no automatic `event_id`: a random id would defeat idempotency across your own retries. Use the provider's response id.
+
+## Errors
+
+`track` raises `PrinVoxError` or a subclass — never anything carrying your key, the Authorization header or the event body:
+
+| Class | `code` | When |
+|---|---|---|
+| `PrinVoxValidationError` | `invalid_event`, `invalid_options` | Rejected locally; nothing was sent. |
+| `PrinVoxValidationError` | `invalid_request` | The server refused it (400 `invalid_body` / `provider_mismatch`, 413, …). See `api_error`. |
+| `PrinVoxAuthenticationError` | `authentication`, `forbidden` | 401 (wrong, missing or replaced key) / 403. |
+| `PrinVoxError` | `payment_required` | 402 — the free evaluation ended. |
+| `PrinVoxError` | `quota_exceeded` | 429 `trial_event_limit` — the evaluation's event quota is used up. Final: subscribe instead of resending. |
+| `PrinVoxRateLimitError` | `rate_limited` | 429 throttle — see `retry_after`; resend later with the same `event_id`. |
+| `PrinVoxError` | `server_error` | 5xx after retries. |
+| `PrinVoxConnectionError` | `network`, `timeout` | No answer. |
+| `PrinVoxError` | `invalid_response` | An answer the SDK cannot interpret (including an unexpected 2xx such as 202/204 from a proxy). The event may be stored; resending the same `event_id` is safe. |
+
+Attributes: `code`, `message`, `status_code`, `api_error`, `retry_after`, `request_id`; `to_dict()` is safe to log.
+
+## Options
+
+```python
+PrinVox(
+    api_key,                 # required
+    base_url=None,           # default https://www.prinvox.com — point it at a Preview environment to test
+    timeout=None,            # seconds for connecting and for each read, default 10
+    max_retries=2,
+    retry_delay=0.25,        # backoff base in seconds
+    http_client=None,        # your own httpx.Client (proxies, tests); you keep ownership of it
+)
+```
+
+`base_url` must be `https` (plain `http` only for `localhost`). To try the SDK without touching production data, use a Preview deployment's URL together with that environment's own ingestion key. The client holds a connection pool: reuse one instance, or use it as a context manager (`with PrinVox(...) as client:`). Its `repr()` redacts the key and it cannot be pickled or copied.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e . pytest ruff mypy build
+pytest && ruff check . && mypy && python -m build
+```
+
+## Versioning
+
+The ingestion API has no version prefix today; the SDK wraps it as it is. New optional fields will be added without breaking existing calls.
+
+## License
+
+The PrinVox SDK is licensed under the MIT License. This license applies to this SDK package only and does not license the PrinVox SaaS platform or other proprietary PrinVox source code.

prinvox-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling>=1.27"]  # 1.27+ ships license-files as dist-info/licenses/ (PEP 639)
+build-backend = "hatchling.build"
+
+[project]
+name = "prinvox"
+version = "0.1.0"
+description = "Official PrinVox Margin Guard SDK: report AI usage events (OpenAI, Anthropic, Google Gemini) from your Python server."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27,<1"]
+keywords = ["prinvox", "margin-guard", "ai", "llm", "usage", "cost", "gross-margin", "openai", "anthropic", "gemini"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+# MIT applies to THIS package only (see LICENSE). It does not license the PrinVox SaaS platform or any other proprietary PrinVox source.
+license = { text = "MIT" }
+license-files = ["LICENSE"]
+
+[project.urls]
+Homepage = "https://www.prinvox.com"
+Documentation = "https://www.prinvox.com/en/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/prinvox"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/prinvox", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 170
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/*" = ["E501"]  # a throwaway Preview smoke script: long call lines are clearer than wrapped ones
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/prinvox"]

prinvox-0.1.0/src/prinvox/__init__.py

@@ -0,0 +1,34 @@
+"""Official PrinVox Margin Guard SDK for Python.
+
+Report AI usage (OpenAI, Anthropic, Google Gemini) from your server::
+
+    from prinvox import PrinVox
+
+    client = PrinVox(api_key=os.environ["PRINVOX_INGESTION_KEY"])
+    client.track(provider="openai", model="gpt-4.1", event_id=response.id, feature_key="assistant", ...)
+"""
+
+from .client import PrinVox
+from .errors import (
+    PrinVoxAuthenticationError,
+    PrinVoxConnectionError,
+    PrinVoxError,
+    PrinVoxRateLimitError,
+    PrinVoxValidationError,
+)
+from .types import KnownProvider, Provider, TrackResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PrinVox",
+    "PrinVoxError",
+    "PrinVoxAuthenticationError",
+    "PrinVoxConnectionError",
+    "PrinVoxRateLimitError",
+    "PrinVoxValidationError",
+    "TrackResult",
+    "KnownProvider",
+    "Provider",
+    "__version__",
+]

prinvox-0.1.0/src/prinvox/client.py

@@ -0,0 +1,346 @@
+"""PrinVox Margin Guard client: a thin, synchronous wrapper over ``POST /api/margin-guard/usage``."""
+
+from __future__ import annotations
+
+import json
+import math
+import operator
+import random
+import re
+import time
+from datetime import datetime, timezone
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from . import errors
+from .errors import (
+    PrinVoxAuthenticationError,
+    PrinVoxConnectionError,
+    PrinVoxError,
+    PrinVoxRateLimitError,
+    PrinVoxValidationError,
+)
+from .types import Provider, TrackResult
+
+DEFAULT_BASE_URL = "https://www.prinvox.com"
+USAGE_PATH = "/api/margin-guard/usage"
+DEFAULT_TIMEOUT = 10.0
+DEFAULT_MAX_RETRIES = 2
+MAX_RETRIES_CEILING = 5
+DEFAULT_RETRY_DELAY = 0.25
+_LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1"}
+# A permanent 5xx (501, 505, ...) will not heal by waiting.
+_RETRYABLE_STATUSES = {500, 502, 503, 504}
+
+# Server-side limits (MARGIN_GUARD_FIELD_LIMITS); the server stays the authority, these only fail fast.
+_LIMITS = {"feature_key": 100, "model": 100, "event_id": 200, "customer_ref": 200}
+_BAD_KEY_CHARS = re.compile(r"[\s\x00-\x1f\x7f]")
+
+
+def _fail_options(message: str) -> PrinVoxError:
+    return PrinVoxValidationError(errors.INVALID_OPTIONS, message)
+
+
+def _fail_event(message: str) -> PrinVoxError:
+    return PrinVoxValidationError(errors.INVALID_EVENT, message)
+
+
+def _non_blank(value: object, limit: int) -> bool:
+    return isinstance(value, str) and value.strip() != "" and len(value) <= limit
+
+
+def _token_count(name: str, value: object) -> int | None:
+    if value is None:
+        return None
+    # bool is an int subclass (True would silently become 1); float and Decimal are not integers. Anything that is a true
+    # integer type (numpy.int64, ...) is accepted through operator.index and normalised to a plain int.
+    if isinstance(value, bool):
+        raise _fail_event(f"{name} must be a non-negative integer.")
+    try:
+        number = operator.index(value)  # type: ignore[arg-type]
+    except TypeError:
+        raise _fail_event(f"{name} must be a non-negative integer.") from None
+    if number < 0 or number > 2**53 - 1:
+        raise _fail_event(f"{name} must be a non-negative integer.")
+    return int(number)
+
+
+_ISO = re.compile(r"^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2})(?:[.,](\d+))?(Z|[+-]\d{2}(?::?\d{2})?)?$")
+
+
+def _normalise_iso(text: str) -> str:
+    """ISO 8601 extended form with any number of fractional digits and `Z` or `+hh[:mm]`, accepted identically on Python 3.10+."""
+    match = _ISO.match(text.strip())
+    if not match:
+        raise ValueError("not an ISO 8601 date-time")
+    day, clock, fraction, zone = match.groups()
+    fraction_part = f".{(fraction + '000000')[:6]}" if fraction else ""
+    if zone is None or zone == "Z":
+        zone_part = "+00:00" if zone == "Z" else ""
+    else:
+        digits = zone[1:].replace(":", "")
+        zone_part = f"{zone[0]}{digits[:2]}:{(digits + '00')[2:4]}"
+    return f"{day}T{clock}{fraction_part}{zone_part}"
+
+
+def _iso_timestamp(value: object) -> str:
+    if value is None:
+        moment = datetime.now(timezone.utc)
+    elif isinstance(value, datetime):
+        # A naive datetime is taken as UTC (documented); an aware one is converted to UTC.
+        moment = value.replace(tzinfo=timezone.utc) if value.tzinfo is None else value.astimezone(timezone.utc)
+    elif isinstance(value, str):
+        try:
+            parsed = datetime.fromisoformat(_normalise_iso(value))
+        except ValueError as exc:
+            raise _fail_event("timestamp is not a valid ISO 8601 date.") from exc
+        moment = parsed.replace(tzinfo=timezone.utc) if parsed.tzinfo is None else parsed.astimezone(timezone.utc)
+    else:
+        raise _fail_event("timestamp must be a datetime or an ISO 8601 string.")
+    return moment.isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+class PrinVox:
+    """PrinVox Margin Guard client. Server-side only: it holds your ingestion key.
+
+    ``api_key``: your PrinVox ingestion key (``mgik_...``), created under Margin Guard -> Connections, one per provider.
+    ``base_url``: defaults to ``https://www.prinvox.com``; set it to test against a Preview environment or a local server.
+    ``timeout``: seconds, applied to connecting and to each read. Default 10.
+    ``max_retries``: extra attempts after a network error, a timeout or a 500/502/503/504 answer. Default 2, maximum 5,
+    ``0`` disables. Retrying is safe because every event carries its own ``event_id`` (the server's idempotency key): a
+    repeat is answered ``duplicate`` and never counted twice. 429 and 4xx are never retried automatically.
+    ``retry_delay``: base of the exponential backoff in seconds (default 0.25: 0.25, 0.5, 1, ...).
+    ``http_client``: an ``httpx.Client`` of your own (proxies, a mock transport in tests). You keep ownership of it.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        retry_delay: float = DEFAULT_RETRY_DELAY,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if not isinstance(api_key, str) or api_key == "" or _BAD_KEY_CHARS.search(api_key):
+            raise _fail_options("api_key must be your PrinVox ingestion key (a non-empty string without whitespace).")
+
+        try:
+            parts = urlsplit(base_url if base_url is not None else DEFAULT_BASE_URL)
+            hostname = parts.hostname
+            port_number = parts.port  # raises ValueError for an out-of-range or non-numeric port
+        except ValueError as exc:
+            raise _fail_options("base_url must be a valid URL.") from exc
+        if parts.query or parts.fragment:
+            raise _fail_options("base_url must not contain a query string or fragment.")
+        if parts.scheme not in ("http", "https") or not hostname:
+            raise _fail_options("base_url must be a valid http(s) URL.")
+        if parts.scheme != "https" and hostname not in _LOOPBACK_HOSTS:
+            raise _fail_options("base_url must use https (http is allowed only for localhost).")
+        if parts.username or parts.password:
+            raise _fail_options("base_url must not contain credentials.")
+        host = f"[{hostname}]" if ":" in hostname else hostname
+        port = f":{port_number}" if port_number is not None else ""
+        self._endpoint = f"{parts.scheme}://{host}{port}{parts.path.rstrip('/')}{USAGE_PATH}"
+
+        effective_timeout = DEFAULT_TIMEOUT if timeout is None else timeout
+        if isinstance(effective_timeout, bool) or not isinstance(effective_timeout, (int, float)) or not math.isfinite(effective_timeout) or effective_timeout <= 0:
+            raise _fail_options("timeout must be a positive number of seconds.")
+        if isinstance(max_retries, bool) or not isinstance(max_retries, int) or not 0 <= max_retries <= MAX_RETRIES_CEILING:
+            raise _fail_options(f"max_retries must be an integer from 0 to {MAX_RETRIES_CEILING}.")
+        if isinstance(retry_delay, bool) or not isinstance(retry_delay, (int, float)) or not math.isfinite(retry_delay) or retry_delay < 0:
+            raise _fail_options("retry_delay must be a non-negative number of seconds.")
+
+        self._api_key = api_key
+        self._base_url = f"{parts.scheme}://{host}{port}{parts.path.rstrip('/')}"
+        self._timeout = float(effective_timeout)
+        self._max_retries = max_retries
+        self._retry_delay = float(retry_delay)
+        self._owns_client = http_client is None
+        self._http = http_client if http_client is not None else httpx.Client()
+
+    # -- secret hygiene ---------------------------------------------------------------------------------------------
+    def __repr__(self) -> str:
+        return f"PrinVox(base_url={self._base_url!r}, timeout={self._timeout!r}, max_retries={self._max_retries!r}, api_key=<redacted>)"
+
+    def __getstate__(self) -> object:
+        raise TypeError("PrinVox clients hold a secret and cannot be pickled or copied.")
+
+    def __copy__(self) -> object:
+        raise TypeError("PrinVox clients hold a secret and cannot be pickled or copied.")
+
+    def __deepcopy__(self, memo: object) -> object:
+        raise TypeError("PrinVox clients hold a secret and cannot be pickled or copied.")
+
+    # -- lifecycle ------------------------------------------------------------------------------------------------------
+    def close(self) -> None:
+        """Close the underlying HTTP client (only if this SDK created it)."""
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> PrinVox:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    # -- public API -----------------------------------------------------------------------------------------------------
+    def track(
+        self,
+        *,
+        provider: Provider,
+        model: str,
+        event_id: str,
+        feature_key: str,
+        input_tokens: int | None = None,
+        output_tokens: int | None = None,
+        input_audio_tokens: int | None = None,
+        customer_ref: str | None = None,
+        stripe_customer_id: str | None = None,
+        timestamp: object | None = None,
+    ) -> TrackResult:
+        """Report one AI request's usage. Returns ``TrackResult`` (``processed`` or ``duplicate``) or raises ``PrinVoxError``.
+
+        ``event_id`` is the idempotency key (sent as ``provider_request_id``): use the provider's own response id
+        (OpenAI ``response.id``, Anthropic ``message.id``, Gemini ``response_id``) or any id you keep stable for this
+        request across your own retries. Omit token counts the provider did not report: the cost is then UNKNOWN, never zero.
+        ``input_audio_tokens`` is REQUIRED (0 if none) for gemini-2.5-flash, gemini-2.5-flash-lite and gemini-3.1-flash-lite;
+        without it their cost is UNKNOWN. For Gemini, ``output_tokens`` includes thinking tokens.
+        ``timestamp``: a ``datetime`` (naive means UTC) or an ISO 8601 string (``2026-10-20T10:00:00.5Z``, ``+02:00`` ...); defaults to now.
+        This call is BLOCKING (network I/O, retries): do not call it directly on an asyncio event loop; run it in a thread or a background task.
+        """
+        body = json.dumps(
+            self._wire(provider, model, event_id, feature_key, input_tokens, output_tokens, input_audio_tokens, customer_ref, stripe_customer_id, timestamp),
+            separators=(",", ":"),
+        )
+        last: PrinVoxError | None = None
+        for attempt in range(self._max_retries + 1):
+            if attempt > 0:
+                # Exponential backoff with jitter (50-100 %), so many clients do not retry in lock-step.
+                time.sleep(self._retry_delay * 2 ** (attempt - 1) * (0.5 + random.random() / 2))
+            try:
+                return self._send(body)
+            except PrinVoxError as error:
+                last = error
+                # Only a transient failure is repeated. The same body (same event_id) goes out each time, so a repeat of
+                # an event the server already stored is answered `duplicate`, never counted twice.
+                transient = error.code in (errors.NETWORK, errors.TIMEOUT) or (
+                    error.code == errors.SERVER_ERROR and error.status_code in _RETRYABLE_STATUSES
+                )
+                if not transient:
+                    raise
+        assert last is not None
+        raise last
+
+    # -- internals ------------------------------------------------------------------------------------------------------
+    @staticmethod
+    def _wire(
+        provider: object,
+        model: object,
+        event_id: object,
+        feature_key: object,
+        input_tokens: object,
+        output_tokens: object,
+        input_audio_tokens: object,
+        customer_ref: object,
+        stripe_customer_id: object,
+        timestamp: object,
+    ) -> dict[str, Any]:
+        if not isinstance(provider, str) or provider.strip() == "":
+            raise _fail_event("provider is required.")
+        if not _non_blank(model, _LIMITS["model"]):
+            raise _fail_event("model is required (1-100 characters).")
+        if not _non_blank(event_id, _LIMITS["event_id"]):
+            raise _fail_event("event_id is required (1-200 characters): it is the idempotency key.")
+        if not _non_blank(feature_key, _LIMITS["feature_key"]):
+            raise _fail_event("feature_key is required (1-100 characters).")
+        if customer_ref is not None and not _non_blank(customer_ref, _LIMITS["customer_ref"]):
+            raise _fail_event("customer_ref must be 1-200 characters.")
+        if stripe_customer_id is not None and not _non_blank(stripe_customer_id, 100):
+            raise _fail_event("stripe_customer_id must be a Stripe customer id (cus_...).")
+        wire: dict[str, Any] = {
+            "feature_key": feature_key,
+            "provider": provider,
+            "model": model,
+            "provider_request_id": event_id,
+            "external_customer_id": customer_ref,
+            "stripe_customer_id": stripe_customer_id,
+            "input_tokens": _token_count("input_tokens", input_tokens),
+            "output_tokens": _token_count("output_tokens", output_tokens),
+            "input_audio_tokens": _token_count("input_audio_tokens", input_audio_tokens),
+            "occurred_at": _iso_timestamp(timestamp),
+        }
+        # Fields not given are omitted, never sent as null/0: "unknown" must stay unknown.
+        return {k: v for k, v in wire.items() if v is not None}
+
+    def _send(self, body: str) -> TrackResult:
+        try:
+            response = self._http.post(
+                self._endpoint,
+                content=body,
+                headers={"authorization": f"Bearer {self._api_key}", "content-type": "application/json", "accept": "application/json"},
+                timeout=self._timeout,
+            )
+        except (httpx.LocalProtocolError, httpx.UnsupportedProtocol):
+            # Something wrong on OUR side of the request (for example a header value h11 refuses): retrying cannot help.
+            raise _fail_options("The request could not be built (check api_key and base_url).") from None
+        except httpx.TimeoutException:
+            # Fixed messages only: the underlying exception is deliberately not attached (it could echo request details).
+            raise PrinVoxConnectionError(errors.TIMEOUT, f"PrinVox did not answer within {self._timeout:g} s.") from None
+        except httpx.HTTPError:
+            raise PrinVoxConnectionError(errors.NETWORK, "Could not reach PrinVox (network error).") from None
+        return self._interpret(response)
+
+    @staticmethod
+    def _interpret(response: httpx.Response) -> TrackResult:
+        status = response.status_code
+        request_id = response.headers.get("x-request-id")
+        payload: dict[str, Any] | None = None
+        try:
+            parsed = json.loads(response.text)
+            payload = parsed if isinstance(parsed, dict) else None
+        except ValueError:
+            payload = None
+        raw_error = payload.get("error") if payload else None
+        api_error = raw_error[:100] if isinstance(raw_error, str) else None
+        common: dict[str, Any] = {"status_code": status, "api_error": api_error, "request_id": request_id}
+
+        if status in (200, 201):
+            if payload and payload.get("status") in ("processed", "duplicate"):
+                return TrackResult(status=payload["status"])
+            raise PrinVoxError(errors.INVALID_RESPONSE, "PrinVox answered with an unexpected body.", status_code=status, request_id=request_id)
+        # Any other 2xx is not part of the contract: say so, instead of calling a possibly stored event "rejected".
+        if 200 <= status < 300:
+            raise PrinVoxError(errors.INVALID_RESPONSE, f"PrinVox answered with an unexpected success status ({status}).", status_code=status, request_id=request_id)
+        if 300 <= status < 400:
+            # httpx does not follow redirects here: the event was never evaluated. Almost always a base_url problem.
+            raise PrinVoxError(
+                errors.INVALID_RESPONSE,
+                f"PrinVox redirected the request ({status}); check base_url (the canonical host is https://www.prinvox.com).",
+                status_code=status,
+                request_id=request_id,
+            )
+        if status == 401:
+            raise PrinVoxAuthenticationError(errors.AUTHENTICATION, "PrinVox rejected the ingestion key (missing, wrong or replaced).", **common)
+        if status == 403:
+            raise PrinVoxAuthenticationError(errors.FORBIDDEN, "PrinVox refused this request (403).", **common)
+        if status == 402:
+            raise PrinVoxError(errors.PAYMENT_REQUIRED, "The free evaluation has ended; subscribe to keep ingesting events.", **common)
+        if status == 429:
+            # `trial_event_limit` is the evaluation's total event quota: final, not a throttle -- resending will not help.
+            if api_error == "trial_event_limit":
+                raise PrinVoxError(errors.QUOTA_EXCEEDED, "The free evaluation has used all of its events; subscribe to keep ingesting.", **common)
+            retry_after: float | None = None
+            try:
+                header = float(response.headers.get("retry-after", ""))
+                retry_after = header if math.isfinite(header) and header > 0 else None
+            except ValueError:
+                retry_after = None
+            raise PrinVoxRateLimitError(errors.RATE_LIMITED, "PrinVox rate limit reached; resend later with the same event_id.", retry_after=retry_after, **common)
+        if status >= 500:
+            raise PrinVoxError(errors.SERVER_ERROR, f"PrinVox is temporarily unavailable ({status}).", **common)
+        suffix = f": {api_error}" if api_error else ""
+        raise PrinVoxValidationError(errors.INVALID_REQUEST, f"PrinVox rejected the event ({status}{suffix}).", **common)

prinvox-0.1.0/src/prinvox/errors.py

@@ -0,0 +1,81 @@
+"""Exceptions raised by the PrinVox SDK.
+
+Every exception carries only safe, fixed information: a stable ``code``, an HTTP ``status_code`` where there was one,
+the server's own error string (``api_error``), ``retry_after`` and ``request_id``. None of them can contain the ingestion
+key, the Authorization header or the event body: messages are fixed strings built inside this package.
+"""
+
+from __future__ import annotations
+
+# Stable error codes, identical to the Node.js SDK's.
+INVALID_OPTIONS = "invalid_options"  # the client was constructed with something unusable
+INVALID_EVENT = "invalid_event"  # rejected locally, nothing was sent
+AUTHENTICATION = "authentication"  # 401: missing, wrong or replaced ingestion key
+FORBIDDEN = "forbidden"  # 403
+INVALID_REQUEST = "invalid_request"  # other 4xx the server rejected (400 invalid_body / provider_mismatch, 413, ...)
+PAYMENT_REQUIRED = "payment_required"  # 402: the free evaluation ended (trial_expired)
+QUOTA_EXCEEDED = "quota_exceeded"  # 429 trial_event_limit: the evaluation's event quota is used up (final)
+RATE_LIMITED = "rate_limited"  # 429 throttle: resend later with the same event_id
+SERVER_ERROR = "server_error"  # 5xx
+NETWORK = "network"  # no answer: DNS, connection, TLS
+TIMEOUT = "timeout"  # no answer within ``timeout``
+INVALID_RESPONSE = "invalid_response"  # an answer the SDK cannot interpret
+
+
+class PrinVoxError(Exception):
+    """Base class of every error this SDK raises."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        status_code: int | None = None,
+        api_error: str | None = None,
+        retry_after: float | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        self.api_error = api_error
+        self.retry_after = retry_after
+        self.request_id = request_id
+
+    def __str__(self) -> str:
+        return self.message
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(code={self.code!r}, status_code={self.status_code!r}, "
+            f"api_error={self.api_error!r}, message={self.message!r})"
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        """Safe to log or serialise: no secret can be in any of these fields."""
+        return {
+            "name": type(self).__name__,
+            "code": self.code,
+            "message": self.message,
+            "status_code": self.status_code,
+            "api_error": self.api_error,
+            "retry_after": self.retry_after,
+            "request_id": self.request_id,
+        }
+
+
+class PrinVoxValidationError(PrinVoxError):
+    """The event was refused: locally (``invalid_event``) or by the server (``invalid_request``, 400/413/...)."""
+
+
+class PrinVoxAuthenticationError(PrinVoxError):
+    """401 (wrong, missing or replaced ingestion key) or 403."""
+
+
+class PrinVoxRateLimitError(PrinVoxError):
+    """429 throttle. ``retry_after`` (seconds) is the server's hint; resend later with the SAME ``event_id``."""
+
+
+class PrinVoxConnectionError(PrinVoxError):
+    """No answer: a network failure (``code == "network"``) or a timeout (``code == "timeout"``)."""

prinvox-0.1.0/src/prinvox/types.py

@@ -0,0 +1,22 @@
+"""Public types. Plain dataclasses: no third-party model library."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+#: Providers PrinVox prices today. ``Provider`` stays open (``str``) so a provider added later needs no SDK upgrade.
+KnownProvider = Literal["openai", "anthropic", "google_gemini"]
+Provider = KnownProvider | str
+
+
+@dataclass(frozen=True)
+class TrackResult:
+    """The server's answer to a stored or repeated event."""
+
+    #: ``processed``: stored now. ``duplicate``: this ``event_id`` was already stored; nothing changed.
+    status: Literal["processed", "duplicate"]
+
+    @property
+    def duplicate(self) -> bool:
+        return self.status == "duplicate"