Chrysopedia
From chrysopoeia (alchemical transmutation of base material into gold) + encyclopedia.
Chrysopedia transmutes raw video content into refined, searchable production knowledge.
A self-hosted knowledge extraction system for electronic music production content. Video libraries are transcribed with Whisper, analyzed through a multi-stage LLM pipeline, curated via an admin review workflow, and served through a search-first web UI designed for mid-session retrieval.
Information Flow
Content moves through six stages from raw video to searchable knowledge:
┌─────────────────────────────────────────────────────────────────────────┐
│ STAGE 1 · Transcription [Desktop / GPU] │
│ │
│ Video files → Whisper large-v3 (CUDA) → JSON transcripts │
│ Output: timestamped segments with speaker text │
└────────────────────────────────┬────────────────────────────────────────┘
│ JSON files (manual or folder watcher)
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ STAGE 2 · Ingestion [API + Watcher] │
│ │
│ POST /api/v1/ingest ← watcher auto-submits from /watch folder │
│ • Validate JSON structure │
│ • Compute content hash (SHA-256) for deduplication │
│ • Find-or-create Creator from folder name │
│ • Upsert SourceVideo (exact filename → content hash → fuzzy match) │
│ • Bulk-insert TranscriptSegment rows │
│ • Dispatch pipeline to Celery worker │
└────────────────────────────────┬────────────────────────────────────────┘
│ Celery task: run_pipeline(video_id)
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ STAGE 3 · LLM Extraction Pipeline [Celery Worker] │
│ │
│ Four sequential LLM stages, each with its own prompt template: │
│ │
│ 3a. Segmentation — Split transcript into semantic topic boundaries │
│ Model: chat (fast) Prompt: stage2_segmentation.txt │
│ │
│ 3b. Extraction — Identify key moments (title, summary, timestamps) │
│ Model: reasoning (think) Prompt: stage3_extraction.txt │
│ │
│ 3c. Classification — Assign content types + extract plugin names │
│ Model: chat (fast) Prompt: stage4_classification.txt │
│ │
│ 3d. Synthesis — Compose technique pages from approved moments │
│ Model: reasoning (think) Prompt: stage5_synthesis.txt │
│ │
│ Each stage emits PipelineEvent rows (tokens, duration, model, errors) │
└────────────────────────────────┬────────────────────────────────────────┘
│ KeyMoment rows (review_status: pending)
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ STAGE 4 · Review & Curation [Admin UI] │
│ │
│ Admin reviews extracted KeyMoments before they become technique pages: │
│ • Approve — moment proceeds to synthesis │
│ • Edit — correct title, summary, content type, plugins, then approve │
│ • Reject — moment is excluded from knowledge base │
│ (When REVIEW_MODE=false, moments auto-approve and skip this stage) │
└────────────────────────────────┬────────────────────────────────────────┘
│ Approved moments → Stage 3d synthesis
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ STAGE 5 · Knowledge Base [Web UI] │
│ │
│ TechniquePages — the primary output: │
│ • Structured body sections, signal chains, plugin lists │
│ • Linked to source KeyMoments with video timestamps │
│ • Cross-referenced via RelatedTechniqueLinks │
│ • Versioned (snapshots before each re-synthesis) │
│ • Organized by topic taxonomy (6 categories from canonical_tags.yaml) │
└────────────────────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ STAGE 6 · Search & Retrieval [Web UI] │
│ │
│ • Semantic search: query → embedding → Qdrant vector similarity │
│ • Keyword fallback: ILIKE search on title/summary (300ms timeout) │
│ • Browse by topic hierarchy, creator, or content type │
│ • Typeahead search from home page (debounced, top 5 results) │
└─────────────────────────────────────────────────────────────────────────┘
Architecture
┌──────────────────────────────────────────────────────────────────────────┐
│ Desktop (GPU workstation — hal0022) │
│ whisper/transcribe.py → JSON transcripts → copy to /watch folder │
└────────────────────────────┬─────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Docker Compose: xpltd_chrysopedia (ub01) │
│ Network: chrysopedia (172.32.0.0/24) │
│ │
│ ┌────────────┐ ┌─────────────┐ ┌───────────────┐ ┌──────────────┐ │
│ │ PostgreSQL │ │ Redis │ │ Qdrant │ │ Ollama │ │
│ │ :5433 │ │ broker + │ │ vector DB │ │ embeddings │ │
│ │ 7 entities │ │ cache │ │ semantic │ │ nomic-embed │ │
│ └─────┬───────┘ └──────┬──────┘ └───────┬───────┘ └──────┬───────┘ │
│ │ │ │ │ │
│ ┌─────┴─────────────────┴─────────────────┴─────────────────┴────────┐ │
│ │ FastAPI (API) │ │
│ │ Ingest · Pipeline control · Review · Search · CRUD · Reports │ │
│ └──────────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ┌──────────────┐ ┌────────────┴───┐ ┌──────────────────────────┐ │
│ │ Watcher │ │ Celery Worker │ │ Web UI (React) │ │
│ │ /watch → │ │ LLM pipeline │ │ nginx → :8096 │ │
│ │ auto-ingest │ │ stages 2-5 │ │ search-first interface │ │
│ └──────────────┘ └────────────────┘ └──────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
Services
| Service |
Image |
Port |
Purpose |
chrysopedia-db |
postgres:16-alpine |
5433 → 5432 |
Primary data store |
chrysopedia-redis |
redis:7-alpine |
— |
Celery broker + feature flag cache |
chrysopedia-qdrant |
qdrant/qdrant:v1.13.2 |
— |
Vector DB for semantic search |
chrysopedia-ollama |
ollama/ollama |
— |
Embedding model server (nomic-embed-text) |
chrysopedia-api |
Dockerfile.api |
8000 |
FastAPI REST API |
chrysopedia-worker |
Dockerfile.api |
— |
Celery worker (LLM pipeline) |
chrysopedia-watcher |
Dockerfile.api |
— |
Folder monitor → auto-ingest |
chrysopedia-web |
Dockerfile.web |
8096 → 80 |
React frontend (nginx) |
Data Model
| Entity |
Purpose |
| Creator |
Artists/producers whose content is indexed |
| SourceVideo |
Video files processed by the pipeline (with content hash dedup) |
| TranscriptSegment |
Timestamped text segments from Whisper |
| KeyMoment |
Discrete insights extracted by LLM analysis |
| TechniquePage |
Synthesized knowledge pages — the primary output |
| TechniquePageVersion |
Snapshots before re-synthesis overwrites |
| RelatedTechniqueLink |
Cross-references between technique pages |
| Tag |
Hierarchical topic taxonomy |
| ContentReport |
User-submitted content issues |
| PipelineEvent |
Structured pipeline execution logs (tokens, timing, errors) |
Quick Start
Prerequisites
- Docker ≥ 24.0 and Docker Compose ≥ 2.20
- Python 3.10+ with NVIDIA GPU + CUDA (for Whisper transcription)
Setup
# Clone and configure
git clone git@github.com:xpltdco/chrysopedia.git
cd chrysopedia
cp .env.example .env # edit with real values
# Start the stack
docker compose up -d
# Run database migrations
docker exec chrysopedia-api alembic upgrade head
# Pull the embedding model (first time only)
docker exec chrysopedia-ollama ollama pull nomic-embed-text
# Verify
curl http://localhost:8096/health
Transcribe videos
cd whisper && pip install -r requirements.txt
# Single file
python transcribe.py --input "path/to/video.mp4" --output-dir ./transcripts
# Batch
python transcribe.py --input ./videos/ --output-dir ./transcripts
See whisper/README.md for full transcription docs.
Environment Variables
Copy .env.example to .env. Key groups:
| Group |
Variables |
Notes |
| Database |
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB |
Default user: chrysopedia |
| LLM |
LLM_API_URL, LLM_API_KEY, LLM_MODEL |
OpenAI-compatible endpoint |
| LLM Fallback |
LLM_FALLBACK_URL, LLM_FALLBACK_MODEL |
Automatic failover |
| Per-Stage Models |
LLM_STAGE{2-5}_MODEL, LLM_STAGE{2-5}_MODALITY |
chat for fast stages, thinking for reasoning |
| Embedding |
EMBEDDING_API_URL, EMBEDDING_MODEL |
Ollama nomic-embed-text |
| Vector DB |
QDRANT_URL, QDRANT_COLLECTION |
Container-internal |
| Features |
REVIEW_MODE, DEBUG_MODE |
Review gate + LLM I/O capture |
| Storage |
TRANSCRIPT_STORAGE_PATH, VIDEO_METADATA_PATH |
Container bind mounts |
API Endpoints
Public
| Method |
Path |
Description |
| GET |
/health |
Health check (DB connectivity) |
| GET |
/api/v1/search?q=&scope=&limit= |
Semantic + keyword search |
| GET |
/api/v1/techniques |
List technique pages |
| GET |
/api/v1/techniques/{slug} |
Technique detail + key moments |
| GET |
/api/v1/techniques/{slug}/versions |
Version history |
| GET |
/api/v1/creators |
List creators (sort, genre filter) |
| GET |
/api/v1/creators/{slug} |
Creator detail |
| GET |
/api/v1/topics |
Topic hierarchy with counts |
| GET |
/api/v1/videos |
List source videos |
| POST |
/api/v1/reports |
Submit content report |
Admin
| Method |
Path |
Description |
| GET |
/api/v1/review/queue |
Review queue (status filter) |
| POST |
/api/v1/review/moments/{id}/approve |
Approve key moment |
| POST |
/api/v1/review/moments/{id}/reject |
Reject key moment |
| PUT |
/api/v1/review/moments/{id} |
Edit key moment |
| POST |
/api/v1/admin/pipeline/trigger/{video_id} |
Trigger/retrigger pipeline |
| GET |
/api/v1/admin/pipeline/events/{video_id} |
Pipeline event log |
| GET |
/api/v1/admin/pipeline/token-summary/{video_id} |
Token usage by stage |
| GET |
/api/v1/admin/pipeline/worker-status |
Celery worker status |
| PUT |
/api/v1/admin/pipeline/debug-mode |
Toggle debug mode |
Ingest
| Method |
Path |
Description |
| POST |
/api/v1/ingest |
Upload Whisper JSON transcript |
Development
# Local backend (with Docker services)
python -m venv .venv && source .venv/bin/activate
pip install -r backend/requirements.txt
docker compose up -d chrysopedia-db chrysopedia-redis
alembic upgrade head
cd backend && uvicorn main:app --reload --host 0.0.0.0 --port 8000
# Database migrations
alembic revision --autogenerate -m "describe_change"
alembic upgrade head
Project Structure
chrysopedia/
├── backend/ # FastAPI application
│ ├── main.py # Entry point, middleware, router mounting
│ ├── config.py # Pydantic Settings (all env vars)
│ ├── models.py # SQLAlchemy ORM models
│ ├── schemas.py # Pydantic request/response schemas
│ ├── worker.py # Celery app configuration
│ ├── watcher.py # Transcript folder watcher service
│ ├── search_service.py # Semantic search + keyword fallback
│ ├── routers/ # API endpoint handlers
│ ├── pipeline/ # LLM pipeline stages + clients
│ │ ├── stages.py # Stages 2-5 (Celery tasks)
│ │ ├── llm_client.py # OpenAI-compatible LLM client
│ │ ├── embedding_client.py
│ │ └── qdrant_client.py
│ └── tests/
├── frontend/ # React + TypeScript + Vite
│ └── src/
│ ├── pages/ # Home, Search, Technique, Creator, Topic, Admin
│ ├── components/ # Shared UI components
│ └── api/ # Typed API clients
├── whisper/ # Desktop transcription (Whisper large-v3)
├── docker/ # Dockerfiles + nginx config
├── alembic/ # Database migrations
├── config/ # canonical_tags.yaml (topic taxonomy)
├── prompts/ # LLM prompt templates (editable at runtime)
├── docker-compose.yml
└── .env.example
Deployment (ub01)
ssh ub01
cd /vmPool/r/repos/xpltdco/chrysopedia
git pull && docker compose build && docker compose up -d
| Resource |
Location |
| Web UI |
http://ub01:8096 |
| API |
http://ub01:8096/health |
| PostgreSQL |
ub01:5433 |
| Compose config |
/vmPool/r/compose/xpltd_chrysopedia/docker-compose.yml |
| Persistent data |
/vmPool/r/services/chrysopedia_* |
XPLTD conventions: xpltd_chrysopedia project name, dedicated bridge network (172.32.0.0/24), bind mounts under /vmPool/r/services/, PostgreSQL on port 5433.
