---
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](https://huggingface.co/docs/hub/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

```bash
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):

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

### 3. Run the server

```bash
python main.py
```

Server runs at **http://127.0.0.1:8000**.

Or with uvicorn:

```bash
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`):

```bash
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):**

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

**Success response (200):**

```json
{
  "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:

```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

```bash
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:

```python
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.