codebase-receipts-cli 1.0.0__py3-none-any.whl

receipts/ledger/pricing_table.py

@@ -0,0 +1,54 @@
+"""Per-provider, per-model pricing in dollars per 1K tokens.
+
+Ollama is always $0 (local). For paid providers the prices here are
+approximate list prices as of mid-2026 — the ledger uses them for cost
+*estimates*, not billing. When a model isn't in the table the ledger
+falls back to $0 and labels the cost as unknown.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ModelPricing:
+    input_per_1k: float
+    output_per_1k: float
+
+
+_TABLE: dict[str, dict[str, ModelPricing]] = {
+    "ollama": {},
+    "gemini": {
+        "gemini-3.5-flash": ModelPricing(0.0, 0.0),
+        "gemini-3.1-flash-lite": ModelPricing(0.0, 0.0),
+        "gemini-2.5-flash-lite": ModelPricing(0.0, 0.0),
+        "gemini-2.0-flash": ModelPricing(0.0, 0.0),
+        "gemini-embedding-2": ModelPricing(0.0, 0.0),
+        "gemini-embedding-001": ModelPricing(0.0, 0.0),
+    },
+    "anthropic": {
+        "claude-sonnet-4-20250514": ModelPricing(0.003, 0.015),
+        "claude-haiku-3-5-20241022": ModelPricing(0.0008, 0.004),
+    },
+    "openai": {
+        "gpt-4o-mini": ModelPricing(0.00015, 0.0006),
+        "gpt-4o": ModelPricing(0.0025, 0.01),
+        "text-embedding-3-small": ModelPricing(0.00002, 0.0),
+    },
+    "fake": {},
+}
+
+
+def cost_estimate(
+    provider: str, model: str, input_tokens: int, output_tokens: int
+) -> float:
+    """Estimated cost in USD. Returns 0.0 for local/free providers."""
+    provider_table = _TABLE.get(provider, {})
+    pricing = provider_table.get(model)
+    if pricing is None:
+        return 0.0
+    return (
+        input_tokens / 1000 * pricing.input_per_1k
+        + output_tokens / 1000 * pricing.output_per_1k
+    )

receipts/ledger/token_ledger.py

@@ -0,0 +1,226 @@
+"""SQLite-backed token/cost ledger — per-session and lifetime.
+
+Every LLM call is logged here, even for free providers (Ollama cost = $0).
+The ledger is a local file under ``~/.receipts/ledger.db`` by default.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+
+from receipts.ledger.pricing_table import cost_estimate
+from receipts.llm.provider import CompletionResult
+
+_DEFAULT_DB_PATH = Path.home() / ".receipts" / "ledger.db"
+
+_CREATE_TABLE = """\
+CREATE TABLE IF NOT EXISTS ledger (
+    id TEXT PRIMARY KEY,
+    session_id TEXT NOT NULL,
+    timestamp REAL NOT NULL,
+    provider TEXT NOT NULL,
+    model TEXT NOT NULL,
+    input_tokens INTEGER NOT NULL,
+    output_tokens INTEGER NOT NULL,
+    tokens_estimated INTEGER NOT NULL,
+    cost_usd REAL NOT NULL
+)"""
+
+_CREATE_INDEX = """\
+CREATE INDEX IF NOT EXISTS idx_ledger_session
+ON ledger (session_id)"""
+
+_INSERT = """\
+INSERT INTO ledger
+    (id, session_id, timestamp, provider, model,
+     input_tokens, output_tokens, tokens_estimated, cost_usd)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"""
+
+
+@dataclass(frozen=True)
+class LedgerEntry:
+    id: str
+    session_id: str
+    timestamp: float
+    provider: str
+    model: str
+    input_tokens: int
+    output_tokens: int
+    tokens_estimated: bool
+    cost_usd: float
+
+
+@dataclass(frozen=True)
+class SessionSummary:
+    session_id: str
+    total_input: int
+    total_output: int
+    total_cost: float
+    call_count: int
+
+
+@dataclass(frozen=True)
+class LifetimeSummary:
+    total_input: int
+    total_output: int
+    total_cost: float
+    call_count: int
+    session_count: int
+
+
+@dataclass(frozen=True)
+class ModelUsage:
+    provider: str
+    model: str
+    call_count: int
+    total_input: int
+    total_output: int
+    total_cost: float
+
+
+class TokenLedger:
+    """Append-only token/cost log backed by SQLite."""
+
+    def __init__(
+        self,
+        db_path: Path | None = None,
+        session_id: str | None = None,
+    ) -> None:
+        self.db_path = db_path or _DEFAULT_DB_PATH
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self.session_id = session_id or uuid.uuid4().hex[:12]
+        self._conn = sqlite3.connect(str(self.db_path))
+        self._conn.execute(_CREATE_TABLE)
+        self._conn.execute(_CREATE_INDEX)
+        self._conn.commit()
+        self._session_entries: list[LedgerEntry] = []
+
+    def log(self, result: CompletionResult) -> LedgerEntry:
+        """Record a completed LLM call and return the entry."""
+        cost = cost_estimate(
+            result.provider,
+            result.model,
+            result.input_tokens,
+            result.output_tokens,
+        )
+        entry = LedgerEntry(
+            id=uuid.uuid4().hex[:16],
+            session_id=self.session_id,
+            timestamp=time.time(),
+            provider=result.provider,
+            model=result.model,
+            input_tokens=result.input_tokens,
+            output_tokens=result.output_tokens,
+            tokens_estimated=result.tokens_estimated,
+            cost_usd=cost,
+        )
+        self._conn.execute(
+            _INSERT,
+            (
+                entry.id,
+                entry.session_id,
+                entry.timestamp,
+                entry.provider,
+                entry.model,
+                entry.input_tokens,
+                entry.output_tokens,
+                int(entry.tokens_estimated),
+                entry.cost_usd,
+            ),
+        )
+        self._conn.commit()
+        self._session_entries.append(entry)
+        return entry
+
+    def session_summary(self) -> SessionSummary:
+        """Summary of the current session from in-memory entries."""
+        total_in = sum(e.input_tokens for e in self._session_entries)
+        total_out = sum(e.output_tokens for e in self._session_entries)
+        total_cost = sum(e.cost_usd for e in self._session_entries)
+        return SessionSummary(
+            session_id=self.session_id,
+            total_input=total_in,
+            total_output=total_out,
+            total_cost=total_cost,
+            call_count=len(self._session_entries),
+        )
+
+    def model_breakdown(self) -> list[ModelUsage]:
+        """Lifetime usage per (provider, model), heaviest first."""
+        rows = self._conn.execute(
+            "SELECT provider, model, COUNT(*),"
+            " COALESCE(SUM(input_tokens), 0),"
+            " COALESCE(SUM(output_tokens), 0),"
+            " COALESCE(SUM(cost_usd), 0)"
+            " FROM ledger GROUP BY provider, model"
+            " ORDER BY SUM(input_tokens) + SUM(output_tokens) DESC"
+        ).fetchall()
+        return [
+            ModelUsage(
+                provider=r[0],
+                model=r[1],
+                call_count=r[2],
+                total_input=r[3],
+                total_output=r[4],
+                total_cost=r[5],
+            )
+            for r in rows
+        ]
+
+    def last_session_summary(self) -> SessionSummary | None:
+        """Summary of the most recent session recorded in the database.
+
+        Unlike :meth:`session_summary` (this process's in-memory entries),
+        this answers "what did my last run cost?" after the fact — each CLI
+        invocation is its own session, so a fresh ``TokenLedger`` always has
+        an empty in-memory session.
+        """
+        # rowid breaks timestamp ties (two calls can share a clock tick):
+        # insertion order is the ground truth for "most recent".
+        row = self._conn.execute(
+            "SELECT session_id FROM ledger ORDER BY timestamp DESC, rowid DESC"
+            " LIMIT 1"
+        ).fetchone()
+        if row is None:
+            return None
+        sid = row[0]
+        agg = self._conn.execute(
+            "SELECT COALESCE(SUM(input_tokens), 0),"
+            " COALESCE(SUM(output_tokens), 0),"
+            " COALESCE(SUM(cost_usd), 0),"
+            " COUNT(*)"
+            " FROM ledger WHERE session_id = ?",
+            (sid,),
+        ).fetchone()
+        return SessionSummary(
+            session_id=sid,
+            total_input=agg[0],
+            total_output=agg[1],
+            total_cost=agg[2],
+            call_count=agg[3],
+        )
+
+    def lifetime_summary(self) -> LifetimeSummary:
+        """Aggregate across all sessions from the database."""
+        row = self._conn.execute(
+            "SELECT COALESCE(SUM(input_tokens), 0),"
+            " COALESCE(SUM(output_tokens), 0),"
+            " COALESCE(SUM(cost_usd), 0),"
+            " COUNT(*),"
+            " COUNT(DISTINCT session_id)"
+            " FROM ledger"
+        ).fetchone()
+        return LifetimeSummary(
+            total_input=row[0],
+            total_output=row[1],
+            total_cost=row[2],
+            call_count=row[3],
+            session_count=row[4],
+        )
+
+    def close(self) -> None:
+        self._conn.close()

receipts/llm/anthropic_provider.py

@@ -0,0 +1,95 @@
+"""Anthropic provider — BYOK adapter for end users with their own API key.
+
+Not used in the maintainer's own testing (no paid key). Exists so end users
+who prefer Claude can ``pip install codebase-receipts-cli[anthropic]`` and
+set ``RECEIPTS_PROVIDER=anthropic`` with their own key.
+
+API facts verified against the installed anthropic 0.116.0 package:
+``client.messages.create`` takes ``model``, ``max_tokens``, ``system``
+(string), ``messages`` (list of dicts). Response has ``.content`` (list of
+ContentBlock), ``.usage`` with ``input_tokens`` and ``output_tokens``.
+Errors: ``AuthenticationError``, ``RateLimitError``, ``NotFoundError``.
+Anthropic does not offer an embeddings API, so ``embed`` raises.
+"""
+
+from __future__ import annotations
+
+import anthropic
+
+from receipts.errors import ProviderConfigError, ProviderUnavailableError
+from receipts.llm.provider import CompletionResult, LLMProvider
+
+_MISSING_KEY_HELP = """\
+No Anthropic API key configured.
+  Set ANTHROPIC_API_KEY=<your key> in your environment or local .env file.
+  This is a paid API — see https://console.anthropic.com/ for pricing."""
+
+_BAD_KEY_HELP = """\
+Anthropic rejected your API key.
+  Check that ANTHROPIC_API_KEY is set to a valid key from
+  https://console.anthropic.com/ (no quotes, no extra spaces)."""
+
+_NO_EMBED_HELP = """\
+Anthropic does not offer an embeddings API.
+  Use a different provider for ingestion (e.g. RECEIPTS_PROVIDER=ollama),
+  then switch to anthropic for verification/rewriting only."""
+
+
+class AnthropicProvider(LLMProvider):
+    name = "anthropic"
+
+    def __init__(
+        self, *, api_key: str | None, chat_model: str, max_tokens: int = 4096
+    ) -> None:
+        if not api_key:
+            raise ProviderConfigError(_MISSING_KEY_HELP)
+        self.chat_model = chat_model
+        self.max_tokens = max_tokens
+        self._client = anthropic.Anthropic(api_key=api_key)
+
+    def complete(
+        self, system: str, user: str, *, json_mode: bool = False
+    ) -> CompletionResult:
+        messages = [{"role": "user", "content": user}]
+        try:
+            response = self._client.messages.create(
+                model=self.chat_model,
+                max_tokens=self.max_tokens,
+                system=system,
+                messages=messages,
+            )
+        except anthropic.AuthenticationError as exc:
+            raise ProviderConfigError(_BAD_KEY_HELP) from exc
+        except anthropic.RateLimitError as exc:
+            raise ProviderUnavailableError(
+                "Anthropic rate limit hit. Wait and retry, or switch to a"
+                " local provider: set RECEIPTS_PROVIDER=ollama."
+            ) from exc
+        except anthropic.NotFoundError as exc:
+            raise ProviderConfigError(
+                f"Anthropic model '{self.chat_model}' was not found."
+                " Set ANTHROPIC_CHAT_MODEL to a valid model id"
+                " (see https://docs.anthropic.com/en/docs/about-claude/models)."
+            ) from exc
+        except anthropic.APIError as exc:
+            raise ProviderUnavailableError(
+                f"Anthropic API error: {exc.message}"
+            ) from exc
+
+        text = ""
+        for block in response.content:
+            if block.type == "text":
+                text += block.text
+
+        usage = response.usage
+        return CompletionResult(
+            text=text,
+            input_tokens=usage.input_tokens,
+            output_tokens=usage.output_tokens,
+            provider=self.name,
+            model=self.chat_model,
+            tokens_estimated=False,
+        )
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        raise ProviderConfigError(_NO_EMBED_HELP)

receipts/llm/factory.py

@@ -0,0 +1,124 @@
+"""Provider factory — the only place tool code gets a provider from.
+
+Reads ``RECEIPTS_PROVIDER`` (via Settings), defaulting to ``ollama``. Never
+silently falls back to a different provider than the one configured; when the
+configured provider can't work, it fails with a message that says exactly
+what to do next.
+
+Concrete providers are imported lazily so that, e.g., an Ollama-only user
+never imports the Gemini SDK, and the test suite can exercise factory logic
+without any provider SDK side effects.
+"""
+
+from __future__ import annotations
+
+from receipts.config import Settings, load_settings
+from receipts.errors import ProviderConfigError
+from receipts.llm.provider import LLMProvider
+
+_VALID_HINT = (
+    "Valid values: ollama (default), gemini, anthropic, openai,"
+    " fake (offline testing)."
+)
+
+
+def get_provider(
+    settings: Settings | None = None, *, verify: bool = True
+) -> LLMProvider:
+    """Return the configured provider, ready to use.
+
+    With ``verify=True`` (the default), provider reachability / model ids
+    are probed up front so the user gets a friendly actionable error
+    immediately instead of a failure on the first real call.
+
+    When ``RECEIPTS_EMBED_PROVIDER`` names a different provider, chat and
+    embeddings are split — this is how Claude (no embeddings API) works:
+    RECEIPTS_PROVIDER=anthropic + RECEIPTS_EMBED_PROVIDER=gemini.
+    """
+    if settings is None:
+        settings = load_settings()
+    name = settings.provider
+
+    if name == "fake":
+        from receipts.llm.fake_provider import FakeProvider
+
+        # Deliberately unmetered: the fake provider exists for offline tests,
+        # which must not write to the user's real ledger database.
+        return FakeProvider()
+
+    provider = _build_provider(name, settings, verify=verify)
+
+    embed_name = settings.embed_provider
+    if embed_name and embed_name != name:
+        if embed_name == "anthropic":
+            raise ProviderConfigError(
+                "Anthropic has no embeddings API and can't be the embed"
+                " provider. Set RECEIPTS_EMBED_PROVIDER to ollama, gemini,"
+                " or openai."
+            )
+        from receipts.llm.split import SplitProvider
+
+        # The embed backend's chat model is never used — skip its probe.
+        embed = _build_provider(embed_name, settings, verify=False)
+        provider = SplitProvider(provider, embed)
+
+    return _metered(provider)
+
+
+def _build_provider(name: str, settings: Settings, *, verify: bool) -> LLMProvider:
+    """Construct one concrete provider (unmetered, unsplit)."""
+    if name == "ollama":
+        from receipts.llm.ollama_provider import OllamaProvider
+
+        provider = OllamaProvider(
+            host=settings.ollama_host,
+            chat_model=settings.ollama_chat_model,
+            embed_model=settings.ollama_embed_model,
+        )
+        if verify:
+            provider.check_available()
+        return provider
+
+    if name == "gemini":
+        from receipts.llm.gemini_provider import GeminiProvider
+
+        provider = GeminiProvider(
+            api_key=settings.gemini_api_key,
+            chat_model=settings.gemini_chat_model,
+            embed_model=settings.gemini_embed_model,
+        )
+        if verify:
+            provider.check_available()
+        return provider
+
+    if name == "anthropic":
+        from receipts.llm.anthropic_provider import AnthropicProvider
+
+        return AnthropicProvider(
+            api_key=settings.anthropic_api_key,
+            chat_model=settings.anthropic_chat_model,
+        )
+
+    if name == "openai":
+        from receipts.llm.openai_provider import OpenAIProvider
+
+        return OpenAIProvider(
+            api_key=settings.openai_api_key,
+            chat_model=settings.openai_chat_model,
+            embed_model=settings.openai_embed_model,
+            base_url=settings.openai_base_url,
+        )
+
+    if name == "fake":
+        from receipts.llm.fake_provider import FakeProvider
+
+        return FakeProvider()
+
+    raise ProviderConfigError(f"Unknown provider '{name}'. {_VALID_HINT}")
+
+
+def _metered(provider: LLMProvider) -> LLMProvider:
+    """Wrap a real provider so every call lands in the token ledger."""
+    from receipts.llm.metered import MeteredProvider
+
+    return MeteredProvider(provider)

receipts/llm/fake_provider.py

@@ -0,0 +1,79 @@
+"""In-memory fake provider for tests and offline demos.
+
+No network, deterministic, and it records every call so tests can assert on
+exactly what was sent. Token counts use a crude chars/4 heuristic on purpose:
+real estimation (tiktoken) lives only in the Ollama provider, because tiktoken
+downloads its encoding file on first use and the test suite must run with zero
+network access.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+
+from receipts.llm.provider import CompletionResult, LLMProvider
+
+
+def _rough_token_count(text: str) -> int:
+    return max(1, len(text) // 4)
+
+
+@dataclass
+class RecordedCall:
+    kind: str  # "complete" | "embed"
+    system: str | None = None
+    user: str | None = None
+    json_mode: bool = False
+    texts: list[str] = field(default_factory=list)
+
+
+class FakeProvider(LLMProvider):
+    """Deterministic offline stand-in for a real LLM backend.
+
+    ``responses`` are returned by ``complete`` in order; once exhausted (or if
+    none were given) a fixed canned response is returned. Embeddings are
+    derived from a hash of the input text, so the same text always maps to the
+    same vector.
+    """
+
+    name = "fake"
+
+    def __init__(
+        self,
+        responses: list[str] | None = None,
+        *,
+        model: str = "fake-model",
+        embedding_dim: int = 8,
+    ) -> None:
+        self._responses = list(responses or [])
+        self.model = model
+        self.embedding_dim = embedding_dim
+        self.calls: list[RecordedCall] = []
+
+    def complete(
+        self, system: str, user: str, *, json_mode: bool = False
+    ) -> CompletionResult:
+        self.calls.append(
+            RecordedCall("complete", system=system, user=user, json_mode=json_mode)
+        )
+        if self._responses:
+            text = self._responses.pop(0)
+        else:
+            text = '{"fake": true}' if json_mode else "fake response"
+        return CompletionResult(
+            text=text,
+            input_tokens=_rough_token_count(system) + _rough_token_count(user),
+            output_tokens=_rough_token_count(text),
+            provider=self.name,
+            model=self.model,
+            tokens_estimated=True,
+        )
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        self.calls.append(RecordedCall("embed", texts=list(texts)))
+        return [self._vector_for(text) for text in texts]
+
+    def _vector_for(self, text: str) -> list[float]:
+        digest = hashlib.sha256(text.encode("utf-8")).digest()
+        return [digest[i % len(digest)] / 255.0 for i in range(self.embedding_dim)]