agentcogs 0.1.1__py3-none-any.whl

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/__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/_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/_version.py

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

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

agentcogs/client.py

@@ -0,0 +1,145 @@
+"""HTTP client. Fire-and-forget POST to ingest endpoint.
+
+Never blocks user code. Failures route to outbox for retry.
+"""
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Dict, Optional, Tuple
+
+import httpx
+
+from ._version import __version__
+from .config import get_config
+from .errors import AgentCOGSError
+from .outbox import drain, enqueue
+
+log = logging.getLogger("agentcogs")
+
+_client: Optional[httpx.Client] = None
+_executor: Optional[ThreadPoolExecutor] = None
+
+
+def _user_agent() -> str:
+    return f"agentcogs-python/{__version__}"
+
+
+def _default_headers() -> Dict[str, str]:
+    return {
+        "Authorization": f"Bearer {get_config().api_key}",
+        "User-Agent": _user_agent(),
+        "Content-Type": "application/json",
+        "X-AgentCOGS-SDK-Version": __version__,
+    }
+
+
+def reset_client() -> None:
+    """Close httpx client (e.g. on re-init)."""
+    global _client
+    if _client is not None:
+        try:
+            _client.close()
+        except Exception:
+            pass
+        _client = None
+
+
+def _get_client() -> httpx.Client:
+    global _client
+    if _client is None:
+        cfg = get_config()
+        _client = httpx.Client(
+            base_url=cfg.endpoint,
+            headers=_default_headers(),
+            timeout=cfg.timeout_seconds,
+        )
+    return _client
+
+
+def _get_executor() -> ThreadPoolExecutor:
+    global _executor
+    if _executor is None:
+        cfg = get_config()
+        _executor = ThreadPoolExecutor(
+            max_workers=cfg.max_ingest_workers,
+            thread_name_prefix="agentcogs-ingest",
+        )
+    return _executor
+
+
+def shutdown_executor(wait: bool = True, timeout: float = 10.0) -> None:
+    global _executor
+    if _executor is not None:
+        _executor.shutdown(wait=wait, cancel_futures=not wait)
+        _executor = None
+
+
+def _post(event: Dict[str, Any]) -> None:
+    """Synchronous POST. Raises on any failure."""
+    cfg = get_config()
+    if cfg.offline:
+        log.debug("offline mode — event %s skipped", event["run_id"])
+        return
+    resp = _get_client().post("/v1/ingest", json=event)
+    resp.raise_for_status()
+
+
+def emit_event_sync(event: Dict[str, Any]) -> Tuple[bool, Optional[str]]:
+    """Synchronous ingest. Returns (accepted, error_message)."""
+    try:
+        drain(_post, max_items=20)
+    except Exception as e:
+        log.debug("outbox drain failed: %s", e)
+    try:
+        _post(event)
+        return True, None
+    except Exception as e:
+        enqueue(event)
+        return False, str(e)
+
+
+def emit_event(event: Dict[str, Any]) -> None:
+    """Best-effort delivery via thread pool. Always returns quickly."""
+
+    def _work() -> None:
+        try:
+            drain(_post, max_items=20)
+        except Exception as e:
+            log.debug("outbox drain failed: %s", e)
+        try:
+            _post(event)
+        except Exception as e:
+            log.warning("ingest failed (%s) — queued for retry", e)
+            enqueue(event)
+
+    _get_executor().submit(_work)
+
+
+def fetch_budget(workspace_id: str, customer_id: str) -> Dict[str, Any]:
+    """Pre-flight budget check. Fail-open unless budget_mode=closed."""
+    cfg = get_config()
+    if cfg.offline:
+        return {
+            "status": "ok",
+            "spent_usd": 0.0,
+            "budget_usd": None,
+            "remaining_usd": float("inf"),
+        }
+    try:
+        resp = _get_client().get(
+            "/v1/budget",
+            params={"workspace": workspace_id, "customer": customer_id},
+        )
+        resp.raise_for_status()
+        return resp.json()
+    except Exception as e:
+        if cfg.budget_mode == "closed":
+            raise AgentCOGSError(
+                f"Budget check failed and budget_mode=closed: {e}"
+            ) from e
+        log.warning("budget fetch failed (%s) — failing open", e)
+        return {
+            "status": "ok",
+            "spent_usd": 0.0,
+            "budget_usd": None,
+            "remaining_usd": float("inf"),
+        }

agentcogs/config.py

@@ -0,0 +1,90 @@
+import atexit
+import os
+from dataclasses import dataclass, field
+from typing import Callable, Literal, Optional
+
+from .errors import ConfigurationError
+
+BudgetMode = Literal["open", "closed"]
+
+
+@dataclass
+class _Config:
+    api_key: Optional[str] = None
+    workspace_id: Optional[str] = None
+    endpoint: str = "https://api.agentcogs.dev"
+    timeout_seconds: float = 2.0
+    offline: bool = False
+    budget_mode: BudgetMode = "open"
+    max_ingest_workers: int = 4
+    register_atexit: bool = True
+    on_telemetry_error: Optional[Callable[[Exception], None]] = None
+    _atexit_registered: bool = field(default=False, repr=False)
+
+
+_config = _Config()
+
+
+def init(
+    api_key: Optional[str] = None,
+    workspace_id: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    offline: bool = False,
+    timeout_seconds: float = 2.0,
+    budget_mode: BudgetMode = "open",
+    max_ingest_workers: int = 4,
+    register_atexit: bool = True,
+    on_telemetry_error: Optional[Callable[[Exception], None]] = None,
+) -> None:
+    """Initialise the AgentCOGS SDK.
+
+    Reads from env vars as fallback:
+      AGENTCOGS_API_KEY, AGENTCOGS_WORKSPACE_ID, AGENTCOGS_ENDPOINT,
+      AGENTCOGS_OFFLINE, AGENTCOGS_BUDGET_MODE (open|closed)
+    """
+    from . import client as _client_mod
+
+    _client_mod.reset_client()
+
+    _config.api_key = api_key or os.environ.get("AGENTCOGS_API_KEY")
+    _config.workspace_id = workspace_id or os.environ.get("AGENTCOGS_WORKSPACE_ID")
+    _config.endpoint = (
+        endpoint
+        or os.environ.get("AGENTCOGS_ENDPOINT")
+        or "https://api.agentcogs.dev"
+    ).rstrip("/")
+    _config.offline = offline or os.environ.get("AGENTCOGS_OFFLINE") == "1"
+    _config.timeout_seconds = timeout_seconds
+    env_budget = os.environ.get("AGENTCOGS_BUDGET_MODE", "").lower()
+    if env_budget in ("open", "closed"):
+        _config.budget_mode = env_budget  # type: ignore[assignment]
+    else:
+        _config.budget_mode = budget_mode
+    _config.max_ingest_workers = max(1, max_ingest_workers)
+    _config.register_atexit = register_atexit
+    _config.on_telemetry_error = on_telemetry_error
+
+    if not _config.offline and not _config.api_key:
+        raise ConfigurationError(
+            "agentcogs.init() requires api_key (or AGENTCOGS_API_KEY env). "
+            "For local dev without backend, pass offline=True."
+        )
+
+    if register_atexit and not _config._atexit_registered:
+        atexit.register(_shutdown_on_exit)
+        _config._atexit_registered = True
+
+
+def get_config() -> _Config:
+    if _config.api_key is None and not _config.offline:
+        init()
+    return _config
+
+
+def _shutdown_on_exit() -> None:
+    try:
+        from .shutdown import shutdown
+
+        shutdown(drain_timeout=5.0)
+    except Exception:
+        pass

agentcogs/context.py

@@ -0,0 +1,36 @@
+"""Request-scoped customer/workflow attribution via contextvars."""
+from contextvars import ContextVar
+from typing import Optional
+
+_customer_id: ContextVar[Optional[str]] = ContextVar("agentcogs_customer_id", default=None)
+_workflow_id: ContextVar[Optional[str]] = ContextVar("agentcogs_workflow_id", default=None)
+
+
+def set_customer(customer_id: Optional[str]) -> None:
+    """Set billing customer for the current async/thread context."""
+    _customer_id.set(customer_id)
+
+
+def set_workflow(workflow_id: Optional[str]) -> None:
+    """Set default workflow id for subsequent run() calls in this context."""
+    _workflow_id.set(workflow_id)
+
+
+def get_customer() -> Optional[str]:
+    return _customer_id.get()
+
+
+def get_workflow() -> Optional[str]:
+    return _workflow_id.get()
+
+
+def resolve_customer(explicit: Optional[str]) -> Optional[str]:
+    if explicit is not None:
+        return explicit
+    return get_customer()
+
+
+def resolve_workflow(explicit: Optional[str], default: str = "default") -> str:
+    if explicit is not None:
+        return explicit
+    return get_workflow() or default

agentcogs/errors.py

@@ -0,0 +1,32 @@
+class AgentCOGSError(Exception):
+    """Base exception for all AgentCOGS errors."""
+
+
+class ConfigurationError(AgentCOGSError):
+    """Raised when SDK is used without init() or with bad config."""
+
+
+class PingError(AgentCOGSError):
+    """Raised when agentcogs.ping() cannot reach or authenticate to the API."""
+
+
+class CustomerBudgetExceededError(AgentCOGSError):
+    """Raised when a customer's monthly budget cap is reached.
+
+    Raised on context entry BEFORE any LLM call fires, so zero
+    provider charges are incurred.
+
+    Attributes:
+        customer_id: External customer identifier
+        spent_usd:   Current month-to-date spend
+        budget_usd:  Configured monthly cap
+    """
+
+    def __init__(self, customer_id: str, spent_usd: float, budget_usd: float):
+        self.customer_id = customer_id
+        self.spent_usd = spent_usd
+        self.budget_usd = budget_usd
+        super().__init__(
+            f"Customer '{customer_id}' exceeded budget: "
+            f"${spent_usd:.2f} / ${budget_usd:.2f}"
+        )

agentcogs/integrations/__init__.py

@@ -0,0 +1 @@
+"""Adapters that turn another product's payload into an AgentCOGS ingest event."""

agentcogs/integrations/fastapi.py

@@ -0,0 +1,44 @@
+"""Starlette/FastAPI middleware — set tenant context once per request."""
+from typing import Callable, Optional, Sequence
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+from ..context import set_customer, set_workflow
+
+
+class AgentCOGSMiddleware(BaseHTTPMiddleware):
+    """Populate agentcogs context from each HTTP request.
+
+    Example:
+        app.add_middleware(
+            AgentCOGSMiddleware,
+            customer_id=lambda req: req.state.tenant_id,
+        )
+    """
+
+    def __init__(
+        self,
+        app,
+        customer_id: Callable[[Request], Optional[str]],
+        workflow_id: Optional[Callable[[Request], Optional[str]]] = None,
+        exclude_paths: Sequence[str] = ("/health", "/health/ready"),
+    ):
+        super().__init__(app)
+        self._customer_id = customer_id
+        self._workflow_id = workflow_id
+        self._exclude = tuple(exclude_paths)
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        if request.url.path in self._exclude:
+            return await call_next(request)
+        try:
+            cid = self._customer_id(request)
+            set_customer(cid)
+            if self._workflow_id is not None:
+                set_workflow(self._workflow_id(request))
+            return await call_next(request)
+        finally:
+            set_customer(None)
+            set_workflow(None)

agentcogs/integrations/langgraph.py

@@ -0,0 +1,38 @@
+"""LangGraph helper — set tenant from configurable and wrap run()."""
+from contextlib import contextmanager
+from typing import Any, Iterator, Optional
+
+from ..budget import RunContext, run
+
+
+@contextmanager
+def agentcogs_run(
+    config: Optional[dict] = None,
+    *,
+    customer_id: Optional[str] = None,
+    workflow_id: str = "default",
+    workspace_id: Optional[str] = None,
+    metadata: Optional[dict] = None,
+) -> Iterator[RunContext]:
+    """Context manager for LangGraph invoke blocks.
+
+    Reads tenant_id from config[\"configurable\"][\"tenant_id\"] when customer_id omitted.
+
+    Example:
+        with agentcogs_run(config, workflow_id=\"research_agent\") as ctx:
+            result = graph.invoke(state, config)
+    """
+    cfg = config or {}
+    configurable = cfg.get("configurable") or {}
+    tenant = (
+        customer_id
+        or configurable.get("tenant_id")
+        or configurable.get("customer_id")
+    )
+    with run(
+        customer_id=str(tenant) if tenant else None,
+        workflow_id=workflow_id,
+        workspace_id=workspace_id,
+        metadata=metadata,
+    ) as ctx:
+        yield ctx

agentcogs/integrations/litellm_event.py

@@ -0,0 +1,67 @@
+"""Build an /v1/ingest body from a LiteLLM callback kwargs dict.
+
+LiteLLM reports OpenAI-style usage (prompt_tokens, completion_tokens).
+A raw provider response uses input_tokens and output_tokens. Both are accepted.
+"""
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any
+
+
+def _usage_int(usage: Any, *keys: str) -> int:
+    if usage is None:
+        return 0
+    if isinstance(usage, dict):
+        for key in keys:
+            value = usage.get(key)
+            if value:
+                return int(value)
+        return 0
+    for key in keys:
+        value = getattr(usage, key, None)
+        if value:
+            return int(value)
+    return 0
+
+
+def build_ingest_event(
+    kwargs: dict,
+    *,
+    status: str,
+    error: str | None = None,
+    workspace_id: str | None = None,
+) -> dict | None:
+    """Return an ingest body, or None when the call has no customer."""
+    meta = kwargs.get("metadata") or {}
+    customer_id = kwargs.get("user") or meta.get("agentcogs_customer_id")
+    if not customer_id:
+        return None
+
+    model = kwargs.get("model") or "unknown"
+    cost = float(kwargs.get("response_cost") or 0)
+    usage = kwargs.get("usage")
+    start = kwargs.get("start_time")
+    ts = int(start.timestamp()) if start is not None and hasattr(start, "timestamp") else int(time.time())
+    event = {
+        "run_id": str(uuid.uuid4()),
+        "customer_id": str(customer_id),
+        "workflow_id": meta.get("agentcogs_workflow_id") or "default",
+        "ts": ts,
+        "status": status,
+        "total_usd": max(cost, 0.0),
+        "models": {
+            model: {
+                "input_tokens": _usage_int(usage, "prompt_tokens", "input_tokens"),
+                "output_tokens": _usage_int(usage, "completion_tokens", "output_tokens"),
+                "usd": max(cost, 0.0),
+            }
+        },
+        "node_costs": {},
+        "metadata": {"source": "litellm"},
+        "error": error,
+    }
+    if workspace_id:
+        event["workspace_id"] = workspace_id
+    return event

agentcogs/outbox.py

@@ -0,0 +1,121 @@
+"""Local SQLite outbox for offline-safe cost event delivery.
+
+Pattern: write locally first, retry on next run().
+Mirrors Stripe's recommended meter-event delivery pattern.
+"""
+import json
+import pathlib
+import sqlite3
+import threading
+import time
+from typing import Any, Callable, Dict, List, Tuple
+
+_DB_PATH = pathlib.Path.home() / ".agentcogs" / "outbox.db"
+_LOCK = threading.Lock()
+_MAX_ATTEMPTS = 8
+
+
+def _ensure_db() -> sqlite3.Connection:
+    _DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(_DB_PATH), timeout=5.0, isolation_level=None)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS outbox (
+            run_id      TEXT PRIMARY KEY,
+            payload     TEXT NOT NULL,
+            attempts    INTEGER NOT NULL DEFAULT 0,
+            next_retry  INTEGER NOT NULL DEFAULT 0,
+            created_at  INTEGER NOT NULL,
+            status      TEXT NOT NULL DEFAULT 'pending'
+        )
+        """
+    )
+    # Migrate older DBs without status column
+    cols = {row[1] for row in conn.execute("PRAGMA table_info(outbox)").fetchall()}
+    if "status" not in cols:
+        conn.execute("ALTER TABLE outbox ADD COLUMN status TEXT NOT NULL DEFAULT 'pending'")
+    return conn
+
+
+def enqueue(event: dict) -> None:
+    with _LOCK:
+        conn = _ensure_db()
+        try:
+            conn.execute(
+                "INSERT OR IGNORE INTO outbox (run_id, payload, created_at, status) "
+                "VALUES (?,?,?, 'pending')",
+                (event["run_id"], json.dumps(event), int(time.time())),
+            )
+        finally:
+            conn.close()
+
+
+def drain(post_fn: Callable[[dict], None], max_items: int = 50) -> Tuple[int, int]:
+    """Try to deliver queued events. Returns (succeeded, failed)."""
+    now = int(time.time())
+    sent = failed = 0
+    with _LOCK:
+        conn = _ensure_db()
+        try:
+            rows: List[Tuple[str, str, int]] = conn.execute(
+                "SELECT run_id, payload, attempts FROM outbox "
+                "WHERE status = 'pending' AND attempts < ? AND next_retry <= ? "
+                "ORDER BY created_at LIMIT ?",
+                (_MAX_ATTEMPTS, now, max_items),
+            ).fetchall()
+
+            for run_id, payload, attempts in rows:
+                try:
+                    post_fn(json.loads(payload))
+                    conn.execute("DELETE FROM outbox WHERE run_id=?", (run_id,))
+                    sent += 1
+                except Exception:
+                    new_attempts = attempts + 1
+                    if new_attempts >= _MAX_ATTEMPTS:
+                        conn.execute(
+                            "UPDATE outbox SET attempts=?, status='dead' WHERE run_id=?",
+                            (new_attempts, run_id),
+                        )
+                    else:
+                        backoff = min(2**new_attempts, 3600)
+                        conn.execute(
+                            "UPDATE outbox SET attempts=?, next_retry=? WHERE run_id=?",
+                            (new_attempts, now + backoff, run_id),
+                        )
+                    failed += 1
+        finally:
+            conn.close()
+    return sent, failed
+
+
+def outbox_size() -> int:
+    return int(get_status()["pending"])
+
+
+def clear_outbox() -> None:
+    with _LOCK:
+        conn = _ensure_db()
+        try:
+            conn.execute("DELETE FROM outbox")
+        finally:
+            conn.close()
+
+
+def get_status() -> Dict[str, Any]:
+    with _LOCK:
+        conn = _ensure_db()
+        try:
+            pending = conn.execute(
+                "SELECT COUNT(*) FROM outbox WHERE status='pending'"
+            ).fetchone()[0]
+            dead = conn.execute(
+                "SELECT COUNT(*) FROM outbox WHERE status='dead'"
+            ).fetchone()[0]
+            oldest = conn.execute(
+                "SELECT MIN(created_at) FROM outbox WHERE status='pending'"
+            ).fetchone()[0]
+        finally:
+            conn.close()
+    age = int(time.time()) - oldest if oldest else 0
+    return {"pending": pending, "dead": dead, "oldest_pending_age_sec": age}

agentcogs/ping.py

@@ -0,0 +1,78 @@
+"""Connectivity check — verify API key and endpoint before first run()."""
+from dataclasses import dataclass
+from typing import Optional
+
+import httpx
+
+from .config import get_config
+from .errors import ConfigurationError, PingError
+
+
+@dataclass(frozen=True)
+class PingResult:
+    ok: bool
+    workspace_id: str
+    plan: str
+    server_time: Optional[int] = None
+
+
+def ping(timeout_seconds: Optional[float] = None) -> PingResult:
+    """Verify API key, workspace, and reachability.
+
+    Requires prior agentcogs.init() (or AGENTCOGS_* env vars).
+    """
+    cfg = get_config()
+    if cfg.offline:
+        raise PingError(
+            "ping() is not available in offline mode. Set offline=False and provide api_key."
+        )
+    if not cfg.api_key:
+        raise ConfigurationError(
+            "agentcogs.init() requires api_key (or AGENTCOGS_API_KEY env)."
+        )
+
+    timeout = timeout_seconds if timeout_seconds is not None else cfg.timeout_seconds
+    try:
+        resp = httpx.get(
+            f"{cfg.endpoint}/v1/sdk/ping",
+            headers={
+                "Authorization": f"Bearer {cfg.api_key}",
+                "User-Agent": _user_agent(),
+            },
+            timeout=timeout,
+        )
+    except httpx.ConnectError as e:
+        raise PingError(
+            f"Cannot reach AgentCOGS API at {cfg.endpoint}. "
+            f"Check AGENTCOGS_ENDPOINT and network. ({e})"
+        ) from e
+    except httpx.TimeoutException as e:
+        raise PingError(
+            f"AgentCOGS API timed out after {timeout}s ({cfg.endpoint})."
+        ) from e
+
+    if resp.status_code == 401:
+        raise PingError(
+            "Invalid API key. Copy the key from Settings in the dashboard."
+        )
+    if resp.status_code == 404:
+        raise PingError(
+            f"SDK ping endpoint not found at {cfg.endpoint}. "
+            "Check AGENTCOGS_ENDPOINT (e.g. http://localhost:8000 for local dev)."
+        )
+    if resp.status_code >= 400:
+        raise PingError(f"ping failed: HTTP {resp.status_code} — {resp.text[:200]}")
+
+    data = resp.json()
+    return PingResult(
+        ok=bool(data.get("ok", True)),
+        workspace_id=str(data["workspace_id"]),
+        plan=str(data.get("plan", "free")),
+        server_time=data.get("server_time"),
+    )
+
+
+def _user_agent() -> str:
+    from ._version import __version__
+
+    return f"agentcogs-python/{__version__}"

agentcogs/shutdown.py

@@ -0,0 +1,38 @@
+"""Graceful shutdown — drain outbox and close HTTP resources."""
+from dataclasses import dataclass
+
+from .client import emit_event_sync, reset_client, shutdown_executor
+from .outbox import drain, get_status
+
+
+@dataclass(frozen=True)
+class ShutdownResult:
+    outbox_sent: int
+    outbox_failed: int
+    outbox_pending: int
+    outbox_dead: int
+
+
+def shutdown(drain_timeout: float = 10.0) -> ShutdownResult:
+    """Drain outbox, shut down ingest pool, close httpx client."""
+    from .config import get_config
+    from .client import _post
+
+    cfg = get_config()
+    sent = failed = 0
+    if not cfg.offline:
+        try:
+            sent, failed = drain(_post, max_items=500)
+        except Exception:
+            pass
+
+    shutdown_executor(wait=True, timeout=drain_timeout)
+    reset_client()
+
+    st = get_status()
+    return ShutdownResult(
+        outbox_sent=sent,
+        outbox_failed=failed,
+        outbox_pending=st["pending"],
+        outbox_dead=st["dead"],
+    )

agentcogs/tokens.py

@@ -0,0 +1,4 @@
+"""Provider-specific token normalisation (re-exported from shekel compat layer)."""
+from ._shekel_compat import normalize_summary
+
+__all__ = ["normalize_summary"]

agentcogs-0.1.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,21 @@
+agentcogs/__init__.py,sha256=5qDdVACiAU4e7punzzeDUGJdEDnZFnQtnZnT2C4Wb4o,1056
+agentcogs/__main__.py,sha256=rTZL4C-NQvvPx1P3bwws0GMGxFOvFPxLeAwG06Dn-CM,397
+agentcogs/_shekel_compat.py,sha256=egePEUC0ql-OEebO6useAHSDLYoqXc5DR8g13QevMl4,1654
+agentcogs/_version.py,sha256=rnObPjuBcEStqSO0S6gsdS_ot8ITOQjVj_-P1LUUYpg,22
+agentcogs/budget.py,sha256=x7oauMAlkamAJ0v3nCOc0ekGeA-xrJ2qjKOmYAF_VUw,5546
+agentcogs/client.py,sha256=v86F9UFOYahcjSKzqbJkYx8p46SR16Xzhd0OYLVXApE,4016
+agentcogs/config.py,sha256=C9Rn3NSNfMydSNbBYYR9mjcrbG5VX57VLcAvyvcjXAw,2783
+agentcogs/context.py,sha256=Kgly2n_w0Ho088k82fqjpTGvzreBLppFwgdPUDoWEmg,1098
+agentcogs/errors.py,sha256=zkRL6A8zAz_8Y7Pd3Ka-SeP3KpyJ34UUHz0gn9C8Wb0,1032
+agentcogs/outbox.py,sha256=hajnxk3WwbzUuejuXf159VOR__Rx5_CGlZE647Yb4Vk,4130
+agentcogs/ping.py,sha256=rLPdWixwRnkHWmHh-nd0I1j1xWcf6l0YNyIzG8bg0UA,2389
+agentcogs/shutdown.py,sha256=fXyGAdh_0x4XZNWypNevoExjXDncnVTgMnYIYppQ62I,980
+agentcogs/tokens.py,sha256=zu9UU3cehK5pTY6X3sF5K1tuk4ucUrQ3KSUuV9lSe4E,163
+agentcogs/integrations/__init__.py,sha256=X-JoNZJvuig45_VLsVqZetdlITO3dmZDbEy0m-tIG0g,83
+agentcogs/integrations/fastapi.py,sha256=48pzjAwLPR_2bK0i37t6pG_RrRI9mDXgwp7QF45dmjs,1453
+agentcogs/integrations/langgraph.py,sha256=8x0bzKMSdGqoqY14363LuHVurPsMgCF3oDQB1ypF9Lw,1128
+agentcogs/integrations/litellm_event.py,sha256=SqcpkVCOKZ0JyxEmexBglBKtM3pyzD-wTOx-Iu2V5dM,2042
+agentcogs-0.1.1.dist-info/METADATA,sha256=EjbjLRVmWhUBV1f54TuzN3RIzNkvAcBEouLYk60VpFk,6633
+agentcogs-0.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+agentcogs-0.1.1.dist-info/licenses/LICENSE,sha256=TgFnrhRAuJjfSOjEXFD0SiLP7Wzy79NX1kIFz5spWGI,1066
+agentcogs-0.1.1.dist-info/RECORD,,

agentcogs-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentcogs-0.1.1.dist-info/licenses/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.