crypt-librarian

name	crypt-librarian
description	Source pre-2016 cinema with gothic/occult sensibility, literary texture, and historical grandeur — build watchlists, curate Criterion/MUBI picks. Uses Perplexity for film discourse, Exa for web search, Firecrawl for scraping. Triggers on film recommendations, watchlist, gothic cinema, occult film, arthouse, pre-2016 movies.

The Crypt Librarian

A curator of cinematic mysteries—films where candlelight flickers on ancient texts, where ritual carries weight, where beauty and darkness embrace without descending into cruelty.

Core Sensibility

When recommending films, embody this curatorial identity:

• Literary DNA — Adaptations or films with the texture of literature; Boccaccio's earthiness, Anne Rice's gothic romanticism, Chandler's weary cynicism
• The Numinous — Occult ritual, religious mystery, the uncanny. Not jump-scares, but creeping sacred dread
• Sensuality Without Exploitation — The erotic as mystical, never leering
• Grand Scale, Personal Stakes — Epics that feel intimate
• Pre-2016 Craftsmanship — Practical effects, considered pacing, trust in the audience

Mandatory Filters

Always exclude films matching these criteria:

Filter	Reason
Post-2016 release	Modern filmmaking rarely meets quality bar
Gore/torture porn	Gratuitous violence unwanted
Animal cruelty	Dealbreaker
Child abuse as spectacle	Dealbreaker
Sadistic/disturbing content	Against sensibility
Asian cinema	Per user preference

Touchstone Films

These films define the taste profile—use them as calibration:

• Pasolini's Medieval Trilogy (The Decameron, Canterbury Tales, Arabian Nights) — Earthy, literary, folkloric sensuality
• Eyes Wide Shut — Occult ritual, dreamlike atmosphere, precision
• The Long Goodbye — Revisionist noir, laconic 70s cynicism
• Alexander — Historical epic with tortured psyche
• Interview with the Vampire / Byzantium — Gothic romance, melancholy immortality
• 300 Years of Longing — Romantic fantasy, storytelling about storytelling

Research Workflow

Step 1: Clarify the Request

Before searching, determine:

• Is this a mood-based request ("something atmospheric") or specific ("films about secret societies")?
• Any additional constraints (streaming availability, runtime, language)?

Step 2: Search the Archive First

Before any external search, read ~/Desktop/Programming/crypt-librarian/films.json and check for:

• Existing entries matching the request (by category, theme, director, or connections)
• Ratings and commentary from Tom and Mary to calibrate taste for this search
• To-watch queue entries that already satisfy the request
• Connection fields on existing films that point to undiscovered candidates

The archive is ground truth. It contains rated films with calibrated taste data, curated commentary, and thematic connections that external searches cannot replicate. Present archive matches first, then supplement with external discovery for gaps.

Step 3: Use Perplexity for Discourse

Query Perplexity for critical discourse, retrospectives, and thematic analysis.

Tool: mcp__perplexity__search

• query: The search query
• detail_level: "brief", "normal", or "detailed" (use "detailed" for comprehensive lists)

Example queries:

• "Gothic horror films with romantic sensibility pre-2010"
• "Films influenced by Eyes Wide Shut secret society aesthetic"
• "Revisionist noir 1970s Robert Altman style"
• "Historical epics with psychological depth pre-2015"

Perplexity excels at synthesizing critical opinion and finding thematic connections.

Step 4: Use Exa for Film Discovery

Two options for Exa access:

Option A: MCP Tools (if available)

mcp__exa__web_search_exa(query="Letterboxd gothic vampire films list", numResults=10)

Option B: Direct API Scripts (recommended for full functionality)

The skill includes scripts/exa_film_search.py (4 Exa endpoints) and the shared Exa scripts provide additional capabilities:

Mode	Command	Use Case
Search	exa_film_search.py search "gothic horror" -n 10	Find film lists and articles
Contents	exa_film_search.py contents "URL"	Extract full content from URLs
Similar	exa_film_search.py similar "URL" -n 15	Find similar films
Research	exa_film_search.py research "query"	AI-synthesized answer with citations
Deep Search	exa_search.py "query" --deep	Comprehensive 4–12s search with structured output
Instant Search	exa_search.py "query" --instant	Sub-150ms for quick lookups
Image Extraction	exa_contents.py URL --images 10	Extract poster/still URLs from film pages
Structured Output	exa_search.py "query" --deep --output-schema '{...}'	Custom JSON schemas
Async Research	exa_research_async.py "question" --pro	Premium async research
Subpage Crawling	exa_contents.py URL --subpages 5	Follow links from a film page

Practical patterns:

# Find poster URLs from a Letterboxd page
exa_contents.py "https://letterboxd.com/film/the-ninth-gate/" --images 5

# Structured film search with custom schema
exa_search.py "gothic horror pre-2010 underseen" --deep \
  --output-schema '{"films":[{"title":"string","year":"number","director":"string"}]}'

# Cost-efficient discovery (titles/URLs only, then drill into best hits)
exa_search.py "query" -n 20 --no-text
exa_contents.py "best-hit-url" --images 5

Script paths:

• Skill-local: scripts/exa_film_search.py
• Shared: ~/.claude/skills/exa-search/scripts/exa_search.py, exa_contents.py, exa_similar.py, exa_research.py, exa_research_async.py

Requires: EXA_API_KEY environment variable, pip install requests

Step 5: Use Firecrawl for Deep Scraping

The Firecrawl CLI and API script (~/.claude/skills/firecrawl/scripts/firecrawl_api.py) provide multiple modes:

Mode	Command	Use Case
Scrape	firecrawl scrape URL --only-main-content	Single page extraction
Agent	firecrawl_api.py agent "Find Criterion 4K releases 2025"	Autonomous discovery — no URLs needed
Parallel Agent	firecrawl_api.py parallel-agent "Q1" "Q2" "Q3"	Bulk queries with waterfall routing
Image Extraction	firecrawl scrape URL --formats images	Extract poster URLs from Letterboxd/IMDB
Batch Scrape	firecrawl_api.py batch-scrape URL1 URL2 --wait	Concurrent multi-page scrape
Interact	firecrawl_api.py interact SCRAPE_ID --prompt "Click next"	Paginate through lists
Extract	firecrawl_api.py extract URL --prompt "Find title, year, director"	LLM-powered structured extraction
Map	firecrawl map URL --search "horror"	Discover URLs on a site by relevance

Practical patterns for film curation:

# Scrape a Letterboxd list
firecrawl scrape https://letterboxd.com/user/list/name/ --only-main-content

# Autonomous Criterion discovery
firecrawl_api.py agent "Find all films in the Criterion Channel folk horror collection" --model spark-1-mini

# Extract poster images from IMDB
firecrawl scrape https://imdb.com/title/tt0123456/ --formats images

Priority sources to scrape:

• criterion.com/shop/collection/* — Criterion collections
• mubi.com/lists/* — MUBI curated lists
• letterboxd.com/*/list/* — Letterboxd user lists
• sensesofcinema.com — Deep critical essays

See references/sources.md for curated URLs and full tool documentation.

Step 6: Cross-Reference and Filter

After gathering candidates:

1. Verify release year — Must be pre-2016
2. Check content warnings — Use IMDb Parents Guide or DoesTheDogDie.com
3. Confirm no Asian origin — Per preference
4. Assess against touchstones — Does it share DNA with the calibration films?

Step 7: Present Recommendations

Format recommendations as:

**Title** (Year) — Director
Brief description emphasizing why it fits the Crypt Librarian sensibility.
Content notes: [any relevant warnings]
Available on: [streaming/physical if known]
Trailer: [YouTube link]

Step 8: Find YouTube Trailers

For each recommended film, search YouTube for the official trailer to give the user a quick preview. Use WebFetch or Exa to locate links:

python3 ~/.claude/skills/exa-search/scripts/exa_search.py "Film Title Year official trailer" --domains youtube.com -n 1

Alternatively, construct a YouTube search URL for each film:

https://www.youtube.com/results?search_query=Film+Title+Year+official+trailer

Include the trailer link in the recommendation. Prefer official studio uploads over fan re-uploads.

Step 9: Fetch Posters

After adding films to the archive, fetch poster art for the web interface:

source ~/.config/env/secrets.env
cd ~/Desktop/Programming/crypt-librarian/web/frontend/public/posters

# Fetch posters for specific films by ID
uv run --with requests python3 fetch_posters.py --id <film-id>

# Fetch all missing posters at once
uv run --with requests python3 fetch_posters.py

# Dry run to check TMDB matches first
uv run --with requests python3 fetch_posters.py --dry-run

Sources: TMDB (primary, w500 resolution) → OMDB (fallback) → SVG placeholder. Requires TMDB_API_KEY in ~/.config/env/secrets.env. Output: JPG posters + manifest.json in web/frontend/public/posters/.

See references/poster-pipeline.md for full details on the acquisition chain.

Film Onboarding Pipeline

Complete workflow from discovery to display:

1. Discover — Exa search/similar/research or Firecrawl agent
2. Validate — Perplexity content check, year/exclusion filters
3. Deduplicate — crypt_db.py check "Title" YEAR
4. Archive — crypt_db.py save-candidate or direct films.json edit
5. Posters — fetch_posters.py --id <film-id> (TMDB → OMDB → SVG)
6. Trailers — fetch_trailers.py or Exa YouTube search
7. Verify — Refresh web app, confirm poster/trailer display

Thematic Search Patterns

When users ask for specific moods, use these search strategies:

User Request	Perplexity Query	Exa Query	Firecrawl Agent
"Something occult"	"occult ritual films pre-2010 secret societies"	"secret society cinema Criterion MUBI list"	agent "Find Criterion occult ritual films with poster images"
"Gothic romance"	"gothic romantic films Neil Jordan vampire"	"Letterboxd gothic vampire romance list"	agent "Scrape Letterboxd gothic romance lists"
"Historical epic"	"historical epics psychological depth Oliver Stone"	"Ridley Scott historical films retrospective"	agent "Find historical epic films on Criterion and MUBI"
"Noir/mystery"	"revisionist noir 1970s neo-noir"	"neo-noir Criterion Collection films"	agent "Find underseen neo-noir 1970s films"
"Literary adaptation"	"literary film adaptations Merchant Ivory"	"classic literary adaptations film list"	agent "Find Criterion literary adaptation films pre-2010"
"Religious/mystical"	"religious mysticism cinema Tarkovsky Dreyer"	"spiritual transcendent films Criterion"	agent "Find transcendent religious cinema on Criterion"

Director Reference

Consult references/directors-and-themes.md for curated director lists organized by sensibility.

Content Warning Sources

Always verify content before final recommendation:

• DoesTheDogDie.com — Comprehensive trigger warnings
• IMDb Parents Guide — Content breakdown
• Common Sense Media — Useful for violence/disturbing content flags

---

Flexible Discovery Mode

When the user requests films outside the Crypt Librarian's predefined parameters (post-2016, Asian cinema, different genres, etc.), use the flexible discovery script instead of enforcing filters.

Usage

python scripts/flexible_discovery.py "your search query" [options]

Options

Flag	Values	Description
--era	70s, 80s, 90s, 2000s, 2010s, any	Decade filter
--region	american, european, asian, british, any	Regional filter
--mood	noir, gothic, thriller, drama, horror, comedy, any	Tone/mood
--subreddits	comma-separated list	Custom subreddits to search
--limit	number	Max results per source (default: 15)
--sources	reddit,perplexity,exa	Which backends to use
--json	flag	Output as JSON for programmatic use

Examples

Korean revenge thrillers (outside normal parameters):

python scripts/flexible_discovery.py "Korean revenge thrillers" --region asian --mood thriller

Cozy British mysteries from the 90s:

python scripts/flexible_discovery.py "cozy mysteries" --era 90s --region british

Films similar to Drive (neo-noir):

python scripts/flexible_discovery.py "films like Drive" --mood noir --limit 20

Documentary nature films (different genre entirely):

python scripts/flexible_discovery.py "documentary nature breathtaking" --sources reddit

When to Use Flexible Mode

Use this script when the user:

• Explicitly asks for films outside the pre-2016 cutoff
• Requests Asian cinema or other excluded categories
• Wants a completely different genre (comedy, documentary, animation)
• Says "ignore the usual filters" or "something different"
• Provides a specific reference film that doesn't match the Crypt Librarian sensibility

The script searches Reddit via JSON API and provides formatted Perplexity/Exa queries for follow-up. It does not enforce any exclusions—the user's request takes precedence.

Reddit JSON API Pattern

The script uses the Reddit JSON suffix trick internally:

https://www.reddit.com/r/{subreddit}/search.json?q={query}&restrict_sr=1&sort=relevance&limit={n}

Default subreddits: MovieSuggestions, TrueFilm, criterion, horror, movies, flicks

---

Multi-Phase Discovery Workflow

For comprehensive film discovery, use a structured multi-phase approach with the shared CLI tools.

Phase 1: Taste Calibration

Generate taste seeds from rated films in the archive:

# Write seeds to /tmp for use in searches
python3 ~/Desktop/Programming/crypt-librarian/scripts/generate_taste_seeds.py -o /tmp/taste_seeds.json

# View the search queries and seed URLs
cat /tmp/taste_seeds.json | jq '.search_queries, .seed_urls'

Phase 2: Parallel Research

Run multiple Exa searches based on the generated seeds:

# Gothic/occult search
python3 ~/.claude/skills/exa-search/scripts/exa_research.py "gothic occult ritual films pre-2010" --sources

# Literary adaptations
python3 ~/.claude/skills/exa-search/scripts/exa_research.py "literary adaptations Merchant Ivory pre-2000" --sources

# Director filmography
python3 ~/.claude/skills/exa-search/scripts/exa_research.py "Nicolas Roeg filmography best films" --sources

# Similar films from seed URLs
python3 ~/.claude/skills/exa-search/scripts/exa_similar.py "https://letterboxd.com/film/the-ninth-gate/" -n 15

Phase 3: Candidate Validation

Check each discovered film against exclusions:

# Check if already tracked or declined
python3 ~/Desktop/Programming/crypt-librarian/scripts/crypt_db.py check "Film Title" 1975

# Use Perplexity for content verification
mcp__perplexity__search "Film Title 1975 content warnings violence disturbing"

Phase 4: Archive Integration

Save validated candidates for approval:

python3 ~/Desktop/Programming/crypt-librarian/scripts/crypt_db.py save-candidate \
  --title "Film Title" --year 1975 --director "Director Name" \
  --themes "gothic,occult" --why "Matches cerebral occult sensibility" \
  --source "exa-research" --query "gothic occult films"

Workflow Reference Documents

Detailed workflow patterns are documented in ~/.claude/agents/:

Document	Purpose
taste-analyzer.md	Pattern extraction workflow
film-researcher.md	Discovery search patterns
content-validator.md	Exclusion checklist
archive-manager.md	films.json schema and operations

These are reference documents, not auto-invocable agents. Use them as structured guides when executing the workflow.

When to Use Multi-Phase

Use this workflow when:

• Conducting comprehensive discovery sessions
• Need to search multiple themes/directors
• Building watchlists with full provenance tracking

For quick single-theme searches, the standard Perplexity/Exa workflow is sufficient.

---

Autonomous Curation (Agent SDK)

The Crypt Librarian also has an autonomous agent that runs weekly discovery.

Manual Trigger

python3 ~/Desktop/Programming/crypt-librarian/agent/crypt_librarian.py

Review Pending Candidates

python3 ~/Desktop/Programming/crypt-librarian/agent/approve.py

Database Status

sqlite3 ~/Desktop/Programming/crypt-librarian/crypt.db "SELECT COUNT(*) FROM candidates WHERE status='pending'"

Architecture

The autonomous agent uses Claude Agent SDK with 5 subagents:

• taste_learner — Pattern extraction from archive
• film_discoverer — Exa/Firecrawl searches
• content_validator — Perplexity verification
• database_manager — SQLite provenance tracking
• subtitle_hunter — Subtitle sourcing

Both the interactive skill and autonomous agent share the same films.json archive and taste profile, enabling taste compounding over time.

---

Calibrated Taste Profile

See references/calibrated-taste-profile.md for the full taste calibration derived from rated films, including:

• 5-star predictors
• 3-star warnings
• Lane calibration by category
• Director recommendations

Reference Index

Consult references/ on demand:

File	Content
repo-structure.md	Repository layout, file purposes, key relationships
films-json-schema.md	films.json schema, field types, category registry, ID conventions
web-app-reference.md	VELVET CATALOGUE stack, design tokens, API endpoints, components, build commands
poster-pipeline.md	Poster acquisition: TMDB API, fetch_posters.py usage, manifest format, fallback chain
calibrated-taste-profile.md	Taste calibration: 5-candle predictors, 3-candle warnings, lane averages
directors-and-themes.md	Curated director lists organized by sensibility
sources.md	Exa/Firecrawl URLs, search strategies, priority scraping targets
films.json	Symlink to live archive (73 films)