feat: Hook Engine with 7 viral hook styles

README.md

@@ -15,6 +15,49 @@ AI-powered tool for generating YouTube Shorts / TikTok videos with script genera
 - **Two pipelines**: normal (YouTube bg + optional image overlays) and images-only (AI/web images + overlay animation, no YouTube bg)
 - **Typer CLI** — nested subcommands, auto-generated `--help`, shell completion
 - **Batch Processing** — semicolon-separated subjects for multi-video runs
+- **Hook Engine** — 7 viral hook styles (curiosity, counter-narrative, controversy, challenge, reveal, story) with pattern interrupt and curiosity gap mechanics
+
+## Hook Styles
+
+AutoShorts now supports multiple hook styles to optimize script engagement:
+
+- `default` — Original curiosity-driven hook (backward compatible)
+- `curiosity` — Creates information asymmetry (viewer knows something is important but not what)
+- `counter` — Challenges common knowledge and assumptions
+- `controversy` — Takes a strong stance that demands engagement
+- `challenge` — Direct challenge to viewer's knowledge
+- `reveal` — Promises a shocking fact upfront
+- `story` — Opens a narrative arc with character and conflict
+
+### Usage
+
+```bash
+autoshorts new explainer "Corinthians 2012 Libertadores" --hook-style controversy
+autoshorts new explainer "Pelé 1000 goals" --hook-style curiosity
+autoshorts new explainer "Neymar vs Ronaldo" --hook-style counter
+```
+
+### Examples
+
+```bash
+# Curiosity gap (works well for history/facts)
+autoshorts new explainer "Pelé 1000 goals" --hook-style curiosity
+
+# Counter-narrative (works well for debates)
+autoshorts new explainer "Neymar vs Ronaldo" --hook-style counter
+
+# Controversy (works well for opinions)
+autoshorts new explainer "VAR no futebol brasileiro" --hook-style controversy
+
+# Challenge (works well for trivia)
+autoshorts new explainer "Primeiro estrangeiro no Brasil" --hook-style challenge
+
+# Reveal (works well for secrets)
+autoshorts new explainer "Flamengo 1981 bastidores" --hook-style reveal
+
+# Story (works well for narratives)
+autoshorts new explainer "Palmeiras 2006 quase rebaixado" --hook-style story
+```
 
 ## Installation
 
@@ -111,9 +154,10 @@ AutoShorts/
 │       │   └── explainer.py        # ExplainerGenerator (both pipelines)
 │       └── modules/                # Core modules
 │           ├── config.py
+│           ├── hook_engine.py      # Hook Engine with 7 viral styles, pattern interrupt, curiosity gap
 │           ├── image_searcher.py   # Web/AI image search + NSFW filter
 │           ├── logging_system.py
-│           ├── script_generator.py # Script gen, fact verification, title validation
+│           ├── script_generator.py # Script gen, fact verification, title validation, hook integration
 │           ├── subtitle_system.py
 │           ├── tts_system.py
 │           ├── utils.py
@@ -125,6 +169,7 @@ AutoShorts/
 │   ├── test_config.py
 │   ├── test_edge_cases.py
 │   ├── test_fluximages.py          # Explainer generator tests
+│   ├── test_hook_engine.py         # Hook Engine (15+ tests)
 │   ├── test_init.py
 │   ├── test_integration.py
 │   ├── test_script_generator.py

src/autoshorts/cli/commands/explainer.py

@@ -8,6 +8,7 @@
 
 from ...generators import VIDEO_TYPES
 from ...modules import VideoMetadata, log, shutdown_computer
+from ...modules.hook_engine import HookStyle
 from ..new import new_app
 
 
@@ -42,6 +43,13 @@ def explainer_command(
         "-c",
         help="Custom instructions for the AI on how to craft the video alongside the theme",
     ),
+    hook_style: HookStyle = typer.Option(
+        HookStyle.DEFAULT,
+        "--hook-style",
+        "-hs",
+        case_sensitive=False,
+        help="Hook style for script generation (default, curiosity, counter, controversy, challenge, reveal, story)",
+    ),
 ):
     if no_images and images_only:
         raise typer.BadParameter("--no-images and --images-only are mutually exclusive")
@@ -63,8 +71,9 @@ def explainer_command(
     output_path = Path(output)
     success_count = 0
     total_count = len(subjects)
+
     def _sanitize(s):
-        return re.sub(r'[\\/*?:"<>|]', "", s).replace(" ", "_").lower()[:20]
+        return re.sub(r'[\\/*?:\"<>|]', "", s).replace(" ", "_").lower()[:20]
 
     for i, subj in enumerate(subjects, 1):
         log(f"Processing {i}/{total_count}: {subj or 'youtube-url'}")
@@ -90,6 +99,7 @@ def _sanitize(s):
                     "no_web_search": no_web_search,
                     "batch": batch,
                     "custom_instructions": custom_instructions,
+                    "hook_style": hook_style.value if isinstance(hook_style, HookStyle) else str(hook_style),
                 }, ensure_ascii=False),
             )
 
@@ -103,6 +113,7 @@ def _sanitize(s):
                 image_source=images,
                 custom_instructions=custom_instructions,
                 metadata=metadata,
+                hook_style=hook_style,
             )
             success = asyncio.run(gen.generate())
             if success:

src/autoshorts/cli/commands/help_cmd.py

@@ -13,15 +13,18 @@ def help_command(
 
         if args:
             for name in args:
-                if isinstance(target, click.Group) and name in target.commands:
-                    target = target.commands[name]
-                    info_parts.append(name)
-                else:
-                    typer.secho(
-                        f"Error: No such command: autoshorts {' '.join(args)}",
-                        fg="red",
-                    )
-                    raise typer.Exit(1)
+                if hasattr(target, "commands"):
+                    cmds = getattr(target, "commands", {}) or {}
+                    if name in cmds:
+                        target = cmds[name]
+                        info_parts.append(name)
+                        continue
+
+                typer.secho(
+                    f"Error: No such command: autoshorts {' '.join(args)}",
+                    fg="red",
+                )
+                raise typer.Exit(1)
 
         help_ctx = click.Context(target, info_name=" ".join(info_parts))
         typer.echo(target.get_help(help_ctx))

src/autoshorts/generators/explainer.py

@@ -50,6 +50,7 @@
     log,
     setup_directories,
 )
+from ..modules.hook_engine import HookStyle
 
 
 class ExplainerGenerator:
@@ -65,6 +66,7 @@ def __init__(
         image_source: str = "web",
         custom_instructions: str | None = None,
         metadata: VideoMetadata | None = None,
+        hook_style: HookStyle = HookStyle.DEFAULT,
     ):
         self.subject = subject
         self.output = output
@@ -75,10 +77,12 @@ def __init__(
         self.image_source = image_source
         self.custom_instructions = custom_instructions
         self.metadata = metadata or VideoMetadata()
+        self.hook_style = hook_style
 
         self.script_generator = ScriptGenerator(
             web_search=web_search,
             custom_instructions=custom_instructions,
+            hook_style=hook_style,
         )
         self.tts_system = TTSSystem()
         self.temp_dir = create_temp_dir()

src/autoshorts/modules/__init__.py

@@ -71,6 +71,7 @@
     YOUTUBE_FORMAT,
     YOUTUBE_MAX_HEIGHT,
 )
+from .hook_engine import HookEngine, HookStyle
 from .image_searcher import ImageSearcher
 from .logging_system import Colors, log
 from .metadata import VideoMetadata
@@ -164,6 +165,8 @@
     "log",
     "Colors",
     "ScriptGenerator",
+    "HookEngine",
+    "HookStyle",
     "TTSSystem",
     "VideoBackgroundManager",
     "VideoCompositor",