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

receipts/config.py

@@ -0,0 +1,106 @@
+"""BYOK configuration.
+
+All configuration comes from environment variables, optionally loaded from
+``.env`` files (never committed). Resolution order (first hit wins):
+
+1. real environment variables
+2. ``.env`` in the current working directory (per-project overrides)
+3. ``~/.receipts/.env`` (user-level config, written by ``receipts setup``)
+
+No key is ever hardcoded, and no default points at a paid API — the default
+provider is local Ollama.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+GLOBAL_CONFIG_PATH = Path.home() / ".receipts" / ".env"
+
+DEFAULT_PROVIDER = "ollama"
+DEFAULT_OLLAMA_HOST = "http://localhost:11434"
+# Defaults chosen from what is actually pulled on the dev machine (see
+# SETUP.md for how to change them or pull alternatives).
+DEFAULT_OLLAMA_CHAT_MODEL = "gpt-oss:20b"
+DEFAULT_OLLAMA_EMBED_MODEL = "nomic-embed-text"
+# Current free-tier Gemini models (verified against ai.google.dev, July 2026).
+DEFAULT_GEMINI_CHAT_MODEL = "gemini-3.5-flash"
+DEFAULT_GEMINI_EMBED_MODEL = "gemini-embedding-2"
+DEFAULT_ANTHROPIC_CHAT_MODEL = "claude-sonnet-4-20250514"
+DEFAULT_OPENAI_CHAT_MODEL = "gpt-4o-mini"
+DEFAULT_OPENAI_EMBED_MODEL = "text-embedding-3-small"
+
+
+@dataclass(frozen=True)
+class Settings:
+    provider: str = DEFAULT_PROVIDER
+    # Optional separate provider for embeddings (RECEIPTS_EMBED_PROVIDER).
+    # Needed for chat providers without an embeddings API (Anthropic).
+    # None = embeddings use the same provider as chat.
+    embed_provider: str | None = None
+    ollama_host: str = DEFAULT_OLLAMA_HOST
+    ollama_chat_model: str = DEFAULT_OLLAMA_CHAT_MODEL
+    ollama_embed_model: str = DEFAULT_OLLAMA_EMBED_MODEL
+    gemini_api_key: str | None = None
+    gemini_chat_model: str = DEFAULT_GEMINI_CHAT_MODEL
+    gemini_embed_model: str = DEFAULT_GEMINI_EMBED_MODEL
+    anthropic_api_key: str | None = None
+    anthropic_chat_model: str = DEFAULT_ANTHROPIC_CHAT_MODEL
+    openai_api_key: str | None = None
+    openai_chat_model: str = DEFAULT_OPENAI_CHAT_MODEL
+    openai_embed_model: str = DEFAULT_OPENAI_EMBED_MODEL
+    # Optional OpenAI-compatible endpoint (Groq, OpenRouter, local servers).
+    # No default — leaving it unset means the official OpenAI API.
+    openai_base_url: str | None = None
+
+
+def load_settings(env: Mapping[str, str] | None = None) -> Settings:
+    """Build Settings from environment variables.
+
+    When ``env`` is not injected (normal runtime), a local ``.env`` file is
+    loaded first; real environment variables always win over ``.env`` values.
+    Tests pass an explicit ``env`` mapping and never touch the process
+    environment or the filesystem.
+    """
+    if env is None:
+        # dotenv never overrides variables that are already set, so loading
+        # the project .env first makes it win over the user-level file.
+        load_dotenv()
+        if GLOBAL_CONFIG_PATH.is_file():
+            load_dotenv(GLOBAL_CONFIG_PATH)
+        env = os.environ
+    return Settings(
+        provider=env.get("RECEIPTS_PROVIDER", DEFAULT_PROVIDER).strip().lower(),
+        embed_provider=(env.get("RECEIPTS_EMBED_PROVIDER", "").strip().lower() or None),
+        ollama_host=env.get("OLLAMA_HOST", DEFAULT_OLLAMA_HOST).strip(),
+        ollama_chat_model=env.get(
+            "OLLAMA_CHAT_MODEL", DEFAULT_OLLAMA_CHAT_MODEL
+        ).strip(),
+        ollama_embed_model=env.get(
+            "OLLAMA_EMBED_MODEL", DEFAULT_OLLAMA_EMBED_MODEL
+        ).strip(),
+        gemini_api_key=env.get("GEMINI_API_KEY") or None,
+        gemini_chat_model=env.get(
+            "GEMINI_CHAT_MODEL", DEFAULT_GEMINI_CHAT_MODEL
+        ).strip(),
+        gemini_embed_model=env.get(
+            "GEMINI_EMBED_MODEL", DEFAULT_GEMINI_EMBED_MODEL
+        ).strip(),
+        anthropic_api_key=env.get("ANTHROPIC_API_KEY") or None,
+        anthropic_chat_model=env.get(
+            "ANTHROPIC_CHAT_MODEL", DEFAULT_ANTHROPIC_CHAT_MODEL
+        ).strip(),
+        openai_api_key=env.get("OPENAI_API_KEY") or None,
+        openai_chat_model=env.get(
+            "OPENAI_CHAT_MODEL", DEFAULT_OPENAI_CHAT_MODEL
+        ).strip(),
+        openai_embed_model=env.get(
+            "OPENAI_EMBED_MODEL", DEFAULT_OPENAI_EMBED_MODEL
+        ).strip(),
+        openai_base_url=(env.get("OPENAI_BASE_URL") or "").strip() or None,
+    )

receipts/errors.py

@@ -0,0 +1,18 @@
+"""Shared exception types for receipts."""
+
+from __future__ import annotations
+
+
+class ReceiptsError(Exception):
+    """Base class for all receipts errors."""
+
+
+class ProviderConfigError(ReceiptsError):
+    """The configured provider is missing something it needs (e.g. an API key).
+
+    The message must always tell the user exactly what to do next.
+    """
+
+
+class ProviderUnavailableError(ReceiptsError):
+    """The configured provider exists but cannot be reached right now."""

receipts/export.py

@@ -0,0 +1,120 @@
+"""Export documents to PDF — markdown via pure Python, TeX via a compiler.
+
+Markdown (dossiers, reports) converts with zero external programs:
+``markdown`` renders HTML, ``xhtml2pdf`` renders the PDF. Both are plain
+pip installs (the ``[pdf]`` extra). TeX genuinely requires a TeX engine —
+we detect latexmk/tectonic/pdflatex and say exactly what to install when
+none exists (or point at Overleaf).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from receipts.errors import ReceiptsError
+
+_PDF_EXTRA_HELP = """\
+PDF export for markdown needs the optional [pdf] extra:
+  pip install codebase-receipts-cli[pdf]
+(installs 'markdown' and 'xhtml2pdf' — pure Python, no system packages)"""
+
+_STYLE = """
+@page { size: a4; margin: 1.6cm; }
+body { font-family: Helvetica, Arial, sans-serif; font-size: 10pt; color: #1a1a1a; }
+h1 { font-size: 17pt; border-bottom: 2px solid #333; padding-bottom: 4px; }
+h2 { font-size: 13pt; margin-top: 14pt; border-bottom: 1px solid #999; }
+h3 { font-size: 11pt; margin-top: 10pt; }
+code { font-family: Courier, monospace; font-size: 9pt; background: #f2f2f2; }
+pre { background: #f2f2f2; padding: 6px; font-size: 8.5pt; }
+blockquote { border-left: 3px solid #888; margin-left: 0;
+             padding-left: 10px; color: #333; }
+table { border-collapse: collapse; }
+th, td { border: 1px solid #999; padding: 4px 8px; font-size: 9pt; }
+hr { border: 0; border-top: 1px solid #bbb; }
+"""
+
+
+@dataclass(frozen=True)
+class ExportResult:
+    success: bool
+    pdf_path: Path | None
+    tool_used: str
+    error: str | None = None
+
+
+def export_markdown_pdf(md_path: Path, output: Path | None = None) -> ExportResult:
+    """Render a markdown file to PDF with pure-Python tooling."""
+    try:
+        import markdown
+        from xhtml2pdf import pisa
+    except ImportError as exc:
+        raise ReceiptsError(_PDF_EXTRA_HELP) from exc
+
+    if output is None:
+        output = md_path.with_suffix(".pdf")
+
+    text = md_path.read_text(encoding="utf-8")
+    body = markdown.markdown(text, extensions=["tables", "fenced_code", "sane_lists"])
+    html = (
+        "<html><head><style>"
+        + _STYLE
+        + "</style></head><body>"
+        + body
+        + "</body></html>"
+    )
+
+    with open(output, "wb") as fh:
+        status = pisa.CreatePDF(src=html, dest=fh, encoding="utf-8")
+
+    if status.err:
+        return ExportResult(
+            success=False,
+            pdf_path=None,
+            tool_used="xhtml2pdf",
+            error=f"PDF rendering reported {status.err} error(s).",
+        )
+    return ExportResult(success=True, pdf_path=output, tool_used="xhtml2pdf")
+
+
+def export_tex_pdf(tex_path: Path, output: Path | None = None) -> ExportResult:
+    """Compile a .tex file to PDF via whatever TeX engine is installed."""
+    from receipts.rewrite.compiler import compile_tex
+
+    result = compile_tex(tex_path)
+    if not result.success:
+        error = result.error or "compilation failed"
+        if result.tool_used is None:
+            error += (
+                "\n  Easiest single-binary install: tectonic"
+                " (https://tectonic-typesetting.github.io) — or paste the"
+                " .tex into Overleaf."
+            )
+        return ExportResult(
+            success=False,
+            pdf_path=None,
+            tool_used=result.tool_used or "none",
+            error=error,
+        )
+
+    pdf_path = result.pdf_path
+    if output is not None and pdf_path is not None and output != pdf_path:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_bytes(pdf_path.read_bytes())
+        pdf_path = output
+
+    return ExportResult(
+        success=True, pdf_path=pdf_path, tool_used=result.tool_used or "tex"
+    )
+
+
+def export_to_pdf(source: Path, output: Path | None = None) -> ExportResult:
+    """Dispatch on extension: .md → xhtml2pdf, .tex → TeX compiler."""
+    suffix = source.suffix.lower()
+    if suffix in (".md", ".markdown"):
+        return export_markdown_pdf(source, output)
+    if suffix == ".tex":
+        return export_tex_pdf(source, output)
+    raise ReceiptsError(
+        f"Don't know how to export '{source.suffix}' to PDF —" " supported: .md, .tex"
+    )