codebase-receipts-cli 1.0.0__tar.gz

codebase_receipts_cli-1.0.0/.env.example

@@ -0,0 +1,98 @@
+# Receipts configuration — copy this file to `.env` and edit as needed:
+#     cp .env.example .env
+# The real `.env` is gitignored and must NEVER be committed. Every value here
+# is a safe local default; nothing requires a paid API key.
+
+# Which LLM provider to use: ollama | gemini | anthropic | openai | fake
+#   ollama    — local, free, private, the default; needs the Ollama app running.
+#   gemini    — Google Gemini with a FREE key from https://aistudio.google.com/apikey
+#   anthropic — paid; needs ANTHROPIC_API_KEY (pip install codebase-receipts-cli[anthropic])
+#   openai    — paid; needs OPENAI_API_KEY (pip install codebase-receipts-cli[openai])
+#   fake      — deterministic offline stub, only useful for tests/demos.
+RECEIPTS_PROVIDER=ollama
+
+# Optional: use a DIFFERENT provider for embeddings than for chat.
+# Required for anthropic (Claude has no embeddings API):
+#   RECEIPTS_PROVIDER=anthropic
+#   RECEIPTS_EMBED_PROVIDER=gemini
+# IMPORTANT: must match whatever embedded your knowledge base — vectors from
+# different embedding models are not comparable (re-ingest if you switch).
+RECEIPTS_EMBED_PROVIDER=
+
+# Hybrid retrieval (dense embeddings + BM25 keyword match, fused): on by
+# default and costs zero extra LLM calls. Set to 0 to fall back to
+# embeddings-only retrieval.
+RECEIPTS_HYBRID=1
+
+# --- Optional retrieval upgrades (each costs LLM calls; all off by default
+# --- so the standard path stays fast on modest machines) -------------------
+
+# Contextual chunk enrichment at ingest: one LLM call per artifact generates
+# a one-line context prepended before embedding. Cached by content hash, so
+# re-ingests regenerate nothing. Better disambiguation at query time.
+RECEIPTS_ENRICH=0
+
+# Hierarchical corpus summaries at ingest: per-file -> per-directory -> one
+# repo-level architecture summary, each stored as a searchable chunk so
+# whole-repo claims ("microservices architecture") can retrieve real
+# evidence. Cached like enrichment. (The zero-LLM CODE FACTS and IMPORT MAP
+# chunks are always added — no flag needed.)
+RECEIPTS_SUMMARIES=0
+
+# Query expansion + HyDE at verify time: rewrite each claim into 2-3
+# code-phrased queries plus a hypothetical snippet, search all of them, and
+# allow ONE reformulate-and-retry when nothing passes the threshold.
+RECEIPTS_QUERY_EXPANSION=0
+
+# LLM reranking at verify time: over-fetch candidates and let the model
+# reorder the top of the pile before verification. Reorders/drops only —
+# it can never add evidence or bypass the distance threshold.
+RECEIPTS_RERANK=0
+
+# Where the local Ollama daemon listens. The default matches a standard install.
+OLLAMA_HOST=http://localhost:11434
+
+# Ollama chat model for verification/rewriting. gpt-oss:20b is strong at code
+# reasoning but needs ~16 GB RAM; if your machine struggles, try gemma3:4b.
+# See what you have with `ollama list`; pull with `ollama pull <model>`.
+OLLAMA_CHAT_MODEL=gpt-oss:20b
+
+# Ollama embedding model used to index your code. nomic-embed-text is the
+# standard lightweight choice. Changing it later means re-ingesting, since
+# vectors from different models are not comparable.
+OLLAMA_EMBED_MODEL=nomic-embed-text
+
+# Free Gemini API key from Google AI Studio (https://aistudio.google.com/apikey).
+# Only needed when RECEIPTS_PROVIDER=gemini. Note: receipts reads exactly this
+# variable and passes it to the SDK explicitly, so a stray GOOGLE_API_KEY in
+# your environment won't silently take over.
+GEMINI_API_KEY=
+
+# Gemini chat model (free-tier eligible as of July 2026).
+GEMINI_CHAT_MODEL=gemini-3.5-flash
+
+# Gemini embedding model. gemini-embedding-001 also works, but its vectors are
+# INCOMPATIBLE with gemini-embedding-2 — pick one and re-ingest if you switch.
+GEMINI_EMBED_MODEL=gemini-embedding-2
+
+# Anthropic API key (paid). Only needed when RECEIPTS_PROVIDER=anthropic.
+# Get one at https://console.anthropic.com/
+# Note: Anthropic does not offer an embeddings API. Use Ollama or Gemini for
+# ingestion, then switch to anthropic for verification/rewriting.
+ANTHROPIC_API_KEY=
+ANTHROPIC_CHAT_MODEL=claude-sonnet-4-20250514
+
+# OpenAI API key (paid). Only needed when RECEIPTS_PROVIDER=openai.
+# Get one at https://platform.openai.com/
+OPENAI_API_KEY=
+OPENAI_CHAT_MODEL=gpt-4o-mini
+OPENAI_EMBED_MODEL=text-embedding-3-small
+
+# Optional: point the OpenAI adapter at any OpenAI-COMPATIBLE endpoint —
+# e.g. Groq or OpenRouter (both have hosted strong open models like
+# gpt-oss-20b, sometimes with free tiers) or a local inference server.
+# Leave empty for the official OpenAI API. Set OPENAI_API_KEY to the key
+# for whichever service the URL points at.
+#   Groq:       OPENAI_BASE_URL=https://api.groq.com/openai/v1
+#   OpenRouter: OPENAI_BASE_URL=https://openrouter.ai/api/v1
+OPENAI_BASE_URL=

codebase_receipts_cli-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --group dev
+      - run: uv run ruff check receipts/ tests/
+      - run: uv run black --check receipts/ tests/
+      - run: uv run pytest -v

codebase_receipts_cli-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv sync --group dev
+      - run: uv run ruff check receipts/ tests/
+      - run: uv run black --check receipts/ tests/
+      - run: uv run pytest -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

codebase_receipts_cli-1.0.0/.gitignore

@@ -0,0 +1,33 @@
+__pycache__/
+*.pyc
+.venv/
+.uv/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# BYOK — real keys live here and must never be committed
+.env
+
+# Personal test data — your actual resume and target JD stay local
+resume.tex
+jd.txt
+
+# Generated outputs (rebuilt by the tool on demand)
+resume_optimized.tex
+resume_optimized.pdf
+dossier.md
+dossier.pdf
+
+# Editor / assistant local state
+.claude/
+.vscode/
+
+# LaTeX build artifacts (receipts export / pdflatex)
+*.aux
+*.toc
+resume_optimized.log
+resume_optimized.out
+sanity_dossier.md
+sanity_dossier.pdf

codebase_receipts_cli-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      - id: ruff
+        args: [--fix]
+  - repo: https://github.com/psf/black
+    rev: 26.5.1
+    hooks:
+      - id: black
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+        # uv.lock is ~1MB and belongs in the repo (reproducible dev env)
+        args: [--maxkb=2048]
+      - id: detect-private-key

codebase_receipts_cli-1.0.0/CHANGELOG.md

@@ -0,0 +1,153 @@
+<h1 align="center">CHANGELOG</h1>
+
+<p align="center">
+  <sub>All notable changes, one version at a time.</sub>
+</p>
+
+<br>
+
+---
+
+## `1.0.0` &mdash; 2026-07-17
+
+> Phases 8 through 23. Multi-repo, scale, remote sources, universal
+> language coverage, a unified TUI, next-gen retrieval, and PDF resumes —
+> on top of the 0.1.0 foundation.
+
+### Model Answers &amp; Interview Prep
+
+- AMA reveals a grounded, honest model answer after every round (honest
+  reframe when no evidence exists) instead of just a pass/fail verdict
+- Dossier upgraded to one model answer per question, not one per bullet
+- Readiness tracking persists model answers via an additive DB migration
+
+### Complete Slash-Command Palette
+
+- `/check` `/setup` `/tui` `/export` `/ledger` `/dashboard` added to the
+  interactive REPL &mdash; every CLI command now has a slash equivalent
+- Fixed `/check` incorrectly fuzzy-matching into `/verify`
+- Fixed a dead `--session` flag on `receipts ledger` that silently did
+  nothing; added `TokenLedger.last_session_summary()`
+
+### Scale Provisioning
+
+- Ingest budget auto-scales to corpus size with importance allocation
+  (parsed code over file excerpts, round-robin across directories) instead
+  of a fixed cap spent in alphabetical order
+- Incremental sync via content hashing: only new/changed artifacts are
+  re-embedded on re-ingest &mdash; measured 249.6s cold to 4.7s warm (~53x)
+  on a 376-artifact codebase
+- Source-labelled, filterable retrieval closes a measured cross-source
+  contamination gap (86% of claims picked up wrong-project evidence in a
+  merged corpus; 0% with the filter)
+
+### Remote Sources
+
+- `receipts ingest <github-url>` gets a durable, URL-keyed knowledge base
+  and a manifest of aliases usable anywhere a folder is accepted
+- `GITHUB_TOKEN` support for private repos (never logged, scrubbed from
+  every error message), `--branch`, `--full-history`
+- `--jd-url` fetches a job description straight from a posting URL
+
+### Universal Language Coverage
+
+- Extraction parity for Java, Kotlin, Go, Rust, C, C++, C#, PHP, Ruby,
+  Swift &mdash; tree-sitter grammar node types probe-verified against the
+  installed parser (never guessed) plus a regex fallback for the Windows
+  path where tree-sitter is disabled
+
+### PDF &amp; Plain-Text Resumes
+
+- `verify`, `ama`, `dossier`, and `score` accept `.pdf` and `.txt` resumes
+  in addition to `.tex` &mdash; zero LLM cost, pure text extraction plus
+  layout heuristics, measured at 85% claim-fidelity against a `.tex`
+  ground truth
+- Scanned/image PDFs are rejected with guidance, never guessed at
+
+### TUI Hub
+
+- One unified app for dashboard, readiness, and ledger screens with
+  consistent keybindings and `--tui` deep links from each command
+- New per-model token/cost breakdown on the ledger screen
+
+### Next-Generation Retrieval
+
+- Hybrid retrieval: a from-scratch BM25 lexical index fused with dense
+  embeddings via reciprocal rank fusion, on by default &mdash; measured
+  recall@5 improvement (8/11 to 11/11) with false-evidence chunks going
+  *down*, not up
+- A self-checking calibration gate measures whether any retrieval upgrade
+  makes the tool more gullible before it ships. It already caught one:
+  query-expansion/HyDE doubled the false-evidence rate (15 to 30 chunks)
+  by generating fake supporting code and searching with it &mdash; that
+  feature now ships disabled by default
+- Contextual chunk enrichment, hierarchical corpus summaries, and an
+  LLM reranker, all opt-in and independently toggleable
+
+### Fixes
+
+- MiKTeX-aware TeX compiler with platform-ordered fallbacks (pdflatex
+  before latexmk on Windows, where latexmk needs Perl)
+- Architecture-aware install failure messages for tree-sitter and chromadb
+  on unsupported platforms, with concrete fix instructions per OS
+
+---
+
+## `0.1.0` &mdash; 2026-07-08
+
+> The one that ships everything.
+
+### Ingest Pipeline
+
+- Tree-style codebase scanner respecting `.gitignore`
+- Git URL support &mdash; clone remote repos, scan, clean up
+- Pre-embedding secrets detection (named patterns + Shannon entropy) with
+  automatic redaction
+- Tree-sitter artifact extraction (functions, classes) with configurable
+  token budget
+
+### Resume Parsing
+
+- LaTeX `.tex` parser supporting rendercv and common resume templates
+- Claim extractor: percentages, counts, latency figures, technology names
+
+### Verification Engine
+
+- ChromaDB-backed knowledge base with cosine similarity search
+- Three-tier classification: **Verified** / **Plausible** / **Unsupported**
+- Hard rule: no evidence past distance threshold = Unsupported, no LLM call
+- Honest rewriter: rewrites weak bullets using only what the code can justify
+- Keyword gap analysis: job description vs resume vs codebase
+
+### Terminal UI
+
+- Full-screen Textual app: file tree, claims table, rewrites diff, LLM log
+- Live token counter and status bar
+- Background verification with thread-safe UI updates
+
+### Mock Interview
+
+- `ama` command: weighted Q&A loop targeting weak claims
+- Follow-up questions, per-bullet assessment, final summary
+
+### Provider Abstraction (BYOK)
+
+- **Ollama** &mdash; default, local, free, no key needed
+- **Gemini** &mdash; free-tier Google AI Studio key
+- **Anthropic** &mdash; paid BYOK adapter (optional dependency)
+- **OpenAI** &mdash; paid BYOK adapter (optional dependency)
+- Fake provider for fully offline, deterministic testing
+
+### Token Ledger
+
+- SQLite-backed per-session and lifetime token/cost tracking
+- Pricing table: $/1K-token rates per provider and model
+- `receipts ledger` CLI command for usage summaries
+
+### Infrastructure
+
+- `uv`-managed project with ruff + black pre-commit hooks
+- 136 tests, zero network access, zero Ollama dependency
+- CI: GitHub Actions on Ubuntu + Windows, Python 3.10 + 3.12
+- Publishing: trusted publishing (OIDC) to PyPI on tag push
+- MIT License