cli-modelarium 0.1.3__py3-none-any.whl

cli_modelarium/pricing.py

@@ -0,0 +1,199 @@
+"""Pricing data and cost calculation for all supported models.
+
+Pricing is per 1M tokens, in USD. Verified May 25, 2026 from each provider's
+official documentation. LLM pricing changes frequently - re-verify against
+the provider's pricing page before relying on these values for production
+budgeting.
+
+Schema per entry:
+    input         - cost per 1M input tokens (required)
+    output        - cost per 1M output tokens (required)
+    cached_input  - cost per 1M cached input tokens (optional; typically ~90% off)
+    provider      - provider name matching BaseProvider.name (required)
+    is_local      - True for local models (optional; always free)
+"""
+
+from __future__ import annotations
+
+from cli_modelarium.exceptions import UnknownModelError
+
+PRICING_AS_OF = "2026-05-25"
+
+PRICING: dict[str, dict[str, float | str | bool]] = {
+    # ===== OpenAI =====
+    "gpt-5.5": {"input": 5.00, "output": 30.00, "cached_input": 0.50, "provider": "openai"},
+    "gpt-5.5-pro": {"input": 30.00, "output": 180.00, "provider": "openai"},
+    "gpt-5.4": {"input": 2.50, "output": 15.00, "cached_input": 1.25, "provider": "openai"},
+    "gpt-5.4-mini": {"input": 0.75, "output": 4.50, "cached_input": 0.40, "provider": "openai"},
+    "gpt-5.4-nano": {"input": 0.20, "output": 1.25, "cached_input": 0.10, "provider": "openai"},
+    "gpt-5.4-pro": {"input": 15.00, "output": 60.00, "provider": "openai"},
+    "gpt-5.3-codex": {"input": 1.75, "output": 14.00, "provider": "openai"},
+    "gpt-5.3-codex-spark": {"input": 0.50, "output": 2.00, "provider": "openai"},
+    "o3": {"input": 15.00, "output": 60.00, "cached_input": 7.50, "provider": "openai"},
+    "o3-pro": {"input": 30.00, "output": 120.00, "provider": "openai"},
+    "o4-mini": {"input": 1.10, "output": 4.40, "cached_input": 0.55, "provider": "openai"},
+    "gpt-oss-120b": {"input": 0.30, "output": 0.60, "provider": "openai"},
+    "gpt-oss-20b": {"input": 0.10, "output": 0.30, "provider": "openai"},
+    "gpt-5": {"input": 1.25, "output": 10.00, "provider": "openai"},
+    "gpt-4.1-mini": {"input": 0.40, "output": 1.60, "provider": "openai"},
+    "gpt-4o": {"input": 2.50, "output": 10.00, "provider": "openai"},
+    "gpt-4o-mini": {"input": 0.15, "output": 0.60, "provider": "openai"},
+    # ===== Anthropic =====
+    # Verified against Anthropic's pricing page May 25, 2026.
+    "claude-opus-4-7": {
+        "input": 5.00,
+        "output": 25.00,
+        "cached_input": 0.50,
+        "provider": "anthropic",
+    },
+    "claude-sonnet-4-6": {
+        "input": 3.00,
+        "output": 15.00,
+        "cached_input": 0.30,
+        "provider": "anthropic",
+    },
+    "claude-haiku-4-5": {
+        "input": 1.00,
+        "output": 5.00,
+        "cached_input": 0.10,
+        "provider": "anthropic",
+    },
+    "claude-opus-4-6": {
+        "input": 5.00,
+        "output": 25.00,
+        "cached_input": 0.50,
+        "provider": "anthropic",
+    },
+    # ===== Google Gemini (Google uses dots in model IDs) =====
+    "gemini-3.5-flash": {"input": 0.50, "output": 3.00, "provider": "google"},
+    "gemini-3.1-pro": {"input": 1.25, "output": 5.00, "cached_input": 0.625, "provider": "google"},
+    "gemini-3.1-flash-lite": {"input": 0.10, "output": 0.40, "provider": "google"},
+    "gemini-3-flash": {"input": 0.30, "output": 2.50, "provider": "google"},
+    "gemini-2.5-flash": {"input": 0.30, "output": 2.50, "provider": "google"},
+    "gemini-2.5-flash-lite": {"input": 0.10, "output": 0.40, "provider": "google"},
+    # ===== xAI Grok (xAI uses dots in model IDs) =====
+    "grok-4.3": {"input": 1.25, "output": 2.50, "cached_input": 0.20, "provider": "xai"},
+    "grok-4.20": {"input": 2.00, "output": 6.00, "cached_input": 0.20, "provider": "xai"},
+    "grok-4.20-multi-agent-beta": {
+        "input": 2.00,
+        "output": 6.00,
+        "cached_input": 0.20,
+        "provider": "xai",
+    },
+    "grok-4.1-fast": {"input": 0.20, "output": 0.50, "cached_input": 0.05, "provider": "xai"},
+    "grok-build-0.1": {"input": 1.00, "output": 2.00, "cached_input": 0.20, "provider": "xai"},
+    # ===== DeepSeek =====
+    "deepseek-v4-pro": {
+        "input": 0.55,
+        "output": 2.19,
+        "cached_input": 0.055,
+        "provider": "deepseek",
+    },
+    "deepseek-v4-flash": {
+        "input": 0.27,
+        "output": 1.10,
+        "cached_input": 0.027,
+        "provider": "deepseek",
+    },
+    # Legacy aliases - deprecating July 24, 2026; kept for backward compatibility.
+    "deepseek-chat": {"input": 0.27, "output": 1.10, "cached_input": 0.027, "provider": "deepseek"},
+    "deepseek-reasoner": {
+        "input": 0.27,
+        "output": 1.10,
+        "cached_input": 0.027,
+        "provider": "deepseek",
+    },
+    # ===== Mistral =====
+    "mistral-medium-3.5": {"input": 0.40, "output": 2.00, "provider": "mistral"},
+    "mistral-medium-latest": {"input": 0.40, "output": 2.00, "provider": "mistral"},
+    "mistral-large-latest": {"input": 0.50, "output": 1.50, "provider": "mistral"},
+    "mistral-small-latest": {"input": 0.15, "output": 0.60, "provider": "mistral"},
+    "codestral-latest": {"input": 0.30, "output": 0.90, "provider": "mistral"},
+    "magistral-medium-latest": {"input": 2.00, "output": 5.00, "provider": "mistral"},
+    "magistral-small-latest": {"input": 0.50, "output": 1.50, "provider": "mistral"},
+    # ===== Groq =====
+    "llama-3.3-70b-versatile": {"input": 0.59, "output": 0.79, "provider": "groq"},
+    "openai/gpt-oss-120b": {"input": 0.30, "output": 0.60, "provider": "groq"},
+    "openai/gpt-oss-safeguard-20b": {"input": 0.10, "output": 0.30, "provider": "groq"},
+    "meta-llama/llama-4-scout-17b-16e-instruct": {
+        "input": 0.20,
+        "output": 0.30,
+        "provider": "groq",
+    },
+    # ===== OpenRouter =====
+    # OpenRouter aggregates 315+ models behind one API. We register a few
+    # representative entries here; users can pass any OpenRouter model ID and
+    # we'll route it. Models not in this dict get a fallback cost of $0 (the
+    # provider returns real usage data in the response either way).
+    "qwen/qwen3.7-max": {"input": 2.50, "output": 7.50, "provider": "openrouter"},
+    "qwen/qwen3.5-plus": {"input": 0.30, "output": 1.80, "provider": "openrouter"},
+    "qwen/qwen3.6-flash": {"input": 0.19, "output": 1.13, "provider": "openrouter"},
+    "qwen/qwen3-coder:free": {"input": 0.0, "output": 0.0, "provider": "openrouter"},
+    "deepseek/deepseek-r1:free": {"input": 0.0, "output": 0.0, "provider": "openrouter"},
+    "meta-llama/llama-3-3-70b-instruct:free": {
+        "input": 0.0,
+        "output": 0.0,
+        "provider": "openrouter",
+    },
+    "openai/gpt-oss-120b:free": {"input": 0.0, "output": 0.0, "provider": "openrouter"},
+    "zhipuai/glm-4.7-flash:free": {"input": 0.0, "output": 0.0, "provider": "openrouter"},
+    # ===== Local =====
+    # Wildcard entry. Any model with `local/` prefix resolves here and costs $0.
+    "local/*": {"input": 0.0, "output": 0.0, "provider": "local", "is_local": True},
+}
+
+
+def is_local_model(model: str) -> bool:
+    """Return True for any model with the `local/` prefix."""
+    return model.startswith("local/")
+
+
+def get_pricing(model: str) -> dict[str, float | str | bool] | None:
+    """Look up the pricing entry for a model.
+
+    Local models always resolve to the `local/*` entry.
+    Returns None if the model is unknown (callers handle the error).
+    """
+    if is_local_model(model):
+        return PRICING["local/*"]
+    return PRICING.get(model)
+
+
+def calculate_cost(
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+    cached_tokens: int = 0,
+) -> float:
+    """Return the USD cost for a single completion.
+
+    Cached input tokens use the discounted `cached_input` rate if the model's
+    pricing entry includes one; otherwise they fall back to the normal input
+    rate. Local models always cost $0.
+    """
+    if is_local_model(model):
+        return 0.0
+
+    pricing = PRICING.get(model)
+    if pricing is None:
+        raise UnknownModelError(
+            f"Unknown model: {model}. Run `cli-modelarium list-models` to see supported models."
+        )
+
+    cached_tokens = max(0, min(cached_tokens, input_tokens))
+    non_cached = input_tokens - cached_tokens
+
+    cost = (non_cached / 1_000_000) * float(pricing["input"])
+
+    if cached_tokens > 0:
+        cached_rate = pricing.get("cached_input", pricing["input"])
+        cost += (cached_tokens / 1_000_000) * float(cached_rate)
+
+    cost += (output_tokens / 1_000_000) * float(pricing["output"])
+
+    return cost
+
+
+def pricing_freshness_note() -> str:
+    """Return the standard pricing-freshness disclaimer for user-facing output."""
+    return f"Note: Pricing data as of {PRICING_AS_OF}. Verify current pricing at provider websites."

cli_modelarium/providers/__init__.py

@@ -0,0 +1,7 @@
+"""Provider abstraction layer for Cli Modelarium."""
+
+from __future__ import annotations
+
+from cli_modelarium.providers.base import BaseProvider, CompletionResult
+
+__all__ = ["BaseProvider", "CompletionResult"]

cli_modelarium/providers/_utils.py

@@ -0,0 +1,26 @@
+"""Small helpers shared across provider modules."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def extract_retry_after(error: Any) -> float | None:
+    """Read a numeric `Retry-After` header from an SDK exception's response.
+
+    Handles either case (`retry-after` or `Retry-After`). Returns None if the
+    header is missing or not a parseable number (HTTP-date format is ignored).
+    """
+    response = getattr(error, "response", None)
+    if response is None:
+        return None
+    headers = getattr(response, "headers", None)
+    if headers is None:
+        return None
+    raw = headers.get("retry-after") or headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        return float(raw)
+    except (TypeError, ValueError):
+        return None

cli_modelarium/providers/anthropic_provider.py

@@ -0,0 +1,148 @@
+"""Anthropic provider implementation.
+
+Two things make Anthropic distinct from OpenAI-style providers:
+
+    1. The `system` prompt is a TOP-LEVEL parameter on `messages.create()`,
+       NOT a message with `role: "system"` inside the messages array.
+    2. `max_tokens` is REQUIRED on every call. We default to 4096 if the
+       caller doesn't specify one.
+
+Streaming uses the `messages.stream()` async context manager. The final
+usage payload (input/output/cache-read tokens) is read after iteration
+via `stream.get_final_message()`.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import AsyncIterator
+from typing import Any
+
+import anthropic
+from anthropic import AsyncAnthropic
+
+from cli_modelarium.exceptions import (
+    AuthenticationError,
+    ProviderError,
+    ProviderOverloadedError,
+    RateLimitError,
+)
+from cli_modelarium.pricing import calculate_cost
+from cli_modelarium.providers._utils import extract_retry_after
+from cli_modelarium.providers.base import BaseProvider, CompletionResult, OnChunk
+from cli_modelarium.security import redact_secrets
+
+DEFAULT_MAX_TOKENS = 4096
+
+
+class AnthropicProvider(BaseProvider):
+    """Provider using the official Anthropic Python SDK."""
+
+    name: str = "anthropic"
+
+    def __init__(self, api_key: str) -> None:
+        self.client = AsyncAnthropic(api_key=api_key)
+
+    def _build_kwargs(
+        self,
+        prompt: str,
+        model: str,
+        temperature: float,
+        system_prompt: str | None,
+        max_tokens: int = DEFAULT_MAX_TOKENS,
+    ) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+        }
+        if system_prompt:
+            kwargs["system"] = system_prompt
+        return kwargs
+
+    async def stream(
+        self,
+        prompt: str,
+        model: str,
+        temperature: float,
+        system_prompt: str | None = None,
+    ) -> AsyncIterator[str]:
+        kwargs = self._build_kwargs(prompt, model, temperature, system_prompt)
+        try:
+            async with self.client.messages.stream(**kwargs) as stream:
+                async for text in stream.text_stream:
+                    yield text
+        except anthropic.APIError as e:
+            self._reraise(e)
+
+    async def complete(
+        self,
+        prompt: str,
+        model: str,
+        temperature: float,
+        system_prompt: str | None = None,
+        *,
+        on_chunk: OnChunk | None = None,
+    ) -> CompletionResult:
+        kwargs = self._build_kwargs(prompt, model, temperature, system_prompt)
+
+        start = time.monotonic()
+        ttft_ms: float | None = None
+        chunks: list[str] = []
+        input_tokens = 0
+        output_tokens = 0
+        cached_tokens = 0
+
+        try:
+            async with self.client.messages.stream(**kwargs) as stream:
+                async for text in stream.text_stream:
+                    if ttft_ms is None:
+                        ttft_ms = (time.monotonic() - start) * 1000
+                    if on_chunk is not None:
+                        on_chunk(text)
+                    chunks.append(text)
+                final = await stream.get_final_message()
+                usage = final.usage
+                input_tokens = getattr(usage, "input_tokens", 0) or 0
+                output_tokens = getattr(usage, "output_tokens", 0) or 0
+                cached_tokens = getattr(usage, "cache_read_input_tokens", 0) or 0
+        except anthropic.APIError as e:
+            self._reraise(e)
+
+        latency_ms = (time.monotonic() - start) * 1000
+
+        try:
+            cost = calculate_cost(model, input_tokens, output_tokens, cached_tokens)
+        except Exception:
+            cost = 0.0
+
+        return CompletionResult(
+            output="".join(chunks),
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cached_tokens=cached_tokens,
+            cost_usd=cost,
+            latency_ms=latency_ms,
+            ttft_ms=ttft_ms,
+            model=model,
+            provider=self.name,
+            temperature=temperature,
+        )
+
+    def _reraise(self, error: anthropic.APIError) -> None:
+        """Translate an Anthropic SDK error into a redacted Cli Modelarium exception."""
+        message = redact_secrets(str(error))
+
+        if isinstance(error, anthropic.AuthenticationError):
+            raise AuthenticationError(message, provider=self.name) from None
+        if isinstance(error, anthropic.RateLimitError):
+            retry_after = extract_retry_after(error)
+            raise RateLimitError(message, provider=self.name, retry_after=retry_after) from None
+        # Anthropic returns 529 when their service is overloaded - distinct from rate limits.
+        if (
+            isinstance(error, anthropic.APIStatusError)
+            and getattr(error, "status_code", None) == 529
+        ):
+            raise ProviderOverloadedError(message, provider=self.name) from None
+        raise ProviderError(message, provider=self.name) from None

cli_modelarium/providers/base.py

@@ -0,0 +1,87 @@
+"""Provider abstraction: every concrete provider implements this interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator, Callable
+from dataclasses import dataclass
+
+
+@dataclass
+class CompletionResult:
+    """The full result of a single completion call.
+
+    All fields default-initialized so partial results (on error, mid-stream
+    failure, or sync collection) remain valid dataclasses.
+    """
+
+    output: str = ""
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cached_tokens: int = 0
+    cost_usd: float = 0.0
+    latency_ms: float = 0.0
+    ttft_ms: float | None = None
+    model: str = ""
+    provider: str = ""
+    temperature: float = 0.0
+    error: str | None = None
+
+
+# Type alias for the per-chunk callback that the streaming orchestrator passes in.
+OnChunk = Callable[[str], None]
+
+
+class BaseProvider(ABC):
+    """Abstract base class for every provider integration.
+
+    Subclasses implement `stream()` as an async generator that yields token
+    chunks. The default `complete()` collects those chunks but cannot capture
+    usage data - subclasses should override `complete()` to read the final
+    usage payload from the provider's response.
+    """
+
+    name: str = "base"
+
+    @abstractmethod
+    async def stream(
+        self,
+        prompt: str,
+        model: str,
+        temperature: float,
+        system_prompt: str | None = None,
+    ) -> AsyncIterator[str]:
+        """Yield response token chunks as they arrive from the provider."""
+        ...
+
+    async def complete(
+        self,
+        prompt: str,
+        model: str,
+        temperature: float,
+        system_prompt: str | None = None,
+        *,
+        on_chunk: OnChunk | None = None,
+    ) -> CompletionResult:
+        """Run a non-streaming completion.
+
+        Default implementation collects chunks from `stream()` but cannot
+        capture token usage. Subclasses should override to read usage data
+        from the final API response.
+
+        If `on_chunk` is provided it is invoked with each text chunk before
+        the chunk is appended to the accumulator. This lets the streaming
+        orchestrator surface partial output live without changing the public
+        return type.
+        """
+        chunks: list[str] = []
+        async for chunk in self.stream(prompt, model, temperature, system_prompt):
+            if on_chunk is not None:
+                on_chunk(chunk)
+            chunks.append(chunk)
+        return CompletionResult(
+            output="".join(chunks),
+            model=model,
+            provider=self.name,
+            temperature=temperature,
+        )

cli_modelarium/providers/deepseek_provider.py

@@ -0,0 +1,15 @@
+"""DeepSeek provider - uses the OpenAI SDK with a different base URL."""
+
+from __future__ import annotations
+
+from cli_modelarium.providers.openai_provider import OpenAIProvider
+
+
+class DeepSeekProvider(OpenAIProvider):
+    """DeepSeek models via the OpenAI-compatible endpoint at api.deepseek.com."""
+
+    name: str = "deepseek"
+    BASE_URL: str = "https://api.deepseek.com/v1"
+
+    def __init__(self, api_key: str) -> None:
+        super().__init__(api_key=api_key, base_url=self.BASE_URL)

cli_modelarium/providers/google_provider.py

@@ -0,0 +1,135 @@
+"""Google Gemini provider using the google-genai SDK.
+
+API quirks compared to OpenAI-style providers:
+
+    - The Client is constructed via `genai.Client(api_key=...)`.
+    - Async work goes through `client.aio.models.*`.
+    - System prompts live inside the `config` dict as `system_instruction`,
+      not as a message with `role="system"`.
+    - Usage data is on the chunk's `usage_metadata` (with field names like
+      `prompt_token_count` rather than OpenAI's `prompt_tokens`).
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import AsyncIterator
+from typing import Any
+
+from google import genai
+from google.genai import errors as genai_errors
+
+from cli_modelarium.exceptions import (
+    AuthenticationError,
+    ProviderError,
+    RateLimitError,
+)
+from cli_modelarium.pricing import calculate_cost
+from cli_modelarium.providers.base import BaseProvider, CompletionResult, OnChunk
+from cli_modelarium.security import redact_secrets
+
+
+class GoogleProvider(BaseProvider):
+    """Provider using the official google-genai SDK for Gemini models."""
+
+    name: str = "google"
+
+    def __init__(self, api_key: str) -> None:
+        self.client = genai.Client(api_key=api_key)
+
+    def _build_config(self, temperature: float, system_prompt: str | None) -> dict[str, Any]:
+        config: dict[str, Any] = {"temperature": temperature}
+        if system_prompt:
+            config["system_instruction"] = system_prompt
+        return config
+
+    async def stream(
+        self,
+        prompt: str,
+        model: str,
+        temperature: float,
+        system_prompt: str | None = None,
+    ) -> AsyncIterator[str]:
+        config = self._build_config(temperature, system_prompt)
+        try:
+            response_stream = await self.client.aio.models.generate_content_stream(
+                model=model,
+                contents=prompt,
+                config=config,
+            )
+            async for chunk in response_stream:
+                if chunk.text:
+                    yield chunk.text
+        except genai_errors.APIError as e:
+            self._reraise(e)
+
+    async def complete(
+        self,
+        prompt: str,
+        model: str,
+        temperature: float,
+        system_prompt: str | None = None,
+        *,
+        on_chunk: OnChunk | None = None,
+    ) -> CompletionResult:
+        config = self._build_config(temperature, system_prompt)
+
+        start = time.monotonic()
+        ttft_ms: float | None = None
+        chunks: list[str] = []
+        input_tokens = 0
+        output_tokens = 0
+        cached_tokens = 0
+
+        try:
+            response_stream = await self.client.aio.models.generate_content_stream(
+                model=model,
+                contents=prompt,
+                config=config,
+            )
+            async for chunk in response_stream:
+                if chunk.text:
+                    if ttft_ms is None:
+                        ttft_ms = (time.monotonic() - start) * 1000
+                    if on_chunk is not None:
+                        on_chunk(chunk.text)
+                    chunks.append(chunk.text)
+                # Final chunk carries the usage_metadata.
+                usage = getattr(chunk, "usage_metadata", None)
+                if usage is not None:
+                    input_tokens = getattr(usage, "prompt_token_count", 0) or 0
+                    output_tokens = getattr(usage, "candidates_token_count", 0) or 0
+                    cached_tokens = getattr(usage, "cached_content_token_count", 0) or 0
+        except genai_errors.APIError as e:
+            self._reraise(e)
+
+        latency_ms = (time.monotonic() - start) * 1000
+
+        try:
+            cost = calculate_cost(model, input_tokens, output_tokens, cached_tokens)
+        except Exception:
+            cost = 0.0
+
+        return CompletionResult(
+            output="".join(chunks),
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cached_tokens=cached_tokens,
+            cost_usd=cost,
+            latency_ms=latency_ms,
+            ttft_ms=ttft_ms,
+            model=model,
+            provider=self.name,
+            temperature=temperature,
+        )
+
+    def _reraise(self, error: genai_errors.APIError) -> None:
+        """Translate a google-genai SDK error into a redacted Cli Modelarium exception."""
+        message = redact_secrets(str(error))
+        # google-genai doesn't expose typed subclasses for 401/429 - route by HTTP code.
+        code = getattr(error, "code", None)
+        if code in (401, 403):
+            raise AuthenticationError(message, provider=self.name) from None
+        if code == 429:
+            raise RateLimitError(message, provider=self.name, retry_after=None) from None
+        raise ProviderError(message, provider=self.name) from None

cli_modelarium/providers/groq_provider.py

@@ -0,0 +1,15 @@
+"""Groq provider - uses the OpenAI SDK with a different base URL."""
+
+from __future__ import annotations
+
+from cli_modelarium.providers.openai_provider import OpenAIProvider
+
+
+class GroqProvider(OpenAIProvider):
+    """Groq models via the OpenAI-compatible endpoint at api.groq.com."""
+
+    name: str = "groq"
+    BASE_URL: str = "https://api.groq.com/openai/v1"
+
+    def __init__(self, api_key: str) -> None:
+        super().__init__(api_key=api_key, base_url=self.BASE_URL)