llmslim 0.1.0__py3-none-any.whl

llmslim/__init__.py

@@ -0,0 +1,30 @@
+"""llmslim: cut LLM prompt size by 40-70% with one function call.
+
+Quickstart:
+    >>> from llmslim import compress
+    >>> result = compress(my_long_prompt, target_ratio=0.5)
+    >>> print(result.compressed_text)
+    >>> print(result.summary())
+"""
+
+from .core import CompressionResult, ContextCompressor, compress
+from .cost import CostEstimate, MODEL_PRICING, estimate_cost_savings, list_supported_models
+from .pipelines import compress_chat_messages, compress_documents
+from .tokens import count_tokens, count_tokens_batch
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "compress",
+    "ContextCompressor",
+    "CompressionResult",
+    "compress_chat_messages",
+    "compress_documents",
+    "estimate_cost_savings",
+    "list_supported_models",
+    "CostEstimate",
+    "MODEL_PRICING",
+    "count_tokens",
+    "count_tokens_batch",
+    "__version__",
+]

llmslim/chunking.py

@@ -0,0 +1,105 @@
+"""Semantic chunking: group consecutive sentences into coherent chunks.
+
+A new chunk is started whenever a sentence's embedding drifts too far
+from the running topic centroid (a topic shift) or the chunk would
+exceed a maximum token budget. This keeps each chunk focused on a single
+idea, which makes per-chunk extractive ranking far more meaningful than
+ranking sentences across an entire document at once.
+"""
+
+from __future__ import annotations
+
+from typing import List, Sequence
+
+import numpy as np
+
+from .tokens import count_tokens
+
+
+class Chunk:
+    """A semantically coherent group of consecutive sentences."""
+
+    __slots__ = ("sentence_indices", "sentences", "token_counts", "total_tokens")
+
+    def __init__(self, sentence_indices: List[int], sentences: List[str], token_counts: List[int]):
+        self.sentence_indices = sentence_indices
+        self.sentences = sentences
+        self.token_counts = token_counts
+        self.total_tokens = sum(token_counts)
+
+    def __len__(self) -> int:
+        return len(self.sentence_indices)
+
+    def __repr__(self) -> str:
+        preview = self.sentences[0][:40] + "..." if self.sentences else ""
+        return f"Chunk(n_sentences={len(self)}, tokens={self.total_tokens}, starts_with={preview!r})"
+
+
+def _cosine(a: np.ndarray, b: np.ndarray) -> float:
+    na = float(np.linalg.norm(a))
+    nb = float(np.linalg.norm(b))
+    if na == 0.0 or nb == 0.0:
+        return 0.0
+    return float(np.dot(a, b) / (na * nb))
+
+
+def semantic_chunk(
+    sentences: Sequence[str],
+    embeddings: np.ndarray,
+    max_chunk_tokens: int = 180,
+    similarity_threshold: float = 0.35,
+) -> List[Chunk]:
+    """Group ``sentences`` into semantically coherent :class:`Chunk` objects.
+
+    Args:
+        sentences: Sentences in original document order.
+        embeddings: Array of shape ``(len(sentences), dim)``.
+        max_chunk_tokens: Soft cap on the token size of a chunk.
+        similarity_threshold: Minimum cosine similarity to the running
+            chunk centroid required to add a sentence to the current
+            chunk. Lower values produce fewer, larger chunks.
+
+    Returns:
+        List of :class:`Chunk` objects covering every input sentence,
+        in original order.
+    """
+    if not sentences:
+        return []
+
+    token_counts = [count_tokens(s) for s in sentences]
+
+    chunks: List[Chunk] = []
+    current_indices: List[int] = [0]
+    current_embs: List[np.ndarray] = [embeddings[0]]
+    current_tokens = token_counts[0]
+
+    for i in range(1, len(sentences)):
+        sent_tokens = token_counts[i]
+        centroid = np.mean(current_embs, axis=0)
+        similarity = _cosine(embeddings[i], centroid)
+
+        starts_new_chunk = (
+            similarity < similarity_threshold
+            or current_tokens + sent_tokens > max_chunk_tokens
+        )
+
+        if starts_new_chunk and current_indices:
+            chunks.append(_build_chunk(current_indices, sentences, token_counts))
+            current_indices = [i]
+            current_embs = [embeddings[i]]
+            current_tokens = sent_tokens
+        else:
+            current_indices.append(i)
+            current_embs.append(embeddings[i])
+            current_tokens += sent_tokens
+
+    if current_indices:
+        chunks.append(_build_chunk(current_indices, sentences, token_counts))
+
+    return chunks
+
+
+def _build_chunk(indices: List[int], sentences: Sequence[str], token_counts: List[int]) -> Chunk:
+    chunk_sentences = [sentences[i] for i in indices]
+    chunk_token_counts = [token_counts[i] for i in indices]
+    return Chunk(list(indices), chunk_sentences, chunk_token_counts)

llmslim/cli.py

@@ -0,0 +1,90 @@
+"""Command-line interface for llmslim.
+
+Usage:
+    llmslim input.txt -r 0.5 -o compressed.txt --stats
+    cat prompt.txt | llmslim --ratio 0.4 --cost gpt-5
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .core import compress
+from .cost import estimate_cost_savings, list_supported_models
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="llmslim",
+        description="Compress text/prompts to reduce LLM token usage by 40-70%.",
+    )
+    parser.add_argument(
+        "input",
+        nargs="?",
+        help="Path to an input text file. Reads from stdin if omitted.",
+    )
+    parser.add_argument(
+        "-r", "--ratio", type=float, default=0.5,
+        help="Target fraction of tokens to keep, e.g. 0.5 = 50%% reduction (default: 0.5).",
+    )
+    parser.add_argument(
+        "-q", "--query", type=str, default=None,
+        help="Optional query for relevance-aware compression (RAG use case).",
+    )
+    parser.add_argument(
+        "-o", "--output", type=str, default=None,
+        help="Write compressed text to this file instead of stdout.",
+    )
+    parser.add_argument(
+        "--stats", action="store_true",
+        help="Print compression statistics to stderr.",
+    )
+    parser.add_argument(
+        "--cost", type=str, default=None, metavar="MODEL",
+        help=f"Print a cost-savings estimate for MODEL. Options: {', '.join(list_supported_models())}",
+    )
+    parser.add_argument(
+        "--requests-per-day", type=int, default=1000,
+        help="Request volume used for --cost estimates (default: 1000).",
+    )
+    return parser
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.input:
+        with open(args.input, "r", encoding="utf-8") as f:
+            text = f.read()
+    else:
+        text = sys.stdin.read()
+
+    result = compress(text, target_ratio=args.ratio, query=args.query)
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(result.compressed_text)
+    else:
+        print(result.compressed_text)
+
+    if args.stats:
+        print("\n--- Compression Stats ---", file=sys.stderr)
+        print(result.summary(), file=sys.stderr)
+
+    if args.cost:
+        print("\n--- Cost Savings Estimate ---", file=sys.stderr)
+        estimate = estimate_cost_savings(
+            result.original_tokens,
+            result.compressed_tokens,
+            model=args.cost,
+            requests_per_day=args.requests_per_day,
+        )
+        print(estimate.summary(), file=sys.stderr)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

llmslim/core.py

@@ -0,0 +1,354 @@
+"""Core compression engine.
+
+This module ties together sentence splitting, semantic chunking,
+extractive ranking, and budget-aware selection into the main
+:func:`compress` function and :class:`ContextCompressor` class.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Sequence
+
+import numpy as np
+
+from .chunking import Chunk, semantic_chunk
+from .embeddings import EmbeddingBackend, get_default_backend
+from .ranking import score_chunk_sentences
+from .tokenization import split_paragraphs, split_sentences
+from .tokens import count_tokens
+
+# Below this many tokens, compression overhead isn't worth it and the
+# original text is returned unchanged.
+DEFAULT_MIN_TOKENS_FOR_COMPRESSION = 40
+
+_LIST_ITEM_RE = re.compile(r"^\s*(#{1,6}\s|[-*+]\s|\d+[.)]\s)")
+
+
+@dataclass
+class ChunkResult:
+    """Per-chunk compression detail, useful for debugging and analytics."""
+
+    text: str
+    original_tokens: int
+    compressed_tokens: int
+    sentences_total: int
+    sentences_kept: int
+
+
+@dataclass
+class CompressionResult:
+    """The result of compressing a piece of text.
+
+    The compressed text is available both as ``.compressed_text`` and via
+    ``str(result)``, so it can often be dropped directly into an existing
+    prompt-building pipeline.
+    """
+
+    original_text: str
+    compressed_text: str
+    original_tokens: int
+    compressed_tokens: int
+    target_ratio: float
+    sentences_total: int
+    sentences_kept: int
+    num_chunks: int
+    backend: str = ""
+    chunk_results: List[ChunkResult] = field(default_factory=list, repr=False)
+
+    @property
+    def actual_ratio(self) -> float:
+        """Fraction of original tokens retained (lower = more compression)."""
+        if self.original_tokens == 0:
+            return 1.0
+        return self.compressed_tokens / self.original_tokens
+
+    @property
+    def reduction_percent(self) -> float:
+        """Percentage reduction in token count."""
+        return round((1 - self.actual_ratio) * 100, 1)
+
+    @property
+    def tokens_saved(self) -> int:
+        return self.original_tokens - self.compressed_tokens
+
+    def summary(self) -> str:
+        """A human-readable summary of the compression result."""
+        target_reduction = round((1 - self.target_ratio) * 100, 1)
+        return (
+            f"Original tokens : {self.original_tokens}\n"
+            f"Compressed tokens: {self.compressed_tokens}\n"
+            f"Reduction        : {self.reduction_percent}% (target ~{target_reduction}%)\n"
+            f"Sentences kept   : {self.sentences_kept}/{self.sentences_total}\n"
+            f"Chunks           : {self.num_chunks}\n"
+            f"Embedding backend: {self.backend}"
+        )
+
+    def __str__(self) -> str:
+        return self.compressed_text
+
+
+class ContextCompressor:
+    """Compresses text via semantic chunking + extractive sentence ranking.
+
+    Example:
+        >>> compressor = ContextCompressor()
+        >>> result = compressor.compress(long_text, target_ratio=0.5)
+        >>> print(result.compressed_text)
+        >>> print(result.summary())
+
+    Args:
+        embedding_backend: Custom :class:`EmbeddingBackend`. Defaults to
+            :func:`get_default_backend` (sentence-transformers if
+            available, otherwise TF-IDF).
+        max_chunk_tokens: Soft token cap per semantic chunk.
+        similarity_threshold: Cosine similarity below which a new chunk
+            is started. Lower values create fewer, larger chunks.
+        min_tokens_for_compression: Texts at or below this token count
+            are returned unchanged.
+        weights: Optional overrides for ranking weights -- see
+            ``llmslim.ranking.DEFAULT_WEIGHTS``.
+        preserve_patterns: Optional list of regex strings; any sentence
+            matching one of these is always retained (e.g.
+            ``[r"API_KEY", r"^System:"]``).
+    """
+
+    def __init__(
+        self,
+        embedding_backend: Optional[EmbeddingBackend] = None,
+        max_chunk_tokens: int = 300,
+        similarity_threshold: float = 0.35,
+        min_tokens_for_compression: int = DEFAULT_MIN_TOKENS_FOR_COMPRESSION,
+        weights: Optional[Dict[str, float]] = None,
+        preserve_patterns: Optional[Sequence[str]] = None,
+    ):
+        self.backend = embedding_backend or get_default_backend()
+        self.max_chunk_tokens = max_chunk_tokens
+        self.similarity_threshold = similarity_threshold
+        self.min_tokens_for_compression = min_tokens_for_compression
+        self.weights = weights
+        self.preserve_patterns = list(preserve_patterns or [])
+
+    def compress(
+        self,
+        text: str,
+        target_ratio: float = 0.5,
+        query: Optional[str] = None,
+    ) -> CompressionResult:
+        """Compress ``text``, retaining approximately ``target_ratio`` of its tokens.
+
+        Args:
+            text: The prompt or document to compress.
+            target_ratio: Fraction of original tokens to retain
+                (e.g. ``0.5`` keeps ~50%, i.e. a ~50% reduction).
+                Must be in ``(0, 1]``.
+            query: Optional query string. When provided, sentences more
+                similar to the query are favored -- ideal for compressing
+                retrieved documents in a RAG pipeline.
+
+        Returns:
+            A :class:`CompressionResult`.
+        """
+        if not (0.0 < target_ratio <= 1.0):
+            raise ValueError("target_ratio must be in the range (0, 1]")
+
+        original_tokens = count_tokens(text)
+
+        if original_tokens <= self.min_tokens_for_compression:
+            return self._passthrough(text, original_tokens, target_ratio, sentences_total=0)
+
+        paragraphs = split_paragraphs(text)
+        all_sentences: List[str] = []
+        para_end_indices: List[int] = []
+        for paragraph in paragraphs:
+            sentences = split_sentences(paragraph)
+            if not sentences:
+                continue
+            all_sentences.extend(sentences)
+            para_end_indices.append(len(all_sentences))
+
+        if len(all_sentences) <= 1:
+            return self._passthrough(text, original_tokens, target_ratio, sentences_total=len(all_sentences))
+
+        embeddings, query_embedding = self._encode(all_sentences, query)
+
+        chunks = semantic_chunk(
+            all_sentences,
+            embeddings,
+            max_chunk_tokens=self.max_chunk_tokens,
+            similarity_threshold=self.similarity_threshold,
+        )
+
+        kept_mask = np.zeros(len(all_sentences), dtype=bool)
+        chunk_results: List[ChunkResult] = []
+
+        for chunk in chunks:
+            chunk_embeddings = embeddings[chunk.sentence_indices]
+            scored = score_chunk_sentences(
+                chunk,
+                chunk_embeddings,
+                query_embedding=query_embedding,
+                weights=self.weights,
+                preserve_patterns=self.preserve_patterns,
+            )
+            kept_local = self._select_for_chunk(scored, chunk.token_counts, target_ratio)
+
+            for local_idx in kept_local:
+                kept_mask[chunk.sentence_indices[local_idx]] = True
+
+            kept_tokens = sum(chunk.token_counts[i] for i in kept_local)
+            chunk_results.append(
+                ChunkResult(
+                    text=" ".join(chunk.sentences[i] for i in sorted(kept_local)),
+                    original_tokens=chunk.total_tokens,
+                    compressed_tokens=kept_tokens,
+                    sentences_total=len(chunk.sentences),
+                    sentences_kept=len(kept_local),
+                )
+            )
+
+        compressed_text = self._reassemble(all_sentences, kept_mask, para_end_indices)
+        compressed_tokens = count_tokens(compressed_text)
+
+        return CompressionResult(
+            original_text=text,
+            compressed_text=compressed_text,
+            original_tokens=original_tokens,
+            compressed_tokens=compressed_tokens,
+            target_ratio=target_ratio,
+            sentences_total=len(all_sentences),
+            sentences_kept=int(kept_mask.sum()),
+            num_chunks=len(chunks),
+            backend=self.backend.name,
+            chunk_results=chunk_results,
+        )
+
+    def _passthrough(self, text: str, original_tokens: int, target_ratio: float, sentences_total: int) -> CompressionResult:
+        return CompressionResult(
+            original_text=text,
+            compressed_text=text,
+            original_tokens=original_tokens,
+            compressed_tokens=original_tokens,
+            target_ratio=target_ratio,
+            sentences_total=sentences_total,
+            sentences_kept=sentences_total,
+            num_chunks=0,
+            backend=self.backend.name,
+        )
+
+    def _encode(self, sentences: List[str], query: Optional[str]):
+        """Encode sentences (and optionally a query) with a single, consistent vector space."""
+        texts = list(sentences)
+        if query:
+            texts.append(query)
+
+        encoded = np.asarray(self.backend.encode(texts))
+
+        if query:
+            return encoded[:-1], encoded[-1]
+        return encoded, None
+
+    @staticmethod
+    def _select_for_chunk(scored: List[Dict], token_counts: List[int], target_ratio: float) -> set:
+        """Greedily select sentence indices for a chunk within its token budget."""
+        total_tokens = sum(token_counts)
+        target_tokens = max(1, round(total_tokens * target_ratio))
+
+        must_keep = [s for s in scored if s["must_keep"]]
+        optional = sorted(
+            (s for s in scored if not s["must_keep"]),
+            key=lambda s: s["score"],
+            reverse=True,
+        )
+
+        selected = {s["index"] for s in must_keep}
+        used_tokens = sum(token_counts[i] for i in selected)
+
+        if used_tokens > target_tokens:
+            # Too many must-keep sentences for the budget: keep the
+            # highest-scoring ones until we exceed the budget, but always
+            # keep at least one sentence.
+            must_sorted = sorted(must_keep, key=lambda s: s["score"], reverse=True)
+            selected = set()
+            used_tokens = 0
+            for s in must_sorted:
+                if not selected or used_tokens + token_counts[s["index"]] <= target_tokens:
+                    selected.add(s["index"])
+                    used_tokens += token_counts[s["index"]]
+        else:
+            for s in optional:
+                if used_tokens >= target_tokens:
+                    break
+                if used_tokens + token_counts[s["index"]] <= target_tokens:
+                    selected.add(s["index"])
+                    used_tokens += token_counts[s["index"]]
+
+        if not selected:
+            best = max(scored, key=lambda s: s["score"])
+            selected.add(best["index"])
+
+        return selected
+
+    @staticmethod
+    def _reassemble(sentences: List[str], kept_mask: np.ndarray, para_end_indices: List[int]) -> str:
+        """Rebuild paragraphs from kept sentences, preserving list formatting."""
+        paragraphs_out: List[str] = []
+        start = 0
+        for end in para_end_indices:
+            kept_sentences = [s for s, keep in zip(sentences[start:end], kept_mask[start:end]) if keep]
+            start = end
+            if not kept_sentences:
+                continue
+            if len(kept_sentences) > 1 and all(_LIST_ITEM_RE.match(s) for s in kept_sentences):
+                paragraphs_out.append("\n".join(kept_sentences))
+            else:
+                paragraphs_out.append(" ".join(kept_sentences))
+        return "\n\n".join(paragraphs_out)
+
+
+_default_compressor: Optional[ContextCompressor] = None
+
+
+def _get_default_compressor() -> ContextCompressor:
+    global _default_compressor
+    if _default_compressor is None:
+        _default_compressor = ContextCompressor()
+    return _default_compressor
+
+
+def compress(
+    text: str,
+    target_ratio: float = 0.5,
+    query: Optional[str] = None,
+    **kwargs,
+) -> CompressionResult:
+    """Compress ``text``, retaining approximately ``target_ratio`` of its tokens.
+
+    This is the main entry point for the library -- a single function
+    call that performs semantic chunking, extractive ranking, and
+    reassembly.
+
+    Args:
+        text: The prompt or document to compress.
+        target_ratio: Fraction of original tokens to retain (e.g. ``0.5``
+            for a ~50% reduction, ``0.3`` for a ~70% reduction).
+        query: Optional query string for relevance-aware compression
+            (useful for RAG contexts).
+        **kwargs: Passed to :class:`ContextCompressor` if provided (e.g.
+            ``max_chunk_tokens``, ``similarity_threshold``,
+            ``preserve_patterns``). If no kwargs are given, a shared
+            default compressor instance is reused for efficiency.
+
+    Returns:
+        A :class:`CompressionResult` with ``.compressed_text``,
+        ``.reduction_percent``, and other statistics.
+
+    Example:
+        >>> from llmslim import compress
+        >>> result = compress(my_long_prompt, target_ratio=0.5)
+        >>> send_to_llm(result.compressed_text)
+        >>> print(f"Saved {result.tokens_saved} tokens ({result.reduction_percent}%)")
+    """
+    compressor = ContextCompressor(**kwargs) if kwargs else _get_default_compressor()
+    return compressor.compress(text, target_ratio=target_ratio, query=query)

llmslim/cost.py

@@ -0,0 +1,117 @@
+"""Cost savings estimation for compressed prompts.
+
+Provides rough, easily-updatable per-1K-token pricing for popular models
+so users can quickly translate token reductions into dollar savings at
+their own request volume.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List
+
+# Approximate USD price per 1,000 *input* tokens. These are illustrative
+# and change frequently -- always check current provider pricing pages
+# for production cost calculations.
+MODEL_PRICING: Dict[str, Dict[str, float]] = {
+    "gpt-5": {"input": 0.00125, "output": 0.0100},
+    "gpt-4o": {"input": 0.00250, "output": 0.0100},
+    "gpt-5.4": {"input": 0.00250, "output": 0.0150},
+    "gpt-5-mini": {"input": 0.00025, "output": 0.0020},
+    "claude-opus-4.8": {"input": 0.00500, "output": 0.0250},
+    "claude-sonnet-4.6": {"input": 0.00300, "output": 0.0150},
+    "claude-haiku-4.5": {"input": 0.00100, "output": 0.0050},
+    "gemini-2.5-pro": {"input": 0.00125, "output": 0.0050},
+    "gemini-1.5-pro": {"input": 0.00125, "output": 0.0050},
+    "gemini-2.5-flash": {"input": 0.000075, "output": 0.00030},
+    "gemini-2.5-flash-lite": {"input": 0.00010, "output": 0.0004},
+    "mistral-large-3": {"input": 0.00100, "output": 0.00300},
+    "mistral-small-4": {"input": 0.00010, "output": 0.0003},
+    "deepseek-v3": {"input": 0.00014, "output": 0.00028},
+    "deepseek-r1.5": {"input": 0.00055, "output": 0.00219},
+}
+
+
+@dataclass
+class CostEstimate:
+    """Estimated cost savings from a compression result."""
+
+    model: str
+    original_tokens: int
+    compressed_tokens: int
+    tokens_saved: int
+    reduction_percent: float
+    requests_per_day: int
+    price_per_1k_input: float
+    daily_savings_usd: float
+    monthly_savings_usd: float
+    annual_savings_usd: float
+
+    def summary(self) -> str:
+        return (
+            f"Model: {self.model} (${self.price_per_1k_input}/1K input tokens)\n"
+            f"Tokens saved per request: {self.tokens_saved} ({self.reduction_percent}%)\n"
+            f"At {self.requests_per_day:,} requests/day:\n"
+            f"  Daily savings:   ${self.daily_savings_usd:,.2f}\n"
+            f"  Monthly savings: ${self.monthly_savings_usd:,.2f}\n"
+            f"  Annual savings:  ${self.annual_savings_usd:,.2f}"
+        )
+
+    def __str__(self) -> str:
+        return self.summary()
+
+
+def estimate_cost_savings(
+    original_tokens: int,
+    compressed_tokens: int,
+    model: str = "gpt-5",
+    requests_per_day: int = 1000,
+) -> CostEstimate:
+    """Estimate dollar savings from compressing prompts at scale.
+
+    Args:
+        original_tokens: Token count before compression.
+        compressed_tokens: Token count after compression.
+        model: One of the keys in :data:`MODEL_PRICING`.
+        requests_per_day: Expected daily request volume.
+
+    Returns:
+        A :class:`CostEstimate` with daily/monthly/annual savings.
+
+    Example:
+        >>> from llmslim import compress, estimate_cost_savings
+        >>> result = compress(prompt, target_ratio=0.5)
+        >>> cost = estimate_cost_savings(
+        ...     result.original_tokens, result.compressed_tokens,
+        ...     model="gpt-5", requests_per_day=50_000,
+        ... )
+        >>> print(cost.summary())
+    """
+    if model not in MODEL_PRICING:
+        available = ", ".join(sorted(MODEL_PRICING))
+        raise ValueError(f"Unknown model '{model}'. Available models: {available}")
+
+    price_per_1k_input = MODEL_PRICING[model]["input"]
+    tokens_saved = max(0, original_tokens - compressed_tokens)
+    reduction_percent = round((tokens_saved / original_tokens) * 100, 1) if original_tokens else 0.0
+
+    daily_saved_tokens = tokens_saved * requests_per_day
+    daily_savings = (daily_saved_tokens / 1000) * price_per_1k_input
+
+    return CostEstimate(
+        model=model,
+        original_tokens=original_tokens,
+        compressed_tokens=compressed_tokens,
+        tokens_saved=tokens_saved,
+        reduction_percent=reduction_percent,
+        requests_per_day=requests_per_day,
+        price_per_1k_input=price_per_1k_input,
+        daily_savings_usd=round(daily_savings, 4),
+        monthly_savings_usd=round(daily_savings * 30, 2),
+        annual_savings_usd=round(daily_savings * 365, 2),
+    )
+
+
+def list_supported_models() -> List[str]:
+    """Return the list of model names recognized by :func:`estimate_cost_savings`."""
+    return sorted(MODEL_PRICING)