pr-context-engine 0.1.0__tar.gz

pr_context_engine-0.1.0/.env.example

@@ -0,0 +1,30 @@
+# Copy this file to .env for local development. .env is gitignored — never commit it.
+
+# ── Provider selection ────────────────────────────────────────────────────────
+# Choose: groq (default) | gemini | ollama | anthropic
+LLM_PROVIDER=groq
+
+# ── Provider keys (only the selected provider's key is required) ──────────────
+
+# Free Groq API key (no credit card): https://console.groq.com/keys
+GROQ_API_KEY=your-groq-api-key-here
+
+# Google Gemini key (fallback): https://aistudio.google.com/apikey
+GEMINI_API_KEY=your-gemini-api-key-here
+
+# Anthropic Claude key (BYO): https://console.anthropic.com/settings/keys
+ANTHROPIC_API_KEY=your-anthropic-api-key-here
+
+# Ollama (local, no key needed — just run `ollama serve`)
+# OLLAMA_BASE_URL=http://localhost:11434
+# OLLAMA_MODEL=qwen2.5-coder:7b
+
+# ── GitHub ────────────────────────────────────────────────────────────────────
+# A GitHub token with `pull-requests: write` scope.
+# Locally, you can generate one with: gh auth token
+GITHUB_TOKEN=your-github-token-here
+
+# ── Fix suggestions (opt-in) ──────────────────────────────────────────────────
+# Set to true to generate confidence-gated patch suggestions. Default: false.
+# See CONFIG.md for full details.
+ENABLE_FIXES=false

pr_context_engine-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: Something isn't working
+labels: bug
+---
+
+**What happened**
+<!-- A clear description of the bug. -->
+
+**To reproduce**
+```bash
+# Command you ran
+pr-context-engine review --pr N --repo owner/name
+```
+
+**Expected behaviour**
+
+**Actual behaviour** (include the full error / log output)
+
+**Environment**
+- OS:
+- Python version (`python --version`):
+- Package version (`pr-context-engine --version` or `pip show pr-context-engine`):
+- LLM provider (`LLM_PROVIDER` value):

pr_context_engine-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,16 @@
+---
+name: Feature request
+about: Suggest an improvement
+labels: enhancement
+---
+
+**What problem does this solve?**
+<!-- Describe the use case, not the implementation. -->
+
+**What should the solution look like?**
+
+**Alternatives you've considered**
+
+**Would you be willing to open a PR?**
+- [ ] Yes
+- [ ] No

pr_context_engine-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## What changed
+
+<!-- 2-3 sentences on the intent, not the line count. -->
+
+## Why
+
+<!-- Link to the issue this closes, or explain the motivation. -->
+
+## Checklist
+
+- [ ] `uv run ruff check src/ tests/` passes
+- [ ] `uv run pytest tests/unit/ -v` passes
+- [ ] New behaviour is covered by a unit test
+- [ ] `CONFIG.md` updated if new env vars were added
+- [ ] `CHANGELOG.md` entry added under `## Unreleased`

pr_context_engine-0.1.0/.github/workflows/pr-review.yml

@@ -0,0 +1,59 @@
+name: PR Context Briefing
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install uv
+        run: pip install uv
+      - name: Install dev dependencies
+        run: uv sync --group dev
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+  brief:
+    needs: lint
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 50 # tradeoff: enough history for most files, fast clone; see Milestone 6 note
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Restore index cache
+        uses: actions/cache@v4
+        with:
+          path: index.db
+          key: pr-engine-index-${{ github.event.pull_request.base.sha }}
+          restore-keys: pr-engine-index-
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Generate briefing
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          LLM_PROVIDER: groq
+          GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }} # fallback (Milestone 7)
+        run: >
+          uv run pr-context-engine review
+          --pr ${{ github.event.pull_request.number }}
+          --repo ${{ github.repository }}

pr_context_engine-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC — no PyPI token secret needed)
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pr_context_engine-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Byte-compiled / cached Python
+__pycache__/
+*.py[cod]
+
+# Packaging / build artifacts
+build/
+dist/
+*.egg-info/
+
+# Virtual environment
+.venv/
+
+# Local secrets — never commit (see .env.example)
+.env
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+
+# Generated codebase index (Milestone 5)
+index.db
+
+# Eval run output — generated on each run, not committed
+tests/eval/scores.jsonl

pr_context_engine-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

pr_context_engine-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project uses [semantic versioning](https://semver.org/).
+
+## Unreleased
+
+## 0.1.0 — 2026-05-17
+
+### Added
+
+- **Milestone 1** — End-to-end skeleton: Typer CLI entrypoint (`pr-context-engine review`), Groq LLM provider, GitHub diff fetch and PR comment posting, GitHub Actions workflow.
+- **Milestone 2** — Pluggable LLM providers: `LLMProvider` abstract base, Gemini, Ollama, and Anthropic implementations, `LLM_PROVIDER` env var switching.
+- **Milestone 3** — Real diff analysis: `diff_parser`, `ast_walker` (function/class name extraction), `risk_scorer` with located-issue objects (`file`, `line`, `snippet`).
+- **Milestone 4** — Senior-voice prompt and structured briefing: four-section markdown output (What changed / Blast radius / Risk flags / Questions), terse system prompt.
+- **Milestone 5** — Codebase index (RAG): `sqlite-vec` + `fastembed` local embeddings, semantic similar-chunk retrieval, `actions/cache` integration.
+- **Milestone 6** — Git history context: per-file commit history, recent merged PR lookup, graceful shallow-clone degradation.
+- **Milestone 7** — Provider failover: `FailoverProvider` (Groq → Gemini on 429), provider attribution in PR comment footer, unit test for failover path.
+- **Milestone 8** — Confidence-gated fix suggestions: `fix_generator`, confidence gate (`high`/`medium` → suggestion block, `low` → prose), collapsed `<details>` + GitHub suggestion blocks, `ENABLE_FIXES` kill switch.
+- **Milestone 9** — Eval harness: LLM-as-judge scoring across 5 rubric dimensions + fix correctness + calibration rate, `pytest tests/eval/` scorecard.
+- **Milestone 10** — Open-source readiness: `action.yml` for one-line GitHub Action install, `--dry-run` flag, `quickstart` command, `LICENSE` (MIT), `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `CONFIG.md`, PyPI metadata, issue/PR templates.

pr_context_engine-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## Our Pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainer directly. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

pr_context_engine-0.1.0/CONFIG.md

@@ -0,0 +1,80 @@
+# Configuration Reference
+
+All configuration is via environment variables or CLI flags. CLI flags take precedence over env vars.
+
+## Minimal config (one API key is enough)
+
+```bash
+export GROQ_API_KEY=<your-groq-key>
+export GITHUB_TOKEN=<your-github-token>
+pr-context-engine review --pr 42 --repo owner/name
+```
+
+## Full reference
+
+### Provider selection
+
+| Env var | Default | Values | Description |
+|---|---|---|---|
+| `LLM_PROVIDER` | `groq` | `groq` \| `gemini` \| `ollama` \| `anthropic` | Primary LLM provider. |
+
+### API keys
+
+| Env var | Required | Notes |
+|---|---|---|
+| `GROQ_API_KEY` | Yes (if `LLM_PROVIDER=groq`) | Free at https://console.groq.com/keys. ~1 000 req/day. |
+| `GEMINI_API_KEY` | No | Failover when Groq is rate-limited. Also used as primary when `LLM_PROVIDER=gemini`. |
+| `ANTHROPIC_API_KEY` | No | Required only when `LLM_PROVIDER=anthropic`. No free tier. |
+| `GITHUB_TOKEN` | Yes (unless `--dry-run`) | Needs `pull-requests:write`. In Actions, use `${{ secrets.GITHUB_TOKEN }}`. |
+
+### Ollama
+
+| Env var | Default | Description |
+|---|---|---|
+| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama server URL. |
+| `OLLAMA_MODEL` | `qwen2.5-coder:7b` | Model name to use via Ollama. |
+
+### Fix suggestions (opt-in)
+
+| Env var | CLI flag | Default | Description |
+|---|---|---|---|
+| `ENABLE_FIXES` | `--enable-fixes` / `--no-enable-fixes` | `false` | Generate confidence-gated fix suggestions. Opt-in per repo. See [ADR-5](docs/design-decisions.md). |
+
+### Failover
+
+Failover to Gemini is **automatic** whenever `GEMINI_API_KEY` is set, regardless of `LLM_PROVIDER`. The PR comment footer shows which provider was actually used (`via groq`, `via gemini (groq rate-limited)`, etc.).
+
+To disable auto-failover, set `LLM_PROVIDER=gemini` explicitly — this makes Gemini the primary and there is no automatic fallback.
+
+## CLI flags (review command)
+
+```
+pr-context-engine review [OPTIONS]
+
+  --pr INTEGER          Pull request number. [required]
+  --repo TEXT           Repository in owner/name form. [required]
+  --github-token TEXT   GitHub token. Defaults to GITHUB_TOKEN env var.
+  --enable-fixes        Generate fix suggestions (default off).
+  --no-enable-fixes     Disable fix suggestions (default).
+  --dry-run             Print briefing to stdout; do not post to GitHub.
+  --help                Show this message and exit.
+```
+
+## CLI flags (quickstart command)
+
+```
+pr-context-engine quickstart
+
+  Checks whether GROQ_API_KEY, GEMINI_API_KEY, and GITHUB_TOKEN are set and
+  whether the GitHub token has the correct scope. Prints exactly what is missing.
+```
+
+## GitHub Actions example (full config)
+
+```yaml
+- uses: paramahastha/pr-context-engine@v1
+  with:
+    groq-api-key: ${{ secrets.GROQ_API_KEY }}
+    gemini-api-key: ${{ secrets.GEMINI_API_KEY }}   # optional failover
+    enable-fixes: "true"                             # opt-in fix suggestions
+```

pr_context_engine-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+## Development setup
+
+Requires Python 3.12+ and [`uv`](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/paramahastha/pr-context-engine
+cd pr-context-engine
+uv sync --group dev
+```
+
+Copy `.env.example` to `.env` and fill in your API keys.
+
+## Running tests
+
+```bash
+# Unit tests (fast, no API calls)
+uv run pytest tests/unit/ -v
+
+# Eval harness (requires a provider key; uses LLM-as-judge)
+uv run pytest tests/eval/ -v
+```
+
+## Lint
+
+```bash
+uv run ruff check src/ tests/
+```
+
+## Local dry-run
+
+```bash
+export GITHUB_TOKEN=$(gh auth token)
+export GROQ_API_KEY=<your-key>
+uv run pr-context-engine review --pr <N> --repo <owner/name> --dry-run
+```
+
+## Milestone philosophy
+
+Each milestone is designed so the next milestone doesn't require painful refactors of the previous one. The key early decisions — CLI-core entrypoint (M1), provider abstraction (M2), and located-issue data shape in the risk scorer (M3) — exist specifically to make M7, M8, and M9 cheap. Don't skip milestones or reorder them.
+
+## Commit message format
+
+```
+feat(milestone-N): description
+fix(milestone-N): description
+refactor: description
+```
+
+## Pull request checklist
+
+- [ ] `uv run ruff check src/ tests/` passes
+- [ ] `uv run pytest tests/unit/ -v` passes
+- [ ] New behaviour is covered by a test in `tests/unit/`
+- [ ] No new required env vars without updating `CONFIG.md`
+
+## Reporting bugs
+
+Open an issue using the [bug report template](https://github.com/paramahastha/pr-context-engine/issues/new?template=bug_report.md).

pr_context_engine-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kautsar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pr_context_engine-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: pr-context-engine
+Version: 0.1.0
+Summary: An AI tool that reads every PR and posts a senior-engineer-style briefing.
+Project-URL: Homepage, https://github.com/paramahastha/pr-context-engine
+Project-URL: Repository, https://github.com/paramahastha/pr-context-engine
+Project-URL: Issues, https://github.com/paramahastha/pr-context-engine/issues
+Project-URL: Changelog, https://github.com/paramahastha/pr-context-engine/blob/main/CHANGELOG.md
+Author-email: Kautsar <paramahastha@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,code-review,github,llm,pull-request
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.12
+Requires-Dist: anthropic>=0.40
+Requires-Dist: fastembed>=0.4
+Requires-Dist: google-genai>=1.0
+Requires-Dist: groq>=0.13
+Requires-Dist: pygithub>=2.4
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: requests>=2.32
+Requires-Dist: sqlite-vec>=0.1
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# PR Context Engine
+
+[![CI](https://github.com/paramahastha/pr-context-engine/actions/workflows/pr-review.yml/badge.svg)](https://github.com/paramahastha/pr-context-engine/actions/workflows/pr-review.yml)
+[![PyPI version](https://img.shields.io/pypi/v/pr-context-engine)](https://pypi.org/project/pr-context-engine/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+
+> An AI tool that reads every PR and writes the briefing — and the fixes — a senior engineer would, with the calibration data to prove it's not just guessing.
+
+## What it does
+
+Every PR opens with three problems for the reviewer: _what is this actually doing_, _what could it break_, and _what should I push back on_. A diff doesn't answer any of those.
+
+PR Context Engine reads the diff plus surrounding code, recent git history, and semantically similar code from elsewhere in the repo, then posts a terse briefing written like a senior backend engineer would write it:
+
+```markdown
+## PR Briefing
+
+**What changed**
+Refactors the session token storage from an in-memory dict to Redis, adding a
+configurable TTL. The auth middleware is updated to hit Redis on every request.
+
+**Blast radius**
+Any caller of `get_session()` now depends on Redis being reachable. If Redis is
+down, all authenticated requests will 401. The previous in-memory store had no
+such single point of failure.
+
+**Risk flags**
+- `modifies_auth`: src/auth/session.py line 42 — `token = generate_token(user_id)`
+
+**Questions for the reviewer**
+
+1. The Redis client is initialised once at import time — is there a reconnect
+   strategy if the connection drops mid-deploy?
+2. `SESSION_TTL` defaults to 3600 but the old in-memory store had no TTL — have
+   existing sessions been migrated or will they all expire immediately after deploy?
+3. There are no tests for the Redis-down path — is 401-on-outage the intended
+   degradation, or should it fall back to the old store?
+```
+
+No praise. No filler. No "this LGTM." Just the context a reviewer needs.
+
+## Quickstart (5 minutes)
+
+### Option A — GitHub Action (recommended)
+
+1. Get a free [Groq API key](https://console.groq.com/keys) — no credit card.
+2. Add it as a secret: **Settings → Secrets → Actions → New secret** → `GROQ_API_KEY`.
+3. Enable write permissions: **Settings → Actions → General → Workflow permissions → Read and write**.
+4. Add this to `.github/workflows/pr-briefing.yml`:
+
+```yaml
+name: PR Briefing
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+jobs:
+  brief:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - uses: paramahastha/pr-context-engine@main
+        with:
+          groq-api-key: ${{ secrets.GROQ_API_KEY }}
+```
+
+That's it. Every new PR gets a briefing comment automatically.
+
+### Option B — CLI (any CI or local)
+
+```bash
+pipx install pr-context-engine
+export GROQ_API_KEY=<your-groq-key>
+export GITHUB_TOKEN=$(gh auth token)
+
+# Check your setup first
+pr-context-engine quickstart
+
+# Dry-run: see the briefing without posting it
+pr-context-engine review --pr 42 --repo owner/name --dry-run
+
+# Post the real comment
+pr-context-engine review --pr 42 --repo owner/name
+```
+
+## Switching LLM providers
+
+Set `LLM_PROVIDER` to any of `groq` (default), `gemini`, `ollama`, or `anthropic`. Nothing downstream changes.
+
+| Provider | Key env var | Notes |
+|---|---|---|
+| `groq` *(default)* | `GROQ_API_KEY` | Free, ~1 000 req/day, fast |
+| `gemini` | `GEMINI_API_KEY` | Free-tier fallback; auto-engaged on Groq 429 |
+| `ollama` | — | Local, offline, no rate limits |
+| `anthropic` | `ANTHROPIC_API_KEY` | BYO key, no free tier |
+
+**Automatic failover:** if `GEMINI_API_KEY` is set, the tool fails over to Gemini on any Groq 429 or error and notes it in the PR comment footer. See [ADR-7](docs/design-decisions.md).
+
+## Fix suggestions (opt-in)
+
+When `ENABLE_FIXES=true`, the tool generates confidence-gated patch suggestions for located issues. Only `high`/`medium` confidence suggestions become one-click GitHub suggestion blocks; `low` confidence produces prose notes only. Max 3 suggestions per PR.
+
+```yaml
+- uses: paramahastha/pr-context-engine@main
+  with:
+    groq-api-key: ${{ secrets.GROQ_API_KEY }}
+    enable-fixes: "true"
+```
+
+See [ADR-5](docs/design-decisions.md) for why this is opt-in and confidence-gated.
+
+## Eval results
+
+`pytest tests/eval/` produces a scorecard across five rubric dimensions (Accuracy, Blast radius, Risk flags, Question quality, Brevity) plus fix correctness and calibration rate.
+
+```
+pytest tests/eval/ -v
+```
+
+Results are committed to `tests/eval/scores/` so improvements are visible in git history. The headline metrics are **fix correctness rate** and **false-confidence rate** (when the model said `high` confidence, how often was the patch actually correct).
+
+## Architecture
+
+```
+Front door A:                    Front door B:
+GitHub Action wrapper            pipx install + run in any CI / locally
+(paramahastha/pr-context-engine@main)
+     │                                 │
+     └────────────┬────────────────────┘
+                  ▼
+     ┌─────────────────────────────────────┐
+     │  CLI core (src/cli.py + orchestrator)│
+     └─────────────────────────────────────┘
+                  │
+     ├──► analyzers/   diff → FileChange objects, AST symbols, risk flags
+     ├──► context/     git history, sqlite-vec codebase index (RAG)
+     ├──► briefing/    prompt assembly → LLM call → structured output
+     ├──► fixes/       confidence-gated patch suggestions (opt-in)
+     ├──► llm/         pluggable providers + FailoverProvider
+     └──► github_api/  fetch diff, post comment + suggestion blocks
+```
+
+The CLI is the product; the GitHub Action is a thin wrapper. See [docs/architecture.md](docs/architecture.md) and [docs/design-decisions.md](docs/design-decisions.md).
+
+## Data & privacy
+
+**What leaves your machine:**
+
+- The PR diff and parsed metadata (file paths, function names, changed lines) are sent to the active LLM provider (Groq or Gemini by default).
+- No source code beyond the diff is sent to any external API. The codebase index (RAG) runs entirely locally via `fastembed` + `sqlite-vec`.
+- Git history and PR metadata are fetched from the GitHub API using your `GITHUB_TOKEN`.
+
+**Provider data policies:**
+
+- Groq and Gemini free tiers may use inputs for model improvement. See their respective privacy policies before using on private/sensitive repos.
+- Use `LLM_PROVIDER=ollama` or `LLM_PROVIDER=anthropic` (with `ANTHROPIC_API_KEY`) if you need a provider with stronger data-isolation guarantees.
+- The tool has no shared backend. Your API key, your quota, your data.
+
+## Configuration
+
+See [CONFIG.md](CONFIG.md) for the full reference of every env var and flag.
+
+## Design decisions
+
+See [docs/design-decisions.md](docs/design-decisions.md) for ADRs covering: why provider abstraction is built early, why SQLite over Pinecone, why fixes are opt-in, why MIT license, and more.
+
+## Cost
+
+**$0/month** for a portfolio-scale project on public repos.
+
+- GitHub Actions: free for public repos.
+- Groq: free tier, ~1 000 req/day.
+- Gemini fallback: free tier (~1 500 req/day).
+- Local embeddings (`fastembed`): $0, no API.
+- The tool has no shared backend — your usage costs stay yours regardless of how many repos adopt it.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and feature requests go in [Issues](https://github.com/paramahastha/pr-context-engine/issues).