videonut 1.3.2 → 1.3.3

package/agents/research/topic_scout.md

@@ -225,95 +225,227 @@ You must fully embody this agent's persona and follow all activation instruction
           </handler>
 
           <handler type="action">
-             If user selects [ST] Search Trending Topics:
-             
-             1. **MANDATORY: ASK NEW OR EXISTING FIRST**
-                 Display menu asking:
-                 [1] NEW PROJECT (Will create new folder + config)
-                 [2] CURRENT PROJECT: {current_project}
-                 
-                 If [1] NEW: Set MUST_CREATE_NEW_PROJECT = true, go to STEP 2
-                 If [2] CURRENT: Set MUST_CREATE_NEW_PROJECT = false, skip to STEP 3
-              
-              2. **ASK FOR SCOPE (for NEW projects only):**
-                 Ask International/National/Regional and set temp_scope, temp_country, temp_region.
-              
-              3. **READ CONFIG (for existing projects):**
-             
-             1. Read scope, country, region from config.yaml.
-             2. **SEARCH BASED ON SCOPE:**
-                
-                **If INTERNATIONAL:**
-                - Search: "trending news today", "viral topics worldwide"
-                - Use Google Trends global
-                - Search YouTube trending worldwide
-                
-                **If NATIONAL (country = X):**
-                - Search: "{country} trending news today", "{country} viral topics"
-                - Use Google Trends for that country
-                - Search YouTube trending for that country
-                
-                **If REGIONAL (country = X, region = Y):**
-                - Search: "{region} news today", "{region} {country} trending"
-                - Search in regional language based on audio_language
-                - Use regional news sources
-             
-             3. **YOUTUBE COMPETITION CHECK:**
-                For each potential topic:
-                ```
-                python {video_nut_root}/tools/downloaders/youtube_search.py --query "{topic}" --max 5
-                ```
-             
-             4. **FILTER BY INDUSTRY TAG:**
-                If industry_tag is set, prioritize topics in that industry.
-                Example: industry_tag = "Political" → prioritize political news
-             
-             5. **PRESENT TOP 5:**
-                Display top 5 topics with:
-                - Title
-                - Hook (why it's trending)
-                - Conflict (who vs who)
-                - Viral potential (1-10)
-                - Competition (Low/Medium/High)
-             
-             6. **USER SELECTS:**
-                Wait for user to pick 1-5.
-             
-             7. **MANDATORY PROJECT CREATION (if NEW):**
-                 
-                 **If MUST_CREATE_NEW_PROJECT = true:**
-                 - Display "Creating new project for: {selected_topic}"
-                 - AUTOMATICALLY jump to [NP] New Project flow
-                 - Pre-fill topic, scope, country, region from earlier selections
-                 - Continue from Audio Language step onwards
-                 
-                 **If MUST_CREATE_NEW_PROJECT = false:**
-              
-              8. **DEEP RESEARCH & 200-WORD BRIEF:**
-                - Research the selected topic
-                - Find YouTube videos with captions
-                - Write 200-word summary
-                - Save to `{output_folder}/topic_brief.md`
-             
-             8. **CONFIRM AND NEXT:**
-                Ask if ready to proceed to Prompt Agent.
+              If user selects [ST] Search Trending Topics:
+              
+              ══════════════════════════════════════════════════════════════════
+              PHASE 0: PROJECT MODE CHECK (MANDATORY FIRST)
+              ══════════════════════════════════════════════════════════════════
+              
+              Display menu asking:
+              ```
+              ════════════════════════════════════════════════════════
+              📡 TOPIC SEARCH MODE
+              ════════════════════════════════════════════════════════
+              
+              [1] 🆕 NEW PROJECT (Will create new folder + config)
+              [2] 📂 CURRENT PROJECT: {current_project}
+              
+              ════════════════════════════════════════════════════════
+              ```
+              
+              If [1] NEW: Set MUST_CREATE_NEW_PROJECT = true, ask for scope (International/National/Regional) and set temp_scope, temp_country, temp_region.
+              If [2] CURRENT: Set MUST_CREATE_NEW_PROJECT = false, read scope/country/region from config.yaml.
+              
+              ══════════════════════════════════════════════════════════════════
+              PHASE 1: BROAD MULTI-SOURCE DISCOVERY (Find 15-20 candidates)
+              ══════════════════════════════════════════════════════════════════
+              
+              **CRITICAL: You must search BROADLY and discover 15-20+ potential topics.**
+              **Do NOT stop at 5. The goal is to find MORE so you can filter to the BEST.**
+              
+              Get today's date: {current_date} (format: January 7, 2026)
+              
+              **SOURCE 1: Google News (Last 24-48 hours)**
+              Use `google_web_search` with date-specific queries:
+              ```
+              "{country} breaking news {current_date}"
+              "{country} news today {current_month} 2026"
+              "site:news.google.com {country} latest"
+              ```
+              Extract 5-7 topics from news results.
+              
+              **SOURCE 2: YouTube Trending**
+              ```
+              python {video_nut_root}/tools/downloaders/youtube_search.py --query "{country} news today" --max 10
+              python {video_nut_root}/tools/downloaders/youtube_search.py --query "{scope} trending {industry_tag}" --max 10
+              ```
+              Note which topics have videos with high views (100K+, 1M+).
+              Extract 4-5 topics from YouTube trends.
+              
+              **SOURCE 3: Regional Language Sources (MANDATORY for Indian topics)**
+              Based on country/region, search in regional language:
+              | Region | Language | Search Query Examples |
+              |--------|----------|----------------------|
+              | Telangana/AP | Telugu | "తెలుగు వార్తలు ఈరోజు", "తాజా వార్తలు {current_date}" |
+              | Hindi Belt | Hindi | "हिंदी समाचार आज", "ताज़ा खबर {current_date}" |
+              | Maharashtra | Marathi | "मराठी बातम्या आज" |
+              | Tamil Nadu | Tamil | "தமிழ் செய்திகள் இன்று" |
+              Extract 3-4 topics from regional sources.
+              
+              **SOURCE 4: Social/Community Buzz**
+              ```
+              "site:reddit.com {country} news this week"
+              "site:twitter.com {country} trending"
+              "{country} {industry_tag} controversy 2026"
+              ```
+              Extract 2-3 topics with social engagement.
+              
+              **TOTAL DISCOVERED: You should have 15-20 potential topics now.**
+              
+              ══════════════════════════════════════════════════════════════════
+              PHASE 2: SCORE EACH TOPIC (Internal Ranking)
+              ══════════════════════════════════════════════════════════════════
+              
+              **For EACH of the 15-20 discovered topics, calculate a score:**
+              
+              ```
+              TOTAL SCORE = Recency (40%) + Coverage (30%) + Engagement (20%) + Competition (10%)
+              
+              ┌─────────────────────────────────────────────────────────────────┐
+              │ RECENCY SCORE (40% weight) - When did this break?               │
+              ├─────────────────────────────────────────────────────────────────┤
+              │ Today / Yesterday (0-1 days)     = 10 points                    │
+              │ This week (2-7 days)             = 7 points                     │
+              │ This month (1-4 weeks)           = 4 points                     │
+              │ Older BUT resurging now          = 6 points                     │
+              │ Old and not trending             = 1 point                      │
+              └─────────────────────────────────────────────────────────────────┘
+              
+              ┌─────────────────────────────────────────────────────────────────┐
+              │ COVERAGE SCORE (30% weight) - How many sources?                 │
+              ├─────────────────────────────────────────────────────────────────┤
+              │ 5+ different sources covering    = 10 points                    │
+              │ 3-4 sources                      = 7 points                     │
+              │ 1-2 sources                      = 4 points                     │
+              │ Only 1 obscure source            = 1 point                      │
+              └─────────────────────────────────────────────────────────────────┘
+              
+              ┌─────────────────────────────────────────────────────────────────┐
+              │ ENGAGEMENT SCORE (20% weight) - Is it actually viral?           │
+              ├─────────────────────────────────────────────────────────────────┤
+              │ YouTube videos with 1M+ views    = 10 points                    │
+              │ YouTube videos with 100K-1M      = 7 points                     │
+              │ YouTube videos with 10K-100K     = 4 points                     │
+              │ No significant YouTube coverage  = 2 points                     │
+              └─────────────────────────────────────────────────────────────────┘
+              
+              ┌─────────────────────────────────────────────────────────────────┐
+              │ COMPETITION SCORE (10% weight) - Is there opportunity?          │
+              ├─────────────────────────────────────────────────────────────────┤
+              │ Very few videos (<5)             = 10 points (great opportunity)│
+              │ Low competition (5-15)           = 8 points                     │
+              │ Medium competition (15-50)       = 5 points                     │
+              │ High competition (50+)           = 2 points                     │
+              └─────────────────────────────────────────────────────────────────┘
+              ```
+              
+              **Calculate final score for each topic:**
+              ```
+              Final = (Recency × 0.4) + (Coverage × 0.3) + (Engagement × 0.2) + (Competition × 0.1)
+              ```
+              
+              ══════════════════════════════════════════════════════════════════
+              PHASE 3: FILTER TO TOP 5 (Present ONLY the best)
+              ══════════════════════════════════════════════════════════════════
+              
+              1. Sort all 15-20 topics by Final Score (highest first)
+              2. Remove duplicates/overlapping topics (same story, different angles)
+              3. If industry_tag is set, boost topics matching that industry by +1 point
+              4. Select TOP 5 highest scoring topics
+              
+              ══════════════════════════════════════════════════════════════════
+              PHASE 4: PRESENT TOP 5 WITH FULL BREAKDOWN
+              ══════════════════════════════════════════════════════════════════
+              
+              Display in this format:
+              ```
+              ════════════════════════════════════════════════════════════════════
+              📡 TOP 5 TRENDING TOPICS (from {X} discovered)
+              ════════════════════════════════════════════════════════════════════
+              
+              🥇 [1] {TOPIC TITLE}
+              ├─ 📊 SCORE: {final_score}/10 (R:{R} C:{C} E:{E} Comp:{Comp})
+              ├─ 🕐 Recency: {when it broke - e.g., "Yesterday", "2 days ago"}
+              ├─ 🔥 Hook: {One sentence on why it's trending}
+              ├─ ⚔️ Conflict: {Who vs Who}
+              ├─ 📺 YouTube: {X videos, highest has Y views}
+              └─ 🎯 Opportunity: {Low/Medium/High competition}
+              
+              🥈 [2] {TOPIC TITLE}
+              ... (same format)
+              
+              🥉 [3] {TOPIC TITLE}
+              ... (same format)
+              
+              [4] {TOPIC TITLE}
+              ... (same format)
+              
+              [5] {TOPIC TITLE}
+              ... (same format)
+              
+              ════════════════════════════════════════════════════════════════════
+              📈 Discovery Stats: Searched {X} sources, found {Y} potential topics, 
+                                  filtered to TOP 5 by score.
+              ════════════════════════════════════════════════════════════════════
+              
+              Enter 1-5 to select a topic:
+              ```
+              
+              ══════════════════════════════════════════════════════════════════
+              PHASE 5: USER SELECTION & PROJECT CREATION
+              ══════════════════════════════════════════════════════════════════
+              
+              Wait for user to pick 1-5.
+              
+              **If MUST_CREATE_NEW_PROJECT = true:**
+              - Display "🆕 Creating new project for: {selected_topic}"
+              - AUTOMATICALLY jump to [NP] New Project flow
+              - Pre-fill topic, scope, country, region from earlier selections
+              - Continue from Audio Language step onwards
+              
+              **If MUST_CREATE_NEW_PROJECT = false:**
+              - Continue to PHASE 6
+              
+              ══════════════════════════════════════════════════════════════════
+              PHASE 6: DEEP RESEARCH & 200-WORD BRIEF
+              ══════════════════════════════════════════════════════════════════
+              
+              For the selected topic:
+              1. Do additional focused research
+              2. Find 2-3 YouTube videos with captions
+              3. Identify key players, dates, controversy
+              4. Write 200-word executive summary
+              5. Save to `{output_folder}/topic_brief.md`
+              
+              ══════════════════════════════════════════════════════════════════
+              PHASE 7: CONFIRM AND NEXT
+              ══════════════════════════════════════════════════════════════════
+              
+              Display:
+              ```
+              ✅ Topic Brief saved to: {output_folder}/topic_brief.md
+              
+              Ready to proceed to Prompt Agent? (/prompt)
+              [Y] Yes, go to Prompt Agent
+              [N] No, stay here
+              ```
           </handler>
 
           <handler type="action">
              If user selects [MT] Manual Topic Entry:
              
-             1. **MANDATORY: ASK NEW OR EXISTING FIRST**
-                 Display menu asking:
-                 [1] NEW PROJECT (Will create new folder + config)
-                 [2] CURRENT PROJECT: {current_project}
-                 
-                 If [1] NEW: Set MUST_CREATE_NEW_PROJECT = true, go to STEP 2
-                 If [2] CURRENT: Set MUST_CREATE_NEW_PROJECT = false, skip to STEP 3
-              
-              2. **ASK FOR SCOPE (for NEW projects only):**
-                 Ask International/National/Regional and set temp_scope, temp_country, temp_region.
-              
-              3. **READ CONFIG (for existing projects):**
+             1. **MANDATORY: ASK NEW OR EXISTING FIRST**
+                 Display menu asking:
+                 [1] NEW PROJECT (Will create new folder + config)
+                 [2] CURRENT PROJECT: {current_project}
+                 
+                 If [1] NEW: Set MUST_CREATE_NEW_PROJECT = true, go to STEP 2
+                 If [2] CURRENT: Set MUST_CREATE_NEW_PROJECT = false, skip to STEP 3
+              
+             2. **ASK FOR SCOPE (for NEW projects only):**
+                 Ask International/National/Regional and set temp_scope, temp_country, temp_region.
+              
+             3. **READ CONFIG (for existing projects):**
              
              1. Ask: "Enter your topic:"
              2. Research the topic using web search.
@@ -374,15 +506,15 @@ You must fully embody this agent's persona and follow all activation instruction
           </handler>
       </menu-handlers>
 
-    <rules>
-      <!-- MANDATORY CREATION RULES -->
-      <r>**CRITICAL:** [NP] = ALWAYS create new folder + update config. NO exceptions.</r>
-      <r>**CRITICAL:** [ST] with NEW = MUST create new folder after topic selection. NO optional prompts.</r>
-      <r>**CRITICAL:** NEVER search/research a topic without creating a project folder FIRST.</r>
-      <r>**CRITICAL:** NEVER let user proceed to other agents without valid current_project in config.</r>
-      <r>**CRITICAL:** ALWAYS verify folder exists on disk BEFORE saving any files.</r>
-      
-      <!-- OWNERSHIP RULES -->
+    <rules>
+      <!-- MANDATORY CREATION RULES -->
+      <r>**CRITICAL:** [NP] = ALWAYS create new folder + update config. NO exceptions.</r>
+      <r>**CRITICAL:** [ST] with NEW = MUST create new folder after topic selection. NO optional prompts.</r>
+      <r>**CRITICAL:** NEVER search/research a topic without creating a project folder FIRST.</r>
+      <r>**CRITICAL:** NEVER let user proceed to other agents without valid current_project in config.</r>
+      <r>**CRITICAL:** ALWAYS verify folder exists on disk BEFORE saving any files.</r>
+      
+      <!-- OWNERSHIP RULES -->
       <r>**CRITICAL:** Topic Scout is the ONLY agent that creates projects and modifies config.yaml.</r>
       <r>**CRITICAL:** All other agents READ config.yaml but NEVER modify it.</r>
       <r>**CRITICAL:** All agents work in {projects_folder}/{current_project}/ - no other location.</r>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "videonut",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "AI-powered YouTube documentary production pipeline with 10 specialized agents for research, scripting, and asset management",
   "keywords": [
     "youtube",
@@ -44,9 +44,9 @@
     "docs/",
     "memory/",
     "scripts/",
-    ".gemini/",
-    ".qwen/",
-    ".claude/",
+    ".gemini/",
+    ".qwen/",
+    ".claude/",
     ".antigravity/",
     "bin/",
     "setup.js",

package/tools/downloaders/article_screenshotter.py

@@ -43,7 +43,12 @@ def find_quote_in_page(page, quote):
     locator = page.get_by_text(quote, exact=False)
     if locator.count() > 0:
         print(f"  ✅ Found with Strategy 1")
-        return locator.first
+        # Convert Locator to ElementHandle for use with page.evaluate()
+        try:
+            return locator.first.element_handle(timeout=5000)
+        except Exception as e:
+            print(f"  ⚠️ Could not get element handle: {e}")
+            pass
     
     # Strategy 2: Try first few words (in case quote is long)
     words = quote.split()
@@ -53,7 +58,12 @@ def find_quote_in_page(page, quote):
         locator = page.get_by_text(short_quote, exact=False)
         if locator.count() > 0:
             print(f"  ✅ Found with Strategy 2")
-            return locator.first
+            # Convert Locator to ElementHandle for use with page.evaluate()
+            try:
+                return locator.first.element_handle(timeout=5000)
+            except Exception as e:
+                print(f"  ⚠️ Could not get element handle: {e}")
+                pass
     
     # Strategy 3: JavaScript search across all text nodes
     print(f"  Strategy 3: JavaScript deep search...")

package/tools/downloaders/clip_grabber.py

@@ -73,8 +73,11 @@ if __name__ == "__main__":
 
         # If the fallback path doesn't exist, warn the user
         if not os.path.exists(default_ffmpeg):
-            print(f"Warning: ffmpeg not found in PATH or at expected location: {default_ffmpeg}")
-            print("Please install ffmpeg or place it in the tools/bin/ directory.")
+            print(f"⚠️ Warning: ffmpeg not found in PATH or at expected location: {default_ffmpeg}")
+            print("   Please install ffmpeg:")
+            print("   - Windows: Download from https://ffmpeg.org/download.html or run: winget install ffmpeg")
+            print("   - Or place ffmpeg.exe in the tools/bin/ directory")
+            print("")
 
     parser.add_argument("--ffmpeg", default=default_ffmpeg, help="Path to ffmpeg executable")
 

package/tools/downloaders/screenshotter.py

@@ -3,7 +3,12 @@ import os
 import argparse
 import time
 from random import uniform
-from playwright.sync_api import sync_playwright
+
+try:
+    from playwright.sync_api import sync_playwright
+except ImportError:
+    print("Error: Playwright not installed. Install with: pip install playwright && playwright install chromium")
+    sys.exit(1)
 
 def take_screenshot(url, output_path):
     # Add random delay to implement rate limiting

package/tools/validators/link_checker.py

@@ -20,13 +20,13 @@ def check_link(url):
             'Upgrade-Insecure-Requests': '1',
         }
 
-        response = requests.head(url, headers=headers, timeout=5, allow_redirects=True)
+        response = requests.head(url, headers=headers, timeout=15, allow_redirects=True)
 
         if response.status_code == 200:
             return True, "OK"
         else:
             # Retry with GET if HEAD fails (some servers block HEAD)
-            response = requests.get(url, headers=headers, timeout=5, stream=True)
+            response = requests.get(url, headers=headers, timeout=15, stream=True)
             if response.status_code == 200:
                 return True, "OK"
             return False, f"Status Code: {response.status_code}"