vidlens-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,448 @@
+<p align="center">
+  <img src="assets/vidlens-logo.png" alt="VidLens" width="400" />
+</p>
+
+<p align="center">
+  <strong>The YouTube intelligence layer for AI agents</strong><br/>
+  <em>Zero config · 40 tools · Three-tier fallback · Transcript + visual search</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/vidlens-mcp"><img src="https://img.shields.io/npm/v/vidlens-mcp?style=flat-square&color=red" alt="npm" /></a>
+  <a href="https://github.com/rajanrengasamy/vidlens-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License" /></a>
+  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-green?style=flat-square" alt="MCP" /></a>
+  <img src="https://img.shields.io/badge/tools-40-orange?style=flat-square" alt="40 tools" />
+  <img src="https://img.shields.io/badge/zero--config-✓-brightgreen?style=flat-square" alt="Zero Config" />
+</p>
+
+---
+
+## 🔍 What is VidLens?
+
+VidLens is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI agents deep, reliable access to YouTube. Not just transcripts - full intelligence: sentiment analysis, trend discovery, semantic search, media assets, creator analytics, and image-backed visual search.
+
+**No API key required to start.** Every tool has a three-tier fallback chain (YouTube API → yt-dlp → page extraction) so nothing breaks when quota runs out or keys aren't configured.
+
+---
+
+## 🎯 Core Capabilities
+
+### 🔎 Semantic Search Across Playlists
+Import entire playlists or video sets, index every transcript with Gemini embeddings, and search across hundreds of hours of content by meaning — not just keywords.
+
+> *"Find every mention of gradient descent across 50 Stanford CS lectures"*
+>
+> *"What did the instructor say about backpropagation in any of these videos?"*
+
+### 👁️ Visual Search — See What's In Videos
+Extract keyframes, describe them with Gemini Vision, run OCR on slides and whiteboards, and search by what you **see** — not just what's said. Three layers: Apple Vision feature prints for image similarity, Gemini frame descriptions for scene understanding, and semantic embeddings for text→visual search.
+
+> *"Find the frame where he draws the system architecture diagram"*
+>
+> *"Show me every slide that mentions 'transformer architecture'"*
+
+### 📊 Intelligence Layer — Not Just Data
+Sentiment analysis with themes and risk signals. Niche trend discovery with momentum and saturation scoring. Content gap detection. Hook pattern analysis. Upload timing recommendations. The LLM does the thinking — VidLens gives it the right data.
+
+> *"What's the audience sentiment on this video? Any risk signals?"*
+>
+> *"What's trending in the AI coding niche right now?"*
+
+### ⚡ Zero Config, Always Works
+No API key needed to start. Three-tier fallback chain on every tool: YouTube API → yt-dlp → page extraction. Nothing breaks when quota runs out. Keys are optional power-ups, not requirements.
+
+### 🎬 Full Media Pipeline
+Download videos/audio/thumbnails. Extract keyframes. Index comments for semantic search. Build a local knowledge base from any YouTube content — all through natural language.
+
+---
+
+## ⚡ Why VidLens?
+
+<table>
+<tr><th></th><th>VidLens</th><th>Other YouTube MCP servers</th></tr>
+<tr><td>🔑 <strong>Setup</strong></td><td>✅ Works immediately - no keys needed</td><td>❌ Most require YouTube API key upfront</td></tr>
+<tr><td>🛡️ <strong>Reliability</strong></td><td>✅ Three-tier fallback on every tool</td><td>❌ Single point of failure - API down = broken</td></tr>
+<tr><td>🧠 <strong>Intelligence</strong></td><td>✅ Sentiment, trends, content gaps, hooks</td><td>❌ Raw data dumps - you do the analysis</td></tr>
+<tr><td>📦 <strong>Token efficiency</strong></td><td>✅ 75-87% smaller responses</td><td>❌ Verbose JSON with thumbnails, etags, junk</td></tr>
+<tr><td>🔬 <strong>Depth</strong></td><td>✅ 40 tools across 9 modules</td><td>⚠️ 1-5 tools, mostly transcripts only</td></tr>
+<tr><td>🖼️ <strong>Visual evidence</strong></td><td>✅ Returns actual frame paths + timestamps, not just text hits</td><td>⚠️ Usually transcript-only or raw frame dumps</td></tr>
+<tr><td>⚖️ <strong>Trademark</strong></td><td>✅ Compliant naming</td><td>⚠️ Most violate YouTube trademark</td></tr>
+</table>
+
+---
+
+## 🚀 Quick Start
+
+### 1. Install
+
+```bash
+npx vidlens-mcp setup
+```
+
+This auto-detects your MCP client (Claude Desktop, Cursor, etc.) and configures it.
+
+### 2. Or configure manually
+
+**Claude Desktop** - add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "vidlens-mcp": {
+      "command": "npx",
+      "args": ["-y", "vidlens-mcp", "serve"]
+    }
+  }
+}
+```
+
+### 3. Restart your MCP client
+
+Fully quit and reopen Claude Desktop (or your client). VidLens will appear in the tool list.
+
+### 4. Try it
+
+> "Import this playlist and search across all videos for mentions of machine learning"
+>
+> "Search this video's visuals for the whiteboard architecture diagram and show me the frame evidence"
+>
+> "What's trending in the AI coding niche right now?"
+>
+> "Build a complete dossier for this video — metadata, transcript, sentiment, hooks, everything"
+>
+> "What's the audience sentiment on this video? Any risk signals?"
+>
+> "Get the transcript of this video: https://youtube.com/watch?v=dQw4w9WgXcQ"
+
+---
+
+## 🧰 Tools - 40 across 9 modules
+
+### 📺 Core - Video & Channel Intelligence
+*Always available, no API key needed*
+
+| Tool | What it does |
+|---|---|
+| `findVideos` | Search YouTube by query with metadata |
+| `inspectVideo` | Deep metadata - tags, engagement, language, category |
+| `inspectChannel` | Channel stats, description, recent uploads |
+| `listChannelCatalog` | Browse a channel's full video library |
+| `readTranscript` | Full transcript with timestamps and chapters |
+| `readComments` | Top comments with likes and engagement |
+| `expandPlaylist` | List all videos in any playlist |
+
+### 🔎 Knowledge Base - Semantic Search
+*Index transcripts and search across them with natural language*
+
+| Tool | What it does |
+|---|---|
+| `importPlaylist` | Index an entire playlist's transcripts |
+| `importVideos` | Index specific videos by URL/ID |
+| `searchTranscripts` | Natural language search across indexed content |
+| `listCollections` | Browse your indexed collections |
+| `setActiveCollection` | Scope searches to one collection |
+| `clearActiveCollection` | Search across all collections |
+| `removeCollection` | Delete a collection and its index |
+
+### 💬 Sentiment & Analysis
+*Understand what audiences think and feel*
+
+| Tool | What it does |
+|---|---|
+| `measureAudienceSentiment` | Comment sentiment with themes and risk signals |
+| `analyzeVideoSet` | Compare performance across multiple videos |
+| `analyzePlaylist` | Playlist-level engagement analytics |
+| `buildVideoDossier` | Complete single-video deep analysis |
+
+### 🎯 Creator Intelligence
+*Insights for content strategy*
+
+| Tool | What it does |
+|---|---|
+| `scoreHookPatterns` | Analyze what makes video openings work |
+| `researchTagsAndTitles` | Tag and title optimization insights |
+| `compareShortsVsLong` | Short-form vs long-form performance |
+| `recommendUploadWindows` | Best times to publish for engagement |
+
+### 📈 Discovery & Trends
+*Find what's working in any niche*
+
+| Tool | What it does |
+|---|---|
+| `discoverNicheTrends` | Momentum, saturation, content gaps in any topic |
+| `exploreNicheCompetitors` | Channel landscape and top performers |
+
+### 🎬 Media Assets
+*Download and manage video files locally*
+
+| Tool | What it does |
+|---|---|
+| `downloadAsset` | Download video, audio, or thumbnails |
+| `listMediaAssets` | Browse stored media files |
+| `removeMediaAsset` | Clean up downloaded assets |
+| `extractKeyframes` | Extract key frames from videos |
+| `mediaStoreHealth` | Storage usage and diagnostics |
+
+### 🖼️ Visual Search
+*Three-layer visual intelligence. Not transcript reuse.*
+
+| Tool | What it does |
+|---|---|
+| `indexVisualContent` | Extract frames, run Apple Vision OCR + feature prints, Gemini frame descriptions, and Gemini semantic embeddings |
+| `searchVisualContent` | Search visual frames using semantic embeddings + lexical matching. Returns actual image paths + timestamps as evidence |
+| `findSimilarFrames` | Image-to-image frame similarity using Apple Vision feature prints |
+
+**Three layers, all real:**
+1. **Apple Vision feature prints** — image-to-image similarity (find frames that look alike)
+2. **Gemini 2.5 Flash frame descriptions** — natural language scene understanding per frame
+3. **Gemini semantic embeddings** — 768-dim embedding retrieval over OCR + description text for true text→visual search
+
+**What you always get back:** frame path on disk, timestamp, source video URL/title, match explanation, OCR text, visual description.
+
+**What is NOT happening:** no transcript embeddings are reused for visual search. This is a separate visual index.
+
+### 💭 Comment Knowledge Base
+*Index and semantically search YouTube comments*
+
+| Tool | What it does |
+|---|---|
+| `importComments` | Index a video's comments for search |
+| `searchComments` | Natural language search over comment corpus |
+| `listCommentCollections` | Browse comment collections |
+| `setActiveCommentCollection` | Scope comment searches |
+| `clearActiveCommentCollection` | Search all comment collections |
+| `removeCommentCollection` | Delete a comment collection |
+
+### 🏥 Diagnostics
+*Health checks and pre-flight validation*
+
+| Tool | What it does |
+|---|---|
+| `checkSystemHealth` | Full system diagnostic report |
+| `checkImportReadiness` | Validate before importing content |
+
+---
+
+## 🔑 API Keys (Optional)
+
+VidLens works **without any API keys**. Add them to unlock more capabilities:
+
+| Key | What it unlocks | Free? | How to get it |
+|---|---|---|---|
+| `YOUTUBE_API_KEY` | Better metadata, comment API, search via YouTube API | ✅ Free tier (10,000 units/day) | [Google Cloud Console](https://console.cloud.google.com/) → APIs → Enable YouTube Data API v3 → Credentials → Create API Key |
+| `GEMINI_API_KEY` | Higher-quality embeddings for semantic search (768d vs 384d) | ✅ Free tier | [Google AI Studio](https://aistudio.google.com/) → Get API Key |
+
+> ⚠️ **These are separate keys from separate Google services.** A Gemini key will NOT work for YouTube API calls and vice versa. Create them independently.
+
+```bash
+# Configure via setup wizard
+npx vidlens-mcp setup --youtube-api-key YOUR_YOUTUBE_KEY --gemini-api-key YOUR_GEMINI_KEY
+
+# Or via environment variables
+export YOUTUBE_API_KEY=your_youtube_key
+export GEMINI_API_KEY=your_gemini_key
+```
+
+---
+
+## 💻 CLI
+
+```bash
+npx vidlens-mcp               # Start MCP server (stdio)
+npx vidlens-mcp serve         # Start MCP server (explicit)
+npx vidlens-mcp setup         # Auto-configure MCP clients
+npx vidlens-mcp doctor        # Run diagnostics
+npx vidlens-mcp version       # Print version
+npx vidlens-mcp help          # Usage guide
+```
+
+### Doctor - diagnose issues
+
+```bash
+npx vidlens-mcp doctor --no-live
+```
+
+Checks: Node.js version, yt-dlp availability, API key validation, data directory health, MCP client detection (Claude Desktop, ChatGPT Desktop, Cursor, VS Code).
+
+---
+
+## 🏗️ Architecture
+
+### System Overview
+
+```mermaid
+graph TB
+    subgraph Client["MCP Client"]
+        Claude["Claude Desktop"]
+        Cursor["Cursor"]
+        VSCode["VS Code"]
+        Other["Any MCP Client"]
+    end
+
+    subgraph VidLens["VidLens MCP Server"]
+        Router["Tool Router"]
+        
+        subgraph Modules["9 Tool Modules · 40 Tools"]
+            Core["📺 Core<br/>7 tools"]
+            KB["🔎 Knowledge Base<br/>7 tools"]
+            Sentiment["💬 Sentiment<br/>4 tools"]
+            Creator["🎯 Creator Intel<br/>4 tools"]
+            Trends["📈 Discovery<br/>2 tools"]
+            Media["🎬 Media<br/>5 tools"]
+            Visual["🖼️ Visual Search<br/>3 tools"]
+            Comments["💭 Comments<br/>6 tools"]
+            Diag["🏥 Diagnostics<br/>2 tools"]
+        end
+
+        subgraph Storage["Local Storage"]
+            SQLite["SQLite + sqlite-vec"]
+            Embeddings["Embedding Index<br/>384d / 768d vectors"]
+            MediaStore["Media Store<br/>video · audio · frames"]
+        end
+
+        subgraph Fallback["Three-Tier Fallback Chain"]
+            T1["① YouTube Data API v3"]
+            T2["② yt-dlp"]
+            T3["③ Page extraction"]
+        end
+    end
+
+    subgraph External["External Services"]
+        YT["YouTube"]
+        Gemini["Gemini API"]
+        AppleVision["Apple Vision"]
+    end
+
+    Client -->|stdio / SSE| Router
+    Router --> Modules
+    Modules --> Fallback
+    Fallback --> YT
+    KB --> SQLite
+    KB --> Embeddings
+    Visual --> Embeddings
+    Visual --> MediaStore
+    Visual --> AppleVision
+    Visual --> Gemini
+    Comments --> SQLite
+    Media --> MediaStore
+
+    T1 -.->|"quota exceeded?"| T2
+    T2 -.->|"unavailable?"| T3
+```
+
+### How the Fallback Chain Works
+
+Every tool that touches YouTube data uses the same resilience pattern:
+
+```mermaid
+flowchart LR
+    Request["Tool call"] --> Check{"API key<br/>configured?"}
+    Check -->|Yes| API["YouTube API v3"]
+    Check -->|No| YTD["yt-dlp"]
+    API -->|"200 ✓"| OK["Return data +<br/>provenance tag"]
+    API -->|"403 / quota"| YTD
+    YTD -->|"✓"| OK
+    YTD -->|"error"| Page["Page Extraction"]
+    Page -->|"✓"| OK
+    Page -->|"error"| Fail["Graceful error +<br/>fallback report"]
+```
+
+Every response includes a `provenance` field telling you exactly which tier served the data and whether anything was partial. No silent degradation — you always know what happened.
+
+### Visual Search Pipeline
+
+Visual search is not transcript reuse. It's a dedicated three-layer index:
+
+```mermaid
+flowchart TB
+    Video["Video URL"] --> Extract["Extract Keyframes<br/>ffmpeg scene detection"]
+    
+    Extract --> L1["Layer 1: Apple Vision<br/>Feature prints + OCR"]
+    Extract --> L2["Layer 2: Gemini Vision<br/>Frame descriptions"]
+    
+    L1 --> FP["Feature Print Index"]
+    L1 --> OCR["OCR Text"]
+    L2 --> Desc["Scene Descriptions"]
+    
+    OCR --> L3["Layer 3: Gemini Embeddings<br/>768-dim semantic vectors"]
+    Desc --> L3
+    
+    L3 --> VecDB["sqlite-vec Index"]
+    FP --> VecDB
+    
+    VecDB --> Search["searchVisualContent / findSimilarFrames"]
+    Search --> Results["Frame path · Timestamp · Source video<br/>Match reason · OCR text · Visual description"]
+```
+
+**Three layers, all real:**
+1. **Apple Vision feature prints** — image-to-image similarity (find frames that *look* alike)
+2. **Gemini Vision frame descriptions** — natural language scene understanding per frame
+3. **Gemini semantic embeddings** — 768-dim retrieval over OCR + description text
+
+### Data Storage
+
+Everything lives in a single directory. No external databases, no Docker, no infrastructure.
+
+```
+~/.vidlens/
+├── vidlens.db            # Metadata, embeddings, indexes (sqlite-vec)
+├── media/
+│   └── {video-id}/
+│       ├── video.mp4
+│       ├── audio.mp3
+│       └── frames/
+│           ├── frame_001_00m30s.jpg
+│           └── frame_002_01m15s.jpg
+└── logs/                 # Diagnostics output
+```
+
+One directory. Portable. Back it up by copying. Delete it to start fresh.
+
+---
+
+## 📋 Requirements
+
+| Requirement | Status | Notes |
+|---|---|---|
+| **Node.js ≥ 20** | Required | `node --version` to check |
+| **yt-dlp** | Recommended | `brew install yt-dlp` - enables zero-config mode |
+| **ffmpeg** | Optional | Needed for frame extraction and visual indexing |
+| **YouTube API key** | Optional | Unlocks comments, better metadata |
+| **Gemini API key** | Optional | Upgrades transcript embeddings and frame descriptions for visual search |
+| **macOS Apple Vision** | Automatic on macOS | Powers native OCR and image similarity for visual search |
+
+---
+
+## 🔧 Troubleshooting
+
+### "Tool not found" in Claude Desktop
+Fully quit Claude Desktop (⌘Q, not just close window) and reopen. MCP servers only load on startup.
+
+### "YOUTUBE_API_KEY not configured" warning
+This is informational, not an error. VidLens works without it. Add a key only if you need comments/sentiment features.
+
+### "API_KEY_SERVICE_BLOCKED" error
+Your API key has restrictions. Create a new **unrestricted** key in Google Cloud Console, or remove the API restriction from the existing key.
+
+### Gemini key doesn't work for YouTube API
+These are **separate services**. You need a YouTube API key from Google Cloud Console AND a Gemini key from Google AI Studio. They are not interchangeable.
+
+### Build errors
+```bash
+npx vidlens-mcp doctor     # Run diagnostics
+npx vidlens-mcp doctor --no-live  # Skip network checks
+```
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+<p align="center">
+  <a href="https://github.com/rajanrengasamy/vidlens-mcp">GitHub</a> ·
+  <a href="https://www.npmjs.com/package/vidlens-mcp">npm</a> ·
+  <a href="https://modelcontextprotocol.io/">Model Context Protocol</a>
+</p>

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from "./lib/cli-runtime.js";
+runCli(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof Error ? error.stack ?? error.message : String(error);
+    process.stderr.write(`vidlens-mcp failed: ${message}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC5C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,OAAO,IAAI,CAAC,CAAC;IACzD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createYouTubeMcpServer, startStdioServer, tools } from "./server/mcp-server.js";
+export { YouTubeService } from "./lib/youtube-service.js";
+export { CommentKnowledgeBase } from "./lib/comment-knowledge-base.js";
+export { MediaStore } from "./lib/media-store.js";
+export { MediaDownloader } from "./lib/media-downloader.js";
+export { ThumbnailExtractor } from "./lib/thumbnail-extractor.js";
+export { VisualIndexStore, VisualSearchEngine } from "./lib/visual-search.js";
+export * from "./lib/types.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { createYouTubeMcpServer, startStdioServer, tools } from "./server/mcp-server.js";
+export { YouTubeService } from "./lib/youtube-service.js";
+export { CommentKnowledgeBase } from "./lib/comment-knowledge-base.js";
+export { MediaStore } from "./lib/media-store.js";
+export { MediaDownloader } from "./lib/media-downloader.js";
+export { ThumbnailExtractor } from "./lib/thumbnail-extractor.js";
+export { VisualIndexStore, VisualSearchEngine } from "./lib/visual-search.js";
+export * from "./lib/types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AACzF,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC9E,cAAc,gBAAgB,CAAC"}

package/dist/lib/analysis.d.ts

@@ -0,0 +1,71 @@
+import type { Chapter, CommentRecord, ContentGap, NicheMomentum, NicheSaturation, TranscriptRecord, TranscriptSegment, TrendingVideo, VideoRecord } from "./types.js";
+export interface SentimentSummary {
+    positivePct: number;
+    neutralPct: number;
+    negativePct: number;
+    sentimentScore: number;
+}
+export interface ThemeScore {
+    theme: string;
+    prevalencePct: number;
+    sentimentScore: number;
+}
+export interface RiskSignal {
+    signal: string;
+    severity: "low" | "medium" | "high";
+    frequencyPct: number;
+}
+export interface QuoteSample {
+    text: string;
+    sentiment: "positive" | "neutral" | "negative";
+}
+export interface HookPatternResult {
+    hookScore: number;
+    hookType: "question" | "promise" | "shock" | "story" | "proof" | "other";
+    first30SecSummary: string;
+    weakSignals: string[];
+    improvements: string[];
+}
+export declare function median(values: number[]): number | undefined;
+export declare function percentile(values: number[], ratio: number): number | undefined;
+export declare function average(values: number[]): number | undefined;
+export declare function inferVideoFormat(durationSec?: number): "short" | "long" | "unknown";
+export declare function computeEngagementRate(video: Pick<VideoRecord, "views" | "likes" | "comments">): number | undefined;
+export declare function computeCommentRate(video: Pick<VideoRecord, "views" | "comments">): number | undefined;
+export declare function computeLikeRate(video: Pick<VideoRecord, "views" | "likes">): number | undefined;
+export declare function computeViewVelocity24h(views: number | undefined, publishedAt?: string): number | undefined;
+export declare function summarizeText(text: string, maxSentences?: number): string;
+export declare function parseDescriptionChapters(description?: string): Chapter[];
+export declare function buildTranscriptSegmentsForWindow(transcript: TranscriptRecord, windowSec: number, maxSegments?: number): TranscriptSegment[];
+export declare function buildChapterTranscriptSegments(transcript: TranscriptRecord): TranscriptSegment[];
+export declare function analyzeComments(comments: CommentRecord[], includeThemes?: boolean, includeQuotes?: boolean): {
+    sentiment: SentimentSummary;
+    themes?: ThemeScore[];
+    riskSignals: RiskSignal[];
+    representativeQuotes?: QuoteSample[];
+};
+export declare function scoreHookPattern(videoId: string, transcript: TranscriptRecord, hookWindowSec?: number): HookPatternResult;
+export declare function extractRecurringKeywords(videos: VideoRecord[], limit?: number): string[];
+export declare function titleStructure(title: string): string;
+/**
+ * Compute momentum indicator by comparing recent videos vs older videos.
+ * Splits the video set by median publish date and compares median views.
+ */
+export declare function computeNicheMomentum(videos: TrendingVideo[], lookbackDays: number): NicheMomentum;
+/**
+ * Estimate niche saturation from the view distribution of search results.
+ */
+export declare function computeNicheSaturation(videos: TrendingVideo[]): NicheSaturation;
+/**
+ * Detect content gap angles from title/tag patterns. Heuristic:
+ * look for under-represented sub-topics and format gaps.
+ */
+export declare function detectContentGaps(videos: TrendingVideo[], niche: string): ContentGap[];
+/**
+ * Compute format breakdown percentages.
+ */
+export declare function computeFormatBreakdown(videos: TrendingVideo[]): {
+    shortsPct: number;
+    longFormPct: number;
+    unknownPct: number;
+};