compute-cfo 0.1.0__tar.gz

compute_cfo-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+*.jsonl
+
+# TypeScript
+node_modules/
+dist/
+*.js
+*.d.ts
+*.js.map
+!jest.config.js
+!tsconfig.json
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Environment
+.env
+.env.local

compute_cfo-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: compute-cfo
+Version: 0.1.0
+Summary: Cost tracking, attribution, and budget enforcement for AI inference APIs
+Project-URL: Homepage, https://github.com/YanLukashin/compute-cfo
+Project-URL: Documentation, https://github.com/YanLukashin/compute-cfo#readme
+Project-URL: Repository, https://github.com/YanLukashin/compute-cfo
+Project-URL: Issues, https://github.com/YanLukashin/compute-cfo/issues
+Author-email: Compute CFO <hello@computecfo.com>
+License-Expression: Apache-2.0
+Keywords: ai,anthropic,budget,cost,inference,llm,openai,tracking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software 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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: anthropic>=0.20.0; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+See the main [README](../README.md).

compute_cfo-0.1.0/README.md

@@ -0,0 +1 @@
+See the main [README](../README.md).

compute_cfo-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "compute-cfo"
+version = "0.1.0"
+description = "Cost tracking, attribution, and budget enforcement for AI inference APIs"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.9"
+authors = [
+    { name = "Compute CFO", email = "hello@computecfo.com" },
+]
+keywords = ["llm", "cost", "tracking", "openai", "anthropic", "budget", "inference", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software 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",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.20.0"]
+all = ["openai>=1.0.0", "anthropic>=0.20.0"]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21.0"]
+
+[project.urls]
+Homepage = "https://github.com/YanLukashin/compute-cfo"
+Documentation = "https://github.com/YanLukashin/compute-cfo#readme"
+Repository = "https://github.com/YanLukashin/compute-cfo"
+Issues = "https://github.com/YanLukashin/compute-cfo/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/compute_cfo"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

compute_cfo-0.1.0/src/compute_cfo/__init__.py

@@ -0,0 +1,23 @@
+"""compute-cfo: Cost tracking, attribution, and budget enforcement for AI inference APIs."""
+
+from .budget import BudgetPolicy
+from .exporters import console_exporter, jsonl_exporter, webhook_exporter
+from .pricing import get_cost, get_price
+from .tracker import CostTracker
+from .types import BudgetExceededError, CostEvent
+from .wrapper import wrap
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "wrap",
+    "CostTracker",
+    "CostEvent",
+    "BudgetPolicy",
+    "BudgetExceededError",
+    "get_cost",
+    "get_price",
+    "console_exporter",
+    "jsonl_exporter",
+    "webhook_exporter",
+]

compute_cfo-0.1.0/src/compute_cfo/budget.py

@@ -0,0 +1,91 @@
+"""Budget policy enforcement."""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Callable, Dict, List, Literal, Optional
+
+from .types import BudgetExceededError, CostEvent
+
+
+@dataclass
+class BudgetPolicy:
+    """Defines spending limits and enforcement behavior.
+
+    Args:
+        max_cost: Maximum allowed spend in USD.
+        window: Time window for the budget. "total" means lifetime of the tracker.
+        on_exceed: Action when budget is exceeded.
+            - "raise": raise BudgetExceededError
+            - "warn": emit a warning
+            - "callback": call the on_exceed_callback function
+        on_exceed_callback: Called when on_exceed="callback". Receives the CostEvent
+            that would exceed the budget.
+        tags: If set, this budget applies only to events matching ALL these tags.
+    """
+
+    max_cost: float
+    window: Literal["hourly", "daily", "monthly", "total"] = "total"
+    on_exceed: Literal["raise", "warn", "callback"] = "raise"
+    on_exceed_callback: Optional[Callable[[CostEvent, float], None]] = field(
+        default=None, repr=False
+    )
+    tags: Optional[Dict[str, str]] = None
+
+    def _get_window_start(self, now: datetime) -> Optional[datetime]:
+        if self.window == "total":
+            return None
+        if self.window == "hourly":
+            return now.replace(minute=0, second=0, microsecond=0)
+        if self.window == "daily":
+            return now.replace(hour=0, minute=0, second=0, microsecond=0)
+        if self.window == "monthly":
+            return now.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+        return None
+
+    def _matches_tags(self, event: CostEvent) -> bool:
+        if self.tags is None:
+            return True
+        return all(event.tags.get(k) == v for k, v in self.tags.items())
+
+    def current_spend(self, events: List[CostEvent]) -> float:
+        """Calculate current spend within the active window."""
+        now = datetime.now(timezone.utc)
+        window_start = self._get_window_start(now)
+        total = 0.0
+        for e in events:
+            if window_start and e.timestamp < window_start:
+                continue
+            if not self._matches_tags(e):
+                continue
+            if e.cost_usd is not None:
+                total += e.cost_usd
+        return total
+
+    def check(self, events: List[CostEvent], pending_event: CostEvent) -> None:
+        """Check if recording pending_event would exceed the budget.
+
+        Raises BudgetExceededError or warns depending on on_exceed setting.
+        """
+        if not self._matches_tags(pending_event):
+            return
+
+        current = self.current_spend(events)
+        pending_cost = pending_event.cost_usd or 0.0
+        projected = current + pending_cost
+
+        if projected <= self.max_cost:
+            return
+
+        if self.on_exceed == "raise":
+            raise BudgetExceededError(self.max_cost, projected, self.window)
+        elif self.on_exceed == "warn":
+            warnings.warn(
+                f"[compute-cfo] Budget warning: ${projected:.4f} / ${self.max_cost:.4f} "
+                f"({self.window} window)",
+                stacklevel=3,
+            )
+        elif self.on_exceed == "callback" and self.on_exceed_callback:
+            self.on_exceed_callback(pending_event, projected)

compute_cfo-0.1.0/src/compute_cfo/exporters.py

@@ -0,0 +1,87 @@
+"""Cost event exporters."""
+
+from __future__ import annotations
+
+import json
+import sys
+import urllib.request
+from typing import Callable
+
+from .types import CostEvent
+
+Exporter = Callable[[CostEvent], None]
+
+
+def console_exporter(event: CostEvent) -> None:
+    """Print cost event to stderr."""
+    cost_str = f"${event.cost_usd:.6f}" if event.cost_usd is not None else "$?.??????"
+    total_tokens = event.input_tokens + event.output_tokens
+
+    parts = [
+        f"\033[90m[compute-cfo]\033[0m",
+        f"\033[1m{event.model}\033[0m",
+        f"{total_tokens} tokens",
+        f"\033[33m{cost_str}\033[0m",
+    ]
+
+    if event.tags:
+        tag_str = " ".join(f"{k}:{v}" for k, v in event.tags.items())
+        parts.append(f"\033[90m{tag_str}\033[0m")
+
+    print(" | ".join(parts), file=sys.stderr)
+
+
+def jsonl_exporter(path: str = "compute_cfo_events.jsonl") -> Exporter:
+    """Return an exporter that appends JSON lines to a file."""
+
+    def _export(event: CostEvent) -> None:
+        with open(path, "a") as f:
+            f.write(json.dumps(event.to_dict()) + "\n")
+
+    return _export
+
+
+def webhook_exporter(url: str) -> Exporter:
+    """Return an exporter that POSTs cost events to a URL."""
+
+    def _export(event: CostEvent) -> None:
+        data = json.dumps(event.to_dict()).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            urllib.request.urlopen(req, timeout=5)
+        except Exception:
+            pass  # fire-and-forget
+
+    return _export
+
+
+def get_exporter(spec: str) -> Exporter:
+    """Parse an exporter specification string and return the exporter.
+
+    Supported formats:
+        "console" — print to stderr
+        "jsonl" — write to compute_cfo_events.jsonl
+        "jsonl:/path/to/file.jsonl" — write to custom path
+        "webhook:https://example.com/hook" — POST to URL
+    """
+    if spec == "console":
+        return console_exporter
+
+    if spec == "jsonl":
+        return jsonl_exporter()
+
+    if spec.startswith("jsonl:"):
+        return jsonl_exporter(spec[6:])
+
+    if spec.startswith("webhook:"):
+        return webhook_exporter(spec[8:])
+
+    raise ValueError(
+        f"Unknown exporter: {spec!r}. "
+        f"Use 'console', 'jsonl', 'jsonl:/path', or 'webhook:URL'."
+    )

compute_cfo-0.1.0/src/compute_cfo/pricing.py

@@ -0,0 +1,96 @@
+"""Model pricing database for OpenAI and Anthropic.
+
+Prices are in USD per 1 million tokens. Updated March 2026.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+# {model_id: (input_price_per_1M, output_price_per_1M)}
+MODEL_PRICES: dict[str, Tuple[float, float]] = {
+    # ── OpenAI ──────────────────────────────────────────────
+    # GPT-4.1 family
+    "gpt-4.1": (2.00, 8.00),
+    "gpt-4.1-mini": (0.40, 1.60),
+    "gpt-4.1-nano": (0.10, 0.40),
+    # GPT-4o family
+    "gpt-4o": (2.50, 10.00),
+    "gpt-4o-mini": (0.15, 0.60),
+    "gpt-4o-audio-preview": (2.50, 10.00),
+    # GPT-4 legacy
+    "gpt-4-turbo": (10.00, 30.00),
+    "gpt-4": (30.00, 60.00),
+    # GPT-3.5
+    "gpt-3.5-turbo": (0.50, 1.50),
+    # o-series reasoning
+    "o3": (2.00, 8.00),
+    "o3-mini": (1.10, 4.40),
+    "o4-mini": (1.10, 4.40),
+    "o1": (15.00, 60.00),
+    "o1-mini": (1.10, 4.40),
+    "o1-preview": (15.00, 60.00),
+    # Embeddings
+    "text-embedding-3-small": (0.02, 0.0),
+    "text-embedding-3-large": (0.13, 0.0),
+    "text-embedding-ada-002": (0.10, 0.0),
+
+    # ── Anthropic ───────────────────────────────────────────
+    "claude-opus-4-20250514": (15.00, 75.00),
+    "claude-sonnet-4-20250514": (3.00, 15.00),
+    "claude-3-7-sonnet-20250219": (3.00, 15.00),
+    "claude-3-5-sonnet-20241022": (3.00, 15.00),
+    "claude-3-5-sonnet-20240620": (3.00, 15.00),
+    "claude-3-5-haiku-20241022": (0.80, 4.00),
+    "claude-3-opus-20240229": (15.00, 75.00),
+    "claude-3-sonnet-20240229": (3.00, 15.00),
+    "claude-3-haiku-20240307": (0.25, 1.25),
+    # Aliases
+    "claude-opus-4-0": (15.00, 75.00),
+    "claude-sonnet-4-0": (3.00, 15.00),
+    "claude-3.7-sonnet": (3.00, 15.00),
+    "claude-3.5-sonnet": (3.00, 15.00),
+    "claude-3.5-haiku": (0.80, 4.00),
+    "claude-3-opus": (15.00, 75.00),
+    "claude-3-sonnet": (3.00, 15.00),
+    "claude-3-haiku": (0.25, 1.25),
+}
+
+# Common aliases mapping
+_ALIASES: dict[str, str] = {
+    "gpt-4o-2024-11-20": "gpt-4o",
+    "gpt-4o-2024-08-06": "gpt-4o",
+    "gpt-4o-2024-05-13": "gpt-4o",
+    "gpt-4o-mini-2024-07-18": "gpt-4o-mini",
+    "gpt-4-turbo-2024-04-09": "gpt-4-turbo",
+    "gpt-4-turbo-preview": "gpt-4-turbo",
+    "gpt-4-0125-preview": "gpt-4-turbo",
+    "gpt-4-1106-preview": "gpt-4-turbo",
+    "gpt-3.5-turbo-0125": "gpt-3.5-turbo",
+    "gpt-3.5-turbo-1106": "gpt-3.5-turbo",
+    "o3-2025-04-16": "o3",
+    "o4-mini-2025-04-16": "o4-mini",
+}
+
+
+def resolve_model(model: str) -> str:
+    """Resolve model aliases to canonical name."""
+    return _ALIASES.get(model, model)
+
+
+def get_price(model: str) -> Optional[Tuple[float, float]]:
+    """Return (input_price, output_price) per 1M tokens, or None if unknown."""
+    canonical = resolve_model(model)
+    return MODEL_PRICES.get(canonical)
+
+
+def get_cost(model: str, input_tokens: int, output_tokens: int) -> Optional[float]:
+    """Calculate cost in USD for a given model and token counts.
+
+    Returns None if model pricing is unknown.
+    """
+    price = get_price(model)
+    if price is None:
+        return None
+    input_price, output_price = price
+    return (input_tokens * input_price + output_tokens * output_price) / 1_000_000

compute_cfo-0.1.0/src/compute_cfo/tracker.py

@@ -0,0 +1,103 @@
+"""CostTracker — core cost accumulation and querying."""
+
+from __future__ import annotations
+
+import threading
+from collections import defaultdict
+from typing import Dict, List, Optional
+
+from .budget import BudgetPolicy
+from .exporters import Exporter, get_exporter
+from .types import CostEvent
+
+
+class CostTracker:
+    """Accumulates cost events and provides spend queries.
+
+    Thread-safe by default.
+
+    Args:
+        budget: Optional budget policy to enforce.
+        export: Exporter specification. Can be:
+            - "console" (default): print to stdout
+            - "jsonl": append to compute_cfo_events.jsonl
+            - "jsonl:/path/to/file.jsonl": custom file path
+            - None: no automatic export
+            - A callable that receives CostEvent
+        quiet: If True, suppress console output even if export="console".
+    """
+
+    def __init__(
+        self,
+        budget: Optional[BudgetPolicy] = None,
+        export: Optional[str] = "console",
+        quiet: bool = False,
+    ):
+        self._events: List[CostEvent] = []
+        self._lock = threading.Lock()
+        self._budget = budget
+        self._exporters: List[Exporter] = []
+
+        if quiet:
+            export = None
+
+        if export is not None:
+            self._exporters.append(get_exporter(export))
+
+    def record(self, event: CostEvent) -> None:
+        """Record a cost event. Checks budget and exports."""
+        with self._lock:
+            if self._budget:
+                self._budget.check(self._events, event)
+
+            remaining = None
+            if self._budget and event.cost_usd is not None:
+                spent = self._budget.current_spend(self._events) + event.cost_usd
+                remaining = max(0, self._budget.max_cost - spent)
+            event.budget_remaining_usd = remaining
+
+            self._events.append(event)
+
+        for exporter in self._exporters:
+            exporter(event)
+
+    @property
+    def events(self) -> List[CostEvent]:
+        """Return a copy of all recorded events."""
+        with self._lock:
+            return list(self._events)
+
+    @property
+    def total_cost(self) -> float:
+        """Total cost across all events."""
+        with self._lock:
+            return sum(e.cost_usd for e in self._events if e.cost_usd is not None)
+
+    def cost_by(self, key: str) -> Dict[str, float]:
+        """Aggregate cost by a tag key or by 'model'/'provider'.
+
+        Args:
+            key: Tag name, or "model" / "provider" to group by those fields.
+
+        Returns:
+            Dict mapping key values to total cost.
+        """
+        result: Dict[str, float] = defaultdict(float)
+        with self._lock:
+            for e in self._events:
+                if e.cost_usd is None:
+                    continue
+                if key == "model":
+                    result[e.model] += e.cost_usd
+                elif key == "provider":
+                    result[e.provider] += e.cost_usd
+                else:
+                    tag_val = e.tags.get(key)
+                    if tag_val is not None:
+                        result[tag_val] += e.cost_usd
+        return dict(result)
+
+    def reset(self) -> None:
+        """Clear all recorded events."""
+        with self._lock:
+            self._events.clear()

compute_cfo-0.1.0/src/compute_cfo/types.py

@@ -0,0 +1,55 @@
+"""Core data types for compute-cfo."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class CostEvent:
+    """A single inference cost event."""
+
+    timestamp: datetime
+    provider: str
+    model: str
+    operation: str
+    input_tokens: int
+    output_tokens: int
+    cost_usd: Optional[float]
+    latency_ms: Optional[float] = None
+    tags: Dict[str, str] = field(default_factory=dict)
+    budget_remaining_usd: Optional[float] = None
+    raw_response: Any = field(default=None, repr=False)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to a JSON-compatible dict."""
+        d: Dict[str, Any] = {
+            "timestamp": self.timestamp.isoformat(),
+            "provider": self.provider,
+            "model": self.model,
+            "operation": self.operation,
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "cost_usd": self.cost_usd,
+        }
+        if self.latency_ms is not None:
+            d["latency_ms"] = self.latency_ms
+        if self.tags:
+            d["tags"] = self.tags
+        if self.budget_remaining_usd is not None:
+            d["budget_remaining_usd"] = self.budget_remaining_usd
+        return d
+
+
+class BudgetExceededError(Exception):
+    """Raised when a budget limit has been exceeded."""
+
+    def __init__(self, limit: float, current: float, window: str):
+        self.limit = limit
+        self.current = current
+        self.window = window
+        super().__init__(
+            f"Budget exceeded: ${current:.4f} / ${limit:.4f} ({window} window)"
+        )

compute_cfo-0.1.0/src/compute_cfo/wrapper.py

@@ -0,0 +1,173 @@
+"""Drop-in wrapper for OpenAI and Anthropic SDK clients."""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from .pricing import get_cost
+from .tracker import CostTracker
+from .types import CostEvent
+
+_DEFAULT_TRACKER: Optional[CostTracker] = None
+
+
+def _get_or_create_default_tracker() -> CostTracker:
+    global _DEFAULT_TRACKER
+    if _DEFAULT_TRACKER is None:
+        _DEFAULT_TRACKER = CostTracker(export="console")
+    return _DEFAULT_TRACKER
+
+
+def wrap(client: Any, tracker: Optional[CostTracker] = None) -> Any:
+    """Wrap an OpenAI or Anthropic client with cost tracking.
+
+    Args:
+        client: An instance of openai.OpenAI or anthropic.Anthropic.
+        tracker: Optional CostTracker. If not provided, a default one
+                 with console output is used.
+
+    Returns:
+        A wrapped client that tracks costs transparently.
+    """
+    tracker = tracker or _get_or_create_default_tracker()
+
+    client_type = type(client).__module__.split(".")[0]
+
+    if client_type == "openai":
+        return _OpenAIWrapper(client, tracker)
+    elif client_type == "anthropic":
+        return _AnthropicWrapper(client, tracker)
+    else:
+        raise TypeError(
+            f"Unsupported client type: {type(client).__name__}. "
+            f"Supported: openai.OpenAI, anthropic.Anthropic"
+        )
+
+
+class _TrackedCompletions:
+    """Proxy for client.chat.completions with cost tracking."""
+
+    def __init__(self, completions: Any, tracker: CostTracker):
+        self._completions = completions
+        self._tracker = tracker
+
+    def create(self, **kwargs: Any) -> Any:
+        tags = kwargs.pop("metadata", None) or {}
+        if not isinstance(tags, dict):
+            tags = {}
+
+        model = kwargs.get("model", "unknown")
+        start = time.monotonic()
+        response = self._completions.create(**kwargs)
+        latency_ms = (time.monotonic() - start) * 1000
+
+        usage = getattr(response, "usage", None)
+        input_tokens = getattr(usage, "prompt_tokens", 0) if usage else 0
+        output_tokens = getattr(usage, "completion_tokens", 0) if usage else 0
+
+        actual_model = getattr(response, "model", model)
+        cost = get_cost(actual_model, input_tokens, output_tokens)
+
+        event = CostEvent(
+            timestamp=datetime.now(timezone.utc),
+            provider="openai",
+            model=actual_model,
+            operation="chat.completions",
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cost_usd=cost,
+            latency_ms=round(latency_ms, 1),
+            tags=tags,
+        )
+        self._tracker.record(event)
+        return response
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._completions, name)
+
+
+class _TrackedChat:
+    """Proxy for client.chat with tracked completions."""
+
+    def __init__(self, chat: Any, tracker: CostTracker):
+        self._chat = chat
+        self._tracker = tracker
+        self.completions = _TrackedCompletions(chat.completions, tracker)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._chat, name)
+
+
+class _OpenAIWrapper:
+    """Proxy for OpenAI client."""
+
+    def __init__(self, client: Any, tracker: CostTracker):
+        self._client = client
+        self._tracker = tracker
+        self.chat = _TrackedChat(client.chat, tracker)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)
+
+
+class _TrackedMessages:
+    """Proxy for client.messages (Anthropic) with cost tracking."""
+
+    def __init__(self, messages: Any, tracker: CostTracker):
+        self._messages = messages
+        self._tracker = tracker
+
+    def create(self, **kwargs: Any) -> Any:
+        metadata = kwargs.get("metadata", None)
+        tags: Dict[str, str] = {}
+        if isinstance(metadata, dict):
+            # Anthropic metadata has a user_id field; we extract custom tags
+            tags = {k: str(v) for k, v in metadata.items() if k != "user_id"}
+
+        # Also support a compute_cfo_tags kwarg for explicit tagging
+        explicit_tags = kwargs.pop("compute_cfo_tags", None)
+        if isinstance(explicit_tags, dict):
+            tags.update(explicit_tags)
+
+        model = kwargs.get("model", "unknown")
+        start = time.monotonic()
+        response = self._messages.create(**kwargs)
+        latency_ms = (time.monotonic() - start) * 1000
+
+        usage = getattr(response, "usage", None)
+        input_tokens = getattr(usage, "input_tokens", 0) if usage else 0
+        output_tokens = getattr(usage, "output_tokens", 0) if usage else 0
+
+        actual_model = getattr(response, "model", model)
+        cost = get_cost(actual_model, input_tokens, output_tokens)
+
+        event = CostEvent(
+            timestamp=datetime.now(timezone.utc),
+            provider="anthropic",
+            model=actual_model,
+            operation="messages",
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cost_usd=cost,
+            latency_ms=round(latency_ms, 1),
+            tags=tags,
+        )
+        self._tracker.record(event)
+        return response
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._messages, name)
+
+
+class _AnthropicWrapper:
+    """Proxy for Anthropic client."""
+
+    def __init__(self, client: Any, tracker: CostTracker):
+        self._client = client
+        self._tracker = tracker
+        self.messages = _TrackedMessages(client.messages, tracker)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._client, name)

compute_cfo-0.1.0/tests/test_budget.py

@@ -0,0 +1,112 @@
+import warnings
+from datetime import datetime, timezone
+
+import pytest
+
+from compute_cfo.budget import BudgetPolicy
+from compute_cfo.tracker import CostTracker
+from compute_cfo.types import BudgetExceededError, CostEvent
+
+
+def _make_event(cost: float = 0.01) -> CostEvent:
+    return CostEvent(
+        timestamp=datetime.now(timezone.utc),
+        provider="openai",
+        model="gpt-4o",
+        operation="chat.completions",
+        input_tokens=100,
+        output_tokens=50,
+        cost_usd=cost,
+    )
+
+
+def test_budget_raise_on_exceed():
+    tracker = CostTracker(
+        budget=BudgetPolicy(max_cost=0.05, on_exceed="raise"),
+        quiet=True,
+    )
+    tracker.record(_make_event(cost=0.03))
+    with pytest.raises(BudgetExceededError) as exc_info:
+        tracker.record(_make_event(cost=0.03))
+    assert exc_info.value.limit == 0.05
+    assert exc_info.value.current > 0.05
+
+
+def test_budget_warn_on_exceed():
+    tracker = CostTracker(
+        budget=BudgetPolicy(max_cost=0.05, on_exceed="warn"),
+        quiet=True,
+    )
+    tracker.record(_make_event(cost=0.03))
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        tracker.record(_make_event(cost=0.03))
+        assert len(w) == 1
+        assert "Budget warning" in str(w[0].message)
+
+
+def test_budget_callback_on_exceed():
+    exceeded_events = []
+
+    def on_exceed(event: CostEvent, projected: float):
+        exceeded_events.append((event, projected))
+
+    tracker = CostTracker(
+        budget=BudgetPolicy(
+            max_cost=0.05,
+            on_exceed="callback",
+            on_exceed_callback=on_exceed,
+        ),
+        quiet=True,
+    )
+    tracker.record(_make_event(cost=0.03))
+    tracker.record(_make_event(cost=0.03))
+    assert len(exceeded_events) == 1
+    assert exceeded_events[0][1] > 0.05
+
+
+def test_budget_not_exceeded():
+    tracker = CostTracker(
+        budget=BudgetPolicy(max_cost=1.00, on_exceed="raise"),
+        quiet=True,
+    )
+    tracker.record(_make_event(cost=0.03))
+    tracker.record(_make_event(cost=0.03))
+    assert abs(tracker.total_cost - 0.06) < 1e-10
+
+
+def test_budget_remaining_tracked():
+    tracker = CostTracker(
+        budget=BudgetPolicy(max_cost=1.00),
+        quiet=True,
+    )
+    tracker.record(_make_event(cost=0.30))
+    event = tracker.events[-1]
+    assert event.budget_remaining_usd is not None
+    assert abs(event.budget_remaining_usd - 0.70) < 1e-10
+
+
+def test_budget_with_tag_filter():
+    tracker = CostTracker(
+        budget=BudgetPolicy(
+            max_cost=0.05,
+            on_exceed="raise",
+            tags={"project": "expensive"},
+        ),
+        quiet=True,
+    )
+    # This should not count toward the budget
+    cheap_event = _make_event(cost=0.10)
+    cheap_event.tags = {"project": "cheap"}
+    tracker.record(cheap_event)
+
+    # This should count
+    exp_event = _make_event(cost=0.03)
+    exp_event.tags = {"project": "expensive"}
+    tracker.record(exp_event)
+
+    # This should exceed
+    exp_event2 = _make_event(cost=0.03)
+    exp_event2.tags = {"project": "expensive"}
+    with pytest.raises(BudgetExceededError):
+        tracker.record(exp_event2)

compute_cfo-0.1.0/tests/test_pricing.py

@@ -0,0 +1,45 @@
+from compute_cfo.pricing import get_cost, get_price, resolve_model
+
+
+def test_known_model_price():
+    price = get_price("gpt-4o")
+    assert price == (2.50, 10.00)
+
+
+def test_anthropic_model_price():
+    price = get_price("claude-sonnet-4-20250514")
+    assert price == (3.00, 15.00)
+
+
+def test_unknown_model_returns_none():
+    assert get_price("nonexistent-model") is None
+
+
+def test_alias_resolution():
+    assert resolve_model("gpt-4o-2024-11-20") == "gpt-4o"
+    assert resolve_model("gpt-4o") == "gpt-4o"  # not an alias, returns as-is
+
+
+def test_get_cost_calculation():
+    # gpt-4o: $2.50 input, $10.00 output per 1M tokens
+    cost = get_cost("gpt-4o", input_tokens=1000, output_tokens=500)
+    assert cost is not None
+    expected = (1000 * 2.50 + 500 * 10.00) / 1_000_000
+    assert abs(cost - expected) < 1e-10
+
+
+def test_get_cost_unknown_model():
+    assert get_cost("nonexistent", 100, 100) is None
+
+
+def test_get_cost_alias():
+    cost_alias = get_cost("gpt-4o-2024-11-20", 1000, 500)
+    cost_direct = get_cost("gpt-4o", 1000, 500)
+    assert cost_alias == cost_direct
+
+
+def test_embedding_model_no_output_cost():
+    cost = get_cost("text-embedding-3-small", input_tokens=1000, output_tokens=0)
+    assert cost is not None
+    expected = (1000 * 0.02) / 1_000_000
+    assert abs(cost - expected) < 1e-10

compute_cfo-0.1.0/tests/test_tracker.py

@@ -0,0 +1,80 @@
+from datetime import datetime, timezone
+
+from compute_cfo.tracker import CostTracker
+from compute_cfo.types import CostEvent
+
+
+def _make_event(
+    cost: float = 0.01,
+    model: str = "gpt-4o",
+    provider: str = "openai",
+    tags: dict | None = None,
+) -> CostEvent:
+    return CostEvent(
+        timestamp=datetime.now(timezone.utc),
+        provider=provider,
+        model=model,
+        operation="chat.completions",
+        input_tokens=100,
+        output_tokens=50,
+        cost_usd=cost,
+        tags=tags or {},
+    )
+
+
+def test_empty_tracker():
+    t = CostTracker(quiet=True)
+    assert t.total_cost == 0.0
+    assert t.events == []
+
+
+def test_record_and_total():
+    t = CostTracker(quiet=True)
+    t.record(_make_event(cost=0.05))
+    t.record(_make_event(cost=0.03))
+    assert abs(t.total_cost - 0.08) < 1e-10
+
+
+def test_cost_by_model():
+    t = CostTracker(quiet=True)
+    t.record(_make_event(cost=0.05, model="gpt-4o"))
+    t.record(_make_event(cost=0.01, model="gpt-4o-mini"))
+    t.record(_make_event(cost=0.03, model="gpt-4o"))
+    by_model = t.cost_by("model")
+    assert abs(by_model["gpt-4o"] - 0.08) < 1e-10
+    assert abs(by_model["gpt-4o-mini"] - 0.01) < 1e-10
+
+
+def test_cost_by_tag():
+    t = CostTracker(quiet=True)
+    t.record(_make_event(cost=0.05, tags={"project": "search"}))
+    t.record(_make_event(cost=0.03, tags={"project": "chat"}))
+    t.record(_make_event(cost=0.02, tags={"project": "search"}))
+    by_project = t.cost_by("project")
+    assert abs(by_project["search"] - 0.07) < 1e-10
+    assert abs(by_project["chat"] - 0.03) < 1e-10
+
+
+def test_cost_by_provider():
+    t = CostTracker(quiet=True)
+    t.record(_make_event(cost=0.05, provider="openai"))
+    t.record(_make_event(cost=0.03, provider="anthropic"))
+    by_provider = t.cost_by("provider")
+    assert abs(by_provider["openai"] - 0.05) < 1e-10
+    assert abs(by_provider["anthropic"] - 0.03) < 1e-10
+
+
+def test_reset():
+    t = CostTracker(quiet=True)
+    t.record(_make_event(cost=0.05))
+    t.reset()
+    assert t.total_cost == 0.0
+    assert t.events == []
+
+
+def test_events_returns_copy():
+    t = CostTracker(quiet=True)
+    t.record(_make_event(cost=0.05))
+    events = t.events
+    events.clear()
+    assert len(t.events) == 1  # original not affected

compute_cfo-0.1.0/tests/test_wrapper.py

@@ -0,0 +1,147 @@
+"""Tests for the wrap() function using mock SDK clients."""
+
+from datetime import datetime, timezone
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+from compute_cfo.tracker import CostTracker
+from compute_cfo.wrapper import wrap
+
+
+def _make_openai_client():
+    """Create a mock OpenAI client."""
+    client = MagicMock()
+    client.__class__.__module__ = "openai.client"
+    # Simulate response
+    response = SimpleNamespace(
+        model="gpt-4o",
+        usage=SimpleNamespace(prompt_tokens=100, completion_tokens=50),
+        choices=[SimpleNamespace(message=SimpleNamespace(content="Hello!"))],
+    )
+    client.chat.completions.create.return_value = response
+    return client
+
+
+def _make_anthropic_client():
+    """Create a mock Anthropic client."""
+    client = MagicMock()
+    client.__class__.__module__ = "anthropic.client"
+    response = SimpleNamespace(
+        model="claude-sonnet-4-20250514",
+        usage=SimpleNamespace(input_tokens=100, output_tokens=50),
+        content=[SimpleNamespace(text="Hello!")],
+    )
+    client.messages.create.return_value = response
+    return client
+
+
+def test_wrap_openai_tracks_cost():
+    tracker = CostTracker(quiet=True)
+    client = _make_openai_client()
+    wrapped = wrap(client, tracker=tracker)
+
+    response = wrapped.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "hi"}],
+    )
+
+    assert response.model == "gpt-4o"
+    assert len(tracker.events) == 1
+    event = tracker.events[0]
+    assert event.provider == "openai"
+    assert event.model == "gpt-4o"
+    assert event.input_tokens == 100
+    assert event.output_tokens == 50
+    assert event.cost_usd is not None
+    assert event.cost_usd > 0
+
+
+def test_wrap_openai_with_tags():
+    tracker = CostTracker(quiet=True)
+    client = _make_openai_client()
+    wrapped = wrap(client, tracker=tracker)
+
+    wrapped.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "hi"}],
+        metadata={"project": "search", "agent": "summarizer"},
+    )
+
+    event = tracker.events[0]
+    assert event.tags == {"project": "search", "agent": "summarizer"}
+
+
+def test_wrap_anthropic_tracks_cost():
+    tracker = CostTracker(quiet=True)
+    client = _make_anthropic_client()
+    wrapped = wrap(client, tracker=tracker)
+
+    response = wrapped.messages.create(
+        model="claude-sonnet-4-20250514",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": "hi"}],
+    )
+
+    assert len(tracker.events) == 1
+    event = tracker.events[0]
+    assert event.provider == "anthropic"
+    assert event.model == "claude-sonnet-4-20250514"
+    assert event.input_tokens == 100
+    assert event.output_tokens == 50
+    assert event.cost_usd is not None
+
+
+def test_wrap_anthropic_with_tags():
+    tracker = CostTracker(quiet=True)
+    client = _make_anthropic_client()
+    wrapped = wrap(client, tracker=tracker)
+
+    wrapped.messages.create(
+        model="claude-sonnet-4-20250514",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": "hi"}],
+        compute_cfo_tags={"project": "search"},
+    )
+
+    event = tracker.events[0]
+    assert event.tags == {"project": "search"}
+
+
+def test_wrap_passthrough_attributes():
+    """Non-tracked attributes should pass through to the original client."""
+    tracker = CostTracker(quiet=True)
+    client = _make_openai_client()
+    client.models = MagicMock()
+    client.models.list.return_value = ["gpt-4o"]
+
+    wrapped = wrap(client, tracker=tracker)
+    result = wrapped.models.list()
+    assert result == ["gpt-4o"]
+
+
+def test_wrap_unsupported_client():
+    """Should raise TypeError for unsupported clients."""
+    import pytest
+
+    tracker = CostTracker(quiet=True)
+
+    class FakeClient:
+        pass
+
+    with pytest.raises(TypeError, match="Unsupported client type"):
+        wrap(FakeClient(), tracker=tracker)
+
+
+def test_wrap_records_latency():
+    tracker = CostTracker(quiet=True)
+    client = _make_openai_client()
+    wrapped = wrap(client, tracker=tracker)
+
+    wrapped.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "hi"}],
+    )
+
+    event = tracker.events[0]
+    assert event.latency_ms is not None
+    assert event.latency_ms >= 0