llmcachex-core 0.1.0__py3-none-any.whl

llmcachex/__init__.py

@@ -0,0 +1,7 @@
+"""LLMCacheX - Lightweight LLM/API request optimization library."""
+
+from .decorator import cached_call
+
+__version__ = "0.1.0"
+
+__all__ = ["cached_call", "__version__"]

llmcachex/analytics/__init__.py

@@ -0,0 +1,61 @@
+"""Runtime analytics: events, usage metadata, cost estimation, storage.
+
+This package is provider-independent. It records structured request
+events (cache hits/misses, retries, rate-limit waits), aggregates them
+for the dashboard API, and represents provider-supplied usage and
+configurable cost estimates — never fabricating tokens or prices.
+
+Typical usage::
+
+    from llmcachex.analytics import AnalyticsStore, RequestEvent, EventType
+
+    store = AnalyticsStore("llmcachex.db")
+    store.record(RequestEvent(
+        event_type=EventType.CACHE_MISS,
+        function_name="app.generate",
+        request_hash="abc...",
+        cache_status="miss",
+        success=True,
+    ))
+"""
+
+from .cost import PricingConfig, coerce_decimal, estimate_cost
+from .events import (
+    EVENT_TYPES,
+    HIT_TYPES,
+    REQUEST_EVENT_TYPES,
+    EventType,
+    HitType,
+    RequestEvent,
+)
+from .metrics import (
+    DEFAULT_MAX_EVENTS,
+    AnalyticsStore,
+    AnalyticsSummary,
+    PriorExecution,
+    ProviderAnalytics,
+    TimeSeriesPoint,
+    UsageTotals,
+)
+from .usage import Usage, coerce_usage
+
+__all__ = [
+    "DEFAULT_MAX_EVENTS",
+    "EVENT_TYPES",
+    "HIT_TYPES",
+    "REQUEST_EVENT_TYPES",
+    "AnalyticsStore",
+    "AnalyticsSummary",
+    "EventType",
+    "HitType",
+    "PriorExecution",
+    "PricingConfig",
+    "ProviderAnalytics",
+    "RequestEvent",
+    "TimeSeriesPoint",
+    "Usage",
+    "UsageTotals",
+    "coerce_decimal",
+    "coerce_usage",
+    "estimate_cost",
+]

llmcachex/analytics/cost.py

@@ -0,0 +1,158 @@
+"""Configurable cost estimation (no hardcoded provider pricing).
+
+Prices are *data*, supplied by the developer or a provider adapter:
+LLMCacheX never ships or claims current real-world pricing. All money
+arithmetic uses :class:`decimal.Decimal` to avoid binary floating-point
+rounding in cost-style calculations.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from decimal import Decimal, InvalidOperation
+from typing import Any
+
+from .usage import Usage
+
+__all__ = ["PricingConfig", "estimate_cost", "coerce_decimal"]
+
+_TOKENS_PER_1K = Decimal(1000)
+
+
+def coerce_decimal(value: Any, *, field: str = "value") -> Decimal:
+    """Convert ``int | float | str | Decimal`` to an exact ``Decimal``.
+
+    Floats are routed through ``str()`` first so that e.g. ``0.0025``
+    becomes ``Decimal("0.0025")`` rather than the binary expansion of
+    the float.
+    """
+    if isinstance(value, Decimal):
+        return value
+    if isinstance(value, bool) or not isinstance(value, (int, float, str)):
+        raise ValueError(f"{field} must be a number, got {value!r}.")
+    try:
+        return Decimal(str(value))
+    except InvalidOperation as exc:
+        raise ValueError(f"{field} is not a valid number: {value!r}.") from exc
+
+
+def _check_price(name: str, value: Decimal | None) -> Decimal | None:
+    if value is None:
+        return None
+    if value < 0:
+        raise ValueError(f"{name} must be >= 0, got {value}.")
+    return value
+
+
+@dataclass(frozen=True)
+class PricingConfig:
+    """Prices per 1000 tokens as configured data.
+
+    ``None`` means "price unknown". The configuration is intentionally
+    explicit: no default prices are bundled with the library, so an
+    estimate is only produced when the developer supplied pricing.
+
+    Args:
+        input_cost_per_1k_tokens: Price for 1000 input tokens, or None.
+        output_cost_per_1k_tokens: Price for 1000 output tokens, or None.
+        currency: Optional label (e.g. ``"USD"``) for display only.
+    """
+
+    input_cost_per_1k_tokens: Decimal | None = None
+    output_cost_per_1k_tokens: Decimal | None = None
+    currency: str | None = None
+
+    def __post_init__(self) -> None:
+        _check_price("input_cost_per_1k_tokens", self.input_cost_per_1k_tokens)
+        _check_price("output_cost_per_1k_tokens", self.output_cost_per_1k_tokens)
+
+    @classmethod
+    def from_values(
+        cls,
+        input_cost_per_1k_tokens: Any = None,
+        output_cost_per_1k_tokens: Any = None,
+        currency: str | None = None,
+    ) -> PricingConfig:
+        """Build from plain numbers/strings (converted to Decimal safely)."""
+        return cls(
+            input_cost_per_1k_tokens=(
+                None
+                if input_cost_per_1k_tokens is None
+                else coerce_decimal(
+                    input_cost_per_1k_tokens,
+                    field="input_cost_per_1k_tokens",
+                )
+            ),
+            output_cost_per_1k_tokens=(
+                None
+                if output_cost_per_1k_tokens is None
+                else coerce_decimal(
+                    output_cost_per_1k_tokens,
+                    field="output_cost_per_1k_tokens",
+                )
+            ),
+            currency=currency,
+        )
+
+    def estimate(self, usage: Usage | None) -> Decimal | None:
+        """Estimate cost for ``usage``; ``None`` when it cannot be derived.
+
+        Each side (input/output) contributes only when both its price and
+        its token count are known. If no side is computable the result is
+        ``None`` — never zero — so "unknown" stays distinguishable from
+        "free".
+        """
+        if usage is None:
+            return None
+        parts: list[Decimal] = []
+        if (
+            self.input_cost_per_1k_tokens is not None
+            and usage.input_tokens is not None
+        ):
+            parts.append(
+                Decimal(usage.input_tokens)
+                / _TOKENS_PER_1K
+                * self.input_cost_per_1k_tokens
+            )
+        if (
+            self.output_cost_per_1k_tokens is not None
+            and usage.output_tokens is not None
+        ):
+            parts.append(
+                Decimal(usage.output_tokens)
+                / _TOKENS_PER_1K
+                * self.output_cost_per_1k_tokens
+            )
+        if not parts:
+            return None
+        return sum(parts, Decimal(0))
+
+
+def estimate_cost(
+    usage: Usage | None, pricing: PricingConfig | Mapping[str, Any] | None
+) -> Decimal | None:
+    """Estimate cost from usage + pricing, tolerating unknown inputs."""
+    if pricing is None:
+        return None
+    if isinstance(pricing, Mapping):
+        pricing = PricingConfig(
+            input_cost_per_1k_tokens=(
+                None
+                if pricing.get("input_cost_per_1k_tokens") is None
+                else coerce_decimal(
+                    pricing["input_cost_per_1k_tokens"],
+                    field="input_cost_per_1k_tokens",
+                )
+            ),
+            output_cost_per_1k_tokens=(
+                None
+                if pricing.get("output_cost_per_1k_tokens") is None
+                else coerce_decimal(
+                    pricing["output_cost_per_1k_tokens"],
+                    field="output_cost_per_1k_tokens",
+                )
+            ),
+            currency=pricing.get("currency"),
+        )
+    return pricing.estimate(usage)

llmcachex/analytics/events.py

@@ -0,0 +1,140 @@
+"""Structured request-activity events (metadata only).
+
+One logical call produces at most one *request-level* event
+(``cache_hit`` or ``cache_miss`` — the miss also carries the execution
+outcome), plus one event per discrete ``retry`` attempt and per
+``rate_limit_wait``. The vocabulary is a small extensible set; unknown
+event types are rejected when recording.
+
+Provider/usage/cost fields are ``None`` until real provider metadata
+exists. Nothing here ever stores prompts, responses or API keys.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from decimal import Decimal
+from typing import Final
+
+__all__ = [
+    "EventType",
+    "EVENT_TYPES",
+    "REQUEST_EVENT_TYPES",
+    "HitType",
+    "HIT_TYPES",
+    "RequestEvent",
+    "utc_now_iso",
+]
+
+
+class EventType:
+    """Event vocabulary (plain string constants for easy storage)."""
+
+    CACHE_HIT: Final = "cache_hit"
+    CACHE_MISS: Final = "cache_miss"
+    RETRY: Final = "retry"
+    RATE_LIMIT_WAIT: Final = "rate_limit_wait"
+
+
+class HitType:
+    """How a cache hit was produced (exact hash vs semantic similarity)."""
+
+    EXACT: Final = "exact"
+    SEMANTIC: Final = "semantic"
+
+
+#: Valid ``hit_type`` values for hit events (``None`` elsewhere).
+HIT_TYPES: Final[frozenset[str]] = frozenset(
+    {
+        HitType.EXACT,
+        HitType.SEMANTIC,
+    }
+)
+
+
+#: All currently valid event types. Extensible by adding a constant here.
+EVENT_TYPES: Final[frozenset[str]] = frozenset(
+    {
+        EventType.CACHE_HIT,
+        EventType.CACHE_MISS,
+        EventType.RETRY,
+        EventType.RATE_LIMIT_WAIT,
+    }
+)
+
+#: Event types that count as one logical request.
+REQUEST_EVENT_TYPES: Final[frozenset[str]] = frozenset(
+    {EventType.CACHE_HIT, EventType.CACHE_MISS}
+)
+
+
+def utc_now_iso() -> str:
+    """Current UTC time as a sortable ISO-8601 string."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class RequestEvent:
+    """One analytics record.
+
+    Args:
+        event_type: One of :data:`EVENT_TYPES`.
+        function_name: Dotted function label (``module.qualname``).
+        request_hash: Deterministic request hash (no prompt content).
+        timestamp: ISO-8601 UTC timestamp.
+        cache_status: ``"hit"``, ``"miss"``, or ``None`` for events that
+            are not request-level (retry, rate-limit wait).
+        latency_ms: Measured latency (hit: lookup, miss: execution).
+        retry_count: Retries observed during this request.
+        success: For a miss: did the execution succeed. ``True`` for
+            hits, ``None`` where not applicable.
+        provider: Provider name if known, else ``None``.
+        model: Model name if known, else ``None``.
+        input_tokens / output_tokens / total_tokens: Provider-reported
+            usage, or ``None`` when unknown.
+        request_units: Optional provider-specific billing units.
+        estimated_cost: Cost of executing this request (miss only), or
+            ``None`` when usage/pricing are unavailable.
+        estimated_cost_saved: For a hit: the previously known execution
+            cost that was avoided, or ``None`` when unknown.
+        hit_type: For hit events: ``"exact"`` or ``"semantic"``;
+            ``None`` for misses and non-request events.
+        event_id: Assigned by the store after persistence.
+    """
+
+    event_type: str
+    function_name: str
+    request_hash: str
+    timestamp: str = field(default_factory=utc_now_iso)
+    cache_status: str | None = None
+    latency_ms: float | None = None
+    retry_count: int = 0
+    success: bool | None = None
+    provider: str | None = None
+    model: str | None = None
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    total_tokens: int | None = None
+    request_units: int | None = None
+    estimated_cost: Decimal | None = None
+    estimated_cost_saved: Decimal | None = None
+    hit_type: str | None = None
+    event_id: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.event_type not in EVENT_TYPES:
+            raise ValueError(
+                f"Unknown event type {self.event_type!r}; "
+                f"expected one of {sorted(EVENT_TYPES)}."
+            )
+        if self.cache_status not in (None, "hit", "miss"):
+            raise ValueError(
+                f"cache_status must be 'hit', 'miss' or None, "
+                f"got {self.cache_status!r}."
+            )
+        if self.hit_type is not None and self.hit_type not in HIT_TYPES:
+            raise ValueError(
+                f"hit_type must be 'exact', 'semantic' or None, "
+                f"got {self.hit_type!r}."
+            )