README.md

metadata

title: Repo Summarizer
emoji: 📚
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.0.2
python_version: '3.11'
app_file: app.py
pinned: false
short_description: Summarize GitHub repos — purpose, tech stack, layout.

Repo Summarizer

A FastAPI service that takes a GitHub repository URL, fetches key files (README, main.py, requirements, directory tree), and returns an AI-generated summary, technologies list, and structure description using the Anthropic Claude API.

---

Features

• POST /summarize — Accepts a GitHub repo URL and returns:
  • summary — Short project description (from README, main.py, and the 10 longest Python files).
  • technologies — List of technologies/dependencies (from requirements*.txt and file extensions in the repo).
  • structure — One paragraph describing the project layout (from the repo’s directory tree).
• GET / — Web UI to paste a GitHub URL or local path and see the summary result (index.html).
• app.py — Gradio UI with the same behavior as the HTML page (for Hugging Face Spaces and local runs).
• GET /health — Health check ({"status": "ok"}).
• Unified error responses in JSON: {"status": "error", "message": "..."}.
• Optional GITHUB_TOKEN for higher GitHub API rate limits.
• Entry-point logging via log_entry() (filename, line, function name) for tracing.

---

Project structure

NebiusTest/
├── main.py          # FastAPI app, /summarize, /health, /, GitHub fetch, LLM calls
├── app.py           # Gradio UI (Space entry point); reuses main.py summarization logic
├── logger.py        # log_entry() for request/function tracing
├── constants.py     # FILE_EXTENSIONS (used for repo analysis)
├── index.html       # Frontend form for GitHub URL/local path → summarize
├── requirement.txt  # Python dependencies
├── README.md        # This file
└── .gitignore

---

Setup

1. Install dependencies

pip install -r requirement.txt

2. Environment variables

Variable	Required	Description
ANTHROPIC_API_KEY	Yes	API key for Anthropic (Claude). Used for all summarization.
GITHUB_TOKEN	No	GitHub personal access token. Raises API rate limit (e.g. 5000/hr vs 60/hr without).
SSL_CERT_FILE / REQUESTS_CA_BUNDLE / SSL_CA_BUNDLE	No	PEM path with extra CAs (e.g. corporate HTTPS inspection). Overrides the default Mozilla bundle (certifi) used for GitHub + Anthropic httpx clients.
HTTPX_VERIFY	No	Set to 0, false, or no to disable TLS verification (insecure; debugging only).

Example (PowerShell):

$env:ANTHROPIC_API_KEY = "sk-ant-..."
$env:GITHUB_TOKEN = "ghp_..."   # optional

3. Run the server

python main.py

Server runs at http://127.0.0.1:8000.

Or with uvicorn:

uvicorn main:app --reload --host 127.0.0.1 --port 8000

4. Gradio UI (app.py)

app.py opens a Gradio interface that matches index.html: one text field for a GitHub URL or local directory path, a Summarize button, and sections for Summary, Technologies, and Structure, with errors shown at the top of the result area.

Run locally after installing dependencies (including Gradio from requirement.txt):

python app.py

Gradio prints a local URL in the terminal (defaults may differ by version). The underlying logic is shared with main.py (same GitHub vs. local detection and LLM pipeline).

Hugging Face Spaces

• Create a Space with the Gradio SDK and point it at this repo, or set the Space’s App file to app.py and ensure Gradio finds the global demo object (this project exposes demo at module level in app.py).
• Add Secrets for ANTHROPIC_API_KEY (required) and optionally GITHUB_TOKEN, same as for the FastAPI app.
• Spaces default to a requirements.txt file name. If your Space only sees requirement.txt, either add a requirements.txt mirroring those dependencies or configure the Space build to use requirement.txt.
• Local paths only work when Gradio runs on a machine that can read that folder. On Hugging Face, use GitHub URLs only.

---

API

POST /summarize

Request body (JSON):

{
  "github_url": "https://github.com/owner/repo"
}

Success response (200):

{
  "summary": "**ProjectName** is a ...",
  "technologies": ["Python", "FastAPI", "httpx"],
  "structure": "Main code lives in `src/`, tests in `tests/`, ..."
}

Error response (4xx/5xx):

All errors return JSON:

{
  "status": "error",
  "message": "Description of what went wrong"
}

Example: repository not found, invalid URL, no text files, or LLM/rate-limit errors.

---

Usage

Browser (FastAPI + index.html)

1. Open http://127.0.0.1:8000/
2. Enter a GitHub repository URL or a local repository path.
3. Click Summarize and view summary, technologies, and structure.

Gradio (app.py)

1. Run python app.py.
2. Open the URL shown in the terminal.
3. Enter the same kind of repository source (GitHub URL or local path) and submit.

cURL

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

Python client

From the repo root:

from main import call_summarize

result = call_summarize("https://github.com/psf/requests")
print(result["summary"])
print(result["technologies"])
print(result["structure"])

---

How summarization works

1. Parse URL — Extract owner/repo from the GitHub URL.
2. Fetch repo data (GitHub API):
   • Default branch and recursive file tree.
   • Contents of: README.md, main.py, the 10 longest other .py files, and requirements*.txt.
3. Three sequential LLM calls (to stay within Anthropic rate limits):
   • Summary — From README + main.py + 10 longest Python files (Claude). Used the model claude-opus-4-6, since it works better with code
   • Technologies — From requirements content + file extensions found in the project (constants.FILE_EXTENSIONS). Used the model claude-haiku-4-5 since it's liteweight and fast (the task here is pretty simple)
   • Structure — From the directory tree (paths list). Used the model claude-sonnet-4-6, because this was the default model and I didn't see much difference from other models, and I guess this one is best for tree of structure.
4. Response — JSON with summary, technologies (one-line array), and structure.

---

Dependencies

• fastapi — Web framework.
• uvicorn — ASGI server.
• httpx — Async HTTP client (GitHub API).
• pydantic — Request/validation.
• anthropic — Claude API client.
• gradio — Gradio UI in app.py (Spaces / local).
• python-dotenv — Loads .env for local development (used by main.py).
• certifi — Default CA bundle for TLS (used when custom CA env vars are not set).

---

Logging

• logger.py provides log_entry(), which prints [filename:line] Entering function_name() for the caller.
• Used at entry of main request handlers and helpers to trace execution.

---

License

Use and modify as needed for your project.