Metadata-Version: 2.4
Name: reko-yt
Version: 0.3.0
Summary: A modern, local-first CLI tool to extract transcripts from YouTube and transform them into concise summaries and key points.
Keywords: youtube,summarization,llm,cli,ollama,transcript
Author: Riccardo Ruspoli
Author-email: Riccardo Ruspoli <riccardoruspoli@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Text Processing :: Linguistic
Requires-Dist: bleach~=6.3.0
Requires-Dist: dspy~=3.2.1
Requires-Dist: fastapi~=0.136.3
Requires-Dist: iso639-lang~=2.6.3
Requires-Dist: jinja2~=3.1.6
Requires-Dist: markdown~=3.10.2
Requires-Dist: ollama~=0.6.2
Requires-Dist: pytubefix~=10.9.0
Requires-Dist: tqdm~=4.68.1
Requires-Dist: uvicorn~=0.49.0
Requires-Dist: youtube-transcript-api~=1.2.4
Requires-Python: >=3.10, <3.15
Project-URL: Homepage, https://github.com/riccardoruspoli/reko
Project-URL: Repository, https://github.com/riccardoruspoli/reko
Project-URL: Issues, https://github.com/riccardoruspoli/reko/issues
Description-Content-Type: text/markdown

<div align="center">

# reko

**Make YouTube videos readable** 🎥

_A modern, local-first CLI tool to extract transcripts from YouTube and transform them into concise summaries and key points._

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://img.shields.io/pypi/v/reko-yt.svg)](https://pypi.org/project/reko-yt/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

</div>

## ✨ What is reko?

`reko` is a command-line tool that converts YouTube videos into clean Markdown summaries using transcripts and Large Language Models.

Give it a video URL, a playlist, or a file containing multiple URLs, and `reko` will fetch the transcript, summarize the content in manageable chunks, and generate a readable Markdown document with a summary and optional key points.

It’s designed to be simple, fast, and automation-friendly, making it easy to extract useful information from long, informational videos.  
By default, `reko` is local-first and privacy-friendly when used with Ollama, while still supporting paid cloud models when needed.

<p align="center">
  <img src="docs/screenshot.png" alt="Example of a Markdown summary generated by reko" width="700">
</p>

## 🚀 Features

- Generate clean Markdown summaries with optional key points.
- Summarize a single video, a playlist, or a batch of URLs.
- Optimized for Small Language Models (SLMs), which are often sufficient for high-quality summarization.
- Works with Ollama and cloud providers via APIs.
- Multi-language summaries: uses native transcripts when available, with automatic fallback and translation.
- Handles long videos via transcript chunking.
- Skips reprocessing when a summary already exists (with an option to force regeneration).

## 🧠 How it works

At a high level, `reko` follows a simple pipeline:

1. Resolve the input target (video, playlist, or file).
2. Fetch the YouTube transcript in the requested language, with fallback and translation when needed.
3. Split the transcript into word-based chunks.
4. Summarize each chunk independently.
5. Merge chunk summaries into a coherent final result.
6. Output a Markdown file and/or print to stdout.
7. Optionally extract key points from the generated summary.

This approach allows `reko` to scale smoothly from short clips to multi-hour videos.

### Transcript cache

Raw YouTube transcripts are cached locally by video ID and requested language. Re-running a video with different output options or LLM settings reuses the cached transcript and avoids unnecessary YouTube requests. Set `REKO_DATA_DIR` to choose the cache location; use `--refresh-transcript` only when you explicitly need to fetch a fresh transcript.

## 📦 Installation

### Prerequisites

- **Python 3.10–3.14** (all versions are verified in CI)
- An LLM endpoint:
  - **Ollama** (local): install Ollama and pull the model you want to use.
  - **Hosted APIs** (for example `openai/...`): configure the required API keys in your environment. When using non-local providers, the required environment variables must be configured according to the supported provider of the model which can be found [here](https://docs.litellm.ai/docs/providers).

### Install from PyPI

```bash
pip install reko-yt
```

## ⚡ Quick start

Show available commands:

```bash
reko --help
reko summarize --help
```

> [!NOTE]
> Small Language Models are a great default for most summarization tasks.

Summarize a single YouTube video (prints and saves by default):

```bash
reko summarize 'https://www.youtube.com/watch?v=eMlx5fFNoYc' 'ollama/llama3.2:3b'
reko summarize 'https://www.youtube.com/watch?v=eMlx5fFNoYc' 'openai/gpt-5-nano'
```

For OpenAI GPT-5 models, `reko` uses the Responses API and maps `--max-tokens` to
OpenAI's completion-token limit. GPT-5 reasoning models only support the default
sampling temperature, so custom `--temperature` values are ignored for those
models. You can tune reasoning cost/latency with:

```bash
reko summarize 'https://www.youtube.com/watch?v=eMlx5fFNoYc' \
  'openai/gpt-5-nano' \
  --reasoning-effort low
```

Generate key points only, in Italian, without saving to disk:

```bash
reko summarize 'https://www.youtube.com/watch?v=eMlx5fFNoYc' \
  'ollama/llama3.2:3b' \
  --length short \
  --language it \
  --key-points-only \
  --print-only
```

Summarize a playlist or a batch of URLs:

```bash
reko summarize 'https://www.youtube.com/playlist?list=PL908547EAA7E4AE74' 'ollama/llama3.2:3b'
reko summarize urls.txt 'ollama/llama3.2:3b'
```

> [!WARNING]
> When processing playlists or large batches, YouTube may temporarily rate-limit your IP.  
> Using a proxy is recommended for high-volume usage.

Use a remote Ollama instance:

```bash
reko summarize 'https://www.youtube.com/watch?v=eMlx5fFNoYc' 'ollama/llama3.2:3b' --host 'http://YOUR_OLLAMA_HOST:11434'
```

## 🌐 Local web UI

Start a local web page that can summarize a YouTube URL and render the Markdown:

```bash
reko serve
```

Then open `http://127.0.0.1:8000` in your browser.

Options:

```bash
reko serve --host 127.0.0.1 --port 8000
reko serve --host 0.0.0.0 --port 8000  # expose on your LAN
```

Notes:

- The web UI supports single video URLs (no playlists/batch files).
- Jobs run asynchronously. The UI streams progress with Server-Sent Events (SSE)
  and falls back to a one-second status poll when SSE is unavailable.
- A job reports transcript-cache hit/miss, chunk progress, retries, input/output
  words, elapsed time, phase timings, and terminal success/failure/cancellation.
- Cancel is cooperative: an active LLM request is allowed to finish, but no next
  phase is started. Failed and cancelled jobs can be retried from the UI.
- `REKO_MAX_CONCURRENT_JOBS` controls the in-memory job limit and defaults to
  `1`, which is appropriate for a home server or a local LLM endpoint.
- If a reverse proxy is in front of reko, disable response buffering for
  `/api/jobs/*/events` and preserve `text/event-stream`; otherwise the browser
  will automatically use polling instead of live progress.

## 🐳 Container deployment

The container runs only reko. Configure Ollama or another LLM provider separately in the web UI; Ollama is intentionally not part of the Compose stack.

```bash
cp .env.example .env
docker compose up -d
```

Open `http://YOUR_SERVER:8000`. Transcript cache files are persisted in `./data`. For an Ollama service running on the Docker host, use `http://host.docker.internal:11434` in the UI; for a different host, use an address reachable from the container.

Check service health with:

```bash
curl http://localhost:8000/health
```

## 🧪 Development

All automated checks are offline and use mock data only. Install the development dependencies and run them with `uv`:

```bash
uv sync --group dev
uv run ruff format --check src test
uv run ruff check src test
uv run python -m pytest --cov=src/reko --cov-branch --cov-report=term-missing --cov-report=xml --cov-fail-under=90
uv build
```

## 🚀 Releases

The release workflow runs when a `vX.Y.Z` tag is pushed. It runs the offline quality checks, builds the Python distributions, publishes to PyPI through Trusted Publishing, pushes a tagged image to GHCR, and creates GitHub release notes with git-cliff.

Before the first release, configure PyPI Trusted Publishing for this repository and the `release.yml` workflow, create the protected GitHub environment named `pypi`, and set the GHCR package visibility you want. Set the release version in `pyproject.toml`; the workflow verifies that the tag version matches it.

To refresh the committed changelog before creating a release, run git-cliff locally:

```bash
git cliff --tag vX.Y.Z --output CHANGELOG.md
```

## 📄 License

MIT. See `LICENSE`.
