llmcalc 0.1.0__tar.gz

llmcalc-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+          pip install build
+
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Type check
+        run: python -m mypy llmcalc
+
+      - name: Test
+        run: python -m pytest
+
+      - name: Build
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*

llmcalc-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+.dist/
+build/
+dist/
+
+.env
+.env.local

llmcalc-0.1.0/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md
+
+## Project
+- Name: `llmcalc`
+- Purpose: Calculate LLM token costs from `llmlite` pricing data.
+- Runtime: Python `>=3.11`.
+
+## Code Style
+- Keep modules small and composable.
+- Centralize defaults/env parsing in `llmcalc/config.py`.
+- Prefer pure helpers for deterministic logic (normalization, math, parsing).
+- Keep public API typed and stable.
+
+## Local Commands
+- Install: `pip install -e '.[dev]'`
+- Lint: `python -m ruff check .`
+- Type check: `python -m mypy llmcalc`
+- Test: `python -m pytest`
+- Build: `python -m build --no-isolation`
+- Dist check: `python -m twine check dist/*`
+
+## CLI Expectations
+- Root command: `llmcalc`
+- Version flags: `llmcalc --version` and `llmcalc -v`
+- Cache defaults:
+  - Default TTL: `43200` seconds
+  - Env override: `LLMCALC_CACHE_TIMEOUT`
+
+## Release Checklist
+1. Run lint, mypy, and tests.
+2. Build distributions.
+3. Run `twine check`.
+4. Update `CHANGELOG.md`.
+5. Publish to PyPI.

llmcalc-0.1.0/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## 0.1.0
+- Initial release with pricing fetch, cache, normalization, API, and CLI.

llmcalc-0.1.0/LICENSE

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

llmcalc-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: llmcalc
+Version: 0.1.0
+Summary: Calculate LLM token costs from llmlite pricing data
+Project-URL: Homepage, https://github.com/onlyoneaman/llmcalc
+Project-URL: Repository, https://github.com/onlyoneaman/llmcalc
+Project-URL: Issues, https://github.com/onlyoneaman/llmcalc/issues
+Project-URL: Changelog, https://github.com/onlyoneaman/llmcalc/blob/main/CHANGELOG.md
+Author: Aman
+License: MIT
+License-File: LICENSE
+Keywords: cost,llm,pricing,tokens
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: platformdirs<5,>=4.2
+Requires-Dist: pydantic<3,>=2.8
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'dev'
+Requires-Dist: pytest<9,>=8.2; extra == 'dev'
+Requires-Dist: ruff<1,>=0.6; extra == 'dev'
+Requires-Dist: twine<7,>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# llmcalc
+
+`llmcalc` is a Python package to calculate LLM token costs from `llmlite` pricing data.
+
+## Install
+
+```bash
+pip install llmcalc
+```
+
+## Python usage
+
+```python
+import asyncio
+from llmcalc import calculate_token_cost
+
+result = asyncio.run(calculate_token_cost("gpt-4o-mini", 1200, 800))
+if result:
+    print(result.total_cost)
+```
+
+## CLI usage
+
+```bash
+llmcalc quote --model gpt-4o-mini --input 1200 --output 800
+llmcalc model --model gpt-4o-mini --json
+llmcalc cache clear
+llmcalc --version
+```
+
+## Defaults
+
+- Default cache TTL is `43200` seconds (12 hours).
+- Override cache TTL with `LLMCALC_CACHE_TIMEOUT`.
+- Override pricing source with `LLMCALC_PRICING_URL`.
+- Set fallback currency label with `LLMCALC_CURRENCY` (used only when upstream omits currency).
+
+## Release Validation
+
+```bash
+python -m build --no-isolation
+python -m twine check dist/*
+```

llmcalc-0.1.0/README.md

@@ -0,0 +1,43 @@
+# llmcalc
+
+`llmcalc` is a Python package to calculate LLM token costs from `llmlite` pricing data.
+
+## Install
+
+```bash
+pip install llmcalc
+```
+
+## Python usage
+
+```python
+import asyncio
+from llmcalc import calculate_token_cost
+
+result = asyncio.run(calculate_token_cost("gpt-4o-mini", 1200, 800))
+if result:
+    print(result.total_cost)
+```
+
+## CLI usage
+
+```bash
+llmcalc quote --model gpt-4o-mini --input 1200 --output 800
+llmcalc model --model gpt-4o-mini --json
+llmcalc cache clear
+llmcalc --version
+```
+
+## Defaults
+
+- Default cache TTL is `43200` seconds (12 hours).
+- Override cache TTL with `LLMCALC_CACHE_TIMEOUT`.
+- Override pricing source with `LLMCALC_PRICING_URL`.
+- Set fallback currency label with `LLMCALC_CURRENCY` (used only when upstream omits currency).
+
+## Release Validation
+
+```bash
+python -m build --no-isolation
+python -m twine check dist/*
+```

llmcalc-0.1.0/llmcalc/__init__.py

@@ -0,0 +1,17 @@
+"""llmcalc public package exports."""
+
+from llmcalc.api import calculate_token_cost, calculate_usage_cost, clear_cache, get_model_costs
+from llmcalc.config import get_package_version
+from llmcalc.models import CostBreakdown, ModelPricing
+
+__version__ = get_package_version()
+
+__all__ = [
+    "__version__",
+    "CostBreakdown",
+    "ModelPricing",
+    "calculate_token_cost",
+    "calculate_usage_cost",
+    "clear_cache",
+    "get_model_costs",
+]

llmcalc-0.1.0/llmcalc/api.py

@@ -0,0 +1,120 @@
+"""Public API for llmcalc."""
+
+from __future__ import annotations
+
+from decimal import ROUND_HALF_UP, Decimal
+from typing import Any, Protocol, runtime_checkable
+
+from llmcalc.cache import clear_cache as clear_cache_file
+from llmcalc.config import DEFAULT_CACHE_TIMEOUT_SECONDS, resolve_cache_timeout
+from llmcalc.models import CostBreakdown, ModelPricing
+from llmcalc.normalize import resolve_model_key
+from llmcalc.pricing_client import get_pricing_table
+
+DEFAULT_ROUNDING_PLACES = 6
+
+
+@runtime_checkable
+class UsageLike(Protocol):
+    """Protocol for usage objects accepted by `calculate_usage_cost`."""
+
+    prompt_tokens: int
+    completion_tokens: int
+
+
+def _round_money(amount: Decimal, places: int = DEFAULT_ROUNDING_PLACES) -> Decimal:
+    quant = Decimal("1").scaleb(-places)
+    return amount.quantize(quant, rounding=ROUND_HALF_UP)
+
+
+def _validate_non_negative(value: int, field_name: str) -> None:
+    if value < 0:
+        raise ValueError(f"{field_name} must be non-negative")
+
+
+async def get_model_costs(
+    model: str,
+    cache_timeout: int | None = None,
+) -> ModelPricing | None:
+    """Return per-token pricing for a model, or `None` if not found."""
+    table = await get_pricing_table(cache_timeout=resolve_cache_timeout(cache_timeout))
+    resolved = resolve_model_key(model, table.keys())
+    if resolved is None:
+        return None
+    return table[resolved]
+
+
+async def calculate_token_cost(
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+    cache_timeout: int | None = None,
+) -> CostBreakdown | None:
+    """Calculate model usage cost from token counts, or return `None` if model is unavailable."""
+    _validate_non_negative(input_tokens, "input_tokens")
+    _validate_non_negative(output_tokens, "output_tokens")
+
+    model_costs = await get_model_costs(model, cache_timeout=cache_timeout)
+    if model_costs is None:
+        return None
+
+    input_cost = _round_money(Decimal(input_tokens) * model_costs.input_cost_per_token)
+    output_cost = _round_money(Decimal(output_tokens) * model_costs.output_cost_per_token)
+    total_cost = _round_money(input_cost + output_cost)
+
+    return CostBreakdown(
+        input_cost=input_cost,
+        output_cost=output_cost,
+        total_cost=total_cost,
+        currency=model_costs.currency,
+    )
+
+
+def _value_from_mapping(usage: dict[str, Any], key_options: tuple[str, ...]) -> int | None:
+    for key in key_options:
+        value = usage.get(key)
+        if isinstance(value, int):
+            return value
+    return None
+
+
+def _get_usage_tokens(usage: Any) -> tuple[int, int]:
+    if isinstance(usage, dict):
+        input_tokens = _value_from_mapping(usage, ("input_tokens", "prompt_tokens"))
+        output_tokens = _value_from_mapping(usage, ("output_tokens", "completion_tokens"))
+    else:
+        input_tokens = getattr(usage, "input_tokens", None)
+        if not isinstance(input_tokens, int):
+            input_tokens = getattr(usage, "prompt_tokens", None)
+
+        output_tokens = getattr(usage, "output_tokens", None)
+        if not isinstance(output_tokens, int):
+            output_tokens = getattr(usage, "completion_tokens", None)
+
+    if not isinstance(input_tokens, int) or not isinstance(output_tokens, int):
+        raise ValueError("usage must provide input/prompt tokens and output/completion tokens")
+
+    return input_tokens, output_tokens
+
+
+async def calculate_usage_cost(
+    model: str,
+    usage: UsageLike | dict[str, Any],
+    cache_timeout: int | None = None,
+) -> CostBreakdown | None:
+    """Calculate cost from an object that includes usage token fields."""
+    input_tokens, output_tokens = _get_usage_tokens(usage)
+    return await calculate_token_cost(
+        model=model,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cache_timeout=cache_timeout,
+    )
+
+
+def clear_cache() -> None:
+    """Clear local pricing cache file."""
+    clear_cache_file()
+
+
+DEFAULT_CACHE_TIMEOUT = DEFAULT_CACHE_TIMEOUT_SECONDS

llmcalc-0.1.0/llmcalc/cache.py

@@ -0,0 +1,57 @@
+"""Filesystem cache helpers for pricing payloads."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from platformdirs import user_cache_dir
+
+CACHE_DIR_NAME = "llmcalc"
+CACHE_FILE_NAME = "pricing_cache.json"
+
+
+def cache_file_path() -> Path:
+    base_dir = Path(user_cache_dir(appname=CACHE_DIR_NAME, appauthor=CACHE_DIR_NAME))
+    return base_dir / CACHE_FILE_NAME
+
+
+def load_cached_pricing(max_age_seconds: int) -> dict[str, Any] | None:
+    path = cache_file_path()
+    if not path.exists():
+        return None
+
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    fetched_at = payload.get("fetched_at")
+    data = payload.get("data")
+    if not isinstance(fetched_at, (int, float)) or not isinstance(data, dict):
+        return None
+
+    if time.time() - fetched_at > max_age_seconds:
+        return None
+
+    return data
+
+
+def save_cached_pricing(data: dict[str, Any]) -> None:
+    path = cache_file_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    payload = {
+        "fetched_at": time.time(),
+        "data": data,
+    }
+
+    path.write_text(json.dumps(payload, separators=(",", ":")), encoding="utf-8")
+
+
+def clear_cache() -> None:
+    path = cache_file_path()
+    if path.exists():
+        path.unlink()

llmcalc-0.1.0/llmcalc/cli.py

@@ -0,0 +1,131 @@
+"""CLI for llmcalc."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Annotated, Any
+
+import typer
+
+from llmcalc import __version__
+from llmcalc.api import (
+    calculate_token_cost,
+    clear_cache,
+    get_model_costs,
+)
+from llmcalc.config import DEFAULT_CACHE_TIMEOUT_SECONDS
+
+DEFAULT_CACHE_TIMEOUT_HELP = (
+    f"Cache TTL in seconds (default: {DEFAULT_CACHE_TIMEOUT_SECONDS} or LLMCALC_CACHE_TIMEOUT)"
+)
+
+app = typer.Typer(help="Calculate LLM token pricing from llmlite data.", no_args_is_help=True)
+cache_app = typer.Typer(help="Cache commands.")
+app.add_typer(cache_app, name="cache")
+
+
+def _model_option() -> Any:
+    return typer.Option(..., "--model", help="Model id")
+
+
+def _cache_timeout_option() -> Any:
+    return typer.Option(None, "--cache-timeout", help=DEFAULT_CACHE_TIMEOUT_HELP)
+
+
+def _json_option() -> Any:
+    return typer.Option(False, "--json", help="Emit JSON output")
+
+
+def _emit(data: dict[str, object], as_json: bool) -> None:
+    if as_json:
+        typer.echo(json.dumps(data, default=str))
+        return
+
+    for key, value in data.items():
+        typer.echo(f"{key}: {value}")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"llmcalc {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def app_main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-v",
+            help="Show package version and exit.",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    _ = version
+
+
+@app.command()
+def quote(
+    model: str = _model_option(),
+    input_tokens: int = typer.Option(..., "--input", help="Input token count", min=0),
+    output_tokens: int = typer.Option(..., "--output", help="Output token count", min=0),
+    cache_timeout: int | None = _cache_timeout_option(),
+    as_json: bool = _json_option(),
+) -> None:
+    """Quote input/output/total cost for a model."""
+    result = asyncio.run(
+        calculate_token_cost(
+            model=model,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cache_timeout=cache_timeout,
+        )
+    )
+
+    if result is None:
+        typer.echo(f"Model not found: {model}", err=True)
+        raise typer.Exit(code=1)
+
+    payload = {
+        "model": model,
+        "input_cost": result.input_cost,
+        "output_cost": result.output_cost,
+        "total_cost": result.total_cost,
+        "currency": result.currency,
+    }
+    _emit(payload, as_json)
+
+
+@app.command("model")
+def model_cmd(
+    model: str = _model_option(),
+    cache_timeout: int | None = _cache_timeout_option(),
+    as_json: bool = _json_option(),
+) -> None:
+    """Show per-token pricing for a model."""
+    result = asyncio.run(get_model_costs(model=model, cache_timeout=cache_timeout))
+
+    if result is None:
+        typer.echo(f"Model not found: {model}", err=True)
+        raise typer.Exit(code=1)
+
+    payload = {
+        "model": result.model,
+        "input_cost_per_token": result.input_cost_per_token,
+        "output_cost_per_token": result.output_cost_per_token,
+        "currency": result.currency,
+        "provider": result.provider,
+        "last_updated": result.last_updated,
+    }
+    _emit(payload, as_json)
+
+
+@cache_app.command("clear")
+def cache_clear() -> None:
+    """Clear local pricing cache."""
+    clear_cache()
+    typer.echo("Cache cleared")

llmcalc-0.1.0/llmcalc/config.py

@@ -0,0 +1,60 @@
+"""Configuration defaults and environment-driven settings."""
+
+from __future__ import annotations
+
+import os
+from importlib import metadata
+
+APP_NAME = "llmcalc"
+FALLBACK_VERSION = "0.1.0"
+DEFAULT_CACHE_TIMEOUT_SECONDS = 43200
+DEFAULT_CURRENCY = "USD"
+DEFAULT_PRICING_URL = (
+    "https://raw.githubusercontent.com/llmlite/llmlite/main/model_prices_and_context_window.json"
+)
+
+
+def get_package_version() -> str:
+    """Return installed package version with a source fallback."""
+    try:
+        return metadata.version(APP_NAME)
+    except metadata.PackageNotFoundError:
+        return FALLBACK_VERSION
+
+
+def get_user_agent() -> str:
+    """Return HTTP user agent for outbound pricing requests."""
+    return f"{APP_NAME}/{get_package_version()}"
+
+
+def get_pricing_url(explicit_url: str | None = None) -> str:
+    """Resolve pricing source URL from explicit arg, env var, then default."""
+    return explicit_url or os.getenv("LLMCALC_PRICING_URL") or DEFAULT_PRICING_URL
+
+
+def get_default_currency() -> str:
+    """Resolve fallback currency label from env var or default."""
+    raw = os.getenv("LLMCALC_CURRENCY", "").strip().upper()
+    return raw or DEFAULT_CURRENCY
+
+
+def resolve_cache_timeout(cache_timeout: int | None = None) -> int:
+    """Resolve cache timeout from explicit value, env var, or default."""
+    if cache_timeout is not None:
+        if cache_timeout <= 0:
+            raise ValueError("cache_timeout must be positive")
+        return cache_timeout
+
+    env_value = os.getenv("LLMCALC_CACHE_TIMEOUT")
+    if env_value is None:
+        return DEFAULT_CACHE_TIMEOUT_SECONDS
+
+    try:
+        parsed = int(env_value)
+    except ValueError:
+        return DEFAULT_CACHE_TIMEOUT_SECONDS
+
+    if parsed <= 0:
+        return DEFAULT_CACHE_TIMEOUT_SECONDS
+
+    return parsed

llmcalc-0.1.0/llmcalc/errors.py

@@ -0,0 +1,13 @@
+"""Typed exceptions for llmcalc."""
+
+
+class PricingError(Exception):
+    """Base pricing error type."""
+
+
+class PricingFetchError(PricingError):
+    """Raised when pricing data cannot be fetched and no cache is usable."""
+
+
+class PricingSchemaError(PricingError):
+    """Raised when upstream pricing data is invalid."""

llmcalc-0.1.0/llmcalc/models.py

@@ -0,0 +1,99 @@
+"""Pydantic models for pricing and cost breakdown data."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class CostBreakdown(BaseModel):
+    """Cost result for a token usage calculation."""
+
+    input_cost: Decimal = Field(ge=Decimal("0"))
+    output_cost: Decimal = Field(ge=Decimal("0"))
+    total_cost: Decimal = Field(ge=Decimal("0"))
+    currency: str = "USD"
+
+    model_config = ConfigDict(frozen=True)
+
+
+class ModelPricing(BaseModel):
+    """Normalized token pricing for one model."""
+
+    model: str
+    input_cost_per_token: Decimal = Field(ge=Decimal("0"))
+    output_cost_per_token: Decimal = Field(ge=Decimal("0"))
+    provider: str | None = None
+    currency: str = "USD"
+    last_updated: str | None = None
+
+    model_config = ConfigDict(frozen=True)
+
+
+class RawModelPricing(BaseModel):
+    """Flexible upstream schema model from llmlite pricing JSON."""
+
+    input_cost_per_token: Decimal | None = None
+    output_cost_per_token: Decimal | None = None
+
+    # Common aliases used by some pricing datasets.
+    prompt_cost_per_token: Decimal | None = None
+    completion_cost_per_token: Decimal | None = None
+    input_cost_per_million_tokens: Decimal | None = None
+    output_cost_per_million_tokens: Decimal | None = None
+
+    provider: str | None = None
+    currency: str | None = None
+    last_updated: str | None = None
+
+    @field_validator("input_cost_per_token", "output_cost_per_token", mode="before")
+    @classmethod
+    def normalize_numeric_str(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return value.strip()
+        return value
+
+    @field_validator("prompt_cost_per_token", "completion_cost_per_token", mode="before")
+    @classmethod
+    def normalize_alias_numeric_str(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return value.strip()
+        return value
+
+    @field_validator(
+        "input_cost_per_million_tokens",
+        "output_cost_per_million_tokens",
+        mode="before",
+    )
+    @classmethod
+    def normalize_million_numeric_str(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return value.strip()
+        return value
+
+    def to_model_pricing(self, model: str, default_currency: str = "USD") -> ModelPricing:
+        input_cost = self.input_cost_per_token
+        output_cost = self.output_cost_per_token
+
+        if input_cost is None:
+            input_cost = self.prompt_cost_per_token
+        if output_cost is None:
+            output_cost = self.completion_cost_per_token
+        if input_cost is None and self.input_cost_per_million_tokens is not None:
+            input_cost = self.input_cost_per_million_tokens / Decimal("1000000")
+        if output_cost is None and self.output_cost_per_million_tokens is not None:
+            output_cost = self.output_cost_per_million_tokens / Decimal("1000000")
+
+        if input_cost is None or output_cost is None:
+            raise ValueError("Missing input/output token pricing fields")
+
+        return ModelPricing(
+            model=model,
+            input_cost_per_token=input_cost,
+            output_cost_per_token=output_cost,
+            provider=self.provider,
+            currency=self.currency or default_currency,
+            last_updated=self.last_updated,
+        )

llmcalc-0.1.0/llmcalc/normalize.py

@@ -0,0 +1,63 @@
+"""Model name normalization and lookup helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+# Keep aliases small and explicit; extend as model IDs evolve.
+ALIASES: dict[str, str] = {
+    "gpt-4o-mini-latest": "gpt-4o-mini",
+    "gpt-4.1-mini-latest": "gpt-4.1-mini",
+}
+
+PROVIDER_PREFIXES: set[str] = {
+    "openai",
+    "anthropic",
+    "google",
+    "xai",
+    "meta",
+    "mistral",
+}
+
+
+def normalize_model_name(model: str) -> str:
+    """Normalize an input model identifier to a canonical lookup key."""
+    normalized = model.strip().lower()
+    if not normalized:
+        raise ValueError("model must not be empty")
+
+    if ":" in normalized:
+        provider, suffix = normalized.split(":", 1)
+        if provider and suffix:
+            normalized = suffix
+
+    if "/" in normalized:
+        provider, suffix = normalized.split("/", 1)
+        if provider in PROVIDER_PREFIXES and suffix:
+            normalized = suffix
+
+    return ALIASES.get(normalized, normalized)
+
+
+def resolve_model_key(model: str, available_keys: Iterable[str]) -> str | None:
+    """Resolve a requested model id against available pricing table keys."""
+    key_map: dict[str, str] = {}
+    for key in available_keys:
+        key_map[key.lower()] = key
+        key_map.setdefault(normalize_model_name(key), key)
+
+    candidates: list[str] = []
+    raw = model.strip().lower()
+    if raw:
+        candidates.append(raw)
+    candidates.append(normalize_model_name(model))
+
+    for candidate in candidates:
+        direct = key_map.get(candidate)
+        if direct is not None:
+            return direct
+        alias = ALIASES.get(candidate)
+        if alias is not None and alias in key_map:
+            return key_map[alias]
+
+    return None

llmcalc-0.1.0/llmcalc/pricing_client.py

@@ -0,0 +1,92 @@
+"""Pricing data fetch and normalization against llmlite pricing source."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from llmcalc.cache import load_cached_pricing, save_cached_pricing
+from llmcalc.config import (
+    DEFAULT_CACHE_TIMEOUT_SECONDS,
+    get_default_currency,
+    get_pricing_url,
+    get_user_agent,
+)
+from llmcalc.errors import PricingFetchError, PricingSchemaError
+from llmcalc.models import ModelPricing, RawModelPricing
+
+
+async def fetch_pricing_payload(pricing_url: str | None = None) -> dict[str, Any]:
+    """Fetch pricing payload from configured remote source."""
+    source = get_pricing_url(pricing_url)
+
+    try:
+        async with httpx.AsyncClient(
+            timeout=10,
+            headers={"User-Agent": get_user_agent()},
+        ) as client:
+            response = await client.get(source)
+            response.raise_for_status()
+            payload = response.json()
+    except (httpx.HTTPError, ValueError) as exc:
+        raise PricingFetchError(f"failed to fetch pricing data from {source}") from exc
+
+    if not isinstance(payload, dict):
+        raise PricingSchemaError("pricing payload must be a JSON object")
+
+    return payload
+
+
+def parse_pricing_payload(payload: Mapping[str, Any]) -> dict[str, ModelPricing]:
+    """Parse raw pricing JSON into normalized `ModelPricing` objects."""
+    raw_table: Mapping[str, Any]
+    default_currency = get_default_currency()
+
+    wrapped_data = payload.get("data")
+    raw_table = wrapped_data if isinstance(wrapped_data, Mapping) else payload
+
+    parsed: dict[str, ModelPricing] = {}
+    for model_name, model_data in raw_table.items():
+        if not isinstance(model_name, str) or not isinstance(model_data, Mapping):
+            continue
+
+        try:
+            raw_model = RawModelPricing.model_validate(model_data)
+            parsed[model_name] = raw_model.to_model_pricing(
+                model_name,
+                default_currency=default_currency,
+            )
+        except Exception:
+            # Some payloads contain non-pricing metadata entries; skip them.
+            continue
+
+    if not parsed:
+        raise PricingSchemaError("no valid model pricing entries found")
+
+    return parsed
+
+
+async def get_pricing_table(
+    cache_timeout: int = DEFAULT_CACHE_TIMEOUT_SECONDS,
+    pricing_url: str | None = None,
+) -> dict[str, ModelPricing]:
+    """Get model pricing table using cache-first strategy with remote refresh fallback."""
+    cached_data = load_cached_pricing(cache_timeout)
+    if cached_data is not None:
+        try:
+            return parse_pricing_payload(cached_data)
+        except PricingSchemaError:
+            pass
+
+    try:
+        fetched_payload = await fetch_pricing_payload(pricing_url=pricing_url)
+    except PricingFetchError:
+        if cached_data is not None:
+            return parse_pricing_payload(cached_data)
+        raise
+
+    parsed = parse_pricing_payload(fetched_payload)
+    save_cached_pricing(fetched_payload)
+    return parsed

llmcalc-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "llmcalc"
+version = "0.1.0"
+description = "Calculate LLM token costs from llmlite pricing data"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+  { name = "Aman", url = "https://github.com/onlyoneaman" }
+]
+keywords = ["llm", "pricing", "tokens", "cost"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "platformdirs>=4.2,<5",
+  "pydantic>=2.8,<3",
+  "typer>=0.12,<1",
+]
+
+[project.urls]
+Homepage = "https://github.com/onlyoneaman/llmcalc"
+Repository = "https://github.com/onlyoneaman/llmcalc"
+Issues = "https://github.com/onlyoneaman/llmcalc/issues"
+Changelog = "https://github.com/onlyoneaman/llmcalc/blob/main/CHANGELOG.md"
+
+[project.scripts]
+llmcalc = "llmcalc.cli:app"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.2,<9",
+  "pytest-asyncio>=0.23,<1",
+  "ruff>=0.6,<1",
+  "mypy>=1.10,<2",
+  "twine>=5,<7",
+]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_configs = true

llmcalc-0.1.0/tests/test_api.py

@@ -0,0 +1,125 @@
+from dataclasses import dataclass
+from decimal import Decimal
+
+import pytest
+
+import llmcalc.api as api
+from llmcalc.models import ModelPricing
+
+
+async def _fake_pricing_table(cache_timeout: int = 86400):
+    _ = cache_timeout
+    return {
+        "gpt-4o-mini": ModelPricing(
+            model="gpt-4o-mini",
+            input_cost_per_token=Decimal("0.000001"),
+            output_cost_per_token=Decimal("0.000002"),
+            currency="USD",
+        )
+    }
+
+
+@pytest.mark.asyncio
+async def test_get_model_costs_found(monkeypatch) -> None:
+    monkeypatch.setattr(api, "get_pricing_table", _fake_pricing_table)
+    result = await api.get_model_costs("openai:gpt-4o-mini")
+    assert result is not None
+    assert result.model == "gpt-4o-mini"
+
+
+@pytest.mark.asyncio
+async def test_calculate_token_cost(monkeypatch) -> None:
+    monkeypatch.setattr(api, "get_pricing_table", _fake_pricing_table)
+    result = await api.calculate_token_cost("gpt-4o-mini", input_tokens=1000, output_tokens=500)
+
+    assert result is not None
+    assert result.input_cost == Decimal("0.001000")
+    assert result.output_cost == Decimal("0.001000")
+    assert result.total_cost == Decimal("0.002000")
+
+
+@pytest.mark.asyncio
+async def test_calculate_token_cost_unknown_model(monkeypatch) -> None:
+    monkeypatch.setattr(api, "get_pricing_table", _fake_pricing_table)
+    result = await api.calculate_token_cost("unknown", input_tokens=1, output_tokens=1)
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_calculate_usage_cost_dict(monkeypatch) -> None:
+    monkeypatch.setattr(api, "get_pricing_table", _fake_pricing_table)
+    result = await api.calculate_usage_cost(
+        "gpt-4o-mini",
+        usage={"prompt_tokens": 1000, "completion_tokens": 1000},
+    )
+    assert result is not None
+    assert result.total_cost == Decimal("0.003000")
+
+
+@dataclass
+class UsageObj:
+    input_tokens: int
+    output_tokens: int
+
+
+@pytest.mark.asyncio
+async def test_calculate_usage_cost_object(monkeypatch) -> None:
+    monkeypatch.setattr(api, "get_pricing_table", _fake_pricing_table)
+    result = await api.calculate_usage_cost("gpt-4o-mini", usage=UsageObj(100, 100))
+    assert result is not None
+    assert result.total_cost == Decimal("0.000300")
+
+
+@pytest.mark.asyncio
+async def test_calculate_token_cost_negative_tokens(monkeypatch) -> None:
+    monkeypatch.setattr(api, "get_pricing_table", _fake_pricing_table)
+    with pytest.raises(ValueError):
+        await api.calculate_token_cost("gpt-4o-mini", input_tokens=-1, output_tokens=1)
+
+
+@pytest.mark.asyncio
+async def test_get_model_costs_uses_env_cache_timeout(monkeypatch) -> None:
+    captured = {"cache_timeout": None}
+
+    async def _capture(cache_timeout: int = 0):
+        captured["cache_timeout"] = cache_timeout
+        return await _fake_pricing_table(cache_timeout=cache_timeout)
+
+    monkeypatch.setattr(api, "get_pricing_table", _capture)
+    monkeypatch.setenv("LLMCALC_CACHE_TIMEOUT", "1800")
+
+    await api.get_model_costs("gpt-4o-mini")
+    assert captured["cache_timeout"] == 1800
+
+
+@pytest.mark.asyncio
+async def test_get_model_costs_invalid_env_cache_timeout_falls_back(monkeypatch) -> None:
+    captured = {"cache_timeout": None}
+
+    async def _capture(cache_timeout: int = 0):
+        captured["cache_timeout"] = cache_timeout
+        return await _fake_pricing_table(cache_timeout=cache_timeout)
+
+    monkeypatch.setattr(api, "get_pricing_table", _capture)
+    monkeypatch.setenv("LLMCALC_CACHE_TIMEOUT", "bad-value")
+
+    await api.get_model_costs("gpt-4o-mini")
+    assert captured["cache_timeout"] == api.DEFAULT_CACHE_TIMEOUT
+
+
+@pytest.mark.asyncio
+async def test_get_model_costs_rejects_non_positive_cache_timeout(monkeypatch) -> None:
+    monkeypatch.setattr(api, "get_pricing_table", _fake_pricing_table)
+    with pytest.raises(ValueError):
+        await api.get_model_costs("gpt-4o-mini", cache_timeout=0)
+
+
+def test_clear_cache_calls_cache(monkeypatch) -> None:
+    called = {"value": False}
+
+    def _clear() -> None:
+        called["value"] = True
+
+    monkeypatch.setattr(api, "clear_cache_file", _clear)
+    api.clear_cache()
+    assert called["value"] is True

llmcalc-0.1.0/tests/test_cache.py

@@ -0,0 +1,44 @@
+import json
+import time
+from pathlib import Path
+
+from llmcalc import cache
+
+
+def _set_cache_path(monkeypatch, path: Path) -> None:
+    monkeypatch.setattr(cache, "cache_file_path", lambda: path)
+
+
+def test_save_and_load_cache(tmp_path, monkeypatch) -> None:
+    file_path = tmp_path / "pricing_cache.json"
+    _set_cache_path(monkeypatch, file_path)
+
+    data = {"gpt-4o-mini": {"input_cost_per_token": 0.1, "output_cost_per_token": 0.2}}
+    cache.save_cached_pricing(data)
+
+    loaded = cache.load_cached_pricing(max_age_seconds=3600)
+    assert loaded == data
+
+
+def test_load_cache_expired(tmp_path, monkeypatch) -> None:
+    file_path = tmp_path / "pricing_cache.json"
+    _set_cache_path(monkeypatch, file_path)
+
+    payload = {
+        "fetched_at": time.time() - 10,
+        "data": {"gpt-4o-mini": {"input_cost_per_token": 1, "output_cost_per_token": 2}},
+    }
+    file_path.write_text(json.dumps(payload), encoding="utf-8")
+
+    assert cache.load_cached_pricing(max_age_seconds=1) is None
+
+
+def test_clear_cache(tmp_path, monkeypatch) -> None:
+    file_path = tmp_path / "pricing_cache.json"
+    _set_cache_path(monkeypatch, file_path)
+
+    file_path.write_text("{}", encoding="utf-8")
+    assert file_path.exists()
+
+    cache.clear_cache()
+    assert not file_path.exists()

llmcalc-0.1.0/tests/test_cli.py

@@ -0,0 +1,18 @@
+from typer.testing import CliRunner
+
+from llmcalc import __version__
+from llmcalc.cli import app
+
+runner = CliRunner()
+
+
+def test_cli_version_long_flag() -> None:
+    result = runner.invoke(app, ["--version"])
+    assert result.exit_code == 0
+    assert f"llmcalc {__version__}" in result.stdout
+
+
+def test_cli_version_short_flag() -> None:
+    result = runner.invoke(app, ["-v"])
+    assert result.exit_code == 0
+    assert f"llmcalc {__version__}" in result.stdout

llmcalc-0.1.0/tests/test_models.py

@@ -0,0 +1,27 @@
+from decimal import Decimal
+
+from llmcalc.models import RawModelPricing
+
+
+def test_raw_model_pricing_from_alias_fields() -> None:
+    raw = RawModelPricing(
+        prompt_cost_per_token="0.000001",
+        completion_cost_per_token="0.000002",
+        provider="openai",
+    )
+
+    model = raw.to_model_pricing("gpt-4o-mini")
+    assert model.input_cost_per_token == Decimal("0.000001")
+    assert model.output_cost_per_token == Decimal("0.000002")
+    assert model.provider == "openai"
+
+
+def test_raw_model_pricing_from_per_million_fields() -> None:
+    raw = RawModelPricing(
+        input_cost_per_million_tokens="2",
+        output_cost_per_million_tokens="4",
+    )
+
+    model = raw.to_model_pricing("gpt-4o-mini")
+    assert model.input_cost_per_token == Decimal("0.000002")
+    assert model.output_cost_per_token == Decimal("0.000004")

llmcalc-0.1.0/tests/test_normalize.py

@@ -0,0 +1,20 @@
+from llmcalc.normalize import normalize_model_name, resolve_model_key
+
+
+def test_normalize_model_name_prefixes() -> None:
+    assert normalize_model_name(" openai:gpt-4o-mini ") == "gpt-4o-mini"
+    assert normalize_model_name("openai/gpt-4.1-mini") == "gpt-4.1-mini"
+
+
+def test_normalize_model_name_alias() -> None:
+    assert normalize_model_name("gpt-4o-mini-latest") == "gpt-4o-mini"
+
+
+def test_resolve_model_key_case_insensitive_and_prefixed() -> None:
+    keys = ["GPT-4O-MINI", "claude-3-5-sonnet"]
+    assert resolve_model_key("openai:gpt-4o-mini", keys) == "GPT-4O-MINI"
+
+
+def test_resolve_model_key_missing() -> None:
+    keys = ["gpt-4o-mini"]
+    assert resolve_model_key("unknown-model", keys) is None

llmcalc-0.1.0/tests/test_pricing_client.py

@@ -0,0 +1,125 @@
+from decimal import Decimal
+
+import pytest
+
+from llmcalc.errors import PricingFetchError, PricingSchemaError
+from llmcalc.pricing_client import get_pricing_table, parse_pricing_payload
+
+
+def test_parse_pricing_payload_direct_table() -> None:
+    payload = {
+        "gpt-4o-mini": {
+            "input_cost_per_token": "0.000001",
+            "output_cost_per_token": "0.000002",
+        }
+    }
+
+    table = parse_pricing_payload(payload)
+    assert table["gpt-4o-mini"].input_cost_per_token == Decimal("0.000001")
+
+
+def test_parse_pricing_payload_wrapped_table() -> None:
+    payload = {
+        "data": {
+            "gpt-4o-mini": {
+                "input_cost_per_million_tokens": "2",
+                "output_cost_per_million_tokens": "4",
+            }
+        }
+    }
+
+    table = parse_pricing_payload(payload)
+    assert table["gpt-4o-mini"].output_cost_per_token == Decimal("0.000004")
+
+
+def test_parse_pricing_payload_raises_for_invalid() -> None:
+    with pytest.raises(PricingSchemaError):
+        parse_pricing_payload({"meta": {"foo": "bar"}})
+
+
+def test_parse_pricing_payload_uses_env_currency_fallback(monkeypatch) -> None:
+    monkeypatch.setenv("LLMCALC_CURRENCY", "inr")
+    payload = {
+        "gpt-4o-mini": {
+            "input_cost_per_token": "0.000001",
+            "output_cost_per_token": "0.000002",
+        }
+    }
+
+    table = parse_pricing_payload(payload)
+    assert table["gpt-4o-mini"].currency == "INR"
+
+
+def test_parse_pricing_payload_prefers_payload_currency_over_env(monkeypatch) -> None:
+    monkeypatch.setenv("LLMCALC_CURRENCY", "inr")
+    payload = {
+        "gpt-4o-mini": {
+            "input_cost_per_token": "0.000001",
+            "output_cost_per_token": "0.000002",
+            "currency": "USD",
+        }
+    }
+
+    table = parse_pricing_payload(payload)
+    assert table["gpt-4o-mini"].currency == "USD"
+
+
+@pytest.mark.asyncio
+async def test_get_pricing_table_uses_cache(monkeypatch) -> None:
+    cached = {
+        "gpt-4o-mini": {
+            "input_cost_per_token": "0.000001",
+            "output_cost_per_token": "0.000002",
+        }
+    }
+
+    monkeypatch.setattr("llmcalc.pricing_client.load_cached_pricing", lambda _: cached)
+
+    async def _never_fetch(pricing_url=None):
+        _ = pricing_url
+        raise AssertionError("fetch should not be called when cache is valid")
+
+    monkeypatch.setattr("llmcalc.pricing_client.fetch_pricing_payload", _never_fetch)
+
+    table = await get_pricing_table(cache_timeout=3600)
+    assert "gpt-4o-mini" in table
+
+
+@pytest.mark.asyncio
+async def test_get_pricing_table_fetches_and_saves(monkeypatch) -> None:
+    saved = {"payload": None}
+
+    monkeypatch.setattr("llmcalc.pricing_client.load_cached_pricing", lambda _: None)
+
+    async def _fetch(pricing_url=None):
+        _ = pricing_url
+        return {
+            "gpt-4o-mini": {
+                "input_cost_per_token": "0.000001",
+                "output_cost_per_token": "0.000002",
+            }
+        }
+
+    monkeypatch.setattr("llmcalc.pricing_client.fetch_pricing_payload", _fetch)
+    monkeypatch.setattr(
+        "llmcalc.pricing_client.save_cached_pricing",
+        lambda payload: saved.update(payload=payload),
+    )
+
+    table = await get_pricing_table(cache_timeout=3600)
+    assert "gpt-4o-mini" in table
+    assert saved["payload"] is not None
+
+
+@pytest.mark.asyncio
+async def test_get_pricing_table_raises_when_fetch_fails_without_cache(monkeypatch) -> None:
+    monkeypatch.setattr("llmcalc.pricing_client.load_cached_pricing", lambda _: None)
+
+    async def _fetch(pricing_url=None):
+        _ = pricing_url
+        raise PricingFetchError("failed")
+
+    monkeypatch.setattr("llmcalc.pricing_client.fetch_pricing_payload", _fetch)
+
+    with pytest.raises(PricingFetchError):
+        await get_pricing_table(cache_timeout=3600)