fiscallm 0.1.0__py3-none-any.whl

fiscallm/__init__.py

@@ -0,0 +1,13 @@
+"""Track the AI cost of each user against their subscription revenue.
+
+    from fiscallm import Meter
+
+    meter = Meter(api_key=os.environ["FISCALLM_KEY"])
+    meter.track_openai(response, user_id=revenuecat_app_user_id, feature="chat")
+"""
+
+from .meter import DEFAULT_ENDPOINT, MAX_BATCH, Meter
+from .usage import StreamUsage, Usage, from_anthropic, from_gemini, from_openai
+
+__all__ = ["Meter", "Usage", "StreamUsage", "from_openai", "from_anthropic", "from_gemini", "DEFAULT_ENDPOINT", "MAX_BATCH"]
+__version__ = "0.1.0"

fiscallm/meter.py

@@ -0,0 +1,277 @@
+"""The FiscaLLM meter. Standard library only.
+
+Tracking calls only queue an event; a background thread sends batches. The
+meter never raises and never blocks the caller, except ``flush()``.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import threading
+import time
+import urllib.error
+import urllib.request
+import uuid
+from datetime import datetime, timezone
+from typing import Any, AsyncIterable, AsyncIterator, Callable, Dict, Iterable, Iterator, List, Optional, TypeVar, Union
+
+from .usage import StreamUsage, Usage, from_anthropic, from_gemini, from_openai
+
+DEFAULT_ENDPOINT = "https://fiscallm.com/api/v1/events"
+MAX_BATCH = 100
+TIMEOUT_S = 2.0
+RETRY_DELAY_S = 0.25
+INTERVAL_S = 2.0
+
+log = logging.getLogger("fiscallm")
+T = TypeVar("T")
+
+PostFn = Callable[[str, Dict[str, str], bytes], int]
+
+
+def _http_post(url: str, headers: Dict[str, str], body: bytes) -> int:
+    """POSTs and returns the status code; raises on network errors."""
+    request = urllib.request.Request(url, data=body, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(request, timeout=TIMEOUT_S) as response:
+            return response.status
+    except urllib.error.HTTPError as e:
+        return e.code
+
+
+def _count(value: Any) -> int:
+    try:
+        number = round(float(value))
+    except (TypeError, ValueError):
+        return 0
+    return int(number) if number > 0 else 0
+
+
+class Meter:
+    """Reports AI usage per user to FiscaLLM.
+
+    Create one per process. In serverless functions (AWS Lambda, Google Cloud
+    Functions) call ``flush()`` before returning.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str],
+        *,
+        endpoint: str = DEFAULT_ENDPOINT,
+        flush_interval: float = INTERVAL_S,
+        _post: Optional[PostFn] = None,
+    ) -> None:
+        self._api_key = api_key
+        self._endpoint = endpoint
+        self._interval = flush_interval
+        self._post = _post or _http_post
+        self._queue: List[Dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._send_lock = threading.Lock()
+        self._wake = threading.Event()
+        self._warned: set = set()
+        self._closed = False
+        self._thread: Optional[threading.Thread] = None
+        if not api_key:
+            self._warn_once("no-key", "no api_key given; events are not sent")
+        atexit.register(self.flush)
+
+    # ---- public API ----
+
+    def track(
+        self,
+        *,
+        user_id: str,
+        provider: str,
+        model: str,
+        input_tokens: Union[int, float, None] = 0,
+        output_tokens: Union[int, float, None] = 0,
+        cached_tokens: Union[int, float, None] = 0,
+        cache_write_tokens: Union[int, float, None] = 0,
+        cost_usd: Optional[float] = None,
+        feature: Optional[str] = None,
+        ts: Optional[datetime] = None,
+    ) -> None:
+        """Queues one event. ``input_tokens`` excludes cache reads and writes.
+        Pass ``cost_usd`` for calls not priced per token (images, voice)."""
+        try:
+            if not self._api_key:
+                return
+            if not user_id or not provider or not model:
+                self._warn_once("invalid", "track() needs user_id, provider and model; event skipped")
+                return
+            when = ts or datetime.now(timezone.utc)
+            if when.tzinfo is None:
+                when = when.replace(tzinfo=timezone.utc)
+            event: Dict[str, Any] = {
+                "id": str(uuid.uuid4()),
+                "userId": str(user_id),
+                "ts": when.astimezone(timezone.utc).isoformat().replace("+00:00", "Z"),
+                "provider": provider,
+                "model": model,
+                "inputTokens": _count(input_tokens),
+                "outputTokens": _count(output_tokens),
+                "cachedTokens": _count(cached_tokens),
+                "cacheWriteTokens": _count(cache_write_tokens),
+            }
+            if isinstance(cost_usd, (int, float)) and cost_usd >= 0:
+                event["costUsd"] = float(cost_usd)
+            if feature:
+                event["feature"] = feature
+            with self._lock:
+                self._queue.append(event)
+                full = len(self._queue) >= MAX_BATCH
+            self._ensure_thread()
+            if full:
+                self._wake.set()
+        except Exception:  # Metering must never break the caller.
+            pass
+
+    def track_openai(self, response: Any, *, user_id: str, feature: Optional[str] = None, provider: Optional[str] = None, model: Optional[str] = None) -> None:
+        """A Chat Completions or Responses API result, from the SDK or ``r.json()``.
+        Set ``provider`` for OpenAI-compatible APIs such as Groq or OpenRouter."""
+        self._track_usage(self._safe(from_openai, response), "track_openai", user_id, feature, provider, model)
+
+    def track_anthropic(self, response: Any, *, user_id: str, feature: Optional[str] = None, model: Optional[str] = None) -> None:
+        """A Messages API result."""
+        self._track_usage(self._safe(from_anthropic, response), "track_anthropic", user_id, feature, None, model)
+
+    def track_gemini(self, response: Any, *, user_id: str, feature: Optional[str] = None, model: Optional[str] = None) -> None:
+        """A ``generate_content`` result from google-genai, or the REST JSON."""
+        self._track_usage(self._safe(from_gemini, response), "track_gemini", user_id, feature, None, model)
+
+    def track_stream(self, stream: Any, *, user_id: str, feature: Optional[str] = None, provider: Optional[str] = None, model: Optional[str] = None) -> Any:
+        """Wraps a streamed result; chunks pass through unchanged and usage is
+        recorded when the stream ends. Works for sync and async iterables.
+        OpenAI Chat Completions needs ``stream_options={"include_usage": True}``."""
+        if hasattr(stream, "__aiter__"):
+            return self._wrap_async(stream, user_id, feature, provider, model)
+        return self._wrap_sync(stream, user_id, feature, provider, model)
+
+    def flush(self) -> None:
+        """Sends everything queued, waiting at most a few seconds. Never raises."""
+        try:
+            self._send_all()
+        except Exception:
+            pass
+
+    async def aflush(self) -> None:
+        """``flush()`` for async code, run off the event loop."""
+        import asyncio
+
+        await asyncio.get_running_loop().run_in_executor(None, self.flush)
+
+    # ---- internals ----
+
+    def _wrap_sync(self, stream: Iterable[T], user_id: str, feature: Optional[str], provider: Optional[str], model: Optional[str]) -> Iterator[T]:
+        acc = StreamUsage()
+        try:
+            for chunk in stream:
+                try:
+                    acc.add(chunk)
+                except Exception:
+                    pass
+                yield chunk
+        finally:
+            # Also runs when the caller stops early; partial usage is still
+            # the best estimate of what was billed.
+            self._finish_stream(acc, user_id, feature, provider, model)
+
+    async def _wrap_async(self, stream: AsyncIterable[T], user_id: str, feature: Optional[str], provider: Optional[str], model: Optional[str]) -> AsyncIterator[T]:
+        acc = StreamUsage()
+        try:
+            async for chunk in stream:
+                try:
+                    acc.add(chunk)
+                except Exception:
+                    pass
+                yield chunk
+        finally:
+            self._finish_stream(acc, user_id, feature, provider, model)
+
+    def _finish_stream(self, acc: StreamUsage, user_id: str, feature: Optional[str], provider: Optional[str], model: Optional[str]) -> None:
+        try:
+            if acc.missing_openai_usage:
+                self._warn_once("include-usage", 'OpenAI stream had no usage; pass stream_options={"include_usage": True}')
+                return
+            self._track_usage(acc.usage, "track_stream", user_id, feature, provider, model)
+        except Exception:
+            pass
+
+    def _safe(self, fn: Callable[[Any], Optional[Usage]], response: Any) -> Optional[Usage]:
+        try:
+            return fn(response)
+        except Exception:
+            return None
+
+    def _track_usage(self, usage: Optional[Usage], source: str, user_id: str, feature: Optional[str], provider: Optional[str], model: Optional[str]) -> None:
+        if usage is None:
+            self._warn_once(f"no-usage-{source}", f"{source}: no token usage found in the response; event skipped")
+            return
+        self.track(
+            user_id=user_id,
+            provider=provider or usage.provider,
+            model=model or usage.model,
+            input_tokens=usage.input_tokens,
+            output_tokens=usage.output_tokens,
+            cached_tokens=usage.cached_tokens,
+            cache_write_tokens=usage.cache_write_tokens,
+            feature=feature,
+        )
+
+    def _warn_once(self, key: str, message: str) -> None:
+        if key in self._warned:
+            return
+        self._warned.add(key)
+        try:
+            log.warning("[fiscallm] %s", message)
+        except Exception:
+            pass
+
+    def _ensure_thread(self) -> None:
+        if self._thread is not None and self._thread.is_alive():
+            return
+        with self._lock:
+            if self._thread is not None and self._thread.is_alive():
+                return
+            # Daemon: never keeps the process alive; atexit flushes the rest.
+            self._thread = threading.Thread(target=self._run, name="fiscallm", daemon=True)
+            self._thread.start()
+
+    def _run(self) -> None:
+        while not self._closed:
+            self._wake.wait(self._interval)
+            self._wake.clear()
+            try:
+                self._send_all()
+            except Exception:
+                pass
+
+    def _send_all(self) -> None:
+        with self._send_lock:
+            while True:
+                with self._lock:
+                    batch, self._queue = self._queue[:MAX_BATCH], self._queue[MAX_BATCH:]
+                if not batch:
+                    return
+                self._send(batch)
+
+    def _send(self, batch: List[Dict[str, Any]]) -> None:
+        body = json.dumps({"events": batch}).encode()
+        headers = {"content-type": "application/json", "authorization": f"Bearer {self._api_key}", "user-agent": "fiscallm-python/0.1.0"}
+        for attempt in range(2):
+            try:
+                status = self._post(self._endpoint, headers, body)
+            except Exception:
+                status = 0
+            if 200 <= status < 300:
+                return
+            if status and status != 429 and status < 500:
+                self._warn_once(f"http-{status}", f"events rejected ({status}); check the api_key")
+                return
+            if attempt == 0:
+                time.sleep(RETRY_DELAY_S)
+        self._warn_once("unreachable", f"could not reach {self._endpoint}; {len(batch)} events dropped")

fiscallm/usage.py

@@ -0,0 +1,179 @@
+"""Reads token usage from provider responses by shape, without importing any
+provider SDK. Works with SDK objects (OpenAI, Anthropic, google-genai) and with
+plain dicts from ``response.json()``.
+
+Our convention: input_tokens excludes cache reads and cache writes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class Usage:
+    provider: str
+    model: str
+    input_tokens: int
+    output_tokens: int
+    cached_tokens: int
+    cache_write_tokens: int
+
+
+def _get(obj: Any, *names: str) -> Any:
+    """First present attribute or key among ``names``."""
+    if obj is None:
+        return None
+    for name in names:
+        if isinstance(obj, dict):
+            if name in obj and obj[name] is not None:
+                return obj[name]
+        else:
+            value = getattr(obj, name, None)
+            if value is not None:
+                return value
+    return None
+
+
+def _n(value: Any) -> int:
+    try:
+        number = int(value)
+    except (TypeError, ValueError):
+        return 0
+    return number if number > 0 else 0
+
+
+def _openai_usage(model: str, u: Any) -> Usage:
+    total = _n(_get(u, "prompt_tokens", "input_tokens"))
+    details = _get(u, "prompt_tokens_details", "input_tokens_details")
+    cached = _n(_get(details, "cached_tokens"))
+    written = _n(_get(details, "cache_write_tokens"))
+    return Usage(
+        provider="openai",
+        model=model,
+        input_tokens=max(0, total - cached - written),
+        # Includes reasoning tokens, which are billed as output.
+        output_tokens=_n(_get(u, "completion_tokens", "output_tokens")),
+        cached_tokens=cached,
+        cache_write_tokens=written,
+    )
+
+
+def _anthropic_usage(model: str, u: Any) -> Usage:
+    return Usage(
+        provider="anthropic",
+        model=model,
+        input_tokens=_n(_get(u, "input_tokens")),
+        output_tokens=_n(_get(u, "output_tokens")),
+        cached_tokens=_n(_get(u, "cache_read_input_tokens")),
+        cache_write_tokens=_n(_get(u, "cache_creation_input_tokens")),
+    )
+
+
+def _gemini_usage(model: str, u: Any) -> Usage:
+    cached = _n(_get(u, "cached_content_token_count", "cachedContentTokenCount"))
+    prompt = _n(_get(u, "prompt_token_count", "promptTokenCount"))
+    tool = _n(_get(u, "tool_use_prompt_token_count", "toolUsePromptTokenCount"))
+    return Usage(
+        provider="google",
+        model=model,
+        # The prompt count includes the cached part.
+        input_tokens=max(0, prompt - cached) + tool,
+        # Thinking tokens are billed at the output price.
+        output_tokens=_n(_get(u, "candidates_token_count", "candidatesTokenCount"))
+        + _n(_get(u, "thoughts_token_count", "thoughtsTokenCount")),
+        cached_tokens=cached,
+        cache_write_tokens=0,
+    )
+
+
+def from_openai(res: Any) -> Optional[Usage]:
+    usage = _get(res, "usage")
+    return None if usage is None else _openai_usage(str(_get(res, "model") or ""), usage)
+
+
+def from_anthropic(res: Any) -> Optional[Usage]:
+    usage = _get(res, "usage")
+    return None if usage is None else _anthropic_usage(str(_get(res, "model") or ""), usage)
+
+
+def from_gemini(res: Any) -> Optional[Usage]:
+    usage = _get(res, "usage_metadata", "usageMetadata")
+    return None if usage is None else _gemini_usage(str(_get(res, "model_version", "modelVersion") or ""), usage)
+
+
+class StreamUsage:
+    """Collects usage from streamed chunks of any of the three providers."""
+
+    def __init__(self) -> None:
+        self.kind: Optional[str] = None
+        self.model = ""
+        self.raw: Any = None
+        self._anthropic: dict = {}
+
+    @property
+    def missing_openai_usage(self) -> bool:
+        return self.kind == "openai" and self.raw is None
+
+    def add(self, chunk: Any) -> None:
+        kind = _get(chunk, "type")
+        kind = kind if isinstance(kind, str) else ""
+
+        # Anthropic: message_start has the input; message_delta has
+        # cumulative totals that can also update the input counts.
+        if kind == "message_start":
+            message = _get(chunk, "message")
+            self.kind = "anthropic"
+            self.model = str(_get(message, "model") or self.model)
+            self._merge(_get(message, "usage"))
+            return
+        if kind == "message_delta":
+            self.kind = "anthropic"
+            self._merge(_get(chunk, "usage"))
+            return
+
+        # OpenAI Responses API: response.completed and friends.
+        if kind.startswith("response.") and _get(chunk, "response") is not None:
+            response = _get(chunk, "response")
+            self.kind = "openai"
+            self.model = str(_get(response, "model") or self.model)
+            if _get(response, "usage") is not None:
+                self.raw = _get(response, "usage")
+            return
+
+        # OpenAI Chat Completions: usage on the last chunk with include_usage.
+        if _get(chunk, "object") == "chat.completion.chunk" or _get(chunk, "choices") is not None:
+            self.kind = "openai"
+            self.model = str(_get(chunk, "model") or self.model)
+            if _get(chunk, "usage") is not None:
+                self.raw = _get(chunk, "usage")
+            return
+
+        # Gemini: each chunk may carry usage metadata; the last is final.
+        metadata = _get(chunk, "usage_metadata", "usageMetadata")
+        if metadata is not None or _get(chunk, "candidates") is not None:
+            self.kind = "google"
+            self.model = str(_get(chunk, "model_version", "modelVersion") or self.model)
+            if metadata is not None:
+                self.raw = metadata
+
+    def _merge(self, usage: Any) -> None:
+        if usage is None:
+            return
+        fields = ("input_tokens", "output_tokens", "cache_read_input_tokens", "cache_creation_input_tokens")
+        for field in fields:
+            value = _get(usage, field)
+            if value is not None:
+                self._anthropic[field] = value
+        self.raw = self._anthropic
+
+    @property
+    def usage(self) -> Optional[Usage]:
+        if self.kind is None or self.raw is None:
+            return None
+        if self.kind == "anthropic":
+            return _anthropic_usage(self.model, self.raw)
+        if self.kind == "google":
+            return _gemini_usage(self.model, self.raw)
+        return _openai_usage(self.model, self.raw)

fiscallm-0.1.0.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.5
+Name: fiscallm
+Version: 0.1.0
+Summary: Track AI cost per user against subscription revenue. Zero-dependency SDK for your backend.
+Project-URL: Homepage, https://fiscallm.com
+Project-URL: Documentation, https://fiscallm.com/docs
+Project-URL: Source, https://github.com/magna56/ai_spend_book
+License-Expression: MIT
+Keywords: ai,anthropic,cost,gemini,llm,openai,revenuecat
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# fiscallm
+
+Track the AI cost of each user of your app against their subscription revenue. Zero dependencies, Python 3.9+.
+
+The SDK never sits in the path of your AI calls: tracking only queues an event, a background thread sends batches, and it never raises. Prompts and responses are never sent, only token counts.
+
+```sh
+pip install fiscallm
+```
+
+```python
+import os
+from fiscallm import Meter
+
+meter = Meter(api_key=os.environ["FISCALLM_KEY"])  # one per process
+
+# user_id must be the user's RevenueCat app user ID.
+res = openai_client.chat.completions.create(model=model, messages=messages)
+meter.track_openai(res, user_id=user_id, feature="chat")
+
+meter.track_anthropic(message, user_id=user_id)
+meter.track_gemini(result, user_id=user_id)
+
+# Streams (sync or async): iterate the returned stream.
+stream = meter.track_stream(
+    openai_client.chat.completions.create(model=model, messages=messages, stream=True,
+                                          stream_options={"include_usage": True}),
+    user_id=user_id,
+)
+
+# Anything not priced per token:
+meter.track(user_id=user_id, provider="fal", model="flux-pro", cost_usd=0.05)
+
+# Serverless (AWS Lambda, Cloud Functions): before returning
+meter.flush()          # or: await meter.aflush()
+```
+
+OpenAI-compatible APIs work with `meter.track_openai(res, user_id=user_id, provider="groq")`.
+
+Docs: https://fiscallm.com/docs

fiscallm-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+fiscallm/__init__.py,sha256=eziWD4lwDY-PJLXIwBZwn0P1la4qwMw7ol11WP-_Nkg,525
+fiscallm/meter.py,sha256=6-s2bVkIt9t7qQz38UbgTEgNXp4bCHeH7JYlTBIHExs,10992
+fiscallm/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fiscallm/usage.py,sha256=gS0ChVcfuvng5QKyid_myVVqRvtQ7S_5lrczXTsfEVk,6365
+fiscallm-0.1.0.dist-info/METADATA,sha256=RRoJPoZvety9TmJVfnLWwSoQ9U6Mf8NlxhEFYhSGZDk,1962
+fiscallm-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fiscallm-0.1.0.dist-info/RECORD,,

fiscallm-0.1.0.dist-info/WHEEL

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