agentbill-sdk 0.1.0__tar.gz

agentbill_sdk-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Environment — never commit real credentials
+.env
+.env.local
+
+# Dependencies
+node_modules/
+sdk/node/node_modules/
+
+# Build output
+dist/
+sdk/node/dist/
+
+# macOS
+.DS_Store
+
+# Logs
+*.log
+npm-debug.log*

agentbill_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,333 @@
+Metadata-Version: 2.4
+Name: agentbill-sdk
+Version: 0.1.0
+Summary: Usage-based billing for AI agent developers. 3-line integration.
+Project-URL: Homepage, https://github.com/marketinglior-pixel/agentbill
+Project-URL: Repository, https://github.com/marketinglior-pixel/agentbill
+Project-URL: Documentation, https://github.com/marketinglior-pixel/agentbill#readme
+Author-email: AgentBill <marketinglior@gmail.com>
+License: MIT
+Keywords: agents,ai,billing,llm,metering,usage-based
+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.9
+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.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgentBill
+
+**Usage-based billing for AI agents. 3-line integration.**
+
+Stop charging flat monthly fees for agents whose costs swing between $2 and $40 per run.  
+Stop losing money when a rogue agent loops for 45 minutes at your expense.
+
+---
+
+## The problem
+
+You built an AI agent. It does something valuable. You charge $99/month flat.
+
+- A 3-second run costs you $0.80. You made $98.20.
+- A 45-minute recursive loop costs you $140. You lost $41.
+
+And you don't find out until your OpenAI invoice arrives.
+
+## The fix: 3 lines
+
+```python
+from agentbill import meter
+
+@meter(event="research_run", customer_id_from="customer_id", preflight=True)
+async def run_agent(customer_id: str, topic: str) -> str:
+    result = await call_your_llm(topic)
+    return result
+```
+
+That's it. AgentBill now:
+- Checks the customer's credit balance **before** the LLM call (`preflight=True`)
+- Records the credit usage **after** the function succeeds
+- Blocks the call with `BudgetExhaustedError` the moment the customer runs out — no surprise overages
+
+---
+
+## Install
+
+```bash
+pip install agentbill
+```
+
+```bash
+npm install agentbill
+```
+
+---
+
+## Quick start (5 minutes)
+
+### 1. Get an API key
+
+```
+AGENTBILL_API_KEY=your_key_here
+```
+
+### 2. Decorate your agent
+
+```python
+from agentbill import meter, BudgetExhaustedError
+
+# Charge 1 credit per run
+@meter(event="research_run", customer_id_from="customer_id")
+async def run_agent(customer_id: str, topic: str) -> str:
+    ...
+
+# Pre-flight: block BEFORE the LLM call if the customer is out of credits
+@meter(event="research_run", customer_id_from="customer_id", preflight=True)
+async def run_agent_safe(customer_id: str, topic: str) -> str:
+    ...
+
+# Outcome-based: charge credits only if the task succeeded
+@meter(
+    event="ticket_resolved",
+    customer_id_from="customer_id",
+    units=lambda result: 5 if result["resolved"] else 0,
+)
+async def resolve_ticket(customer_id: str, ticket_id: str) -> dict:
+    ...
+```
+
+### 3. Handle credit exhaustion
+
+```python
+try:
+    result = await run_agent(customer_id="cust_123", topic="quarterly report")
+except BudgetExhaustedError as e:
+    # Show paywall, send upgrade email, pause the agent — your call
+    show_paywall(e.customer_id)
+```
+
+### 4. Watch your dashboard
+
+Open `https://your-instance/dashboard` to see every customer's credit usage in real time:
+
+- Credit usage bar (turns red at 80%)
+- Remaining credits
+- BLOCKED badge when limit is hit
+
+---
+
+## Node.js
+
+```typescript
+import { meter, BudgetExhaustedError } from 'agentbill'
+
+const runAgent = meter(
+  async ({ customerId, topic }: { customerId: string; topic: string }) => {
+    const result = await callLLM(topic)
+    return result
+  },
+  {
+    event: 'research_run',
+    customerIdFrom: 'customerId',
+    preflight: true,
+  }
+)
+
+try {
+  await runAgent({ customerId: 'cust_123', topic: 'quarterly report' })
+} catch (e) {
+  if (e instanceof BudgetExhaustedError) {
+    showPaywall(e.customerId)
+  }
+}
+```
+
+---
+
+## Pricing for outcomes, not tokens
+
+Most billing tools count *events*. They have no concept of "did the task actually succeed?"
+
+AgentBill does. The credit count is a function of the result — you decide what success means:
+
+```python
+# Support agent — charge credits only when the ticket is resolved
+@meter(
+    event="ticket_resolved",
+    customer_id_from="customer_id",
+    units=lambda result: 5 if result["resolved"] else 0,
+)
+async def resolve_ticket(customer_id: str, ticket_id: str) -> dict:
+    resolution = await run_support_agent(ticket_id)
+    return resolution  # {"resolved": True, "summary": "..."}
+```
+
+```python
+# Coding agent — charge credits only when tests pass
+@meter(
+    event="code_generated",
+    customer_id_from="customer_id",
+    units=lambda result: 10 if result["tests_passed"] else 0,
+)
+async def generate_code(customer_id: str, spec: str) -> dict:
+    code = await run_coding_agent(spec)
+    passed = run_tests(code)
+    return {"code": code, "tests_passed": passed}
+```
+
+```python
+# Research agent — charge by volume processed
+@meter(
+    event="research_completed",
+    customer_id_from="customer_id",
+    units=lambda result: result["pages_processed"],
+)
+async def research(customer_id: str, topic: str) -> dict:
+    return await run_research_agent(topic)
+    # returns {"summary": "...", "pages_processed": 14}
+```
+
+If credits resolve to `0` — no event is recorded. The customer is not charged. Your margins stay intact.
+
+---
+
+## Why AgentBill? (vs. Metronome / Orb / Stripe)
+
+**Metronome and Orb** are excellent for SaaS products. They're built around usage records, pricing tiers, and invoicing. If you're building a database or an API with predictable units — use them.
+
+AgentBill is different in two ways:
+
+### 1. Pre-flight enforcement
+
+Metronome and Orb record usage *after the fact*. They have no way to stop an expensive operation before it starts.
+
+AgentBill checks the customer's credit balance **before** the LLM call runs. If they're out — the function never executes. No API call is made. No money is spent.
+
+```
+Metronome/Orb:   run → bill → (oops, over budget)
+AgentBill:       check → [blocked if over budget] → run → bill
+```
+
+This matters when a single agent run costs $0.80 on a good day and $43 on a bad one.
+
+### 2. Lives inside your function
+
+Metronome requires you to emit events from your infrastructure. AgentBill is a decorator — it wraps your function directly and handles everything: pre-flight check, credit deduction, idempotency, error handling.
+
+No event pipelines. No webhooks to configure. One line.
+
+---
+
+## Current scope — what AgentBill solves today
+
+AgentBill is designed for **atomic, short-running agent tasks** — functions that complete in a single execution and return a deterministic result.
+
+**Works well for:**
+- Research runs, report generation, document processing
+- Support ticket resolution (single attempt)
+- Code generation with test validation
+- Any agent function that runs once and returns a clear result
+
+**Not yet supported:**
+- **Multi-signal outcomes** — tasks where success is determined by multiple events over time (e.g., a ticket that gets reopened 3 days later)
+- **Long-running workflows** — agents that run for hours or days across multiple steps
+- **Outcome invalidation** — billing reversal when a previously "successful" result is later undone
+
+These are real problems. They require a different architecture — event sourcing, state machines, reversal logic. If you're building at that level of complexity, AgentBill's current version isn't the right tool yet.
+
+For atomic tasks — it's 3 lines.
+
+---
+
+## How it works
+
+```
+Your agent code
+     │
+     ▼
+@meter decorator
+     │
+     ├─ [preflight=true] GET /budget → is_blocked? → raise BudgetExhaustedError
+     │
+     ├─ Run your function (LLM call happens here)
+     │
+     ├─ [function succeeded] POST /events → record credits used
+     │
+     └─ Return result
+```
+
+Credits are recorded **after success only**. If your agent throws, the customer is not charged.
+
+---
+
+## API reference
+
+### `@meter(event, options)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `event` | `str` | required | Event label, shown in dashboard |
+| `customer_id` | `str` | — | Fixed customer identifier |
+| `customer_id_from` | `str` | — | Name of a function parameter to read customer_id from |
+| `units` | `int \| callable` | `1` | Credits per call, or a function `(result) -> int` returning 0 to skip billing |
+| `preflight` | `bool` | `False` | Check credit balance before running. Blocks immediately if exhausted. |
+| `metadata` | `dict` | — | Static key-value pairs attached to every event |
+
+### Exceptions
+
+| Exception | When |
+|---|---|
+| `BudgetExhaustedError` | Customer has 0 remaining credits (HTTP 402) |
+| `AgentBillError` | Network error or unexpected server response |
+
+---
+
+## Self-hosting
+
+```bash
+git clone https://github.com/marketinglior-pixel/agentbill
+cd agentbill
+cp .env.example .env   # add your DATABASE_URL and AGENTBILL_API_KEY
+npm install
+npm run dev
+```
+
+Requires: Node 20+, PostgreSQL 14+
+
+---
+
+## Roadmap
+
+- [x] Core metering (`POST /events`)
+- [x] Credit balance enforcement (HTTP 402)
+- [x] Pre-flight guardrails (`preflight=True`)
+- [x] Outcome-based billing (`units=lambda`)
+- [x] Live dashboard
+- [ ] Stripe Connect — bill your customers directly
+- [ ] Webhooks — alerts at 80% and 100% credit usage
+- [ ] Multi-signal outcome support
+- [ ] Team accounts
+
+---
+
+## Why not Stripe directly?
+
+Stripe's metered billing requires: a product, a price, a customer, a subscription, a subscription item, and then a usage record per event. That's 6 API calls and 47 pages of documentation to charge someone $2.
+
+Stripe also has no concept of "did the task succeed?" or "stop before it starts."
+
+AgentBill handles all of that behind a single decorator.
+
+---
+
+Built for developers who ship agents and want to get paid fairly for what they actually deliver.

agentbill_sdk-0.1.0/README.md

@@ -0,0 +1,306 @@
+# AgentBill
+
+**Usage-based billing for AI agents. 3-line integration.**
+
+Stop charging flat monthly fees for agents whose costs swing between $2 and $40 per run.  
+Stop losing money when a rogue agent loops for 45 minutes at your expense.
+
+---
+
+## The problem
+
+You built an AI agent. It does something valuable. You charge $99/month flat.
+
+- A 3-second run costs you $0.80. You made $98.20.
+- A 45-minute recursive loop costs you $140. You lost $41.
+
+And you don't find out until your OpenAI invoice arrives.
+
+## The fix: 3 lines
+
+```python
+from agentbill import meter
+
+@meter(event="research_run", customer_id_from="customer_id", preflight=True)
+async def run_agent(customer_id: str, topic: str) -> str:
+    result = await call_your_llm(topic)
+    return result
+```
+
+That's it. AgentBill now:
+- Checks the customer's credit balance **before** the LLM call (`preflight=True`)
+- Records the credit usage **after** the function succeeds
+- Blocks the call with `BudgetExhaustedError` the moment the customer runs out — no surprise overages
+
+---
+
+## Install
+
+```bash
+pip install agentbill
+```
+
+```bash
+npm install agentbill
+```
+
+---
+
+## Quick start (5 minutes)
+
+### 1. Get an API key
+
+```
+AGENTBILL_API_KEY=your_key_here
+```
+
+### 2. Decorate your agent
+
+```python
+from agentbill import meter, BudgetExhaustedError
+
+# Charge 1 credit per run
+@meter(event="research_run", customer_id_from="customer_id")
+async def run_agent(customer_id: str, topic: str) -> str:
+    ...
+
+# Pre-flight: block BEFORE the LLM call if the customer is out of credits
+@meter(event="research_run", customer_id_from="customer_id", preflight=True)
+async def run_agent_safe(customer_id: str, topic: str) -> str:
+    ...
+
+# Outcome-based: charge credits only if the task succeeded
+@meter(
+    event="ticket_resolved",
+    customer_id_from="customer_id",
+    units=lambda result: 5 if result["resolved"] else 0,
+)
+async def resolve_ticket(customer_id: str, ticket_id: str) -> dict:
+    ...
+```
+
+### 3. Handle credit exhaustion
+
+```python
+try:
+    result = await run_agent(customer_id="cust_123", topic="quarterly report")
+except BudgetExhaustedError as e:
+    # Show paywall, send upgrade email, pause the agent — your call
+    show_paywall(e.customer_id)
+```
+
+### 4. Watch your dashboard
+
+Open `https://your-instance/dashboard` to see every customer's credit usage in real time:
+
+- Credit usage bar (turns red at 80%)
+- Remaining credits
+- BLOCKED badge when limit is hit
+
+---
+
+## Node.js
+
+```typescript
+import { meter, BudgetExhaustedError } from 'agentbill'
+
+const runAgent = meter(
+  async ({ customerId, topic }: { customerId: string; topic: string }) => {
+    const result = await callLLM(topic)
+    return result
+  },
+  {
+    event: 'research_run',
+    customerIdFrom: 'customerId',
+    preflight: true,
+  }
+)
+
+try {
+  await runAgent({ customerId: 'cust_123', topic: 'quarterly report' })
+} catch (e) {
+  if (e instanceof BudgetExhaustedError) {
+    showPaywall(e.customerId)
+  }
+}
+```
+
+---
+
+## Pricing for outcomes, not tokens
+
+Most billing tools count *events*. They have no concept of "did the task actually succeed?"
+
+AgentBill does. The credit count is a function of the result — you decide what success means:
+
+```python
+# Support agent — charge credits only when the ticket is resolved
+@meter(
+    event="ticket_resolved",
+    customer_id_from="customer_id",
+    units=lambda result: 5 if result["resolved"] else 0,
+)
+async def resolve_ticket(customer_id: str, ticket_id: str) -> dict:
+    resolution = await run_support_agent(ticket_id)
+    return resolution  # {"resolved": True, "summary": "..."}
+```
+
+```python
+# Coding agent — charge credits only when tests pass
+@meter(
+    event="code_generated",
+    customer_id_from="customer_id",
+    units=lambda result: 10 if result["tests_passed"] else 0,
+)
+async def generate_code(customer_id: str, spec: str) -> dict:
+    code = await run_coding_agent(spec)
+    passed = run_tests(code)
+    return {"code": code, "tests_passed": passed}
+```
+
+```python
+# Research agent — charge by volume processed
+@meter(
+    event="research_completed",
+    customer_id_from="customer_id",
+    units=lambda result: result["pages_processed"],
+)
+async def research(customer_id: str, topic: str) -> dict:
+    return await run_research_agent(topic)
+    # returns {"summary": "...", "pages_processed": 14}
+```
+
+If credits resolve to `0` — no event is recorded. The customer is not charged. Your margins stay intact.
+
+---
+
+## Why AgentBill? (vs. Metronome / Orb / Stripe)
+
+**Metronome and Orb** are excellent for SaaS products. They're built around usage records, pricing tiers, and invoicing. If you're building a database or an API with predictable units — use them.
+
+AgentBill is different in two ways:
+
+### 1. Pre-flight enforcement
+
+Metronome and Orb record usage *after the fact*. They have no way to stop an expensive operation before it starts.
+
+AgentBill checks the customer's credit balance **before** the LLM call runs. If they're out — the function never executes. No API call is made. No money is spent.
+
+```
+Metronome/Orb:   run → bill → (oops, over budget)
+AgentBill:       check → [blocked if over budget] → run → bill
+```
+
+This matters when a single agent run costs $0.80 on a good day and $43 on a bad one.
+
+### 2. Lives inside your function
+
+Metronome requires you to emit events from your infrastructure. AgentBill is a decorator — it wraps your function directly and handles everything: pre-flight check, credit deduction, idempotency, error handling.
+
+No event pipelines. No webhooks to configure. One line.
+
+---
+
+## Current scope — what AgentBill solves today
+
+AgentBill is designed for **atomic, short-running agent tasks** — functions that complete in a single execution and return a deterministic result.
+
+**Works well for:**
+- Research runs, report generation, document processing
+- Support ticket resolution (single attempt)
+- Code generation with test validation
+- Any agent function that runs once and returns a clear result
+
+**Not yet supported:**
+- **Multi-signal outcomes** — tasks where success is determined by multiple events over time (e.g., a ticket that gets reopened 3 days later)
+- **Long-running workflows** — agents that run for hours or days across multiple steps
+- **Outcome invalidation** — billing reversal when a previously "successful" result is later undone
+
+These are real problems. They require a different architecture — event sourcing, state machines, reversal logic. If you're building at that level of complexity, AgentBill's current version isn't the right tool yet.
+
+For atomic tasks — it's 3 lines.
+
+---
+
+## How it works
+
+```
+Your agent code
+     │
+     ▼
+@meter decorator
+     │
+     ├─ [preflight=true] GET /budget → is_blocked? → raise BudgetExhaustedError
+     │
+     ├─ Run your function (LLM call happens here)
+     │
+     ├─ [function succeeded] POST /events → record credits used
+     │
+     └─ Return result
+```
+
+Credits are recorded **after success only**. If your agent throws, the customer is not charged.
+
+---
+
+## API reference
+
+### `@meter(event, options)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `event` | `str` | required | Event label, shown in dashboard |
+| `customer_id` | `str` | — | Fixed customer identifier |
+| `customer_id_from` | `str` | — | Name of a function parameter to read customer_id from |
+| `units` | `int \| callable` | `1` | Credits per call, or a function `(result) -> int` returning 0 to skip billing |
+| `preflight` | `bool` | `False` | Check credit balance before running. Blocks immediately if exhausted. |
+| `metadata` | `dict` | — | Static key-value pairs attached to every event |
+
+### Exceptions
+
+| Exception | When |
+|---|---|
+| `BudgetExhaustedError` | Customer has 0 remaining credits (HTTP 402) |
+| `AgentBillError` | Network error or unexpected server response |
+
+---
+
+## Self-hosting
+
+```bash
+git clone https://github.com/marketinglior-pixel/agentbill
+cd agentbill
+cp .env.example .env   # add your DATABASE_URL and AGENTBILL_API_KEY
+npm install
+npm run dev
+```
+
+Requires: Node 20+, PostgreSQL 14+
+
+---
+
+## Roadmap
+
+- [x] Core metering (`POST /events`)
+- [x] Credit balance enforcement (HTTP 402)
+- [x] Pre-flight guardrails (`preflight=True`)
+- [x] Outcome-based billing (`units=lambda`)
+- [x] Live dashboard
+- [ ] Stripe Connect — bill your customers directly
+- [ ] Webhooks — alerts at 80% and 100% credit usage
+- [ ] Multi-signal outcome support
+- [ ] Team accounts
+
+---
+
+## Why not Stripe directly?
+
+Stripe's metered billing requires: a product, a price, a customer, a subscription, a subscription item, and then a usage record per event. That's 6 API calls and 47 pages of documentation to charge someone $2.
+
+Stripe also has no concept of "did the task succeed?" or "stop before it starts."
+
+AgentBill handles all of that behind a single decorator.
+
+---
+
+Built for developers who ship agents and want to get paid fairly for what they actually deliver.

agentbill_sdk-0.1.0/agentbill/__init__.py

@@ -0,0 +1,3 @@
+from .meter import meter, BudgetExhaustedError, AgentBillError
+
+__all__ = ["meter", "BudgetExhaustedError", "AgentBillError"]

agentbill_sdk-0.1.0/agentbill/meter.py

@@ -0,0 +1,277 @@
+"""agentbill.meter
+~~~~~~~~~~~~~~~
+
+A decorator that records billable agent events.
+
+    from agentbill import meter
+
+    @meter(event="research_run", customer_id_from="customer_id")
+    async def run_agent(customer_id: str, topic: str) -> str:
+        ...
+
+Environment variables
+---------------------
+AGENTBILL_API_KEY     Required. Your API key from agentbill.dev/dashboard.
+AGENTBILL_BASE_URL    Optional. Defaults to https://api.agentbill.dev/v1
+AGENTBILL_CUSTOMER_ID Optional. Fallback customer_id when not passed per-call.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import os
+import uuid
+from typing import Any, Callable, Optional, TypeVar, Union
+
+import httpx
+
+F = TypeVar("F", bound=Callable[..., Any])
+UnitsResolver = Union[int, Callable[[Any], int]]
+
+_BASE_URL = os.environ.get("AGENTBILL_BASE_URL", "https://api.agentbill.dev/v1")
+
+
+# ---------------------------------------------------------------------------
+# Public exceptions — import and handle these in your agent code
+# ---------------------------------------------------------------------------
+
+class BudgetExhaustedError(Exception):
+    """The customer has 0 remaining units (HTTP 402).
+
+    Catch this to show the user a paywall or pause the agent gracefully.
+
+        try:
+            result = await run_agent(customer_id="cust_123", topic="...")
+        except BudgetExhaustedError as e:
+            print(f"Customer {e.customer_id} is out of budget.")
+    """
+    def __init__(self, customer_id: str, message: str = "") -> None:
+        self.customer_id = customer_id
+        super().__init__(message or f"Customer {customer_id!r} has no remaining budget.")
+
+
+class AgentBillError(Exception):
+    """Unexpected AgentBill error (network failure, 5xx response).
+
+    By default the decorator raises this so your agent doesn't bill
+    silently on server errors. Override this by wrapping the call.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _api_key() -> str:
+    key = os.environ.get("AGENTBILL_API_KEY", "")
+    if not key:
+        raise AgentBillError(
+            "AGENTBILL_API_KEY is not set. "
+            "Get your key at agentbill.dev/dashboard."
+        )
+    return key
+
+
+def _resolve_customer_id(
+    customer_id: str | None,
+    customer_id_from: str | None,
+    func: Callable,
+    args: tuple,
+    kwargs: dict,
+) -> str:
+    # Priority: explicit kwarg > function param > env var
+    if customer_id is not None:
+        return customer_id
+
+    if customer_id_from is not None:
+        sig = inspect.signature(func)
+        bound = sig.bind(*args, **kwargs)
+        bound.apply_defaults()
+        value = bound.arguments.get(customer_id_from)
+        if value is None:
+            raise AgentBillError(
+                f"customer_id_from={customer_id_from!r} was not found in "
+                f"the arguments of {func.__name__}(). "
+                f"Available: {list(bound.arguments)}"
+            )
+        return str(value)
+
+    env_id = os.environ.get("AGENTBILL_CUSTOMER_ID", "")
+    if env_id:
+        return env_id
+
+    raise AgentBillError(
+        "No customer_id resolved. Use one of:\n"
+        "  @meter(event=..., customer_id='fixed_id')\n"
+        "  @meter(event=..., customer_id_from='param_name')\n"
+        "  export AGENTBILL_CUSTOMER_ID=..."
+    )
+
+
+def _build_payload(customer_id: str, event: str, units: int, metadata: dict | None) -> dict:
+    payload: dict = {
+        "customer_id": customer_id,
+        "event_type": event,
+        "units": units,
+        # Auto-generated — unique per invocation, safe for retries
+        "idempotency_key": f"{event}_{uuid.uuid4().hex}",
+    }
+    if metadata:
+        payload["metadata"] = metadata
+    return payload
+
+
+def _handle_response(resp: httpx.Response, customer_id: str) -> None:
+    if resp.status_code == 200:
+        return
+    if resp.status_code == 402:
+        data = resp.json()
+        raise BudgetExhaustedError(customer_id, data.get("message", ""))
+    raise AgentBillError(
+        f"AgentBill returned unexpected status {resp.status_code}: {resp.text[:200]}"
+    )
+
+
+def _resolve_units(units: UnitsResolver, result: Any) -> int:
+    if callable(units):
+        resolved = units(result)
+        if not isinstance(resolved, int) or resolved < 0:
+            raise AgentBillError(
+                f"units callable must return a non-negative int, got {resolved!r}"
+            )
+        return resolved
+    return units
+
+
+def _preflight_sync(customer_id: str) -> None:
+    """Raise BudgetExhaustedError before the agent runs if the customer is blocked."""
+    with httpx.Client() as client:
+        resp = client.get(
+            f"{_BASE_URL}/budget",
+            params={"customer_id": customer_id},
+            headers={"Authorization": f"Bearer {_api_key()}"},
+            timeout=5.0,
+        )
+    if resp.status_code != 200:
+        raise AgentBillError(f"AgentBill /budget returned {resp.status_code}: {resp.text[:200]}")
+    data = resp.json()
+    if data.get("is_blocked"):
+        raise BudgetExhaustedError(customer_id)
+
+
+async def _preflight_async(customer_id: str) -> None:
+    """Async version of _preflight_sync."""
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            f"{_BASE_URL}/budget",
+            params={"customer_id": customer_id},
+            headers={"Authorization": f"Bearer {_api_key()}"},
+            timeout=5.0,
+        )
+    if resp.status_code != 200:
+        raise AgentBillError(f"AgentBill /budget returned {resp.status_code}: {resp.text[:200]}")
+    data = resp.json()
+    if data.get("is_blocked"):
+        raise BudgetExhaustedError(customer_id)
+
+
+def _submit_sync(customer_id: str, event: str, units: int, metadata: dict | None) -> None:
+    with httpx.Client() as client:
+        resp = client.post(
+            f"{_BASE_URL}/events",
+            json=_build_payload(customer_id, event, units, metadata),
+            headers={"Authorization": f"Bearer {_api_key()}"},
+            timeout=5.0,
+        )
+    _handle_response(resp, customer_id)
+
+
+async def _submit_async(customer_id: str, event: str, units: int, metadata: dict | None) -> None:
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            f"{_BASE_URL}/events",
+            json=_build_payload(customer_id, event, units, metadata),
+            headers={"Authorization": f"Bearer {_api_key()}"},
+            timeout=5.0,
+        )
+    _handle_response(resp, customer_id)
+
+
+# ---------------------------------------------------------------------------
+# Public decorator
+# ---------------------------------------------------------------------------
+
+def meter(
+    event: str,
+    *,
+    units: UnitsResolver = 1,
+    customer_id: str | None = None,
+    customer_id_from: str | None = None,
+    metadata: dict | None = None,
+    preflight: bool = False,
+) -> Callable[[F], F]:
+    """Decorator that records a billable event after the wrapped function returns.
+
+    The event is submitted AFTER the function succeeds. If the function raises,
+    no event is recorded and your customer is not billed.
+
+    Args:
+        event:            Event type label (snake_case). Shown in dashboard and Stripe.
+        units:            Billable units per call. Default 1.
+        customer_id:      Fixed customer identifier.
+        customer_id_from: Name of a function parameter to read customer_id from.
+        metadata:         Static key-value pairs attached to every event (not billed).
+        preflight:        If True, check budget BEFORE running the function. Raises
+                          BudgetExhaustedError immediately if the customer is blocked,
+                          preventing any expensive LLM calls from being made.
+
+    Raises:
+        BudgetExhaustedError: Customer has 0 remaining units (HTTP 402).
+        AgentBillError:       Network error or unexpected server response.
+
+    Examples::
+
+        # Async agent — reads customer_id from function param
+        @meter(event="research_run", customer_id_from="customer_id")
+        async def run_agent(customer_id: str, topic: str) -> str:
+            ...
+
+        # Sync function — fixed customer
+        @meter(event="report_generated", customer_id="internal_ops", units=1)
+        def generate_report(date: str) -> bytes:
+            ...
+
+        # Batch: bill by volume (e.g. pages processed)
+        @meter(event="pages_processed", customer_id_from="customer_id", units=10)
+        async def process_document(customer_id: str, path: str) -> list:
+            ...
+    """
+    def decorator(func: F) -> F:
+        if asyncio.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                cid = _resolve_customer_id(customer_id, customer_id_from, func, args, kwargs)
+                if preflight:
+                    await _preflight_async(cid)
+                result = await func(*args, **kwargs)
+                actual_units = _resolve_units(units, result)
+                if actual_units > 0:
+                    await _submit_async(cid, event, actual_units, metadata)
+                return result
+            return async_wrapper  # type: ignore[return-value]
+        else:
+            @functools.wraps(func)
+            def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                cid = _resolve_customer_id(customer_id, customer_id_from, func, args, kwargs)
+                if preflight:
+                    _preflight_sync(cid)
+                result = func(*args, **kwargs)
+                actual_units = _resolve_units(units, result)
+                if actual_units > 0:
+                    _submit_sync(cid, event, actual_units, metadata)
+                return result
+            return sync_wrapper  # type: ignore[return-value]
+
+    return decorator  # type: ignore[return-value]

agentbill_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentbill-sdk"
+version = "0.1.0"
+description = "Usage-based billing for AI agent developers. 3-line integration."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.27"]
+authors = [
+  { name = "AgentBill", email = "marketinglior@gmail.com" }
+]
+keywords = ["ai", "agents", "billing", "metering", "llm", "usage-based"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/marketinglior-pixel/agentbill"
+Repository = "https://github.com/marketinglior-pixel/agentbill"
+Documentation = "https://github.com/marketinglior-pixel/agentbill#readme"
+
+[tool.hatch.build.targets.wheel]
+packages = ["agentbill"]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio", "respx"]

agentbill_sdk-0.1.0/test_preflight.py

@@ -0,0 +1,37 @@
+"""
+Pre-flight budget check test.
+Run: python3 test_preflight.py
+Server must be running: npm run dev (in agentbill folder)
+"""
+import sys, os
+sys.path.insert(0, '.')
+
+os.environ['AGENTBILL_API_KEY'] = 'test_key'
+os.environ['AGENTBILL_BASE_URL'] = 'http://localhost:3000'
+
+from agentbill.meter import meter, BudgetExhaustedError
+
+call_count = 0
+
+# limit_test is already BLOCKED (used=3, limit=3)
+@meter(event="preflight_test", customer_id="limit_test", units=1, preflight=True)
+def expensive_agent(task: str) -> str:
+    global call_count
+    call_count += 1
+    print(f"  → Agent body ran (#{call_count}) — this costs money!")
+    return f"result: {task}"
+
+
+print("=" * 50)
+print("Pre-flight budget check test")
+print("Customer: limit_test (blocked, used=3/3)")
+print("=" * 50)
+
+try:
+    expensive_agent("analyze this document")
+    print("\nFAIL: should have been blocked before running!")
+except BudgetExhaustedError as e:
+    print(f"\n✅  BudgetExhaustedError caught BEFORE agent ran")
+    print(f"    Message: {e}")
+    print(f"    Agent body executions: {call_count}  (expected: 0)")
+    print(f"\n→  The LLM call was never made. No money wasted.")