xpltdco/chrysopedia
2
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions

fix: Fixed syntax errors in pipeline event instrumentation — _emit_even…

Browse source 
- "backend/pipeline/stages.py"

GSD-Task: S01/T01
This commit is contained in:
jlightner 2026-03-30 08:27:53 +00:00
parent e08e8d021f
commit 7aa33cd17f
88 changed files with 272 additions and 14814 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
.env.example
View file

@ -1,52 +0,0 @@
# ─── Chrysopedia Environment Variables ───
# Copy to .env and fill in secrets before docker compose up
# PostgreSQL
POSTGRES_USER=chrysopedia
POSTGRES_PASSWORD=changeme
POSTGRES_DB=chrysopedia
# Redis (Celery broker) — container-internal, no secret needed
REDIS_URL=redis://chrysopedia-redis:6379/0
# LLM endpoint (OpenAI-compatible — OpenWebUI on FYN DGX)
LLM_API_URL=https://chat.forgetyour.name/api/v1
LLM_API_KEY=sk-changeme
LLM_MODEL=fyn-llm-agent-chat
LLM_FALLBACK_URL=https://chat.forgetyour.name/api/v1
LLM_FALLBACK_MODEL=fyn-llm-agent-chat
# Per-stage LLM model overrides (optional — defaults to LLM_MODEL)
# Modality: "chat" = standard JSON mode, "thinking" = reasoning model (strips <think> tags)
# Stages 2 (segmentation) and 4 (classification) are mechanical — use fast chat model
# Stages 3 (extraction) and 5 (synthesis) need reasoning — use thinking model
LLM_STAGE2_MODEL=fyn-llm-agent-chat
LLM_STAGE2_MODALITY=chat
LLM_STAGE3_MODEL=fyn-llm-agent-think
LLM_STAGE3_MODALITY=thinking
LLM_STAGE4_MODEL=fyn-llm-agent-chat
LLM_STAGE4_MODALITY=chat
LLM_STAGE5_MODEL=fyn-llm-agent-think
LLM_STAGE5_MODALITY=thinking
# Max tokens for LLM responses (OpenWebUI defaults to 1000 — pipeline needs much more)
LLM_MAX_TOKENS=65536
# Embedding endpoint (Ollama container in the compose stack)
EMBEDDING_API_URL=http://chrysopedia-ollama:11434/v1
EMBEDDING_MODEL=nomic-embed-text
# Qdrant (container-internal)
QDRANT_URL=http://chrysopedia-qdrant:6333
QDRANT_COLLECTION=chrysopedia
# Application
APP_ENV=production
APP_LOG_LEVEL=info
# File storage paths (inside container, bind-mounted to /vmPool/r/services/chrysopedia_data)
TRANSCRIPT_STORAGE_PATH=/data/transcripts
VIDEO_METADATA_PATH=/data/video_meta
# Review mode toggle (true = moments require admin review before publishing)
REVIEW_MODE=true

11
.gsd/milestones/M005/M005-ROADMAP.md Normal file
View file

@ -0,0 +1,11 @@
# M005:
## Vision
Add a pipeline management dashboard under admin (trigger, pause, monitor, view logs/token usage/JSON responses), redesign technique pages with a 2-column layout (prose left, moments/chains/plugins right), and clean up key moment card presentation for consistent readability.
## Slice Overview
| ID | Slice | Risk | Depends | Done | After this |
|----|-------|------|---------|------|------------|
| S01 | Pipeline Admin Dashboard | high | — | ⬜ | Admin page at /admin/pipeline shows video list with status, retrigger button, and log viewer with token counts and expandable JSON responses |
| S02 | Technique Page 2-Column Layout | medium | — | ⬜ | Technique page shows prose content on left, plugins/moments/chains on right at desktop widths. Single column on mobile. |
| S03 | Key Moment Card Redesign | low | S02 | ⬜ | Key moment cards show title prominently on its own line, with source file, timestamp, and type badge on a clean secondary row |

18
.gsd/milestones/M005/slices/S01/S01-PLAN.md Normal file
View file

@ -0,0 +1,18 @@
# S01: Pipeline Admin Dashboard
**Goal:** Build a pipeline management admin page with monitoring, triggering, pausing, and debugging capabilities including token usage and expandable JSON responses
**Demo:** After this: Admin page at /admin/pipeline shows video list with status, retrigger button, and log viewer with token counts and expandable JSON responses
## Tasks
- [x] **T01: Fixed syntax errors in pipeline event instrumentation — _emit_event and _make_llm_callback now work correctly, events persist to pipeline_events table** — Add PipelineEvent DB model (video_id, stage, event_type, payload JSONB, token counts, created_at). Alembic migration 004. Instrument LLM client to persist events (token usage, response content) per-call. Instrument each stage to emit start/complete/error events.
- Estimate: 45min
- Files: backend/models.py, backend/schemas.py, alembic/versions/004_pipeline_events.py, backend/pipeline/llm_client.py, backend/pipeline/stages.py
- Verify: docker exec chrysopedia-api python -c 'from models import PipelineEvent; print(OK)' && docker exec chrysopedia-api alembic upgrade head
- [ ] **T02: Pipeline admin API endpoints** — New router: GET /admin/pipeline/videos (list with status + event counts), POST /admin/pipeline/trigger/{video_id} (retrigger), POST /admin/pipeline/revoke/{video_id} (pause/stop via Celery revoke), GET /admin/pipeline/events/{video_id} (event log with pagination), GET /admin/pipeline/worker-status (active/reserved tasks from Celery inspect).
- Estimate: 30min
- Files: backend/routers/pipeline.py, backend/schemas.py, backend/main.py
- Verify: curl -s http://localhost:8096/api/v1/admin/pipeline/videos | python3 -m json.tool && curl -s http://localhost:8096/api/v1/admin/pipeline/worker-status | python3 -m json.tool
- [ ] **T03: Pipeline admin frontend page** — New AdminPipeline.tsx page at /admin/pipeline. Video list table with status badges, retrigger/pause buttons. Expandable row showing event log timeline with token usage and collapsible JSON response viewer. Worker status indicator. Wire into App.tsx and nav.
- Estimate: 45min
- Files: frontend/src/pages/AdminPipeline.tsx, frontend/src/api/public-client.ts, frontend/src/App.tsx, frontend/src/App.css
- Verify: docker compose build chrysopedia-web 2>&1 | tail -5 (exit 0, zero TS errors)

26
.gsd/milestones/M005/slices/S01/tasks/T01-PLAN.md Normal file
View file

@ -0,0 +1,26 @@
---
estimated_steps: 1
estimated_files: 5
skills_used: []
---
# T01: PipelineEvent model, migration, and event capture in pipeline stages
Add PipelineEvent DB model (video_id, stage, event_type, payload JSONB, token counts, created_at). Alembic migration 004. Instrument LLM client to persist events (token usage, response content) per-call. Instrument each stage to emit start/complete/error events.
## Inputs
- `backend/models.py`
- `backend/pipeline/llm_client.py`
- `backend/pipeline/stages.py`
## Expected Output
- `backend/models.py (PipelineEvent model)`
- `alembic/versions/004_pipeline_events.py`
- `backend/pipeline/llm_client.py (event persistence)`
- `backend/pipeline/stages.py (stage event emission)`
## Verification
docker exec chrysopedia-api python -c 'from models import PipelineEvent; print(OK)' && docker exec chrysopedia-api alembic upgrade head

76
.gsd/milestones/M005/slices/S01/tasks/T01-SUMMARY.md Normal file
View file

@ -0,0 +1,76 @@
---
id: T01
parent: S01
milestone: M005
provides: []
requires: []
affects: []
key_files: ["backend/pipeline/stages.py"]
key_decisions: ["Fixed _emit_event to use _get_sync_session() with explicit try/finally close instead of nonexistent _get_session_factory() context manager"]
patterns_established: []
drill_down_paths: []
observability_surfaces: []
duration: ""
verification_result: "docker exec chrysopedia-api python -c 'from models import PipelineEvent; print("OK")' → OK (exit 0). docker exec chrysopedia-api alembic upgrade head → already at 004_pipeline_events head (exit 0). docker exec chrysopedia-api python -c 'from pipeline.stages import _emit_event, _make_llm_callback; print("OK")' → OK (exit 0). Manual _emit_event test call persisted event to DB and was verified via psql count."
completed_at: 2026-03-30T08:27:47.536Z
blocker_discovered: false
---
# T01: Fixed syntax errors in pipeline event instrumentation — _emit_event and _make_llm_callback now work correctly, events persist to pipeline_events table
> Fixed syntax errors in pipeline event instrumentation — _emit_event and _make_llm_callback now work correctly, events persist to pipeline_events table
## What Happened
---
id: T01
parent: S01
milestone: M005
key_files:
- backend/pipeline/stages.py
key_decisions:
- Fixed _emit_event to use _get_sync_session() with explicit try/finally close instead of nonexistent _get_session_factory() context manager
duration: ""
verification_result: passed
completed_at: 2026-03-30T08:27:47.536Z
blocker_discovered: false
---
# T01: Fixed syntax errors in pipeline event instrumentation — _emit_event and _make_llm_callback now work correctly, events persist to pipeline_events table
**Fixed syntax errors in pipeline event instrumentation — _emit_event and _make_llm_callback now work correctly, events persist to pipeline_events table**
## What Happened
The PipelineEvent model, Alembic migration 004, and event instrumentation code already existed but _emit_event and _make_llm_callback in stages.py had critical syntax errors: missing triple-quote docstrings, unquoted string literals, unquoted logger format string, and reference to nonexistent _get_session_factory(). Fixed all issues, replaced _get_session_factory() with existing _get_sync_session(), rebuilt and redeployed containers. Verified 24 real events already in the pipeline_events table from prior runs, and confirmed the fixed functions import and execute correctly.
## Verification
docker exec chrysopedia-api python -c 'from models import PipelineEvent; print("OK")' → OK (exit 0). docker exec chrysopedia-api alembic upgrade head → already at 004_pipeline_events head (exit 0). docker exec chrysopedia-api python -c 'from pipeline.stages import _emit_event, _make_llm_callback; print("OK")' → OK (exit 0). Manual _emit_event test call persisted event to DB and was verified via psql count.
## Verification Evidence
| # | Command | Exit Code | Verdict | Duration |
|---|---------|-----------|---------|----------|
| 1 | `docker exec chrysopedia-api python -c 'from models import PipelineEvent; print("OK")'` | 0 | ✅ pass | 1000ms |
| 2 | `docker exec chrysopedia-api alembic upgrade head` | 0 | ✅ pass | 1000ms |
| 3 | `docker exec chrysopedia-api python -c 'from pipeline.stages import _emit_event, _make_llm_callback; print("OK")'` | 0 | ✅ pass | 1000ms |
## Deviations
Model, migration, and instrumentation code already existed — task became a syntax fix rather than writing from scratch. Replaced nonexistent _get_session_factory() with existing _get_sync_session() pattern.
## Known Issues
None.
## Files Created/Modified
- `backend/pipeline/stages.py`
## Deviations
Model, migration, and instrumentation code already existed — task became a syntax fix rather than writing from scratch. Replaced nonexistent _get_session_factory() with existing _get_sync_session() pattern.
## Known Issues
None.

24
.gsd/milestones/M005/slices/S01/tasks/T02-PLAN.md Normal file
View file

@ -0,0 +1,24 @@
---
estimated_steps: 1
estimated_files: 3
skills_used: []
---
# T02: Pipeline admin API endpoints
New router: GET /admin/pipeline/videos (list with status + event counts), POST /admin/pipeline/trigger/{video_id} (retrigger), POST /admin/pipeline/revoke/{video_id} (pause/stop via Celery revoke), GET /admin/pipeline/events/{video_id} (event log with pagination), GET /admin/pipeline/worker-status (active/reserved tasks from Celery inspect).
## Inputs
- `backend/routers/pipeline.py`
- `backend/models.py`
- `backend/schemas.py`
## Expected Output
- `backend/routers/pipeline.py (expanded with admin endpoints)`
- `backend/schemas.py (pipeline admin schemas)`
## Verification
curl -s http://localhost:8096/api/v1/admin/pipeline/videos | python3 -m json.tool && curl -s http://localhost:8096/api/v1/admin/pipeline/worker-status | python3 -m json.tool

26
.gsd/milestones/M005/slices/S01/tasks/T03-PLAN.md Normal file
View file

@ -0,0 +1,26 @@
---
estimated_steps: 1
estimated_files: 4
skills_used: []
---
# T03: Pipeline admin frontend page
New AdminPipeline.tsx page at /admin/pipeline. Video list table with status badges, retrigger/pause buttons. Expandable row showing event log timeline with token usage and collapsible JSON response viewer. Worker status indicator. Wire into App.tsx and nav.
## Inputs
- `frontend/src/api/public-client.ts`
- `frontend/src/App.tsx`
- `frontend/src/App.css`
## Expected Output
- `frontend/src/pages/AdminPipeline.tsx`
- `frontend/src/api/public-client.ts (pipeline admin API functions)`
- `frontend/src/App.tsx (route + nav)`
- `frontend/src/App.css (pipeline admin styles)`
## Verification
docker compose build chrysopedia-web 2>&1 | tail -5 (exit 0, zero TS errors)

6
.gsd/milestones/M005/slices/S02/S02-PLAN.md Normal file
View file

@ -0,0 +1,6 @@
# S02: Technique Page 2-Column Layout
**Goal:** Restructure technique page into a responsive 2-column layout with sidebar content
**Demo:** After this: Technique page shows prose content on left, plugins/moments/chains on right at desktop widths. Single column on mobile.
## Tasks

6
.gsd/milestones/M005/slices/S03/S03-PLAN.md Normal file
View file

@ -0,0 +1,6 @@
# S03: Key Moment Card Redesign
**Goal:** Clean up key moment card layout for consistent readability
**Demo:** After this: Key moment cards show title prominently on its own line, with source file, timestamp, and type badge on a clean secondary row
## Tasks

322
README.md
View file

@ -1,322 +0,0 @@
# 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 and retrieval system for electronic music production content. Transcribes video libraries with Whisper, extracts key moments and techniques with LLM analysis, and serves a search-first web UI for mid-session retrieval.
---
## Architecture
```
┌──────────────────────────────────────────────────────────────────┐
│ Desktop (GPU workstation) │
│ ┌──────────────┐ │
│ │ whisper/ │ Transcribes video → JSON (Whisper large-v3) │
│ │ transcribe.py │ Runs locally with CUDA, outputs to /data │
│ └──────┬───────┘ │
│ │ JSON transcripts │
└─────────┼────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ Docker Compose (xpltd_chrysopedia) — Server (e.g. ub01) │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌──────────────────┐ │
│ │ chrysopedia-db │ │chrysopedia-redis│ │ chrysopedia-api │ │
│ │ PostgreSQL 16 │ │ Redis 7 │ │ FastAPI + Uvicorn│ │
│ │ :5433→5432 │ │ │ │ :8000 │ │
│ └────────────────┘ └────────────────┘ └────────┬─────────┘ │
│ │ │
│ ┌──────────────────┐ ┌──────────────────────┐ │ │
│ │ chrysopedia-web │ │ chrysopedia-worker │ │ │
│ │ React + nginx │ │ Celery (LLM pipeline)│ │ │
│ │ :3000→80 │ │ │ │ │
│ └──────────────────┘ └──────────────────────┘ │ │
│ │ │
│ Network: chrysopedia (172.24.0.0/24) │ │
└──────────────────────────────────────────────────────────────────┘
```
### Services
| Service | Image / Build | Port | Purpose |
|----------------------|------------------------|---------------|--------------------------------------------|
| `chrysopedia-db` | `postgres:16-alpine` | `5433 → 5432` | Primary data store (7 entity schema) |
| `chrysopedia-redis` | `redis:7-alpine` | — | Celery broker / cache |
| `chrysopedia-api` | `docker/Dockerfile.api`| `8000` | FastAPI REST API |
| `chrysopedia-worker` | `docker/Dockerfile.api`| — | Celery worker for LLM pipeline stages 2-5 |
| `chrysopedia-web` | `docker/Dockerfile.web`| `3000 → 80` | React frontend (nginx) |
### Data Model (7 entities)
- **Creator** — artists/producers whose content is indexed
- **SourceVideo** — original video files processed by the pipeline
- **TranscriptSegment** — timestamped text segments from Whisper
- **KeyMoment** — discrete insights extracted by LLM analysis
- **TechniquePage** — synthesized knowledge pages (primary output)
- **RelatedTechniqueLink** — cross-references between technique pages
- **Tag** — hierarchical topic/genre taxonomy
---
## Prerequisites
- **Docker** ≥ 24.0 and **Docker Compose** ≥ 2.20
- **Python 3.10+** (for the Whisper transcription script)
- **ffmpeg** (for audio extraction)
- **NVIDIA GPU + CUDA** (recommended for Whisper; CPU fallback available)
---
## Quick Start
### 1. Clone and configure
```bash
git clone <repository-url>
cd content-to-kb-automator
# Create environment file from template
cp .env.example .env
# Edit .env with your actual values (see Environment Variables below)
```
### 2. Start the Docker Compose stack
```bash
docker compose up -d
```
This starts PostgreSQL, Redis, the API server, the Celery worker, and the web UI.
### 3. Run database migrations
```bash
# From inside the API container:
docker compose exec chrysopedia-api alembic upgrade head
# Or locally (requires Python venv with backend deps):
alembic upgrade head
```
### 4. Verify the stack
```bash
# Health check (with DB connectivity)
curl http://localhost:8000/health
# API health (lightweight, no DB)
curl http://localhost:8000/api/v1/health
# Docker Compose status
docker compose ps
```
### 5. Transcribe videos (desktop)
```bash
cd whisper
pip install -r requirements.txt
# Single file
python transcribe.py --input "path/to/video.mp4" --output-dir ./transcripts
# Batch (all videos in a directory)
python transcribe.py --input ./videos/ --output-dir ./transcripts
```
See [`whisper/README.md`](whisper/README.md) for full transcription documentation.
---
## Environment Variables
Create `.env` from `.env.example`. All variables have sensible defaults for local development.
### Database
| Variable | Default | Description |
|--------------------|----------------|---------------------------------|
| `POSTGRES_USER` | `chrysopedia` | PostgreSQL username |
| `POSTGRES_PASSWORD`| `changeme` | PostgreSQL password |
| `POSTGRES_DB` | `chrysopedia` | Database name |
| `DATABASE_URL` | *(composed)* | Full async connection string |
### Services
| Variable | Default | Description |
|-----------------|------------------------------------|--------------------------|
| `REDIS_URL` | `redis://chrysopedia-redis:6379/0` | Redis connection string |
### LLM Configuration
| Variable | Default | Description |
|---------------------|-------------------------------------------|------------------------------------|
| `LLM_API_URL` | `https://friend-openwebui.example.com/api`| Primary LLM endpoint (OpenAI-compatible) |
| `LLM_API_KEY` | `sk-changeme` | API key for primary LLM |
| `LLM_MODEL` | `qwen2.5-72b` | Primary model name |
| `LLM_FALLBACK_URL` | `http://localhost:11434/v1` | Fallback LLM endpoint (Ollama) |
| `LLM_FALLBACK_MODEL`| `qwen2.5:14b-q8_0` | Fallback model name |
### Embedding / Vector
| Variable | Default | Description |
|-----------------------|-------------------------------|--------------------------|
| `EMBEDDING_API_URL` | `http://localhost:11434/v1` | Embedding endpoint |
| `EMBEDDING_MODEL` | `nomic-embed-text` | Embedding model name |
| `QDRANT_URL` | `http://qdrant:6333` | Qdrant vector DB URL |
| `QDRANT_COLLECTION` | `chrysopedia` | Qdrant collection name |
### Application
| Variable | Default | Description |
|--------------------------|----------------------------------|--------------------------------|
| `APP_ENV` | `production` | Environment (`development` / `production`) |
| `APP_LOG_LEVEL` | `info` | Log level |
| `APP_SECRET_KEY` | `changeme-generate-a-real-secret`| Application secret key |
| `TRANSCRIPT_STORAGE_PATH`| `/data/transcripts` | Transcript JSON storage path |
| `VIDEO_METADATA_PATH` | `/data/video_meta` | Video metadata storage path |
| `REVIEW_MODE` | `true` | Enable human review workflow |
---
## Development Workflow
### Local development (without Docker)
```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate
# Install backend dependencies
pip install -r backend/requirements.txt
# Start PostgreSQL and Redis (via Docker)
docker compose up -d chrysopedia-db chrysopedia-redis
# Run migrations
alembic upgrade head
# Start the API server with hot-reload
cd backend && uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
### Database migrations
```bash
# Create a new migration after model changes
alembic revision --autogenerate -m "describe_change"
# Apply all pending migrations
alembic upgrade head
# Rollback one migration
alembic downgrade -1
```
### Project structure
```
content-to-kb-automator/
├── backend/ # FastAPI application
│ ├── main.py # App entry point, middleware, routers
│ ├── config.py # pydantic-settings configuration
│ ├── database.py # SQLAlchemy async engine + session
│ ├── models.py # 7-entity ORM models
│ ├── schemas.py # Pydantic request/response schemas
│ ├── routers/ # API route handlers
│ │ ├── health.py # /health (DB check)
│ │ ├── creators.py # /api/v1/creators
│ │ └── videos.py # /api/v1/videos
│ └── requirements.txt # Python dependencies
├── whisper/ # Desktop transcription script
│ ├── transcribe.py # Whisper CLI tool
│ ├── requirements.txt # Whisper + ffmpeg deps
│ └── README.md # Transcription documentation
├── docker/ # Dockerfiles
│ ├── Dockerfile.api # FastAPI + Celery image
│ ├── Dockerfile.web # React + nginx image
│ └── nginx.conf # nginx reverse proxy config
├── alembic/ # Database migrations
│ ├── env.py # Migration environment
│ └── versions/ # Migration scripts
├── config/ # Configuration files
│ └── canonical_tags.yaml # 6 topic categories + genre taxonomy
├── prompts/ # LLM prompt templates (editable)
├── frontend/ # React web UI (placeholder)
├── tests/ # Test fixtures and test suites
│ └── fixtures/ # Sample data for testing
├── docker-compose.yml # Full stack definition
├── alembic.ini # Alembic configuration
├── .env.example # Environment variable template
└── chrysopedia-spec.md # Full project specification
```
---
## API Endpoints
| Method | Path | Description |
|--------|-----------------------------|---------------------------------|
| GET | `/health` | Health check with DB connectivity |
| GET | `/api/v1/health` | Lightweight health (no DB) |
| GET | `/api/v1/creators` | List all creators |
| GET | `/api/v1/creators/{slug}` | Get creator by slug |
| GET | `/api/v1/videos` | List all source videos |
---
## XPLTD Conventions
This project follows XPLTD infrastructure conventions:
- **Docker project name:** `xpltd_chrysopedia`
- **Bind mounts:** persistent data stored under `/vmPool/r/services/`
- **Network:** dedicated bridge `chrysopedia` (`172.32.0.0/24`)
- **PostgreSQL host port:** `5433` (avoids conflict with system PostgreSQL on `5432`)
---
## Deployment (ub01)
The production stack runs on **ub01.a.xpltd.co**:
```bash
# Clone (first time only — requires SSH agent forwarding)
ssh -A ub01
cd /vmPool/r/repos/xpltdco/chrysopedia
git clone git@github.com:xpltdco/chrysopedia.git .
# Create .env from template
cp .env.example .env
# Edit .env with production secrets
# Build and start
docker compose build
docker compose up -d
# Run migrations
docker exec chrysopedia-api alembic upgrade head
# Pull embedding model (first time only)
docker exec chrysopedia-ollama ollama pull nomic-embed-text
```
### Service URLs
| Service | URL |
|---------|-----|
| Web UI | http://ub01:8096 |
| API Health | http://ub01:8096/health |
| PostgreSQL | ub01:5433 |
| Compose config | `/vmPool/r/compose/xpltd_chrysopedia/docker-compose.yml` |
### Update Workflow
```bash
ssh -A ub01
cd /vmPool/r/repos/xpltdco/chrysopedia
git pull
docker compose build && docker compose up -d
```

37
alembic.ini
View file

@ -1,37 +0,0 @@
# Chrysopedia — Alembic configuration
[alembic]
script_location = alembic
sqlalchemy.url = postgresql+asyncpg://chrysopedia:changeme@localhost:5433/chrysopedia
[loggers]
keys = root,sqlalchemy,alembic
[handlers]
keys = console
[formatters]
keys = generic
[logger_root]
level = WARN
handlers = console
[logger_sqlalchemy]
level = WARN
handlers =
qualname = sqlalchemy.engine
[logger_alembic]
level = INFO
handlers =
qualname = alembic
[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic
[formatter_generic]
format = %(levelname)-5.5s [%(name)s] %(message)s
datefmt = %H:%M:%S

72
alembic/env.py
View file

@ -1,72 +0,0 @@
"""Alembic env.py — async migration runner for Chrysopedia."""
import asyncio
import os
import sys
from logging.config import fileConfig
from alembic import context
from sqlalchemy import pool
from sqlalchemy.ext.asyncio import async_engine_from_config
# Ensure the backend package is importable
# When running locally: alembic/ sits beside backend/, so ../backend works
# When running in Docker: alembic/ is inside /app/ alongside the backend modules
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "backend"))
sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
from database import Base # noqa: E402
import models # noqa: E402, F401 — registers all tables on Base.metadata
config = context.config
if config.config_file_name is not None:
fileConfig(config.config_file_name)
target_metadata = Base.metadata
# Allow DATABASE_URL env var to override alembic.ini
url_override = os.getenv("DATABASE_URL")
if url_override:
config.set_main_option("sqlalchemy.url", url_override)
def run_migrations_offline() -> None:
"""Run migrations in 'offline' mode — emit SQL to stdout."""
url = config.get_main_option("sqlalchemy.url")
context.configure(
url=url,
target_metadata=target_metadata,
literal_binds=True,
dialect_opts={"paramstyle": "named"},
)
with context.begin_transaction():
context.run_migrations()
def do_run_migrations(connection):
context.configure(connection=connection, target_metadata=target_metadata)
with context.begin_transaction():
context.run_migrations()
async def run_async_migrations() -> None:
"""Run migrations in 'online' mode with an async engine."""
connectable = async_engine_from_config(
config.get_section(config.config_ini_section, {}),
prefix="sqlalchemy.",
poolclass=pool.NullPool,
)
async with connectable.connect() as connection:
await connection.run_sync(do_run_migrations)
await connectable.dispose()
def run_migrations_online() -> None:
asyncio.run(run_async_migrations())
if context.is_offline_mode():
run_migrations_offline()
else:
run_migrations_online()

25
alembic/script.py.mako
View file

@ -1,25 +0,0 @@
"""${message}
Revision ID: ${up_revision}
Revises: ${down_revision | comma,n}
Create Date: ${create_date}
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
${imports if imports else ""}
# revision identifiers, used by Alembic.
revision: str = ${repr(up_revision)}
down_revision: Union[str, None] = ${repr(down_revision)}
branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
def upgrade() -> None:
${upgrades if upgrades else "pass"}
def downgrade() -> None:
${downgrades if downgrades else "pass"}

171
alembic/versions/001_initial.py
View file

@ -1,171 +0,0 @@
"""initial schema — 7 core entities
Revision ID: 001_initial
Revises:
Create Date: 2026-03-29
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
from sqlalchemy.dialects.postgresql import ARRAY, JSONB, UUID
# revision identifiers, used by Alembic.
revision: str = "001_initial"
down_revision: Union[str, None] = None
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None
def upgrade() -> None:
# ── Enum types ───────────────────────────────────────────────────────
content_type = sa.Enum(
"tutorial", "livestream", "breakdown", "short_form",
name="content_type",
)
processing_status = sa.Enum(
"pending", "transcribed", "extracted", "reviewed", "published",
name="processing_status",
)
key_moment_content_type = sa.Enum(
"technique", "settings", "reasoning", "workflow",
name="key_moment_content_type",
)
review_status = sa.Enum(
"pending", "approved", "edited", "rejected",
name="review_status",
)
source_quality = sa.Enum(
"structured", "mixed", "unstructured",
name="source_quality",
)
page_review_status = sa.Enum(
"draft", "reviewed", "published",
name="page_review_status",
)
relationship_type = sa.Enum(
"same_technique_other_creator", "same_creator_adjacent", "general_cross_reference",
name="relationship_type",
)
# ── creators ─────────────────────────────────────────────────────────
op.create_table(
"creators",
sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
sa.Column("name", sa.String(255), nullable=False),
sa.Column("slug", sa.String(255), nullable=False, unique=True),
sa.Column("genres", ARRAY(sa.String), nullable=True),
sa.Column("folder_name", sa.String(255), nullable=False),
sa.Column("view_count", sa.Integer, nullable=False, server_default="0"),
sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
)
# ── source_videos ────────────────────────────────────────────────────
op.create_table(
"source_videos",
sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
sa.Column("creator_id", UUID(as_uuid=True), sa.ForeignKey("creators.id", ondelete="CASCADE"), nullable=False),
sa.Column("filename", sa.String(500), nullable=False),
sa.Column("file_path", sa.String(1000), nullable=False),
sa.Column("duration_seconds", sa.Integer, nullable=True),
sa.Column("content_type", content_type, nullable=False),
sa.Column("transcript_path", sa.String(1000), nullable=True),
sa.Column("processing_status", processing_status, nullable=False, server_default="pending"),
sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
)
op.create_index("ix_source_videos_creator_id", "source_videos", ["creator_id"])
# ── transcript_segments ──────────────────────────────────────────────
op.create_table(
"transcript_segments",
sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
sa.Column("source_video_id", UUID(as_uuid=True), sa.ForeignKey("source_videos.id", ondelete="CASCADE"), nullable=False),
sa.Column("start_time", sa.Float, nullable=False),
sa.Column("end_time", sa.Float, nullable=False),
sa.Column("text", sa.Text, nullable=False),
sa.Column("segment_index", sa.Integer, nullable=False),
sa.Column("topic_label", sa.String(255), nullable=True),
)
op.create_index("ix_transcript_segments_video_id", "transcript_segments", ["source_video_id"])
# ── technique_pages (must come before key_moments due to FK) ─────────
op.create_table(
"technique_pages",
sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
sa.Column("creator_id", UUID(as_uuid=True), sa.ForeignKey("creators.id", ondelete="CASCADE"), nullable=False),
sa.Column("title", sa.String(500), nullable=False),
sa.Column("slug", sa.String(500), nullable=False, unique=True),
sa.Column("topic_category", sa.String(255), nullable=False),
sa.Column("topic_tags", ARRAY(sa.String), nullable=True),
sa.Column("summary", sa.Text, nullable=True),
sa.Column("body_sections", JSONB, nullable=True),
sa.Column("signal_chains", JSONB, nullable=True),
sa.Column("plugins", ARRAY(sa.String), nullable=True),
sa.Column("source_quality", source_quality, nullable=True),
sa.Column("view_count", sa.Integer, nullable=False, server_default="0"),
sa.Column("review_status", page_review_status, nullable=False, server_default="draft"),
sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
)
op.create_index("ix_technique_pages_creator_id", "technique_pages", ["creator_id"])
op.create_index("ix_technique_pages_topic_category", "technique_pages", ["topic_category"])
# ── key_moments ──────────────────────────────────────────────────────
op.create_table(
"key_moments",
sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
sa.Column("source_video_id", UUID(as_uuid=True), sa.ForeignKey("source_videos.id", ondelete="CASCADE"), nullable=False),
sa.Column("technique_page_id", UUID(as_uuid=True), sa.ForeignKey("technique_pages.id", ondelete="SET NULL"), nullable=True),
sa.Column("title", sa.String(500), nullable=False),
sa.Column("summary", sa.Text, nullable=False),
sa.Column("start_time", sa.Float, nullable=False),
sa.Column("end_time", sa.Float, nullable=False),
sa.Column("content_type", key_moment_content_type, nullable=False),
sa.Column("plugins", ARRAY(sa.String), nullable=True),
sa.Column("review_status", review_status, nullable=False, server_default="pending"),
sa.Column("raw_transcript", sa.Text, nullable=True),
sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
)
op.create_index("ix_key_moments_source_video_id", "key_moments", ["source_video_id"])
op.create_index("ix_key_moments_technique_page_id", "key_moments", ["technique_page_id"])
# ── related_technique_links ──────────────────────────────────────────
op.create_table(
"related_technique_links",
sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
sa.Column("source_page_id", UUID(as_uuid=True), sa.ForeignKey("technique_pages.id", ondelete="CASCADE"), nullable=False),
sa.Column("target_page_id", UUID(as_uuid=True), sa.ForeignKey("technique_pages.id", ondelete="CASCADE"), nullable=False),
sa.Column("relationship", relationship_type, nullable=False),
sa.UniqueConstraint("source_page_id", "target_page_id", "relationship", name="uq_technique_link"),
)
# ── tags ─────────────────────────────────────────────────────────────
op.create_table(
"tags",
sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
sa.Column("name", sa.String(255), nullable=False, unique=True),
sa.Column("category", sa.String(255), nullable=False),
sa.Column("aliases", ARRAY(sa.String), nullable=True),
)
op.create_index("ix_tags_category", "tags", ["category"])
def downgrade() -> None:
op.drop_table("tags")
op.drop_table("related_technique_links")
op.drop_table("key_moments")
op.drop_table("technique_pages")
op.drop_table("transcript_segments")
op.drop_table("source_videos")
op.drop_table("creators")
# Drop enum types
for name in [
"relationship_type", "page_review_status", "source_quality",
"review_status", "key_moment_content_type", "processing_status",
"content_type",
]:
sa.Enum(name=name).drop(op.get_bind(), checkfirst=True)

39
alembic/versions/002_technique_page_versions.py
View file

@ -1,39 +0,0 @@
"""technique_page_versions table for article versioning
Revision ID: 002_technique_page_versions
Revises: 001_initial
Create Date: 2026-03-30
"""
from typing import Sequence, Union
from alembic import op
import sqlalchemy as sa
from sqlalchemy.dialects.postgresql import JSONB, UUID
# revision identifiers, used by Alembic.
revision: str = "002_technique_page_versions"
down_revision: Union[str, None] = "001_initial"
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None
def upgrade() -> None:
op.create_table(
"technique_page_versions",
sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
sa.Column("technique_page_id", UUID(as_uuid=True), sa.ForeignKey("technique_pages.id", ondelete="CASCADE"), nullable=False),
sa.Column("version_number", sa.Integer, nullable=False),
sa.Column("content_snapshot", JSONB, nullable=False),
sa.Column("pipeline_metadata", JSONB, nullable=True),
sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
)
op.create_index(
"ix_technique_page_versions_page_version",
"technique_page_versions",
["technique_page_id", "version_number"],
unique=True,
)
def downgrade() -> None:
op.drop_table("technique_page_versions")

78
backend/config.py
View file

@ -1,78 +0,0 @@
"""Application configuration loaded from environment variables."""
from functools import lru_cache
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
"""Chrysopedia API settings.
Values are loaded from environment variables (or .env file via
pydantic-settings' dotenv support).
"""
# Database
database_url: str = "postgresql+asyncpg://chrysopedia:changeme@localhost:5433/chrysopedia"
# Redis
redis_url: str = "redis://localhost:6379/0"
# Application
app_env: str = "development"
app_log_level: str = "info"
app_secret_key: str = "changeme-generate-a-real-secret"
# CORS
cors_origins: list[str] = ["*"]
# LLM endpoint (OpenAI-compatible)
llm_api_url: str = "http://localhost:11434/v1"
llm_api_key: str = "sk-placeholder"
llm_model: str = "fyn-llm-agent-chat"
llm_fallback_url: str = "http://localhost:11434/v1"
llm_fallback_model: str = "fyn-llm-agent-chat"
# Per-stage model overrides (optional — falls back to llm_model / "chat")
llm_stage2_model: str | None = "fyn-llm-agent-chat" # segmentation — mechanical, fast chat
llm_stage2_modality: str = "chat"
llm_stage3_model: str | None = "fyn-llm-agent-think" # extraction — reasoning
llm_stage3_modality: str = "thinking"
llm_stage4_model: str | None = "fyn-llm-agent-chat" # classification — mechanical, fast chat
llm_stage4_modality: str = "chat"
llm_stage5_model: str | None = "fyn-llm-agent-think" # synthesis — reasoning
llm_stage5_modality: str = "thinking"
# Max tokens for LLM responses (OpenWebUI defaults to 1000 which truncates pipeline JSON)
llm_max_tokens: int = 65536
# Embedding endpoint
embedding_api_url: str = "http://localhost:11434/v1"
embedding_model: str = "nomic-embed-text"
embedding_dimensions: int = 768
# Qdrant
qdrant_url: str = "http://localhost:6333"
qdrant_collection: str = "chrysopedia"
# Prompt templates
prompts_path: str = "./prompts"
# Review mode — when True, extracted moments go to review queue before publishing
review_mode: bool = True
# File storage
transcript_storage_path: str = "/data/transcripts"
video_metadata_path: str = "/data/video_meta"
model_config = {
"env_file": ".env",
"env_file_encoding": "utf-8",
"case_sensitive": False,
}
@lru_cache
def get_settings() -> Settings:
"""Return cached application settings (singleton)."""
return Settings()

26
backend/database.py
View file

@ -1,26 +0,0 @@
"""Database engine, session factory, and declarative base for Chrysopedia."""
import os
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from sqlalchemy.orm import DeclarativeBase
DATABASE_URL = os.getenv(
"DATABASE_URL",
"postgresql+asyncpg://chrysopedia:changeme@localhost:5433/chrysopedia",
)
engine = create_async_engine(DATABASE_URL, echo=False, pool_pre_ping=True)
async_session = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
class Base(DeclarativeBase):
"""Declarative base for all ORM models."""
pass
async def get_session() -> AsyncSession: # type: ignore[misc]
"""FastAPI dependency that yields an async DB session."""
async with async_session() as session:
yield session

94
backend/main.py
View file

@ -1,94 +0,0 @@
"""Chrysopedia API — Knowledge extraction and retrieval system.
Entry point for the FastAPI application. Configures middleware,
structured logging, and mounts versioned API routers.
"""
import logging
import sys
from contextlib import asynccontextmanager
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from config import get_settings
from routers import creators, health, ingest, pipeline, review, search, techniques, topics, videos
def _setup_logging() -> None:
"""Configure structured logging to stdout."""
settings = get_settings()
level = getattr(logging, settings.app_log_level.upper(), logging.INFO)
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(
logging.Formatter(
fmt="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
datefmt="%Y-%m-%dT%H:%M:%S",
)
)
root = logging.getLogger()
root.setLevel(level)
# Avoid duplicate handlers on reload
root.handlers.clear()
root.addHandler(handler)
# Quiet noisy libraries
logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING)
@asynccontextmanager
async def lifespan(app: FastAPI): # noqa: ARG001
"""Application lifespan: setup on startup, teardown on shutdown."""
_setup_logging()
logger = logging.getLogger("chrysopedia")
settings = get_settings()
logger.info(
"Chrysopedia API starting (env=%s, log_level=%s)",
settings.app_env,
settings.app_log_level,
)
yield
logger.info("Chrysopedia API shutting down")
app = FastAPI(
title="Chrysopedia API",
description="Knowledge extraction and retrieval for music production content",
version="0.1.0",
lifespan=lifespan,
)
# ── Middleware ────────────────────────────────────────────────────────────────
settings = get_settings()
app.add_middleware(
CORSMiddleware,
allow_origins=settings.cors_origins,
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# ── Routers ──────────────────────────────────────────────────────────────────
# Root-level health (no prefix)
app.include_router(health.router)
# Versioned API
app.include_router(creators.router, prefix="/api/v1")
app.include_router(ingest.router, prefix="/api/v1")
app.include_router(pipeline.router, prefix="/api/v1")
app.include_router(review.router, prefix="/api/v1")
app.include_router(search.router, prefix="/api/v1")
app.include_router(techniques.router, prefix="/api/v1")
app.include_router(topics.router, prefix="/api/v1")
app.include_router(videos.router, prefix="/api/v1")
@app.get("/api/v1/health")
async def api_health():
"""Lightweight version-prefixed health endpoint (no DB check)."""
return {"status": "ok", "version": "0.1.0"}

321
backend/models.py
View file

@ -1,321 +0,0 @@
"""SQLAlchemy ORM models for the Chrysopedia knowledge base.
Seven entities matching chrysopedia-spec.md §6.1:
Creator, SourceVideo, TranscriptSegment, KeyMoment,
TechniquePage, RelatedTechniqueLink, Tag
"""
from __future__ import annotations
import enum
import uuid
from datetime import datetime, timezone
from sqlalchemy import (
Enum,
Float,
ForeignKey,
Integer,
String,
Text,
UniqueConstraint,
func,
)
from sqlalchemy.dialects.postgresql import ARRAY, JSONB, UUID
from sqlalchemy.orm import Mapped, mapped_column
from sqlalchemy.orm import relationship as sa_relationship
from database import Base
# ── Enums ────────────────────────────────────────────────────────────────────
class ContentType(str, enum.Enum):
"""Source video content type."""
tutorial = "tutorial"
livestream = "livestream"
breakdown = "breakdown"
short_form = "short_form"
class ProcessingStatus(str, enum.Enum):
"""Pipeline processing status for a source video."""
pending = "pending"
transcribed = "transcribed"
extracted = "extracted"
reviewed = "reviewed"
published = "published"
class KeyMomentContentType(str, enum.Enum):
"""Content classification for a key moment."""
technique = "technique"
settings = "settings"
reasoning = "reasoning"
workflow = "workflow"
class ReviewStatus(str, enum.Enum):
"""Human review status for key moments."""
pending = "pending"
approved = "approved"
edited = "edited"
rejected = "rejected"
class SourceQuality(str, enum.Enum):
"""Derived source quality for technique pages."""
structured = "structured"
mixed = "mixed"
unstructured = "unstructured"
class PageReviewStatus(str, enum.Enum):
"""Review lifecycle for technique pages."""
draft = "draft"
reviewed = "reviewed"
published = "published"
class RelationshipType(str, enum.Enum):
"""Types of links between technique pages."""
same_technique_other_creator = "same_technique_other_creator"
same_creator_adjacent = "same_creator_adjacent"
general_cross_reference = "general_cross_reference"
# ── Helpers ──────────────────────────────────────────────────────────────────
def _uuid_pk() -> Mapped[uuid.UUID]:
return mapped_column(
UUID(as_uuid=True),
primary_key=True,
default=uuid.uuid4,
server_default=func.gen_random_uuid(),
)
def _now() -> datetime:
"""Return current UTC time as a naive datetime (no tzinfo).
PostgreSQL TIMESTAMP WITHOUT TIME ZONE columns require naive datetimes.
asyncpg rejects timezone-aware datetimes for such columns.
"""
return datetime.now(timezone.utc).replace(tzinfo=None)
# ── Models ───────────────────────────────────────────────────────────────────
class Creator(Base):
__tablename__ = "creators"
id: Mapped[uuid.UUID] = _uuid_pk()
name: Mapped[str] = mapped_column(String(255), nullable=False)
slug: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
genres: Mapped[list[str] | None] = mapped_column(ARRAY(String), nullable=True)
folder_name: Mapped[str] = mapped_column(String(255), nullable=False)
view_count: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
created_at: Mapped[datetime] = mapped_column(
default=_now, server_default=func.now()
)
updated_at: Mapped[datetime] = mapped_column(
default=_now, server_default=func.now(), onupdate=_now
)
# relationships
videos: Mapped[list[SourceVideo]] = sa_relationship(back_populates="creator")
technique_pages: Mapped[list[TechniquePage]] = sa_relationship(back_populates="creator")
class SourceVideo(Base):
__tablename__ = "source_videos"
id: Mapped[uuid.UUID] = _uuid_pk()
creator_id: Mapped[uuid.UUID] = mapped_column(
ForeignKey("creators.id", ondelete="CASCADE"), nullable=False
)
filename: Mapped[str] = mapped_column(String(500), nullable=False)
file_path: Mapped[str] = mapped_column(String(1000), nullable=False)
duration_seconds: Mapped[int] = mapped_column(Integer, nullable=True)
content_type: Mapped[ContentType] = mapped_column(
Enum(ContentType, name="content_type", create_constraint=True),
nullable=False,
)
transcript_path: Mapped[str | None] = mapped_column(String(1000), nullable=True)
processing_status: Mapped[ProcessingStatus] = mapped_column(
Enum(ProcessingStatus, name="processing_status", create_constraint=True),
default=ProcessingStatus.pending,
server_default="pending",
)
created_at: Mapped[datetime] = mapped_column(
default=_now, server_default=func.now()
)
updated_at: Mapped[datetime] = mapped_column(
default=_now, server_default=func.now(), onupdate=_now
)
# relationships
creator: Mapped[Creator] = sa_relationship(back_populates="videos")
segments: Mapped[list[TranscriptSegment]] = sa_relationship(back_populates="source_video")
key_moments: Mapped[list[KeyMoment]] = sa_relationship(back_populates="source_video")
class TranscriptSegment(Base):
__tablename__ = "transcript_segments"
id: Mapped[uuid.UUID] = _uuid_pk()
source_video_id: Mapped[uuid.UUID] = mapped_column(
ForeignKey("source_videos.id", ondelete="CASCADE"), nullable=False
)
start_time: Mapped[float] = mapped_column(Float, nullable=False)
end_time: Mapped[float] = mapped_column(Float, nullable=False)
text: Mapped[str] = mapped_column(Text, nullable=False)
segment_index: Mapped[int] = mapped_column(Integer, nullable=False)
topic_label: Mapped[str | None] = mapped_column(String(255), nullable=True)
# relationships
source_video: Mapped[SourceVideo] = sa_relationship(back_populates="segments")
class KeyMoment(Base):
__tablename__ = "key_moments"
id: Mapped[uuid.UUID] = _uuid_pk()
source_video_id: Mapped[uuid.UUID] = mapped_column(
ForeignKey("source_videos.id", ondelete="CASCADE"), nullable=False
)
technique_page_id: Mapped[uuid.UUID | None] = mapped_column(
ForeignKey("technique_pages.id", ondelete="SET NULL"), nullable=True
)
title: Mapped[str] = mapped_column(String(500), nullable=False)
summary: Mapped[str] = mapped_column(Text, nullable=False)
start_time: Mapped[float] = mapped_column(Float, nullable=False)
end_time: Mapped[float] = mapped_column(Float, nullable=False)
content_type: Mapped[KeyMomentContentType] = mapped_column(
Enum(KeyMomentContentType, name="key_moment_content_type", create_constraint=True),
nullable=False,
)
plugins: Mapped[list[str] | None] = mapped_column(ARRAY(String), nullable=True)
review_status: Mapped[ReviewStatus] = mapped_column(
Enum(ReviewStatus, name="review_status", create_constraint=True),
default=ReviewStatus.pending,
server_default="pending",
)
raw_transcript: Mapped[str | None] = mapped_column(Text, nullable=True)
created_at: Mapped[datetime] = mapped_column(
default=_now, server_default=func.now()
)
updated_at: Mapped[datetime] = mapped_column(
default=_now, server_default=func.now(), onupdate=_now
)
# relationships
source_video: Mapped[SourceVideo] = sa_relationship(back_populates="key_moments")
technique_page: Mapped[TechniquePage | None] = sa_relationship(
back_populates="key_moments", foreign_keys=[technique_page_id]
)
class TechniquePage(Base):
__tablename__ = "technique_pages"
id: Mapped[uuid.UUID] = _uuid_pk()
creator_id: Mapped[uuid.UUID] = mapped_column(
ForeignKey("creators.id", ondelete="CASCADE"), nullable=False
)
title: Mapped[str] = mapped_column(String(500), nullable=False)
slug: Mapped[str] = mapped_column(String(500), unique=True, nullable=False)
topic_category: Mapped[str] = mapped_column(String(255), nullable=False)
topic_tags: Mapped[list[str] | None] = mapped_column(ARRAY(String), nullable=True)
summary: Mapped[str | None] = mapped_column(Text, nullable=True)
body_sections: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
signal_chains: Mapped[list | None] = mapped_column(JSONB, nullable=True)
plugins: Mapped[list[str] | None] = mapped_column(ARRAY(String), nullable=True)
source_quality: Mapped[SourceQuality | None] = mapped_column(
Enum(SourceQuality, name="source_quality", create_constraint=True),
nullable=True,
)
view_count: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
review_status: Mapped[PageReviewStatus] = mapped_column(
Enum(PageReviewStatus, name="page_review_status", create_constraint=True),
default=PageReviewStatus.draft,
server_default="draft",
)
created_at: Mapped[datetime] = mapped_column(
default=_now, server_default=func.now()
)
updated_at: Mapped[datetime] = mapped_column(
default=_now, server_default=func.now(), onupdate=_now
)
# relationships
creator: Mapped[Creator] = sa_relationship(back_populates="technique_pages")
key_moments: Mapped[list[KeyMoment]] = sa_relationship(
back_populates="technique_page", foreign_keys=[KeyMoment.technique_page_id]
)
versions: Mapped[list[TechniquePageVersion]] = sa_relationship(
back_populates="technique_page", order_by="TechniquePageVersion.version_number"
)
outgoing_links: Mapped[list[RelatedTechniqueLink]] = sa_relationship(
foreign_keys="RelatedTechniqueLink.source_page_id", back_populates="source_page"
)
incoming_links: Mapped[list[RelatedTechniqueLink]] = sa_relationship(
foreign_keys="RelatedTechniqueLink.target_page_id", back_populates="target_page"
)
class RelatedTechniqueLink(Base):
__tablename__ = "related_technique_links"
__table_args__ = (
UniqueConstraint("source_page_id", "target_page_id", "relationship", name="uq_technique_link"),
)
id: Mapped[uuid.UUID] = _uuid_pk()
source_page_id: Mapped[uuid.UUID] = mapped_column(
ForeignKey("technique_pages.id", ondelete="CASCADE"), nullable=False
)
target_page_id: Mapped[uuid.UUID] = mapped_column(
ForeignKey("technique_pages.id", ondelete="CASCADE"), nullable=False
)
relationship: Mapped[RelationshipType] = mapped_column(
Enum(RelationshipType, name="relationship_type", create_constraint=True),
nullable=False,
)
# relationships
source_page: Mapped[TechniquePage] = sa_relationship(
foreign_keys=[source_page_id], back_populates="outgoing_links"
)
target_page: Mapped[TechniquePage] = sa_relationship(
foreign_keys=[target_page_id], back_populates="incoming_links"
)
class TechniquePageVersion(Base):
"""Snapshot of a TechniquePage before a pipeline re-synthesis overwrites it."""
__tablename__ = "technique_page_versions"
id: Mapped[uuid.UUID] = _uuid_pk()
technique_page_id: Mapped[uuid.UUID] = mapped_column(
ForeignKey("technique_pages.id", ondelete="CASCADE"), nullable=False
)
version_number: Mapped[int] = mapped_column(Integer, nullable=False)
content_snapshot: Mapped[dict] = mapped_column(JSONB, nullable=False)
pipeline_metadata: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
created_at: Mapped[datetime] = mapped_column(
default=_now, server_default=func.now()
)
# relationships
technique_page: Mapped[TechniquePage] = sa_relationship(
back_populates="versions"
)
class Tag(Base):
__tablename__ = "tags"
id: Mapped[uuid.UUID] = _uuid_pk()
name: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
category: Mapped[str] = mapped_column(String(255), nullable=False)
aliases: Mapped[list[str] | None] = mapped_column(ARRAY(String), nullable=True)

0
backend/pipeline/__init__.py
View file

88
backend/pipeline/embedding_client.py
View file

@ -1,88 +0,0 @@
"""Synchronous embedding client using the OpenAI-compatible /v1/embeddings API.
Uses ``openai.OpenAI`` (sync) since Celery tasks run synchronously.
Handles connection failures gracefully — embedding is non-blocking for the pipeline.
"""
from __future__ import annotations
import logging
import openai
from config import Settings
logger = logging.getLogger(__name__)
class EmbeddingClient:
"""Sync embedding client backed by an OpenAI-compatible /v1/embeddings endpoint."""
def __init__(self, settings: Settings) -> None:
self.settings = settings
self._client = openai.OpenAI(
base_url=settings.embedding_api_url,
api_key=settings.llm_api_key,
)
def embed(self, texts: list[str]) -> list[list[float]]:
"""Generate embedding vectors for a batch of texts.
Parameters
----------
texts:
List of strings to embed.
Returns
-------
list[list[float]]
Embedding vectors. Returns empty list on connection/timeout errors
so the pipeline can continue without embeddings.
"""
if not texts:
return []
try:
response = self._client.embeddings.create(
model=self.settings.embedding_model,
input=texts,
)
except (openai.APIConnectionError, openai.APITimeoutError) as exc:
logger.warning(
"Embedding API unavailable (%s: %s). Skipping %d texts.",
type(exc).__name__,
exc,
len(texts),
)
return []
except openai.APIError as exc:
logger.warning(
"Embedding API error (%s: %s). Skipping %d texts.",
type(exc).__name__,
exc,
len(texts),
)
return []
vectors = [item.embedding for item in response.data]
# Validate dimensions
expected_dim = self.settings.embedding_dimensions
for i, vec in enumerate(vectors):
if len(vec) != expected_dim:
logger.warning(
"Embedding dimension mismatch at index %d: expected %d, got %d. "
"Returning empty list.",
i,
expected_dim,
len(vec),
)
return []
logger.info(
"Generated %d embeddings (dim=%d) using model=%s",
len(vectors),
expected_dim,
self.settings.embedding_model,
)
return vectors

222
backend/pipeline/llm_client.py
View file

@ -1,222 +0,0 @@
"""Synchronous LLM client with primary/fallback endpoint logic.
Uses the OpenAI-compatible API (works with Ollama, vLLM, OpenWebUI, etc.).
Celery tasks run synchronously, so this uses ``openai.OpenAI`` (not Async).
Supports two modalities:
- **chat**: Standard JSON mode with ``response_format: {"type": "json_object"}``
- **thinking**: For reasoning models that emit ``<think>...</think>`` blocks
before their answer. Skips ``response_format``, appends JSON instructions to
the system prompt, and strips think tags from the response.
"""
from __future__ import annotations
import logging
import re
from typing import TypeVar
import openai
from pydantic import BaseModel
from config import Settings
logger = logging.getLogger(__name__)
T = TypeVar("T", bound=BaseModel)
# ── Think-tag stripping ──────────────────────────────────────────────────────
_THINK_PATTERN = re.compile(r"<think>.*?</think>", re.DOTALL)
def strip_think_tags(text: str) -> str:
"""Remove ``<think>...</think>`` blocks from LLM output.
Thinking/reasoning models often prefix their JSON with a reasoning trace
wrapped in ``<think>`` tags. This strips all such blocks (including
multiline and multiple occurrences) and returns the cleaned text.
Handles:
- Single ``<think>...</think>`` block
- Multiple blocks in one response
- Multiline content inside think tags
- Responses with no think tags (passthrough)
- Empty input (passthrough)
"""
if not text:
return text
cleaned = _THINK_PATTERN.sub("", text)
return cleaned.strip()
class LLMClient:
"""Sync LLM client that tries a primary endpoint and falls back on failure."""
def __init__(self, settings: Settings) -> None:
self.settings = settings
self._primary = openai.OpenAI(
base_url=settings.llm_api_url,
api_key=settings.llm_api_key,
)
self._fallback = openai.OpenAI(
base_url=settings.llm_fallback_url,
api_key=settings.llm_api_key,
)
# ── Core completion ──────────────────────────────────────────────────
def complete(
self,
system_prompt: str,
user_prompt: str,
response_model: type[BaseModel] | None = None,
modality: str = "chat",
model_override: str | None = None,
) -> str:
"""Send a chat completion request, falling back on connection/timeout errors.
Parameters
----------
system_prompt:
System message content.
user_prompt:
User message content.
response_model:
If provided and modality is "chat", ``response_format`` is set to
``{"type": "json_object"}``. For "thinking" modality, JSON
instructions are appended to the system prompt instead.
modality:
Either "chat" (default) or "thinking". Thinking modality skips
response_format and strips ``<think>`` tags from output.
model_override:
Model name to use instead of the default. If None, uses the
configured default for the endpoint.
Returns
-------
str
Raw completion text from the model (think tags stripped if thinking).
"""
kwargs: dict = {}
effective_system = system_prompt
if modality == "thinking":
# Thinking models often don't support response_format: json_object.
# Instead, append explicit JSON instructions to the system prompt.
if response_model is not None:
json_schema_hint = (
"\n\nYou MUST respond with ONLY valid JSON. "
"No markdown code fences, no explanation, no preamble — "
"just the raw JSON object."
)
effective_system = system_prompt + json_schema_hint
else:
# Chat modality — use standard JSON mode
if response_model is not None:
kwargs["response_format"] = {"type": "json_object"}
messages = [
{"role": "system", "content": effective_system},
{"role": "user", "content": user_prompt},
]
primary_model = model_override or self.settings.llm_model
fallback_model = self.settings.llm_fallback_model
logger.info(
"LLM request: model=%s, modality=%s, response_model=%s",
primary_model,
modality,
response_model.__name__ if response_model else None,
)
# --- Try primary endpoint ---
try:
response = self._primary.chat.completions.create(
model=primary_model,
messages=messages,
max_tokens=self.settings.llm_max_tokens,
**kwargs,
)
raw = response.choices[0].message.content or ""
usage = getattr(response, "usage", None)
if usage:
logger.info(
"LLM response: prompt_tokens=%s, completion_tokens=%s, total=%s, content_len=%d, finish=%s",
usage.prompt_tokens, usage.completion_tokens, usage.total_tokens,
len(raw), response.choices[0].finish_reason,
)
if modality == "thinking":
raw = strip_think_tags(raw)
return raw
except (openai.APIConnectionError, openai.APITimeoutError) as exc:
logger.warning(
"Primary LLM endpoint failed (%s: %s), trying fallback at %s",
type(exc).__name__,
exc,
self.settings.llm_fallback_url,
)
# --- Try fallback endpoint ---
try:
response = self._fallback.chat.completions.create(
model=fallback_model,
messages=messages,
max_tokens=self.settings.llm_max_tokens,
**kwargs,
)
raw = response.choices[0].message.content or ""
usage = getattr(response, "usage", None)
if usage:
logger.info(
"LLM response (fallback): prompt_tokens=%s, completion_tokens=%s, total=%s, content_len=%d, finish=%s",
usage.prompt_tokens, usage.completion_tokens, usage.total_tokens,
len(raw), response.choices[0].finish_reason,
)
if modality == "thinking":
raw = strip_think_tags(raw)
return raw
except (openai.APIConnectionError, openai.APITimeoutError, openai.APIError) as exc:
logger.error(
"Fallback LLM endpoint also failed (%s: %s). Giving up.",
type(exc).__name__,
exc,
)
raise
# ── Response parsing ─────────────────────────────────────────────────
def parse_response(self, text: str, model: type[T]) -> T:
"""Parse raw LLM output as JSON and validate against a Pydantic model.
Parameters
----------
text:
Raw JSON string from the LLM.
model:
Pydantic model class to validate against.
Returns
-------
T
Validated Pydantic model instance.
Raises
------
pydantic.ValidationError
If the JSON doesn't match the schema.
ValueError
If the text is not valid JSON.
"""
try:
return model.model_validate_json(text)
except Exception:
logger.error(
"Failed to parse LLM response as %s. Response text: %.500s",
model.__name__,
text,
)
raise

184
backend/pipeline/qdrant_client.py
View file

@ -1,184 +0,0 @@
"""Qdrant vector database manager for collection lifecycle and point upserts.
Handles collection creation (idempotent) and batch upserts for technique pages
and key moments. Connection failures are non-blocking — the pipeline continues
without search indexing.
"""
from __future__ import annotations
import logging
import uuid
from qdrant_client import QdrantClient
from qdrant_client.http import exceptions as qdrant_exceptions
from qdrant_client.models import Distance, PointStruct, VectorParams
from config import Settings
logger = logging.getLogger(__name__)
class QdrantManager:
"""Manages a Qdrant collection for Chrysopedia technique-page and key-moment vectors."""
def __init__(self, settings: Settings) -> None:
self.settings = settings
self._client = QdrantClient(url=settings.qdrant_url)
self._collection = settings.qdrant_collection
# ── Collection management ────────────────────────────────────────────
def ensure_collection(self) -> None:
"""Create the collection if it does not already exist.
Uses cosine distance and the configured embedding dimensions.
"""
try:
if self._client.collection_exists(self._collection):
logger.info("Qdrant collection '%s' already exists.", self._collection)
return
self._client.create_collection(
collection_name=self._collection,
vectors_config=VectorParams(
size=self.settings.embedding_dimensions,
distance=Distance.COSINE,
),
)
logger.info(
"Created Qdrant collection '%s' (dim=%d, cosine).",
self._collection,
self.settings.embedding_dimensions,
)
except qdrant_exceptions.UnexpectedResponse as exc:
logger.warning(
"Qdrant error during ensure_collection (%s). Skipping.",
exc,
)
except Exception as exc:
logger.warning(
"Qdrant connection failed during ensure_collection (%s: %s). Skipping.",
type(exc).__name__,
exc,
)
# ── Low-level upsert ─────────────────────────────────────────────────
def upsert_points(self, points: list[PointStruct]) -> None:
"""Upsert a batch of pre-built PointStruct objects."""
if not points:
return
try:
self._client.upsert(
collection_name=self._collection,
points=points,
)
logger.info(
"Upserted %d points to Qdrant collection '%s'.",
len(points),
self._collection,
)
except qdrant_exceptions.UnexpectedResponse as exc:
logger.warning(
"Qdrant upsert failed (%s). %d points skipped.",
exc,
len(points),
)
except Exception as exc:
logger.warning(
"Qdrant upsert connection error (%s: %s). %d points skipped.",
type(exc).__name__,
exc,
len(points),
)
# ── High-level upserts ───────────────────────────────────────────────
def upsert_technique_pages(
self,
pages: list[dict],
vectors: list[list[float]],
) -> None:
"""Build and upsert PointStructs for technique pages.
Each page dict must contain:
page_id, creator_id, title, topic_category, topic_tags, summary
Parameters
----------
pages:
Metadata dicts, one per technique page.
vectors:
Corresponding embedding vectors (same order as pages).
"""
if len(pages) != len(vectors):
logger.warning(
"Technique-page count (%d) != vector count (%d). Skipping upsert.",
len(pages),
len(vectors),
)
return
points = []
for page, vector in zip(pages, vectors):
point = PointStruct(
id=str(uuid.uuid4()),
vector=vector,
payload={
"type": "technique_page",
"page_id": page["page_id"],
"creator_id": page["creator_id"],
"title": page["title"],
"topic_category": page["topic_category"],
"topic_tags": page.get("topic_tags") or [],
"summary": page.get("summary") or "",
},
)
points.append(point)
self.upsert_points(points)
def upsert_key_moments(
self,
moments: list[dict],
vectors: list[list[float]],
) -> None:
"""Build and upsert PointStructs for key moments.
Each moment dict must contain:
moment_id, source_video_id, title, start_time, end_time, content_type
Parameters
----------
moments:
Metadata dicts, one per key moment.
vectors:
Corresponding embedding vectors (same order as moments).
"""
if len(moments) != len(vectors):
logger.warning(
"Key-moment count (%d) != vector count (%d). Skipping upsert.",
len(moments),
len(vectors),
)
return
points = []
for moment, vector in zip(moments, vectors):
point = PointStruct(
id=str(uuid.uuid4()),
vector=vector,
payload={
"type": "key_moment",
"moment_id": moment["moment_id"],
"source_video_id": moment["source_video_id"],
"title": moment["title"],
"start_time": moment["start_time"],
"end_time": moment["end_time"],
"content_type": moment["content_type"],
},
)
points.append(point)
self.upsert_points(points)

99
backend/pipeline/schemas.py
View file

@ -1,99 +0,0 @@
"""Pydantic schemas for pipeline stage inputs and outputs.
Stage 2 — Segmentation: groups transcript segments by topic.
Stage 3 — Extraction: extracts key moments from segments.
Stage 4 — Classification: classifies moments by category/tags.
Stage 5 — Synthesis: generates technique pages from classified moments.
"""
from __future__ import annotations
from pydantic import BaseModel, Field
# ── Stage 2: Segmentation ───────────────────────────────────────────────────
class TopicSegment(BaseModel):
"""A contiguous group of transcript segments sharing a topic."""
start_index: int = Field(description="First transcript segment index in this group")
end_index: int = Field(description="Last transcript segment index in this group (inclusive)")
topic_label: str = Field(description="Short label describing the topic")
summary: str = Field(description="Brief summary of what is discussed")
class SegmentationResult(BaseModel):
"""Full output of stage 2 (segmentation)."""
segments: list[TopicSegment]
# ── Stage 3: Extraction ─────────────────────────────────────────────────────
class ExtractedMoment(BaseModel):
"""A single key moment extracted from a topic segment group."""
title: str = Field(description="Concise title for the moment")
summary: str = Field(description="Detailed summary of the technique/concept")
start_time: float = Field(description="Start time in seconds")
end_time: float = Field(description="End time in seconds")
content_type: str = Field(description="One of: technique, settings, reasoning, workflow")
plugins: list[str] = Field(default_factory=list, description="Plugins/tools mentioned")
raw_transcript: str = Field(default="", description="Raw transcript text for this moment")
class ExtractionResult(BaseModel):
"""Full output of stage 3 (extraction)."""
moments: list[ExtractedMoment]
# ── Stage 4: Classification ─────────────────────────────────────────────────
class ClassifiedMoment(BaseModel):
"""Classification metadata for a single extracted moment."""
moment_index: int = Field(description="Index into ExtractionResult.moments")
topic_category: str = Field(description="High-level topic category")
topic_tags: list[str] = Field(default_factory=list, description="Specific topic tags")
content_type_override: str | None = Field(
default=None,
description="Override for content_type if classification disagrees with extraction",
)
class ClassificationResult(BaseModel):
"""Full output of stage 4 (classification)."""
classifications: list[ClassifiedMoment]
# ── Stage 5: Synthesis ───────────────────────────────────────────────────────
class SynthesizedPage(BaseModel):
"""A technique page synthesized from classified moments."""
title: str = Field(description="Page title")
slug: str = Field(description="URL-safe slug")
topic_category: str = Field(description="Primary topic category")
topic_tags: list[str] = Field(default_factory=list, description="Associated tags")
summary: str = Field(description="Page summary / overview paragraph")
body_sections: dict = Field(
default_factory=dict,
description="Structured body content as section_name -> content mapping",
)
signal_chains: list[dict] = Field(
default_factory=list,
description="Signal chain descriptions (for audio/music production contexts)",
)
plugins: list[str] = Field(default_factory=list, description="Plugins/tools referenced")
source_quality: str = Field(
default="mixed",
description="One of: structured, mixed, unstructured",
)
class SynthesisResult(BaseModel):
"""Full output of stage 5 (synthesis)."""
pages: list[SynthesizedPage]

83
backend/pipeline/stages.py
View file

@ -26,6 +26,7 @@ from config import get_settings
from models import (
KeyMoment,
KeyMomentContentType,
PipelineEvent,
ProcessingStatus,
SourceVideo,
TechniquePage,
@ -45,6 +46,68 @@ from worker import celery_app
logger = logging.getLogger(__name__)
# ── Pipeline event persistence ───────────────────────────────────────────────
def _emit_event(
video_id: str,
stage: str,
event_type: str,
*,
prompt_tokens: int | None = None,
completion_tokens: int | None = None,
total_tokens: int | None = None,
model: str | None = None,
duration_ms: int | None = None,
payload: dict | None = None,
) -> None:
"""Persist a pipeline event to the DB. Best-effort -- failures logged, not raised."""
try:
session = _get_sync_session()
try:
event = PipelineEvent(
video_id=video_id,
stage=stage,
event_type=event_type,
prompt_tokens=prompt_tokens,
completion_tokens=completion_tokens,
total_tokens=total_tokens,
model=model,
duration_ms=duration_ms,
payload=payload,
)
session.add(event)
session.commit()
finally:
session.close()
except Exception as exc:
logger.warning("Failed to emit pipeline event: %s", exc)
def _make_llm_callback(video_id: str, stage: str):
"""Create an on_complete callback for LLMClient that emits llm_call events."""
def callback(*, model=None, prompt_tokens=None, completion_tokens=None,
total_tokens=None, content=None, finish_reason=None,
is_fallback=False, **_kwargs):
# Truncate content for storage — keep first 2000 chars for debugging
truncated = content[:2000] if content and len(content) > 2000 else content
_emit_event(
video_id=video_id,
stage=stage,
event_type="llm_call",
model=model,
prompt_tokens=prompt_tokens,
completion_tokens=completion_tokens,
total_tokens=total_tokens,
payload={
"content_preview": truncated,
"content_length": len(content) if content else 0,
"finish_reason": finish_reason,
"is_fallback": is_fallback,
},
)
return callback
# ── Helpers ──────────────────────────────────────────────────────────────────
_engine = None
@ -175,6 +238,7 @@ def stage2_segmentation(self, video_id: str) -> str:
"""
start = time.monotonic()
logger.info("Stage 2 (segmentation) starting for video_id=%s", video_id)
_emit_event(video_id, "stage2_segmentation", "start")
session = _get_sync_session()
try:
@ -208,7 +272,7 @@ def stage2_segmentation(self, video_id: str) -> str:
llm = _get_llm_client()
model_override, modality = _get_stage_config(2)
logger.info("Stage 2 using model=%s, modality=%s", model_override or "default", modality)
raw = llm.complete(system_prompt, user_prompt, response_model=SegmentationResult,
raw = llm.complete(system_prompt, user_prompt, response_model=SegmentationResult, on_complete=_make_llm_callback(video_id, "stage2_segmentation"),
modality=modality, model_override=model_override)
result = _safe_parse_llm_response(raw, SegmentationResult, llm, system_prompt, user_prompt,
modality=modality, model_override=model_override)
@ -222,6 +286,7 @@ def stage2_segmentation(self, video_id: str) -> str:
session.commit()
elapsed = time.monotonic() - start
_emit_event(video_id, "stage2_segmentation", "complete")
logger.info(
"Stage 2 (segmentation) completed for video_id=%s in %.1fs — %d topic groups found",
video_id, elapsed, len(result.segments),
@ -232,6 +297,7 @@ def stage2_segmentation(self, video_id: str) -> str:
raise # Don't retry missing prompt files
except Exception as exc:
session.rollback()
_emit_event(video_id, "stage2_segmentation", "error", payload={"error": str(exc)})
logger.error("Stage 2 failed for video_id=%s: %s", video_id, exc)
raise self.retry(exc=exc)
finally:
@ -251,6 +317,7 @@ def stage3_extraction(self, video_id: str) -> str:
"""
start = time.monotonic()
logger.info("Stage 3 (extraction) starting for video_id=%s", video_id)
_emit_event(video_id, "stage3_extraction", "start")
session = _get_sync_session()
try:
@ -295,7 +362,7 @@ def stage3_extraction(self, video_id: str) -> str:
f"<segment>\n{segment_text}\n</segment>"
)
raw = llm.complete(system_prompt, user_prompt, response_model=ExtractionResult,
raw = llm.complete(system_prompt, user_prompt, response_model=ExtractionResult, on_complete=_make_llm_callback(video_id, "stage3_extraction"),
modality=modality, model_override=model_override)
result = _safe_parse_llm_response(raw, ExtractionResult, llm, system_prompt, user_prompt,
modality=modality, model_override=model_override)
@ -329,6 +396,7 @@ def stage3_extraction(self, video_id: str) -> str:
session.commit()
elapsed = time.monotonic() - start
_emit_event(video_id, "stage3_extraction", "complete")
logger.info(
"Stage 3 (extraction) completed for video_id=%s in %.1fs — %d moments created",
video_id, elapsed, total_moments,
@ -339,6 +407,7 @@ def stage3_extraction(self, video_id: str) -> str:
raise
except Exception as exc:
session.rollback()
_emit_event(video_id, "stage3_extraction", "error", payload={"error": str(exc)})
logger.error("Stage 3 failed for video_id=%s: %s", video_id, exc)
raise self.retry(exc=exc)
finally:
@ -361,6 +430,7 @@ def stage4_classification(self, video_id: str) -> str:
"""
start = time.monotonic()
logger.info("Stage 4 (classification) starting for video_id=%s", video_id)
_emit_event(video_id, "stage4_classification", "start")
session = _get_sync_session()
try:
@ -405,7 +475,7 @@ def stage4_classification(self, video_id: str) -> str:
llm = _get_llm_client()
model_override, modality = _get_stage_config(4)
logger.info("Stage 4 using model=%s, modality=%s", model_override or "default", modality)
raw = llm.complete(system_prompt, user_prompt, response_model=ClassificationResult,
raw = llm.complete(system_prompt, user_prompt, response_model=ClassificationResult, on_complete=_make_llm_callback(video_id, "stage4_classification"),
modality=modality, model_override=model_override)
result = _safe_parse_llm_response(raw, ClassificationResult, llm, system_prompt, user_prompt,
modality=modality, model_override=model_override)
@ -437,6 +507,7 @@ def stage4_classification(self, video_id: str) -> str:
_store_classification_data(video_id, classification_data)
elapsed = time.monotonic() - start
_emit_event(video_id, "stage4_classification", "complete")
logger.info(
"Stage 4 (classification) completed for video_id=%s in %.1fs — %d moments classified",
video_id, elapsed, len(classification_data),
@ -447,6 +518,7 @@ def stage4_classification(self, video_id: str) -> str:
raise
except Exception as exc:
session.rollback()
_emit_event(video_id, "stage4_classification", "error", payload={"error": str(exc)})
logger.error("Stage 4 failed for video_id=%s: %s", video_id, exc)
raise self.retry(exc=exc)
finally:
@ -539,6 +611,7 @@ def stage5_synthesis(self, video_id: str) -> str:
"""
start = time.monotonic()
logger.info("Stage 5 (synthesis) starting for video_id=%s", video_id)
_emit_event(video_id, "stage5_synthesis", "start")
settings = get_settings()
session = _get_sync_session()
@ -600,7 +673,7 @@ def stage5_synthesis(self, video_id: str) -> str:
user_prompt = f"<moments>\n{moments_text}\n</moments>"
raw = llm.complete(system_prompt, user_prompt, response_model=SynthesisResult,
raw = llm.complete(system_prompt, user_prompt, response_model=SynthesisResult, on_complete=_make_llm_callback(video_id, "stage5_synthesis"),
modality=modality, model_override=model_override)
result = _safe_parse_llm_response(raw, SynthesisResult, llm, system_prompt, user_prompt,
modality=modality, model_override=model_override)
@ -690,6 +763,7 @@ def stage5_synthesis(self, video_id: str) -> str:
session.commit()
elapsed = time.monotonic() - start
_emit_event(video_id, "stage5_synthesis", "complete")
logger.info(
"Stage 5 (synthesis) completed for video_id=%s in %.1fs — %d pages created/updated",
video_id, elapsed, pages_created,
@ -700,6 +774,7 @@ def stage5_synthesis(self, video_id: str) -> str:
raise
except Exception as exc:
session.rollback()
_emit_event(video_id, "stage5_synthesis", "error", payload={"error": str(exc)})
logger.error("Stage 5 failed for video_id=%s: %s", video_id, exc)
raise self.retry(exc=exc)
finally:

3
backend/pytest.ini
View file

@ -1,3 +0,0 @@
[pytest]
asyncio_mode = auto
testpaths = tests

15
backend/redis_client.py
View file

@ -1,15 +0,0 @@
"""Async Redis client helper for Chrysopedia."""
import redis.asyncio as aioredis
from config import get_settings
async def get_redis() -> aioredis.Redis:
"""Return an async Redis client from the configured URL.
Callers should close the connection when done, or use it
as a short-lived client within a request handler.
"""
settings = get_settings()
return aioredis.from_url(settings.redis_url, decode_responses=True)

19
backend/requirements.txt
View file

@ -1,19 +0,0 @@
fastapi>=0.115.0,<1.0
uvicorn[standard]>=0.32.0,<1.0
sqlalchemy[asyncio]>=2.0,<3.0
asyncpg>=0.30.0,<1.0
alembic>=1.14.0,<2.0
pydantic>=2.0,<3.0
pydantic-settings>=2.0,<3.0
celery[redis]>=5.4.0,<6.0
redis>=5.0,<6.0
python-dotenv>=1.0,<2.0
python-multipart>=0.0.9,<1.0
httpx>=0.27.0,<1.0
openai>=1.0,<2.0
qdrant-client>=1.9,<2.0
pyyaml>=6.0,<7.0
psycopg2-binary>=2.9,<3.0
# Test dependencies
pytest>=8.0,<10.0
pytest-asyncio>=0.24,<1.0

1
backend/routers/__init__.py
View file

@ -1 +0,0 @@
"""Chrysopedia API routers package."""

119
backend/routers/creators.py
View file

@ -1,119 +0,0 @@
"""Creator endpoints for Chrysopedia API.
Enhanced with sort (random default per R014), genre filter, and
technique/video counts for browse pages.
"""
import logging
from typing import Annotated
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
from database import get_session
from models import Creator, SourceVideo, TechniquePage
from schemas import CreatorBrowseItem, CreatorDetail, CreatorRead
logger = logging.getLogger("chrysopedia.creators")
router = APIRouter(prefix="/creators", tags=["creators"])
@router.get("")
async def list_creators(
sort: Annotated[str, Query()] = "random",
genre: Annotated[str | None, Query()] = None,
offset: Annotated[int, Query(ge=0)] = 0,
limit: Annotated[int, Query(ge=1, le=100)] = 50,
db: AsyncSession = Depends(get_session),
):
"""List creators with sort, genre filter, and technique/video counts.
- **sort**: ``random`` (default, R014 creator equity), ``alpha``, ``views``
- **genre**: filter by genre (matches against ARRAY column)
"""
# Subqueries for counts
technique_count_sq = (
select(func.count())
.where(TechniquePage.creator_id == Creator.id)
.correlate(Creator)
.scalar_subquery()
)
video_count_sq = (
select(func.count())
.where(SourceVideo.creator_id == Creator.id)
.correlate(Creator)
.scalar_subquery()
)
stmt = select(
Creator,
technique_count_sq.label("technique_count"),
video_count_sq.label("video_count"),
)
# Genre filter
if genre:
stmt = stmt.where(Creator.genres.any(genre))
# Sorting
if sort == "alpha":
stmt = stmt.order_by(Creator.name)
elif sort == "views":
stmt = stmt.order_by(Creator.view_count.desc())
else:
# Default: random (small dataset <100, func.random() is fine)
stmt = stmt.order_by(func.random())
stmt = stmt.offset(offset).limit(limit)
result = await db.execute(stmt)
rows = result.all()
items: list[CreatorBrowseItem] = []
for row in rows:
creator = row[0]
tc = row[1] or 0
vc = row[2] or 0
base = CreatorRead.model_validate(creator)
items.append(
CreatorBrowseItem(**base.model_dump(), technique_count=tc, video_count=vc)
)
# Get total count (without offset/limit)
count_stmt = select(func.count()).select_from(Creator)
if genre:
count_stmt = count_stmt.where(Creator.genres.any(genre))
total = (await db.execute(count_stmt)).scalar() or 0
logger.debug(
"Listed %d creators (sort=%s, genre=%s, offset=%d, limit=%d)",
len(items), sort, genre, offset, limit,
)
return {"items": items, "total": total, "offset": offset, "limit": limit}
@router.get("/{slug}", response_model=CreatorDetail)
async def get_creator(
slug: str,
db: AsyncSession = Depends(get_session),
) -> CreatorDetail:
"""Get a single creator by slug, including video count."""
stmt = select(Creator).where(Creator.slug == slug)
result = await db.execute(stmt)
creator = result.scalar_one_or_none()
if creator is None:
raise HTTPException(status_code=404, detail=f"Creator '{slug}' not found")
# Count videos for this creator
count_stmt = (
select(func.count())
.select_from(SourceVideo)
.where(SourceVideo.creator_id == creator.id)
)
count_result = await db.execute(count_stmt)
video_count = count_result.scalar() or 0
creator_data = CreatorRead.model_validate(creator)
return CreatorDetail(**creator_data.model_dump(), video_count=video_count)

34
backend/routers/health.py
View file

@ -1,34 +0,0 @@
"""Health check endpoints for Chrysopedia API."""
import logging
from fastapi import APIRouter, Depends
from sqlalchemy import text
from sqlalchemy.ext.asyncio import AsyncSession
from database import get_session
from schemas import HealthResponse
logger = logging.getLogger("chrysopedia.health")
router = APIRouter(tags=["health"])
@router.get("/health", response_model=HealthResponse)
async def health_check(db: AsyncSession = Depends(get_session)) -> HealthResponse:
"""Root health check — verifies API is running and DB is reachable."""
db_status = "unknown"
try:
result = await db.execute(text("SELECT 1"))
result.scalar()
db_status = "connected"
except Exception:
logger.warning("Database health check failed", exc_info=True)
db_status = "unreachable"
return HealthResponse(
status="ok",
service="chrysopedia-api",
version="0.1.0",
database=db_status,
)

206
backend/routers/ingest.py
View file

@ -1,206 +0,0 @@
"""Transcript ingestion endpoint for the Chrysopedia API.
Accepts a Whisper-format transcript JSON via multipart file upload, finds or
creates a Creator, upserts a SourceVideo, bulk-inserts TranscriptSegments,
persists the raw JSON to disk, and returns a structured response.
"""
import json
import logging
import os
import re
import uuid
from fastapi import APIRouter, Depends, HTTPException, UploadFile
from sqlalchemy import delete, select
from sqlalchemy.ext.asyncio import AsyncSession
from config import get_settings
from database import get_session
from models import ContentType, Creator, ProcessingStatus, SourceVideo, TranscriptSegment
from schemas import TranscriptIngestResponse
logger = logging.getLogger("chrysopedia.ingest")
router = APIRouter(prefix="/ingest", tags=["ingest"])
REQUIRED_KEYS = {"source_file", "creator_folder", "duration_seconds", "segments"}
def slugify(value: str) -> str:
"""Lowercase, replace non-alphanumeric chars with hyphens, collapse/strip."""
value = value.lower()
value = re.sub(r"[^a-z0-9]+", "-", value)
value = value.strip("-")
value = re.sub(r"-{2,}", "-", value)
return value
@router.post("", response_model=TranscriptIngestResponse)
async def ingest_transcript(
file: UploadFile,
db: AsyncSession = Depends(get_session),
) -> TranscriptIngestResponse:
"""Ingest a Whisper transcript JSON file.
Workflow:
1. Parse and validate the uploaded JSON.
2. Find-or-create a Creator by folder_name.
3. Upsert a SourceVideo by (creator_id, filename).
4. Bulk-insert TranscriptSegment rows.
5. Save raw JSON to transcript_storage_path.
6. Return structured response.
"""
settings = get_settings()
# ── 1. Read & parse JSON ─────────────────────────────────────────────
try:
raw_bytes = await file.read()
raw_text = raw_bytes.decode("utf-8")
except Exception as exc:
raise HTTPException(status_code=400, detail=f"Invalid file: {exc}") from exc
try:
data = json.loads(raw_text)
except json.JSONDecodeError as exc:
raise HTTPException(
status_code=422, detail=f"JSON parse error: {exc}"
) from exc
if not isinstance(data, dict):
raise HTTPException(status_code=422, detail="Expected a JSON object at the top level")
missing = REQUIRED_KEYS - data.keys()
if missing:
raise HTTPException(
status_code=422,
detail=f"Missing required keys: {', '.join(sorted(missing))}",
)
source_file: str = data["source_file"]
creator_folder: str = data["creator_folder"]
duration_seconds: int | None = data.get("duration_seconds")
segments_data: list = data["segments"]
if not isinstance(segments_data, list):
raise HTTPException(status_code=422, detail="'segments' must be an array")
# ── 2. Find-or-create Creator ────────────────────────────────────────
stmt = select(Creator).where(Creator.folder_name == creator_folder)
result = await db.execute(stmt)
creator = result.scalar_one_or_none()
if creator is None:
creator = Creator(
name=creator_folder,
slug=slugify(creator_folder),
folder_name=creator_folder,
)
db.add(creator)
await db.flush() # assign id
# ── 3. Upsert SourceVideo ────────────────────────────────────────────
stmt = select(SourceVideo).where(
SourceVideo.creator_id == creator.id,
SourceVideo.filename == source_file,
)
result = await db.execute(stmt)
existing_video = result.scalar_one_or_none()
is_reupload = existing_video is not None
if is_reupload:
video = existing_video
# Delete old segments for idempotent re-upload
await db.execute(
delete(TranscriptSegment).where(
TranscriptSegment.source_video_id == video.id
)
)
video.duration_seconds = duration_seconds
video.processing_status = ProcessingStatus.transcribed
else:
video = SourceVideo(
creator_id=creator.id,
filename=source_file,
file_path=f"{creator_folder}/{source_file}",
duration_seconds=duration_seconds,
content_type=ContentType.tutorial,
processing_status=ProcessingStatus.transcribed,
)
db.add(video)
await db.flush() # assign id
# ── 4. Bulk-insert TranscriptSegments ────────────────────────────────
segment_objs = [
TranscriptSegment(
source_video_id=video.id,
start_time=float(seg["start"]),
end_time=float(seg["end"]),
text=str(seg["text"]),
segment_index=idx,
)
for idx, seg in enumerate(segments_data)
]
db.add_all(segment_objs)
# ── 5. Save raw JSON to disk ─────────────────────────────────────────
transcript_dir = os.path.join(
settings.transcript_storage_path, creator_folder
)
transcript_path = os.path.join(transcript_dir, f"{source_file}.json")
try:
os.makedirs(transcript_dir, exist_ok=True)
with open(transcript_path, "w", encoding="utf-8") as f:
f.write(raw_text)
except OSError as exc:
raise HTTPException(
status_code=500, detail=f"Failed to save transcript: {exc}"
) from exc
video.transcript_path = transcript_path
# ── 6. Commit & respond ──────────────────────────────────────────────
try:
await db.commit()
except Exception as exc:
await db.rollback()
logger.error("Database commit failed during ingest: %s", exc)
raise HTTPException(
status_code=500, detail="Database error during ingest"
) from exc
await db.refresh(video)
await db.refresh(creator)
# ── 7. Dispatch LLM pipeline (best-effort) ──────────────────────────
try:
from pipeline.stages import run_pipeline
run_pipeline.delay(str(video.id))
logger.info("Pipeline dispatched for video_id=%s", video.id)
except Exception as exc:
logger.warning(
"Pipeline dispatch failed for video_id=%s (ingest still succeeds): %s",
video.id,
exc,
)
logger.info(
"Ingested transcript: creator=%s, file=%s, segments=%d, reupload=%s",
creator.name,
source_file,
len(segment_objs),
is_reupload,
)
return TranscriptIngestResponse(
video_id=video.id,
creator_id=creator.id,
creator_name=creator.name,
filename=source_file,
segments_stored=len(segment_objs),
processing_status=video.processing_status.value,
is_reupload=is_reupload,
)

54
backend/routers/pipeline.py
View file

@ -1,54 +0,0 @@
"""Pipeline management endpoints for manual re-trigger and status inspection."""
import logging
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from database import get_session
from models import SourceVideo
logger = logging.getLogger("chrysopedia.pipeline")
router = APIRouter(prefix="/pipeline", tags=["pipeline"])
@router.post("/trigger/{video_id}")
async def trigger_pipeline(
video_id: str,
db: AsyncSession = Depends(get_session),
):
"""Manually trigger (or re-trigger) the LLM extraction pipeline for a video.
Looks up the SourceVideo by ID, dispatches ``run_pipeline.delay()``,
and returns the current processing status. Returns 404 if the video
does not exist.
"""
stmt = select(SourceVideo).where(SourceVideo.id == video_id)
result = await db.execute(stmt)
video = result.scalar_one_or_none()
if video is None:
raise HTTPException(status_code=404, detail=f"Video not found: {video_id}")
# Import inside handler to avoid circular import at module level
from pipeline.stages import run_pipeline
try:
run_pipeline.delay(str(video.id))
logger.info("Pipeline manually triggered for video_id=%s", video_id)
except Exception as exc:
logger.warning(
"Failed to dispatch pipeline for video_id=%s: %s", video_id, exc
)
raise HTTPException(
status_code=503,
detail="Pipeline dispatch failed — Celery/Redis may be unavailable",
) from exc
return {
"status": "triggered",
"video_id": str(video.id),
"current_processing_status": video.processing_status.value,
}

375
backend/routers/review.py
View file

@ -1,375 +0,0 @@
"""Review queue endpoints for Chrysopedia API.
Provides admin review workflow: list queue, stats, approve, reject,
edit, split, merge key moments, and toggle review/auto mode via Redis.
"""
import logging
import uuid
from typing import Annotated
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy import case, func, select
from sqlalchemy.ext.asyncio import AsyncSession
from config import get_settings
from database import get_session
from models import Creator, KeyMoment, KeyMomentContentType, ReviewStatus, SourceVideo
from redis_client import get_redis
from schemas import (
KeyMomentRead,
MomentEditRequest,
MomentMergeRequest,
MomentSplitRequest,
ReviewModeResponse,
ReviewModeUpdate,
ReviewQueueItem,
ReviewQueueResponse,
ReviewStatsResponse,
)
logger = logging.getLogger("chrysopedia.review")
router = APIRouter(prefix="/review", tags=["review"])
REDIS_MODE_KEY = "chrysopedia:review_mode"
VALID_STATUSES = {"pending", "approved", "edited", "rejected", "all"}
# ── Helpers ──────────────────────────────────────────────────────────────────
def _moment_to_queue_item(
moment: KeyMoment, video_filename: str, creator_name: str
) -> ReviewQueueItem:
"""Convert a KeyMoment ORM instance + joined fields to a ReviewQueueItem."""
data = KeyMomentRead.model_validate(moment).model_dump()
data["video_filename"] = video_filename
data["creator_name"] = creator_name
return ReviewQueueItem(**data)
# ── Endpoints ────────────────────────────────────────────────────────────────
@router.get("/queue", response_model=ReviewQueueResponse)
async def list_queue(
status: Annotated[str, Query()] = "pending",
offset: Annotated[int, Query(ge=0)] = 0,
limit: Annotated[int, Query(ge=1, le=1000)] = 50,
db: AsyncSession = Depends(get_session),
) -> ReviewQueueResponse:
"""List key moments in the review queue, filtered by status."""
if status not in VALID_STATUSES:
raise HTTPException(
status_code=400,
detail=f"Invalid status filter '{status}'. Must be one of: {', '.join(sorted(VALID_STATUSES))}",
)
# Base query joining KeyMoment → SourceVideo → Creator
base = (
select(
KeyMoment,
SourceVideo.filename.label("video_filename"),
Creator.name.label("creator_name"),
)
.join(SourceVideo, KeyMoment.source_video_id == SourceVideo.id)
.join(Creator, SourceVideo.creator_id == Creator.id)
)
if status != "all":
base = base.where(KeyMoment.review_status == ReviewStatus(status))
# Count total matching rows
count_stmt = select(func.count()).select_from(base.subquery())
total = (await db.execute(count_stmt)).scalar_one()
# Fetch paginated results
stmt = base.order_by(KeyMoment.created_at.desc()).offset(offset).limit(limit)
rows = (await db.execute(stmt)).all()
items = [
_moment_to_queue_item(row.KeyMoment, row.video_filename, row.creator_name)
for row in rows
]
return ReviewQueueResponse(items=items, total=total, offset=offset, limit=limit)
@router.get("/stats", response_model=ReviewStatsResponse)
async def get_stats(
db: AsyncSession = Depends(get_session),
) -> ReviewStatsResponse:
"""Return counts of key moments grouped by review status."""
stmt = (
select(
KeyMoment.review_status,
func.count().label("cnt"),
)
.group_by(KeyMoment.review_status)
)
result = await db.execute(stmt)
counts = {row.review_status.value: row.cnt for row in result.all()}
return ReviewStatsResponse(
pending=counts.get("pending", 0),
approved=counts.get("approved", 0),
edited=counts.get("edited", 0),
rejected=counts.get("rejected", 0),
)
@router.post("/moments/{moment_id}/approve", response_model=KeyMomentRead)
async def approve_moment(
moment_id: uuid.UUID,
db: AsyncSession = Depends(get_session),
) -> KeyMomentRead:
"""Approve a key moment for publishing."""
moment = await db.get(KeyMoment, moment_id)
if moment is None:
raise HTTPException(
status_code=404,
detail=f"Key moment {moment_id} not found",
)
moment.review_status = ReviewStatus.approved
await db.commit()
await db.refresh(moment)
logger.info("Approved key moment %s", moment_id)
return KeyMomentRead.model_validate(moment)
@router.post("/moments/{moment_id}/reject", response_model=KeyMomentRead)
async def reject_moment(
moment_id: uuid.UUID,
db: AsyncSession = Depends(get_session),
) -> KeyMomentRead:
"""Reject a key moment."""
moment = await db.get(KeyMoment, moment_id)
if moment is None:
raise HTTPException(
status_code=404,
detail=f"Key moment {moment_id} not found",
)
moment.review_status = ReviewStatus.rejected
await db.commit()
await db.refresh(moment)
logger.info("Rejected key moment %s", moment_id)
return KeyMomentRead.model_validate(moment)
@router.put("/moments/{moment_id}", response_model=KeyMomentRead)
async def edit_moment(
moment_id: uuid.UUID,
body: MomentEditRequest,
db: AsyncSession = Depends(get_session),
) -> KeyMomentRead:
"""Update editable fields of a key moment and set status to edited."""
moment = await db.get(KeyMoment, moment_id)
if moment is None:
raise HTTPException(
status_code=404,
detail=f"Key moment {moment_id} not found",
)
update_data = body.model_dump(exclude_unset=True)
# Convert content_type string to enum if provided
if "content_type" in update_data and update_data["content_type"] is not None:
try:
update_data["content_type"] = KeyMomentContentType(update_data["content_type"])
except ValueError:
raise HTTPException(
status_code=400,
detail=f"Invalid content_type '{update_data['content_type']}'",
)
for field, value in update_data.items():
setattr(moment, field, value)
moment.review_status = ReviewStatus.edited
await db.commit()
await db.refresh(moment)
logger.info("Edited key moment %s (fields: %s)", moment_id, list(update_data.keys()))
return KeyMomentRead.model_validate(moment)
@router.post("/moments/{moment_id}/split", response_model=list[KeyMomentRead])
async def split_moment(
moment_id: uuid.UUID,
body: MomentSplitRequest,
db: AsyncSession = Depends(get_session),
) -> list[KeyMomentRead]:
"""Split a key moment into two at the given timestamp."""
moment = await db.get(KeyMoment, moment_id)
if moment is None:
raise HTTPException(
status_code=404,
detail=f"Key moment {moment_id} not found",
)
# Validate split_time is strictly between start_time and end_time
if body.split_time <= moment.start_time or body.split_time >= moment.end_time:
raise HTTPException(
status_code=400,
detail=(
f"split_time ({body.split_time}) must be strictly between "
f"start_time ({moment.start_time}) and end_time ({moment.end_time})"
),
)
# Update original moment to [start_time, split_time)
original_end = moment.end_time
moment.end_time = body.split_time
moment.review_status = ReviewStatus.pending
# Create new moment for [split_time, end_time]
new_moment = KeyMoment(
source_video_id=moment.source_video_id,
technique_page_id=moment.technique_page_id,
title=f"{moment.title} (split)",
summary=moment.summary,
start_time=body.split_time,
end_time=original_end,
content_type=moment.content_type,
plugins=moment.plugins,
review_status=ReviewStatus.pending,
raw_transcript=moment.raw_transcript,
)
db.add(new_moment)
await db.commit()
await db.refresh(moment)
await db.refresh(new_moment)
logger.info(
"Split key moment %s at %.2f → original [%.2f, %.2f), new [%.2f, %.2f]",
moment_id, body.split_time,
moment.start_time, moment.end_time,
new_moment.start_time, new_moment.end_time,
)
return [
KeyMomentRead.model_validate(moment),
KeyMomentRead.model_validate(new_moment),
]
@router.post("/moments/{moment_id}/merge", response_model=KeyMomentRead)
async def merge_moments(
moment_id: uuid.UUID,
body: MomentMergeRequest,
db: AsyncSession = Depends(get_session),
) -> KeyMomentRead:
"""Merge two key moments into one."""
if moment_id == body.target_moment_id:
raise HTTPException(
status_code=400,
detail="Cannot merge a moment with itself",
)
source = await db.get(KeyMoment, moment_id)
if source is None:
raise HTTPException(
status_code=404,
detail=f"Key moment {moment_id} not found",
)
target = await db.get(KeyMoment, body.target_moment_id)
if target is None:
raise HTTPException(
status_code=404,
detail=f"Target key moment {body.target_moment_id} not found",
)
# Both must belong to the same source video
if source.source_video_id != target.source_video_id:
raise HTTPException(
status_code=400,
detail="Cannot merge moments from different source videos",
)
# Merge: combined summary, min start, max end
source.summary = f"{source.summary}\n\n{target.summary}"
source.start_time = min(source.start_time, target.start_time)
source.end_time = max(source.end_time, target.end_time)
source.review_status = ReviewStatus.pending
# Delete target
await db.delete(target)
await db.commit()
await db.refresh(source)
logger.info(
"Merged key moment %s with %s → [%.2f, %.2f]",
moment_id, body.target_moment_id,
source.start_time, source.end_time,
)
return KeyMomentRead.model_validate(source)
@router.get("/moments/{moment_id}", response_model=ReviewQueueItem)
async def get_moment(
moment_id: uuid.UUID,
db: AsyncSession = Depends(get_session),
) -> ReviewQueueItem:
"""Get a single key moment by ID with video and creator info."""
stmt = (
select(KeyMoment, SourceVideo.file_path, Creator.name)
.join(SourceVideo, KeyMoment.source_video_id == SourceVideo.id)
.join(Creator, SourceVideo.creator_id == Creator.id)
.where(KeyMoment.id == moment_id)
)
result = await db.execute(stmt)
row = result.one_or_none()
if row is None:
raise HTTPException(status_code=404, detail=f"Moment {moment_id} not found")
moment, file_path, creator_name = row
return _moment_to_queue_item(moment, file_path or "", creator_name)
@router.get("/mode", response_model=ReviewModeResponse)
async def get_mode() -> ReviewModeResponse:
"""Get the current review mode (review vs auto)."""
settings = get_settings()
try:
redis = await get_redis()
try:
value = await redis.get(REDIS_MODE_KEY)
if value is not None:
return ReviewModeResponse(review_mode=value.lower() == "true")
finally:
await redis.aclose()
except Exception as exc:
# Redis unavailable — fall back to config default
logger.warning("Redis unavailable for mode read, using config default: %s", exc)
return ReviewModeResponse(review_mode=settings.review_mode)
@router.put("/mode", response_model=ReviewModeResponse)
async def set_mode(
body: ReviewModeUpdate,
) -> ReviewModeResponse:
"""Set the review mode (review vs auto)."""
try:
redis = await get_redis()
try:
await redis.set(REDIS_MODE_KEY, str(body.review_mode))
finally:
await redis.aclose()
except Exception as exc:
logger.error("Failed to set review mode in Redis: %s", exc)
raise HTTPException(
status_code=503,
detail=f"Redis unavailable: {exc}",
)
logger.info("Review mode set to %s", body.review_mode)
return ReviewModeResponse(review_mode=body.review_mode)

46
backend/routers/search.py
View file

@ -1,46 +0,0 @@
"""Search endpoint for semantic + keyword search with graceful fallback."""
from __future__ import annotations
import logging
from typing import Annotated
from fastapi import APIRouter, Depends, Query
from sqlalchemy.ext.asyncio import AsyncSession
from config import get_settings
from database import get_session
from schemas import SearchResponse, SearchResultItem
from search_service import SearchService
logger = logging.getLogger("chrysopedia.search.router")
router = APIRouter(prefix="/search", tags=["search"])
def _get_search_service() -> SearchService:
"""Build a SearchService from current settings."""
return SearchService(get_settings())
@router.get("", response_model=SearchResponse)
async def search(
q: Annotated[str, Query(max_length=500)] = "",
scope: Annotated[str, Query()] = "all",
limit: Annotated[int, Query(ge=1, le=100)] = 20,
db: AsyncSession = Depends(get_session),
) -> SearchResponse:
"""Semantic search with keyword fallback.
- **q**: Search query (max 500 chars). Empty → empty results.
- **scope**: ``all`` | ``topics`` | ``creators``. Invalid → defaults to ``all``.
- **limit**: Max results (1–100, default 20).
"""
svc = _get_search_service()
result = await svc.search(query=q, scope=scope, limit=limit, db=db)
return SearchResponse(
items=[SearchResultItem(**item) for item in result["items"]],
total=result["total"],
query=result["query"],
fallback_used=result["fallback_used"],
)

209
backend/routers/techniques.py
View file

@ -1,209 +0,0 @@
"""Technique page endpoints — list and detail with eager-loaded relations."""
from __future__ import annotations
import logging
from typing import Annotated
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.orm import selectinload
from database import get_session
from models import Creator, KeyMoment, RelatedTechniqueLink, SourceVideo, TechniquePage, TechniquePageVersion
from schemas import (
CreatorInfo,
KeyMomentSummary,
PaginatedResponse,
RelatedLinkItem,
TechniquePageDetail,
TechniquePageRead,
TechniquePageVersionDetail,
TechniquePageVersionListResponse,
TechniquePageVersionSummary,
)
logger = logging.getLogger("chrysopedia.techniques")
router = APIRouter(prefix="/techniques", tags=["techniques"])
@router.get("", response_model=PaginatedResponse)
async def list_techniques(
category: Annotated[str | None, Query()] = None,
creator_slug: Annotated[str | None, Query()] = None,
offset: Annotated[int, Query(ge=0)] = 0,
limit: Annotated[int, Query(ge=1, le=100)] = 50,
db: AsyncSession = Depends(get_session),
) -> PaginatedResponse:
"""List technique pages with optional category/creator filtering."""
stmt = select(TechniquePage)
if category:
stmt = stmt.where(TechniquePage.topic_category == category)
if creator_slug:
# Join to Creator to filter by slug
stmt = stmt.join(Creator, TechniquePage.creator_id == Creator.id).where(
Creator.slug == creator_slug
)
# Count total before pagination
from sqlalchemy import func
count_stmt = select(func.count()).select_from(stmt.subquery())
count_result = await db.execute(count_stmt)
total = count_result.scalar() or 0
stmt = stmt.order_by(TechniquePage.created_at.desc()).offset(offset).limit(limit)
result = await db.execute(stmt)
pages = result.scalars().all()
return PaginatedResponse(
items=[TechniquePageRead.model_validate(p) for p in pages],
total=total,
offset=offset,
limit=limit,
)
@router.get("/{slug}", response_model=TechniquePageDetail)
async def get_technique(
slug: str,
db: AsyncSession = Depends(get_session),
) -> TechniquePageDetail:
"""Get full technique page detail with key moments, creator, and related links."""
stmt = (
select(TechniquePage)
.where(TechniquePage.slug == slug)
.options(
selectinload(TechniquePage.key_moments).selectinload(KeyMoment.source_video),
selectinload(TechniquePage.creator),
selectinload(TechniquePage.outgoing_links).selectinload(
RelatedTechniqueLink.target_page
),
selectinload(TechniquePage.incoming_links).selectinload(
RelatedTechniqueLink.source_page
),
)
)
result = await db.execute(stmt)
page = result.scalar_one_or_none()
if page is None:
raise HTTPException(status_code=404, detail=f"Technique '{slug}' not found")
# Build key moments (ordered by start_time)
key_moments = sorted(page.key_moments, key=lambda km: km.start_time)
key_moment_items = []
for km in key_moments:
item = KeyMomentSummary.model_validate(km)
item.video_filename = km.source_video.filename if km.source_video else ""
key_moment_items.append(item)
# Build creator info
creator_info = None
if page.creator:
creator_info = CreatorInfo(
name=page.creator.name,
slug=page.creator.slug,
genres=page.creator.genres,
)
# Build related links (outgoing + incoming)
related_links: list[RelatedLinkItem] = []
for link in page.outgoing_links:
if link.target_page:
related_links.append(
RelatedLinkItem(
target_title=link.target_page.title,
target_slug=link.target_page.slug,
relationship=link.relationship.value if hasattr(link.relationship, 'value') else str(link.relationship),
)
)
for link in page.incoming_links:
if link.source_page:
related_links.append(
RelatedLinkItem(
target_title=link.source_page.title,
target_slug=link.source_page.slug,
relationship=link.relationship.value if hasattr(link.relationship, 'value') else str(link.relationship),
)
)
base = TechniquePageRead.model_validate(page)
# Count versions for this page
version_count_stmt = select(func.count()).where(
TechniquePageVersion.technique_page_id == page.id
)
version_count_result = await db.execute(version_count_stmt)
version_count = version_count_result.scalar() or 0
return TechniquePageDetail(
**base.model_dump(),
key_moments=key_moment_items,
creator_info=creator_info,
related_links=related_links,
version_count=version_count,
)
@router.get("/{slug}/versions", response_model=TechniquePageVersionListResponse)
async def list_technique_versions(
slug: str,
db: AsyncSession = Depends(get_session),
) -> TechniquePageVersionListResponse:
"""List all version snapshots for a technique page, newest first."""
# Resolve the technique page
page_stmt = select(TechniquePage).where(TechniquePage.slug == slug)
page_result = await db.execute(page_stmt)
page = page_result.scalar_one_or_none()
if page is None:
raise HTTPException(status_code=404, detail=f"Technique '{slug}' not found")
# Fetch versions ordered by version_number DESC
versions_stmt = (
select(TechniquePageVersion)
.where(TechniquePageVersion.technique_page_id == page.id)
.order_by(TechniquePageVersion.version_number.desc())
)
versions_result = await db.execute(versions_stmt)
versions = versions_result.scalars().all()
items = [TechniquePageVersionSummary.model_validate(v) for v in versions]
return TechniquePageVersionListResponse(items=items, total=len(items))
@router.get("/{slug}/versions/{version_number}", response_model=TechniquePageVersionDetail)
async def get_technique_version(
slug: str,
version_number: int,
db: AsyncSession = Depends(get_session),
) -> TechniquePageVersionDetail:
"""Get a specific version snapshot by version number."""
# Resolve the technique page
page_stmt = select(TechniquePage).where(TechniquePage.slug == slug)
page_result = await db.execute(page_stmt)
page = page_result.scalar_one_or_none()
if page is None:
raise HTTPException(status_code=404, detail=f"Technique '{slug}' not found")
# Fetch the specific version
version_stmt = (
select(TechniquePageVersion)
.where(
TechniquePageVersion.technique_page_id == page.id,
TechniquePageVersion.version_number == version_number,
)
)
version_result = await db.execute(version_stmt)
version = version_result.scalar_one_or_none()
if version is None:
raise HTTPException(
status_code=404,
detail=f"Version {version_number} not found for technique '{slug}'",
)
return TechniquePageVersionDetail.model_validate(version)

135
backend/routers/topics.py
View file

@ -1,135 +0,0 @@
"""Topics endpoint — two-level category hierarchy with aggregated counts."""
from __future__ import annotations
import logging
import os
from typing import Annotated, Any
import yaml
from fastapi import APIRouter, Depends, Query
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
from database import get_session
from models import Creator, TechniquePage
from schemas import (
PaginatedResponse,
TechniquePageRead,
TopicCategory,
TopicSubTopic,
)
logger = logging.getLogger("chrysopedia.topics")
router = APIRouter(prefix="/topics", tags=["topics"])
# Path to canonical_tags.yaml relative to the backend directory
_TAGS_PATH = os.path.join(os.path.dirname(__file__), "..", "..", "config", "canonical_tags.yaml")
def _load_canonical_tags() -> list[dict[str, Any]]:
"""Load the canonical tag categories from YAML."""
path = os.path.normpath(_TAGS_PATH)
try:
with open(path) as f:
data = yaml.safe_load(f)
return data.get("categories", [])
except FileNotFoundError:
logger.warning("canonical_tags.yaml not found at %s", path)
return []
@router.get("", response_model=list[TopicCategory])
async def list_topics(
db: AsyncSession = Depends(get_session),
) -> list[TopicCategory]:
"""Return the two-level topic hierarchy with technique/creator counts per sub-topic.
Categories come from ``canonical_tags.yaml``. Counts are computed
from live DB data by matching ``topic_tags`` array contents.
"""
categories = _load_canonical_tags()
# Pre-fetch all technique pages with their tags and creator_ids for counting
tp_stmt = select(
TechniquePage.topic_category,
TechniquePage.topic_tags,
TechniquePage.creator_id,
)
tp_result = await db.execute(tp_stmt)
tp_rows = tp_result.all()
# Build per-sub-topic counts
result: list[TopicCategory] = []
for cat in categories:
cat_name = cat.get("name", "")
cat_desc = cat.get("description", "")
sub_topic_names: list[str] = cat.get("sub_topics", [])
sub_topics: list[TopicSubTopic] = []
for st_name in sub_topic_names:
technique_count = 0
creator_ids: set[str] = set()
for tp_cat, tp_tags, tp_creator_id in tp_rows:
tags = tp_tags or []
# Match if the sub-topic name appears in the technique's tags
# or if the category matches and tag is in sub-topics
if st_name.lower() in [t.lower() for t in tags]:
technique_count += 1
creator_ids.add(str(tp_creator_id))
sub_topics.append(
TopicSubTopic(
name=st_name,
technique_count=technique_count,
creator_count=len(creator_ids),
)
)
result.append(
TopicCategory(
name=cat_name,
description=cat_desc,
sub_topics=sub_topics,
)
)
return result
@router.get("/{category_slug}", response_model=PaginatedResponse)
async def get_topic_techniques(
category_slug: str,
offset: Annotated[int, Query(ge=0)] = 0,
limit: Annotated[int, Query(ge=1, le=100)] = 50,
db: AsyncSession = Depends(get_session),
) -> PaginatedResponse:
"""Return technique pages filtered by topic_category.
The ``category_slug`` is matched case-insensitively against
``technique_pages.topic_category`` (e.g. 'sound-design' matches 'Sound design').
"""
# Normalize slug to category name: replace hyphens with spaces, title-case
category_name = category_slug.replace("-", " ").title()
# Also try exact match on the slug form
stmt = select(TechniquePage).where(
TechniquePage.topic_category.ilike(category_name)
)
count_stmt = select(func.count()).select_from(stmt.subquery())
count_result = await db.execute(count_stmt)
total = count_result.scalar() or 0
stmt = stmt.order_by(TechniquePage.title).offset(offset).limit(limit)
result = await db.execute(stmt)
pages = result.scalars().all()
return PaginatedResponse(
items=[TechniquePageRead.model_validate(p) for p in pages],
total=total,
offset=offset,
limit=limit,
)

36
backend/routers/videos.py
View file

@ -1,36 +0,0 @@
"""Source video endpoints for Chrysopedia API."""
import logging
from typing import Annotated
from fastapi import APIRouter, Depends, Query
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from database import get_session
from models import SourceVideo
from schemas import SourceVideoRead
logger = logging.getLogger("chrysopedia.videos")
router = APIRouter(prefix="/videos", tags=["videos"])
@router.get("", response_model=list[SourceVideoRead])
async def list_videos(
offset: Annotated[int, Query(ge=0)] = 0,
limit: Annotated[int, Query(ge=1, le=100)] = 50,
creator_id: str | None = None,
db: AsyncSession = Depends(get_session),
) -> list[SourceVideoRead]:
"""List source videos with optional filtering by creator."""
stmt = select(SourceVideo).order_by(SourceVideo.created_at.desc())
if creator_id:
stmt = stmt.where(SourceVideo.creator_id == creator_id)
stmt = stmt.offset(offset).limit(limit)
result = await db.execute(stmt)
videos = result.scalars().all()
logger.debug("Listed %d videos (offset=%d, limit=%d)", len(videos), offset, limit)
return [SourceVideoRead.model_validate(v) for v in videos]

366
backend/schemas.py
View file

@ -1,366 +0,0 @@
"""Pydantic schemas for the Chrysopedia API.
Read-only schemas for list/detail endpoints and input schemas for creation.
Each schema mirrors the corresponding SQLAlchemy model in models.py.
"""
from __future__ import annotations
import uuid
from datetime import datetime
from pydantic import BaseModel, ConfigDict, Field
# ── Health ───────────────────────────────────────────────────────────────────
class HealthResponse(BaseModel):
status: str = "ok"
service: str = "chrysopedia-api"
version: str = "0.1.0"
database: str = "unknown"
# ── Creator ──────────────────────────────────────────────────────────────────
class CreatorBase(BaseModel):
name: str
slug: str
genres: list[str] | None = None
folder_name: str
class CreatorCreate(CreatorBase):
pass
class CreatorRead(CreatorBase):
model_config = ConfigDict(from_attributes=True)
id: uuid.UUID
view_count: int = 0
created_at: datetime
updated_at: datetime
class CreatorDetail(CreatorRead):
"""Creator with nested video count."""
video_count: int = 0
# ── SourceVideo ──────────────────────────────────────────────────────────────
class SourceVideoBase(BaseModel):
filename: str
file_path: str
duration_seconds: int | None = None
content_type: str
transcript_path: str | None = None
class SourceVideoCreate(SourceVideoBase):
creator_id: uuid.UUID
class SourceVideoRead(SourceVideoBase):
model_config = ConfigDict(from_attributes=True)
id: uuid.UUID
creator_id: uuid.UUID
processing_status: str = "pending"
created_at: datetime
updated_at: datetime
# ── TranscriptSegment ────────────────────────────────────────────────────────
class TranscriptSegmentBase(BaseModel):
start_time: float
end_time: float
text: str
segment_index: int
topic_label: str | None = None
class TranscriptSegmentCreate(TranscriptSegmentBase):
source_video_id: uuid.UUID
class TranscriptSegmentRead(TranscriptSegmentBase):
model_config = ConfigDict(from_attributes=True)
id: uuid.UUID
source_video_id: uuid.UUID
# ── KeyMoment ────────────────────────────────────────────────────────────────
class KeyMomentBase(BaseModel):
title: str
summary: str
start_time: float
end_time: float
content_type: str
plugins: list[str] | None = None
raw_transcript: str | None = None
class KeyMomentCreate(KeyMomentBase):
source_video_id: uuid.UUID
technique_page_id: uuid.UUID | None = None
class KeyMomentRead(KeyMomentBase):
model_config = ConfigDict(from_attributes=True)
id: uuid.UUID
source_video_id: uuid.UUID
technique_page_id: uuid.UUID | None = None
review_status: str = "pending"
created_at: datetime
updated_at: datetime
# ── TechniquePage ────────────────────────────────────────────────────────────
class TechniquePageBase(BaseModel):
title: str
slug: str
topic_category: str
topic_tags: list[str] | None = None
summary: str | None = None
body_sections: dict | None = None
signal_chains: list | None = None
plugins: list[str] | None = None
class TechniquePageCreate(TechniquePageBase):
creator_id: uuid.UUID
source_quality: str | None = None
class TechniquePageRead(TechniquePageBase):
model_config = ConfigDict(from_attributes=True)
id: uuid.UUID
creator_id: uuid.UUID
source_quality: str | None = None
view_count: int = 0
review_status: str = "draft"
created_at: datetime
updated_at: datetime
# ── RelatedTechniqueLink ─────────────────────────────────────────────────────
class RelatedTechniqueLinkBase(BaseModel):
source_page_id: uuid.UUID
target_page_id: uuid.UUID
relationship: str
class RelatedTechniqueLinkCreate(RelatedTechniqueLinkBase):
pass
class RelatedTechniqueLinkRead(RelatedTechniqueLinkBase):
model_config = ConfigDict(from_attributes=True)
id: uuid.UUID
# ── Tag ──────────────────────────────────────────────────────────────────────
class TagBase(BaseModel):
name: str
category: str
aliases: list[str] | None = None
class TagCreate(TagBase):
pass
class TagRead(TagBase):
model_config = ConfigDict(from_attributes=True)
id: uuid.UUID
# ── Transcript Ingestion ─────────────────────────────────────────────────────
class TranscriptIngestResponse(BaseModel):
"""Response returned after successfully ingesting a transcript."""
video_id: uuid.UUID
creator_id: uuid.UUID
creator_name: str
filename: str
segments_stored: int
processing_status: str
is_reupload: bool
# ── Pagination wrapper ───────────────────────────────────────────────────────
class PaginatedResponse(BaseModel):
"""Generic paginated list response."""
items: list = Field(default_factory=list)
total: int = 0
offset: int = 0
limit: int = 50
# ── Review Queue ─────────────────────────────────────────────────────────────
class ReviewQueueItem(KeyMomentRead):
"""Key moment enriched with source video and creator info for review UI."""
video_filename: str
creator_name: str
class ReviewQueueResponse(BaseModel):
"""Paginated response for the review queue."""
items: list[ReviewQueueItem] = Field(default_factory=list)
total: int = 0
offset: int = 0
limit: int = 50
class ReviewStatsResponse(BaseModel):
"""Counts of key moments grouped by review status."""
pending: int = 0
approved: int = 0
edited: int = 0
rejected: int = 0
class MomentEditRequest(BaseModel):
"""Editable fields for a key moment."""
title: str | None = None
summary: str | None = None
start_time: float | None = None
end_time: float | None = None
content_type: str | None = None
plugins: list[str] | None = None
class MomentSplitRequest(BaseModel):
"""Request to split a moment at a given timestamp."""
split_time: float
class MomentMergeRequest(BaseModel):
"""Request to merge two moments."""
target_moment_id: uuid.UUID
class ReviewModeResponse(BaseModel):
"""Current review mode state."""
review_mode: bool
class ReviewModeUpdate(BaseModel):
"""Request to update the review mode."""
review_mode: bool
# ── Search ───────────────────────────────────────────────────────────────────
class SearchResultItem(BaseModel):
"""A single search result."""
title: str
slug: str = ""
type: str = ""
score: float = 0.0
summary: str = ""
creator_name: str = ""
creator_slug: str = ""
topic_category: str = ""
topic_tags: list[str] = Field(default_factory=list)
class SearchResponse(BaseModel):
"""Top-level search response with metadata."""
items: list[SearchResultItem] = Field(default_factory=list)
total: int = 0
query: str = ""
fallback_used: bool = False
# ── Technique Page Detail ────────────────────────────────────────────────────
class KeyMomentSummary(BaseModel):
"""Lightweight key moment for technique page detail."""
model_config = ConfigDict(from_attributes=True)
id: uuid.UUID
title: str
summary: str
start_time: float
end_time: float
content_type: str
plugins: list[str] | None = None
video_filename: str = ""
class RelatedLinkItem(BaseModel):
"""A related technique link with target info."""
model_config = ConfigDict(from_attributes=True)
target_title: str = ""
target_slug: str = ""
relationship: str = ""
class CreatorInfo(BaseModel):
"""Minimal creator info embedded in technique detail."""
model_config = ConfigDict(from_attributes=True)
name: str
slug: str
genres: list[str] | None = None
class TechniquePageDetail(TechniquePageRead):
"""Technique page with nested key moments, creator, and related links."""
key_moments: list[KeyMomentSummary] = Field(default_factory=list)
creator_info: CreatorInfo | None = None
related_links: list[RelatedLinkItem] = Field(default_factory=list)
version_count: int = 0
# ── Technique Page Versions ──────────────────────────────────────────────────
class TechniquePageVersionSummary(BaseModel):
"""Lightweight version entry for list responses."""
model_config = ConfigDict(from_attributes=True)
version_number: int
created_at: datetime
pipeline_metadata: dict | None = None
class TechniquePageVersionDetail(BaseModel):
"""Full version snapshot for detail responses."""
model_config = ConfigDict(from_attributes=True)
version_number: int
content_snapshot: dict
pipeline_metadata: dict | None = None
created_at: datetime
class TechniquePageVersionListResponse(BaseModel):
"""Response for version list endpoint."""
items: list[TechniquePageVersionSummary] = Field(default_factory=list)
total: int = 0
# ── Topics ───────────────────────────────────────────────────────────────────
class TopicSubTopic(BaseModel):
"""A sub-topic with aggregated counts."""
name: str
technique_count: int = 0
creator_count: int = 0
class TopicCategory(BaseModel):
"""A top-level topic category with sub-topics."""
name: str
description: str = ""
sub_topics: list[TopicSubTopic] = Field(default_factory=list)
# ── Creator Browse ───────────────────────────────────────────────────────────
class CreatorBrowseItem(CreatorRead):
"""Creator with technique and video counts for browse pages."""
technique_count: int = 0
video_count: int = 0

337
backend/search_service.py
View file

@ -1,337 +0,0 @@
"""Async search service for the public search endpoint.
Orchestrates semantic search (embedding + Qdrant) with keyword fallback.
All external calls have timeouts and graceful degradation — if embedding
or Qdrant fail, the service falls back to keyword-only (ILIKE) search.
"""
from __future__ import annotations
import asyncio
import logging
import time
from typing import Any
import openai
from qdrant_client import AsyncQdrantClient
from qdrant_client.http import exceptions as qdrant_exceptions
from qdrant_client.models import FieldCondition, Filter, MatchValue
from sqlalchemy import or_, select
from sqlalchemy.ext.asyncio import AsyncSession
from config import Settings
from models import Creator, KeyMoment, TechniquePage
logger = logging.getLogger("chrysopedia.search")
# Timeout for external calls (embedding API, Qdrant) in seconds
_EXTERNAL_TIMEOUT = 0.3 # 300ms per plan
class SearchService:
"""Async search service with semantic + keyword fallback.
Parameters
----------
settings:
Application settings containing embedding and Qdrant config.
"""
def __init__(self, settings: Settings) -> None:
self.settings = settings
self._openai = openai.AsyncOpenAI(
base_url=settings.embedding_api_url,
api_key=settings.llm_api_key,
)
self._qdrant = AsyncQdrantClient(url=settings.qdrant_url)
self._collection = settings.qdrant_collection
# ── Embedding ────────────────────────────────────────────────────────
async def embed_query(self, text: str) -> list[float] | None:
"""Embed a query string into a vector.
Returns None on any failure (timeout, connection, malformed response)
so the caller can fall back to keyword search.
"""
try:
response = await asyncio.wait_for(
self._openai.embeddings.create(
model=self.settings.embedding_model,
input=text,
),
timeout=_EXTERNAL_TIMEOUT,
)
except asyncio.TimeoutError:
logger.warning("Embedding API timeout (%.0fms limit) for query: %.50s…", _EXTERNAL_TIMEOUT * 1000, text)
return None
except (openai.APIConnectionError, openai.APITimeoutError) as exc:
logger.warning("Embedding API connection error (%s: %s)", type(exc).__name__, exc)
return None
except openai.APIError as exc:
logger.warning("Embedding API error (%s: %s)", type(exc).__name__, exc)
return None
if not response.data:
logger.warning("Embedding API returned empty data for query: %.50s…", text)
return None
vector = response.data[0].embedding
if len(vector) != self.settings.embedding_dimensions:
logger.warning(
"Embedding dimension mismatch: expected %d, got %d",
self.settings.embedding_dimensions,
len(vector),
)
return None
return vector
# ── Qdrant vector search ─────────────────────────────────────────────
async def search_qdrant(
self,
vector: list[float],
limit: int = 20,
type_filter: str | None = None,
) -> list[dict[str, Any]]:
"""Search Qdrant for nearest neighbours.
Returns a list of dicts with 'score' and 'payload' keys.
Returns empty list on failure.
"""
query_filter = None
if type_filter:
query_filter = Filter(
must=[FieldCondition(key="type", match=MatchValue(value=type_filter))]
)
try:
results = await asyncio.wait_for(
self._qdrant.query_points(
collection_name=self._collection,
query=vector,
query_filter=query_filter,
limit=limit,
with_payload=True,
),
timeout=_EXTERNAL_TIMEOUT,
)
except asyncio.TimeoutError:
logger.warning("Qdrant search timeout (%.0fms limit)", _EXTERNAL_TIMEOUT * 1000)
return []
except qdrant_exceptions.UnexpectedResponse as exc:
logger.warning("Qdrant search error: %s", exc)
return []
except Exception as exc:
logger.warning("Qdrant connection error (%s: %s)", type(exc).__name__, exc)
return []
return [
{"score": point.score, "payload": point.payload}
for point in results.points
]
# ── Keyword fallback ─────────────────────────────────────────────────
async def keyword_search(
self,
query: str,
scope: str,
limit: int,
db: AsyncSession,
) -> list[dict[str, Any]]:
"""ILIKE keyword search across technique pages, key moments, and creators.
Searches title/name columns. Returns a unified list of result dicts.
"""
results: list[dict[str, Any]] = []
pattern = f"%{query}%"
if scope in ("all", "topics"):
stmt = (
select(TechniquePage)
.where(
or_(
TechniquePage.title.ilike(pattern),
TechniquePage.summary.ilike(pattern),
)
)
.limit(limit)
)
rows = await db.execute(stmt)
for tp in rows.scalars().all():
results.append({
"type": "technique_page",
"title": tp.title,
"slug": tp.slug,
"summary": tp.summary or "",
"topic_category": tp.topic_category,
"topic_tags": tp.topic_tags or [],
"creator_id": str(tp.creator_id),
"score": 0.0,
})
if scope in ("all",):
km_stmt = (
select(KeyMoment)
.where(KeyMoment.title.ilike(pattern))
.limit(limit)
)
km_rows = await db.execute(km_stmt)
for km in km_rows.scalars().all():
results.append({
"type": "key_moment",
"title": km.title,
"slug": "",
"summary": km.summary or "",
"topic_category": "",
"topic_tags": [],
"creator_id": "",
"score": 0.0,
})
if scope in ("all", "creators"):
cr_stmt = (
select(Creator)
.where(Creator.name.ilike(pattern))
.limit(limit)
)
cr_rows = await db.execute(cr_stmt)
for cr in cr_rows.scalars().all():
results.append({
"type": "creator",
"title": cr.name,
"slug": cr.slug,
"summary": "",
"topic_category": "",
"topic_tags": cr.genres or [],
"creator_id": str(cr.id),
"score": 0.0,
})
return results[:limit]
# ── Orchestrator ─────────────────────────────────────────────────────
async def search(
self,
query: str,
scope: str,
limit: int,
db: AsyncSession,
) -> dict[str, Any]:
"""Run semantic search with keyword fallback.
Returns a dict matching the SearchResponse schema shape.
"""
start = time.monotonic()
# Validate / sanitize inputs
if not query or not query.strip():
return {"items": [], "total": 0, "query": query, "fallback_used": False}
# Truncate long queries
query = query.strip()[:500]
# Normalize scope
if scope not in ("all", "topics", "creators"):
scope = "all"
# Map scope to Qdrant type filter
type_filter_map = {
"all": None,
"topics": "technique_page",
"creators": None, # creators aren't in Qdrant
}
qdrant_type_filter = type_filter_map.get(scope)
fallback_used = False
items: list[dict[str, Any]] = []
# Try semantic search
vector = await self.embed_query(query)
if vector is not None:
qdrant_results = await self.search_qdrant(vector, limit=limit, type_filter=qdrant_type_filter)
if qdrant_results:
# Enrich Qdrant results with DB metadata
items = await self._enrich_results(qdrant_results, db)
# Fallback to keyword search if semantic failed or returned nothing
if not items:
items = await self.keyword_search(query, scope, limit, db)
fallback_used = True
elapsed_ms = (time.monotonic() - start) * 1000
logger.info(
"Search query=%r scope=%s results=%d fallback=%s latency_ms=%.1f",
query,
scope,
len(items),
fallback_used,
elapsed_ms,
)
return {
"items": items,
"total": len(items),
"query": query,
"fallback_used": fallback_used,
}
# ── Result enrichment ────────────────────────────────────────────────
async def _enrich_results(
self,
qdrant_results: list[dict[str, Any]],
db: AsyncSession,
) -> list[dict[str, Any]]:
"""Enrich Qdrant results with creator names and slugs from DB."""
enriched: list[dict[str, Any]] = []
# Collect creator_ids to batch-fetch
creator_ids = set()
for r in qdrant_results:
payload = r.get("payload", {})
cid = payload.get("creator_id")
if cid:
creator_ids.add(cid)
# Batch fetch creators
creator_map: dict[str, dict[str, str]] = {}
if creator_ids:
from sqlalchemy.dialects.postgresql import UUID as PgUUID
import uuid as uuid_mod
valid_ids = []
for cid in creator_ids:
try:
valid_ids.append(uuid_mod.UUID(cid))
except (ValueError, AttributeError):
pass
if valid_ids:
stmt = select(Creator).where(Creator.id.in_(valid_ids))
result = await db.execute(stmt)
for c in result.scalars().all():
creator_map[str(c.id)] = {"name": c.name, "slug": c.slug}
for r in qdrant_results:
payload = r.get("payload", {})
cid = payload.get("creator_id", "")
creator_info = creator_map.get(cid, {"name": "", "slug": ""})
enriched.append({
"type": payload.get("type", ""),
"title": payload.get("title", ""),
"slug": payload.get("slug", payload.get("title", "").lower().replace(" ", "-")),
"summary": payload.get("summary", ""),
"topic_category": payload.get("topic_category", ""),
"topic_tags": payload.get("topic_tags", []),
"creator_id": cid,
"creator_name": creator_info["name"],
"creator_slug": creator_info["slug"],
"score": r.get("score", 0.0),
})
return enriched

0
backend/tests/__init__.py
View file

192
backend/tests/conftest.py
View file

@ -1,192 +0,0 @@
"""Shared fixtures for Chrysopedia integration tests.
Provides:
- Async SQLAlchemy engine/session against a real PostgreSQL test database
- Sync SQLAlchemy engine/session for pipeline stage tests (Celery stages are sync)
- httpx.AsyncClient wired to the FastAPI app with dependency overrides
- Pre-ingest fixture for pipeline tests
- Sample transcript fixture path and temporary storage directory
Key design choice: function-scoped engine with NullPool avoids asyncpg
"another operation in progress" errors caused by session-scoped connection
reuse between the ASGI test client and verification queries.
"""
import json
import os
import pathlib
import uuid
import pytest
import pytest_asyncio
from httpx import ASGITransport, AsyncClient
from sqlalchemy import create_engine
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from sqlalchemy.orm import Session, sessionmaker
from sqlalchemy.pool import NullPool
# Ensure backend/ is on sys.path so "from models import ..." works
import sys
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent))
from database import Base, get_session # noqa: E402
from main import app # noqa: E402
from models import ( # noqa: E402
ContentType,
Creator,
ProcessingStatus,
SourceVideo,
TranscriptSegment,
)
TEST_DATABASE_URL = os.getenv(
"TEST_DATABASE_URL",
"postgresql+asyncpg://chrysopedia:changeme@localhost:5433/chrysopedia_test",
)
TEST_DATABASE_URL_SYNC = TEST_DATABASE_URL.replace(
"postgresql+asyncpg://", "postgresql+psycopg2://"
)
@pytest_asyncio.fixture()
async def db_engine():
"""Create a per-test async engine (NullPool) and create/drop all tables."""
engine = create_async_engine(TEST_DATABASE_URL, echo=False, poolclass=NullPool)
# Create all tables fresh for each test
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.drop_all)
await conn.run_sync(Base.metadata.create_all)
yield engine
# Drop all tables after test
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.drop_all)
await engine.dispose()
@pytest_asyncio.fixture()
async def client(db_engine, tmp_path):
"""Async HTTP test client wired to FastAPI with dependency overrides."""
session_factory = async_sessionmaker(
db_engine, class_=AsyncSession, expire_on_commit=False
)
async def _override_get_session():
async with session_factory() as session:
yield session
# Override DB session dependency
app.dependency_overrides[get_session] = _override_get_session
# Override transcript_storage_path via environment variable
os.environ["TRANSCRIPT_STORAGE_PATH"] = str(tmp_path)
# Clear the lru_cache so Settings picks up the new env var
from config import get_settings
get_settings.cache_clear()
transport = ASGITransport(app=app)
async with AsyncClient(transport=transport, base_url="http://testserver") as ac:
yield ac
# Teardown: clean overrides and restore settings cache
app.dependency_overrides.clear()
os.environ.pop("TRANSCRIPT_STORAGE_PATH", None)
get_settings.cache_clear()
@pytest.fixture()
def sample_transcript_path() -> pathlib.Path:
"""Path to the sample 5-segment transcript JSON fixture."""
return pathlib.Path(__file__).parent / "fixtures" / "sample_transcript.json"
@pytest.fixture()
def tmp_transcript_dir(tmp_path) -> pathlib.Path:
"""Temporary directory for transcript storage during tests."""
return tmp_path
# ── Sync engine/session for pipeline stages ──────────────────────────────────
@pytest.fixture()
def sync_engine(db_engine):
"""Create a sync SQLAlchemy engine pointing at the test database.
Tables are already created/dropped by the async ``db_engine`` fixture,
so this fixture just wraps a sync engine around the same DB URL.
"""
engine = create_engine(TEST_DATABASE_URL_SYNC, echo=False, poolclass=NullPool)
yield engine
engine.dispose()
@pytest.fixture()
def sync_session(sync_engine) -> Session:
"""Create a sync SQLAlchemy session for pipeline stage tests."""
factory = sessionmaker(bind=sync_engine)
session = factory()
yield session
session.close()
# ── Pre-ingest fixture for pipeline tests ────────────────────────────────────
@pytest.fixture()
def pre_ingested_video(sync_engine):
"""Ingest the sample transcript directly into the test DB via sync ORM.
Returns a dict with ``video_id``, ``creator_id``, and ``segment_count``.
"""
factory = sessionmaker(bind=sync_engine)
session = factory()
try:
# Create creator
creator = Creator(
name="Skope",
slug="skope",
folder_name="Skope",
)
session.add(creator)
session.flush()
# Create video
video = SourceVideo(
creator_id=creator.id,
filename="mixing-basics-ep1.mp4",
file_path="Skope/mixing-basics-ep1.mp4",
duration_seconds=1234,
content_type=ContentType.tutorial,
processing_status=ProcessingStatus.transcribed,
)
session.add(video)
session.flush()
# Create transcript segments
sample = pathlib.Path(__file__).parent / "fixtures" / "sample_transcript.json"
data = json.loads(sample.read_text())
for idx, seg in enumerate(data["segments"]):
session.add(TranscriptSegment(
source_video_id=video.id,
start_time=float(seg["start"]),
end_time=float(seg["end"]),
text=str(seg["text"]),
segment_index=idx,
))
session.commit()
result = {
"video_id": str(video.id),
"creator_id": str(creator.id),
"segment_count": len(data["segments"]),
}
finally:
session.close()
return result

111
backend/tests/fixtures/mock_llm_responses.py vendored
View file

@ -1,111 +0,0 @@
"""Mock LLM and embedding responses for pipeline integration tests.
Each response is a JSON string matching the Pydantic schema for that stage.
The sample transcript has 5 segments about gain staging, so mock responses
reflect that content.
"""
import json
import random
# ── Stage 2: Segmentation ───────────────────────────────────────────────────
STAGE2_SEGMENTATION_RESPONSE = json.dumps({
"segments": [
{
"start_index": 0,
"end_index": 1,
"topic_label": "Introduction",
"summary": "Introduces the episode about mixing basics and gain staging.",
},
{
"start_index": 2,
"end_index": 4,
"topic_label": "Gain Staging Technique",
"summary": "Covers practical steps for gain staging including setting levels and avoiding clipping.",
},
]
})
# ── Stage 3: Extraction ─────────────────────────────────────────────────────
STAGE3_EXTRACTION_RESPONSE = json.dumps({
"moments": [
{
"title": "Setting Levels for Gain Staging",
"summary": "Demonstrates the process of setting proper gain levels across the signal chain to maintain headroom.",
"start_time": 12.8,
"end_time": 28.5,
"content_type": "technique",
"plugins": ["Pro-Q 3"],
"raw_transcript": "First thing you want to do is set your levels. Make sure nothing is clipping on the master bus.",
},
{
"title": "Master Bus Clipping Prevention",
"summary": "Explains how to monitor and prevent clipping on the master bus during a mix session.",
"start_time": 20.1,
"end_time": 35.0,
"content_type": "settings",
"plugins": [],
"raw_transcript": "Make sure nothing is clipping on the master bus. That wraps up this quick overview.",
},
]
})
# ── Stage 4: Classification ─────────────────────────────────────────────────
STAGE4_CLASSIFICATION_RESPONSE = json.dumps({
"classifications": [
{
"moment_index": 0,
"topic_category": "Mixing",
"topic_tags": ["gain staging", "eq"],
"content_type_override": None,
},
{
"moment_index": 1,
"topic_category": "Mixing",
"topic_tags": ["gain staging", "bus processing"],
"content_type_override": None,
},
]
})
# ── Stage 5: Synthesis ───────────────────────────────────────────────────────
STAGE5_SYNTHESIS_RESPONSE = json.dumps({
"pages": [
{
"title": "Gain Staging in Mixing",
"slug": "gain-staging-in-mixing",
"topic_category": "Mixing",
"topic_tags": ["gain staging"],
"summary": "A comprehensive guide to gain staging in a mixing context, covering level setting and master bus management.",
"body_sections": {
"Overview": "Gain staging ensures each stage of the signal chain operates at optimal levels.",
"Steps": "1. Set input levels. 2. Check bus levels. 3. Monitor master output.",
},
"signal_chains": [
{"chain": "Input -> Channel Strip -> Bus -> Master", "notes": "Keep headroom at each stage."}
],
"plugins": ["Pro-Q 3"],
"source_quality": "structured",
}
]
})
# ── Embedding response ───────────────────────────────────────────────────────
def make_mock_embedding(dim: int = 768) -> list[float]:
"""Generate a deterministic-seeded mock embedding vector."""
rng = random.Random(42)
return [rng.uniform(-1, 1) for _ in range(dim)]
def make_mock_embeddings(n: int, dim: int = 768) -> list[list[float]]:
"""Generate n distinct mock embedding vectors."""
return [
[random.Random(42 + i).uniform(-1, 1) for _ in range(dim)]
for i in range(n)
]

12
backend/tests/fixtures/sample_transcript.json vendored
View file

@ -1,12 +0,0 @@
{
"source_file": "mixing-basics-ep1.mp4",
"creator_folder": "Skope",
"duration_seconds": 1234,
"segments": [
{"start": 0.0, "end": 5.2, "text": "Welcome to mixing basics episode one."},
{"start": 5.2, "end": 12.8, "text": "Today we are going to talk about gain staging."},
{"start": 12.8, "end": 20.1, "text": "First thing you want to do is set your levels."},
{"start": 20.1, "end": 28.5, "text": "Make sure nothing is clipping on the master bus."},
{"start": 28.5, "end": 35.0, "text": "That wraps up this quick overview of gain staging."}
]
}

179
backend/tests/test_ingest.py
View file

@ -1,179 +0,0 @@
"""Integration tests for the transcript ingest endpoint.
Tests run against a real PostgreSQL database via httpx.AsyncClient
on the FastAPI ASGI app. Each test gets a clean database state via
TRUNCATE in the client fixture (conftest.py).
"""
import json
import pathlib
import pytest
from httpx import AsyncClient
from sqlalchemy import func, select, text
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from models import Creator, SourceVideo, TranscriptSegment
# ── Helpers ──────────────────────────────────────────────────────────────────
INGEST_URL = "/api/v1/ingest"
def _upload_file(path: pathlib.Path):
"""Return a dict suitable for httpx multipart file upload."""
return {"file": (path.name, path.read_bytes(), "application/json")}
async def _query_db(db_engine, stmt):
"""Run a read query in its own session to avoid connection contention."""
session_factory = async_sessionmaker(
db_engine, class_=AsyncSession, expire_on_commit=False
)
async with session_factory() as session:
result = await session.execute(stmt)
return result
async def _count_rows(db_engine, model):
"""Count rows in a table via a fresh session."""
result = await _query_db(db_engine, select(func.count(model.id)))
return result.scalar_one()
# ── Happy-path tests ────────────────────────────────────────────────────────
async def test_ingest_creates_creator_and_video(client, sample_transcript_path, db_engine):
"""POST a valid transcript → 200 with creator, video, and 5 segments created."""
resp = await client.post(INGEST_URL, files=_upload_file(sample_transcript_path))
assert resp.status_code == 200, f"Expected 200, got {resp.status_code}: {resp.text}"
data = resp.json()
assert "video_id" in data
assert "creator_id" in data
assert data["segments_stored"] == 5
assert data["creator_name"] == "Skope"
assert data["is_reupload"] is False
# Verify DB state via a fresh session
session_factory = async_sessionmaker(db_engine, class_=AsyncSession, expire_on_commit=False)
async with session_factory() as session:
# Creator exists with correct folder_name and slug
result = await session.execute(
select(Creator).where(Creator.folder_name == "Skope")
)
creator = result.scalar_one()
assert creator.slug == "skope"
assert creator.name == "Skope"
# SourceVideo exists with correct status
result = await session.execute(
select(SourceVideo).where(SourceVideo.creator_id == creator.id)
)
video = result.scalar_one()
assert video.processing_status.value == "transcribed"
assert video.filename == "mixing-basics-ep1.mp4"
# 5 TranscriptSegment rows with sequential indices
result = await session.execute(
select(TranscriptSegment)
.where(TranscriptSegment.source_video_id == video.id)
.order_by(TranscriptSegment.segment_index)
)
segments = result.scalars().all()
assert len(segments) == 5
assert [s.segment_index for s in segments] == [0, 1, 2, 3, 4]
async def test_ingest_reuses_existing_creator(client, sample_transcript_path, db_engine):
"""If a Creator with the same folder_name already exists, reuse it."""
session_factory = async_sessionmaker(db_engine, class_=AsyncSession, expire_on_commit=False)
# Pre-create a Creator with folder_name='Skope' in a separate session
async with session_factory() as session:
existing = Creator(name="Skope", slug="skope", folder_name="Skope")
session.add(existing)
await session.commit()
await session.refresh(existing)
existing_id = existing.id
# POST transcript — should reuse the creator
resp = await client.post(INGEST_URL, files=_upload_file(sample_transcript_path))
assert resp.status_code == 200
data = resp.json()
assert data["creator_id"] == str(existing_id)
# Verify only 1 Creator row in DB
count = await _count_rows(db_engine, Creator)
assert count == 1, f"Expected 1 creator, got {count}"
async def test_ingest_idempotent_reupload(client, sample_transcript_path, db_engine):
"""Uploading the same transcript twice is idempotent: same video, no duplicate segments."""
# First upload
resp1 = await client.post(INGEST_URL, files=_upload_file(sample_transcript_path))
assert resp1.status_code == 200
data1 = resp1.json()
assert data1["is_reupload"] is False
video_id = data1["video_id"]
# Second upload (same file)
resp2 = await client.post(INGEST_URL, files=_upload_file(sample_transcript_path))
assert resp2.status_code == 200
data2 = resp2.json()
assert data2["is_reupload"] is True
assert data2["video_id"] == video_id
# Verify DB: still only 1 SourceVideo and 5 segments (not 10)
video_count = await _count_rows(db_engine, SourceVideo)
assert video_count == 1, f"Expected 1 video, got {video_count}"
seg_count = await _count_rows(db_engine, TranscriptSegment)
assert seg_count == 5, f"Expected 5 segments, got {seg_count}"
async def test_ingest_saves_json_to_disk(client, sample_transcript_path, tmp_path):
"""Ingested transcript raw JSON is persisted to the filesystem."""
resp = await client.post(INGEST_URL, files=_upload_file(sample_transcript_path))
assert resp.status_code == 200
# The ingest endpoint saves to {transcript_storage_path}/{creator_folder}/{source_file}.json
expected_path = tmp_path / "Skope" / "mixing-basics-ep1.mp4.json"
assert expected_path.exists(), f"Expected file at {expected_path}"
# Verify the saved JSON is valid and matches the source
saved = json.loads(expected_path.read_text())
source = json.loads(sample_transcript_path.read_text())
assert saved == source
# ── Error tests ──────────────────────────────────────────────────────────────
async def test_ingest_rejects_invalid_json(client, tmp_path):
"""Uploading a non-JSON file returns 422."""
bad_file = tmp_path / "bad.json"
bad_file.write_text("this is not valid json {{{")
resp = await client.post(
INGEST_URL,
files={"file": ("bad.json", bad_file.read_bytes(), "application/json")},
)
assert resp.status_code == 422, f"Expected 422, got {resp.status_code}: {resp.text}"
assert "JSON parse error" in resp.json()["detail"]
async def test_ingest_rejects_missing_fields(client, tmp_path):
"""Uploading JSON without required fields returns 422."""
incomplete = tmp_path / "incomplete.json"
# Missing creator_folder and segments
incomplete.write_text(json.dumps({"source_file": "test.mp4", "duration_seconds": 100}))
resp = await client.post(
INGEST_URL,
files={"file": ("incomplete.json", incomplete.read_bytes(), "application/json")},
)
assert resp.status_code == 422, f"Expected 422, got {resp.status_code}: {resp.text}"
assert "Missing required keys" in resp.json()["detail"]

773
backend/tests/test_pipeline.py
View file

@ -1,773 +0,0 @@
"""Integration tests for the LLM extraction pipeline.
Tests run against a real PostgreSQL test database with mocked LLM and Qdrant
clients. Pipeline stages are sync (Celery tasks), so tests call stage
functions directly with sync SQLAlchemy sessions.
Tests (a)–(f) call pipeline stages directly. Tests (g)–(i) use the async
HTTP client. Test (j) verifies LLM fallback logic.
"""
from __future__ import annotations
import json
import os
import pathlib
import uuid
from unittest.mock import MagicMock, patch, PropertyMock
import openai
import pytest
from sqlalchemy import create_engine, select
from sqlalchemy.orm import Session, sessionmaker
from sqlalchemy.pool import NullPool
from models import (
Creator,
KeyMoment,
KeyMomentContentType,
ProcessingStatus,
SourceVideo,
TechniquePage,
TranscriptSegment,
)
from pipeline.schemas import (
ClassificationResult,
ExtractionResult,
SegmentationResult,
SynthesisResult,
)
from tests.fixtures.mock_llm_responses import (
STAGE2_SEGMENTATION_RESPONSE,
STAGE3_EXTRACTION_RESPONSE,
STAGE4_CLASSIFICATION_RESPONSE,
STAGE5_SYNTHESIS_RESPONSE,
make_mock_embeddings,
)
# ── Test database URL ────────────────────────────────────────────────────────
TEST_DATABASE_URL_SYNC = os.getenv(
"TEST_DATABASE_URL",
"postgresql+asyncpg://chrysopedia:changeme@localhost:5433/chrysopedia_test",
).replace("postgresql+asyncpg://", "postgresql+psycopg2://")
# ── Helpers ──────────────────────────────────────────────────────────────────
def _make_mock_openai_response(content: str):
"""Build a mock OpenAI ChatCompletion response object."""
mock_message = MagicMock()
mock_message.content = content
mock_choice = MagicMock()
mock_choice.message = mock_message
mock_response = MagicMock()
mock_response.choices = [mock_choice]
return mock_response
def _make_mock_embedding_response(vectors: list[list[float]]):
"""Build a mock OpenAI Embedding response object."""
mock_items = []
for i, vec in enumerate(vectors):
item = MagicMock()
item.embedding = vec
item.index = i
mock_items.append(item)
mock_response = MagicMock()
mock_response.data = mock_items
return mock_response
def _patch_pipeline_engine(sync_engine):
"""Patch the pipeline.stages module to use the test sync engine/session."""
return [
patch("pipeline.stages._engine", sync_engine),
patch(
"pipeline.stages._SessionLocal",
sessionmaker(bind=sync_engine),
),
]
def _patch_llm_completions(side_effect_fn):
"""Patch openai.OpenAI so all instances share a mocked chat.completions.create."""
mock_client = MagicMock()
mock_client.chat.completions.create.side_effect = side_effect_fn
return patch("openai.OpenAI", return_value=mock_client)
def _create_canonical_tags_file(tmp_path: pathlib.Path) -> pathlib.Path:
"""Write a minimal canonical_tags.yaml for stage4 to load."""
config_dir = tmp_path / "config"
config_dir.mkdir(exist_ok=True)
tags_path = config_dir / "canonical_tags.yaml"
tags_path.write_text(
"categories:\n"
" - name: Mixing\n"
" description: Balancing and processing elements\n"
" sub_topics: [eq, compression, gain staging, bus processing]\n"
" - name: Sound design\n"
" description: Creating sounds\n"
" sub_topics: [bass, drums]\n"
)
return tags_path
# ── (a) Stage 2: Segmentation ───────────────────────────────────────────────
def test_stage2_segmentation_updates_topic_labels(
db_engine, sync_engine, pre_ingested_video, tmp_path
):
"""Stage 2 should update topic_label on each TranscriptSegment."""
video_id = pre_ingested_video["video_id"]
# Create prompts directory
prompts_dir = tmp_path / "prompts"
prompts_dir.mkdir()
(prompts_dir / "stage2_segmentation.txt").write_text("You are a segmentation assistant.")
# Build the mock LLM that returns the segmentation response
def llm_side_effect(**kwargs):
return _make_mock_openai_response(STAGE2_SEGMENTATION_RESPONSE)
patches = _patch_pipeline_engine(sync_engine)
for p in patches:
p.start()
with _patch_llm_completions(llm_side_effect), \
patch("pipeline.stages.get_settings") as mock_settings:
s = MagicMock()
s.prompts_path = str(prompts_dir)
s.llm_api_url = "http://mock:11434/v1"
s.llm_api_key = "sk-test"
s.llm_model = "test-model"
s.llm_fallback_url = "http://mock:11434/v1"
s.llm_fallback_model = "test-model"
s.database_url = TEST_DATABASE_URL_SYNC.replace("psycopg2", "asyncpg")
mock_settings.return_value = s
# Import and call stage directly (not via Celery)
from pipeline.stages import stage2_segmentation
result = stage2_segmentation(video_id)
assert result == video_id
for p in patches:
p.stop()
# Verify: check topic_label on segments
factory = sessionmaker(bind=sync_engine)
session = factory()
try:
segments = (
session.execute(
select(TranscriptSegment)
.where(TranscriptSegment.source_video_id == video_id)
.order_by(TranscriptSegment.segment_index)
)
.scalars()
.all()
)
# Segments 0,1 should have "Introduction", segments 2,3,4 should have "Gain Staging Technique"
assert segments[0].topic_label == "Introduction"
assert segments[1].topic_label == "Introduction"
assert segments[2].topic_label == "Gain Staging Technique"
assert segments[3].topic_label == "Gain Staging Technique"
assert segments[4].topic_label == "Gain Staging Technique"
finally:
session.close()
# ── (b) Stage 3: Extraction ─────────────────────────────────────────────────
def test_stage3_extraction_creates_key_moments(
db_engine, sync_engine, pre_ingested_video, tmp_path
):
"""Stages 2+3 should create KeyMoment rows and set processing_status=extracted."""
video_id = pre_ingested_video["video_id"]
prompts_dir = tmp_path / "prompts"
prompts_dir.mkdir()
(prompts_dir / "stage2_segmentation.txt").write_text("Segment assistant.")
(prompts_dir / "stage3_extraction.txt").write_text("Extraction assistant.")
call_count = {"n": 0}
responses = [STAGE2_SEGMENTATION_RESPONSE, STAGE3_EXTRACTION_RESPONSE, STAGE3_EXTRACTION_RESPONSE]
def llm_side_effect(**kwargs):
idx = min(call_count["n"], len(responses) - 1)
resp = responses[idx]
call_count["n"] += 1
return _make_mock_openai_response(resp)
patches = _patch_pipeline_engine(sync_engine)
for p in patches:
p.start()
with _patch_llm_completions(llm_side_effect), \
patch("pipeline.stages.get_settings") as mock_settings:
s = MagicMock()
s.prompts_path = str(prompts_dir)
s.llm_api_url = "http://mock:11434/v1"
s.llm_api_key = "sk-test"
s.llm_model = "test-model"
s.llm_fallback_url = "http://mock:11434/v1"
s.llm_fallback_model = "test-model"
s.database_url = TEST_DATABASE_URL_SYNC.replace("psycopg2", "asyncpg")
mock_settings.return_value = s
from pipeline.stages import stage2_segmentation, stage3_extraction
stage2_segmentation(video_id)
stage3_extraction(video_id)
for p in patches:
p.stop()
# Verify key moments created
factory = sessionmaker(bind=sync_engine)
session = factory()
try:
moments = (
session.execute(
select(KeyMoment)
.where(KeyMoment.source_video_id == video_id)
.order_by(KeyMoment.start_time)
)
.scalars()
.all()
)
# Two topic groups → extraction called twice → up to 4 moments
# (2 per group from the mock response)
assert len(moments) >= 2
assert moments[0].title == "Setting Levels for Gain Staging"
assert moments[0].content_type == KeyMomentContentType.technique
# Verify processing_status
video = session.execute(
select(SourceVideo).where(SourceVideo.id == video_id)
).scalar_one()
assert video.processing_status == ProcessingStatus.extracted
finally:
session.close()
# ── (c) Stage 4: Classification ─────────────────────────────────────────────
def test_stage4_classification_assigns_tags(
db_engine, sync_engine, pre_ingested_video, tmp_path
):
"""Stages 2+3+4 should store classification data in Redis."""
video_id = pre_ingested_video["video_id"]
prompts_dir = tmp_path / "prompts"
prompts_dir.mkdir()
(prompts_dir / "stage2_segmentation.txt").write_text("Segment assistant.")
(prompts_dir / "stage3_extraction.txt").write_text("Extraction assistant.")
(prompts_dir / "stage4_classification.txt").write_text("Classification assistant.")
_create_canonical_tags_file(tmp_path)
call_count = {"n": 0}
responses = [
STAGE2_SEGMENTATION_RESPONSE,
STAGE3_EXTRACTION_RESPONSE,
STAGE3_EXTRACTION_RESPONSE,
STAGE4_CLASSIFICATION_RESPONSE,
]
def llm_side_effect(**kwargs):
idx = min(call_count["n"], len(responses) - 1)
resp = responses[idx]
call_count["n"] += 1
return _make_mock_openai_response(resp)
patches = _patch_pipeline_engine(sync_engine)
for p in patches:
p.start()
stored_cls_data = {}
def mock_store_classification(vid, data):
stored_cls_data[vid] = data
with _patch_llm_completions(llm_side_effect), \
patch("pipeline.stages.get_settings") as mock_settings, \
patch("pipeline.stages._load_canonical_tags") as mock_tags, \
patch("pipeline.stages._store_classification_data", side_effect=mock_store_classification):
s = MagicMock()
s.prompts_path = str(prompts_dir)
s.llm_api_url = "http://mock:11434/v1"
s.llm_api_key = "sk-test"
s.llm_model = "test-model"
s.llm_fallback_url = "http://mock:11434/v1"
s.llm_fallback_model = "test-model"
s.database_url = TEST_DATABASE_URL_SYNC.replace("psycopg2", "asyncpg")
s.review_mode = True
mock_settings.return_value = s
mock_tags.return_value = {
"categories": [
{"name": "Mixing", "description": "Balancing", "sub_topics": ["gain staging", "eq"]},
]
}
from pipeline.stages import stage2_segmentation, stage3_extraction, stage4_classification
stage2_segmentation(video_id)
stage3_extraction(video_id)
stage4_classification(video_id)
for p in patches:
p.stop()
# Verify classification data was stored
assert video_id in stored_cls_data
cls_data = stored_cls_data[video_id]
assert len(cls_data) >= 1
assert cls_data[0]["topic_category"] == "Mixing"
assert "gain staging" in cls_data[0]["topic_tags"]
# ── (d) Stage 5: Synthesis ──────────────────────────────────────────────────
def test_stage5_synthesis_creates_technique_pages(
db_engine, sync_engine, pre_ingested_video, tmp_path
):
"""Full pipeline stages 2-5 should create TechniquePage rows linked to KeyMoments."""
video_id = pre_ingested_video["video_id"]
prompts_dir = tmp_path / "prompts"
prompts_dir.mkdir()
(prompts_dir / "stage2_segmentation.txt").write_text("Segment assistant.")
(prompts_dir / "stage3_extraction.txt").write_text("Extraction assistant.")
(prompts_dir / "stage4_classification.txt").write_text("Classification assistant.")
(prompts_dir / "stage5_synthesis.txt").write_text("Synthesis assistant.")
call_count = {"n": 0}
responses = [
STAGE2_SEGMENTATION_RESPONSE,
STAGE3_EXTRACTION_RESPONSE,
STAGE3_EXTRACTION_RESPONSE,
STAGE4_CLASSIFICATION_RESPONSE,
STAGE5_SYNTHESIS_RESPONSE,
]
def llm_side_effect(**kwargs):
idx = min(call_count["n"], len(responses) - 1)
resp = responses[idx]
call_count["n"] += 1
return _make_mock_openai_response(resp)
patches = _patch_pipeline_engine(sync_engine)
for p in patches:
p.start()
# Mock classification data in Redis (simulate stage 4 having stored it)
mock_cls_data = [
{"moment_id": "will-be-replaced", "topic_category": "Mixing", "topic_tags": ["gain staging"]},
]
with _patch_llm_completions(llm_side_effect), \
patch("pipeline.stages.get_settings") as mock_settings, \
patch("pipeline.stages._load_canonical_tags") as mock_tags, \
patch("pipeline.stages._store_classification_data"), \
patch("pipeline.stages._load_classification_data") as mock_load_cls:
s = MagicMock()
s.prompts_path = str(prompts_dir)
s.llm_api_url = "http://mock:11434/v1"
s.llm_api_key = "sk-test"
s.llm_model = "test-model"
s.llm_fallback_url = "http://mock:11434/v1"
s.llm_fallback_model = "test-model"
s.database_url = TEST_DATABASE_URL_SYNC.replace("psycopg2", "asyncpg")
s.review_mode = True
mock_settings.return_value = s
mock_tags.return_value = {
"categories": [
{"name": "Mixing", "description": "Balancing", "sub_topics": ["gain staging"]},
]
}
from pipeline.stages import (
stage2_segmentation,
stage3_extraction,
stage4_classification,
stage5_synthesis,
)
stage2_segmentation(video_id)
stage3_extraction(video_id)
stage4_classification(video_id)
# Now set up mock_load_cls to return data with real moment IDs
factory = sessionmaker(bind=sync_engine)
sess = factory()
real_moments = (
sess.execute(
select(KeyMoment).where(KeyMoment.source_video_id == video_id)
)
.scalars()
.all()
)
real_cls = [
{"moment_id": str(m.id), "topic_category": "Mixing", "topic_tags": ["gain staging"]}
for m in real_moments
]
sess.close()
mock_load_cls.return_value = real_cls
stage5_synthesis(video_id)
for p in patches:
p.stop()
# Verify TechniquePages created
factory = sessionmaker(bind=sync_engine)
session = factory()
try:
pages = session.execute(select(TechniquePage)).scalars().all()
assert len(pages) >= 1
page = pages[0]
assert page.title == "Gain Staging in Mixing"
assert page.body_sections is not None
assert "Overview" in page.body_sections
assert page.signal_chains is not None
assert len(page.signal_chains) >= 1
assert page.summary is not None
# Verify KeyMoments are linked to the TechniquePage
moments = (
session.execute(
select(KeyMoment).where(KeyMoment.technique_page_id == page.id)
)
.scalars()
.all()
)
assert len(moments) >= 1
# Verify processing_status updated
video = session.execute(
select(SourceVideo).where(SourceVideo.id == video_id)
).scalar_one()
assert video.processing_status == ProcessingStatus.reviewed
finally:
session.close()
# ── (e) Stage 6: Embed & Index ──────────────────────────────────────────────
def test_stage6_embeds_and_upserts_to_qdrant(
db_engine, sync_engine, pre_ingested_video, tmp_path
):
"""Full pipeline through stage 6 should call EmbeddingClient and QdrantManager."""
video_id = pre_ingested_video["video_id"]
prompts_dir = tmp_path / "prompts"
prompts_dir.mkdir()
(prompts_dir / "stage2_segmentation.txt").write_text("Segment assistant.")
(prompts_dir / "stage3_extraction.txt").write_text("Extraction assistant.")
(prompts_dir / "stage4_classification.txt").write_text("Classification assistant.")
(prompts_dir / "stage5_synthesis.txt").write_text("Synthesis assistant.")
call_count = {"n": 0}
responses = [
STAGE2_SEGMENTATION_RESPONSE,
STAGE3_EXTRACTION_RESPONSE,
STAGE3_EXTRACTION_RESPONSE,
STAGE4_CLASSIFICATION_RESPONSE,
STAGE5_SYNTHESIS_RESPONSE,
]
def llm_side_effect(**kwargs):
idx = min(call_count["n"], len(responses) - 1)
resp = responses[idx]
call_count["n"] += 1
return _make_mock_openai_response(resp)
patches = _patch_pipeline_engine(sync_engine)
for p in patches:
p.start()
mock_embed_client = MagicMock()
mock_embed_client.embed.side_effect = lambda texts: make_mock_embeddings(len(texts))
mock_qdrant_mgr = MagicMock()
with _patch_llm_completions(llm_side_effect), \
patch("pipeline.stages.get_settings") as mock_settings, \
patch("pipeline.stages._load_canonical_tags") as mock_tags, \
patch("pipeline.stages._store_classification_data"), \
patch("pipeline.stages._load_classification_data") as mock_load_cls, \
patch("pipeline.stages.EmbeddingClient", return_value=mock_embed_client), \
patch("pipeline.stages.QdrantManager", return_value=mock_qdrant_mgr):
s = MagicMock()
s.prompts_path = str(prompts_dir)
s.llm_api_url = "http://mock:11434/v1"
s.llm_api_key = "sk-test"
s.llm_model = "test-model"
s.llm_fallback_url = "http://mock:11434/v1"
s.llm_fallback_model = "test-model"
s.database_url = TEST_DATABASE_URL_SYNC.replace("psycopg2", "asyncpg")
s.review_mode = True
s.embedding_api_url = "http://mock:11434/v1"
s.embedding_model = "test-embed"
s.embedding_dimensions = 768
s.qdrant_url = "http://mock:6333"
s.qdrant_collection = "test_collection"
mock_settings.return_value = s
mock_tags.return_value = {
"categories": [
{"name": "Mixing", "description": "Balancing", "sub_topics": ["gain staging"]},
]
}
from pipeline.stages import (
stage2_segmentation,
stage3_extraction,
stage4_classification,
stage5_synthesis,
stage6_embed_and_index,
)
stage2_segmentation(video_id)
stage3_extraction(video_id)
stage4_classification(video_id)
# Load real moment IDs for classification data mock
factory = sessionmaker(bind=sync_engine)
sess = factory()
real_moments = (
sess.execute(
select(KeyMoment).where(KeyMoment.source_video_id == video_id)
)
.scalars()
.all()
)
real_cls = [
{"moment_id": str(m.id), "topic_category": "Mixing", "topic_tags": ["gain staging"]}
for m in real_moments
]
sess.close()
mock_load_cls.return_value = real_cls
stage5_synthesis(video_id)
stage6_embed_and_index(video_id)
for p in patches:
p.stop()
# Verify EmbeddingClient.embed was called
assert mock_embed_client.embed.called
# Verify QdrantManager methods called
mock_qdrant_mgr.ensure_collection.assert_called_once()
assert (
mock_qdrant_mgr.upsert_technique_pages.called
or mock_qdrant_mgr.upsert_key_moments.called
), "Expected at least one upsert call to QdrantManager"
# ── (f) Resumability ────────────────────────────────────────────────────────
def test_run_pipeline_resumes_from_extracted(
db_engine, sync_engine, pre_ingested_video, tmp_path
):
"""When status=extracted, run_pipeline should skip stages 2+3 and run 4+5+6."""
video_id = pre_ingested_video["video_id"]
# Set video status to "extracted" directly
factory = sessionmaker(bind=sync_engine)
session = factory()
video = session.execute(
select(SourceVideo).where(SourceVideo.id == video_id)
).scalar_one()
video.processing_status = ProcessingStatus.extracted
session.commit()
session.close()
patches = _patch_pipeline_engine(sync_engine)
for p in patches:
p.start()
with patch("pipeline.stages.get_settings") as mock_settings, \
patch("pipeline.stages.stage2_segmentation") as mock_s2, \
patch("pipeline.stages.stage3_extraction") as mock_s3, \
patch("pipeline.stages.stage4_classification") as mock_s4, \
patch("pipeline.stages.stage5_synthesis") as mock_s5, \
patch("pipeline.stages.stage6_embed_and_index") as mock_s6, \
patch("pipeline.stages.celery_chain") as mock_chain:
s = MagicMock()
s.database_url = TEST_DATABASE_URL_SYNC.replace("psycopg2", "asyncpg")
mock_settings.return_value = s
# Mock chain to inspect what stages it gets
mock_pipeline = MagicMock()
mock_chain.return_value = mock_pipeline
# Mock the .s() method on each task
mock_s2.s = MagicMock(return_value="s2_sig")
mock_s3.s = MagicMock(return_value="s3_sig")
mock_s4.s = MagicMock(return_value="s4_sig")
mock_s5.s = MagicMock(return_value="s5_sig")
mock_s6.s = MagicMock(return_value="s6_sig")
from pipeline.stages import run_pipeline
run_pipeline(video_id)
# Verify: stages 2 and 3 should NOT have .s() called with video_id
mock_s2.s.assert_not_called()
mock_s3.s.assert_not_called()
# Stages 4, 5, 6 should have .s() called
mock_s4.s.assert_called_once_with(video_id)
mock_s5.s.assert_called_once()
mock_s6.s.assert_called_once()
for p in patches:
p.stop()
# ── (g) Pipeline trigger endpoint ───────────────────────────────────────────
async def test_pipeline_trigger_endpoint(client, db_engine):
"""POST /api/v1/pipeline/trigger/{video_id} with valid video returns 200."""
# Ingest a transcript first to create a video
sample = pathlib.Path(__file__).parent / "fixtures" / "sample_transcript.json"
with patch("routers.ingest.run_pipeline", create=True) as mock_rp:
mock_rp.delay = MagicMock()
resp = await client.post(
"/api/v1/ingest",
files={"file": (sample.name, sample.read_bytes(), "application/json")},
)
assert resp.status_code == 200
video_id = resp.json()["video_id"]
# Trigger the pipeline
with patch("pipeline.stages.run_pipeline") as mock_rp:
mock_rp.delay = MagicMock()
resp = await client.post(f"/api/v1/pipeline/trigger/{video_id}")
assert resp.status_code == 200
data = resp.json()
assert data["status"] == "triggered"
assert data["video_id"] == video_id
# ── (h) Pipeline trigger 404 ────────────────────────────────────────────────
async def test_pipeline_trigger_404_for_missing_video(client):
"""POST /api/v1/pipeline/trigger/{nonexistent} returns 404."""
fake_id = str(uuid.uuid4())
resp = await client.post(f"/api/v1/pipeline/trigger/{fake_id}")
assert resp.status_code == 404
assert "not found" in resp.json()["detail"].lower()
# ── (i) Ingest dispatches pipeline ──────────────────────────────────────────
async def test_ingest_dispatches_pipeline(client, db_engine):
"""Ingesting a transcript should call run_pipeline.delay with the video_id."""
sample = pathlib.Path(__file__).parent / "fixtures" / "sample_transcript.json"
with patch("pipeline.stages.run_pipeline") as mock_rp:
mock_rp.delay = MagicMock()
resp = await client.post(
"/api/v1/ingest",
files={"file": (sample.name, sample.read_bytes(), "application/json")},
)
assert resp.status_code == 200
video_id = resp.json()["video_id"]
mock_rp.delay.assert_called_once_with(video_id)
# ── (j) LLM fallback on primary failure ─────────────────────────────────────
def test_llm_fallback_on_primary_failure():
"""LLMClient should fall back to secondary endpoint when primary raises APIConnectionError."""
from pipeline.llm_client import LLMClient
settings = MagicMock()
settings.llm_api_url = "http://primary:11434/v1"
settings.llm_api_key = "sk-test"
settings.llm_fallback_url = "http://fallback:11434/v1"
settings.llm_fallback_model = "fallback-model"
settings.llm_model = "primary-model"
with patch("openai.OpenAI") as MockOpenAI:
primary_client = MagicMock()
fallback_client = MagicMock()
# First call → primary, second call → fallback
MockOpenAI.side_effect = [primary_client, fallback_client]
client = LLMClient(settings)
# Primary raises APIConnectionError
primary_client.chat.completions.create.side_effect = openai.APIConnectionError(
request=MagicMock()
)
# Fallback succeeds
fallback_response = _make_mock_openai_response('{"result": "ok"}')
fallback_client.chat.completions.create.return_value = fallback_response
result = client.complete("system", "user")
assert result == '{"result": "ok"}'
primary_client.chat.completions.create.assert_called_once()
fallback_client.chat.completions.create.assert_called_once()
# ── Think-tag stripping ─────────────────────────────────────────────────────
def test_strip_think_tags():
"""strip_think_tags should handle all edge cases correctly."""
from pipeline.llm_client import strip_think_tags
# Single block with JSON after
assert strip_think_tags('<think>reasoning here</think>{"a": 1}') == '{"a": 1}'
# Multiline think block
assert strip_think_tags(
'<think>\nI need to analyze this.\nLet me think step by step.\n</think>\n{"result": "ok"}'
) == '{"result": "ok"}'
# Multiple think blocks
result = strip_think_tags('<think>first</think>hello<think>second</think> world')
assert result == "hello world"
# No think tags — passthrough
assert strip_think_tags('{"clean": true}') == '{"clean": true}'
# Empty string
assert strip_think_tags("") == ""
# Think block with special characters
assert strip_think_tags(
'<think>analyzing "complex" <data> & stuff</think>{"done": true}'
) == '{"done": true}'
# Only a think block, no actual content
assert strip_think_tags("<think>just thinking</think>") == ""

526
backend/tests/test_public_api.py
View file

@ -1,526 +0,0 @@
"""Integration tests for the public S05 API endpoints:
techniques, topics, and enhanced creators.
Tests run against a real PostgreSQL test database via httpx.AsyncClient.
"""
from __future__ import annotations
import uuid
import pytest
import pytest_asyncio
from httpx import AsyncClient
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from models import (
ContentType,
Creator,
KeyMoment,
KeyMomentContentType,
ProcessingStatus,
RelatedTechniqueLink,
RelationshipType,
SourceVideo,
TechniquePage,
)
TECHNIQUES_URL = "/api/v1/techniques"
TOPICS_URL = "/api/v1/topics"
CREATORS_URL = "/api/v1/creators"
# ── Seed helpers ─────────────────────────────────────────────────────────────
async def _seed_full_data(db_engine) -> dict:
"""Seed 2 creators, 2 videos, 3 technique pages, key moments, and a related link.
Returns a dict of IDs and metadata for assertions.
"""
session_factory = async_sessionmaker(
db_engine, class_=AsyncSession, expire_on_commit=False
)
async with session_factory() as session:
# Creators
creator1 = Creator(
name="Alpha Creator",
slug="alpha-creator",
genres=["Bass music", "Dubstep"],
folder_name="AlphaCreator",
)
creator2 = Creator(
name="Beta Producer",
slug="beta-producer",
genres=["House", "Techno"],
folder_name="BetaProducer",
)
session.add_all([creator1, creator2])
await session.flush()
# Videos
video1 = SourceVideo(
creator_id=creator1.id,
filename="bass-tutorial.mp4",
file_path="AlphaCreator/bass-tutorial.mp4",
duration_seconds=600,
content_type=ContentType.tutorial,
processing_status=ProcessingStatus.extracted,
)
video2 = SourceVideo(
creator_id=creator2.id,
filename="mixing-masterclass.mp4",
file_path="BetaProducer/mixing-masterclass.mp4",
duration_seconds=1200,
content_type=ContentType.tutorial,
processing_status=ProcessingStatus.extracted,
)
session.add_all([video1, video2])
await session.flush()
# Technique pages
tp1 = TechniquePage(
creator_id=creator1.id,
title="Reese Bass Design",
slug="reese-bass-design",
topic_category="Sound design",
topic_tags=["bass", "textures"],
summary="Classic reese bass creation",
body_sections={"intro": "Getting started with reese bass"},
)
tp2 = TechniquePage(
creator_id=creator2.id,
title="Granular Pad Textures",
slug="granular-pad-textures",
topic_category="Synthesis",
topic_tags=["granular", "pads"],
summary="Creating evolving pad textures",
)
tp3 = TechniquePage(
creator_id=creator1.id,
title="FM Bass Layering",
slug="fm-bass-layering",
topic_category="Synthesis",
topic_tags=["fm", "bass"],
summary="FM synthesis for bass layers",
)
session.add_all([tp1, tp2, tp3])
await session.flush()
# Key moments
km1 = KeyMoment(
source_video_id=video1.id,
technique_page_id=tp1.id,
title="Oscillator setup",
summary="Setting up the initial oscillator",
start_time=10.0,
end_time=60.0,
content_type=KeyMomentContentType.technique,
)
km2 = KeyMoment(
source_video_id=video1.id,
technique_page_id=tp1.id,
title="Distortion chain",
summary="Adding distortion to the reese",
start_time=60.0,
end_time=120.0,
content_type=KeyMomentContentType.technique,
)
km3 = KeyMoment(
source_video_id=video2.id,
technique_page_id=tp2.id,
title="Granular engine parameters",
summary="Configuring the granular engine",
start_time=20.0,
end_time=80.0,
content_type=KeyMomentContentType.settings,
)
session.add_all([km1, km2, km3])
await session.flush()
# Related technique link: tp1 → tp3 (same_creator_adjacent)
link = RelatedTechniqueLink(
source_page_id=tp1.id,
target_page_id=tp3.id,
relationship=RelationshipType.same_creator_adjacent,
)
session.add(link)
await session.commit()
return {
"creator1_id": str(creator1.id),
"creator1_name": creator1.name,
"creator1_slug": creator1.slug,
"creator2_id": str(creator2.id),
"creator2_name": creator2.name,
"creator2_slug": creator2.slug,
"video1_id": str(video1.id),
"video2_id": str(video2.id),
"tp1_slug": tp1.slug,
"tp1_title": tp1.title,
"tp2_slug": tp2.slug,
"tp3_slug": tp3.slug,
"tp3_title": tp3.title,
}
# ── Technique Tests ──────────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_list_techniques(client, db_engine):
"""GET /techniques returns a paginated list of technique pages."""
seed = await _seed_full_data(db_engine)
resp = await client.get(TECHNIQUES_URL)
assert resp.status_code == 200
data = resp.json()
assert data["total"] == 3
assert len(data["items"]) == 3
# Each item has required fields
slugs = {item["slug"] for item in data["items"]}
assert seed["tp1_slug"] in slugs
assert seed["tp2_slug"] in slugs
assert seed["tp3_slug"] in slugs
@pytest.mark.asyncio
async def test_list_techniques_with_category_filter(client, db_engine):
"""GET /techniques?category=Synthesis returns only Synthesis technique pages."""
await _seed_full_data(db_engine)
resp = await client.get(TECHNIQUES_URL, params={"category": "Synthesis"})
assert resp.status_code == 200
data = resp.json()
assert data["total"] == 2
for item in data["items"]:
assert item["topic_category"] == "Synthesis"
@pytest.mark.asyncio
async def test_get_technique_detail(client, db_engine):
"""GET /techniques/{slug} returns full detail with key_moments, creator_info, and related_links."""
seed = await _seed_full_data(db_engine)
resp = await client.get(f"{TECHNIQUES_URL}/{seed['tp1_slug']}")
assert resp.status_code == 200
data = resp.json()
assert data["title"] == seed["tp1_title"]
assert data["slug"] == seed["tp1_slug"]
assert data["topic_category"] == "Sound design"
# Key moments: tp1 has 2 key moments
assert len(data["key_moments"]) == 2
km_titles = {km["title"] for km in data["key_moments"]}
assert "Oscillator setup" in km_titles
assert "Distortion chain" in km_titles
# Creator info
assert data["creator_info"] is not None
assert data["creator_info"]["name"] == seed["creator1_name"]
assert data["creator_info"]["slug"] == seed["creator1_slug"]
# Related links: tp1 → tp3 (same_creator_adjacent)
assert len(data["related_links"]) >= 1
related_slugs = {link["target_slug"] for link in data["related_links"]}
assert seed["tp3_slug"] in related_slugs
@pytest.mark.asyncio
async def test_get_technique_invalid_slug_returns_404(client, db_engine):
"""GET /techniques/{invalid-slug} returns 404."""
await _seed_full_data(db_engine)
resp = await client.get(f"{TECHNIQUES_URL}/nonexistent-slug-xyz")
assert resp.status_code == 404
assert "not found" in resp.json()["detail"].lower()
# ── Topics Tests ─────────────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_list_topics_hierarchy(client, db_engine):
"""GET /topics returns category hierarchy with counts matching seeded data."""
await _seed_full_data(db_engine)
resp = await client.get(TOPICS_URL)
assert resp.status_code == 200
data = resp.json()
# Should have the 6 categories from canonical_tags.yaml
assert len(data) == 6
category_names = {cat["name"] for cat in data}
assert "Sound design" in category_names
assert "Synthesis" in category_names
assert "Mixing" in category_names
# Check Sound design category — should have "bass" sub-topic with count
sound_design = next(c for c in data if c["name"] == "Sound design")
bass_sub = next(
(st for st in sound_design["sub_topics"] if st["name"] == "bass"), None
)
assert bass_sub is not None
# tp1 (tags: ["bass", "textures"]) and tp3 (tags: ["fm", "bass"]) both have "bass"
assert bass_sub["technique_count"] == 2
# Both from creator1
assert bass_sub["creator_count"] == 1
# Check Synthesis category — "granular" sub-topic
synthesis = next(c for c in data if c["name"] == "Synthesis")
granular_sub = next(
(st for st in synthesis["sub_topics"] if st["name"] == "granular"), None
)
assert granular_sub is not None
assert granular_sub["technique_count"] == 1
assert granular_sub["creator_count"] == 1
@pytest.mark.asyncio
async def test_topics_with_no_technique_pages(client, db_engine):
"""GET /topics with no seeded data returns categories with zero counts."""
# No data seeded — just use the clean DB
resp = await client.get(TOPICS_URL)
assert resp.status_code == 200
data = resp.json()
assert len(data) == 6
# All sub-topic counts should be zero
for category in data:
for st in category["sub_topics"]:
assert st["technique_count"] == 0
assert st["creator_count"] == 0
# ── Creator Tests ────────────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_list_creators_random_sort(client, db_engine):
"""GET /creators?sort=random returns all creators (order may vary)."""
seed = await _seed_full_data(db_engine)
resp = await client.get(CREATORS_URL, params={"sort": "random"})
assert resp.status_code == 200
data = resp.json()
assert len(data) == 2
names = {item["name"] for item in data}
assert seed["creator1_name"] in names
assert seed["creator2_name"] in names
# Each item has technique_count and video_count
for item in data:
assert "technique_count" in item
assert "video_count" in item
@pytest.mark.asyncio
async def test_list_creators_alpha_sort(client, db_engine):
"""GET /creators?sort=alpha returns creators in alphabetical order."""
seed = await _seed_full_data(db_engine)
resp = await client.get(CREATORS_URL, params={"sort": "alpha"})
assert resp.status_code == 200
data = resp.json()
assert len(data) == 2
# "Alpha Creator" < "Beta Producer" alphabetically
assert data[0]["name"] == "Alpha Creator"
assert data[1]["name"] == "Beta Producer"
@pytest.mark.asyncio
async def test_list_creators_genre_filter(client, db_engine):
"""GET /creators?genre=Bass+music returns only matching creators."""
seed = await _seed_full_data(db_engine)
resp = await client.get(CREATORS_URL, params={"genre": "Bass music"})
assert resp.status_code == 200
data = resp.json()
assert len(data) == 1
assert data[0]["name"] == seed["creator1_name"]
assert data[0]["slug"] == seed["creator1_slug"]
@pytest.mark.asyncio
async def test_get_creator_detail(client, db_engine):
"""GET /creators/{slug} returns detail with video_count."""
seed = await _seed_full_data(db_engine)
resp = await client.get(f"{CREATORS_URL}/{seed['creator1_slug']}")
assert resp.status_code == 200
data = resp.json()
assert data["name"] == seed["creator1_name"]
assert data["slug"] == seed["creator1_slug"]
assert data["video_count"] == 1 # creator1 has 1 video
@pytest.mark.asyncio
async def test_get_creator_invalid_slug_returns_404(client, db_engine):
"""GET /creators/{invalid-slug} returns 404."""
await _seed_full_data(db_engine)
resp = await client.get(f"{CREATORS_URL}/nonexistent-creator-xyz")
assert resp.status_code == 404
@pytest.mark.asyncio
async def test_creators_with_counts(client, db_engine):
"""GET /creators returns correct technique_count and video_count."""
seed = await _seed_full_data(db_engine)
resp = await client.get(CREATORS_URL, params={"sort": "alpha"})
assert resp.status_code == 200
data = resp.json()
# Alpha Creator: 2 technique pages, 1 video
alpha = data[0]
assert alpha["name"] == "Alpha Creator"
assert alpha["technique_count"] == 2
assert alpha["video_count"] == 1
# Beta Producer: 1 technique page, 1 video
beta = data[1]
assert beta["name"] == "Beta Producer"
assert beta["technique_count"] == 1
assert beta["video_count"] == 1
@pytest.mark.asyncio
async def test_creators_empty_list(client, db_engine):
"""GET /creators with no creators returns empty list."""
# No data seeded
resp = await client.get(CREATORS_URL)
assert resp.status_code == 200
data = resp.json()
assert data == []
# ── Version Tests ────────────────────────────────────────────────────────────
async def _insert_version(db_engine, technique_page_id: str, version_number: int, content_snapshot: dict, pipeline_metadata: dict | None = None):
"""Insert a TechniquePageVersion row directly for testing."""
from models import TechniquePageVersion
session_factory = async_sessionmaker(
db_engine, class_=AsyncSession, expire_on_commit=False
)
async with session_factory() as session:
v = TechniquePageVersion(
technique_page_id=uuid.UUID(technique_page_id) if isinstance(technique_page_id, str) else technique_page_id,
version_number=version_number,
content_snapshot=content_snapshot,
pipeline_metadata=pipeline_metadata,
)
session.add(v)
await session.commit()
@pytest.mark.asyncio
async def test_version_list_empty(client, db_engine):
"""GET /techniques/{slug}/versions returns empty list when page has no versions."""
seed = await _seed_full_data(db_engine)
resp = await client.get(f"{TECHNIQUES_URL}/{seed['tp1_slug']}/versions")
assert resp.status_code == 200
data = resp.json()
assert data["items"] == []
assert data["total"] == 0
@pytest.mark.asyncio
async def test_version_list_with_versions(client, db_engine):
"""GET /techniques/{slug}/versions returns versions after inserting them."""
seed = await _seed_full_data(db_engine)
# Get the technique page ID by fetching the detail
detail_resp = await client.get(f"{TECHNIQUES_URL}/{seed['tp1_slug']}")
page_id = detail_resp.json()["id"]
# Insert two versions
snapshot1 = {"title": "Old Reese Bass v1", "summary": "First draft"}
snapshot2 = {"title": "Old Reese Bass v2", "summary": "Second draft"}
await _insert_version(db_engine, page_id, 1, snapshot1, {"model": "gpt-4o"})
await _insert_version(db_engine, page_id, 2, snapshot2, {"model": "gpt-4o-mini"})
resp = await client.get(f"{TECHNIQUES_URL}/{seed['tp1_slug']}/versions")
assert resp.status_code == 200
data = resp.json()
assert data["total"] == 2
assert len(data["items"]) == 2
# Ordered by version_number DESC
assert data["items"][0]["version_number"] == 2
assert data["items"][1]["version_number"] == 1
assert data["items"][0]["pipeline_metadata"]["model"] == "gpt-4o-mini"
assert data["items"][1]["pipeline_metadata"]["model"] == "gpt-4o"
@pytest.mark.asyncio
async def test_version_detail_returns_content_snapshot(client, db_engine):
"""GET /techniques/{slug}/versions/{version_number} returns full snapshot."""
seed = await _seed_full_data(db_engine)
detail_resp = await client.get(f"{TECHNIQUES_URL}/{seed['tp1_slug']}")
page_id = detail_resp.json()["id"]
snapshot = {"title": "Old Title", "summary": "Old summary", "body_sections": {"intro": "Old intro"}}
metadata = {"model": "gpt-4o", "prompt_hash": "abc123"}
await _insert_version(db_engine, page_id, 1, snapshot, metadata)
resp = await client.get(f"{TECHNIQUES_URL}/{seed['tp1_slug']}/versions/1")
assert resp.status_code == 200
data = resp.json()
assert data["version_number"] == 1
assert data["content_snapshot"] == snapshot
assert data["pipeline_metadata"] == metadata
assert "created_at" in data
@pytest.mark.asyncio
async def test_version_detail_404_for_nonexistent_version(client, db_engine):
"""GET /techniques/{slug}/versions/999 returns 404."""
seed = await _seed_full_data(db_engine)
resp = await client.get(f"{TECHNIQUES_URL}/{seed['tp1_slug']}/versions/999")
assert resp.status_code == 404
assert "not found" in resp.json()["detail"].lower()
@pytest.mark.asyncio
async def test_versions_404_for_nonexistent_slug(client, db_engine):
"""GET /techniques/nonexistent-slug/versions returns 404."""
await _seed_full_data(db_engine)
resp = await client.get(f"{TECHNIQUES_URL}/nonexistent-slug-xyz/versions")
assert resp.status_code == 404
assert "not found" in resp.json()["detail"].lower()
@pytest.mark.asyncio
async def test_technique_detail_includes_version_count(client, db_engine):
"""GET /techniques/{slug} includes version_count field."""
seed = await _seed_full_data(db_engine)
# Initially version_count should be 0
resp = await client.get(f"{TECHNIQUES_URL}/{seed['tp1_slug']}")
assert resp.status_code == 200
data = resp.json()
assert data["version_count"] == 0
# Insert a version and check again
page_id = data["id"]
await _insert_version(db_engine, page_id, 1, {"title": "Snapshot"})
resp2 = await client.get(f"{TECHNIQUES_URL}/{seed['tp1_slug']}")
assert resp2.status_code == 200
assert resp2.json()["version_count"] == 1

495
backend/tests/test_review.py
View file

@ -1,495 +0,0 @@
"""Integration tests for the review queue endpoints.
Tests run against a real PostgreSQL test database via httpx.AsyncClient.
Redis is mocked for mode toggle tests.
"""
import uuid
from unittest.mock import AsyncMock, patch
import pytest
import pytest_asyncio
from httpx import AsyncClient
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from models import (
ContentType,
Creator,
KeyMoment,
KeyMomentContentType,
ProcessingStatus,
ReviewStatus,
SourceVideo,
)
# ── Helpers ──────────────────────────────────────────────────────────────────
QUEUE_URL = "/api/v1/review/queue"
STATS_URL = "/api/v1/review/stats"
MODE_URL = "/api/v1/review/mode"
def _moment_url(moment_id: str, action: str = "") -> str:
"""Build a moment action URL."""
base = f"/api/v1/review/moments/{moment_id}"
return f"{base}/{action}" if action else base
async def _seed_creator_and_video(db_engine) -> dict:
"""Seed a creator and source video, return their IDs."""
session_factory = async_sessionmaker(
db_engine, class_=AsyncSession, expire_on_commit=False
)
async with session_factory() as session:
creator = Creator(
name="TestCreator",
slug="test-creator",
folder_name="TestCreator",
)
session.add(creator)
await session.flush()
video = SourceVideo(
creator_id=creator.id,
filename="test-video.mp4",
file_path="TestCreator/test-video.mp4",
duration_seconds=600,
content_type=ContentType.tutorial,
processing_status=ProcessingStatus.extracted,
)
session.add(video)
await session.flush()
result = {
"creator_id": creator.id,
"creator_name": creator.name,
"video_id": video.id,
"video_filename": video.filename,
}
await session.commit()
return result
async def _seed_moment(
db_engine,
video_id: uuid.UUID,
title: str = "Test Moment",
summary: str = "A test key moment",
start_time: float = 10.0,
end_time: float = 30.0,
review_status: ReviewStatus = ReviewStatus.pending,
) -> uuid.UUID:
"""Seed a single key moment and return its ID."""
session_factory = async_sessionmaker(
db_engine, class_=AsyncSession, expire_on_commit=False
)
async with session_factory() as session:
moment = KeyMoment(
source_video_id=video_id,
title=title,
summary=summary,
start_time=start_time,
end_time=end_time,
content_type=KeyMomentContentType.technique,
review_status=review_status,
)
session.add(moment)
await session.commit()
return moment.id
async def _seed_second_video(db_engine, creator_id: uuid.UUID) -> uuid.UUID:
"""Seed a second video for cross-video merge tests."""
session_factory = async_sessionmaker(
db_engine, class_=AsyncSession, expire_on_commit=False
)
async with session_factory() as session:
video = SourceVideo(
creator_id=creator_id,
filename="other-video.mp4",
file_path="TestCreator/other-video.mp4",
duration_seconds=300,
content_type=ContentType.tutorial,
processing_status=ProcessingStatus.extracted,
)
session.add(video)
await session.commit()
return video.id
# ── Queue listing tests ─────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_list_queue_empty(client: AsyncClient):
"""Queue returns empty list when no moments exist."""
resp = await client.get(QUEUE_URL)
assert resp.status_code == 200
data = resp.json()
assert data["items"] == []
assert data["total"] == 0
@pytest.mark.asyncio
async def test_list_queue_with_moments(client: AsyncClient, db_engine):
"""Queue returns moments enriched with video filename and creator name."""
seed = await _seed_creator_and_video(db_engine)
await _seed_moment(db_engine, seed["video_id"], title="EQ Basics")
resp = await client.get(QUEUE_URL)
assert resp.status_code == 200
data = resp.json()
assert data["total"] == 1
item = data["items"][0]
assert item["title"] == "EQ Basics"
assert item["video_filename"] == seed["video_filename"]
assert item["creator_name"] == seed["creator_name"]
assert item["review_status"] == "pending"
@pytest.mark.asyncio
async def test_list_queue_filter_by_status(client: AsyncClient, db_engine):
"""Queue filters correctly by status query parameter."""
seed = await _seed_creator_and_video(db_engine)
await _seed_moment(db_engine, seed["video_id"], title="Pending One")
await _seed_moment(
db_engine, seed["video_id"], title="Approved One",
review_status=ReviewStatus.approved,
)
await _seed_moment(
db_engine, seed["video_id"], title="Rejected One",
review_status=ReviewStatus.rejected,
)
# Default filter: pending
resp = await client.get(QUEUE_URL)
assert resp.json()["total"] == 1
assert resp.json()["items"][0]["title"] == "Pending One"
# Approved
resp = await client.get(QUEUE_URL, params={"status": "approved"})
assert resp.json()["total"] == 1
assert resp.json()["items"][0]["title"] == "Approved One"
# All
resp = await client.get(QUEUE_URL, params={"status": "all"})
assert resp.json()["total"] == 3
# ── Stats tests ──────────────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_stats_counts(client: AsyncClient, db_engine):
"""Stats returns correct counts per review status."""
seed = await _seed_creator_and_video(db_engine)
await _seed_moment(db_engine, seed["video_id"], review_status=ReviewStatus.pending)
await _seed_moment(db_engine, seed["video_id"], review_status=ReviewStatus.pending)
await _seed_moment(db_engine, seed["video_id"], review_status=ReviewStatus.approved)
await _seed_moment(db_engine, seed["video_id"], review_status=ReviewStatus.rejected)
resp = await client.get(STATS_URL)
assert resp.status_code == 200
data = resp.json()
assert data["pending"] == 2
assert data["approved"] == 1
assert data["edited"] == 0
assert data["rejected"] == 1
# ── Approve tests ────────────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_approve_moment(client: AsyncClient, db_engine):
"""Approve sets review_status to approved."""
seed = await _seed_creator_and_video(db_engine)
moment_id = await _seed_moment(db_engine, seed["video_id"])
resp = await client.post(_moment_url(str(moment_id), "approve"))
assert resp.status_code == 200
assert resp.json()["review_status"] == "approved"
@pytest.mark.asyncio
async def test_approve_nonexistent_moment(client: AsyncClient):
"""Approve returns 404 for nonexistent moment."""
fake_id = str(uuid.uuid4())
resp = await client.post(_moment_url(fake_id, "approve"))
assert resp.status_code == 404
# ── Reject tests ─────────────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_reject_moment(client: AsyncClient, db_engine):
"""Reject sets review_status to rejected."""
seed = await _seed_creator_and_video(db_engine)
moment_id = await _seed_moment(db_engine, seed["video_id"])
resp = await client.post(_moment_url(str(moment_id), "reject"))
assert resp.status_code == 200
assert resp.json()["review_status"] == "rejected"
@pytest.mark.asyncio
async def test_reject_nonexistent_moment(client: AsyncClient):
"""Reject returns 404 for nonexistent moment."""
fake_id = str(uuid.uuid4())
resp = await client.post(_moment_url(fake_id, "reject"))
assert resp.status_code == 404
# ── Edit tests ───────────────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_edit_moment(client: AsyncClient, db_engine):
"""Edit updates fields and sets review_status to edited."""
seed = await _seed_creator_and_video(db_engine)
moment_id = await _seed_moment(db_engine, seed["video_id"], title="Original Title")
resp = await client.put(
_moment_url(str(moment_id)),
json={"title": "Updated Title", "summary": "New summary"},
)
assert resp.status_code == 200
data = resp.json()
assert data["title"] == "Updated Title"
assert data["summary"] == "New summary"
assert data["review_status"] == "edited"
@pytest.mark.asyncio
async def test_edit_nonexistent_moment(client: AsyncClient):
"""Edit returns 404 for nonexistent moment."""
fake_id = str(uuid.uuid4())
resp = await client.put(
_moment_url(fake_id),
json={"title": "Won't Work"},
)
assert resp.status_code == 404
# ── Split tests ──────────────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_split_moment(client: AsyncClient, db_engine):
"""Split creates two moments with correct timestamps."""
seed = await _seed_creator_and_video(db_engine)
moment_id = await _seed_moment(
db_engine, seed["video_id"],
title="Full Moment", start_time=10.0, end_time=30.0,
)
resp = await client.post(
_moment_url(str(moment_id), "split"),
json={"split_time": 20.0},
)
assert resp.status_code == 200
data = resp.json()
assert len(data) == 2
# First (original): [10.0, 20.0)
assert data[0]["start_time"] == 10.0
assert data[0]["end_time"] == 20.0
# Second (new): [20.0, 30.0]
assert data[1]["start_time"] == 20.0
assert data[1]["end_time"] == 30.0
assert "(split)" in data[1]["title"]
@pytest.mark.asyncio
async def test_split_invalid_time_below_start(client: AsyncClient, db_engine):
"""Split returns 400 when split_time is at or below start_time."""
seed = await _seed_creator_and_video(db_engine)
moment_id = await _seed_moment(
db_engine, seed["video_id"], start_time=10.0, end_time=30.0,
)
resp = await client.post(
_moment_url(str(moment_id), "split"),
json={"split_time": 10.0},
)
assert resp.status_code == 400
@pytest.mark.asyncio
async def test_split_invalid_time_above_end(client: AsyncClient, db_engine):
"""Split returns 400 when split_time is at or above end_time."""
seed = await _seed_creator_and_video(db_engine)
moment_id = await _seed_moment(
db_engine, seed["video_id"], start_time=10.0, end_time=30.0,
)
resp = await client.post(
_moment_url(str(moment_id), "split"),
json={"split_time": 30.0},
)
assert resp.status_code == 400
@pytest.mark.asyncio
async def test_split_nonexistent_moment(client: AsyncClient):
"""Split returns 404 for nonexistent moment."""
fake_id = str(uuid.uuid4())
resp = await client.post(
_moment_url(fake_id, "split"),
json={"split_time": 20.0},
)
assert resp.status_code == 404
# ── Merge tests ──────────────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_merge_moments(client: AsyncClient, db_engine):
"""Merge combines two moments: combined summary, min start, max end, target deleted."""
seed = await _seed_creator_and_video(db_engine)
m1_id = await _seed_moment(
db_engine, seed["video_id"],
title="First", summary="Summary A",
start_time=10.0, end_time=20.0,
)
m2_id = await _seed_moment(
db_engine, seed["video_id"],
title="Second", summary="Summary B",
start_time=25.0, end_time=35.0,
)
resp = await client.post(
_moment_url(str(m1_id), "merge"),
json={"target_moment_id": str(m2_id)},
)
assert resp.status_code == 200
data = resp.json()
assert data["start_time"] == 10.0
assert data["end_time"] == 35.0
assert "Summary A" in data["summary"]
assert "Summary B" in data["summary"]
# Target should be deleted — reject should 404
resp2 = await client.post(_moment_url(str(m2_id), "reject"))
assert resp2.status_code == 404
@pytest.mark.asyncio
async def test_merge_different_videos(client: AsyncClient, db_engine):
"""Merge returns 400 when moments are from different source videos."""
seed = await _seed_creator_and_video(db_engine)
m1_id = await _seed_moment(db_engine, seed["video_id"], title="Video 1 moment")
other_video_id = await _seed_second_video(db_engine, seed["creator_id"])
m2_id = await _seed_moment(db_engine, other_video_id, title="Video 2 moment")
resp = await client.post(
_moment_url(str(m1_id), "merge"),
json={"target_moment_id": str(m2_id)},
)
assert resp.status_code == 400
assert "different source videos" in resp.json()["detail"]
@pytest.mark.asyncio
async def test_merge_with_self(client: AsyncClient, db_engine):
"""Merge returns 400 when trying to merge a moment with itself."""
seed = await _seed_creator_and_video(db_engine)
m_id = await _seed_moment(db_engine, seed["video_id"])
resp = await client.post(
_moment_url(str(m_id), "merge"),
json={"target_moment_id": str(m_id)},
)
assert resp.status_code == 400
assert "itself" in resp.json()["detail"]
@pytest.mark.asyncio
async def test_merge_nonexistent_target(client: AsyncClient, db_engine):
"""Merge returns 404 when target moment does not exist."""
seed = await _seed_creator_and_video(db_engine)
m_id = await _seed_moment(db_engine, seed["video_id"])
resp = await client.post(
_moment_url(str(m_id), "merge"),
json={"target_moment_id": str(uuid.uuid4())},
)
assert resp.status_code == 404
@pytest.mark.asyncio
async def test_merge_nonexistent_source(client: AsyncClient):
"""Merge returns 404 when source moment does not exist."""
fake_id = str(uuid.uuid4())
resp = await client.post(
_moment_url(fake_id, "merge"),
json={"target_moment_id": str(uuid.uuid4())},
)
assert resp.status_code == 404
# ── Mode toggle tests ───────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_get_mode_default(client: AsyncClient):
"""Get mode returns config default when Redis has no value."""
mock_redis = AsyncMock()
mock_redis.get = AsyncMock(return_value=None)
mock_redis.aclose = AsyncMock()
with patch("routers.review.get_redis", return_value=mock_redis):
resp = await client.get(MODE_URL)
assert resp.status_code == 200
# Default from config is True
assert resp.json()["review_mode"] is True
@pytest.mark.asyncio
async def test_set_mode(client: AsyncClient):
"""Set mode writes to Redis and returns the new value."""
mock_redis = AsyncMock()
mock_redis.set = AsyncMock()
mock_redis.aclose = AsyncMock()
with patch("routers.review.get_redis", return_value=mock_redis):
resp = await client.put(MODE_URL, json={"review_mode": False})
assert resp.status_code == 200
assert resp.json()["review_mode"] is False
mock_redis.set.assert_called_once_with("chrysopedia:review_mode", "False")
@pytest.mark.asyncio
async def test_get_mode_from_redis(client: AsyncClient):
"""Get mode reads the value stored in Redis."""
mock_redis = AsyncMock()
mock_redis.get = AsyncMock(return_value="False")
mock_redis.aclose = AsyncMock()
with patch("routers.review.get_redis", return_value=mock_redis):
resp = await client.get(MODE_URL)
assert resp.status_code == 200
assert resp.json()["review_mode"] is False
@pytest.mark.asyncio
async def test_get_mode_redis_error_fallback(client: AsyncClient):
"""Get mode falls back to config default when Redis is unavailable."""
with patch("routers.review.get_redis", side_effect=ConnectionError("Redis down")):
resp = await client.get(MODE_URL)
assert resp.status_code == 200
# Falls back to config default (True)
assert resp.json()["review_mode"] is True
@pytest.mark.asyncio
async def test_set_mode_redis_error(client: AsyncClient):
"""Set mode returns 503 when Redis is unavailable."""
with patch("routers.review.get_redis", side_effect=ConnectionError("Redis down")):
resp = await client.put(MODE_URL, json={"review_mode": False})
assert resp.status_code == 503

341
backend/tests/test_search.py
View file

@ -1,341 +0,0 @@
"""Integration tests for the /api/v1/search endpoint.
Tests run against a real PostgreSQL test database via httpx.AsyncClient.
SearchService is mocked at the router dependency level so we can test
endpoint behavior without requiring external embedding API or Qdrant.
"""
from __future__ import annotations
import uuid
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
import pytest_asyncio
from httpx import AsyncClient
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from models import (
ContentType,
Creator,
KeyMoment,
KeyMomentContentType,
ProcessingStatus,
SourceVideo,
TechniquePage,
)
SEARCH_URL = "/api/v1/search"
# ── Seed helpers ─────────────────────────────────────────────────────────────
async def _seed_search_data(db_engine) -> dict:
"""Seed 2 creators, 3 technique pages, and 5 key moments for search tests.
Returns a dict with creator/technique IDs and metadata for assertions.
"""
session_factory = async_sessionmaker(
db_engine, class_=AsyncSession, expire_on_commit=False
)
async with session_factory() as session:
# Creators
creator1 = Creator(
name="Mr. Bill",
slug="mr-bill",
genres=["Bass music", "Glitch"],
folder_name="MrBill",
)
creator2 = Creator(
name="KOAN Sound",
slug="koan-sound",
genres=["Drum & bass", "Neuro"],
folder_name="KOANSound",
)
session.add_all([creator1, creator2])
await session.flush()
# Videos (needed for key moments FK)
video1 = SourceVideo(
creator_id=creator1.id,
filename="bass-design-101.mp4",
file_path="MrBill/bass-design-101.mp4",
duration_seconds=600,
content_type=ContentType.tutorial,
processing_status=ProcessingStatus.extracted,
)
video2 = SourceVideo(
creator_id=creator2.id,
filename="reese-bass-deep-dive.mp4",
file_path="KOANSound/reese-bass-deep-dive.mp4",
duration_seconds=900,
content_type=ContentType.tutorial,
processing_status=ProcessingStatus.extracted,
)
session.add_all([video1, video2])
await session.flush()
# Technique pages
tp1 = TechniquePage(
creator_id=creator1.id,
title="Reese Bass Design",
slug="reese-bass-design",
topic_category="Sound design",
topic_tags=["bass", "textures"],
summary="How to create a classic reese bass",
)
tp2 = TechniquePage(
creator_id=creator2.id,
title="Granular Pad Textures",
slug="granular-pad-textures",
topic_category="Synthesis",
topic_tags=["granular", "pads"],
summary="Creating pad textures with granular synthesis",
)
tp3 = TechniquePage(
creator_id=creator1.id,
title="FM Bass Layering",
slug="fm-bass-layering",
topic_category="Synthesis",
topic_tags=["fm", "bass"],
summary="FM synthesis techniques for bass layering",
)
session.add_all([tp1, tp2, tp3])
await session.flush()
# Key moments
km1 = KeyMoment(
source_video_id=video1.id,
technique_page_id=tp1.id,
title="Setting up the Reese oscillator",
summary="Initial oscillator setup for reese bass",
start_time=10.0,
end_time=60.0,
content_type=KeyMomentContentType.technique,
)
km2 = KeyMoment(
source_video_id=video1.id,
technique_page_id=tp1.id,
title="Adding distortion to the Reese",
summary="Distortion processing chain for reese bass",
start_time=60.0,
end_time=120.0,
content_type=KeyMomentContentType.technique,
)
km3 = KeyMoment(
source_video_id=video2.id,
technique_page_id=tp2.id,
title="Granular engine settings",
summary="Dialing in granular engine parameters",
start_time=20.0,
end_time=80.0,
content_type=KeyMomentContentType.settings,
)
km4 = KeyMoment(
source_video_id=video1.id,
technique_page_id=tp3.id,
title="FM ratio selection",
summary="Choosing FM ratios for bass tones",
start_time=5.0,
end_time=45.0,
content_type=KeyMomentContentType.technique,
)
km5 = KeyMoment(
source_video_id=video2.id,
title="Outro and credits",
summary="End of the video",
start_time=800.0,
end_time=900.0,
content_type=KeyMomentContentType.workflow,
)
session.add_all([km1, km2, km3, km4, km5])
await session.commit()
return {
"creator1_id": str(creator1.id),
"creator1_name": creator1.name,
"creator1_slug": creator1.slug,
"creator2_id": str(creator2.id),
"creator2_name": creator2.name,
"tp1_slug": tp1.slug,
"tp1_title": tp1.title,
"tp2_slug": tp2.slug,
"tp3_slug": tp3.slug,
}
# ── Tests ────────────────────────────────────────────────────────────────────
@pytest.mark.asyncio
async def test_search_happy_path_with_mocked_service(client, db_engine):
"""Search endpoint returns mocked results with correct response shape."""
seed = await _seed_search_data(db_engine)
# Mock the SearchService.search method to return canned results
mock_result = {
"items": [
{
"type": "technique_page",
"title": "Reese Bass Design",
"slug": "reese-bass-design",
"summary": "How to create a classic reese bass",
"topic_category": "Sound design",
"topic_tags": ["bass", "textures"],
"creator_name": "Mr. Bill",
"creator_slug": "mr-bill",
"score": 0.95,
}
],
"total": 1,
"query": "reese bass",
"fallback_used": False,
}
with patch("routers.search.SearchService") as MockSvc:
instance = MockSvc.return_value
instance.search = AsyncMock(return_value=mock_result)
resp = await client.get(SEARCH_URL, params={"q": "reese bass"})
assert resp.status_code == 200
data = resp.json()
assert data["query"] == "reese bass"
assert data["total"] == 1
assert data["fallback_used"] is False
assert len(data["items"]) == 1
item = data["items"][0]
assert item["title"] == "Reese Bass Design"
assert item["slug"] == "reese-bass-design"
assert "score" in item
@pytest.mark.asyncio
async def test_search_empty_query_returns_empty(client, db_engine):
"""Empty search query returns empty results without hitting SearchService."""
await _seed_search_data(db_engine)
# With empty query, the search service returns empty results directly
mock_result = {
"items": [],
"total": 0,
"query": "",
"fallback_used": False,
}
with patch("routers.search.SearchService") as MockSvc:
instance = MockSvc.return_value
instance.search = AsyncMock(return_value=mock_result)
resp = await client.get(SEARCH_URL, params={"q": ""})
assert resp.status_code == 200
data = resp.json()
assert data["items"] == []
assert data["total"] == 0
assert data["query"] == ""
assert data["fallback_used"] is False
@pytest.mark.asyncio
async def test_search_keyword_fallback(client, db_engine):
"""When embedding fails, search uses keyword fallback and sets fallback_used=true."""
seed = await _seed_search_data(db_engine)
mock_result = {
"items": [
{
"type": "technique_page",
"title": "Reese Bass Design",
"slug": "reese-bass-design",
"summary": "How to create a classic reese bass",
"topic_category": "Sound design",
"topic_tags": ["bass", "textures"],
"creator_name": "",
"creator_slug": "",
"score": 0.0,
}
],
"total": 1,
"query": "reese",
"fallback_used": True,
}
with patch("routers.search.SearchService") as MockSvc:
instance = MockSvc.return_value
instance.search = AsyncMock(return_value=mock_result)
resp = await client.get(SEARCH_URL, params={"q": "reese"})
assert resp.status_code == 200
data = resp.json()
assert data["fallback_used"] is True
assert data["total"] >= 1
assert data["items"][0]["title"] == "Reese Bass Design"
@pytest.mark.asyncio
async def test_search_scope_filter(client, db_engine):
"""Search with scope=topics returns only technique_page type results."""
await _seed_search_data(db_engine)
mock_result = {
"items": [
{
"type": "technique_page",
"title": "FM Bass Layering",
"slug": "fm-bass-layering",
"summary": "FM synthesis techniques for bass layering",
"topic_category": "Synthesis",
"topic_tags": ["fm", "bass"],
"creator_name": "Mr. Bill",
"creator_slug": "mr-bill",
"score": 0.88,
}
],
"total": 1,
"query": "bass",
"fallback_used": False,
}
with patch("routers.search.SearchService") as MockSvc:
instance = MockSvc.return_value
instance.search = AsyncMock(return_value=mock_result)
resp = await client.get(SEARCH_URL, params={"q": "bass", "scope": "topics"})
assert resp.status_code == 200
data = resp.json()
# All items should be technique_page type when scope=topics
for item in data["items"]:
assert item["type"] == "technique_page"
# Verify the service was called with scope=topics
call_kwargs = instance.search.call_args
assert call_kwargs.kwargs.get("scope") == "topics" or call_kwargs[1].get("scope") == "topics"
@pytest.mark.asyncio
async def test_search_no_matching_results(client, db_engine):
"""Search with no matching results returns empty items list."""
await _seed_search_data(db_engine)
mock_result = {
"items": [],
"total": 0,
"query": "zzzznonexistent",
"fallback_used": True,
}
with patch("routers.search.SearchService") as MockSvc:
instance = MockSvc.return_value
instance.search = AsyncMock(return_value=mock_result)
resp = await client.get(SEARCH_URL, params={"q": "zzzznonexistent"})
assert resp.status_code == 200
data = resp.json()
assert data["items"] == []
assert data["total"] == 0

32
backend/worker.py
View file

@ -1,32 +0,0 @@
"""Celery application instance for the Chrysopedia pipeline.
Usage:
celery -A worker worker --loglevel=info
"""
from celery import Celery
from config import get_settings
settings = get_settings()
celery_app = Celery(
"chrysopedia",
broker=settings.redis_url,
backend=settings.redis_url,
)
celery_app.conf.update(
task_serializer="json",
result_serializer="json",
accept_content=["json"],
timezone="UTC",
enable_utc=True,
task_track_started=True,
task_acks_late=True,
worker_prefetch_multiplier=1,
)
# Import pipeline.stages so that @celery_app.task decorators register tasks.
# This import must come after celery_app is defined.
import pipeline.stages # noqa: E402, F401

713
chrysopedia-spec.md
View file

@ -1,713 +0,0 @@
# Chrysopedia — Project Specification
> **Etymology:** From *chrysopoeia* (the alchemical transmutation of base material into gold) + *encyclopedia* (an organized body of knowledge). Chrysopedia transmutes raw video content into refined, searchable production knowledge.
---
## 1. Project overview
### 1.1 Problem statement
Hundreds of hours of educational video content from electronic music producers sit on local storage — tutorials, livestreams, track breakdowns, and deep dives covering techniques in sound design, mixing, arrangement, synthesis, and more. This content is extremely valuable but nearly impossible to retrieve: videos are unsearchable, unchaptered, and undocumented. A 4-hour livestream may contain 6 minutes of actionable gold buried among tangents and chat interaction. The current retrieval method is "scrub through from memory and hope" — or more commonly, the knowledge is simply lost.
### 1.2 Solution
Chrysopedia is a self-hosted knowledge extraction and retrieval system that:
1. **Transcribes** video content using local Whisper inference
2. **Extracts** key moments, techniques, and insights using LLM analysis
3. **Classifies** content by topic, creator, plugins, and production stage
4. **Synthesizes** knowledge across multiple sources into coherent technique pages
5. **Serves** a fast, search-first web UI for mid-session retrieval
The system transforms raw video files into a browsable, searchable knowledge base with direct timestamp links back to source material.
### 1.3 Design principles
- **Search-first.** The primary interaction is typing a query and getting results in seconds. Browse is secondary, for exploration.
- **Surgical retrieval.** A producer mid-session should be able to Alt+Tab, find the technique they need, absorb the key insight, and get back to their DAW in under 2 minutes.
- **Creator equity.** No artist is privileged in the UI. All creators get equal visual weight. Default sort is randomized.
- **Dual-axis navigation.** Content is accessible by Topic (technique/production stage) and by Creator (artist), with both paths being first-class citizens.
- **Incremental, not one-time.** The system must handle ongoing content additions, not just an initial batch.
- **Self-hosted and portable.** Packaged as a Docker Compose project, deployable on existing infrastructure.
### 1.4 Name and identity
- **Project name:** Chrysopedia
- **Suggested subdomain:** `chrysopedia.xpltd.co`
- **Docker project name:** `chrysopedia`
---
## 2. Content inventory and source material
### 2.1 Current state
- **Volume:** 100–500 video files
- **Creators:** 50+ distinct artists/producers
- **Formats:** Primarily MP4/MKV, mixed quality and naming conventions
- **Organization:** Folders per artist, filenames loosely descriptive
- **Location:** Local desktop storage (not yet on the hypervisor/NAS)
- **Content types:**
- Full-length tutorials (30min–4hrs, structured walkthroughs)
- Livestream recordings (long, unstructured, conversational)
- Track breakdowns / start-to-finish productions
### 2.2 Content characteristics
The audio track carries the vast majority of the value. Visual demonstrations (screen recordings of DAW work) are useful context but are not the primary extraction target. The transcript is the primary ore.
**Structured content** (tutorials, breakdowns) tends to have natural topic boundaries — the producer announces what they're about to cover, then demonstrates. These are easier to segment.
**Unstructured content** (livestreams) is chaotic: tangents, chat interaction, rambling, with gems appearing without warning. The extraction pipeline must handle both structured and unstructured content using semantic understanding, not just topic detection from speaker announcements.
---
## 3. Terminology
| Term | Definition |
|------|-----------|
| **Creator** | An artist, producer, or educator whose video content is in the system. Formerly "artist" — renamed for flexibility. |
| **Technique page** | The primary knowledge unit: a structured page covering one technique or concept from one creator, compiled from one or more source videos. |
| **Key moment** | A discrete, timestamped insight extracted from a video — a specific technique, setting, or piece of reasoning worth capturing. |
| **Topic** | A production domain or concept category (e.g., "sound design," "mixing," "snare design"). Organized hierarchically. |
| **Genre** | A broad musical style tag (e.g., "dubstep," "drum & bass," "halftime"). Stored as metadata on Creators, not on techniques. Used as a filter across all views. |
| **Source video** | An original video file that has been processed by the pipeline. |
| **Transcript** | The timestamped text output of Whisper processing a source video's audio. |
---
## 4. User experience
### 4.1 UX philosophy
The system is accessed via Alt+Tab from a DAW on the same desktop machine. Every design decision optimizes for speed of retrieval and minimal cognitive load. The interface should feel like a tool, not a destination.
**Primary access method:** Same machine, Alt+Tab to browser.
### 4.2 Landing page (Launchpad)
The landing page is a decision point, not a dashboard. Minimal, focused, fast.
**Layout (top to bottom):**
1. **Search bar** — prominent, full-width, with live typeahead (results appear after 2–3 characters). This is the primary interaction for most visits. Scope toggle tabs below the search input: `All | Topics | Creators`
2. **Two navigation cards** — side-by-side:
- **Topics** — "Browse by technique, production stage, or concept" with count of total techniques and categories
- **Creators** — "Browse by artist, filterable by genre" with count of total creators and genres
3. **Recently added** — a short list of the most recently processed/published technique pages with creator name, topic tag, and relative timestamp
**Future feature (not v1):** Trending / popular section alongside recently added, driven by view counts and cross-reference frequency.
### 4.3 Live search (typeahead)
The search bar is the primary interface. Behavior:
- Results begin appearing after 2–3 characters typed
- Scope toggle: `All | Topics | Creators` — filters what types of results appear
- **"All" scope** groups results by type:
- **Topics** — technique pages matching the query, showing title, creator name(s), parent topic tag
- **Key moments** — individual timestamped insights matching the query, showing moment title, creator, source file, and timestamp. Clicking jumps to the technique page (or eventually direct to the video moment)
- **Creators** — creator names matching the query
- **"Topics" scope** — shows only technique pages
- **"Creators" scope** — shows only creator matches
- Genre filter is accessible on Creators scope and cross-filters Topics scope (using creator-level genre metadata)
- Search is semantic where possible (powered by Qdrant vector search), with keyword fallback
### 4.4 Technique page (A+C hybrid format)
The core content unit. Each technique page covers one technique or concept from one creator. The format adapts by content type but follows a consistent structure.
**Layout (top to bottom):**
1. **Header:**
- Topic tags (e.g., "sound design," "drums," "snare")
- Technique title (e.g., "Snare design")
- Creator name
- Meta line: "Compiled from N sources · M key moments · Last updated [date]"
- Source quality warning (amber banner) if content came from an unstructured livestream
2. **Study guide prose (Section A):**
- Organized by sub-aspects of the technique (e.g., "Layer construction," "Saturation & character," "Mix context")
- Rich prose capturing:
- The specific technique/method described (highest priority)
- Exact settings, plugins, and parameters when the creator was *teaching* the setting (not incidental use)
- The reasoning/philosophy behind choices when the creator explains *why*
- Signal chain blocks rendered in monospace when a creator walks through a routing chain
- Direct quotes of creator opinions/warnings when they add value (e.g., "He says it 'smears the transient into mush'")
3. **Key moments index (Section C):**
- Compact list of individual timestamped insights
- Each row: moment title, source video filename, clickable timestamp
- Sorted chronologically within each source video
4. **Related techniques:**
- Links to related technique pages — same technique by other creators, adjacent techniques by the same creator, general/cross-creator technique pages
- Renders as clickable pill-shaped tags
5. **Plugins referenced:**
- List of all plugins/tools mentioned in the technique page
- Each is a clickable tag that could lead to "all techniques referencing this plugin" (future: dedicated plugin pages)
**Content type adaptation:**
- **Technique-heavy content** (sound design, specific methods): Full A+C treatment with signal chains, plugin details, parameter specifics
- **Philosophy/workflow content** (mixdown approach, creative process): More prose-heavy, fewer signal chain blocks, but same overall structure. These pages are still browsable but also serve as rich context for future RAG/chat retrieval
- **Livestream-sourced content:** Amber warning banner noting source quality. Timestamps may land in messy context with tangents nearby
### 4.5 Creators browse page
Accessed from the landing page "Creators" card.
**Layout:**
- Page title: "Creators" with total count
- Filter input: type-to-narrow the list
- Genre filter pills: `All genres | Bass music | Drum & bass | Dubstep | Halftime | House | IDM | Neuro | Techno | ...` — clicking a genre filters the list to creators tagged with that genre
- Sort options: Randomized (default, re-shuffled on every page load), Alphabetical, View count
- Creator list: flat, equal-weight rows. Each row shows:
- Creator name
- Genre tags (multiple allowed)
- Technique count
- Video count
- View count (sum of activity across all content derived from this creator)
- Clicking a row navigates to that creator's detail page (list of all their technique pages)
**Default sort is randomized on every page load** to prevent discovery bias. Users can toggle to alphabetical or sort by view count.
### 4.6 Topics browse page
Accessed from the landing page "Topics" card.
**Layout:**
- Page title: "Topics" with total technique count
- Filter input: type-to-narrow
- Genre filter pills (uses creator-level genre metadata to filter): show only techniques from creators tagged with the selected genre
- **Two-level hierarchy displayed:**
- **Top-level categories:** Sound design, Mixing, Synthesis, Arrangement, Workflow, Mastering
- **Sub-topics within each:** clicking a top-level category expands or navigates to show sub-topics (e.g., Sound Design → Bass, Drums, Pads, Leads, FX, Foley; Drums → Kick, Snare, Hi-hat, Percussion)
- Each sub-topic shows: technique count, number of creators covering it
- Clicking a sub-topic shows all technique pages in that category, filterable by creator and genre
### 4.7 Search results page
For complex queries that go beyond typeahead (e.g., hitting Enter after typing a full query).
**Layout:**
- Search bar at top (retains query)
- Scope tabs: `All results (N) | Techniques (N) | Key moments (N) | Creators (N)`
- Results split into two tiers:
- **Technique pages** — first-class results with title, creator, summary snippet, tags, moment count, plugin list
- **Also mentioned in** — cross-references where the search term appears inside other technique pages (e.g., searching "snare" surfaces "drum bus processing" because it mentions snare bus techniques)
---
## 5. Taxonomy and topic hierarchy
### 5.1 Top-level categories
These are broad production stages/domains. They should cover the full scope of music production education:
| Category | Description | Example sub-topics |
|----------|-------------|-------------------|
| Sound design | Creating and shaping sounds from scratch or samples | Bass, drums (kick, snare, hi-hat, percussion), pads, leads, FX, foley, vocals, textures |
| Mixing | Balancing, processing, and spatializing elements in a session | EQ, compression, bus processing, reverb/delay, stereo imaging, gain staging, automation |
| Synthesis | Methods of generating sound | FM, wavetable, granular, additive, subtractive, modular, physical modeling |
| Arrangement | Structuring a track from intro to outro | Song structure, transitions, tension/release, energy flow, breakdowns, drops |
| Workflow | Creative process, session management, productivity | DAW setup, templates, creative process, collaboration, file management, resampling |
| Mastering | Final stage processing for release | Limiting, stereo width, loudness, format delivery, referencing |
### 5.2 Sub-topic management
Sub-topics are not rigidly pre-defined. The extraction pipeline proposes sub-topic tags during classification, and the taxonomy grows organically as content is processed. However, the system maintains a **canonical tag list** that the LLM references during classification to ensure consistency (e.g., always "snare" not sometimes "snare drum" and sometimes "snare design").
The canonical tag list is editable by the administrator and should be stored as a configuration file that the pipeline references. New tags can be proposed by the pipeline and queued for admin approval, or auto-added if they fit within an existing top-level category.
### 5.3 Genre taxonomy
Genres are broad, general-level tags. Sub-genre classification is explicitly out of scope to avoid complexity.
**Initial genre set (expandable):**
Bass music, Drum & bass, Dubstep, Halftime, House, Techno, IDM, Glitch, Downtempo, Neuro, Ambient, Experimental, Cinematic
**Rules:**
- Genres are metadata on Creators, not on techniques
- A Creator can have multiple genre tags
- Genre is available as a filter on both the Creators browse page and the Topics browse page (filtering Topics by genre shows techniques from creators tagged with that genre)
- Genre tags are assigned during initial creator setup (manually or LLM-suggested based on content analysis) and can be edited by the administrator
---
## 6. Data model
### 6.1 Core entities
**Creator**
```
id UUID
name string (display name, e.g., "KOAN Sound")
slug string (URL-safe, e.g., "koan-sound")
genres string[] (e.g., ["glitch hop", "neuro", "bass music"])
folder_name string (matches the folder name on disk for source mapping)
view_count integer (aggregated from child technique page views)
created_at timestamp
updated_at timestamp
```
**Source Video**
```
id UUID
creator_id FK → Creator
filename string (original filename)
file_path string (path on disk)
duration_seconds integer
content_type enum: tutorial | livestream | breakdown | short_form
transcript_path string (path to transcript JSON)
processing_status enum: pending | transcribed | extracted | reviewed | published
created_at timestamp
updated_at timestamp
```
**Transcript Segment**
```
id UUID
source_video_id FK → Source Video
start_time float (seconds)
end_time float (seconds)
text text
segment_index integer (order within video)
topic_label string (LLM-assigned topic label for this segment)
```
**Key Moment**
```
id UUID
source_video_id FK → Source Video
technique_page_id FK → Technique Page (nullable until assigned)
title string (e.g., "Three-layer snare construction")
summary text (1-3 sentence description)
start_time float (seconds)
end_time float (seconds)
content_type enum: technique | settings | reasoning | workflow
plugins string[] (plugin names detected)
review_status enum: pending | approved | edited | rejected
raw_transcript text (the original transcript text for this segment)
created_at timestamp
updated_at timestamp
```
**Technique Page**
```
id UUID
creator_id FK → Creator
title string (e.g., "Snare design")
slug string (URL-safe)
topic_category string (top-level: "sound design")
topic_tags string[] (sub-topics: ["drums", "snare", "layering", "saturation"])
summary text (synthesized overview paragraph)
body_sections JSONB (structured prose sections with headings)
signal_chains JSONB[] (structured signal chain representations)
plugins string[] (all plugins referenced across all moments)
source_quality enum: structured | mixed | unstructured (derived from source video types)
view_count integer
review_status enum: draft | reviewed | published
created_at timestamp
updated_at timestamp
```
**Related Technique Link**
```
id UUID
source_page_id FK → Technique Page
target_page_id FK → Technique Page
relationship enum: same_technique_other_creator | same_creator_adjacent | general_cross_reference
```
**Tag (canonical)**
```
id UUID
name string (e.g., "snare")
category string (parent top-level category: "sound design")
aliases string[] (alternative phrasings the LLM should normalize: ["snare drum", "snare design"])
```
### 6.2 Storage layer
| Store | Purpose | Technology |
|-------|---------|------------|
| Relational DB | All structured data (creators, videos, moments, technique pages, tags) | PostgreSQL (preferred) or SQLite for initial simplicity |
| Vector DB | Semantic search embeddings for transcripts, key moments, and technique page content | Qdrant (already running on hypervisor) |
| File store | Raw transcript JSON files, source video reference metadata | Local filesystem on hypervisor, organized by creator slug |
### 6.3 Vector embeddings
The following content gets embedded in Qdrant for semantic search:
- Key moment summaries (with metadata: creator, topic, timestamp, source video)
- Technique page summaries and body sections
- Transcript segments (for future RAG/chat retrieval)
Embedding model: configurable. Can use a local model via Ollama (e.g., `nomic-embed-text`) or an API-based model. The embedding endpoint should be a configurable URL, same pattern as the LLM endpoint.
---
## 7. Pipeline architecture
### 7.1 Infrastructure topology
```
Desktop (RTX 4090) Hypervisor (Docker host)
┌─────────────────────┐ ┌─────────────────────────────────┐
│ Video files (local) │ │ Chrysopedia Docker Compose │
│ Whisper (local GPU) │──2.5GbE──────▶│ ├─ API / pipeline service │
│ Output: transcript │ (text only) │ ├─ Web UI │
│ JSON files │ │ ├─ PostgreSQL │
└─────────────────────┘ │ ├─ Qdrant (existing) │
│ └─ File store │
└────────────┬────────────────────┘
│ API calls (text)
┌─────────────▼────────────────────┐
│ Friend's DGX Sparks │
│ Qwen via Open WebUI API │
│ (2Gb fiber, high uptime) │
└──────────────────────────────────┘
```
**Bandwidth analysis:** Transcript JSON files are 200–500KB each. At 50Mbit upload, the entire library's transcripts could transfer in under a minute. The bandwidth constraint is irrelevant for this workload. The only large files (videos) stay on the desktop.
**Future centralization:** The Docker Compose project should be structured so that when all hardware is co-located, the only change is config (moving Whisper into the compose stack and pointing file paths to local storage). No architectural rewrite.
### 7.2 Processing stages
#### Stage 1: Audio extraction and transcription (Desktop)
**Tool:** Whisper large-v3 running locally on RTX 4090
**Input:** Video file (MP4/MKV)
**Process:**
1. Extract audio track from video (ffmpeg → WAV or direct pipe)
2. Run Whisper with word-level or segment-level timestamps
3. Output: JSON file with timestamped transcript
**Output format:**
```json
{
"source_file": "Skope — Sound Design Masterclass pt2.mp4",
"creator_folder": "Skope",
"duration_seconds": 7243,
"segments": [
{
"start": 0.0,
"end": 4.52,
"text": "Hey everyone welcome back to part two...",
"words": [
{"word": "Hey", "start": 0.0, "end": 0.28},
{"word": "everyone", "start": 0.32, "end": 0.74}
]
}
]
}
```
**Performance estimate:** Whisper large-v3 on a 4090 processes audio at roughly 10-20x real-time. A 2-hour video takes ~6-12 minutes to transcribe. For 300 videos averaging 1.5 hours each, the initial transcription pass is roughly 15-40 hours of GPU time.
#### Stage 2: Transcript segmentation (Hypervisor → LLM)
**Tool:** LLM (Qwen on DGX Sparks, or local Ollama as fallback)
**Input:** Full timestamped transcript JSON
**Process:** The LLM analyzes the transcript to identify topic boundaries — points where the creator shifts from one subject to another. Output is a segmented transcript with topic labels per segment.
**This stage can use a lighter model** if needed (segmentation is more mechanical than extraction). However, for simplicity in v1, use the same model endpoint as stages 3-5.
#### Stage 3: Key moment extraction (Hypervisor → LLM)
**Tool:** LLM (Qwen on DGX Sparks)
**Input:** Individual transcript segments from Stage 2
**Process:** The LLM reads each segment and identifies actionable insights. The extraction prompt should distinguish between:
- **Instructional content** (the creator is *teaching* something) → extract as a key moment
- **Incidental content** (the creator is *using* a tool without explaining it) → skip
- **Philosophical/reasoning content** (the creator explains *why* they make a choice) → extract with `content_type: reasoning`
- **Settings/parameters** (specific plugin settings, values, configurations being demonstrated) → extract with `content_type: settings`
**Extraction rule for plugin detail:** Capture plugin names and settings when the creator is *teaching* the setting — spending time explaining why they chose it, what it does, how to configure it. Skip incidental plugin usage (a plugin is visible but not discussed).
#### Stage 4: Classification and tagging (Hypervisor → LLM)
**Tool:** LLM (Qwen on DGX Sparks)
**Input:** Extracted key moments from Stage 3
**Process:** Each moment is classified with:
- Top-level topic category
- Sub-topic tags (referencing the canonical tag list)
- Plugin names (normalized to canonical names)
- Content type classification
The LLM is provided the canonical tag list as context and instructed to use existing tags where possible, proposing new tags only when no existing tag fits.
#### Stage 5: Synthesis (Hypervisor → LLM)
**Tool:** LLM (Qwen on DGX Sparks)
**Input:** All approved/published key moments for a given creator + topic combination
**Process:** When multiple key moments from the same creator cover overlapping or related topics, the synthesis stage merges them into a coherent technique page. This includes:
- Writing the overview summary paragraph
- Organizing body sections by sub-aspect
- Generating signal chain blocks where applicable
- Identifying related technique pages for cross-linking
- Compiling the plugin reference list
This stage runs whenever new key moments are approved for a creator+topic combination that already has a technique page (updating it), or when enough moments accumulate to warrant a new page.
### 7.3 LLM endpoint configuration
The pipeline talks to an **OpenAI-compatible API endpoint** (which both Ollama and Open WebUI expose). The LLM is not hardcoded — it's configured via environment variables:
```
LLM_API_URL=https://friend-openwebui.example.com/api
LLM_API_KEY=sk-...
LLM_MODEL=qwen2.5-72b
LLM_FALLBACK_URL=http://localhost:11434/v1 # local Ollama
LLM_FALLBACK_MODEL=qwen2.5:14b-q8_0
```
The pipeline should attempt the primary endpoint first and fall back to the local model if the primary is unavailable.
### 7.4 Embedding endpoint configuration
Same configurable pattern:
```
EMBEDDING_API_URL=http://localhost:11434/v1
EMBEDDING_MODEL=nomic-embed-text
```
### 7.5 Processing estimates for initial seeding
| Stage | Per video | 300 videos total |
|-------|----------|-----------------|
| Transcription (Whisper, 4090) | 6–12 min | 30–60 hours |
| Segmentation (LLM) | ~1 min | ~5 hours |
| Extraction (LLM) | ~2 min | ~10 hours |
| Classification (LLM) | ~30 sec | ~2.5 hours |
| Synthesis (LLM) | ~2 min per technique page | Varies by page count |
**Recommendation:** Tell the DGX Sparks friend to expect a weekend of sustained processing for the initial seed. The pipeline must be **resumable** — if it drops, it picks up from the last successfully processed video/stage, not from the beginning.
---
## 8. Review and approval workflow
### 8.1 Modes
The system supports two modes:
- **Review mode (initial calibration):** All extracted key moments enter a review queue. The administrator reviews, edits, approves, or rejects each moment before it's published.
- **Auto mode (post-calibration):** Extracted moments are published automatically. The review queue still exists but functions as an audit log rather than a gate.
The mode is a system-level toggle. The transition from review to auto mode happens when the administrator is satisfied with extraction quality — typically after reviewing the first several videos and tuning prompts.
### 8.2 Review queue interface
The review UI is part of the Chrysopedia web application (an admin section, not a separate tool).
**Queue view:**
- Counts: pending, approved, edited, rejected
- Filter tabs: Pending | Approved | Edited | Rejected
- Items organized by source video (review all moments from one video in sequence for context)
**Individual moment review:**
- Extracted moment: title, timestamp range, summary, tags, plugins detected
- Raw transcript segment displayed alongside for comparison
- Five actions:
- **Approve** — publish as-is
- **Edit & approve** — modify summary, tags, timestamp, or plugins, then publish
- **Split** — the moment actually contains two distinct insights; split into two separate moments
- **Merge with adjacent** — the system over-segmented; combine with the next or previous moment
- **Reject** — not a key moment; discard
### 8.3 Prompt tuning
The extraction prompts (stages 2-5) should be stored as editable configuration, not hardcoded. If review reveals systematic issues (e.g., the LLM consistently misclassifies mixing techniques as sound design), the administrator should be able to:
1. Edit the prompt templates
2. Re-run extraction on specific videos or all videos
3. Review the new output
This is the "calibration loop" — run pipeline, review output, tune prompts, re-run, repeat until quality is sufficient for auto mode.
---
## 9. New content ingestion workflow
### 9.1 Adding new videos
The ongoing workflow for adding new content after initial seeding:
1. **Drop file:** Place new video file(s) in the appropriate creator folder on the desktop (or create a new folder for a new creator)
2. **Trigger transcription:** Run the Whisper transcription stage on the new file(s). This could be a manual CLI command, a watched-folder daemon, or an n8n workflow trigger.
3. **Ship transcript:** Transfer the transcript JSON to the hypervisor (automated via the pipeline)
4. **Process:** Stages 2-5 run automatically on the new transcript
5. **Review or auto-publish:** Depending on mode, moments enter the review queue or publish directly
6. **Synthesis update:** If the new content covers a topic that already has a technique page for this creator, the synthesis stage updates the existing page. If it's a new topic, a new technique page is created.
### 9.2 Adding new creators
When a new creator's content is added:
1. Create a new folder on the desktop with the creator's name
2. Add video files
3. The pipeline detects the new folder name and creates a Creator record
4. Genre tags can be auto-suggested by the LLM based on content analysis, or manually assigned by the administrator
5. Process videos as normal
### 9.3 Watched folder (optional, future)
For maximum automation, a filesystem watcher on the desktop could detect new video files and automatically trigger the transcription pipeline. This is a nice-to-have for v2, not a v1 requirement. In v1, transcription is triggered manually.
---
## 10. Deployment and infrastructure
### 10.1 Docker Compose project
The entire Chrysopedia stack (excluding Whisper, which runs on the desktop GPU) is packaged as a single `docker-compose.yml`:
```yaml
# Indicative structure — not final
services:
chrysopedia-api:
# FastAPI or similar — handles pipeline orchestration, API endpoints
chrysopedia-web:
# Web UI — React, Svelte, or similar SPA
chrysopedia-db:
# PostgreSQL
chrysopedia-qdrant:
# Only if not using the existing Qdrant instance
chrysopedia-worker:
# Background job processor for pipeline stages 2-5
```
### 10.2 Existing infrastructure integration
**IMPORTANT:** The implementing agent should reference **XPLTD Lore** when making deployment decisions. This includes:
- Existing Docker conventions, naming patterns, and network configuration
- The hypervisor's current resource allocation and available capacity (~60 containers already running)
- Existing Qdrant instance (may be shared or a new collection created)
- Existing n8n instance (potential for workflow triggers)
- Storage paths and volume mount conventions
- Any reverse proxy or DNS configuration patterns
Do not assume infrastructure details — consult XPLTD Lore for how applications are typically deployed in this environment.
### 10.3 Whisper on desktop
Whisper runs separately on the desktop with the RTX 4090. It is NOT part of the Docker Compose stack (for now). It should be packaged as a simple Python script or lightweight container that:
1. Accepts a video file path (or watches a directory)
2. Extracts audio via ffmpeg
3. Runs Whisper large-v3
4. Outputs transcript JSON
5. Ships the JSON to the hypervisor (SCP, rsync, or API upload to the Chrysopedia API)
**Future centralization:** When all hardware is co-located, Whisper can be added to the Docker Compose stack with GPU passthrough, and the video files can be mounted directly. The pipeline should be designed so this migration is a config change, not a rewrite.
### 10.4 Network considerations
- Desktop ↔ Hypervisor: 2.5GbE (ample for transcript JSON transfer)
- Hypervisor ↔ DGX Sparks: Internet (50Mbit up from Chrysopedia side, 2Gb fiber on the DGX side). Transcript text payloads are tiny; this is not a bottleneck.
- Web UI: Served from hypervisor, accessed via local network (same machine Alt+Tab) or from other devices on the network. Eventually shareable with external users.
---
## 11. Technology recommendations
These are recommendations, not mandates. The implementing agent should evaluate alternatives based on current best practices and XPLTD Lore.
| Component | Recommendation | Rationale |
|-----------|---------------|-----------|
| Transcription | Whisper large-v3 (local, 4090) | Best accuracy, local processing keeps media files on-network |
| LLM inference | Qwen via Open WebUI API (DGX Sparks) | Free, powerful, high uptime. Ollama on 4090 as fallback |
| Embedding | nomic-embed-text via Ollama (local) | Good quality, runs easily alongside other local models |
| Vector DB | Qdrant | Already running on hypervisor |
| Relational DB | PostgreSQL | Robust, good JSONB support for flexible schema fields |
| API framework | FastAPI (Python) | Strong async support, good for pipeline orchestration |
| Web UI | React or Svelte SPA | Fast, component-based, good for search-heavy UIs |
| Background jobs | Celery with Redis, or a simpler task queue | Pipeline stages 2-5 run as background jobs |
| Audio extraction | ffmpeg | Universal, reliable |
---
## 12. Open questions and future considerations
These items are explicitly out of scope for v1 but should be considered in architectural decisions:
### 12.1 Chat / RAG retrieval
Not required for v1, but the system should be **architected to support it easily.** The Qdrant embeddings and structured knowledge base provide the foundation. A future chat interface could use the Qwen instance (or any compatible LLM) with RAG over the Chrysopedia knowledge base to answer natural language questions like "How does Skope approach snare design differently from Au5?"
### 12.2 Direct video playback
v1 provides file paths and timestamps ("Skope — Sound Design Masterclass pt2.mp4 @ 1:42:30"). Future versions could embed video playback directly in the web UI, jumping to the exact timestamp. This requires the video files to be network-accessible from the web UI, which depends on centralizing storage.
### 12.3 Access control
Not needed for v1. The system is initially for personal/local use. Future versions may add authentication for sharing with friends or external users. The architecture should not preclude this (e.g., don't hardcode single-user assumptions into the data model).
### 12.4 Multi-user features
Eventually: user-specific bookmarks, personal notes on technique pages, view history, and personalized "trending" based on individual usage patterns.
### 12.5 Content types beyond video
The extraction pipeline is fundamentally transcript-based. It could be extended to process podcast episodes, audio-only recordings, or even written tutorials/blog posts with minimal architectural changes.
### 12.6 Plugin knowledge base
Plugins referenced across all technique pages could be promoted to a first-class entity with their own browse page: "All techniques that reference Serum" or "Signal chains using Pro-Q 3." The data model already captures plugin references — this is primarily a UI feature.
---
## 13. Success criteria
The system is successful when:
1. **A producer mid-session can find a specific technique in under 30 seconds** — from Alt+Tab to reading the key insight
2. **The extraction pipeline correctly identifies 80%+ of key moments** without human intervention (post-calibration)
3. **New content can be added and processed within hours**, not days
4. **The knowledge base grows more useful over time** — cross-references and related techniques create a web of connected knowledge that surfaces unexpected insights
5. **The system runs reliably on existing infrastructure** without requiring significant new hardware or ongoing cloud costs
---
## 14. Implementation phases
### Phase 1: Foundation
- Set up Docker Compose project with PostgreSQL, API service, and web UI skeleton
- Implement Whisper transcription script for desktop
- Build transcript ingestion endpoint on the API
- Implement basic Creator and Source Video management
### Phase 2: Extraction pipeline
- Implement stages 2-5 (segmentation, extraction, classification, synthesis)
- Build the review queue UI
- Process a small batch of videos (5-10) for calibration
- Tune extraction prompts based on review feedback
### Phase 3: Knowledge UI
- Build the search-first web UI: landing page, live search, technique pages
- Implement Qdrant integration for semantic search
- Build Creators and Topics browse pages
- Implement related technique cross-linking
### Phase 4: Initial seeding
- Process the full video library through the pipeline
- Review and approve extractions (transitioning toward auto mode)
- Populate the canonical tag list and genre taxonomy
- Build out cross-references and related technique links
### Phase 5: Polish and ongoing
- Transition to auto mode for new content
- Implement view count tracking
- Optimize search ranking and relevance
- Begin sharing with trusted external users
---
*This specification was developed through collaborative ideation between the project owner and Claude. The implementing agent should treat this as a comprehensive guide while exercising judgment on technical implementation details, consulting XPLTD Lore for infrastructure conventions, and adapting to discoveries made during development.*

42
config/canonical_tags.yaml
View file

@ -1,42 +0,0 @@
# Canonical tags — 6 top-level production categories
# Sub-topics grow organically during pipeline extraction
categories:
- name: Sound design
description: Creating and shaping sounds from scratch or samples
sub_topics: [bass, drums, kick, snare, hi-hat, percussion, pads, leads, fx, foley, vocals, textures]
- name: Mixing
description: Balancing, processing, and spatializing elements
sub_topics: [eq, compression, bus processing, reverb, delay, stereo imaging, gain staging, automation]
- name: Synthesis
description: Methods of generating sound
sub_topics: [fm, wavetable, granular, additive, subtractive, modular, physical modeling]
- name: Arrangement
description: Structuring a track from intro to outro
sub_topics: [song structure, transitions, tension, energy flow, breakdowns, drops]
- name: Workflow
description: Creative process, session management, productivity
sub_topics: [daw setup, templates, creative process, collaboration, file management, resampling]
- name: Mastering
description: Final stage processing for release
sub_topics: [limiting, stereo width, loudness, format delivery, referencing]
# Genre taxonomy (assigned to Creators, not techniques)
genres:
- Bass music
- Drum & bass
- Dubstep
- Halftime
- House
- Techno
- IDM
- Glitch
- Downtempo
- Neuro
- Ambient
- Experimental
- Cinematic

178
docker-compose.yml
View file

@ -1,178 +0,0 @@
# Chrysopedia — Docker Compose
# XPLTD convention: xpltd_chrysopedia project, bind mounts, dedicated bridge
# Deployed to: /vmPool/r/compose/xpltd_chrysopedia/ (symlinked)
name: xpltd_chrysopedia
services:
# ── PostgreSQL 16 ──
chrysopedia-db:
image: postgres:16-alpine
container_name: chrysopedia-db
restart: unless-stopped
environment:
POSTGRES_USER: ${POSTGRES_USER:-chrysopedia}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-changeme}
POSTGRES_DB: ${POSTGRES_DB:-chrysopedia}
volumes:
- /vmPool/r/services/chrysopedia_db:/var/lib/postgresql/data
ports:
- "127.0.0.1:5433:5432"
networks:
- chrysopedia
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-chrysopedia}"]
interval: 10s
timeout: 5s
retries: 5
stop_grace_period: 30s
# ── Redis (Celery broker + runtime config) ──
chrysopedia-redis:
image: redis:7-alpine
container_name: chrysopedia-redis
restart: unless-stopped
command: redis-server --save 60 1 --loglevel warning
volumes:
- /vmPool/r/services/chrysopedia_redis:/data
networks:
- chrysopedia
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 5s
retries: 5
stop_grace_period: 15s
# ── Qdrant vector database ──
chrysopedia-qdrant:
image: qdrant/qdrant:v1.13.2
container_name: chrysopedia-qdrant
restart: unless-stopped
volumes:
- /vmPool/r/services/chrysopedia_qdrant:/qdrant/storage
networks:
- chrysopedia
healthcheck:
test: ["CMD-SHELL", "bash -c 'echo > /dev/tcp/localhost/6333'"]
interval: 15s
timeout: 5s
retries: 5
start_period: 10s
stop_grace_period: 30s
# ── Ollama (embedding model server) ──
chrysopedia-ollama:
image: ollama/ollama:latest
container_name: chrysopedia-ollama
restart: unless-stopped
volumes:
- /vmPool/r/services/chrysopedia_ollama:/root/.ollama
networks:
- chrysopedia
healthcheck:
test: ["CMD", "ollama", "list"]
interval: 15s
timeout: 5s
retries: 5
start_period: 30s
stop_grace_period: 15s
# ── FastAPI application ──
chrysopedia-api:
build:
context: .
dockerfile: docker/Dockerfile.api
container_name: chrysopedia-api
restart: unless-stopped
env_file:
- path: .env
required: false
environment:
DATABASE_URL: postgresql+asyncpg://${POSTGRES_USER:-chrysopedia}:${POSTGRES_PASSWORD:-changeme}@chrysopedia-db:5432/${POSTGRES_DB:-chrysopedia}
REDIS_URL: redis://chrysopedia-redis:6379/0
QDRANT_URL: http://chrysopedia-qdrant:6333
EMBEDDING_API_URL: http://chrysopedia-ollama:11434/v1
PROMPTS_PATH: /prompts
volumes:
- /vmPool/r/services/chrysopedia_data:/data
- ./config:/config:ro
depends_on:
chrysopedia-db:
condition: service_healthy
chrysopedia-redis:
condition: service_healthy
chrysopedia-qdrant:
condition: service_healthy
chrysopedia-ollama:
condition: service_healthy
networks:
- chrysopedia
stop_grace_period: 15s
# ── Celery worker (pipeline stages 2-6) ──
chrysopedia-worker:
build:
context: .
dockerfile: docker/Dockerfile.api
container_name: chrysopedia-worker
restart: unless-stopped
env_file:
- path: .env
required: false
environment:
DATABASE_URL: postgresql+asyncpg://${POSTGRES_USER:-chrysopedia}:${POSTGRES_PASSWORD:-changeme}@chrysopedia-db:5432/${POSTGRES_DB:-chrysopedia}
REDIS_URL: redis://chrysopedia-redis:6379/0
QDRANT_URL: http://chrysopedia-qdrant:6333
EMBEDDING_API_URL: http://chrysopedia-ollama:11434/v1
PROMPTS_PATH: /prompts
command: ["celery", "-A", "worker", "worker", "--loglevel=info", "--concurrency=1"]
healthcheck:
test: ["CMD-SHELL", "celery -A worker inspect ping --timeout=5 2>/dev/null | grep -q pong || exit 1"]
interval: 30s
timeout: 10s
retries: 3
start_period: 30s
volumes:
- /vmPool/r/services/chrysopedia_data:/data
- ./prompts:/prompts:ro
- ./config:/config:ro
depends_on:
chrysopedia-db:
condition: service_healthy
chrysopedia-redis:
condition: service_healthy
chrysopedia-qdrant:
condition: service_healthy
chrysopedia-ollama:
condition: service_healthy
networks:
- chrysopedia
stop_grace_period: 30s
# ── React web UI (nginx) ──
chrysopedia-web:
build:
context: .
dockerfile: docker/Dockerfile.web
container_name: chrysopedia-web-8096
restart: unless-stopped
ports:
- "0.0.0.0:8096:80"
depends_on:
- chrysopedia-api
networks:
- chrysopedia
healthcheck:
test: ["CMD-SHELL", "curl -sf http://127.0.0.1:80/ || exit 1"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
stop_grace_period: 15s
networks:
chrysopedia:
driver: bridge
ipam:
config:
- subnet: "172.32.0.0/24"

26
docker/Dockerfile.api
View file

@ -1,26 +0,0 @@
FROM python:3.12-slim
WORKDIR /app
# System deps
RUN apt-get update && apt-get install -y --no-install-recommends \
gcc libpq-dev curl \
&& rm -rf /var/lib/apt/lists/*
# Python deps (cached layer)
COPY backend/requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt
# Application code
COPY backend/ /app/
COPY prompts/ /prompts/
COPY config/ /config/
COPY alembic.ini /app/alembic.ini
COPY alembic/ /app/alembic/
EXPOSE 8000
HEALTHCHECK --interval=15s --timeout=5s --retries=3 --start-period=10s \
CMD curl -f http://localhost:8000/health || exit 1
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

16
docker/Dockerfile.web
View file

@ -1,16 +0,0 @@
FROM node:22-alpine AS build
WORKDIR /app
COPY frontend/package*.json ./
RUN npm ci --ignore-scripts
COPY frontend/ .
RUN npm run build
FROM nginx:1.27-alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY docker/nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

24
docker/nginx.conf
View file

@ -1,24 +0,0 @@
server {
listen 80;
server_name _;
root /usr/share/nginx/html;
index index.html;
# SPA fallback
location / {
try_files $uri $uri/ /index.html;
}
# API proxy
location /api/ {
proxy_pass http://chrysopedia-api:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location /health {
proxy_pass http://chrysopedia-api:8000;
}
}

13
frontend/index.html
View file

@ -1,13 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="theme-color" content="#0a0a12" />
<title>Chrysopedia</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>

1888
frontend/package-lock.json generated
View file

File diff suppressed because it is too large Load diff

23
frontend/package.json
View file

@ -1,23 +0,0 @@
{
"name": "chrysopedia-web",
"private": true,
"version": "0.1.0",
"type": "module",
"scripts": {
"dev": "vite",
"build": "tsc -b && vite build",
"preview": "vite preview"
},
"dependencies": {
"react": "^18.3.1",
"react-dom": "^18.3.1",
"react-router-dom": "^6.28.0"
},
"devDependencies": {
"@types/react": "^18.3.12",
"@types/react-dom": "^18.3.1",
"@vitejs/plugin-react": "^4.3.4",
"typescript": "~5.6.3",
"vite": "^6.0.3"
}
}

1931
frontend/src/App.css
View file

File diff suppressed because it is too large Load diff

52
frontend/src/App.tsx
View file

@ -1,52 +0,0 @@
import { Link, Navigate, Route, Routes } from "react-router-dom";
import Home from "./pages/Home";
import SearchResults from "./pages/SearchResults";
import TechniquePage from "./pages/TechniquePage";
import CreatorsBrowse from "./pages/CreatorsBrowse";
import CreatorDetail from "./pages/CreatorDetail";
import TopicsBrowse from "./pages/TopicsBrowse";
import ReviewQueue from "./pages/ReviewQueue";
import MomentDetail from "./pages/MomentDetail";
import ModeToggle from "./components/ModeToggle";
export default function App() {
return (
<div className="app">
<header className="app-header">
<Link to="/" className="app-header__brand">
<h1>Chrysopedia</h1>
</Link>
<div className="app-header__right">
<nav className="app-nav">
<Link to="/">Home</Link>
<Link to="/topics">Topics</Link>
<Link to="/creators">Creators</Link>
<Link to="/admin/review">Admin</Link>
</nav>
<ModeToggle />
</div>
</header>
<main className="app-main">
<Routes>
{/* Public routes */}
<Route path="/" element={<Home />} />
<Route path="/search" element={<SearchResults />} />
<Route path="/techniques/:slug" element={<TechniquePage />} />
{/* Browse routes */}
<Route path="/creators" element={<CreatorsBrowse />} />
<Route path="/creators/:slug" element={<CreatorDetail />} />
<Route path="/topics" element={<TopicsBrowse />} />
{/* Admin routes */}
<Route path="/admin/review" element={<ReviewQueue />} />
<Route path="/admin/review/:momentId" element={<MomentDetail />} />
{/* Fallback */}
<Route path="*" element={<Navigate to="/" replace />} />
</Routes>
</main>
</div>
);
}

193
frontend/src/api/client.ts
View file

@ -1,193 +0,0 @@
/**
* Typed API client for Chrysopedia review queue endpoints.
*
* All functions use fetch() with JSON handling and throw on non-OK responses.
* Base URL is empty so requests go through the Vite dev proxy or nginx in prod.
*/
// ── Types ───────────────────────────────────────────────────────────────────
export interface KeyMomentRead {
id: string;
source_video_id: string;
technique_page_id: string | null;
title: string;
summary: string;
start_time: number;
end_time: number;
content_type: string;
plugins: string[] | null;
raw_transcript: string | null;
review_status: string;
created_at: string;
updated_at: string;
}
export interface ReviewQueueItem extends KeyMomentRead {
video_filename: string;
creator_name: string;
}
export interface ReviewQueueResponse {
items: ReviewQueueItem[];
total: number;
offset: number;
limit: number;
}
export interface ReviewStatsResponse {
pending: number;
approved: number;
edited: number;
rejected: number;
}
export interface ReviewModeResponse {
review_mode: boolean;
}
export interface MomentEditRequest {
title?: string;
summary?: string;
start_time?: number;
end_time?: number;
content_type?: string;
plugins?: string[];
}
export interface MomentSplitRequest {
split_time: number;
}
export interface MomentMergeRequest {
target_moment_id: string;
}
export interface QueueParams {
status?: string;
offset?: number;
limit?: number;
}
// ── Helpers ──────────────────────────────────────────────────────────────────
const BASE = "/api/v1/review";
class ApiError extends Error {
constructor(
public status: number,
public detail: string,
) {
super(`API ${status}: ${detail}`);
this.name = "ApiError";
}
}
async function request<T>(url: string, init?: RequestInit): Promise<T> {
const res = await fetch(url, {
...init,
headers: {
"Content-Type": "application/json",
...init?.headers,
},
});
if (!res.ok) {
let detail = res.statusText;
try {
const body = await res.json();
detail = body.detail ?? detail;
} catch {
// body not JSON — keep statusText
}
throw new ApiError(res.status, detail);
}
return res.json() as Promise<T>;
}
// ── Queue ────────────────────────────────────────────────────────────────────
export async function fetchQueue(
params: QueueParams = {},
): Promise<ReviewQueueResponse> {
const qs = new URLSearchParams();
if (params.status) qs.set("status", params.status);
if (params.offset !== undefined) qs.set("offset", String(params.offset));
if (params.limit !== undefined) qs.set("limit", String(params.limit));
const query = qs.toString();
return request<ReviewQueueResponse>(
`${BASE}/queue${query ? `?${query}` : ""}`,
);
}
export async function fetchMoment(
momentId: string,
): Promise<ReviewQueueItem> {
return request<ReviewQueueItem>(`${BASE}/moments/${momentId}`);
}
export async function fetchStats(): Promise<ReviewStatsResponse> {
return request<ReviewStatsResponse>(`${BASE}/stats`);
}
// ── Actions ──────────────────────────────────────────────────────────────────
export async function approveMoment(id: string): Promise<KeyMomentRead> {
return request<KeyMomentRead>(`${BASE}/moments/${id}/approve`, {
method: "POST",
});
}
export async function rejectMoment(id: string): Promise<KeyMomentRead> {
return request<KeyMomentRead>(`${BASE}/moments/${id}/reject`, {
method: "POST",
});
}
export async function editMoment(
id: string,
data: MomentEditRequest,
): Promise<KeyMomentRead> {
return request<KeyMomentRead>(`${BASE}/moments/${id}`, {
method: "PUT",
body: JSON.stringify(data),
});
}
export async function splitMoment(
id: string,
splitTime: number,
): Promise<KeyMomentRead[]> {
const body: MomentSplitRequest = { split_time: splitTime };
return request<KeyMomentRead[]>(`${BASE}/moments/${id}/split`, {
method: "POST",
body: JSON.stringify(body),
});
}
export async function mergeMoments(
id: string,
targetId: string,
): Promise<KeyMomentRead> {
const body: MomentMergeRequest = { target_moment_id: targetId };
return request<KeyMomentRead>(`${BASE}/moments/${id}/merge`, {
method: "POST",
body: JSON.stringify(body),
});
}
// ── Mode ─────────────────────────────────────────────────────────────────────
export async function getReviewMode(): Promise<ReviewModeResponse> {
return request<ReviewModeResponse>(`${BASE}/mode`);
}
export async function setReviewMode(
enabled: boolean,
): Promise<ReviewModeResponse> {
return request<ReviewModeResponse>(`${BASE}/mode`, {
method: "PUT",
body: JSON.stringify({ review_mode: enabled }),
});
}

274
frontend/src/api/public-client.ts
View file

@ -1,274 +0,0 @@
/**
* Typed API client for Chrysopedia public endpoints.
*
* Mirrors backend schemas: SearchResponse, TechniquePageDetail, TopicCategory, CreatorBrowseItem.
* Uses the same request<T> pattern as client.ts.
*/
// ── Types ───────────────────────────────────────────────────────────────────
export interface SearchResultItem {
title: string;
slug: string;
type: string;
score: number;
summary: string;
creator_name: string;
creator_slug: string;
topic_category: string;
topic_tags: string[];
}
export interface SearchResponse {
items: SearchResultItem[];
total: number;
query: string;
fallback_used: boolean;
}
export interface KeyMomentSummary {
id: string;
title: string;
summary: string;
start_time: number;
end_time: number;
content_type: string;
plugins: string[] | null;
video_filename: string;
}
export interface CreatorInfo {
name: string;
slug: string;
genres: string[] | null;
}
export interface RelatedLinkItem {
target_title: string;
target_slug: string;
relationship: string;
}
export interface TechniquePageDetail {
id: string;
title: string;
slug: string;
topic_category: string;
topic_tags: string[] | null;
summary: string | null;
body_sections: Record<string, unknown> | null;
signal_chains: unknown[] | null;
plugins: string[] | null;
creator_id: string;
source_quality: string | null;
view_count: number;
review_status: string;
created_at: string;
updated_at: string;
key_moments: KeyMomentSummary[];
creator_info: CreatorInfo | null;
related_links: RelatedLinkItem[];
version_count: number;
}
export interface TechniquePageVersionSummary {
version_number: number;
created_at: string;
pipeline_metadata: Record<string, unknown> | null;
}
export interface TechniquePageVersionListResponse {
items: TechniquePageVersionSummary[];
total: number;
}
export interface TechniqueListItem {
id: string;
title: string;
slug: string;
topic_category: string;
topic_tags: string[] | null;
summary: string | null;
creator_id: string;
source_quality: string | null;
view_count: number;
review_status: string;
created_at: string;
updated_at: string;
}
export interface TechniqueListResponse {
items: TechniqueListItem[];
total: number;
offset: number;
limit: number;
}
export interface TopicSubTopic {
name: string;
technique_count: number;
creator_count: number;
}
export interface TopicCategory {
name: string;
description: string;
sub_topics: TopicSubTopic[];
}
export interface CreatorBrowseItem {
id: string;
name: string;
slug: string;
genres: string[] | null;
folder_name: string;
view_count: number;
created_at: string;
updated_at: string;
technique_count: number;
video_count: number;
}
export interface CreatorBrowseResponse {
items: CreatorBrowseItem[];
total: number;
offset: number;
limit: number;
}
export interface CreatorDetailResponse {
id: string;
name: string;
slug: string;
genres: string[] | null;
folder_name: string;
view_count: number;
created_at: string;
updated_at: string;
video_count: number;
}
// ── Helpers ──────────────────────────────────────────────────────────────────
const BASE = "/api/v1";
class ApiError extends Error {
constructor(
public status: number,
public detail: string,
) {
super(`API ${status}: ${detail}`);
this.name = "ApiError";
}
}
async function request<T>(url: string, init?: RequestInit): Promise<T> {
const res = await fetch(url, {
...init,
headers: {
"Content-Type": "application/json",
...init?.headers,
},
});
if (!res.ok) {
let detail = res.statusText;
try {
const body: unknown = await res.json();
if (typeof body === "object" && body !== null && "detail" in body) {
const d = (body as { detail: unknown }).detail;
detail = typeof d === "string" ? d : Array.isArray(d) ? d.map((e: any) => e.msg || JSON.stringify(e)).join("; ") : JSON.stringify(d);
}
} catch {
// body not JSON — keep statusText
}
throw new ApiError(res.status, detail);
}
return res.json() as Promise<T>;
}
// ── Search ───────────────────────────────────────────────────────────────────
export async function searchApi(
q: string,
scope?: string,
limit?: number,
): Promise<SearchResponse> {
const qs = new URLSearchParams({ q });
if (scope) qs.set("scope", scope);
if (limit !== undefined) qs.set("limit", String(limit));
return request<SearchResponse>(`${BASE}/search?${qs.toString()}`);
}
// ── Techniques ───────────────────────────────────────────────────────────────
export interface TechniqueListParams {
limit?: number;
offset?: number;
category?: string;
creator_slug?: string;
}
export async function fetchTechniques(
params: TechniqueListParams = {},
): Promise<TechniqueListResponse> {
const qs = new URLSearchParams();
if (params.limit !== undefined) qs.set("limit", String(params.limit));
if (params.offset !== undefined) qs.set("offset", String(params.offset));
if (params.category) qs.set("category", params.category);
if (params.creator_slug) qs.set("creator_slug", params.creator_slug);
const query = qs.toString();
return request<TechniqueListResponse>(
`${BASE}/techniques${query ? `?${query}` : ""}`,
);
}
export async function fetchTechnique(
slug: string,
): Promise<TechniquePageDetail> {
return request<TechniquePageDetail>(`${BASE}/techniques/${slug}`);
}
export async function fetchTechniqueVersions(
slug: string,
): Promise<TechniquePageVersionListResponse> {
return request<TechniquePageVersionListResponse>(
`${BASE}/techniques/${slug}/versions`,
);
}
// ── Topics ───────────────────────────────────────────────────────────────────
export async function fetchTopics(): Promise<TopicCategory[]> {
return request<TopicCategory[]>(`${BASE}/topics`);
}
// ── Creators ─────────────────────────────────────────────────────────────────
export interface CreatorListParams {
sort?: string;
genre?: string;
limit?: number;
offset?: number;
}
export async function fetchCreators(
params: CreatorListParams = {},
): Promise<CreatorBrowseResponse> {
const qs = new URLSearchParams();
if (params.sort) qs.set("sort", params.sort);
if (params.genre) qs.set("genre", params.genre);
if (params.limit !== undefined) qs.set("limit", String(params.limit));
if (params.offset !== undefined) qs.set("offset", String(params.offset));
const query = qs.toString();
return request<CreatorBrowseResponse>(
`${BASE}/creators${query ? `?${query}` : ""}`,
);
}
export async function fetchCreator(
slug: string,
): Promise<CreatorDetailResponse> {
return request<CreatorDetailResponse>(`${BASE}/creators/${slug}`);
}

59
frontend/src/components/ModeToggle.tsx
View file

@ -1,59 +0,0 @@
/**
* Review / Auto mode toggle switch.
*
* Reads and writes mode via getReviewMode / setReviewMode API.
* Green dot = review mode active; amber = auto mode.
*/
import { useEffect, useState } from "react";
import { getReviewMode, setReviewMode } from "../api/client";
export default function ModeToggle() {
const [reviewMode, setReviewModeState] = useState<boolean | null>(null);
const [toggling, setToggling] = useState(false);
useEffect(() => {
let cancelled = false;
getReviewMode()
.then((res) => {
if (!cancelled) setReviewModeState(res.review_mode);
})
.catch(() => {
// silently fail — mode indicator will just stay hidden
});
return () => { cancelled = true; };
}, []);
async function handleToggle() {
if (reviewMode === null || toggling) return;
setToggling(true);
try {
const res = await setReviewMode(!reviewMode);
setReviewModeState(res.review_mode);
} catch {
// swallow — leave previous state
} finally {
setToggling(false);
}
}
if (reviewMode === null) return null;
return (
<div className="mode-toggle">
<span
className={`mode-toggle__dot ${reviewMode ? "mode-toggle__dot--review" : "mode-toggle__dot--auto"}`}
/>
<span className="mode-toggle__label">
{reviewMode ? "Review Mode" : "Auto Mode"}
</span>
<button
type="button"
className={`mode-toggle__switch ${reviewMode ? "mode-toggle__switch--active" : ""}`}
onClick={handleToggle}
disabled={toggling}
aria-label={`Switch to ${reviewMode ? "auto" : "review"} mode`}
/>
</div>
);
}

19
frontend/src/components/StatusBadge.tsx
View file

@ -1,19 +0,0 @@
/**
* Reusable status badge with color coding.
*
* Maps review_status values to colored pill shapes:
* pending → amber, approved → green, edited → blue, rejected → red
*/
interface StatusBadgeProps {
status: string;
}
export default function StatusBadge({ status }: StatusBadgeProps) {
const normalized = status.toLowerCase();
return (
<span className={`badge badge--${normalized}`}>
{normalized}
</span>
);
}

13
frontend/src/main.tsx
View file

@ -1,13 +0,0 @@
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router-dom";
import App from "./App";
import "./App.css";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<BrowserRouter>
<App />
</BrowserRouter>
</StrictMode>,
);

160
frontend/src/pages/CreatorDetail.tsx
View file

@ -1,160 +0,0 @@
/**
* Creator detail page.
*
* Shows creator info (name, genres, video/technique counts) and lists
* their technique pages with links. Handles loading and 404 states.
*/
import { useEffect, useState } from "react";
import { Link, useParams } from "react-router-dom";
import {
fetchCreator,
fetchTechniques,
type CreatorDetailResponse,
type TechniqueListItem,
} from "../api/public-client";
export default function CreatorDetail() {
const { slug } = useParams<{ slug: string }>();
const [creator, setCreator] = useState<CreatorDetailResponse | null>(null);
const [techniques, setTechniques] = useState<TechniqueListItem[]>([]);
const [loading, setLoading] = useState(true);
const [notFound, setNotFound] = useState(false);
const [error, setError] = useState<string | null>(null);
useEffect(() => {
if (!slug) return;
let cancelled = false;
setLoading(true);
setNotFound(false);
setError(null);
void (async () => {
try {
const [creatorData, techData] = await Promise.all([
fetchCreator(slug),
fetchTechniques({ creator_slug: slug, limit: 100 }),
]);
if (!cancelled) {
setCreator(creatorData);
setTechniques(techData.items);
}
} catch (err) {
if (!cancelled) {
if (err instanceof Error && err.message.includes("404")) {
setNotFound(true);
} else {
setError(
err instanceof Error ? err.message : "Failed to load creator",
);
}
}
} finally {
if (!cancelled) setLoading(false);
}
})();
return () => {
cancelled = true;
};
}, [slug]);
if (loading) {
return <div className="loading">Loading creator…</div>;
}
if (notFound) {
return (
<div className="technique-404">
<h2>Creator Not Found</h2>
<p>The creator "{slug}" doesn't exist.</p>
<Link to="/creators" className="btn">
Back to Creators
</Link>
</div>
);
}
if (error || !creator) {
return (
<div className="loading error-text">
Error: {error ?? "Unknown error"}
</div>
);
}
return (
<div className="creator-detail">
<Link to="/creators" className="back-link">
← Creators
</Link>
{/* Header */}
<header className="creator-detail__header">
<h1 className="creator-detail__name">{creator.name}</h1>
<div className="creator-detail__meta">
{creator.genres && creator.genres.length > 0 && (
<span className="creator-detail__genres">
{creator.genres.map((g) => (
<span key={g} className="pill">
{g}
</span>
))}
</span>
)}
<span className="creator-detail__stats">
{creator.video_count} video{creator.video_count !== 1 ? "s" : ""}
<span className="queue-card__separator">·</span>
{creator.view_count.toLocaleString()} views
</span>
</div>
</header>
{/* Technique pages */}
<section className="creator-techniques">
<h2 className="creator-techniques__title">
Techniques ({techniques.length})
</h2>
{techniques.length === 0 ? (
<div className="empty-state">No techniques yet.</div>
) : (
<div className="creator-techniques__list">
{techniques.map((t) => (
<Link
key={t.id}
to={`/techniques/${t.slug}`}
className="creator-technique-card"
>
<span className="creator-technique-card__title">
{t.title}
</span>
<span className="creator-technique-card__meta">
<span className="badge badge--category">
{t.topic_category}
</span>
{t.topic_tags && t.topic_tags.length > 0 && (
<span className="creator-technique-card__tags">
{t.topic_tags.map((tag) => (
<span key={tag} className="pill">
{tag}
</span>
))}
</span>
)}
</span>
{t.summary && (
<span className="creator-technique-card__summary">
{t.summary.length > 120
? `${t.summary.slice(0, 120)}…`
: t.summary}
</span>
)}
</Link>
))}
</div>
)}
</section>
</div>
);
}

185
frontend/src/pages/CreatorsBrowse.tsx
View file

@ -1,185 +0,0 @@
/**
* Creators browse page (R007, R014).
*
* - Default sort: random (creator equity — no featured/highlighted creators)
* - Genre filter pills from canonical taxonomy
* - Type-to-narrow client-side name filter
* - Sort toggle: Random | Alphabetical | Views
* - Click row → /creators/{slug}
*/
import { useEffect, useState } from "react";
import { Link } from "react-router-dom";
import {
fetchCreators,
type CreatorBrowseItem,
} from "../api/public-client";
const GENRES = [
"Bass music",
"Drum & bass",
"Dubstep",
"Halftime",
"House",
"Techno",
"IDM",
"Glitch",
"Downtempo",
"Neuro",
"Ambient",
"Experimental",
"Cinematic",
];
type SortMode = "random" | "alpha" | "views";
const SORT_OPTIONS: { value: SortMode; label: string }[] = [
{ value: "random", label: "Random" },
{ value: "alpha", label: "A–Z" },
{ value: "views", label: "Views" },
];
export default function CreatorsBrowse() {
const [creators, setCreators] = useState<CreatorBrowseItem[]>([]);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const [sort, setSort] = useState<SortMode>("random");
const [genreFilter, setGenreFilter] = useState<string | null>(null);
const [nameFilter, setNameFilter] = useState("");
useEffect(() => {
let cancelled = false;
setLoading(true);
setError(null);
void (async () => {
try {
const res = await fetchCreators({
sort,
genre: genreFilter ?? undefined,
limit: 100,
});
if (!cancelled) setCreators(res.items);
} catch (err) {
if (!cancelled) {
setError(
err instanceof Error ? err.message : "Failed to load creators",
);
}
} finally {
if (!cancelled) setLoading(false);
}
})();
return () => {
cancelled = true;
};
}, [sort, genreFilter]);
// Client-side name filtering
const displayed = nameFilter
? creators.filter((c) =>
c.name.toLowerCase().includes(nameFilter.toLowerCase()),
)
: creators;
return (
<div className="creators-browse">
<h2 className="creators-browse__title">Creators</h2>
<p className="creators-browse__subtitle">
Discover creators and their technique libraries
</p>
{/* Controls row */}
<div className="creators-controls">
{/* Sort toggle */}
<div className="sort-toggle" role="group" aria-label="Sort creators">
{SORT_OPTIONS.map((opt) => (
<button
key={opt.value}
className={`sort-toggle__btn${sort === opt.value ? " sort-toggle__btn--active" : ""}`}
onClick={() => setSort(opt.value)}
aria-pressed={sort === opt.value}
>
{opt.label}
</button>
))}
</div>
{/* Name filter */}
<input
type="search"
className="creators-filter-input"
placeholder="Filter by name…"
value={nameFilter}
onChange={(e) => setNameFilter(e.target.value)}
aria-label="Filter creators by name"
/>
</div>
{/* Genre pills */}
<div className="genre-pills" role="group" aria-label="Filter by genre">
<button
className={`genre-pill${genreFilter === null ? " genre-pill--active" : ""}`}
onClick={() => setGenreFilter(null)}
>
All
</button>
{GENRES.map((g) => (
<button
key={g}
className={`genre-pill${genreFilter === g ? " genre-pill--active" : ""}`}
onClick={() => setGenreFilter(genreFilter === g ? null : g)}
>
{g}
</button>
))}
</div>
{/* Content */}
{loading ? (
<div className="loading">Loading creators…</div>
) : error ? (
<div className="loading error-text">Error: {error}</div>
) : displayed.length === 0 ? (
<div className="empty-state">
{nameFilter
? `No creators matching "${nameFilter}"`
: "No creators found."}
</div>
) : (
<div className="creators-list">
{displayed.map((creator) => (
<Link
key={creator.id}
to={`/creators/${creator.slug}`}
className="creator-row"
>
<span className="creator-row__name">{creator.name}</span>
<span className="creator-row__genres">
{creator.genres?.map((g) => (
<span key={g} className="pill">
{g}
</span>
))}
</span>
<span className="creator-row__stats">
<span className="creator-row__stat">
{creator.technique_count} technique{creator.technique_count !== 1 ? "s" : ""}
</span>
<span className="creator-row__separator">·</span>
<span className="creator-row__stat">
{creator.video_count} video{creator.video_count !== 1 ? "s" : ""}
</span>
<span className="creator-row__separator">·</span>
<span className="creator-row__stat">
{creator.view_count.toLocaleString()} views
</span>
</span>
</Link>
))}
</div>
)}
</div>
);
}

222
frontend/src/pages/Home.tsx
View file

@ -1,222 +0,0 @@
/**
* Home / landing page.
*
* Prominent search bar with 300ms debounced typeahead (top 5 results after 2+ chars),
* navigation cards for Topics and Creators, and a "Recently Added" section.
*/
import { useCallback, useEffect, useRef, useState } from "react";
import { Link, useNavigate } from "react-router-dom";
import {
searchApi,
fetchTechniques,
type SearchResultItem,
type TechniqueListItem,
} from "../api/public-client";
export default function Home() {
const [query, setQuery] = useState("");
const [suggestions, setSuggestions] = useState<SearchResultItem[]>([]);
const [showDropdown, setShowDropdown] = useState(false);
const [recent, setRecent] = useState<TechniqueListItem[]>([]);
const [recentLoading, setRecentLoading] = useState(true);
const navigate = useNavigate();
const inputRef = useRef<HTMLInputElement>(null);
const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const dropdownRef = useRef<HTMLDivElement>(null);
// Auto-focus search on mount
useEffect(() => {
inputRef.current?.focus();
}, []);
// Load recently added techniques
useEffect(() => {
let cancelled = false;
void (async () => {
try {
const res = await fetchTechniques({ limit: 5 });
if (!cancelled) setRecent(res.items);
} catch {
// silently ignore — not critical
} finally {
if (!cancelled) setRecentLoading(false);
}
})();
return () => {
cancelled = true;
};
}, []);
// Close dropdown on outside click
useEffect(() => {
function handleClick(e: MouseEvent) {
if (
dropdownRef.current &&
!dropdownRef.current.contains(e.target as Node)
) {
setShowDropdown(false);
}
}
document.addEventListener("mousedown", handleClick);
return () => document.removeEventListener("mousedown", handleClick);
}, []);
// Debounced typeahead
const handleInputChange = useCallback(
(value: string) => {
setQuery(value);
if (debounceRef.current) clearTimeout(debounceRef.current);
if (value.length < 2) {
setSuggestions([]);
setShowDropdown(false);
return;
}
debounceRef.current = setTimeout(() => {
void (async () => {
try {
const res = await searchApi(value, undefined, 5);
setSuggestions(res.items);
setShowDropdown(res.items.length > 0);
} catch {
setSuggestions([]);
setShowDropdown(false);
}
})();
}, 300);
},
[],
);
function handleSubmit(e: React.FormEvent) {
e.preventDefault();
if (query.trim()) {
setShowDropdown(false);
navigate(`/search?q=${encodeURIComponent(query.trim())}`);
}
}
function handleKeyDown(e: React.KeyboardEvent) {
if (e.key === "Escape") {
setShowDropdown(false);
}
}
return (
<div className="home">
{/* Hero search */}
<section className="home-hero">
<h2 className="home-hero__title">Chrysopedia</h2>
<p className="home-hero__subtitle">
Search techniques, key moments, and creators
</p>
<div className="search-container" ref={dropdownRef}>
<form onSubmit={handleSubmit} className="search-form search-form--hero">
<input
ref={inputRef}
type="search"
className="search-input search-input--hero"
placeholder="Search techniques…"
value={query}
onChange={(e) => handleInputChange(e.target.value)}
onFocus={() => {
if (suggestions.length > 0) setShowDropdown(true);
}}
onKeyDown={handleKeyDown}
aria-label="Search techniques"
/>
<button type="submit" className="btn btn--search">
Search
</button>
</form>
{showDropdown && suggestions.length > 0 && (
<div className="typeahead-dropdown">
{suggestions.map((item) => (
<Link
key={`${item.type}-${item.slug}`}
to={`/techniques/${item.slug}`}
className="typeahead-item"
onClick={() => setShowDropdown(false)}
>
<span className="typeahead-item__title">{item.title}</span>
<span className="typeahead-item__meta">
<span className={`typeahead-item__type typeahead-item__type--${item.type}`}>
{item.type === "technique_page" ? "Technique" : "Key Moment"}
</span>
{item.creator_name && (
<span className="typeahead-item__creator">
{item.creator_name}
</span>
)}
</span>
</Link>
))}
<Link
to={`/search?q=${encodeURIComponent(query)}`}
className="typeahead-see-all"
onClick={() => setShowDropdown(false)}
>
See all results for "{query}"
</Link>
</div>
)}
</div>
</section>
{/* Navigation cards */}
<section className="nav-cards">
<Link to="/topics" className="nav-card">
<h3 className="nav-card__title">Topics</h3>
<p className="nav-card__desc">
Browse techniques organized by category and sub-topic
</p>
</Link>
<Link to="/creators" className="nav-card">
<h3 className="nav-card__title">Creators</h3>
<p className="nav-card__desc">
Discover creators and their technique libraries
</p>
</Link>
</section>
{/* Recently Added */}
<section className="recent-section">
<h3 className="recent-section__title">Recently Added</h3>
{recentLoading ? (
<div className="loading">Loading…</div>
) : recent.length === 0 ? (
<div className="empty-state">No techniques yet.</div>
) : (
<div className="recent-list">
{recent.map((t) => (
<Link
key={t.id}
to={`/techniques/${t.slug}`}
className="recent-card"
>
<span className="recent-card__title">{t.title}</span>
<span className="recent-card__meta">
<span className="badge badge--category">
{t.topic_category}
</span>
{t.summary && (
<span className="recent-card__summary">
{t.summary.length > 100
? `${t.summary.slice(0, 100)}…`
: t.summary}
</span>
)}
</span>
</Link>
))}
</div>
)}
</section>
</div>
);
}

454
frontend/src/pages/MomentDetail.tsx
View file

@ -1,454 +0,0 @@
/**
* Moment review detail page.
*
* Displays full moment data with action buttons:
* - Approve / Reject → navigate back to queue
* - Edit → inline edit mode for title, summary, content_type
* - Split → dialog with timestamp input
* - Merge → dialog with moment selector
*/
import { useCallback, useEffect, useState } from "react";
import { useParams, useNavigate, Link } from "react-router-dom";
import {
fetchMoment,
fetchQueue,
approveMoment,
rejectMoment,
editMoment,
splitMoment,
mergeMoments,
type ReviewQueueItem,
} from "../api/client";
import StatusBadge from "../components/StatusBadge";
function formatTime(seconds: number): string {
const m = Math.floor(seconds / 60);
const s = Math.floor(seconds % 60);
return `${m}:${s.toString().padStart(2, "0")}`;
}
export default function MomentDetail() {
const { momentId } = useParams<{ momentId: string }>();
const navigate = useNavigate();
// ── Data state ──
const [moment, setMoment] = useState<ReviewQueueItem | null>(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const [actionError, setActionError] = useState<string | null>(null);
const [acting, setActing] = useState(false);
// ── Edit state ──
const [editing, setEditing] = useState(false);
const [editTitle, setEditTitle] = useState("");
const [editSummary, setEditSummary] = useState("");
const [editContentType, setEditContentType] = useState("");
// ── Split state ──
const [showSplit, setShowSplit] = useState(false);
const [splitTime, setSplitTime] = useState("");
// ── Merge state ──
const [showMerge, setShowMerge] = useState(false);
const [mergeCandidates, setMergeCandidates] = useState<ReviewQueueItem[]>([]);
const [mergeTargetId, setMergeTargetId] = useState("");
const loadMoment = useCallback(async () => {
if (!momentId) return;
setLoading(true);
setError(null);
try {
// Fetch all moments and find the one matching our ID
const found = await fetchMoment(momentId);
setMoment(found);
setEditTitle(found.title);
setEditSummary(found.summary);
setEditContentType(found.content_type);
} catch (err) {
setError(err instanceof Error ? err.message : "Failed to load moment");
} finally {
setLoading(false);
}
}, [momentId]);
useEffect(() => {
void loadMoment();
}, [loadMoment]);
// ── Action handlers ──
async function handleApprove() {
if (!momentId || acting) return;
setActing(true);
setActionError(null);
try {
await approveMoment(momentId);
navigate("/admin/review");
} catch (err) {
setActionError(err instanceof Error ? err.message : "Approve failed");
} finally {
setActing(false);
}
}
async function handleReject() {
if (!momentId || acting) return;
setActing(true);
setActionError(null);
try {
await rejectMoment(momentId);
navigate("/admin/review");
} catch (err) {
setActionError(err instanceof Error ? err.message : "Reject failed");
} finally {
setActing(false);
}
}
function startEdit() {
if (!moment) return;
setEditTitle(moment.title);
setEditSummary(moment.summary);
setEditContentType(moment.content_type);
setEditing(true);
setActionError(null);
}
async function handleEditSave() {
if (!momentId || acting) return;
setActing(true);
setActionError(null);
try {
await editMoment(momentId, {
title: editTitle,
summary: editSummary,
content_type: editContentType,
});
setEditing(false);
await loadMoment();
} catch (err) {
setActionError(err instanceof Error ? err.message : "Edit failed");
} finally {
setActing(false);
}
}
function openSplitDialog() {
if (!moment) return;
setSplitTime("");
setShowSplit(true);
setActionError(null);
}
async function handleSplit() {
if (!momentId || !moment || acting) return;
const t = parseFloat(splitTime);
if (isNaN(t) || t <= moment.start_time || t >= moment.end_time) {
setActionError(
`Split time must be between ${formatTime(moment.start_time)} and ${formatTime(moment.end_time)}`
);
return;
}
setActing(true);
setActionError(null);
try {
await splitMoment(momentId, t);
setShowSplit(false);
navigate("/admin/review");
} catch (err) {
setActionError(err instanceof Error ? err.message : "Split failed");
} finally {
setActing(false);
}
}
async function openMergeDialog() {
if (!moment) return;
setShowMerge(true);
setMergeTargetId("");
setActionError(null);
try {
// Load moments from the same video for merge candidates
const res = await fetchQueue({ limit: 100 });
const candidates = res.items.filter(
(m) => m.source_video_id === moment.source_video_id && m.id !== moment.id
);
setMergeCandidates(candidates);
} catch {
setMergeCandidates([]);
}
}
async function handleMerge() {
if (!momentId || !mergeTargetId || acting) return;
setActing(true);
setActionError(null);
try {
await mergeMoments(momentId, mergeTargetId);
setShowMerge(false);
navigate("/admin/review");
} catch (err) {
setActionError(err instanceof Error ? err.message : "Merge failed");
} finally {
setActing(false);
}
}
// ── Render ──
if (loading) return <div className="loading">Loading…</div>;
if (error)
return (
<div>
<Link to="/admin/review" className="back-link">
← Back to queue
</Link>
<div className="loading error-text">Error: {error}</div>
</div>
);
if (!moment) return null;
return (
<div className="detail-page">
<Link to="/admin/review" className="back-link">
← Back to queue
</Link>
{/* ── Moment header ── */}
<div className="detail-header">
<h2>{moment.title}</h2>
<StatusBadge status={moment.review_status} />
</div>
{/* ── Moment data ── */}
<div className="card detail-card">
<div className="detail-field">
<label>Content Type</label>
<span>{moment.content_type}</span>
</div>
<div className="detail-field">
<label>Time Range</label>
<span>
{formatTime(moment.start_time)} – {formatTime(moment.end_time)}
</span>
</div>
<div className="detail-field">
<label>Source</label>
<span>
{moment.creator_name} · {moment.video_filename}
</span>
</div>
{moment.plugins && moment.plugins.length > 0 && (
<div className="detail-field">
<label>Plugins</label>
<span>{moment.plugins.join(", ")}</span>
</div>
)}
<div className="detail-field detail-field--full">
<label>Summary</label>
<p>{moment.summary}</p>
</div>
{moment.raw_transcript && (
<div className="detail-field detail-field--full">
<label>Raw Transcript</label>
<p className="detail-transcript">{moment.raw_transcript}</p>
</div>
)}
</div>
{/* ── Action error ── */}
{actionError && <div className="action-error">{actionError}</div>}
{/* ── Edit mode ── */}
{editing ? (
<div className="card edit-form">
<h3>Edit Moment</h3>
<div className="edit-field">
<label htmlFor="edit-title">Title</label>
<input
id="edit-title"
type="text"
value={editTitle}
onChange={(e) => setEditTitle(e.target.value)}
/>
</div>
<div className="edit-field">
<label htmlFor="edit-summary">Summary</label>
<textarea
id="edit-summary"
rows={4}
value={editSummary}
onChange={(e) => setEditSummary(e.target.value)}
/>
</div>
<div className="edit-field">
<label htmlFor="edit-content-type">Content Type</label>
<input
id="edit-content-type"
type="text"
value={editContentType}
onChange={(e) => setEditContentType(e.target.value)}
/>
</div>
<div className="edit-actions">
<button
type="button"
className="btn btn--approve"
onClick={handleEditSave}
disabled={acting}
>
Save
</button>
<button
type="button"
className="btn"
onClick={() => setEditing(false)}
disabled={acting}
>
Cancel
</button>
</div>
</div>
) : (
/* ── Action buttons ── */
<div className="action-bar">
<button
type="button"
className="btn btn--approve"
onClick={handleApprove}
disabled={acting}
>
✓ Approve
</button>
<button
type="button"
className="btn btn--reject"
onClick={handleReject}
disabled={acting}
>
✕ Reject
</button>
<button
type="button"
className="btn"
onClick={startEdit}
disabled={acting}
>
✎ Edit
</button>
<button
type="button"
className="btn"
onClick={openSplitDialog}
disabled={acting}
>
✂ Split
</button>
<button
type="button"
className="btn"
onClick={openMergeDialog}
disabled={acting}
>
⊕ Merge
</button>
</div>
)}
{/* ── Split dialog ── */}
{showSplit && (
<div className="dialog-overlay" onClick={() => setShowSplit(false)}>
<div className="dialog" onClick={(e) => e.stopPropagation()}>
<h3>Split Moment</h3>
<p className="dialog__hint">
Enter a timestamp (in seconds) between{" "}
{formatTime(moment.start_time)} and {formatTime(moment.end_time)}.
</p>
<div className="edit-field">
<label htmlFor="split-time">Split Time (seconds)</label>
<input
id="split-time"
type="number"
step="0.1"
min={moment.start_time}
max={moment.end_time}
value={splitTime}
onChange={(e) => setSplitTime(e.target.value)}
placeholder={`e.g. ${((moment.start_time + moment.end_time) / 2).toFixed(1)}`}
/>
</div>
<div className="dialog__actions">
<button
type="button"
className="btn btn--approve"
onClick={handleSplit}
disabled={acting}
>
Split
</button>
<button
type="button"
className="btn"
onClick={() => setShowSplit(false)}
>
Cancel
</button>
</div>
</div>
</div>
)}
{/* ── Merge dialog ── */}
{showMerge && (
<div className="dialog-overlay" onClick={() => setShowMerge(false)}>
<div className="dialog" onClick={(e) => e.stopPropagation()}>
<h3>Merge Moment</h3>
<p className="dialog__hint">
Select another moment from the same video to merge with.
</p>
{mergeCandidates.length === 0 ? (
<p className="dialog__hint">
No other moments from this video available.
</p>
) : (
<div className="edit-field">
<label htmlFor="merge-target">Target Moment</label>
<select
id="merge-target"
value={mergeTargetId}
onChange={(e) => setMergeTargetId(e.target.value)}
>
<option value="">Select a moment…</option>
{mergeCandidates.map((c) => (
<option key={c.id} value={c.id}>
{c.title} ({formatTime(c.start_time)} –{" "}
{formatTime(c.end_time)})
</option>
))}
</select>
</div>
)}
<div className="dialog__actions">
<button
type="button"
className="btn btn--approve"
onClick={handleMerge}
disabled={acting || !mergeTargetId}
>
Merge
</button>
<button
type="button"
className="btn"
onClick={() => setShowMerge(false)}
>
Cancel
</button>
</div>
</div>
</div>
)}
</div>
);
}

189
frontend/src/pages/ReviewQueue.tsx
View file

@ -1,189 +0,0 @@
/**
* Admin review queue page.
*
* Shows stats bar, status filter tabs, paginated moment list, and mode toggle.
*/
import { useCallback, useEffect, useState } from "react";
import { Link } from "react-router-dom";
import {
fetchQueue,
fetchStats,
type ReviewQueueItem,
type ReviewStatsResponse,
} from "../api/client";
import StatusBadge from "../components/StatusBadge";
import ModeToggle from "../components/ModeToggle";
const PAGE_SIZE = 20;
type StatusFilter = "all" | "pending" | "approved" | "edited" | "rejected";
const FILTERS: { label: string; value: StatusFilter }[] = [
{ label: "All", value: "all" },
{ label: "Pending", value: "pending" },
{ label: "Approved", value: "approved" },
{ label: "Edited", value: "edited" },
{ label: "Rejected", value: "rejected" },
];
function formatTime(seconds: number): string {
const m = Math.floor(seconds / 60);
const s = Math.floor(seconds % 60);
return `${m}:${s.toString().padStart(2, "0")}`;
}
export default function ReviewQueue() {
const [items, setItems] = useState<ReviewQueueItem[]>([]);
const [stats, setStats] = useState<ReviewStatsResponse | null>(null);
const [total, setTotal] = useState(0);
const [offset, setOffset] = useState(0);
const [filter, setFilter] = useState<StatusFilter>("pending");
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const loadData = useCallback(async (status: StatusFilter, page: number) => {
setLoading(true);
setError(null);
try {
const [queueRes, statsRes] = await Promise.all([
fetchQueue({
status: status === "all" ? undefined : status,
offset: page,
limit: PAGE_SIZE,
}),
fetchStats(),
]);
setItems(queueRes.items);
setTotal(queueRes.total);
setStats(statsRes);
} catch (err) {
setError(err instanceof Error ? err.message : "Failed to load queue");
} finally {
setLoading(false);
}
}, []);
useEffect(() => {
void loadData(filter, offset);
}, [filter, offset, loadData]);
function handleFilterChange(f: StatusFilter) {
setFilter(f);
setOffset(0);
}
const hasNext = offset + PAGE_SIZE < total;
const hasPrev = offset > 0;
return (
<div>
{/* ── Header row with title and mode toggle ── */}
<div className="queue-header">
<h2>Review Queue</h2>
<ModeToggle />
</div>
{/* ── Stats bar ── */}
{stats && (
<div className="stats-bar">
<div className="stats-card stats-card--pending">
<span className="stats-card__count">{stats.pending}</span>
<span className="stats-card__label">Pending</span>
</div>
<div className="stats-card stats-card--approved">
<span className="stats-card__count">{stats.approved}</span>
<span className="stats-card__label">Approved</span>
</div>
<div className="stats-card stats-card--edited">
<span className="stats-card__count">{stats.edited}</span>
<span className="stats-card__label">Edited</span>
</div>
<div className="stats-card stats-card--rejected">
<span className="stats-card__count">{stats.rejected}</span>
<span className="stats-card__label">Rejected</span>
</div>
</div>
)}
{/* ── Filter tabs ── */}
<div className="filter-tabs">
{FILTERS.map((f) => (
<button
key={f.value}
type="button"
className={`filter-tab ${filter === f.value ? "filter-tab--active" : ""}`}
onClick={() => handleFilterChange(f.value)}
>
{f.label}
</button>
))}
</div>
{/* ── Queue list ── */}
{loading ? (
<div className="loading">Loading…</div>
) : error ? (
<div className="loading error-text">Error: {error}</div>
) : items.length === 0 ? (
<div className="empty-state">
<p>No moments match the "{filter}" filter.</p>
</div>
) : (
<>
<div className="queue-list">
{items.map((item) => (
<Link
key={item.id}
to={`/admin/review/${item.id}`}
className="queue-card"
>
<div className="queue-card__header">
<span className="queue-card__title">{item.title}</span>
<StatusBadge status={item.review_status} />
</div>
<p className="queue-card__summary">
{item.summary.length > 150
? `${item.summary.slice(0, 150)}…`
: item.summary}
</p>
<div className="queue-card__meta">
<span>{item.creator_name}</span>
<span className="queue-card__separator">·</span>
<span>{item.video_filename}</span>
<span className="queue-card__separator">·</span>
<span>
{formatTime(item.start_time)} – {formatTime(item.end_time)}
</span>
</div>
</Link>
))}
</div>
{/* ── Pagination ── */}
<div className="pagination">
<button
type="button"
className="btn"
disabled={!hasPrev}
onClick={() => setOffset(Math.max(0, offset - PAGE_SIZE))}
>
← Previous
</button>
<span className="pagination__info">
{offset + 1}–{Math.min(offset + PAGE_SIZE, total)} of {total}
</span>
<button
type="button"
className="btn"
disabled={!hasNext}
onClick={() => setOffset(offset + PAGE_SIZE)}
>
Next →
</button>
</div>
</>
)}
</div>
);
}

184
frontend/src/pages/SearchResults.tsx
View file

@ -1,184 +0,0 @@
/**
* Full search results page.
*
* Reads `q` from URL search params, calls searchApi, groups results by type
* (technique_pages first, then key_moments). Shows fallback banner when
* keyword search was used.
*/
import { useCallback, useEffect, useRef, useState } from "react";
import { Link, useSearchParams, useNavigate } from "react-router-dom";
import { searchApi, type SearchResultItem } from "../api/public-client";
export default function SearchResults() {
const [searchParams] = useSearchParams();
const navigate = useNavigate();
const q = searchParams.get("q") ?? "";
const [results, setResults] = useState<SearchResultItem[]>([]);
const [fallbackUsed, setFallbackUsed] = useState(false);
const [loading, setLoading] = useState(false);
const [error, setError] = useState<string | null>(null);
const [localQuery, setLocalQuery] = useState(q);
const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const doSearch = useCallback(async (query: string) => {
if (!query.trim()) {
setResults([]);
setFallbackUsed(false);
return;
}
setLoading(true);
setError(null);
try {
const res = await searchApi(query.trim());
setResults(res.items);
setFallbackUsed(res.fallback_used);
} catch (err) {
setError(err instanceof Error ? err.message : "Search failed");
setResults([]);
} finally {
setLoading(false);
}
}, []);
// Search when URL param changes
useEffect(() => {
setLocalQuery(q);
if (q) void doSearch(q);
}, [q, doSearch]);
function handleInputChange(value: string) {
setLocalQuery(value);
if (debounceRef.current) clearTimeout(debounceRef.current);
debounceRef.current = setTimeout(() => {
if (value.trim()) {
navigate(`/search?q=${encodeURIComponent(value.trim())}`, {
replace: true,
});
}
}, 400);
}
function handleSubmit(e: React.FormEvent) {
e.preventDefault();
if (debounceRef.current) clearTimeout(debounceRef.current);
if (localQuery.trim()) {
navigate(`/search?q=${encodeURIComponent(localQuery.trim())}`, {
replace: true,
});
}
}
// Group results by type
const techniqueResults = results.filter((r) => r.type === "technique_page");
const momentResults = results.filter((r) => r.type === "key_moment");
return (
<div className="search-results-page">
{/* Inline search bar */}
<form onSubmit={handleSubmit} className="search-form search-form--inline">
<input
type="search"
className="search-input search-input--inline"
placeholder="Search techniques…"
value={localQuery}
onChange={(e) => handleInputChange(e.target.value)}
aria-label="Refine search"
/>
<button type="submit" className="btn btn--search">
Search
</button>
</form>
{/* Status */}
{loading && <div className="loading">Searching…</div>}
{error && <div className="loading error-text">Error: {error}</div>}
{/* Fallback banner */}
{!loading && fallbackUsed && results.length > 0 && (
<div className="search-fallback-banner">
Showing keyword results — semantic search unavailable
</div>
)}
{/* No results */}
{!loading && !error && q && results.length === 0 && (
<div className="empty-state">
<p>No results found for "{q}"</p>
</div>
)}
{/* Technique pages */}
{techniqueResults.length > 0 && (
<section className="search-group">
<h3 className="search-group__title">
Techniques ({techniqueResults.length})
</h3>
<div className="search-group__list">
{techniqueResults.map((item) => (
<SearchResultCard key={`tp-${item.slug}`} item={item} />
))}
</div>
</section>
)}
{/* Key moments */}
{momentResults.length > 0 && (
<section className="search-group">
<h3 className="search-group__title">
Key Moments ({momentResults.length})
</h3>
<div className="search-group__list">
{momentResults.map((item, i) => (
<SearchResultCard key={`km-${item.slug}-${i}`} item={item} />
))}
</div>
</section>
)}
</div>
);
}
function SearchResultCard({ item }: { item: SearchResultItem }) {
return (
<Link
to={`/techniques/${item.slug}`}
className="search-result-card"
>
<div className="search-result-card__header">
<span className="search-result-card__title">{item.title}</span>
<span className={`badge badge--type badge--type-${item.type}`}>
{item.type === "technique_page" ? "Technique" : "Key Moment"}
</span>
</div>
{item.summary && (
<p className="search-result-card__summary">
{item.summary.length > 200
? `${item.summary.slice(0, 200)}…`
: item.summary}
</p>
)}
<div className="search-result-card__meta">
{item.creator_name && <span>{item.creator_name}</span>}
{item.topic_category && (
<>
<span className="queue-card__separator">·</span>
<span>{item.topic_category}</span>
</>
)}
{item.topic_tags.length > 0 && (
<span className="search-result-card__tags">
{item.topic_tags.map((tag) => (
<span key={tag} className="pill">
{tag}
</span>
))}
</span>
)}
</div>
</Link>
);
}

300
frontend/src/pages/TechniquePage.tsx
View file

@ -1,300 +0,0 @@
/**
* Technique page detail view.
*
* Fetches a single technique by slug. Renders:
* - Header with title, category badge, tags, creator link, source quality
* - Amber banner for unstructured (livestream-sourced) content
* - Study guide prose from body_sections JSONB
* - Key moments index
* - Signal chains (if present)
* - Plugins referenced (if present)
* - Related techniques (if present)
* - Loading and 404 states
*/
import { useEffect, useState } from "react";
import { Link, useParams } from "react-router-dom";
import {
fetchTechnique,
type TechniquePageDetail as TechniqueDetail,
} from "../api/public-client";
function formatTime(seconds: number): string {
const m = Math.floor(seconds / 60);
const s = Math.floor(seconds % 60);
return `${m}:${s.toString().padStart(2, "0")}`;
}
export default function TechniquePage() {
const { slug } = useParams<{ slug: string }>();
const [technique, setTechnique] = useState<TechniqueDetail | null>(null);
const [loading, setLoading] = useState(true);
const [notFound, setNotFound] = useState(false);
const [error, setError] = useState<string | null>(null);
useEffect(() => {
if (!slug) return;
let cancelled = false;
setLoading(true);
setNotFound(false);
setError(null);
void (async () => {
try {
const data = await fetchTechnique(slug);
if (!cancelled) setTechnique(data);
} catch (err) {
if (!cancelled) {
if (
err instanceof Error &&
err.message.includes("404")
) {
setNotFound(true);
} else {
setError(
err instanceof Error ? err.message : "Failed to load technique",
);
}
}
} finally {
if (!cancelled) setLoading(false);
}
})();
return () => {
cancelled = true;
};
}, [slug]);
if (loading) {
return <div className="loading">Loading technique…</div>;
}
if (notFound) {
return (
<div className="technique-404">
<h2>Technique Not Found</h2>
<p>The technique "{slug}" doesn't exist.</p>
<Link to="/" className="btn">
Back to Home
</Link>
</div>
);
}
if (error || !technique) {
return (
<div className="loading error-text">
Error: {error ?? "Unknown error"}
</div>
);
}
return (
<article className="technique-page">
{/* Back link */}
<Link to="/" className="back-link">
← Back
</Link>
{/* Unstructured content warning */}
{technique.source_quality === "unstructured" && (
<div className="technique-banner technique-banner--amber">
⚠ This technique was sourced from a livestream and may have less
structured content.
</div>
)}
{/* Header */}
<header className="technique-header">
<h1 className="technique-header__title">{technique.title}</h1>
<div className="technique-header__meta">
<span className="badge badge--category">
{technique.topic_category}
</span>
{technique.topic_tags && technique.topic_tags.length > 0 && (
<span className="technique-header__tags">
{technique.topic_tags.map((tag) => (
<span key={tag} className="pill">
{tag}
</span>
))}
</span>
)}
{technique.creator_info && (
<Link
to={`/creators/${technique.creator_info.slug}`}
className="technique-header__creator"
>
by {technique.creator_info.name}
</Link>
)}
{technique.source_quality && (
<span
className={`badge badge--quality badge--quality-${technique.source_quality}`}
>
{technique.source_quality}
</span>
)}
</div>
{/* Meta stats line */}
<div className="technique-header__stats">
{(() => {
const sourceCount = new Set(
technique.key_moments
.map((km) => km.video_filename)
.filter(Boolean),
).size;
const momentCount = technique.key_moments.length;
const updated = new Date(technique.updated_at).toLocaleDateString(
"en-US",
{ year: "numeric", month: "short", day: "numeric" },
);
const parts = [
`Compiled from ${sourceCount} source${sourceCount !== 1 ? "s" : ""}`,
`${momentCount} key moment${momentCount !== 1 ? "s" : ""}`,
];
if (technique.version_count > 0) {
parts.push(
`${technique.version_count} version${technique.version_count !== 1 ? "s" : ""}`,
);
}
parts.push(`Last updated ${updated}`);
return parts.join(" · ");
})()}
</div>
</header>
{/* Summary */}
{technique.summary && (
<section className="technique-summary">
<p>{technique.summary}</p>
</section>
)}
{/* Study guide prose — body_sections */}
{technique.body_sections &&
Object.keys(technique.body_sections).length > 0 && (
<section className="technique-prose">
{Object.entries(technique.body_sections).map(
([sectionTitle, content]) => (
<div key={sectionTitle} className="technique-prose__section">
<h2>{sectionTitle}</h2>
{typeof content === "string" ? (
<p>{content}</p>
) : typeof content === "object" && content !== null ? (
<pre className="technique-prose__json">
{JSON.stringify(content, null, 2)}
</pre>
) : (
<p>{String(content)}</p>
)}
</div>
),
)}
</section>
)}
{/* Key moments */}
{technique.key_moments.length > 0 && (
<section className="technique-moments">
<h2>Key Moments</h2>
<ol className="technique-moments__list">
{technique.key_moments.map((km) => (
<li key={km.id} className="technique-moment">
<div className="technique-moment__header">
<span className="technique-moment__title">{km.title}</span>
{km.video_filename && (
<span className="technique-moment__source">
{km.video_filename}
</span>
)}
<span className="technique-moment__time">
{formatTime(km.start_time)} – {formatTime(km.end_time)}
</span>
<span className="badge badge--content-type">
{km.content_type}
</span>
</div>
<p className="technique-moment__summary">{km.summary}</p>
</li>
))}
</ol>
</section>
)}
{/* Signal chains */}
{technique.signal_chains &&
technique.signal_chains.length > 0 && (
<section className="technique-chains">
<h2>Signal Chains</h2>
{technique.signal_chains.map((chain, i) => {
const chainObj = chain as Record<string, unknown>;
const chainName =
typeof chainObj["name"] === "string"
? chainObj["name"]
: `Chain ${i + 1}`;
const steps = Array.isArray(chainObj["steps"])
? (chainObj["steps"] as string[])
: [];
return (
<div key={i} className="technique-chain">
<h3>{chainName}</h3>
{steps.length > 0 && (
<div className="technique-chain__flow">
{steps.map((step, j) => (
<span key={j}>
{j > 0 && (
<span className="technique-chain__arrow">
{" → "}
</span>
)}
<span className="technique-chain__step">
{String(step)}
</span>
</span>
))}
</div>
)}
</div>
);
})}
</section>
)}
{/* Plugins */}
{technique.plugins && technique.plugins.length > 0 && (
<section className="technique-plugins">
<h2>Plugins Referenced</h2>
<div className="pill-list">
{technique.plugins.map((plugin) => (
<span key={plugin} className="pill pill--plugin">
{plugin}
</span>
))}
</div>
</section>
)}
{/* Related techniques */}
{technique.related_links.length > 0 && (
<section className="technique-related">
<h2>Related Techniques</h2>
<ul className="technique-related__list">
{technique.related_links.map((link) => (
<li key={link.target_slug}>
<Link to={`/techniques/${link.target_slug}`}>
{link.target_title}
</Link>
<span className="technique-related__rel">
({link.relationship})
</span>
</li>
))}
</ul>
</section>
)}
</article>
);
}

156
frontend/src/pages/TopicsBrowse.tsx
View file

@ -1,156 +0,0 @@
/**
* Topics browse page (R008).
*
* Two-level hierarchy: 6 top-level categories with expandable/collapsible
* sub-topics. Each sub-topic shows technique_count and creator_count.
* Filter input narrows categories and sub-topics.
* Click sub-topic → search results filtered to that topic.
*/
import { useEffect, useState } from "react";
import { Link } from "react-router-dom";
import { fetchTopics, type TopicCategory } from "../api/public-client";
export default function TopicsBrowse() {
const [categories, setCategories] = useState<TopicCategory[]>([]);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const [expanded, setExpanded] = useState<Set<string>>(new Set());
const [filter, setFilter] = useState("");
useEffect(() => {
let cancelled = false;
setLoading(true);
setError(null);
void (async () => {
try {
const data = await fetchTopics();
if (!cancelled) {
setCategories(data);
// All expanded by default
setExpanded(new Set(data.map((c) => c.name)));
}
} catch (err) {
if (!cancelled) {
setError(
err instanceof Error ? err.message : "Failed to load topics",
);
}
} finally {
if (!cancelled) setLoading(false);
}
})();
return () => {
cancelled = true;
};
}, []);
function toggleCategory(name: string) {
setExpanded((prev) => {
const next = new Set(prev);
if (next.has(name)) {
next.delete(name);
} else {
next.add(name);
}
return next;
});
}
// Apply filter: show categories whose name or sub-topics match
const lowerFilter = filter.toLowerCase();
const filtered = filter
? categories
.map((cat) => {
const catMatches = cat.name.toLowerCase().includes(lowerFilter);
const matchingSubs = cat.sub_topics.filter((st) =>
st.name.toLowerCase().includes(lowerFilter),
);
if (catMatches) return cat; // show full category
if (matchingSubs.length > 0) {
return { ...cat, sub_topics: matchingSubs };
}
return null;
})
.filter(Boolean) as TopicCategory[]
: categories;
if (loading) {
return <div className="loading">Loading topics…</div>;
}
if (error) {
return <div className="loading error-text">Error: {error}</div>;
}
return (
<div className="topics-browse">
<h2 className="topics-browse__title">Topics</h2>
<p className="topics-browse__subtitle">
Browse techniques organized by category and sub-topic
</p>
{/* Filter */}
<input
type="search"
className="topics-filter-input"
placeholder="Filter topics…"
value={filter}
onChange={(e) => setFilter(e.target.value)}
aria-label="Filter topics"
/>
{filtered.length === 0 ? (
<div className="empty-state">
No topics matching "{filter}"
</div>
) : (
<div className="topics-list">
{filtered.map((cat) => (
<div key={cat.name} className="topic-category">
<button
className="topic-category__header"
onClick={() => toggleCategory(cat.name)}
aria-expanded={expanded.has(cat.name)}
>
<span className="topic-category__chevron">
{expanded.has(cat.name) ? "▼" : "▶"}
</span>
<span className="topic-category__name">{cat.name}</span>
<span className="topic-category__desc">{cat.description}</span>
<span className="topic-category__count">
{cat.sub_topics.length} sub-topic{cat.sub_topics.length !== 1 ? "s" : ""}
</span>
</button>
{expanded.has(cat.name) && (
<div className="topic-subtopics">
{cat.sub_topics.map((st) => (
<Link
key={st.name}
to={`/search?q=${encodeURIComponent(st.name)}&scope=topics`}
className="topic-subtopic"
>
<span className="topic-subtopic__name">{st.name}</span>
<span className="topic-subtopic__counts">
<span className="topic-subtopic__count">
{st.technique_count} technique{st.technique_count !== 1 ? "s" : ""}
</span>
<span className="topic-subtopic__separator">·</span>
<span className="topic-subtopic__count">
{st.creator_count} creator{st.creator_count !== 1 ? "s" : ""}
</span>
</span>
</Link>
))}
</div>
)}
</div>
))}
</div>
)}
</div>
);
}

1
frontend/src/vite-env.d.ts vendored
View file

@ -1 +0,0 @@
/// <reference types="vite/client" />

25
frontend/tsconfig.app.json
View file

@ -1,25 +0,0 @@
{
"compilerOptions": {
"target": "ES2020",
"useDefineForClassFields": true,
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"module": "ESNext",
"skipLibCheck": true,
/* Bundler mode */
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"isolatedModules": true,
"moduleDetection": "force",
"noEmit": true,
"jsx": "react-jsx",
/* Linting */
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"noUncheckedIndexedAccess": true
},
"include": ["src"]
}

1
frontend/tsconfig.app.tsbuildinfo
View file

@ -1 +0,0 @@
{"root":["./src/App.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/api/client.ts","./src/api/public-client.ts","./src/components/ModeToggle.tsx","./src/components/StatusBadge.tsx","./src/pages/CreatorDetail.tsx","./src/pages/CreatorsBrowse.tsx","./src/pages/Home.tsx","./src/pages/MomentDetail.tsx","./src/pages/ReviewQueue.tsx","./src/pages/SearchResults.tsx","./src/pages/TechniquePage.tsx","./src/pages/TopicsBrowse.tsx"],"version":"5.6.3"}

4
frontend/tsconfig.json
View file

@ -1,4 +0,0 @@
{
"files": [],
"references": [{ "path": "./tsconfig.app.json" }]
}

14
frontend/vite.config.ts
View file

@ -1,14 +0,0 @@
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
server: {
proxy: {
"/api": {
target: "http://localhost:8001",
changeOrigin: true,
},
},
},
});

2
prompts/README.md
View file

@ -1,2 +0,0 @@
# Prompt templates for LLM pipeline stages
# These files are bind-mounted read-only into the worker container.

78
prompts/stage2_segmentation.txt
View file

@ -1,78 +0,0 @@
You are a music production transcript analyst specializing in identifying topic boundaries in educational content from electronic music producers, sound designers, and mixing engineers.
Your task: analyze a tutorial transcript and group consecutive segments into coherent topic blocks that each cover one distinct production subject.
## Domain context
These transcripts come from music production tutorials, livestreams, and track breakdowns. Producers typically cover subjects like sound design (creating drums, basses, leads, pads, FX), mixing (EQ, compression, bus processing, spatial effects), synthesis (FM, wavetable, granular), arrangement, workflow, and mastering.
Topic shifts in this domain look like:
- Moving from one sound element to another (e.g., snare design → kick drum design)
- Moving from one production stage to another (e.g., sound design → mixdown)
- Moving from one technique to another within the same element (e.g., snare layering → snare saturation → snare bus compression)
- Moving between creative work and technical explanation
Topic shifts do NOT include:
- Brief asides that return to the same subject within 1-2 segments ("oh let me check chat real quick... okay so back to the snare")
- Restating or revisiting the same concept from a different angle
- Moving between demonstration and verbal explanation of the same technique
## Granularity guidance
Aim for topic blocks that represent **one coherent teaching unit** — a subject the creator spends meaningful time on (typically 2-30+ segments). The topic should be specific enough to be useful as a label but broad enough to capture the full discussion.
Good granularity:
- "snare layering and transient shaping" (specific technique, complete discussion)
- "parallel bus compression setup" (focused workflow with explanation)
- "serum wavetable import and FM routing" (specific tool + technique)
- "mix bus chain walkthrough" (a complete demonstration)
Too broad:
- "sound design" (covers everything, useless as a label)
- "drum processing" (could contain 5 distinct techniques)
Too narrow:
- "adjusting the attack knob" (a single action within a larger technique)
- "opening the EQ plugin" (a step, not a topic)
## Handling unstructured content
Livestreams and informal sessions may contain:
- Chat interaction, greetings, off-topic tangents, breaks
- The creator jumping between topics and returning to earlier subjects
- Extended periods of silent work or music playback with minimal speech
For these situations:
- Group non-production tangents (chat reading, personal stories, breaks) into segments labeled with descriptive labels like "chat interaction and break" or "off-topic discussion." Do NOT discard them — they must be included to satisfy the coverage constraint — but label them accurately so downstream stages can skip them.
- If a creator returns to a previously discussed topic after a tangent, treat the return as a NEW topic block with a similar label. Do not try to merge non-consecutive segments.
- Segments with very little speech content (just music playing, silence, "umm", "let me think") should be grouped with adjacent substantive segments when possible, or labeled as "demonstration without commentary" if they form a long stretch.
## Input format
Segments are provided inside <transcript> tags, formatted as:
[index] (start_time - end_time) text
## Output format
Return a JSON object with a single key "segments" containing a list of topic groups:
```json
{
"segments": [
{
"start_index": 0,
"end_index": 5,
"topic_label": "snare layering and transient shaping",
"summary": "Creator demonstrates building a snare from three layers (click, body, tail) and shaping each transient independently before summing to the drum bus."
}
]
}
```
## Field rules
- **start_index / end_index**: Inclusive. Every segment index from the transcript must appear in exactly one group. No gaps, no overlaps.
- **topic_label**: 3-8 words. Lowercase. Should read like a chapter title that tells you exactly what production subject is covered. Include the specific element or tool when relevant (e.g., "kick sub layering in Serum" not just "bass sound design").
- **summary**: 1-3 sentences. Describe what the creator teaches or demonstrates in this block. Be specific — mention techniques, tools, and concepts by name. This summary is used by the next pipeline stage to decide what knowledge to extract, so vague summaries like "the creator talks about mixing" directly reduce output quality.
## Output ONLY the JSON object, no other text.

82
prompts/stage3_extraction.txt
View file

@ -1,82 +0,0 @@
You are a music production knowledge extractor. Your task is to identify and extract key moments of genuine educational value from a topic segment of a tutorial transcript.
## What counts as a key moment
A key moment is a discrete piece of knowledge that a music producer could act on — a technique they could apply, a setting they could try, a reasoning framework they could adopt, or a workflow pattern they could implement.
**Extract when the creator is TEACHING:**
- Explaining a technique and why it works ("I layer three elements for my snares because...")
- Walking through specific settings with intent ("I set the attack to 5ms here because anything longer smears the transient")
- Sharing reasoning or philosophy behind a creative choice ("I always check my snare against the lead bus, not soloed, because the 2-4kHz range is where they fight")
- Demonstrating a workflow pattern and explaining its benefits ("I gain-stage every channel to -18dBFS before I start mixing because plugins behave differently at different input levels")
- Warning against common mistakes ("Don't use OTT on your transients — it smears them into mush")
**SKIP when the creator is merely DOING:**
- Silently adjusting a knob or clicking through menus without explanation
- Briefly mentioning a plugin or tool without teaching anything about it ("let me open up my EQ real quick")
- Casual opinions without substance ("yeah this sounds cool")
- Reading chat, greeting viewers, off-topic banter, personal anecdotes unrelated to production
- Repeating the same point already captured in a previous moment from this segment
## Quality standard for summaries
The summary is the single most important field. It becomes the prose content of the final technique page that users will read. Write summaries that are:
- **Actionable**: A producer reading this should be able to understand and attempt the technique without watching the video. Include the what, the how, and — when the creator provides it — the why.
- **Specific**: Include exact values, plugin names, parameter settings, frequency ranges, time values, ratios, and signal routing when the creator mentions them. "Uses compression" is worthless. "Uses a compressor with fast attack (0.5ms), medium release (80ms), 4:1 ratio, hitting about 3-6dB of gain reduction" is useful.
- **Preserving the creator's voice**: When the creator uses a vivid phrase to explain something, capture that phrasing. If they say "it smears the snap into mush," that exact language is more memorable and useful than a clinical paraphrase. Use quotation marks for direct creator quotes within the summary.
- **Self-contained**: Each summary should make sense on its own, without needing to read other moments. Include enough context that a reader understands what problem this technique solves.
Bad summary: "The creator shows how to make a snare sound."
Good summary: "Builds snares as three independent layers: a transient click (short noise burst, 2-5ms decay from Vital's noise oscillator), a tonal body (pitched sine or triangle wave around 200Hz tuned to the track's key), and a noise tail (filtered white noise with fast exponential decay). Each layer is shaped with a transient shaper independently before any bus processing — he uses Kilohearts Transient Shaper with attack boosted +4 to +6dB and sustain pulled back -6 to -8dB, specifically choosing a transient shaper over compression because 'compression adds sustain as a side effect while a transient shaper gives you direct independent control of both.'"
## Content type guidance
Assign content_type based on the PRIMARY nature of the moment. Most real moments blend multiple types — pick the dominant one:
- **technique**: The creator is demonstrating or explaining HOW to do something. This is the most common type. A technique moment may include settings and reasoning, but the core is the method.
- **settings**: The creator is specifically focused on dialing in parameters — plugin settings, exact values, A/B comparisons of different settings. The knowledge value is in the specific numbers and configurations.
- **reasoning**: The creator is explaining WHY they make a choice, often without showing the specific technique. Philosophy, decision frameworks, "when I'm in situation X, I always do Y because Z." The knowledge value is in the thinking process.
- **workflow**: The creator is showing how they organize their session, manage files, set up templates, or structure their creative process. The knowledge value is in the process itself.
When in doubt between technique and settings, choose technique. When in doubt between technique and reasoning, choose technique if they demonstrate it, reasoning if they only discuss it conceptually.
## Input format
The segment is provided inside <segment> tags with a topic label and the transcript text with timestamps.
## Output format
Return a JSON object with a single key "moments" containing a list of extracted moments:
```json
{
"moments": [
{
"title": "Three-layer snare construction with independent transient shaping",
"summary": "Builds snares as three independent layers: a transient click (short noise burst, 2-5ms decay from Vital's noise oscillator), a tonal body (pitched sine or triangle wave around 200Hz), and a noise tail (filtered white noise with fast exponential decay). Each layer is shaped independently with Kilohearts Transient Shaper (attack +4 to +6dB, sustain -6 to -8dB) before any bus processing. Chooses a transient shaper over compression because 'compression adds sustain as a side effect.'",
"start_time": 6150.0,
"end_time": 6855.0,
"content_type": "technique",
"plugins": ["Vital", "Kilohearts Transient Shaper"],
"raw_transcript": "so what I like to do is I actually build this in three separate layers right, so I've got my click which is just a really short noise burst..."
}
]
}
```
## Field rules
- **title**: 4-12 words. Should be specific enough to distinguish this moment from other moments on a similar topic. Include the element being worked on and the core technique. "Snare design" is too vague. "Three-layer snare construction with independent transient shaping" tells you exactly what you'll learn.
- **summary**: 2-6 sentences following the quality standards above. This is the most important field in the entire pipeline — invest the most effort here.
- **start_time / end_time**: Timestamps in seconds from the transcript. Capture the full range where this moment is discussed, including any preamble where the creator sets up what they're about to show.
- **content_type**: One of: technique, settings, reasoning, workflow. See guidance above.
- **plugins**: Plugin names, virtual instruments, DAW-specific tools, and hardware mentioned in context of this moment. Normalize names to their common form (e.g., "FabFilter Pro-Q 3" not "pro q" or "that fabfilter EQ"). Empty list if no specific tools are mentioned.
- **raw_transcript**: The most relevant excerpt of transcript text covering this moment. Include enough to verify the summary's claims but don't copy the entire segment. Typically 2-8 sentences.
## Critical rules
- Prefer FEWER, RICHER moments over MANY thin ones. A segment with 3 deeply detailed moments is far more valuable than 8 shallow ones. If a moment's summary would be under 2 sentences, it probably isn't substantial enough to extract.
- If the segment is off-topic content (chat interaction, tangents, breaks), return {"moments": []}.
- If the segment contains demonstration without meaningful verbal explanation, return {"moments": []} — we cannot extract knowledge from silent screen activity via transcript alone.
- Output ONLY the JSON object, no other text.

64
prompts/stage4_classification.txt
View file

@ -1,64 +0,0 @@
You are a music production knowledge classifier. Your task is to assign each extracted key moment to the correct position in a canonical tag taxonomy so it can be browsed and searched effectively.
## Context
These key moments were extracted from music production tutorials. They need to be classified so users can find them by browsing topic categories (e.g., "Sound design > drums > snare") or by searching. Accurate classification directly determines whether a user searching for "snare design" will find this content.
## Classification principles
**Pick the category that matches WHERE this knowledge would be applied in a production session:**
- If someone would use this knowledge while CREATING a sound from scratch → Sound design
- If someone would use this knowledge while BALANCING and PROCESSING an existing mix → Mixing
- If someone would use this knowledge while PROGRAMMING a synthesizer → Synthesis
- If someone would use this knowledge while STRUCTURING their track → Arrangement
- If someone would use this knowledge while SETTING UP their session or managing their process → Workflow
- If someone would use this knowledge during FINAL PROCESSING for release → Mastering
**Common ambiguities and how to resolve them:**
- "Using an EQ on a bass sound while designing it" → Sound design (the EQ is part of the sound creation process)
- "Using an EQ on the bass bus during mixdown" → Mixing (the EQ is part of the mix balancing process)
- "Building a Serum patch for a bass" → Synthesis (focused on the synth programming)
- "Resampling a bass through effects" → Sound design (creating a new sound, even though it uses existing material)
- "Setting up a template with bus routing" → Workflow
- "Adding a limiter to the master bus" → Mastering (if in the context of final output) or Mixing (if in the context of mix referencing)
**Tag assignment:**
- Assign the single best-fitting top-level **topic_category**
- Assign ALL relevant **topic_tags** from that category's sub-topics. Also include tags from other categories if the moment genuinely spans multiple areas (e.g., a moment about "EQ techniques for bass sound design" could have tags from both Sound design and Mixing)
- When assigning tags, think about what search terms a user would type to find this content. If someone searching "snare" should find this moment, the tag "snare" must be present
- Prefer existing sub_topics from the taxonomy. Only propose a new tag if nothing in the existing taxonomy fits AND the concept is specific enough to be useful as a search/filter term. Don't create redundant tags — "snare processing" is redundant if "snare" already exists as a tag
**content_type_override:**
- Only override when the original classification is clearly wrong. For example, if a moment was classified as "settings" but it's actually the creator explaining their philosophy about gain staging with no specific numbers, override to "reasoning"
- When in doubt, leave as null. The original classification from Stage 3 is usually reasonable
## Input format
Key moments are provided inside <moments> tags as a JSON array.
The canonical taxonomy is provided inside <taxonomy> tags.
## Output format
Return a JSON object with a single key "classifications":
```json
{
"classifications": [
{
"moment_index": 0,
"topic_category": "Sound design",
"topic_tags": ["drums", "snare", "layering", "transient shaping"],
"content_type_override": null
}
]
}
```
## Field rules
- **moment_index**: Zero-based index matching the input moments list. Every moment must have exactly one entry.
- **topic_category**: Must exactly match one top-level category name from the taxonomy.
- **topic_tags**: Array of sub_topic strings. At minimum, include the most specific applicable tag (e.g., "snare" not just "drums"). Include broader parent tags too when they aid discoverability (e.g., ["drums", "snare", "layering"]).
- **content_type_override**: One of "technique", "settings", "reasoning", "workflow", or null. Only set when correcting an error.
## Output ONLY the JSON object, no other text.

127
prompts/stage5_synthesis.txt
View file

@ -1,127 +0,0 @@
You are an expert technical writer specializing in music production education. Your task is to synthesize a set of related key moments from the same creator into a single, high-quality technique page that serves as a definitive reference on the topic.
## What you are creating
A Chrysopedia technique page is NOT a generic article or wiki entry. It is a focused reference document that a music producer will consult mid-session when they need to understand and apply a specific technique. The reader is Alt+Tabbing from their DAW, looking for actionable knowledge, and wants to absorb the key insight and get back to work in under 2 minutes.
The page has two complementary sections:
1. **Study guide prose** — rich, detailed paragraphs organized by sub-aspect of the technique. This is for learning and deep understanding. It reads like notes from an expert mentor, not a textbook.
2. **Key moments index** — a compact list of the individual source moments that contributed to this page, each with a descriptive title that enables quick scanning.
Both sections are essential. The prose synthesizes and explains; the moment index lets readers quickly locate the specific insight they need.
## Voice and tone
Write as if you are a knowledgeable colleague explaining what you learned from watching this creator's content. The tone should be:
- **Direct and confident** — state what the creator does, not "the creator appears to" or "it seems like they"
- **Technical but accessible** — use production terminology naturally, but explain non-obvious concepts when the creator's explanation adds value
- **Preserving the creator's voice** — when the creator uses a memorable phrase, vivid metaphor, or strong opinion, quote them directly with quotation marks. These are often the most valuable parts. Examples: 'He warns against using OTT on snares — says it "smears the snap into mush."' or 'Her reasoning: "every bus you add is another place you'll be tempted to put a compressor that doesn't need to be there."'
- **Specific over general** — always prefer concrete details (frequencies, ratios, ms values, plugin names, specific settings) over vague descriptions. "Uses compression" is never acceptable if the source moments contain specifics.
## Body sections structure
Do NOT use generic section names like "Overview," "Step-by-Step Process," "Key Settings," or "Tips and Variations." These produce lifeless, formulaic output.
Instead, derive section names from the actual content. Each section should cover one sub-aspect of the technique. Use descriptive names that tell the reader exactly what they'll learn:
Good section names (examples):
- "Layer construction" / "Saturation and the crunch character" / "Mix context and bus processing"
- "Resampling loop" / "Preserving transient information" / "Wavetable import settings"
- "Overall philosophy" / "Bus structure" / "Gain staging mindset"
- "Oscillator setup and FM routing" / "Effects chain per-layer" / "Automating movement"
Bad section names (never use these):
- "Overview" / "Introduction" / "Step-by-Step Process" / "Key Settings" / "Tips and Variations" / "Conclusion" / "Summary"
Each section should be 2-5 paragraphs of substantive prose. A section with only 1-2 sentences is too thin — either merge it with another section or expand it with the detail available in the source moments.
## Signal chains
When the source moments describe a signal routing chain (oscillator → effects → processing → bus), represent it as a structured signal chain object. Signal chains are only included when the creator explicitly walks through routing — do not infer chains from casual plugin mentions.
Format signal chain steps to include the role of each stage, not just the plugin name:
- Good: ["Noise osc (Vital)", "Transient Shaper (Kilohearts, attack +6dB)", "EQ (Pro-Q 3, shelf -3dB @ 12kHz)", "Send → Trash 2 (tape algo, 35% wet)"]
- Bad: ["Vital", "Kilohearts", "EQ", "Trash 2"]
## Plugin detail rule
Include specific plugin names, settings, and parameters ONLY when the creator was teaching that setting — spending time explaining why they chose it, what it does, or how to configure it. If a plugin is merely visible or briefly mentioned without explanation, include it in the plugins list but do not feature it in the body prose.
This distinction is critical for page quality. A page that lists every plugin the creator happened to have open reads like a gear list. A page that explains the plugins the creator intentionally demonstrated reads like education.
## Synthesis, not concatenation
You are synthesizing knowledge, not summarizing a video. This means:
- **Merge related information**: If the creator discusses snare transient shaping at timestamp 1:42:00 and then returns to refine the point at 2:15:00, these should be woven into one coherent section, not presented as two separate observations.
- **Build a logical flow**: Organize sections in the order a producer would naturally encounter these decisions (e.g., sound source → processing → mixing context), even if the creator covered them in a different order.
- **Resolve redundancy**: If two moments say essentially the same thing, combine them into one clear statement. Don't repeat yourself.
- **Note contradictions**: If the creator says contradictory things in different moments (e.g., recommends different settings for the same parameter), note both and provide the context for each ("In dense arrangements, he pulls the sustain back further; for sparse sections, he leaves more room for the tail").
## Source quality assessment
Assess source_quality based on the nature of the input moments:
- **structured**: Moments come from a planned tutorial with clear instructional flow. Most details are explicitly taught.
- **mixed**: Some moments are well-structured, others are scattered or conversational. Common for track breakdowns.
- **unstructured**: Moments are extracted from livestreams, Q&A sessions, or very informal content. Insights were scattered across a long session.
## Input format
Key moments are provided inside <moments> tags as a JSON array, enriched with classification metadata (topic_category, topic_tags). All moments are from the same creator and related topic area.
## Output format
Return a JSON object with a single key "pages" containing a list of synthesized pages. Most inputs produce a single page, but if the moments clearly cover two distinctly separate techniques (e.g., moments about both "kick design" and "hi-hat design" that happen to share a topic_category), split them into separate pages.
```json
{
"pages": [
{
"title": "Snare Design by Skope",
"slug": "snare-design-skope",
"topic_category": "Sound design",
"topic_tags": ["drums", "snare", "layering", "saturation", "transient shaping"],
"summary": "Skope builds snares as three independent layers — transient click, tonal body, and noise tail — with each shaped by a transient shaper before any bus processing. The signature crunch comes from parallel soft-clip saturation with a pre-delay that preserves the clean transient. In dense mixes, he uses HP sidechaining on the snare bus to maintain punch without competing with sub content.",
"body_sections": {
"Layer construction": "Skope builds snares as three independent layers, each shaped before they are summed. The transient click is a short noise burst (2-5ms decay) — he uses Vital's noise oscillator for this, sometimes with a bandpass around 2-4kHz to control the character. The tonal body is a pitched sine or triangle wave around 180-220Hz, tuned to complement the key of the track. The tail is filtered white noise with a fast exponential decay.\n\nThe critical insight: he shapes each layer's transient independently before any bus processing. He uses Kilohearts Transient Shaper (attack +4 to +6dB, sustain -6 to -8dB) rather than compression for this, because \"compression adds sustain as a side effect while a transient shaper gives you direct independent control of both.\"",
"Saturation and the crunch character": "The signature Skope snare crunch comes from parallel saturation — not inline. He routes the summed snare to a send with Trash 2 using the tape algorithm at 30-40% wet. The key detail: he puts a pre-delay of approximately 5ms on the saturation send, which lets the clean transient click through untouched while only the body and tail pick up harmonic content.\n\nHe explicitly warns against saturating the transient directly — says it \"smears the snap into mush\" and you lose the precision that makes the snare cut through.",
"Mix context and bus processing": "In dense arrangements, Skope prioritizes punch over sustain. On the snare bus compressor, he uses a high-pass sidechain filter (around 200-300Hz) so low-end energy from the body layer does not trigger gain reduction. This keeps the snare's ability to cut through the mix independent of whatever the sub bass is doing.\n\nHe also checks the snare against the lead or vocal bus specifically, not just soloed — because the 2-4kHz presence range is where both elements compete, and he would rather notch the snare's body slightly than lose vocal clarity."
},
"signal_chains": [
{
"name": "Snare layer processing",
"steps": [
"Noise osc (Vital) → Transient Shaper (Kilohearts, attack +6dB, sustain -8dB) → EQ (Pro-Q 3, shelf -3dB @ 12kHz)",
"Dry path → snare bus",
"Send → Pre-delay (5ms) → Trash 2 (tape algorithm, 35% wet) → snare bus"
]
}
],
"plugins": ["Vital", "Kilohearts Transient Shaper", "FabFilter Pro-Q 3", "iZotope Trash 2"],
"source_quality": "structured"
}
]
}
```
## Field rules
- **title**: The technique or concept name followed by "by CreatorName" — concise and search-friendly. Examples: "Snare Design by Skope", "Bass Resampling Workflow by KOAN Sound", "Mid-Side EQ for Width by Mr. Bill". Use title case.
- **slug**: URL-safe, lowercase, hyphenated version of the title including creator name. Examples: "snare-design-skope", "bass-resampling-workflow-koan-sound". The creator name in the slug prevents collisions when multiple creators teach the same technique.
- **topic_category**: The primary category. Must match the taxonomy.
- **topic_tags**: All relevant tags aggregated from the classified moments. Deduplicated.
- **summary**: 2-4 sentences that capture the essence of the entire technique page. This summary appears as the page header and in search results, so it must be information-dense and compelling. A reader should understand the core approach from this summary alone.
- **body_sections**: Dictionary of section_name → prose content. Section names are derived from content, not generic templates. Prose follows all voice, tone, and quality guidelines above. Use \n\n for paragraph breaks within a section.
- **signal_chains**: Array of signal chain objects. Each has a "name" (what this chain is for) and "steps" (ordered list of stages with plugin names, settings, and roles). Only include when explicitly demonstrated by the creator. Empty array if not applicable.
- **plugins**: Deduplicated array of all plugins, instruments, and specific tools mentioned across the moments. Use canonical/full names ("FabFilter Pro-Q 3" not "Pro-Q", "Xfer Serum" or just "Serum" — use whichever form is most recognizable).
- **source_quality**: One of "structured", "mixed", "unstructured".
## Critical rules
- Never produce generic filler prose. Every sentence should contain specific, actionable information or meaningful creator reasoning. If you find yourself writing "This technique is useful for..." or "This is an important aspect of production..." — delete it and write something specific instead.
- Never invent information. If the source moments don't specify a value, don't make one up. Say "he adjusts the attack" not "he sets the attack to 2ms" if the specific value wasn't mentioned.
- Preserve the creator's actual opinions and warnings. These are often the most valuable content. Quote them directly when they are memorable or forceful.
- If the source moments are thin (only 1-2 moments with brief summaries), produce a proportionally shorter page. A 2-section page with genuine substance is better than a 5-section page padded with filler.
- Output ONLY the JSON object, no other text.

148
tests/fixtures/sample_transcript.json vendored
View file

@ -1,148 +0,0 @@
{
"source_file": "Skope — Sound Design Masterclass pt1.mp4",
"creator_folder": "Skope",
"duration_seconds": 3847,
"segments": [
{
"start": 0.0,
"end": 4.52,
"text": "Hey everyone welcome back to part one of this sound design masterclass.",
"words": [
{ "word": "Hey", "start": 0.0, "end": 0.28 },
{ "word": "everyone", "start": 0.32, "end": 0.74 },
{ "word": "welcome", "start": 0.78, "end": 1.12 },
{ "word": "back", "start": 1.14, "end": 1.38 },
{ "word": "to", "start": 1.40, "end": 1.52 },
{ "word": "part", "start": 1.54, "end": 1.76 },
{ "word": "one", "start": 1.78, "end": 1.98 },
{ "word": "of", "start": 2.00, "end": 2.12 },
{ "word": "this", "start": 2.14, "end": 2.34 },
{ "word": "sound", "start": 2.38, "end": 2.68 },
{ "word": "design", "start": 2.72, "end": 3.08 },
{ "word": "masterclass", "start": 3.14, "end": 4.52 }
]
},
{
"start": 5.10,
"end": 12.84,
"text": "Today we're going to be looking at how to create really aggressive bass sounds using Serum.",
"words": [
{ "word": "Today", "start": 5.10, "end": 5.48 },
{ "word": "we're", "start": 5.52, "end": 5.74 },
{ "word": "going", "start": 5.78, "end": 5.98 },
{ "word": "to", "start": 6.00, "end": 6.12 },
{ "word": "be", "start": 6.14, "end": 6.28 },
{ "word": "looking", "start": 6.32, "end": 6.64 },
{ "word": "at", "start": 6.68, "end": 6.82 },
{ "word": "how", "start": 6.86, "end": 7.08 },
{ "word": "to", "start": 7.12, "end": 7.24 },
{ "word": "create", "start": 7.28, "end": 7.62 },
{ "word": "really", "start": 7.68, "end": 8.02 },
{ "word": "aggressive", "start": 8.08, "end": 8.72 },
{ "word": "bass", "start": 8.78, "end": 9.14 },
{ "word": "sounds", "start": 9.18, "end": 9.56 },
{ "word": "using", "start": 9.62, "end": 9.98 },
{ "word": "Serum", "start": 10.04, "end": 12.84 }
]
},
{
"start": 13.40,
"end": 22.18,
"text": "So the first thing I always do is start with the init preset and then I'll load up a basic wavetable.",
"words": [
{ "word": "So", "start": 13.40, "end": 13.58 },
{ "word": "the", "start": 13.62, "end": 13.78 },
{ "word": "first", "start": 13.82, "end": 14.12 },
{ "word": "thing", "start": 14.16, "end": 14.42 },
{ "word": "I", "start": 14.48, "end": 14.58 },
{ "word": "always", "start": 14.62, "end": 14.98 },
{ "word": "do", "start": 15.02, "end": 15.18 },
{ "word": "is", "start": 15.22, "end": 15.38 },
{ "word": "start", "start": 15.44, "end": 15.78 },
{ "word": "with", "start": 15.82, "end": 16.02 },
{ "word": "the", "start": 16.06, "end": 16.18 },
{ "word": "init", "start": 16.24, "end": 16.52 },
{ "word": "preset", "start": 16.58, "end": 17.02 },
{ "word": "and", "start": 17.32, "end": 17.48 },
{ "word": "then", "start": 17.52, "end": 17.74 },
{ "word": "I'll", "start": 17.78, "end": 17.98 },
{ "word": "load", "start": 18.04, "end": 18.32 },
{ "word": "up", "start": 18.36, "end": 18.52 },
{ "word": "a", "start": 18.56, "end": 18.64 },
{ "word": "basic", "start": 18.68, "end": 19.08 },
{ "word": "wavetable", "start": 19.14, "end": 22.18 }
]
},
{
"start": 23.00,
"end": 35.42,
"text": "What makes this technique work is the FM modulation from oscillator B. You want to set the ratio to something like 3.5 and then automate the depth.",
"words": [
{ "word": "What", "start": 23.00, "end": 23.22 },
{ "word": "makes", "start": 23.26, "end": 23.54 },
{ "word": "this", "start": 23.58, "end": 23.78 },
{ "word": "technique", "start": 23.82, "end": 24.34 },
{ "word": "work", "start": 24.38, "end": 24.68 },
{ "word": "is", "start": 24.72, "end": 24.88 },
{ "word": "the", "start": 24.92, "end": 25.04 },
{ "word": "FM", "start": 25.10, "end": 25.42 },
{ "word": "modulation", "start": 25.48, "end": 26.12 },
{ "word": "from", "start": 26.16, "end": 26.38 },
{ "word": "oscillator", "start": 26.44, "end": 27.08 },
{ "word": "B", "start": 27.14, "end": 27.42 },
{ "word": "You", "start": 28.02, "end": 28.22 },
{ "word": "want", "start": 28.26, "end": 28.52 },
{ "word": "to", "start": 28.56, "end": 28.68 },
{ "word": "set", "start": 28.72, "end": 28.98 },
{ "word": "the", "start": 29.02, "end": 29.14 },
{ "word": "ratio", "start": 29.18, "end": 29.58 },
{ "word": "to", "start": 29.62, "end": 29.76 },
{ "word": "something", "start": 29.80, "end": 30.22 },
{ "word": "like", "start": 30.26, "end": 30.48 },
{ "word": "3.5", "start": 30.54, "end": 31.02 },
{ "word": "and", "start": 31.32, "end": 31.48 },
{ "word": "then", "start": 31.52, "end": 31.74 },
{ "word": "automate", "start": 31.80, "end": 32.38 },
{ "word": "the", "start": 32.42, "end": 32.58 },
{ "word": "depth", "start": 32.64, "end": 35.42 }
]
},
{
"start": 36.00,
"end": 48.76,
"text": "Now I'm going to add some distortion. OTT is great for this. Crank it to like 60 percent and then back off the highs a bit with a shelf EQ.",
"words": [
{ "word": "Now", "start": 36.00, "end": 36.28 },
{ "word": "I'm", "start": 36.32, "end": 36.52 },
{ "word": "going", "start": 36.56, "end": 36.82 },
{ "word": "to", "start": 36.86, "end": 36.98 },
{ "word": "add", "start": 37.02, "end": 37.28 },
{ "word": "some", "start": 37.32, "end": 37.58 },
{ "word": "distortion", "start": 37.64, "end": 38.34 },
{ "word": "OTT", "start": 39.02, "end": 39.42 },
{ "word": "is", "start": 39.46, "end": 39.58 },
{ "word": "great", "start": 39.62, "end": 39.92 },
{ "word": "for", "start": 39.96, "end": 40.12 },
{ "word": "this", "start": 40.16, "end": 40.42 },
{ "word": "Crank", "start": 41.02, "end": 41.38 },
{ "word": "it", "start": 41.42, "end": 41.56 },
{ "word": "to", "start": 41.60, "end": 41.72 },
{ "word": "like", "start": 41.76, "end": 41.98 },
{ "word": "60", "start": 42.04, "end": 42.38 },
{ "word": "percent", "start": 42.42, "end": 42.86 },
{ "word": "and", "start": 43.12, "end": 43.28 },
{ "word": "then", "start": 43.32, "end": 43.54 },
{ "word": "back", "start": 43.58, "end": 43.84 },
{ "word": "off", "start": 43.88, "end": 44.08 },
{ "word": "the", "start": 44.12, "end": 44.24 },
{ "word": "highs", "start": 44.28, "end": 44.68 },
{ "word": "a", "start": 44.72, "end": 44.82 },
{ "word": "bit", "start": 44.86, "end": 45.08 },
{ "word": "with", "start": 45.14, "end": 45.38 },
{ "word": "a", "start": 45.42, "end": 45.52 },
{ "word": "shelf", "start": 45.58, "end": 45.96 },
{ "word": "EQ", "start": 46.02, "end": 48.76 }
]
}
]
}

102
whisper/README.md
View file

@ -1,102 +0,0 @@
# Chrysopedia — Whisper Transcription
Desktop transcription tool for extracting timestamped text from video files
using OpenAI's Whisper model (large-v3). Designed to run on a machine with
an NVIDIA GPU (e.g., RTX 4090).
## Prerequisites
- **Python 3.10+**
- **ffmpeg** installed and on PATH
- **NVIDIA GPU** with CUDA support (recommended; CPU fallback available)
### Install ffmpeg
```bash
# Debian/Ubuntu
sudo apt install ffmpeg
# macOS
brew install ffmpeg
```
### Install Python dependencies
```bash
pip install -r requirements.txt
```
## Usage
### Single file
```bash
python transcribe.py --input "path/to/video.mp4" --output-dir ./transcripts
```
### Batch mode (all videos in a directory)
```bash
python transcribe.py --input ./videos/ --output-dir ./transcripts
```
### Options
| Flag | Default | Description |
| --------------- | ----------- | ----------------------------------------------- |
| `--input` | (required) | Path to a video file or directory of videos |
| `--output-dir` | (required) | Directory to write transcript JSON files |
| `--model` | `large-v3` | Whisper model name (`tiny`, `base`, `small`, `medium`, `large-v3`) |
| `--device` | `cuda` | Compute device (`cuda` or `cpu`) |
| `--creator` | (inferred) | Override creator folder name in output JSON |
| `-v, --verbose` | off | Enable debug logging |
## Output Format
Each video produces a JSON file matching the Chrysopedia spec:
```json
{
"source_file": "Skope — Sound Design Masterclass pt2.mp4",
"creator_folder": "Skope",
"duration_seconds": 7243,
"segments": [
{
"start": 0.0,
"end": 4.52,
"text": "Hey everyone welcome back to part two...",
"words": [
{ "word": "Hey", "start": 0.0, "end": 0.28 },
{ "word": "everyone", "start": 0.32, "end": 0.74 }
]
}
]
}
```
## Resumability
The script automatically skips videos whose output JSON already exists. To
re-transcribe a file, delete its output JSON first.
## Performance
Whisper large-v3 on an RTX 4090 processes audio at roughly 10–20× real-time.
A 2-hour video takes ~6–12 minutes. For 300 videos averaging 1.5 hours each,
the initial transcription pass takes roughly 15–40 hours of GPU time.
## Directory Convention
The script infers the `creator_folder` field from the parent directory of each
video file. Organize videos like:
```
videos/
├── Skope/
│ ├── Sound Design Masterclass pt1.mp4
│ └── Sound Design Masterclass pt2.mp4
├── Mr Bill/
│ └── Glitch Techniques.mp4
```
Override with `--creator` when processing files outside this structure.

9
whisper/requirements.txt
View file

@ -1,9 +0,0 @@
# Chrysopedia — Whisper transcription dependencies
# Install: pip install -r requirements.txt
#
# Note: openai-whisper requires ffmpeg to be installed on the system.
# sudo apt install ffmpeg (Debian/Ubuntu)
# brew install ffmpeg (macOS)
openai-whisper>=20231117
ffmpeg-python>=0.2.0

393
whisper/transcribe.py
View file

@ -1,393 +0,0 @@
#!/usr/bin/env python3
"""
Chrysopedia — Whisper Transcription Script
Desktop transcription tool for extracting timestamped text from video files
using OpenAI's Whisper model (large-v3). Designed to run on a machine with
an NVIDIA GPU (e.g., RTX 4090).
Outputs JSON matching the Chrysopedia spec format:
{
"source_file": "filename.mp4",
"creator_folder": "CreatorName",
"duration_seconds": 7243,
"segments": [
{
"start": 0.0,
"end": 4.52,
"text": "...",
"words": [{"word": "Hey", "start": 0.0, "end": 0.28}, ...]
}
]
}
"""
from __future__ import annotations
import argparse
import json
import logging
import os
import shutil
import subprocess
import sys
import tempfile
import time
from pathlib import Path
# ---------------------------------------------------------------------------
# Logging
# ---------------------------------------------------------------------------
LOG_FORMAT = "%(asctime)s [%(levelname)s] %(message)s"
logging.basicConfig(format=LOG_FORMAT, level=logging.INFO)
logger = logging.getLogger("chrysopedia.transcribe")
# ---------------------------------------------------------------------------
# Constants
# ---------------------------------------------------------------------------
SUPPORTED_EXTENSIONS = {".mp4", ".mkv", ".avi", ".mov", ".webm", ".flv", ".wmv"}
DEFAULT_MODEL = "large-v3"
DEFAULT_DEVICE = "cuda"
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def check_ffmpeg() -> bool:
"""Return True if ffmpeg is available on PATH."""
return shutil.which("ffmpeg") is not None
def get_audio_duration(video_path: Path) -> float | None:
"""Use ffprobe to get duration in seconds. Returns None on failure."""
ffprobe = shutil.which("ffprobe")
if ffprobe is None:
return None
try:
result = subprocess.run(
[
ffprobe,
"-v", "error",
"-show_entries", "format=duration",
"-of", "default=noprint_wrappers=1:nokey=1",
str(video_path),
],
capture_output=True,
text=True,
timeout=30,
)
return float(result.stdout.strip())
except (subprocess.TimeoutExpired, ValueError, OSError) as exc:
logger.warning("Could not determine duration for %s: %s", video_path.name, exc)
return None
def extract_audio(video_path: Path, audio_path: Path) -> None:
"""Extract audio from video to 16kHz mono WAV using ffmpeg."""
logger.info("Extracting audio: %s -> %s", video_path.name, audio_path.name)
cmd = [
"ffmpeg",
"-i", str(video_path),
"-vn", # no video
"-acodec", "pcm_s16le", # 16-bit PCM
"-ar", "16000", # 16kHz (Whisper expects this)
"-ac", "1", # mono
"-y", # overwrite
str(audio_path),
]
result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
if result.returncode != 0:
raise RuntimeError(
f"ffmpeg audio extraction failed (exit {result.returncode}): {result.stderr[:500]}"
)
def transcribe_audio(
audio_path: Path,
model_name: str = DEFAULT_MODEL,
device: str = DEFAULT_DEVICE,
) -> dict:
"""Run Whisper on the audio file and return the raw result dict."""
# Import whisper here so --help works without the dependency installed
try:
import whisper # type: ignore[import-untyped]
except ImportError:
logger.error(
"openai-whisper is not installed. "
"Install it with: pip install openai-whisper"
)
sys.exit(1)
logger.info("Loading Whisper model '%s' on device '%s'...", model_name, device)
t0 = time.time()
model = whisper.load_model(model_name, device=device)
logger.info("Model loaded in %.1f s", time.time() - t0)
logger.info("Transcribing %s ...", audio_path.name)
t0 = time.time()
result = model.transcribe(
str(audio_path),
word_timestamps=True,
verbose=False,
)
elapsed = time.time() - t0
logger.info(
"Transcription complete in %.1f s (%.1fx real-time)",
elapsed,
(result.get("duration", elapsed) / elapsed) if elapsed > 0 else 0,
)
return result
def format_output(
whisper_result: dict,
source_file: str,
creator_folder: str,
duration_seconds: float | None,
) -> dict:
"""Convert Whisper result to the Chrysopedia spec JSON format."""
segments = []
for seg in whisper_result.get("segments", []):
words = []
for w in seg.get("words", []):
words.append(
{
"word": w.get("word", "").strip(),
"start": round(w.get("start", 0.0), 2),
"end": round(w.get("end", 0.0), 2),
}
)
segments.append(
{
"start": round(seg.get("start", 0.0), 2),
"end": round(seg.get("end", 0.0), 2),
"text": seg.get("text", "").strip(),
"words": words,
}
)
# Use duration from ffprobe if available, otherwise from whisper
if duration_seconds is None:
duration_seconds = whisper_result.get("duration", 0.0)
return {
"source_file": source_file,
"creator_folder": creator_folder,
"duration_seconds": round(duration_seconds),
"segments": segments,
}
def infer_creator_folder(video_path: Path) -> str:
"""
Infer creator folder name from directory structure.
Expected layout: /path/to/<CreatorName>/video.mp4
Falls back to parent directory name.
"""
return video_path.parent.name
def output_path_for(video_path: Path, output_dir: Path) -> Path:
"""Compute the output JSON path for a given video file."""
return output_dir / f"{video_path.stem}.json"
def process_single(
video_path: Path,
output_dir: Path,
model_name: str,
device: str,
creator_folder: str | None = None,
) -> Path | None:
"""
Process a single video file. Returns the output path on success, None if skipped.
"""
out_path = output_path_for(video_path, output_dir)
# Resumability: skip if output already exists
if out_path.exists():
logger.info("SKIP (output exists): %s", out_path)
return None
logger.info("Processing: %s", video_path)
# Determine creator folder
folder = creator_folder or infer_creator_folder(video_path)
# Get duration via ffprobe
duration = get_audio_duration(video_path)
if duration is not None:
logger.info("Video duration: %.0f s (%.1f min)", duration, duration / 60)
# Extract audio to temp file
with tempfile.TemporaryDirectory(prefix="chrysopedia_") as tmpdir:
audio_path = Path(tmpdir) / "audio.wav"
extract_audio(video_path, audio_path)
# Transcribe
whisper_result = transcribe_audio(audio_path, model_name, device)
# Format and write output
output = format_output(whisper_result, video_path.name, folder, duration)
output_dir.mkdir(parents=True, exist_ok=True)
with open(out_path, "w", encoding="utf-8") as f:
json.dump(output, f, indent=2, ensure_ascii=False)
segment_count = len(output["segments"])
logger.info("Wrote %s (%d segments)", out_path, segment_count)
return out_path
def find_videos(input_path: Path) -> list[Path]:
"""Find all supported video files in a directory (non-recursive)."""
videos = sorted(
p for p in input_path.iterdir()
if p.is_file() and p.suffix.lower() in SUPPORTED_EXTENSIONS
)
return videos
# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
prog="transcribe",
description=(
"Chrysopedia Whisper Transcription — extract timestamped transcripts "
"from video files using OpenAI's Whisper model."
),
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=(
"Examples:\n"
" # Single file\n"
" python transcribe.py --input video.mp4 --output-dir ./transcripts\n"
"\n"
" # Batch mode (all videos in directory)\n"
" python transcribe.py --input ./videos/ --output-dir ./transcripts\n"
"\n"
" # Use a smaller model on CPU\n"
" python transcribe.py --input video.mp4 --model base --device cpu\n"
),
)
parser.add_argument(
"--input",
required=True,
type=str,
help="Path to a video file or directory of video files",
)
parser.add_argument(
"--output-dir",
required=True,
type=str,
help="Directory to write transcript JSON files",
)
parser.add_argument(
"--model",
default=DEFAULT_MODEL,
type=str,
help=f"Whisper model name (default: {DEFAULT_MODEL})",
)
parser.add_argument(
"--device",
default=DEFAULT_DEVICE,
type=str,
help=f"Compute device: cuda, cpu (default: {DEFAULT_DEVICE})",
)
parser.add_argument(
"--creator",
default=None,
type=str,
help="Override creator folder name (default: inferred from parent directory)",
)
parser.add_argument(
"-v", "--verbose",
action="store_true",
help="Enable debug logging",
)
return parser
def main(argv: list[str] | None = None) -> int:
parser = build_parser()
args = parser.parse_args(argv)
if args.verbose:
logging.getLogger().setLevel(logging.DEBUG)
# Validate ffmpeg availability
if not check_ffmpeg():
logger.error(
"ffmpeg is not installed or not on PATH. "
"Install it with: sudo apt install ffmpeg (or equivalent)"
)
return 1
input_path = Path(args.input).resolve()
output_dir = Path(args.output_dir).resolve()
if not input_path.exists():
logger.error("Input path does not exist: %s", input_path)
return 1
# Single file mode
if input_path.is_file():
if input_path.suffix.lower() not in SUPPORTED_EXTENSIONS:
logger.error(
"Unsupported file type '%s'. Supported: %s",
input_path.suffix,
", ".join(sorted(SUPPORTED_EXTENSIONS)),
)
return 1
result = process_single(
input_path, output_dir, args.model, args.device, args.creator
)
if result is None:
logger.info("Nothing to do (output already exists).")
return 0
# Batch mode (directory)
if input_path.is_dir():
videos = find_videos(input_path)
if not videos:
logger.warning("No supported video files found in %s", input_path)
return 0
logger.info("Found %d video(s) in %s", len(videos), input_path)
processed = 0
skipped = 0
failed = 0
for i, video in enumerate(videos, 1):
logger.info("--- [%d/%d] %s ---", i, len(videos), video.name)
try:
result = process_single(
video, output_dir, args.model, args.device, args.creator
)
if result is not None:
processed += 1
else:
skipped += 1
except Exception:
logger.exception("FAILED: %s", video.name)
failed += 1
logger.info(
"Batch complete: %d processed, %d skipped, %d failed",
processed, skipped, failed,
)
return 1 if failed > 0 else 0
logger.error("Input is neither a file nor a directory: %s", input_path)
return 1
if __name__ == "__main__":
sys.exit(main())