bradan — the course consumer & assimilator

A big concept from a course — ready to work with your agent stack. Point bradan at any course (video lessons, webinar recordings, web pages, PDFs), and it acquires, transcribes, and distills the material into a structured, keyword-annotated corpus that your agents, your knowledge base, and your renderers consume directly.

This repo packages a course-ingest pipeline, built to be adopted and extended — see CONTRIBUTING.md. Optional integrations (knowledge base, renderer, keyword lanes) are documented in HANDBOOK.md as thin adapters, not baked in.

Why this shape

Every real-world course-consumption pipeline hits the same walls:

1. Acquisition — course media lives behind platforms (YouTube, Vimeo, course platforms), web pages, and PDFs. Tools: yt-dlp + stdlib fetch.
2. Transcription — video/audio → word-timestamped text. Tool: local Whisper-class STT (MLX Whisper on Apple Silicon; faster-whisper elsewhere). Local-first: no per-minute API tax, no content leaving the machine.
3. Distillation — transcripts → keywords, concepts, next-best-sentence seeds, course map. Tool: local scoring pass (stdlib only, no API key).
4. Assimilation — the distilled corpus becomes usable knowledge: brain pages, research components, render scripts. These are adapters (see HANDBOOK.md), not core.

The core (this repo) is deliberately stdlib-only + one STT dependency. Everything else plugs in.

The pipeline

acquire (scrape.py)       → media + acquisition.json (url, sha256, tool, timestamp)
transcribe (transcribe.py) → .transcript.json + .txt + .srt + .sha256
distill (distill.py)      → concept-graph.json (typed nodes/edges) + synthesis.json (summary, takeaways,
                            caveats, decision notes, learning path) + course-map.md
                            (+ legacy keywords.json / concepts.json / next-best-seeds.json)
assimilate (adapters)     → knowledge page / keyword lanes / render script  [HANDBOOK.md]

Every stage is idempotent and provenance-anchored: the sha256 of the source media anchors the manifest, and the transcript fingerprints its source file. Re-runs are cheap; nothing silently loses its origin.

Install

bash install.sh            # creates an isolated venv (mlx-whisper on Apple Silicon, faster-whisper elsewhere)
export BRADAN_VENV_PYTHON=~/.hermes/venvs/bradan/bin/python

Alternative venv dirs are fine: bash install.sh ~/my-venv then pass --venv-python.

Usage

# 1. Acquire a lesson (video platform link or web page)
python3 scrape.py "https://www.youtube.com/watch?v=XXXX" --out-dir ./course/media --audio-only
python3 scrape.py "https://some-course-platform.com/lesson-page" --out-dir ./course/pages

# 2. Transcribe everything in a directory
python3 transcribe.py ./course/media/lesson-01.m4a --out-dir ./course/transcripts

# 3. Distill the corpus