llm-agent-metering 0.3.1__tar.gz

llm_agent_metering-0.3.1/LICENSE

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

llm_agent_metering-0.3.1/MANIFEST.in

@@ -0,0 +1,4 @@
+include agent_metering.pth
+include setup.py
+include LICENSE
+include README.md

llm_agent_metering-0.3.1/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: llm-agent-metering
+Version: 0.3.1
+Summary: Language-agnostic LLM cost metering via HTTP proxy — track spend per customer and feature
+Author: prantakhandaker
+License: MIT
+Project-URL: Homepage, https://github.com/prantakhandaker/agent_metering
+Project-URL: Repository, https://github.com/prantakhandaker/agent_metering
+Project-URL: Issues, https://github.com/prantakhandaker/agent_metering/issues
+Project-URL: Changelog, https://github.com/prantakhandaker/agent_metering/releases
+Keywords: llm,openai,anthropic,cost-tracking,metering,observability,saas
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.23.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: dashboard
+Requires-Dist: streamlit>=1.28.0; extra == "dashboard"
+Requires-Dist: pandas>=2.0.0; extra == "dashboard"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Provides-Extra: example
+Requires-Dist: openai>=1.0.0; extra == "example"
+Requires-Dist: anthropic>=0.25.0; extra == "example"
+Provides-Extra: vertex
+Requires-Dist: google-auth>=2.22.0; extra == "vertex"
+Dynamic: license-file
+
+# agent_metering
+
+[![CI](https://github.com/prantakhandaker/agent_metering/actions/workflows/ci.yml/badge.svg)](https://github.com/prantakhandaker/agent_metering/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+
+**Language-agnostic LLM cost metering** for B2B SaaS — point any OpenAI / Anthropic client at the HTTP proxy (Node, Go, Java, PHP, Python, curl, …).
+
+**MIT open source** — [CONTRIBUTING](CONTRIBUTING.md) · [SECURITY](SECURITY.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
+
+## Install
+
+```bash
+pip install llm-agent-metering
+# optional extras:
+# pip install "llm-agent-metering[dashboard]"
+# pip install "llm-agent-metering[example]"
+```
+
+From GitHub (latest main):
+
+```bash
+pip install "git+https://github.com/prantakhandaker/agent_metering.git"
+```
+
+## Any language (recommended)
+
+Run the proxy once, then set your SDK **base URL** to it. No SDK install in the app language required.
+
+```bash
+pip install llm-agent-metering
+python -m uvicorn agent_metering.proxy:app --host 0.0.0.0 --port 8787
+```
+
+| Provider | Base URL / env |
+|----------|----------------|
+| OpenAI | `http://127.0.0.1:8787/proxy/openai/v1` → `OPENAI_BASE_URL` |
+| Anthropic | `http://127.0.0.1:8787/proxy/anthropic` → `ANTHROPIC_BASE_URL` |
+| Azure | `.../proxy/azure/v1` → `AZURE_OPENAI_BASE_URL` |
+
+Optional per-user / feature headers (stripped before upstream):
+
+- `X-User-Id` (preferred) or `X-Customer-Id`
+- `X-Feature`
+- Or OpenAI body field `user` / Anthropic `metadata.user_id`
+
+Defaults: env `AGENT_METERING_CUSTOMER_ID` / `AGENT_METERING_FEATURE`, else `default`.
+
+Spend → local SQLite `agent_metering.db`. Dashboard:
+
+```bash
+python -m streamlit run examples/dashboard.py   # pip install "llm-agent-metering[dashboard]"
+```
+
+### Node
+
+```js
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseURL: "http://127.0.0.1:8787/proxy/openai/v1",
+  defaultHeaders: { "X-User-Id": "user_42" },
+});
+
+await client.chat.completions.create({
+  model: "gpt-4o-mini",
+  messages: [{ role: "user", content: "Hi" }],
+});
+```
+
+Full script: [`examples/proxy_node_example.mjs`](examples/proxy_node_example.mjs).
+
+### curl
+
+```bash
+curl http://127.0.0.1:8787/proxy/openai/v1/chat/completions \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "X-User-Id: user_42" \
+  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hi"}]}'
+```
+
+### Go
+
+```go
+client := openai.NewClient(
+  option.WithAPIKey(os.Getenv("OPENAI_API_KEY")),
+  option.WithBaseURL("http://127.0.0.1:8787/proxy/openai/v1"),
+  option.WithHeader("X-User-Id", "user_42"),
+)
+```
+
+### Docker sidecar
+
+```bash
+docker compose -f examples/docker-compose.sidecar.yml up --build
+```
+
+App containers only need `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` pointing at `http://metering-proxy:8787/proxy/...`.
+
+Or wrap a local process:
+
+```bash
+python -m agent_metering run --start-proxy -- python your_app.py
+```
+
+## Python-only shortcut (optional)
+
+Same venv install auto-patches OpenAI / Anthropic SDKs (no base URL change):
+
+```bash
+pip install llm-agent-metering
+# run your Python app — no import required
+```
+
+Opt out: `AGENT_METERING_AUTO=0`. Demo: `python examples/auto_instrument_example.py`.
+
+Also detects FastAPI/Flask/Django request users and OpenAI `user=` when present.
+
+## Who this is for / not for
+
+**For:** Any stack that can set an LLM HTTP base URL (or env) and needs **per-customer / per-user / per-feature** spend.
+
+**Not for:** Full tracing/evals (Langfuse), or replacing multi-provider gateways you already run (LiteLLM / Portkey) unless you put this proxy in front.
+
+## Why
+
+Flat API rate limits do not protect margin. Agent workloads are open-ended: tool loops and long contexts can burn tokens quietly. Metering per customer/feature surfaces that before margin disappears.
+
+## Project layout
+
+**Primary (any language):** `proxy.py`, `providers/`, `cli.py`  
+**Python convenience:** `autoload.py` (`.pth`), `instrument.py`, `user_detect.py`, `frameworks.py`  
+**Shared:** `config.py`, `core.py`, `storage.py`, `context.py`
+
+## Tests
+
+```bash
+pytest
+```
+
+## Releasing
+
+Maintainers publish to PyPI via GitHub Actions Trusted Publishing (no API token in secrets).
+
+1. One-time on [pypi.org](https://pypi.org): **Publishing → Pending publisher**
+   - Project: `llm-agent-metering`
+   - Owner: `prantakhandaker`
+   - Repository: `agent_metering`
+   - Workflow: `publish.yml`
+   - Environment: **leave empty**
+2. Bump `version` in `pyproject.toml` to match the release tag.
+3. Tag and release:
+
+```bash
+# version in pyproject.toml must match the tag
+git tag v0.3.1
+git push origin v0.3.1
+# then GitHub → Releases → Draft release from that tag → Publish
+```
+
+Publishing workflow: [`.github/workflows/publish.yml`](.github/workflows/publish.yml).
+
+## License
+
+[MIT](LICENSE)

llm_agent_metering-0.3.1/README.md

@@ -0,0 +1,167 @@
+# agent_metering
+
+[![CI](https://github.com/prantakhandaker/agent_metering/actions/workflows/ci.yml/badge.svg)](https://github.com/prantakhandaker/agent_metering/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+
+**Language-agnostic LLM cost metering** for B2B SaaS — point any OpenAI / Anthropic client at the HTTP proxy (Node, Go, Java, PHP, Python, curl, …).
+
+**MIT open source** — [CONTRIBUTING](CONTRIBUTING.md) · [SECURITY](SECURITY.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
+
+## Install
+
+```bash
+pip install llm-agent-metering
+# optional extras:
+# pip install "llm-agent-metering[dashboard]"
+# pip install "llm-agent-metering[example]"
+```
+
+From GitHub (latest main):
+
+```bash
+pip install "git+https://github.com/prantakhandaker/agent_metering.git"
+```
+
+## Any language (recommended)
+
+Run the proxy once, then set your SDK **base URL** to it. No SDK install in the app language required.
+
+```bash
+pip install llm-agent-metering
+python -m uvicorn agent_metering.proxy:app --host 0.0.0.0 --port 8787
+```
+
+| Provider | Base URL / env |
+|----------|----------------|
+| OpenAI | `http://127.0.0.1:8787/proxy/openai/v1` → `OPENAI_BASE_URL` |
+| Anthropic | `http://127.0.0.1:8787/proxy/anthropic` → `ANTHROPIC_BASE_URL` |
+| Azure | `.../proxy/azure/v1` → `AZURE_OPENAI_BASE_URL` |
+
+Optional per-user / feature headers (stripped before upstream):
+
+- `X-User-Id` (preferred) or `X-Customer-Id`
+- `X-Feature`
+- Or OpenAI body field `user` / Anthropic `metadata.user_id`
+
+Defaults: env `AGENT_METERING_CUSTOMER_ID` / `AGENT_METERING_FEATURE`, else `default`.
+
+Spend → local SQLite `agent_metering.db`. Dashboard:
+
+```bash
+python -m streamlit run examples/dashboard.py   # pip install "llm-agent-metering[dashboard]"
+```
+
+### Node
+
+```js
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseURL: "http://127.0.0.1:8787/proxy/openai/v1",
+  defaultHeaders: { "X-User-Id": "user_42" },
+});
+
+await client.chat.completions.create({
+  model: "gpt-4o-mini",
+  messages: [{ role: "user", content: "Hi" }],
+});
+```
+
+Full script: [`examples/proxy_node_example.mjs`](examples/proxy_node_example.mjs).
+
+### curl
+
+```bash
+curl http://127.0.0.1:8787/proxy/openai/v1/chat/completions \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "X-User-Id: user_42" \
+  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hi"}]}'
+```
+
+### Go
+
+```go
+client := openai.NewClient(
+  option.WithAPIKey(os.Getenv("OPENAI_API_KEY")),
+  option.WithBaseURL("http://127.0.0.1:8787/proxy/openai/v1"),
+  option.WithHeader("X-User-Id", "user_42"),
+)
+```
+
+### Docker sidecar
+
+```bash
+docker compose -f examples/docker-compose.sidecar.yml up --build
+```
+
+App containers only need `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` pointing at `http://metering-proxy:8787/proxy/...`.
+
+Or wrap a local process:
+
+```bash
+python -m agent_metering run --start-proxy -- python your_app.py
+```
+
+## Python-only shortcut (optional)
+
+Same venv install auto-patches OpenAI / Anthropic SDKs (no base URL change):
+
+```bash
+pip install llm-agent-metering
+# run your Python app — no import required
+```
+
+Opt out: `AGENT_METERING_AUTO=0`. Demo: `python examples/auto_instrument_example.py`.
+
+Also detects FastAPI/Flask/Django request users and OpenAI `user=` when present.
+
+## Who this is for / not for
+
+**For:** Any stack that can set an LLM HTTP base URL (or env) and needs **per-customer / per-user / per-feature** spend.
+
+**Not for:** Full tracing/evals (Langfuse), or replacing multi-provider gateways you already run (LiteLLM / Portkey) unless you put this proxy in front.
+
+## Why
+
+Flat API rate limits do not protect margin. Agent workloads are open-ended: tool loops and long contexts can burn tokens quietly. Metering per customer/feature surfaces that before margin disappears.
+
+## Project layout
+
+**Primary (any language):** `proxy.py`, `providers/`, `cli.py`  
+**Python convenience:** `autoload.py` (`.pth`), `instrument.py`, `user_detect.py`, `frameworks.py`  
+**Shared:** `config.py`, `core.py`, `storage.py`, `context.py`
+
+## Tests
+
+```bash
+pytest
+```
+
+## Releasing
+
+Maintainers publish to PyPI via GitHub Actions Trusted Publishing (no API token in secrets).
+
+1. One-time on [pypi.org](https://pypi.org): **Publishing → Pending publisher**
+   - Project: `llm-agent-metering`
+   - Owner: `prantakhandaker`
+   - Repository: `agent_metering`
+   - Workflow: `publish.yml`
+   - Environment: **leave empty**
+2. Bump `version` in `pyproject.toml` to match the release tag.
+3. Tag and release:
+
+```bash
+# version in pyproject.toml must match the tag
+git tag v0.3.1
+git push origin v0.3.1
+# then GitHub → Releases → Draft release from that tag → Publish
+```
+
+Publishing workflow: [`.github/workflows/publish.yml`](.github/workflows/publish.yml).
+
+## License
+
+[MIT](LICENSE)

llm_agent_metering-0.3.1/agent_metering/__init__.py

@@ -0,0 +1,58 @@
+"""agent_metering — lightweight LLM cost tracking for B2B AI agents.
+
+Install-only (site .pth) or import-once::
+
+    pip install agent-metering
+    # or: import agent_metering
+
+    agent_metering.set_user("cust_123")  # optional, once per request
+
+Existing OpenAI / Anthropic calls are metered automatically.
+"""
+
+from agent_metering.alerts import check_budgets, slack_notifier
+from agent_metering.context import (
+    clear_feature,
+    clear_user,
+    get_feature,
+    get_user,
+    set_feature,
+    set_user,
+    user_context,
+)
+from agent_metering.core import Meter
+from agent_metering.instrument import disable, enable, get_meter, is_enabled, maybe_auto_enable
+from agent_metering.storage import BaseStorage, SQLiteStorage, UsageRecord
+
+__all__ = [
+    "Meter",
+    "SQLiteStorage",
+    "BaseStorage",
+    "UsageRecord",
+    "check_budgets",
+    "slack_notifier",
+    "app",
+    "enable",
+    "disable",
+    "is_enabled",
+    "get_meter",
+    "set_user",
+    "get_user",
+    "clear_user",
+    "set_feature",
+    "get_feature",
+    "clear_feature",
+    "user_context",
+]
+
+
+def __getattr__(name: str):
+    if name == "app":
+        from agent_metering.proxy import app as proxy_app
+
+        return proxy_app
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+# Auto-enable when config JSON is present (or AGENT_METERING_AUTO=1).
+maybe_auto_enable()

llm_agent_metering-0.3.1/agent_metering/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m agent_metering` (avoids blocked console .exe shims on some Windows setups)."""
+
+from agent_metering.cli import main
+
+raise SystemExit(main())

llm_agent_metering-0.3.1/agent_metering/alerts.py

@@ -0,0 +1,81 @@
+"""Budget checks and Slack alerting helpers."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Optional
+
+
+def check_budgets(
+    meter: Any,
+    customer_limits: Optional[dict[str, float]] = None,
+    feature_limits: Optional[dict[str, float]] = None,
+    window_seconds: float = 86400,
+    on_breach: Optional[Callable[[str, str, float, float], None]] = None,
+) -> list[dict[str, Any]]:
+    """Check spend within a rolling window against customer/feature limits.
+
+    Returns a list of breach dicts:
+    ``{"scope": "customer"|"feature", "id": ..., "spent": ..., "limit": ...}``
+    """
+    since_ts = time.time() - window_seconds
+    breaches: list[dict[str, Any]] = []
+
+    if customer_limits:
+        by_customer = meter.cost_by_customer(since_ts=since_ts)
+        for customer_id, limit in customer_limits.items():
+            spent = float(by_customer.get(customer_id, {}).get("total_cost_usd", 0.0))
+            if spent > limit:
+                breach = {
+                    "scope": "customer",
+                    "id": customer_id,
+                    "spent": spent,
+                    "limit": limit,
+                }
+                breaches.append(breach)
+                if on_breach is not None:
+                    on_breach("customer", customer_id, spent, limit)
+
+    if feature_limits:
+        by_feature = meter.cost_by_feature(since_ts=since_ts)
+        for feature, limit in feature_limits.items():
+            spent = float(by_feature.get(feature, {}).get("total_cost_usd", 0.0))
+            if spent > limit:
+                breach = {
+                    "scope": "feature",
+                    "id": feature,
+                    "spent": spent,
+                    "limit": limit,
+                }
+                breaches.append(breach)
+                if on_breach is not None:
+                    on_breach("feature", feature, spent, limit)
+
+    return breaches
+
+
+def slack_notifier(webhook_url: str) -> Callable[[str, str, float, float], None]:
+    """Return an ``on_breach``-compatible function that POSTs to Slack."""
+
+    def _notify(scope: str, id_: str, spent: float, limit: float) -> None:
+        text = (
+            f":warning: Budget breach — {scope} `{id_}` spent "
+            f"${spent:.4f} (limit ${limit:.4f})"
+        )
+        payload = json.dumps({"text": text}).encode("utf-8")
+        req = urllib.request.Request(
+            webhook_url,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                resp.read()
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            print(f"slack_notifier error: {exc}")
+
+    return _notify

llm_agent_metering-0.3.1/agent_metering/autoload.py

@@ -0,0 +1,21 @@
+"""Site .pth entry — enable metering without any app import.
+
+Installed as ``agent_metering.pth`` in site-packages so every Python
+process in that environment auto-instruments OpenAI / Anthropic SDKs.
+Opt out with ``AGENT_METERING_AUTO=0``.
+"""
+
+from __future__ import annotations
+
+
+def _autoload() -> None:
+    try:
+        from agent_metering.instrument import maybe_auto_enable
+
+        maybe_auto_enable()
+    except Exception:
+        # Never break host interpreter startup.
+        pass
+
+
+_autoload()