tessera-llm-proxy 0.1.0__tar.gz

tessera_llm_proxy-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+dist/
+build/

tessera_llm_proxy-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: tessera-llm-proxy
+Version: 0.1.0
+Summary: Tessera SDK — drop-in LLM cost optimization. One line patches OpenAI, Anthropic, Mistral, Groq, Cohere clients to route through Tessera's auto-route + auto-cache + auto-compress + auto-batch proxy. Free tier: 60M tokens/mo. Production: 20% of measured savings, $0 if none.
+Project-URL: Homepage, https://tesseraai.io
+Project-URL: Documentation, https://tesseraai.io/dev
+Project-URL: Repository, https://github.com/tessera-llm/sdk
+Project-URL: Issues, https://github.com/tessera-llm/sdk/issues
+Project-URL: Changelog, https://github.com/tessera-llm/sdk/releases
+Author-email: "Tessera (Fintechagency OÜ)" <contact@tesseraai.io>
+License: Apache-2.0
+Keywords: ai-cost,ai-proxy,anthropic,claude,cohere,cost-optimization,gemini,gpt-4o,groq,llm,llm-cost,llm-proxy,mistral,observability,openai,tessera
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pytest-mock>=3.0; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# tessera-llm-proxy
+
+[![PyPI version](https://img.shields.io/pypi/v/tessera-llm-proxy.svg)](https://pypi.org/project/tessera-llm-proxy/)
+[![Python](https://img.shields.io/pypi/pyversions/tessera-llm-proxy.svg)](https://pypi.org/project/tessera-llm-proxy/)
+
+**Drop-in cost optimization for LLM applications.** One line of code patches your existing OpenAI / Anthropic / Mistral / DeepSeek / Groq / Together / Fireworks / OpenRouter / Perplexity / Cerebras / xAI client to route through Tessera's measurement + auto-optimize proxy. You keep your provider account and keys; we route + cache + compress and measure savings on every request.
+
+> Free Dev tier: **60M tokens / month · no card required · no fee until you upgrade.** Get your free key at [tesseraai.io/dev](https://tesseraai.io/dev).
+
+## Get a free API key
+
+→ **[Get free key](https://ledger.tesseraai.io/signup-dev)** (email + ToS, 30 seconds, no card)
+
+After signup you get:
+- Your `tk_` API key (shown once)
+- A magic-link for the [dashboard](https://ledger.tesseraai.io/portal) — see your token counter + savings counter live
+- 60M tokens/month at 10 req/min — generous for hobby + side projects
+
+## Install
+
+```bash
+pip install tessera-llm-proxy
+```
+
+## One-line setup
+
+Drop this at the top of your application's entry point (`main.py`, `app.py`, `manage.py`, wherever your app boots):
+
+```python
+import tessera
+tessera.activate("tk_your_tessera_key")
+```
+
+That's it. Your existing code runs unchanged — `openai.OpenAI()`, `anthropic.Anthropic()`, `mistralai.Mistral()`, and other supported SDK constructors are transparently patched to route through Tessera. Your provider keys (OpenAI `sk-...`, Anthropic `sk-ant-...`, etc.) stay in your environment as before; Tessera forwards them upstream untouched.
+
+### Environment variable form
+
+If you'd rather not put the key in code:
+
+```bash
+export TESSERA_KEY=tk_your_tessera_key
+```
+
+```python
+import tessera
+tessera.activate()  # reads TESSERA_KEY from environment
+```
+
+## What gets patched
+
+Calling `tessera.activate(...)` patches the following SDKs at import time (each is opt-in: only patched if the library is installed):
+
+| SDK | Tessera route |
+| --- | --- |
+| `openai` (≥1.0) | `https://api.tesseraai.io/v1/openai` |
+| `anthropic` | `https://api.tesseraai.io/v1/anthropic` |
+| `mistralai` | `https://api.tesseraai.io/v1/mistral` |
+| `cohere` | `https://api.tesseraai.io/v1/cohere` *(Wave 2)* |
+| `groq` | `https://api.tesseraai.io/v1/groq` |
+
+If you use a framework that wraps these SDKs (LangChain, LlamaIndex, CrewAI, AutoGen, Mastra, Pydantic AI, etc.), the patch applies transparently because those frameworks call the underlying SDK constructors which are what we patched.
+
+## Direct provider URLs
+
+If you call providers that aren't covered by an official Python SDK (DeepSeek, Together, Fireworks, OpenRouter, Perplexity, Cerebras, xAI), construct an `openai.OpenAI` client manually with the matching Tessera URL:
+
+```python
+from openai import OpenAI
+
+# DeepSeek via Tessera
+client = OpenAI(
+    api_key="sk-deepseek-...",
+    base_url=tessera.url("deepseek"),  # → https://api.tesseraai.io/v1/deepseek
+    default_headers=tessera.headers(),
+)
+
+# Same pattern for: together, fireworks, openrouter, perplexity, cerebras, groq, xai
+```
+
+`tessera.url(provider)` and `tessera.headers()` are pure helpers — no globals, no patching. Use them when you want explicit, traceable wiring.
+
+## Verification
+
+```python
+import tessera
+tessera.activate("tk_...")
+
+assert tessera.is_active(), "Tessera should be active after activate()"
+print(tessera.status())  # → ProxyStatus(active=True, providers_patched=['openai', 'anthropic'], proxy_base='https://api.tesseraai.io/v1')
+```
+
+## Deactivation
+
+To restore the original SDK constructors (e.g. in test teardown):
+
+```python
+tessera.deactivate()
+```
+
+## Configuration
+
+```python
+tessera.activate(
+    key="tk_...",                              # or TESSERA_KEY env var
+    proxy_base="https://api.tesseraai.io/v1",  # default; override for staging/dev
+    feature_tag="checkout-summarizer",         # attaches to every request for per-feature attribution
+)
+```
+
+`feature_tag` lets you split savings reporting per workload (e.g. one tag per logical feature in your app). You can also set per-request tags by passing `extra_body={"tessera_feature_tag": "..."}` on individual SDK calls.
+
+## How the pricing works
+
+- **Free Sandbox tier:** 60M tokens/month, no card required, $0 fee.
+- **Production tier:** **20%** of measured savings, debited daily from a prepaid balance you control ($100 minimum top-up via Stripe).
+- **Zero savings = zero fee.** If our optimization doesn't save you anything in a period, you pay nothing for that period.
+- **Kill-switch** available anytime from your portal — pauses optimization, traffic still flows passthrough.
+
+Full terms: <https://tesseraai.io/terms>
+
+## License
+
+Apache-2.0

tessera_llm_proxy-0.1.0/README.md

@@ -0,0 +1,123 @@
+# tessera-llm-proxy
+
+[![PyPI version](https://img.shields.io/pypi/v/tessera-llm-proxy.svg)](https://pypi.org/project/tessera-llm-proxy/)
+[![Python](https://img.shields.io/pypi/pyversions/tessera-llm-proxy.svg)](https://pypi.org/project/tessera-llm-proxy/)
+
+**Drop-in cost optimization for LLM applications.** One line of code patches your existing OpenAI / Anthropic / Mistral / DeepSeek / Groq / Together / Fireworks / OpenRouter / Perplexity / Cerebras / xAI client to route through Tessera's measurement + auto-optimize proxy. You keep your provider account and keys; we route + cache + compress and measure savings on every request.
+
+> Free Dev tier: **60M tokens / month · no card required · no fee until you upgrade.** Get your free key at [tesseraai.io/dev](https://tesseraai.io/dev).
+
+## Get a free API key
+
+→ **[Get free key](https://ledger.tesseraai.io/signup-dev)** (email + ToS, 30 seconds, no card)
+
+After signup you get:
+- Your `tk_` API key (shown once)
+- A magic-link for the [dashboard](https://ledger.tesseraai.io/portal) — see your token counter + savings counter live
+- 60M tokens/month at 10 req/min — generous for hobby + side projects
+
+## Install
+
+```bash
+pip install tessera-llm-proxy
+```
+
+## One-line setup
+
+Drop this at the top of your application's entry point (`main.py`, `app.py`, `manage.py`, wherever your app boots):
+
+```python
+import tessera
+tessera.activate("tk_your_tessera_key")
+```
+
+That's it. Your existing code runs unchanged — `openai.OpenAI()`, `anthropic.Anthropic()`, `mistralai.Mistral()`, and other supported SDK constructors are transparently patched to route through Tessera. Your provider keys (OpenAI `sk-...`, Anthropic `sk-ant-...`, etc.) stay in your environment as before; Tessera forwards them upstream untouched.
+
+### Environment variable form
+
+If you'd rather not put the key in code:
+
+```bash
+export TESSERA_KEY=tk_your_tessera_key
+```
+
+```python
+import tessera
+tessera.activate()  # reads TESSERA_KEY from environment
+```
+
+## What gets patched
+
+Calling `tessera.activate(...)` patches the following SDKs at import time (each is opt-in: only patched if the library is installed):
+
+| SDK | Tessera route |
+| --- | --- |
+| `openai` (≥1.0) | `https://api.tesseraai.io/v1/openai` |
+| `anthropic` | `https://api.tesseraai.io/v1/anthropic` |
+| `mistralai` | `https://api.tesseraai.io/v1/mistral` |
+| `cohere` | `https://api.tesseraai.io/v1/cohere` *(Wave 2)* |
+| `groq` | `https://api.tesseraai.io/v1/groq` |
+
+If you use a framework that wraps these SDKs (LangChain, LlamaIndex, CrewAI, AutoGen, Mastra, Pydantic AI, etc.), the patch applies transparently because those frameworks call the underlying SDK constructors which are what we patched.
+
+## Direct provider URLs
+
+If you call providers that aren't covered by an official Python SDK (DeepSeek, Together, Fireworks, OpenRouter, Perplexity, Cerebras, xAI), construct an `openai.OpenAI` client manually with the matching Tessera URL:
+
+```python
+from openai import OpenAI
+
+# DeepSeek via Tessera
+client = OpenAI(
+    api_key="sk-deepseek-...",
+    base_url=tessera.url("deepseek"),  # → https://api.tesseraai.io/v1/deepseek
+    default_headers=tessera.headers(),
+)
+
+# Same pattern for: together, fireworks, openrouter, perplexity, cerebras, groq, xai
+```
+
+`tessera.url(provider)` and `tessera.headers()` are pure helpers — no globals, no patching. Use them when you want explicit, traceable wiring.
+
+## Verification
+
+```python
+import tessera
+tessera.activate("tk_...")
+
+assert tessera.is_active(), "Tessera should be active after activate()"
+print(tessera.status())  # → ProxyStatus(active=True, providers_patched=['openai', 'anthropic'], proxy_base='https://api.tesseraai.io/v1')
+```
+
+## Deactivation
+
+To restore the original SDK constructors (e.g. in test teardown):
+
+```python
+tessera.deactivate()
+```
+
+## Configuration
+
+```python
+tessera.activate(
+    key="tk_...",                              # or TESSERA_KEY env var
+    proxy_base="https://api.tesseraai.io/v1",  # default; override for staging/dev
+    feature_tag="checkout-summarizer",         # attaches to every request for per-feature attribution
+)
+```
+
+`feature_tag` lets you split savings reporting per workload (e.g. one tag per logical feature in your app). You can also set per-request tags by passing `extra_body={"tessera_feature_tag": "..."}` on individual SDK calls.
+
+## How the pricing works
+
+- **Free Sandbox tier:** 60M tokens/month, no card required, $0 fee.
+- **Production tier:** **20%** of measured savings, debited daily from a prepaid balance you control ($100 minimum top-up via Stripe).
+- **Zero savings = zero fee.** If our optimization doesn't save you anything in a period, you pay nothing for that period.
+- **Kill-switch** available anytime from your portal — pauses optimization, traffic still flows passthrough.
+
+Full terms: <https://tesseraai.io/terms>
+
+## License
+
+Apache-2.0

tessera_llm_proxy-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tessera-llm-proxy"
+version = "0.1.0"
+description = "Tessera SDK — drop-in LLM cost optimization. One line patches OpenAI, Anthropic, Mistral, Groq, Cohere clients to route through Tessera's auto-route + auto-cache + auto-compress + auto-batch proxy. Free tier: 60M tokens/mo. Production: 20% of measured savings, $0 if none."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [
+  { name = "Tessera (Fintechagency OÜ)", email = "contact@tesseraai.io" }
+]
+keywords = [
+  "tessera",
+  "llm",
+  "openai",
+  "anthropic",
+  "mistral",
+  "groq",
+  "cohere",
+  "cost-optimization",
+  "ai-cost",
+  "llm-cost",
+  "ai-proxy",
+  "llm-proxy",
+  "observability",
+  "gpt-4o",
+  "claude",
+  "gemini",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "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",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = [
+  "pytest>=7.0",
+  "pytest-mock>=3.0",
+]
+
+[project.urls]
+Homepage = "https://tesseraai.io"
+Documentation = "https://tesseraai.io/dev"
+Repository = "https://github.com/tessera-llm/sdk"
+Issues = "https://github.com/tessera-llm/sdk/issues"
+Changelog = "https://github.com/tessera-llm/sdk/releases"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tessera"]

tessera_llm_proxy-0.1.0/tessera/__init__.py

@@ -0,0 +1,47 @@
+"""Tessera Optimize Layer — drop-in cost optimization for LLM SDKs.
+
+One line of code patches OpenAI / Anthropic / Mistral / Groq / Cohere client
+constructors so requests route through Tessera's measurement + auto-optimize
+proxy. Your existing application code runs unchanged.
+
+Typical use::
+
+    import tessera
+    tessera.activate("tk_your_tessera_key")
+
+    # Now any existing OpenAI/Anthropic/etc client created in this Python
+    # process will transparently forward through Tessera. No further code
+    # changes required.
+
+For SDKs we don't auto-patch (DeepSeek/Together/Fireworks/OpenRouter/etc),
+use ``tessera.url(provider)`` + ``tessera.headers()`` to wire an
+``openai.OpenAI`` client manually.
+
+Locked 2026-05-17 — γ-mode integration per founder direction
+("Cloudflare-стиль: дай ключ, остальное мы делаем").
+"""
+
+from __future__ import annotations
+
+from .core import (
+    ProxyStatus,
+    activate,
+    deactivate,
+    headers,
+    is_active,
+    status,
+    url,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "activate",
+    "deactivate",
+    "headers",
+    "is_active",
+    "ProxyStatus",
+    "status",
+    "url",
+    "__version__",
+]

tessera_llm_proxy-0.1.0/tessera/core.py

@@ -0,0 +1,322 @@
+"""Tessera SDK core — global activation + per-provider patchers.
+
+`activate()` walks a registry of provider-specific patchers. Each patcher is
+opt-in: only fires if the corresponding SDK is importable. So a Python process
+that has only `openai` installed will see `openai` patched and `anthropic`
+silently skipped.
+
+Patchers wrap the SDK's primary client constructor(s). After the wrap, every
+new client instance created in the process has its `base_url` pointed at the
+Tessera proxy + `X-Tessera-Key` injected into default headers, while the
+caller's existing provider key (e.g. `sk-...`) stays untouched and flows
+upstream as before.
+
+This is intentionally a **global side-effect** per founder direction — same
+shape as `cloudflare.activate()` or `sentry.init()`. Reversal via
+`deactivate()` for test teardown.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import importlib
+import logging
+import os
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+logger = logging.getLogger("tessera")
+
+DEFAULT_PROXY_BASE = "https://api.tesseraai.io/v1"
+
+_state: Dict[str, Any] = {
+    "active": False,
+    "key": None,
+    "proxy_base": DEFAULT_PROXY_BASE,
+    "feature_tag": None,
+    "patched": [],  # list of (provider_name, restore_callable)
+}
+
+
+@dataclasses.dataclass
+class ProxyStatus:
+    """Current state of the Tessera SDK patch."""
+
+    active: bool
+    providers_patched: List[str]
+    proxy_base: str
+    feature_tag: Optional[str]
+
+
+def url(provider: str) -> str:
+    """Return the Tessera proxy URL for ``provider``.
+
+    Pure helper — no globals required. Use when wiring an SDK client manually
+    (e.g. for providers without an official Python SDK such as DeepSeek,
+    Together, Fireworks, OpenRouter, Perplexity, Cerebras, xAI).
+    """
+    base = _state.get("proxy_base") or DEFAULT_PROXY_BASE
+    return f"{base.rstrip('/')}/{provider.strip('/')}"
+
+
+def headers(key: Optional[str] = None) -> Dict[str, str]:
+    """Return the headers required to authenticate against Tessera.
+
+    Reads the activated key by default; pass ``key`` explicitly to override.
+    Use alongside :func:`url` for manual SDK wiring.
+    """
+    resolved_key = key or _state.get("key") or os.environ.get("TESSERA_KEY")
+    if not resolved_key:
+        raise RuntimeError(
+            "Tessera key not set. Call `tessera.activate('tk_...')` first or "
+            "pass key= to tessera.headers()."
+        )
+    result = {"X-Tessera-Key": resolved_key}
+    tag = _state.get("feature_tag")
+    if tag:
+        result["X-Tessera-Feature-Tag"] = tag
+    return result
+
+
+def is_active() -> bool:
+    """True if :func:`activate` has been called and patches are installed."""
+    return bool(_state.get("active"))
+
+
+def status() -> ProxyStatus:
+    """Snapshot the current SDK state — useful in health checks + logging."""
+    return ProxyStatus(
+        active=bool(_state.get("active")),
+        providers_patched=[name for name, _ in _state.get("patched", [])],
+        proxy_base=_state.get("proxy_base") or DEFAULT_PROXY_BASE,
+        feature_tag=_state.get("feature_tag"),
+    )
+
+
+def activate(
+    key: Optional[str] = None,
+    *,
+    proxy_base: Optional[str] = None,
+    feature_tag: Optional[str] = None,
+) -> ProxyStatus:
+    """Install Tessera patches globally.
+
+    :param key: Tessera API key (``tk_...``). Falls back to ``TESSERA_KEY``
+        environment variable when omitted.
+    :param proxy_base: Override the proxy origin. Default
+        ``https://api.tesseraai.io/v1``. Used by Tessera staff for staging.
+    :param feature_tag: Attach a default ``X-Tessera-Feature-Tag`` header to
+        every patched request — useful for per-workload attribution.
+    :returns: :class:`ProxyStatus` with the current state.
+    :raises RuntimeError: If no key is provided either argument-side or via
+        the environment variable.
+    """
+    resolved_key = key or os.environ.get("TESSERA_KEY")
+    if not resolved_key:
+        raise RuntimeError(
+            "Tessera key not provided. Pass key= to tessera.activate() or set "
+            "TESSERA_KEY environment variable."
+        )
+
+    if _state["active"]:
+        # Re-activating with new args: deactivate first so we can re-patch with
+        # the new state cleanly.
+        deactivate()
+
+    _state["key"] = resolved_key
+    _state["proxy_base"] = (proxy_base or DEFAULT_PROXY_BASE).rstrip("/")
+    _state["feature_tag"] = feature_tag
+    _state["active"] = True
+    _state["patched"] = []
+
+    for patcher in _PATCHERS:
+        try:
+            restore = patcher()
+            if restore is not None:
+                _state["patched"].append((patcher.__name__.replace("_patch_", ""), restore))
+        except Exception as err:  # noqa: BLE001 — best-effort patching
+            logger.warning(
+                "tessera: failed to patch %s: %s",
+                patcher.__name__,
+                err,
+            )
+
+    return status()
+
+
+def deactivate() -> None:
+    """Reverse all patches installed by :func:`activate`.
+
+    SDK constructors are restored to their original values. Safe to call when
+    Tessera is not active — becomes a no-op.
+    """
+    for _provider, restore in reversed(_state.get("patched", [])):
+        try:
+            restore()
+        except Exception as err:  # noqa: BLE001
+            logger.warning("tessera: failed to restore patch: %s", err)
+    _state["active"] = False
+    _state["patched"] = []
+    _state["key"] = None
+    _state["feature_tag"] = None
+
+
+# ─── per-provider patchers ──────────────────────────────────────────────────
+
+
+def _safe_import(module_name: str):
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+def _wrap_constructor(
+    cls: type,
+    *,
+    base_url_attr: str = "base_url",
+    headers_attr: str = "default_headers",
+    proxy_path: str,
+) -> Callable[[], None]:
+    """Wrap ``cls.__init__`` so newly-constructed instances route via Tessera.
+
+    Returns a restore callable that undoes the wrap.
+    """
+    original_init = cls.__init__
+    proxy_url = url(proxy_path)
+
+    def patched_init(self: Any, *args: Any, **kwargs: Any) -> None:
+        # Don't override an explicit base_url override — caller wins.
+        if base_url_attr not in kwargs:
+            kwargs[base_url_attr] = proxy_url
+        # Merge default headers — preserve any caller-provided headers.
+        merged_headers: Dict[str, str] = dict(kwargs.get(headers_attr) or {})
+        for header_key, header_value in headers().items():
+            merged_headers.setdefault(header_key, header_value)
+        kwargs[headers_attr] = merged_headers
+        original_init(self, *args, **kwargs)
+
+    cls.__init__ = patched_init  # type: ignore[method-assign]
+
+    def restore() -> None:
+        cls.__init__ = original_init  # type: ignore[method-assign]
+
+    return restore
+
+
+def _patch_openai() -> Optional[Callable[[], None]]:
+    mod = _safe_import("openai")
+    if mod is None:
+        return None
+    restorers: List[Callable[[], None]] = []
+    for class_name in ("OpenAI", "AsyncOpenAI"):
+        cls = getattr(mod, class_name, None)
+        if cls is None:
+            continue
+        restorers.append(
+            _wrap_constructor(cls, proxy_path="openai")
+        )
+
+    def restore_all() -> None:
+        for r in restorers:
+            r()
+
+    return restore_all if restorers else None
+
+
+def _patch_anthropic() -> Optional[Callable[[], None]]:
+    mod = _safe_import("anthropic")
+    if mod is None:
+        return None
+    restorers: List[Callable[[], None]] = []
+    for class_name in ("Anthropic", "AsyncAnthropic"):
+        cls = getattr(mod, class_name, None)
+        if cls is None:
+            continue
+        restorers.append(
+            _wrap_constructor(cls, proxy_path="anthropic")
+        )
+
+    def restore_all() -> None:
+        for r in restorers:
+            r()
+
+    return restore_all if restorers else None
+
+
+def _patch_mistral() -> Optional[Callable[[], None]]:
+    # Newer Mistral SDK (>=1.0) exposes class `Mistral`; legacy uses
+    # `MistralClient`. Patch whichever is present.
+    mod = _safe_import("mistralai")
+    if mod is None:
+        return None
+    restorers: List[Callable[[], None]] = []
+    for class_name in ("Mistral", "MistralClient", "AsyncMistral"):
+        cls = getattr(mod, class_name, None)
+        if cls is None:
+            continue
+        # Mistral SDK uses `server_url` rather than `base_url`
+        restorers.append(
+            _wrap_constructor(
+                cls,
+                base_url_attr="server_url",
+                headers_attr="default_headers",
+                proxy_path="mistral",
+            )
+        )
+
+    def restore_all() -> None:
+        for r in restorers:
+            r()
+
+    return restore_all if restorers else None
+
+
+def _patch_groq() -> Optional[Callable[[], None]]:
+    mod = _safe_import("groq")
+    if mod is None:
+        return None
+    restorers: List[Callable[[], None]] = []
+    for class_name in ("Groq", "AsyncGroq"):
+        cls = getattr(mod, class_name, None)
+        if cls is None:
+            continue
+        restorers.append(
+            _wrap_constructor(cls, proxy_path="groq")
+        )
+
+    def restore_all() -> None:
+        for r in restorers:
+            r()
+
+    return restore_all if restorers else None
+
+
+def _patch_cohere() -> Optional[Callable[[], None]]:
+    mod = _safe_import("cohere")
+    if mod is None:
+        return None
+    restorers: List[Callable[[], None]] = []
+    # Cohere v5+ SDK class names — patch whichever exist.
+    for class_name in ("Client", "ClientV2", "AsyncClient", "AsyncClientV2"):
+        cls = getattr(mod, class_name, None)
+        if cls is None:
+            continue
+        # Cohere uses `base_url` keyword
+        restorers.append(
+            _wrap_constructor(cls, proxy_path="cohere")
+        )
+
+    def restore_all() -> None:
+        for r in restorers:
+            r()
+
+    return restore_all if restorers else None
+
+
+_PATCHERS: Tuple[Callable[[], Optional[Callable[[], None]]], ...] = (
+    _patch_openai,
+    _patch_anthropic,
+    _patch_mistral,
+    _patch_groq,
+    _patch_cohere,
+)

tessera_llm_proxy-0.1.0/tests/test_core.py

@@ -0,0 +1,214 @@
+"""Tessera SDK core tests — unit-level (no network).
+
+We don't have OpenAI/Anthropic installed in the test environment necessarily,
+so tests focus on the pure helpers (url, headers, status, activate/deactivate
+lifecycle) and use a stub class to verify the wrap behaviour without depending
+on a specific provider SDK being importable.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import types
+
+import pytest
+
+import tessera
+from tessera import core as tessera_core
+
+
+@pytest.fixture(autouse=True)
+def reset_state():
+    """Ensure each test starts fresh."""
+    tessera_core.deactivate()
+    yield
+    tessera_core.deactivate()
+
+
+def test_default_proxy_base():
+    assert tessera_core.DEFAULT_PROXY_BASE == "https://api.tesseraai.io/v1"
+
+
+def test_url_helper():
+    assert tessera.url("openai") == "https://api.tesseraai.io/v1/openai"
+    assert tessera.url("anthropic") == "https://api.tesseraai.io/v1/anthropic"
+    assert tessera.url("deepseek") == "https://api.tesseraai.io/v1/deepseek"
+
+
+def test_url_helper_with_leading_slash():
+    assert tessera.url("/openai") == "https://api.tesseraai.io/v1/openai"
+
+
+def test_headers_requires_key():
+    with pytest.raises(RuntimeError, match="Tessera key not set"):
+        tessera.headers()
+
+
+def test_headers_with_explicit_key():
+    result = tessera.headers(key="tk_test123")
+    assert result == {"X-Tessera-Key": "tk_test123"}
+
+
+def test_headers_reads_env_var(monkeypatch):
+    monkeypatch.setenv("TESSERA_KEY", "tk_env_key")
+    # Without activate, headers() falls back to env
+    result = tessera.headers()
+    assert result["X-Tessera-Key"] == "tk_env_key"
+
+
+def test_activate_requires_key():
+    with pytest.raises(RuntimeError, match="Tessera key not provided"):
+        tessera.activate()
+
+
+def test_activate_reads_env_var(monkeypatch):
+    monkeypatch.setenv("TESSERA_KEY", "tk_env_activate")
+    status = tessera.activate()
+    assert status.active is True
+    assert tessera.is_active() is True
+
+
+def test_activate_explicit_key():
+    status = tessera.activate("tk_explicit")
+    assert status.active is True
+    assert tessera.headers() == {"X-Tessera-Key": "tk_explicit"}
+
+
+def test_activate_feature_tag():
+    tessera.activate("tk_test", feature_tag="checkout-summarizer")
+    result = tessera.headers()
+    assert result["X-Tessera-Key"] == "tk_test"
+    assert result["X-Tessera-Feature-Tag"] == "checkout-summarizer"
+
+
+def test_activate_custom_proxy_base():
+    status = tessera.activate("tk_test", proxy_base="https://staging.tesseraai.io/v1")
+    assert status.proxy_base == "https://staging.tesseraai.io/v1"
+    assert tessera.url("openai") == "https://staging.tesseraai.io/v1/openai"
+
+
+def test_deactivate_is_safe_when_inactive():
+    # Should not raise.
+    tessera.deactivate()
+    assert tessera.is_active() is False
+
+
+def test_activate_then_deactivate_lifecycle():
+    tessera.activate("tk_test")
+    assert tessera.is_active() is True
+    tessera.deactivate()
+    assert tessera.is_active() is False
+    # headers() should now raise again
+    with pytest.raises(RuntimeError):
+        tessera.headers()
+
+
+def test_re_activate_replaces_key():
+    tessera.activate("tk_first")
+    assert tessera.headers()["X-Tessera-Key"] == "tk_first"
+    tessera.activate("tk_second")
+    assert tessera.headers()["X-Tessera-Key"] == "tk_second"
+
+
+def test_status_snapshot():
+    tessera.activate("tk_test", feature_tag="alpha")
+    s = tessera.status()
+    assert s.active is True
+    assert s.proxy_base == "https://api.tesseraai.io/v1"
+    assert s.feature_tag == "alpha"
+    # providers_patched may be empty in test env (no SDKs installed), or
+    # contain anything that happened to import — just assert shape.
+    assert isinstance(s.providers_patched, list)
+
+
+def test_wrap_constructor_injects_base_url_and_headers(monkeypatch):
+    """Drop a fake SDK module + class into sys.modules then verify the
+    patcher wraps it correctly. Proves the wrap mechanic without needing the
+    real openai package."""
+
+    captured = {}
+
+    class FakeClient:
+        def __init__(self, api_key=None, base_url=None, default_headers=None, **kwargs):
+            captured["api_key"] = api_key
+            captured["base_url"] = base_url
+            captured["default_headers"] = default_headers
+
+    fake_module = types.SimpleNamespace(OpenAI=FakeClient)
+    monkeypatch.setitem(sys.modules, "openai", fake_module)
+
+    tessera.activate("tk_wrap_test")
+
+    # Construct a FakeClient — wrap should inject base_url + Tessera key.
+    instance = FakeClient(api_key="sk-user")  # noqa: F841 — side-effect captures
+    assert captured["base_url"] == "https://api.tesseraai.io/v1/openai"
+    assert captured["default_headers"] == {"X-Tessera-Key": "tk_wrap_test"}
+    assert captured["api_key"] == "sk-user"
+
+
+def test_wrap_does_not_override_explicit_base_url(monkeypatch):
+    """If caller passes their own base_url, Tessera should NOT override it
+    (caller-wins principle for transparent migration)."""
+
+    captured = {}
+
+    class FakeClient:
+        def __init__(self, api_key=None, base_url=None, default_headers=None, **kwargs):
+            captured["base_url"] = base_url
+            captured["default_headers"] = default_headers
+
+    fake_module = types.SimpleNamespace(OpenAI=FakeClient)
+    monkeypatch.setitem(sys.modules, "openai", fake_module)
+
+    tessera.activate("tk_wrap_test")
+
+    FakeClient(api_key="sk-x", base_url="https://my-custom-proxy.example.com")
+    assert captured["base_url"] == "https://my-custom-proxy.example.com"
+
+
+def test_wrap_preserves_user_headers(monkeypatch):
+    """Caller-provided default_headers should merge with Tessera's, not be
+    overwritten. Tessera only adds X-Tessera-Key; caller-provided keys win
+    on conflict (setdefault semantics)."""
+
+    captured = {}
+
+    class FakeClient:
+        def __init__(self, api_key=None, base_url=None, default_headers=None, **kwargs):
+            captured["default_headers"] = default_headers
+
+    fake_module = types.SimpleNamespace(OpenAI=FakeClient)
+    monkeypatch.setitem(sys.modules, "openai", fake_module)
+
+    tessera.activate("tk_wrap_test")
+    FakeClient(api_key="sk-x", default_headers={"X-User-Trace": "abc123"})
+
+    headers = captured["default_headers"]
+    assert headers["X-User-Trace"] == "abc123"  # user header preserved
+    assert headers["X-Tessera-Key"] == "tk_wrap_test"  # Tessera injected
+
+
+def test_deactivate_restores_original_constructor(monkeypatch):
+    """After deactivate(), newly-created clients should NOT have Tessera
+    patches applied. Verifies the restore callable works end-to-end."""
+
+    captured = {}
+    init_calls = []
+
+    class FakeClient:
+        def __init__(self, api_key=None, base_url=None, default_headers=None, **kwargs):
+            init_calls.append("called")
+            captured["base_url"] = base_url
+
+    fake_module = types.SimpleNamespace(OpenAI=FakeClient)
+    monkeypatch.setitem(sys.modules, "openai", fake_module)
+
+    tessera.activate("tk_wrap_test")
+    FakeClient(api_key="sk-x")
+    assert captured["base_url"] == "https://api.tesseraai.io/v1/openai"
+
+    tessera.deactivate()
+    FakeClient(api_key="sk-x")  # should now use original __init__
+    assert captured["base_url"] is None  # no Tessera injection
+    assert len(init_calls) == 2