mintlyr 0.1.0__tar.gz

mintlyr-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,28 @@
+# 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/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-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-0.1.0/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-0.1.0/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-0.1.0/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/mintlyr.egg-info/PKG-INFO

@@ -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/mintlyr.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+mintlyr/__init__.py
+mintlyr/_batcher.py
+mintlyr/_client.py
+mintlyr/_transport.py
+mintlyr/_usage.py
+mintlyr.egg-info/PKG-INFO
+mintlyr.egg-info/SOURCES.txt
+mintlyr.egg-info/dependency_links.txt
+mintlyr.egg-info/top_level.txt
+tests/test_client.py
+tests/test_usage.py

mintlyr-0.1.0/mintlyr.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mintlyr-0.1.0/mintlyr.egg-info/top_level.txt

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

mintlyr-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mintlyr"
+version = "0.1.0"
+description = "Track AI cost per feature and per user. Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = []
+
+[tool.setuptools]
+packages = ["mintlyr"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

mintlyr-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mintlyr-0.1.0/tests/test_client.py

@@ -0,0 +1,101 @@
+import asyncio
+import pytest
+
+import mintlyr
+from mintlyr._batcher import Batcher, MAX_BATCH_EVENTS
+
+
+def make(sent, **kw):
+    return Batcher(send=lambda evs: sent.append(list(evs)), batch_size=kw.get("batch_size", 3), flush_interval_s=kw.get("flush_interval_s", 60))
+
+
+def test_flushes_when_batch_full():
+    sent = []
+    b = make(sent)
+    for i in range(3):
+        b.enqueue({"i": i})
+    assert [len(x) for x in sent] == [3]
+
+
+def test_manual_flush_sends_remainder_once():
+    sent = []
+    b = make(sent)
+    b.enqueue({"i": 1})
+    b.flush()
+    b.flush()
+    assert [len(x) for x in sent] == [1]
+
+
+def test_batch_size_is_capped_to_api_limit():
+    sent = []
+    b = make(sent, batch_size=10**6)
+    assert b.batch_size == MAX_BATCH_EVENTS
+
+
+def test_oversized_and_unserializable_events_are_dropped_not_raised():
+    sent = []
+    b = make(sent)
+    b.enqueue({"x": "a" * 600_000})
+    b.enqueue({"x": object()})
+    b.flush()
+    assert sent == []
+
+
+def test_send_failure_never_raises():
+    def boom(evs):
+        raise RuntimeError("network down")
+    b = Batcher(send=boom, batch_size=1, flush_interval_s=60)
+    b.enqueue({"a": 1})  # must not raise
+
+
+def test_track_ai_returns_result_and_queues_event():
+    sent = []
+    mintlyr.init(api_key="ml_live_x", _send=lambda evs: sent.append(list(evs)))
+    out = mintlyr.track_ai(
+        feature="summarize",
+        call=lambda: {"model": "gpt-5", "usage": {"prompt_tokens": 9, "completion_tokens": 4}},
+        provider="openai",
+        user_id="alice",
+    )
+    assert out["model"] == "gpt-5"
+    mintlyr.flush()
+    ev = sent[0][0]
+    assert ev["feature"] == "summarize" and ev["input_tokens"] == 9 and ev["output_tokens"] == 4
+    assert ev["model"] == "gpt-5" and ev["response_time_ms"] >= 0
+    assert ev["end_user_id"] and ev["end_user_id"] != "alice" and len(ev["end_user_id"]) == 16
+
+
+def test_caller_exceptions_propagate_and_nothing_is_tracked():
+    sent = []
+    mintlyr.init(api_key="k", _send=lambda evs: sent.append(list(evs)))
+
+    def bad():
+        raise ValueError("model error")
+    with pytest.raises(ValueError):
+        mintlyr.track_ai(feature="f", call=bad)
+    mintlyr.flush()
+    assert sent == []
+
+
+def test_local_mode_sends_nothing():
+    sent = []
+    mintlyr.init(api_key="k", local_mode=True, _send=lambda evs: sent.append(list(evs)))
+    mintlyr.track_ai(feature="f", call=lambda: {})
+    mintlyr.flush()
+    assert sent == []
+
+
+def test_async_variant():
+    asyncio.run(_async_case())
+
+
+async def _async_case():
+    sent = []
+    mintlyr.init(api_key="k", _send=lambda evs: sent.append(list(evs)))
+
+    async def call():
+        return {"model": "m", "usage": {"input_tokens": 1, "output_tokens": 2}}
+    out = await mintlyr.atrack_ai(feature="f", call=call, provider="anthropic")
+    assert out["model"] == "m"
+    mintlyr.flush()
+    assert sent[0][0]["output_tokens"] == 2

mintlyr-0.1.0/tests/test_usage.py

@@ -0,0 +1,33 @@
+from types import SimpleNamespace as NS
+
+from mintlyr._usage import extract_usage
+
+
+def test_openai_dict():
+    r = {"model": "gpt-5", "usage": {"prompt_tokens": 10, "completion_tokens": 5}}
+    assert extract_usage(r, "openai") == (10, 5, "gpt-5")
+
+
+def test_openai_object():
+    r = NS(model="gpt-5", usage=NS(prompt_tokens=7, completion_tokens=3))
+    assert extract_usage(r, "openai") == (7, 3, "gpt-5")
+
+
+def test_anthropic_object():
+    r = NS(model="claude-sonnet-4-5", usage=NS(input_tokens=11, output_tokens=2))
+    assert extract_usage(r, "anthropic") == (11, 2, "claude-sonnet-4-5")
+
+
+def test_gemini_object():
+    r = NS(usage_metadata=NS(prompt_token_count=4, candidates_token_count=6), model_version="gemini-2.5-flash")
+    assert extract_usage(r, "google") == (4, 6, "gemini-2.5-flash")
+
+
+def test_auto_detects_each_shape():
+    assert extract_usage({"model": "m", "usage": {"input_tokens": 3, "output_tokens": 1}}, "auto")[:2] == (3, 1)
+    assert extract_usage({"model": "m", "usage": {"prompt_tokens": 2, "completion_tokens": 1}}, "auto")[:2] == (2, 1)
+
+
+def test_unknown_shape_is_zero_not_error():
+    assert extract_usage(object(), "auto") == (0, 0, "unknown")
+    assert extract_usage(None, "openai") == (0, 0, "unknown")