agentcogs 0.1.1__tar.gz

agentcogs-0.1.1/.gitignore

@@ -0,0 +1,51 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+!**/.env.example
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.db
+node_modules/
+dashboard/dist/
+backend/.venv/
+
+# Local-only planning (do not push to GitHub)
+TECH_ROADMAP.local.md
+*.local.md
+tools/.demo_env
+
+# Maintainer / GTM — keep on disk, not in public repo
+docs/internal/
+docs/launch/
+docs/DISTRIBUTION_PLAYBOOK.md
+docs/GTM_FOUNDER_DIRECT.md
+docs/CREDIBILITY_PLAYBOOK.md
+docs/CUSTOMER_JOURNEY_STATUS.md
+docs/SLACK_ALERTS_TECHNICAL_PLAN.md
+docs/SDK_CUSTOMER_JOURNEY_PLAN.md
+docs/DEMO_CALL_SCRIPT.md
+.run/
+
+# Playwright / local auth state (when added)
+playwright/.auth/
+playwright-report/
+test-results/
+
+# OS / IDE
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Cursor IDE (local agent skills, rules — not part of the product)
+.cursor/

agentcogs-0.1.1/LICENSE

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

agentcogs-0.1.1/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: agentcogs
+Version: 0.1.1
+Summary: Per-customer LLM cost attribution and runtime budget caps for agent SaaS
+Project-URL: Homepage, https://agentcogs.dev
+Project-URL: Repository, https://github.com/vaibhav11123/agentcogs
+Project-URL: Issues, https://github.com/vaibhav11123/agentcogs/issues
+Author-email: AgentCOGS <hello@agentcogs.dev>
+License: MIT
+License-File: LICENSE
+Keywords: anthropic,attribution,billing,cost,langchain,langgraph,llm,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: shekel[anthropic,openai]<2,>=1.2
+Requires-Dist: starlette>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: starlette>=0.27.0; extra == 'dev'
+Provides-Extra: integrations
+Requires-Dist: starlette>=0.27.0; extra == 'integrations'
+Description-Content-Type: text/markdown
+
+# AgentCOGS
+
+**Which customer stops making money this month.**
+
+You sell an agent to other companies. The model provider sends one invoice. AgentCOGS splits that spend by the tenant who caused it, sets it against the monthly fee, and shows where the month is headed if the calls keep coming.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![CI](https://github.com/vaibhav11123/agentcogs/actions/workflows/ci.yml/badge.svg)](https://github.com/vaibhav11123/agentcogs/actions/workflows/ci.yml)
+
+The sample company is [Patternstack](https://agentcogs.vercel.app). One click, nothing to type. It is a snapshot of a fictional book of business, shipped in the dashboard, so it opens when no API is running. A hosted AgentCOGS API is not serving. To run your own customers, self-host.
+
+---
+
+## The book, and the account inside it
+
+Patternstack, as of 14 Nov 2026. Forty customers. The month so far looks healthy.
+
+| | So far | If the calls continue |
+| --- | ---: | ---: |
+| AI cost | $39,613.25 | $84,885.54 |
+| Fees | $155,918.00 | $155,918.00 |
+| Margin | 74.6% | 45.6% |
+
+The fee is the monthly amount on the account. Pace is a straight line from the cost so far. It does not forecast a change in behavior.
+
+Two accounts are where the month breaks. Vellum Research has cost $5,822.84 against an $8,200 fee: **29.0%** so far, 2,724 runs, and the largest node is `synthesize`. If that spend continues, the month ends near **−52.2%**. Pinnacle Claims is 35.0% so far and ends near −39.3%. The blended 74.6% does not show either of those.
+
+<p align="center">
+  <img src="docs/assets/screenshots/patternstack-customers.png" alt="Patternstack customers. Blended margin 74.6%. Vellum Research is 29.0% and the month ends near −52.2%." width="880" />
+</p>
+
+Open the account and the same numbers sit next to the call that posted them.
+
+<p align="center">
+  <img src="docs/assets/screenshots/vellum-research.png" alt="Vellum Research. Margin 29.0%, AI cost $5,822.84, fee $8,200, and the set_customer call that posts each run." width="880" />
+</p>
+
+```python
+import agentcogs
+
+agentcogs.init()  # AGENTCOGS_API_KEY, AGENTCOGS_WORKSPACE_ID, AGENTCOGS_ENDPOINT
+agentcogs.set_customer("vellum_research")  # your tenant id, once per request
+
+with agentcogs.run(workflow_id="research_agent"):
+    result = agent.invoke(state)
+```
+
+The SDK does not call a model and does not invent the fee. It names the customer and posts the cost of the call you already made. You type the fee, or you pull the subscription from that customer's Stripe account. If no customer is set, the run stays unattributed.
+
+`python examples/one_run.py` posts one recorded $0.84 cost for Vellum Research so you can see a row land. It does not call a model.
+
+---
+
+## Look, then run it on yours
+
+**Look.** [agentcogs.vercel.app](https://agentcogs.vercel.app) → **Open Patternstack**.
+
+**Run.** From this repo:
+
+```bash
+cp .env.selfhost.example .env
+docker compose up -d --build
+```
+
+Open http://localhost:3000 and choose **Create my workspace**. No email. The next screen has the install command with your key in it. The package is not on PyPI yet:
+
+```bash
+pip install "agentcogs @ git+https://github.com/vaibhav11123/agentcogs.git"
+```
+
+Point `AGENTCOGS_ENDPOINT` at `http://localhost:8000`. Send one call, open that customer, and type the monthly fee. Margin is the fee minus the cost.
+
+Full steps: [docs/quickstart.md](docs/quickstart.md). Self-host notes: [docs/DEPLOY.md](docs/DEPLOY.md).
+
+---
+
+## Who it is for
+
+A founder of a product that sells one agent to many companies, priced as a monthly fee, with the model bill arriving as a single invoice. Support, research, claims, intake, document pipelines.
+
+| You already have | AgentCOGS adds |
+| --- | --- |
+| Langfuse or LangSmith | Which tenant the trace belonged to, and whether that tenant is still profitable |
+| LiteLLM | A callback that posts the tenant and the cost. The proxy stays |
+| Stripe | The subscription as the fee, and an optional meter for the usage you already attributed |
+| The provider invoice | The join from that one number to the customer list |
+
+---
+
+## What you can connect
+
+| | |
+| --- | --- |
+| [FastAPI](docs/integrations/fastapi.md) | Set the tenant from the request |
+| [LangGraph](docs/integrations/langgraph.md) | Wrap the graph |
+| [LiteLLM](docs/integrations/litellm.md) | Post proxy traffic without wrapping the app |
+| [Customer import](docs/integrations/customer-import.md) | Load names and fees before the first run |
+| [Slack](docs/integrations/slack.md) | A spike opens that customer |
+| Stripe | Pull subscription fees. Push a daily usage meter |
+| Budget | `monthly_budget_usd` raises `CustomerBudgetExceededError` before the next call |
+
+Terminal proof for the SDK, the outbox, and a live call: [docs/demo-paths.md](docs/demo-paths.md).
+
+---
+
+## Repo
+
+| Path | |
+| --- | --- |
+| `src/agentcogs/` | The SDK |
+| `backend/` | Ingest, margin, pace, budgets |
+| `dashboard/` | The book |
+| `examples/one_run.py` | One recorded cost, no model call |
+| `docs/` | [Index](docs/README.md) |
+
+Python SDK, FastAPI, Postgres, Redis, React. [MIT](LICENSE). [Contributing](CONTRIBUTING.md). [Security](SECURITY.md).

agentcogs-0.1.1/README.md

@@ -0,0 +1,117 @@
+# AgentCOGS
+
+**Which customer stops making money this month.**
+
+You sell an agent to other companies. The model provider sends one invoice. AgentCOGS splits that spend by the tenant who caused it, sets it against the monthly fee, and shows where the month is headed if the calls keep coming.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![CI](https://github.com/vaibhav11123/agentcogs/actions/workflows/ci.yml/badge.svg)](https://github.com/vaibhav11123/agentcogs/actions/workflows/ci.yml)
+
+The sample company is [Patternstack](https://agentcogs.vercel.app). One click, nothing to type. It is a snapshot of a fictional book of business, shipped in the dashboard, so it opens when no API is running. A hosted AgentCOGS API is not serving. To run your own customers, self-host.
+
+---
+
+## The book, and the account inside it
+
+Patternstack, as of 14 Nov 2026. Forty customers. The month so far looks healthy.
+
+| | So far | If the calls continue |
+| --- | ---: | ---: |
+| AI cost | $39,613.25 | $84,885.54 |
+| Fees | $155,918.00 | $155,918.00 |
+| Margin | 74.6% | 45.6% |
+
+The fee is the monthly amount on the account. Pace is a straight line from the cost so far. It does not forecast a change in behavior.
+
+Two accounts are where the month breaks. Vellum Research has cost $5,822.84 against an $8,200 fee: **29.0%** so far, 2,724 runs, and the largest node is `synthesize`. If that spend continues, the month ends near **−52.2%**. Pinnacle Claims is 35.0% so far and ends near −39.3%. The blended 74.6% does not show either of those.
+
+<p align="center">
+  <img src="docs/assets/screenshots/patternstack-customers.png" alt="Patternstack customers. Blended margin 74.6%. Vellum Research is 29.0% and the month ends near −52.2%." width="880" />
+</p>
+
+Open the account and the same numbers sit next to the call that posted them.
+
+<p align="center">
+  <img src="docs/assets/screenshots/vellum-research.png" alt="Vellum Research. Margin 29.0%, AI cost $5,822.84, fee $8,200, and the set_customer call that posts each run." width="880" />
+</p>
+
+```python
+import agentcogs
+
+agentcogs.init()  # AGENTCOGS_API_KEY, AGENTCOGS_WORKSPACE_ID, AGENTCOGS_ENDPOINT
+agentcogs.set_customer("vellum_research")  # your tenant id, once per request
+
+with agentcogs.run(workflow_id="research_agent"):
+    result = agent.invoke(state)
+```
+
+The SDK does not call a model and does not invent the fee. It names the customer and posts the cost of the call you already made. You type the fee, or you pull the subscription from that customer's Stripe account. If no customer is set, the run stays unattributed.
+
+`python examples/one_run.py` posts one recorded $0.84 cost for Vellum Research so you can see a row land. It does not call a model.
+
+---
+
+## Look, then run it on yours
+
+**Look.** [agentcogs.vercel.app](https://agentcogs.vercel.app) → **Open Patternstack**.
+
+**Run.** From this repo:
+
+```bash
+cp .env.selfhost.example .env
+docker compose up -d --build
+```
+
+Open http://localhost:3000 and choose **Create my workspace**. No email. The next screen has the install command with your key in it. The package is not on PyPI yet:
+
+```bash
+pip install "agentcogs @ git+https://github.com/vaibhav11123/agentcogs.git"
+```
+
+Point `AGENTCOGS_ENDPOINT` at `http://localhost:8000`. Send one call, open that customer, and type the monthly fee. Margin is the fee minus the cost.
+
+Full steps: [docs/quickstart.md](docs/quickstart.md). Self-host notes: [docs/DEPLOY.md](docs/DEPLOY.md).
+
+---
+
+## Who it is for
+
+A founder of a product that sells one agent to many companies, priced as a monthly fee, with the model bill arriving as a single invoice. Support, research, claims, intake, document pipelines.
+
+| You already have | AgentCOGS adds |
+| --- | --- |
+| Langfuse or LangSmith | Which tenant the trace belonged to, and whether that tenant is still profitable |
+| LiteLLM | A callback that posts the tenant and the cost. The proxy stays |
+| Stripe | The subscription as the fee, and an optional meter for the usage you already attributed |
+| The provider invoice | The join from that one number to the customer list |
+
+---
+
+## What you can connect
+
+| | |
+| --- | --- |
+| [FastAPI](docs/integrations/fastapi.md) | Set the tenant from the request |
+| [LangGraph](docs/integrations/langgraph.md) | Wrap the graph |
+| [LiteLLM](docs/integrations/litellm.md) | Post proxy traffic without wrapping the app |
+| [Customer import](docs/integrations/customer-import.md) | Load names and fees before the first run |
+| [Slack](docs/integrations/slack.md) | A spike opens that customer |
+| Stripe | Pull subscription fees. Push a daily usage meter |
+| Budget | `monthly_budget_usd` raises `CustomerBudgetExceededError` before the next call |
+
+Terminal proof for the SDK, the outbox, and a live call: [docs/demo-paths.md](docs/demo-paths.md).
+
+---
+
+## Repo
+
+| Path | |
+| --- | --- |
+| `src/agentcogs/` | The SDK |
+| `backend/` | Ingest, margin, pace, budgets |
+| `dashboard/` | The book |
+| `examples/one_run.py` | One recorded cost, no model call |
+| `docs/` | [Index](docs/README.md) |
+
+Python SDK, FastAPI, Postgres, Redis, React. [MIT](LICENSE). [Contributing](CONTRIBUTING.md). [Security](SECURITY.md).

agentcogs-0.1.1/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentcogs"
+dynamic = ["version"]
+description = "Per-customer LLM cost attribution and runtime budget caps for agent SaaS"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "AgentCOGS", email = "hello@agentcogs.dev" }]
+keywords = ["llm", "cost", "attribution", "langgraph", "langchain", "openai", "anthropic", "billing"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "shekel[openai,anthropic]>=1.2,<2",
+    "httpx>=0.27.0",
+    "starlette>=0.27.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "respx>=0.20", "ruff>=0.6", "starlette>=0.27.0"]
+integrations = ["starlette>=0.27.0"]
+
+[project.urls]
+Homepage = "https://agentcogs.dev"
+Repository = "https://github.com/vaibhav11123/agentcogs"
+Issues = "https://github.com/vaibhav11123/agentcogs/issues"
+
+[tool.hatch.version]
+path = "src/agentcogs/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentcogs"]
+
+# pip install prefers the wheel. The sdist is the fallback and must stay the
+# SDK. The backend, dashboard, and demo tools are the rest of this repo.
+[tool.hatch.build.targets.sdist]
+only-include = ["src/agentcogs", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

agentcogs-0.1.1/src/agentcogs/__init__.py

@@ -0,0 +1,43 @@
+"""AgentCOGS — per-customer LLM cost attribution.
+
+Quickstart:
+    import agentcogs
+    agentcogs.init(api_key="acg_live_...", workspace_id="...")
+
+    agentcogs.set_customer("tenant_42")  # once per request
+    with agentcogs.run(workflow_id="summarize"):
+        # any openai / anthropic / langgraph code here
+        ...
+"""
+from ._version import __version__
+from .budget import IngestStatus, RunContext, run
+from .config import init
+from .context import get_customer, get_workflow, set_customer, set_workflow
+from .errors import (
+    AgentCOGSError,
+    ConfigurationError,
+    CustomerBudgetExceededError,
+    PingError,
+)
+from .ping import PingResult, ping
+from .shutdown import ShutdownResult, shutdown
+
+__all__ = [
+    "__version__",
+    "init",
+    "run",
+    "ping",
+    "shutdown",
+    "set_customer",
+    "set_workflow",
+    "get_customer",
+    "get_workflow",
+    "RunContext",
+    "IngestStatus",
+    "PingResult",
+    "ShutdownResult",
+    "AgentCOGSError",
+    "CustomerBudgetExceededError",
+    "ConfigurationError",
+    "PingError",
+]

agentcogs-0.1.1/src/agentcogs/__main__.py

@@ -0,0 +1,17 @@
+"""CLI: python -m agentcogs outbox status"""
+import json
+import sys
+
+from .outbox import get_status
+
+
+def main() -> None:
+    if len(sys.argv) >= 3 and sys.argv[1] == "outbox" and sys.argv[2] == "status":
+        print(json.dumps(get_status(), indent=2))
+        return
+    print("Usage: python -m agentcogs outbox status", file=sys.stderr)
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

agentcogs-0.1.1/src/agentcogs/_shekel_compat.py

@@ -0,0 +1,48 @@
+"""Thin adapter over shekel 1.x — single place for version-specific field mapping."""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from shekel import budget as _shekel_budget
+
+
+def budget(**kwargs: Any):
+    """Return shekel budget context manager (signature-stable for agentcogs)."""
+    return _shekel_budget(**kwargs)
+
+
+def normalize_summary(by_model: Dict[str, Dict[str, Any]]) -> Dict[str, Dict[str, Any]]:
+    """Convert Shekel's by_model summary into a uniform schema.
+
+    Anthropic prompt caching splits input tokens across three fields; all must be summed.
+    """
+    out: Dict[str, Dict[str, Any]] = {}
+    for model, stats in by_model.items():
+        model_lower = model.lower()
+        if "claude" in model_lower or "anthropic" in model_lower:
+            input_total = (
+                int(stats.get("input_tokens", 0) or 0)
+                + int(stats.get("cache_read_input_tokens", 0) or 0)
+                + int(stats.get("cache_creation_input_tokens", 0) or 0)
+            )
+        else:
+            input_total = int(stats.get("input_tokens", 0) or 0)
+
+        out[model] = {
+            "input_tokens": input_total,
+            "output_tokens": int(stats.get("output_tokens", 0) or 0),
+            "usd": float(stats.get("cost", 0) or 0),
+        }
+    return out
+
+
+def normalize_summary_data(raw: dict) -> dict:
+    """Normalize summary_data() from a shekel budget context."""
+    total = raw.get("total_cost")
+    if total is None:
+        total = raw.get("total_spent", 0)
+    by_model = raw.get("by_model") or {}
+    return {
+        "total_cost": float(total or 0),
+        "by_model": by_model,
+    }

agentcogs-0.1.1/src/agentcogs/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

agentcogs-0.1.1/src/agentcogs/budget.py

@@ -0,0 +1,161 @@
+"""The agentcogs.run() context manager — the SDK's entire public surface."""
+import json
+import logging
+import time
+import uuid
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Dict, Iterator, Optional
+
+from ._shekel_compat import budget as shekel_budget, normalize_summary, normalize_summary_data
+from .client import emit_event, emit_event_sync, fetch_budget
+from .config import get_config
+from .context import resolve_customer, resolve_workflow
+from .errors import ConfigurationError, CustomerBudgetExceededError
+
+log = logging.getLogger("agentcogs")
+
+_MAX_METADATA_KEYS = 100
+_MAX_METADATA_BYTES = 16_384
+
+
+def _cap_metadata(metadata: Optional[dict]) -> dict:
+    if not metadata:
+        return {}
+    capped = dict(list(metadata.items())[:_MAX_METADATA_KEYS])
+    if len(capped) < len(metadata):
+        log.debug("metadata truncated to %d keys", _MAX_METADATA_KEYS)
+    while capped and len(json.dumps(capped, default=str)) > _MAX_METADATA_BYTES:
+        capped.pop(next(iter(capped)))
+    if len(capped) < len(metadata):
+        log.debug("metadata size capped to %d bytes", _MAX_METADATA_BYTES)
+    return capped
+
+
+@dataclass
+class IngestStatus:
+    accepted: bool
+    duplicate: bool = False
+    error: Optional[str] = None
+
+
+class RunContext:
+    """Handle returned from agentcogs.run()."""
+
+    def __init__(
+        self,
+        shekel_ctx: object,
+        run_id: str,
+        customer_id: str,
+        workflow_id: str,
+    ):
+        self._shekel = shekel_ctx
+        self.run_id = run_id
+        self.customer_id = customer_id
+        self.workflow_id = workflow_id
+        self._event: Optional[dict] = None
+
+    def summary_data(self) -> dict:
+        return self._shekel.summary_data()  # type: ignore[attr-defined]
+
+    def wait_for_ingest(self, timeout: float = 5.0) -> IngestStatus:
+        """Block until event is POSTed (onboarding/tests). Uses sync ingest."""
+        if self._event is None:
+            return IngestStatus(accepted=False, error="no event built yet")
+        ok, err = emit_event_sync(self._event)
+        return IngestStatus(accepted=ok, error=err)
+
+    def __getattr__(self, name: str):
+        return getattr(self._shekel, name)
+
+
+@contextmanager
+def run(
+    customer_id: Optional[str] = None,
+    workflow_id: Optional[str] = None,
+    workspace_id: Optional[str] = None,
+    metadata: Optional[dict] = None,
+    price_per_1k_tokens: Optional[Dict[str, float]] = None,
+) -> Iterator[RunContext]:
+    """Wrap any block of LLM-using code with per-customer cost tracking.
+
+    customer_id may be omitted if agentcogs.set_customer() was called for this context.
+    workflow_id defaults to set_workflow() context value, else "default".
+    """
+    cfg = get_config()
+    ws_id = workspace_id or cfg.workspace_id
+    if not ws_id and not cfg.offline:
+        raise ConfigurationError(
+            "workspace_id required: pass workspace_id= or set in init()"
+        )
+
+    resolved_customer = resolve_customer(customer_id)
+    if not resolved_customer:
+        raise ConfigurationError(
+            "customer_id required: pass customer_id= to run() or call "
+            "set_customer() in middleware before agent code. "
+            "See docs/concepts/customer-id.md"
+        )
+    resolved_workflow = resolve_workflow(workflow_id)
+
+    run_id = str(uuid.uuid4())
+
+    b = fetch_budget(ws_id or "offline", resolved_customer)
+    if b["status"] == "exceeded":
+        raise CustomerBudgetExceededError(
+            customer_id=resolved_customer,
+            spent_usd=b["spent_usd"],
+            budget_usd=b["budget_usd"],
+        )
+
+    remaining = b.get("remaining_usd")
+    max_usd = float(remaining) if remaining and remaining != float("inf") else None
+
+    status = "completed"
+    error_msg: Optional[str] = None
+
+    kwargs: dict = {"name": resolved_customer}
+    if max_usd is not None:
+        kwargs["max_usd"] = max_usd
+    if price_per_1k_tokens is not None:
+        kwargs["price_per_1k_tokens"] = price_per_1k_tokens
+
+    run_ctx: Optional[RunContext] = None
+
+    with shekel_budget(**kwargs) as ctx:
+        try:
+            run_ctx = RunContext(ctx, run_id, resolved_customer, resolved_workflow)
+            yield run_ctx
+        except CustomerBudgetExceededError:
+            status = "budget_exceeded"
+            raise
+        except Exception as e:
+            status = "error"
+            error_msg = str(e)[:500]
+            raise
+        finally:
+            try:
+                summary = normalize_summary_data(ctx.summary_data())
+                event = {
+                    "run_id": run_id,
+                    "customer_id": resolved_customer,
+                    "workflow_id": resolved_workflow,
+                    "ts": int(time.time()),
+                    "status": status,
+                    "total_usd": float(summary.get("total_cost") or 0),
+                    "models": normalize_summary(summary.get("by_model", {})),
+                    "node_costs": getattr(ctx, "node_costs", {}),
+                    "metadata": _cap_metadata(metadata),
+                    "error": error_msg,
+                }
+                if run_ctx is not None:
+                    run_ctx._event = event
+                emit_event(event)
+            except Exception as e:
+                log.warning("telemetry failed", exc_info=True)
+                cb = cfg.on_telemetry_error
+                if cb is not None:
+                    try:
+                        cb(e)
+                    except Exception:
+                        pass