> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://summarize.martino.im/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://summarize.martino.im/_mcp/server.

# Contributing

Thanks for helping improve [martinopiaggi/summarize](https://github.com/martinopiaggi/summarize).

## Prerequisites

* **Python** 3.7+ (3.12 recommended)
* **ffmpeg** on your `PATH`
* At least one **LLM API key** in `.env` (see `summarizer.example.yaml` for provider names)
* **Git**

Optional:

* **Docker** + Docker Compose (Streamlit + Cobalt stack)
* **Node.js** 20+ (Fern docs only)

## Local Setup

```bash
git clone https://github.com/martinopiaggi/summarize.git
cd summarize
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -e ".[all]"
pip install pytest streamlit
python -m summarizer --init-config   # or: cp summarizer.example.yaml summarizer.yaml
```

Add API keys to `.env`.

## Running the Project

| Surface   | Command                                                                                 |
| --------- | --------------------------------------------------------------------------------------- |
| CLI       | `python -m summarizer --source "https://youtube.com/watch?v=VIDEO_ID"`                  |
| HTTP API  | `python -m summarizer serve` → [http://localhost:8000/docs](http://localhost:8000/docs) |
| Streamlit | `python -m streamlit run app.py` → [http://localhost:8501](http://localhost:8501)       |
| Docker    | `docker compose up -d`                                                                  |

## Repository Layout

```mermaid
flowchart TD
  web[Streamlit webapp] --> engine[summarizer engine]
  ray[Raycast extension] --> engine
  skill[agent skill] --> engine
  tests[pytest] --> engine
  ci[GitHub workflows] --> engine
  ci --> docs[Fern docs]
```

Every surface calls `summarizer.core.main(config)`; the webapp, HTTP API, CLI, and Docker image share the same engine.

## Tests

```bash
pytest tests/
```

Run tests before opening a PR. Add or update tests when changing behavior.

## Architecture Discipline

All user-facing surfaces (CLI, API, Streamlit, Docker) should call `summarizer.core.main(config)`. Do not add parallel summarization pipelines.

Config flows through `summarizer.config_file.merge_configs()` and `summarizer.api_utils.build_runtime_config()`.

## Pull Requests

1. Fork and branch from `main`
2. Keep changes focused — one logical change per PR
3. **Never commit secrets** — no API keys, `.env`, or personal `summarizer.yaml` with credentials
4. Update docs if install paths or user-facing behavior changes
5. Describe what you tested in the PR body

See also [CONTRIBUTING.md](https://github.com/martinopiaggi/summarize/blob/main/CONTRIBUTING.md) on GitHub.