github-repo-summarizer

A FastAPI service (and one-shot CLI) that turns any public GitHub repository into a structured JSON summary — what the project does, what it's built with, and how it's organized.

{
  "summary": "Requests is an elegant and simple HTTP library for Python, designed for human beings...",
  "technologies": ["Python", "urllib3", "certifi", "pytest", "tox"],
  "structure": "Flat src layout with core HTTP logic in requests/, tests in tests/..."
}

Why this exists

Pointing a generic LLM at "summarize this repo" doesn't scale: a kernel-sized codebase has tens of thousands of files, none of which fit in a single context window. This project is the opposite of that — a small, deterministic packing layer in front of the LLM:

• Adaptive context tiers. File caps and total context budget scale with repo size (small / medium / large), so a 15-file library and the Linux kernel both produce sensible packed payloads.
• Deterministic file scoring. Files are ranked by category (docs > manifests > ops > CI > core code), then by a path/size scoring function with stable tie-breakers. Same repo always produces the same selection.
• Multi-pass sharding. When packed excerpts exceed the single-pass budget, the packer splits selected files into up to 6 shards, summarizes each independently, then synthesizes a final response.
• Provider-agnostic LLM client. OpenAI by default; Nebius supported as an alternative provider when configured. Strict JSON parsing with a repair-pass on malformed output, then fall through to the next provider on failure.

See docs/ARCHITECTURE.md for the full pipeline, docs/SCORING_HEURISTICS.md for the scoring formula, and docs/DECISIONS.md for engineering trade-offs.

Benchmarks

Real timings from the CLI. Single host, OpenAI provider, varies with network and provider load.

Repository	Files	Time	Shards	Notes
sindresorhus/is	15	~11s	1	Tiny TypeScript library
keleshev/schema	20	~19s	1	Small Python package
pallets/flask	235	~25s	1	Medium Python framework
microsoft/vscode	9,579	~56s	1	Large TypeScript monorepo
mdn/content	15,822	~65s	2	Thousands of Markdown docs
opencv/opencv	7,688	~95s	2	Large C++ vision library
tensorflow/tensorflow	35,704	~62–123s	2	Giant ML framework
torvalds/linux	80,000+	~215s	2	The Linux kernel itself

Setup

git clone https://github.com/grimgrimberg/github-repo-summarizer.git
cd github-repo-summarizer

python -m venv .venv
source .venv/bin/activate          # Windows: .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

cp .env.example .env
# Edit .env and set OPENAI_API_KEY (or NEBIUS_API_KEY)

Requires Python 3.11+ and at least one LLM provider key.

Usage

CLI (single repo, no server)

python main.py https://github.com/psf/requests

Prints the JSON summary to stdout.

HTTP API

python main.py

Then in another shell:

curl -X POST http://localhost:8000/summarize \
  -H "Content-Type: application/json" \
  -d '{"github_url":"https://github.com/psf/requests"}'

API

GET /health

Returns {"status": "ok"}.

POST /summarize

Request:

{ "github_url": "https://github.com/psf/requests" }

Response (200):

{
  "summary": "...",
  "technologies": ["..."],
  "structure": "..."
}

Error (4xx/5xx):

{ "status": "error", "message": "..." }

Configuration

Variable	Required	Description
OPENAI_API_KEY	yes (or Nebius)	OpenAI API key — default provider
OPENAI_MODEL	no	OpenAI model (default: gpt-4.1-mini)
NEBIUS_API_KEY	yes (or OpenAI)	Nebius API key — alternative provider
NEBIUS_MODEL	no	Force a specific Nebius model
GITHUB_TOKEN	no	Higher GitHub rate limits + private repo access
MAX_REQUEST_DEADLINE_SECONDS	no	Total timeout per request (default: 120, max: 600)

When both provider keys are set, OpenAI runs first and Nebius is the fallback.

Tests

pytest -q

All tests use mocks — no real API calls are made.

Examples

Small repo — sindresorhus/is (15 files)

python main.py https://github.com/sindresorhus/is

{
  "summary": "Type checking utility library",
  "technologies": ["TypeScript", "JavaScript", "Node.js", "RxJS", "ZenObservable"],
  "structure": "Monorepo"
}

~11s · 15 files scanned · 1 LLM pass

Medium repo — pallets/flask (235 files)

python main.py https://github.com/pallets/flask

{
  "summary": "The Python micro framework for building web applications.",
  "technologies": ["Python", "Flask", "Celery", "Redis", "Click", "Jinja2",
                   "Werkzeug", "Blinker", "MarkupSafe", "itsdangerous"],
  "structure": "Microframework with modular design"
}

~25s · 235 files scanned · 1 LLM pass

Massive repo — torvalds/linux (80,000+ files)

python main.py https://github.com/torvalds/linux

{
  "summary": "The Linux kernel is a free and open-source operating system kernel that manages computer hardware resources and provides services to applications. It includes device drivers, system calls, memory management, process scheduling, file system management, and network communication.",
  "technologies": ["C", "C/C++ Headers", "Python", "Rust", "Sphinx", "Git", "GNU Make", "GCC", "Binutils"],
  "structure": "The Linux kernel is divided into several subsystems, including the process scheduler, memory management, file systems, and network stack. The source tree is organized in a modular structure, with each subsystem in a separate directory."
}

~215s · 2,839 files indexed · 65 selected · 2 LLM shards + synthesis

License

MIT — see LICENSE.