mintlyr 0.1.0__py3-none-any.whl

mintlyr/__init__.py

@@ -0,0 +1,5 @@
+"""Mintlyr: track AI cost per feature and per user. Zero dependencies."""
+from ._client import atrack_ai, flush, init, track_ai
+
+__all__ = ["init", "track_ai", "atrack_ai", "flush"]
+__version__ = "0.1.0"

mintlyr/_batcher.py

@@ -0,0 +1,71 @@
+"""Batched, fire-and-forget delivery. Telemetry must never raise into, or block, the host app."""
+import json
+import threading
+from typing import Any, Callable, Dict, List, Optional
+
+DEFAULT_BATCH_SIZE = 20
+DEFAULT_FLUSH_INTERVAL_S = 2.0
+# The API rejects bodies over 1MB and batches over 1000 events; stay well inside both.
+MAX_BATCH_BYTES = 500_000
+MAX_BATCH_EVENTS = 500
+
+
+class Batcher:
+    def __init__(
+        self,
+        send: Callable[[List[Dict[str, Any]]], None],
+        batch_size: int = DEFAULT_BATCH_SIZE,
+        flush_interval_s: float = DEFAULT_FLUSH_INTERVAL_S,
+    ) -> None:
+        self._send = send
+        self.batch_size = max(1, min(batch_size, MAX_BATCH_EVENTS))
+        self.flush_interval_s = flush_interval_s
+        self._lock = threading.Lock()
+        self._queue: List[Dict[str, Any]] = []
+        self._bytes = 0
+        self._timer: Optional[threading.Timer] = None
+
+    def enqueue(self, event: Dict[str, Any]) -> None:
+        try:
+            size = len(json.dumps(event))
+        except Exception:
+            return  # unserializable: drop, never raise
+        if size > MAX_BATCH_BYTES:
+            return  # the API would reject it outright
+        to_send: Optional[List[Dict[str, Any]]] = None
+        with self._lock:
+            if self._queue and self._bytes + size > MAX_BATCH_BYTES:
+                to_send = self._take()
+                self._deliver(to_send)
+                to_send = None
+            self._queue.append(event)
+            self._bytes += size
+            if len(self._queue) >= self.batch_size:
+                to_send = self._take()
+            elif self._timer is None:
+                self._timer = threading.Timer(self.flush_interval_s, self.flush)
+                self._timer.daemon = True  # never keep the process alive
+                self._timer.start()
+        if to_send:
+            self._deliver(to_send)
+
+    def flush(self) -> None:
+        with self._lock:
+            events = self._take()
+        if events:
+            self._deliver(events)
+
+    def _take(self) -> List[Dict[str, Any]]:
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+        events, self._queue, self._bytes = self._queue, [], 0
+        return events
+
+    def _deliver(self, events: List[Dict[str, Any]]) -> None:
+        if not events:
+            return
+        try:
+            self._send(events)
+        except Exception:
+            pass  # drop the batch; telemetry never crashes the host app

mintlyr/_client.py

@@ -0,0 +1,86 @@
+import atexit
+import hashlib
+import time
+from datetime import datetime, timezone
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+
+from ._batcher import Batcher
+from ._transport import http_send
+from ._usage import extract_usage
+
+DEFAULT_API_URL = "https://mintlyr-api.onrender.com"
+
+_batcher: Optional[Batcher] = None
+_enabled = False
+
+
+def init(
+    api_key: str,
+    api_url: str = DEFAULT_API_URL,
+    local_mode: bool = False,
+    batch_size: int = 20,
+    flush_interval_s: float = 2.0,
+    _send: Optional[Callable[[List[Dict[str, Any]]], None]] = None,
+) -> None:
+    """Configure Mintlyr once at startup. `local_mode=True` tracks nothing and sends nothing."""
+    global _batcher, _enabled
+    if _batcher is not None:
+        _batcher.flush()
+    _enabled = bool(api_key) and not local_mode
+    send = _send or (lambda evs: http_send(api_url, api_key, evs))
+    _batcher = Batcher(send, batch_size, flush_interval_s)
+
+
+def _hash_user(user_id: str) -> str:
+    # Never send raw end-user identifiers. SHA-256 truncated to 16 hex chars.
+    return hashlib.sha256(user_id.encode()).hexdigest()[:16]
+
+
+def _record(result: Any, started: float, feature: str, provider: str, model: Optional[str],
+            user_id: Optional[str], session_id: Optional[str]) -> None:
+    if not _enabled or _batcher is None:
+        return
+    try:
+        in_tok, out_tok, detected = extract_usage(result, provider)
+        _batcher.enqueue({
+            "feature": feature,
+            "provider": provider,
+            "model": model or detected,
+            "input_tokens": in_tok,
+            "output_tokens": out_tok,
+            "response_time_ms": int((time.monotonic() - started) * 1000),
+            "session_id": session_id,
+            "end_user_id": _hash_user(user_id) if user_id else None,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        })
+    except Exception:
+        pass
+
+
+def track_ai(feature: str, call: Callable[[], Any], provider: str = "auto", model: Optional[str] = None,
+             user_id: Optional[str] = None, session_id: Optional[str] = None) -> Any:
+    """Run `call()` and record its token usage. Returns exactly what `call()` returns.
+    Errors from `call()` propagate untouched; errors in tracking never reach the caller."""
+    started = time.monotonic()
+    result = call()
+    _record(result, started, feature, provider, model, user_id, session_id)
+    return result
+
+
+async def atrack_ai(feature: str, call: Callable[[], Awaitable[Any]], provider: str = "auto",
+                    model: Optional[str] = None, user_id: Optional[str] = None,
+                    session_id: Optional[str] = None) -> Any:
+    """Async variant of track_ai."""
+    started = time.monotonic()
+    result = await call()
+    _record(result, started, feature, provider, model, user_id, session_id)
+    return result
+
+
+def flush() -> None:
+    """Send queued events now. Call before a short-lived process (serverless, CLI) exits."""
+    if _batcher is not None:
+        _batcher.flush()
+
+
+atexit.register(flush)

mintlyr/_transport.py

@@ -0,0 +1,27 @@
+import json
+import urllib.request
+from typing import Any, Dict, List
+
+SDK_VERSION = "0.1.0"
+TIMEOUT_S = 8
+
+
+def http_send(api_url: str, api_key: str, events: List[Dict[str, Any]]) -> None:
+    """POST {events: [...]} to /ingest, retrying once. Raises on final failure (the batcher swallows it)."""
+    body = json.dumps({"events": events}).encode()
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {api_key}",
+        "X-Mintlyr-SDK": "python",
+        "X-Mintlyr-SDK-Version": SDK_VERSION,
+        "X-Mintlyr-Batch-Size": str(len(events)),
+    }
+    last: Exception = RuntimeError("unreachable")
+    for _ in range(2):
+        try:
+            req = urllib.request.Request(f"{api_url}/ingest", data=body, headers=headers, method="POST")
+            urllib.request.urlopen(req, timeout=TIMEOUT_S).close()
+            return
+        except Exception as e:  # noqa: BLE001
+            last = e
+    raise last

mintlyr/_usage.py

@@ -0,0 +1,53 @@
+"""Pull token usage out of provider responses (dicts or SDK objects). Never raises."""
+from typing import Any, Tuple
+
+
+def _get(obj: Any, *names: str) -> Any:
+    for name in names:
+        if obj is None:
+            return None
+        val = obj.get(name) if isinstance(obj, dict) else getattr(obj, name, None)
+        if val is not None:
+            return val
+    return None
+
+
+def _int(v: Any) -> int:
+    return v if isinstance(v, int) and not isinstance(v, bool) and v > 0 else 0
+
+
+def _openai(r: Any) -> Tuple[int, int, str]:
+    u = _get(r, "usage")
+    return _int(_get(u, "prompt_tokens")), _int(_get(u, "completion_tokens")), _get(r, "model") or "unknown"
+
+
+def _anthropic(r: Any) -> Tuple[int, int, str]:
+    u = _get(r, "usage")
+    return _int(_get(u, "input_tokens")), _int(_get(u, "output_tokens")), _get(r, "model") or "unknown"
+
+
+def _gemini(r: Any) -> Tuple[int, int, str]:
+    u = _get(r, "usage_metadata", "usageMetadata")
+    return (
+        _int(_get(u, "prompt_token_count", "promptTokenCount")),
+        _int(_get(u, "candidates_token_count", "candidatesTokenCount")),
+        _get(r, "model_version", "modelVersion", "model") or "unknown",
+    )
+
+
+def extract_usage(response: Any, provider: str = "auto") -> Tuple[int, int, str]:
+    """Return (input_tokens, output_tokens, model). Unknown shapes give (0, 0, 'unknown')."""
+    try:
+        if provider == "openai":
+            return _openai(response)
+        if provider == "anthropic":
+            return _anthropic(response)
+        if provider == "google":
+            return _gemini(response)
+        for fn in (_openai, _anthropic, _gemini):
+            res = fn(response)
+            if res[0] > 0:
+                return res
+        return (0, 0, _get(response, "model") or "unknown")
+    except Exception:
+        return (0, 0, "unknown")

mintlyr-0.1.0.dist-info/METADATA

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: mintlyr
+Version: 0.1.0
+Summary: Track AI cost per feature and per user. Zero dependencies.
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# mintlyr (Python)
+
+Track what each AI feature and each user costs. No dependencies; Python 3.9+.
+
+```python
+import mintlyr
+from openai import OpenAI
+
+mintlyr.init(api_key="ml_live_...")
+client = OpenAI()
+
+reply = mintlyr.track_ai(
+    feature="summarize",
+    provider="openai",
+    user_id="user_123",  # hashed before it leaves your server
+    call=lambda: client.chat.completions.create(model="gpt-5", messages=[...]),
+)
+```
+
+Async: `await mintlyr.atrack_ai(feature=..., call=async_fn)`.
+
+- Returns exactly what your call returns; errors from your call propagate unchanged.
+- Tracking never raises into or blocks your code. Events are batched and sent in the background.
+- In serverless functions or short scripts call `mintlyr.flush()` before exiting.
+- `init(..., local_mode=True)` tracks nothing, useful in tests.
+- Works with OpenAI, Anthropic and Gemini response objects (or plain dicts).
+
+Not yet published to PyPI; install from the repo for now: `pip install ./packages/sdk-python`.

mintlyr-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+mintlyr/__init__.py,sha256=Q_L20CMKHjHHto5A0hW_vX13bp9OTEXDEB2Q4Ey-V74,204
+mintlyr/_batcher.py,sha256=VbTZ4P35Edk0qVKCCcPacqhT_oJ2dWyg_DQDWNyjsdo,2509
+mintlyr/_client.py,sha256=COTy5dIzWmV076kCka1yOUV37tbdn_OWsClFvB9Ujfk,3058
+mintlyr/_transport.py,sha256=0WpAgTUbwQ-BazrUMvUticrGDc3XC5OsVZAcXlgHby8,952
+mintlyr/_usage.py,sha256=vbnsN_mo-ALGl--aYE3bgfjnZ3K0zBFQwaKDKhBX0f8,1827
+mintlyr-0.1.0.dist-info/METADATA,sha256=GEzpvwGMYOU3WTSseGDX_TJs2DSPQp70zYhNotF59B8,1190
+mintlyr-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+mintlyr-0.1.0.dist-info/top_level.txt,sha256=aHrmZMwI-2mrJfbR1qDwDZHRqmm79_4UEO6zI4uqptQ,8
+mintlyr-0.1.0.dist-info/RECORD,,

mintlyr-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mintlyr-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mintlyr