How rafapolo/sumaria works
Project type and purpose
• This is a lightweight command-line application (“SumarIA”) for fetching YouTube video transcripts and generating summaries using a local open-source LLM.
• It’s an open-source tool or CLI utility rather than a full-stack web app or microservice suite.
File structure
• Top-level:
– src/
• sumaria.py – the CLI entry point
• transcript_fetcher.py – encapsulates YouTube Transcript API calls
• summarizer.py – encapsulates prompt-construction, chunking logic, and LLM calls
– cached/ – persistent storage of raw transcripts and summary outputs
– requirements.txt – Python dependencies (requests, youtube-transcript-api)
• No “frontend/backend” split; modules follow a simple pipeline pattern.
README for architecture hints
• Describes three main components: entry point, fetcher, summarizer
• External dependencies: YouTube Transcript API, a local Ollama LLM server (HTTP on localhost)
• Caching layer to avoid repeated fetches
a. Main components
1. CLI Layer (sumaria.py)
2. Transcript Fetcher Module
3. Summarizer Module
4. Cache / File System (cached/)
5. External Services:
– YouTube Transcript API
– Local LLM Service (Ollama HTTP server)
b. Relationships & data flow
1. User invokes CLI → sumaria.py parses video ID
2. sumaria.py calls Transcript Fetcher → checks cache → if miss, invokes YouTube API → writes transcript.txt to cached/<video_id>/
3. sumaria.py calls Summarizer → reads transcript.txt → splits into semantic chunks → for each chunk, sends HTTP request to local LLM service → receives chunk summary
4. Aggregator collates chunk summaries → writes summary.md in cached/<video_id>/
5. sumaria.py logs results to console
c. Architectural patterns & principles
• Pipeline pattern: sequential processing (fetch → transform → output)
• Single-responsibility modules (fetcher vs. summarizer)
• Caching for idempotency and performance
• Externalized prompts and chunking logic for maintainability
d. Key technologies & libraries
• Python 3.x
• requests (HTTP client)
• youtube-transcript-api
• ollama (local LLM serve via HTTP)
• local file I/O for caching
Detail without over-splitting
• Every module boundary and cache interaction
• Avoid decomposing internal functions too deeply—focus on inter-module boundaries