weckr-sdk 0.1.0__tar.gz

weckr_sdk-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.env
+.env.local

weckr_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Weckr
+
+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.

weckr_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: weckr-sdk
+Version: 0.1.0
+Summary: AI cost and margin intelligence for SaaS founders
+Project-URL: Homepage, https://useweckr.com
+Project-URL: Documentation, https://useweckr.com/docs
+Project-URL: Repository, https://github.com/Ghiles3232/weckr
+Project-URL: Issues, https://github.com/Ghiles3232/weckr/issues
+Author: Weckr
+License: MIT License
+        
+        Copyright (c) 2026 Weckr
+        
+        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.
+License-File: LICENSE
+Keywords: ai,anthropic,cost,finops,gemini,llm,monitoring,openai,saas
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: anthropic>=0.20.0; extra == 'all'
+Requires-Dist: google-generativeai>=0.5.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>=7.0; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-generativeai>=0.5.0; extra == 'gemini'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# weckr
+
+Token-budget enforcement and observability for LLM apps. One line to wrap any OpenAI or Anthropic client.
+
+## Install
+
+```bash
+pip install weckr
+```
+
+## Quick start
+
+```python
+import os
+from openai import OpenAI
+from weckr import Weckr
+
+wk = Weckr(api_key=os.environ["WK_API_KEY"])
+client = wk.wrap(OpenAI())
+
+resp = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+print(resp.choices[0].message.content)
+```
+
+Every call is logged to your Weckr dashboard with token counts, latency, and cost. If you exceed your daily token cap, the next call raises `WeckrCapError` instead of silently burning money.
+
+## How it works
+
+`wk.wrap(client)` returns a proxy that:
+
+1. Checks your remaining budget before each call (cached, ~5ms overhead).
+2. Forwards the call to the underlying client unchanged.
+3. Fires a non-blocking log to `api.weckr.dev` with usage data.
+
+Works with sync and async clients. Streaming is passed through transparently — usage is logged when the stream closes.
+
+## Anthropic
+
+```python
+from anthropic import Anthropic
+from weckr import Weckr
+
+wk = Weckr(api_key=os.environ["WK_API_KEY"])
+client = wk.wrap(Anthropic())
+
+msg = client.messages.create(
+    model="claude-3-5-sonnet-latest",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+```
+
+## Direct chat
+
+If you don't want to wrap a client, use `wk.chat` directly:
+
+```python
+text = wk.chat(
+    provider="openai",
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hi"}],
+)
+```
+
+`wk.chat` raises `WeckrCapError` if you're over budget.
+
+## Configuration
+
+| Env var          | Purpose                                        |
+| ---------------- | ---------------------------------------------- |
+| `WK_API_KEY`     | Your Weckr API key (starts with `wk_`)         |
+| `OPENAI_API_KEY` | Forwarded to the OpenAI client                 |
+| `ANTHROPIC_API_KEY` | Forwarded to the Anthropic client           |
+
+Get your key at [weckr.dev](https://weckr.dev).
+
+## License
+
+MIT

weckr_sdk-0.1.0/README.md

@@ -0,0 +1,82 @@
+# weckr
+
+Token-budget enforcement and observability for LLM apps. One line to wrap any OpenAI or Anthropic client.
+
+## Install
+
+```bash
+pip install weckr
+```
+
+## Quick start
+
+```python
+import os
+from openai import OpenAI
+from weckr import Weckr
+
+wk = Weckr(api_key=os.environ["WK_API_KEY"])
+client = wk.wrap(OpenAI())
+
+resp = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+print(resp.choices[0].message.content)
+```
+
+Every call is logged to your Weckr dashboard with token counts, latency, and cost. If you exceed your daily token cap, the next call raises `WeckrCapError` instead of silently burning money.
+
+## How it works
+
+`wk.wrap(client)` returns a proxy that:
+
+1. Checks your remaining budget before each call (cached, ~5ms overhead).
+2. Forwards the call to the underlying client unchanged.
+3. Fires a non-blocking log to `api.weckr.dev` with usage data.
+
+Works with sync and async clients. Streaming is passed through transparently — usage is logged when the stream closes.
+
+## Anthropic
+
+```python
+from anthropic import Anthropic
+from weckr import Weckr
+
+wk = Weckr(api_key=os.environ["WK_API_KEY"])
+client = wk.wrap(Anthropic())
+
+msg = client.messages.create(
+    model="claude-3-5-sonnet-latest",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+```
+
+## Direct chat
+
+If you don't want to wrap a client, use `wk.chat` directly:
+
+```python
+text = wk.chat(
+    provider="openai",
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hi"}],
+)
+```
+
+`wk.chat` raises `WeckrCapError` if you're over budget.
+
+## Configuration
+
+| Env var          | Purpose                                        |
+| ---------------- | ---------------------------------------------- |
+| `WK_API_KEY`     | Your Weckr API key (starts with `wk_`)         |
+| `OPENAI_API_KEY` | Forwarded to the OpenAI client                 |
+| `ANTHROPIC_API_KEY` | Forwarded to the Anthropic client           |
+
+Get your key at [weckr.dev](https://weckr.dev).
+
+## License
+
+MIT

weckr_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "weckr-sdk"
+version = "0.1.0"
+description = "AI cost and margin intelligence for SaaS founders"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+authors = [
+    { name = "Weckr" }
+]
+keywords = ["ai", "llm", "openai", "anthropic", "gemini", "cost", "monitoring", "saas", "finops"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT 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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+openai = ["openai>=1.0.0"]
+anthropic = ["anthropic>=0.20.0"]
+gemini = ["google-generativeai>=0.5.0"]
+all = ["openai>=1.0.0", "anthropic>=0.20.0", "google-generativeai>=0.5.0"]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://useweckr.com"
+Documentation = "https://useweckr.com/docs"
+Repository = "https://github.com/Ghiles3232/weckr"
+Issues = "https://github.com/Ghiles3232/weckr/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["weckr"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/weckr",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]

weckr_sdk-0.1.0/weckr/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from .client import Weckr
+from .errors import WeckrCapError, is_weckr_cap_error
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Weckr",
+    "WeckrCapError",
+    "is_weckr_cap_error",
+    "__version__",
+]

weckr_sdk-0.1.0/weckr/cap.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+"""Spend-cap check against /api/v1/check with a 60-second in-memory cache.
+
+The cache is keyed on (user_id, plan_name) per the spec — one entry per
+(user, plan) pair. Failures fail open: if the cap service is unreachable,
+returns CapCheckResult(allowed=True) so a broken service can never block
+legitimate LLM traffic.
+
+The real endpoint is GET /api/v1/check?userId=&planName=&model= with the
+x-api-key header. We send GET with query params, not POST with a body.
+"""
+
+import json
+import time
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Dict, Optional, Tuple
+
+DEFAULT_CHECK_ENDPOINT = "https://app.useweckr.com/api/v1/check"
+_CACHE_TTL_SECONDS = 60.0
+_CHECK_TIMEOUT_SECONDS = 3.0
+
+
+@dataclass
+class CapCheckResult:
+    """Decoded response from /api/v1/check.
+
+    `allowed=True` means the LLM call should proceed.
+    `allowed=False` plus `action='block'` means raise WeckrCapError.
+    `action='downgrade'` plus `alternative_model` means silently swap model.
+    """
+
+    allowed: bool = True
+    action: Optional[str] = None
+    alternative_model: Optional[str] = None
+    remaining_budget: Optional[float] = None
+    current_spend: Optional[float] = None
+    cap: Optional[float] = None
+
+
+# Module-level cache: (user_id, plan_name) -> (result, expires_at_ms)
+# Per-process. A new venv / serverless cold start resets it.
+_CACHE: Dict[Tuple[str, str], Tuple[CapCheckResult, float]] = {}
+
+
+def _cache_key(user_id: str, plan_name: str) -> Tuple[str, str]:
+    return (user_id, plan_name)
+
+
+def check_cap(
+    check_endpoint: str,
+    api_key: str,
+    user_id: str,
+    plan_name: str,
+    model: Optional[str] = None,
+    disable_cap_check: bool = False,
+) -> CapCheckResult:
+    """Return the cap status for this (user_id, plan_name).
+
+    Cached for 60 seconds per pair — at most one extra request per (user, plan)
+    per minute. Fails open on any error.
+    """
+    if disable_cap_check or not user_id or not plan_name:
+        return CapCheckResult(allowed=True)
+
+    key = _cache_key(user_id, plan_name)
+    now = time.time()
+    cached = _CACHE.get(key)
+    if cached is not None:
+        result, expires_at = cached
+        if now < expires_at:
+            return result
+
+    # GET with query params + x-api-key header.
+    query: Dict[str, str] = {"userId": user_id, "planName": plan_name}
+    if model:
+        query["model"] = model
+    url = f"{check_endpoint}?{urllib.parse.urlencode(query)}"
+
+    try:
+        req = urllib.request.Request(
+            url,
+            method="GET",
+            headers={"x-api-key": api_key},
+        )
+        with urllib.request.urlopen(req, timeout=_CHECK_TIMEOUT_SECONDS) as resp:
+            body = resp.read()
+            data = json.loads(body.decode("utf-8"))
+            result = CapCheckResult(
+                allowed=bool(data.get("allowed", True)),
+                action=data.get("action"),
+                alternative_model=data.get("alternativeModel"),
+                remaining_budget=data.get("remainingBudget"),
+                current_spend=data.get("currentSpend"),
+                cap=data.get("cap"),
+            )
+    except Exception:
+        # Fail open — never block the user's app on our error.
+        result = CapCheckResult(allowed=True)
+
+    _CACHE[key] = (result, now + _CACHE_TTL_SECONDS)
+    return result
+
+
+__all__ = ["CapCheckResult", "check_cap", "DEFAULT_CHECK_ENDPOINT", "_CACHE"]

weckr_sdk-0.1.0/weckr/client.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+"""Main Weckr class. Mirrors the @weckr/sdk public interface for TypeScript:
+
+    wk = Weckr(api_key="wk_...", plans={"free": 0, "pro": 29})
+    result = wk.chat(openai, {
+        "model": "gpt-4o-mini",
+        "messages": [{"role": "user", "content": "Summarize this."}],
+        "user_id": user.id,
+        "feature": "ai-summary",
+        "plan": user.plan,
+    })
+
+user_id, feature, plan, and model live INSIDE the params dict — same shape
+as the TS SDK.
+"""
+
+import time
+import warnings
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Optional
+
+from .cap import check_cap
+from .errors import WeckrCapError
+from .logger import fire_and_forget_log
+from .normalize import detect_provider, normalize_usage
+from .pricing import calculate_cost
+
+DEFAULT_LOG_ENDPOINT = "https://app.useweckr.com/api/v1/log"
+DEFAULT_CHECK_ENDPOINT = "https://app.useweckr.com/api/v1/check"
+
+
+class Weckr:
+    def __init__(
+        self,
+        api_key: str,
+        plans: Optional[Dict[str, float]] = None,
+        endpoint: str = DEFAULT_LOG_ENDPOINT,
+        check_endpoint: str = DEFAULT_CHECK_ENDPOINT,
+        disable_cap_check: bool = False,
+        on_error: Optional[Callable[[Exception], None]] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("Weckr: api_key is required.")
+        self.api_key = api_key
+        self.plans: Dict[str, float] = plans or {}
+        self.endpoint = endpoint
+        self.check_endpoint = check_endpoint
+        self.disable_cap_check = disable_cap_check
+        self.on_error = on_error
+
+    def chat(self, client: Any, params: Dict[str, Any]) -> Any:
+        """Wrap any LLM client call. Returns the original result unchanged."""
+        # Shallow-copy so we never mutate the caller's dict.
+        params = dict(params)
+
+        user_id = params.pop("user_id", None)
+        feature = params.pop("feature", "unknown")
+        plan_name = params.pop("plan", None)
+        model = params.get("model", "unknown")
+        plan_revenue = float(self.plans.get(plan_name or "", 0))
+
+        # 1) Cap check before the LLM call (best-effort; fails open).
+        check = check_cap(
+            check_endpoint=self.check_endpoint,
+            api_key=self.api_key,
+            user_id=user_id or "",
+            plan_name=plan_name or "",
+            model=model,
+            disable_cap_check=self.disable_cap_check,
+        )
+        if not check.allowed:
+            if check.action == "block":
+                raise WeckrCapError(
+                    f"Weckr: spending cap reached for user {user_id}",
+                    user_id=user_id or "",
+                    plan_name=plan_name or "",
+                    current_spend=check.current_spend,
+                    cap=check.cap,
+                )
+            if check.action == "downgrade" and check.alternative_model:
+                warnings.warn(
+                    f"Weckr: downgraded {user_id} from {model} "
+                    f"to {check.alternative_model}",
+                    stacklevel=2,
+                )
+                params["model"] = check.alternative_model
+                model = check.alternative_model
+
+        # 2) Detect provider + call.
+        provider = detect_provider(client)
+        start = time.time()
+        result = self._call_provider(client, provider, params)
+        latency_ms = int((time.time() - start) * 1000)
+
+        # 3) Best-effort log. Never raises.
+        try:
+            input_tokens, output_tokens = normalize_usage(provider, result)
+            cost_usd = calculate_cost(model, input_tokens, output_tokens)
+            margin_usd = round(plan_revenue - cost_usd, 6)
+
+            payload: Dict[str, Any] = {
+                "userId": user_id,
+                "feature": feature,
+                "model": model,
+                "provider": provider,
+                "inputTokens": input_tokens,
+                "outputTokens": output_tokens,
+                "costUsd": cost_usd,
+                "latencyMs": latency_ms,
+                "planName": plan_name,
+                "planRevenueUsd": plan_revenue,
+                "marginUsd": margin_usd,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            }
+            fire_and_forget_log(
+                endpoint=self.endpoint,
+                api_key=self.api_key,
+                payload=payload,
+                on_error=self.on_error,
+            )
+        except Exception as err:  # never bubble logging failures
+            if self.on_error is not None:
+                try:
+                    self.on_error(err)
+                except Exception:
+                    pass
+
+        return result
+
+    def _call_provider(self, client: Any, provider: str, params: Dict[str, Any]) -> Any:
+        if provider == "openai":
+            return client.chat.completions.create(**params)
+        if provider == "anthropic":
+            return client.messages.create(**params)
+        if provider == "gemini":
+            model_name = params.get("model", "gemini-2.5-flash")
+            messages = params.get("messages", []) or []
+            prompt = " ".join(
+                m.get("content", "") if isinstance(m, dict) else str(m)
+                for m in messages
+                if isinstance(m, (dict, str))
+            )
+            gemini_model = client.GenerativeModel(model_name)
+            return gemini_model.generate_content(prompt)
+        raise ValueError(f"Unsupported provider: {provider}")
+
+
+__all__ = ["Weckr", "DEFAULT_LOG_ENDPOINT", "DEFAULT_CHECK_ENDPOINT"]

weckr_sdk-0.1.0/weckr/errors.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class WeckrCapError(Exception):
+    """Raised by `wk.chat(...)` when the configured spending cap has been hit
+    and the cap's action is `"block"`. The LLM call is never made.
+    """
+
+    name: str = "WeckrCapError"
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        *,
+        user_id: Optional[str] = None,
+        plan_name: Optional[str] = None,
+        current_spend: Optional[float] = None,
+        cap: Optional[float] = None,
+    ) -> None:
+        msg = message or (
+            f"Weckr: spending cap reached for user {user_id} on plan {plan_name}"
+        )
+        super().__init__(msg)
+        self.user_id = user_id
+        self.plan_name = plan_name
+        self.current_spend = current_spend
+        self.cap = cap
+
+
+def is_weckr_cap_error(e: object) -> bool:
+    """True when `e` is a `WeckrCapError` (matched by class or name)."""
+    if isinstance(e, WeckrCapError):
+        return True
+    return isinstance(e, BaseException) and getattr(e, "name", None) == "WeckrCapError"
+
+
+__all__ = ["WeckrCapError", "is_weckr_cap_error"]

weckr_sdk-0.1.0/weckr/logger.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+"""Fire-and-forget logging to the Weckr ingest endpoint.
+
+Uses urllib (stdlib) so the SDK has zero runtime dependencies. The POST runs
+on a daemon thread so it never blocks the caller's LLM hot path. All errors
+are swallowed silently unless an on_error callback is provided.
+"""
+
+import json
+import threading
+import urllib.request
+from typing import Any, Callable, Dict, Optional
+
+
+DEFAULT_LOG_ENDPOINT = "https://app.useweckr.com/api/v1/log"
+
+
+def fire_and_forget_log(
+    *,
+    endpoint: str,
+    api_key: str,
+    payload: Dict[str, Any],
+    timeout: float = 5.0,
+    on_error: Optional[Callable[[Exception], None]] = None,
+) -> None:
+    """POST `payload` to the Weckr ingest endpoint on a daemon thread.
+
+    Never raises — logging must never break the host application. If an
+    on_error callback is provided, it receives any exception (including a
+    synthesized Exception for non-2xx HTTP responses).
+    """
+
+    def _send() -> None:
+        try:
+            body = json.dumps(payload).encode("utf-8")
+            req = urllib.request.Request(
+                endpoint,
+                data=body,
+                method="POST",
+                headers={
+                    "Content-Type": "application/json",
+                    "x-api-key": api_key,
+                },
+            )
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                resp.read()
+                if resp.status >= 400 and on_error is not None:
+                    try:
+                        on_error(Exception(f"Weckr log failed: HTTP {resp.status}"))
+                    except Exception:
+                        pass
+        except Exception as err:
+            if on_error is not None:
+                try:
+                    on_error(err)
+                except Exception:
+                    pass
+
+    threading.Thread(target=_send, daemon=True).start()
+
+
+__all__ = ["fire_and_forget_log", "DEFAULT_LOG_ENDPOINT"]

weckr_sdk-0.1.0/weckr/normalize.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+"""Provider detection and usage normalization.
+
+`detect_provider(client)` returns one of: "openai", "anthropic", "gemini",
+"unknown" — based on the client's module path with a shape-based fallback.
+
+`normalize_usage(provider, result)` returns a `(input_tokens, output_tokens)`
+tuple. Missing or malformed fields collapse to 0.
+"""
+
+import math
+from typing import Any, Tuple
+
+
+def _to_int(v: Any) -> int:
+    try:
+        if v is None:
+            return 0
+        n = float(v)
+    except (TypeError, ValueError):
+        return 0
+    if not math.isfinite(n):
+        return 0
+    return max(0, int(n))
+
+
+def _get(obj: Any, key: str) -> Any:
+    if obj is None:
+        return None
+    if isinstance(obj, dict):
+        return obj.get(key)
+    return getattr(obj, key, None)
+
+
+def detect_provider(client: Any) -> str:
+    if client is None:
+        return "unknown"
+
+    module_name = ""
+    try:
+        module_name = (type(client).__module__ or "").lower()
+    except Exception:
+        module_name = ""
+
+    if "openai" in module_name:
+        return "openai"
+    if "anthropic" in module_name or "claude" in module_name:
+        return "anthropic"
+    if (
+        "google.genai" in module_name
+        or "google.generativeai" in module_name
+        or "genai" in module_name
+        or "gemini" in module_name
+    ):
+        return "gemini"
+
+    return "unknown"
+
+
+def normalize_usage(provider: str, result: Any) -> Tuple[int, int]:
+    """Return `(input_tokens, output_tokens)` from a provider response."""
+    if provider == "openai":
+        usage = _get(result, "usage")
+        prompt = _get(usage, "prompt_tokens")
+        if prompt is None:
+            prompt = _get(usage, "input_tokens")
+        completion = _get(usage, "completion_tokens")
+        if completion is None:
+            completion = _get(usage, "output_tokens")
+        return _to_int(prompt), _to_int(completion)
+
+    if provider == "anthropic":
+        usage = _get(result, "usage")
+        return _to_int(_get(usage, "input_tokens")), _to_int(_get(usage, "output_tokens"))
+
+    if provider == "gemini":
+        meta = _get(result, "usage_metadata")
+        if meta is None:
+            meta = _get(result, "usageMetadata")
+        prompt = _get(meta, "prompt_token_count")
+        if prompt is None:
+            prompt = _get(meta, "promptTokenCount")
+        completion = _get(meta, "candidates_token_count")
+        if completion is None:
+            completion = _get(meta, "candidatesTokenCount")
+        return _to_int(prompt), _to_int(completion)
+
+    return 0, 0
+
+
+__all__ = ["detect_provider", "normalize_usage"]

weckr_sdk-0.1.0/weckr/pricing.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+"""Per-million-token pricing + cheaper-alternative mapping.
+
+`calculate_cost(model, input_tokens, output_tokens)` returns USD cost as a
+float. Unknown models return 0.0 — server-side recalculation in
+/api/v1/log catches the difference if it matters, and the SDK never crashes
+the host app over a missing pricing row.
+"""
+
+from typing import Dict, TypedDict
+
+
+class ModelPricing(TypedDict):
+    input: float
+    output: float
+
+
+# Per-million-token pricing for supported models. Same numbers as the
+# TypeScript SDK + the backend's weckr-api/lib/caps.ts PRICING.
+PRICING: Dict[str, ModelPricing] = {
+    # OpenAI
+    "gpt-4o":           {"input": 2.50,  "output": 10.00},
+    "gpt-4o-mini":      {"input": 0.15,  "output": 0.60},
+    "gpt-4-turbo":      {"input": 2.50,  "output": 10.00},
+    "gpt-3.5-turbo":    {"input": 0.50,  "output": 1.50},
+    # Anthropic
+    "claude-opus-4":    {"input": 15.00, "output": 75.00},
+    "claude-sonnet-4":  {"input": 3.00,  "output": 15.00},
+    "claude-haiku-4-5": {"input": 0.80,  "output": 4.00},
+    # Gemini
+    "gemini-2.5-pro":   {"input": 1.25,  "output": 10.00},
+    "gemini-2.5-flash": {"input": 0.15,  "output": 0.60},
+}
+
+
+# Cheaper alternative per model — used when a cap's action is "downgrade".
+# Same-provider only; never silently switch a customer to a different vendor.
+CHEAPER_ALTERNATIVE: Dict[str, str] = {
+    # OpenAI
+    "gpt-4o":          "gpt-4o-mini",
+    "gpt-4-turbo":     "gpt-4o-mini",
+    "gpt-4":           "gpt-4o-mini",
+    # Anthropic
+    "claude-opus-4":   "claude-sonnet-4",
+    "claude-sonnet-4": "claude-haiku-4-5",
+    # Gemini
+    "gemini-2.5-pro":  "gemini-2.5-flash",
+    "gemini-1.5-pro":  "gemini-2.5-flash",
+}
+
+
+def calculate_cost(model: str, input_tokens: int, output_tokens: int) -> float:
+    """Return USD cost for `model` given input/output token counts.
+
+    Unknown models return 0.0.
+    """
+    pricing = PRICING.get(model)
+    if pricing is None:
+        return 0.0
+    return (
+        input_tokens * pricing["input"] + output_tokens * pricing["output"]
+    ) / 1_000_000.0
+
+
+__all__ = ["ModelPricing", "PRICING", "CHEAPER_ALTERNATIVE", "calculate_cost"]

weckr_sdk-0.1.0/weckr/types.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+# Providers supported by the SDK
+Provider = Literal["openai", "anthropic", "gemini"]
+ProviderOrUnknown = Literal["openai", "anthropic", "gemini", "unknown"]
+
+# Cap action surfaced by /api/v1/check
+CapAction = Literal["block", "downgrade"]
+
+
+class Message(TypedDict, total=False):
+    role: str
+    content: str
+
+
+class NormalizedUsage(TypedDict):
+    inputTokens: int
+    outputTokens: int
+
+
+class CapCheckResult(TypedDict, total=False):
+    allowed: bool
+    action: CapAction
+    alternativeModel: str
+    remainingBudget: float
+    currentSpend: float
+    cap: float
+
+
+class LogPayload(TypedDict, total=False):
+    userId: Optional[str]
+    feature: Optional[str]
+    model: str
+    provider: str
+    inputTokens: int
+    outputTokens: int
+    costUsd: float
+    latencyMs: int
+    planName: Optional[str]
+    planRevenueUsd: Optional[float]
+    marginUsd: Optional[float]
+    timestamp: str
+
+
+@dataclass
+class WeckrConfig:
+    """Runtime configuration for a Weckr client."""
+
+    api_key: str
+    plans: Dict[str, float] = field(default_factory=dict)
+    endpoint: str = "https://www.weckr.dev/api/v1/log"
+    check_endpoint: Optional[str] = None
+    disable_cap_check: bool = False
+    on_error: Optional[Any] = None  # Callable[[BaseException], None]
+
+
+@dataclass
+class ChatOptions:
+    """Normalized chat-call options. Provider-specific kwargs land in `extra`."""
+
+    model: str
+    messages: List[Dict[str, Any]] = field(default_factory=list)
+    user_id: Optional[str] = None
+    feature: Optional[str] = None
+    plan: Optional[str] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+
+__all__ = [
+    "Provider",
+    "ProviderOrUnknown",
+    "CapAction",
+    "Message",
+    "NormalizedUsage",
+    "CapCheckResult",
+    "LogPayload",
+    "WeckrConfig",
+    "ChatOptions",
+]