Optimization Plan — YouTube Shorts Generator

Generated: 2026-04-11
Last updated: 2026-04-11 (P0 + P1 implemented)

Priority 0 — Critical (broken functionality)

P0 Implementation Details

0.1 — G4F temperature/max_tokens fix
- _call_with_timeout() signature extended: temperature: float = 0.7, max_tokens: int = 2000
- Parameters forwarded via kwargs dict to client.chat.completions.create(**kwargs)
- All 3 call sites (PollinationsAI, DeepInfra, generic) updated
- Specifics: Parameters are passed conditionally (if temperature is not None) to avoid breaking providers that don't support them

0.2 — Dynamic language/region in script prompt
- Added _LANG_MAP dict (en-US, uk-UA, es-ES, de-DE, fr-FR, pt-BR, ja-JP, ko-KR, zh-CN, hi-IN, ar-SA) + _lang_display_name() helper
- System prompt now uses cfg.channel.language → display name and cfg.channel.region dynamically
- Segment count is now dynamic: seg_min = max(2, word_target // 50), seg_max = min(7, word_target // 20)
- Added comprehensive few-shot JSON example (4-segment AI medical script) — also covers P1.2
- Hook instruction: "shocking fact, bold claim, or curiosity-gap question"; CTA: "specific action — avoid generic 'like and subscribe'"

0.3 — Comments LLM provider fix
- _build_llm() rewritten: loads config via reload_config(), uses build_llm_provider(cfg.llm)
- Falls back to None (with error log) if config loading fails, preserving graceful degradation

0.4 — Runtime LLM fallback
- New _FallbackLLMProvider(LLMProvider) wrapper class in factory.py
- Wraps primary + fallback providers; complete() and complete_json() catch primary exceptions and transparently retry on fallback
- build_llm_provider() returns wrapped provider when both primary and fallback are available
- Specifics: Logs llm_runtime_fallback warning with primary name, error, and fallback name for observability

Priority 1 — Important (significant quality/performance impact)

P1 Implementation Details

1.1 — Parallel step execution (Visuals + Audio)
- orchestrator.py: added StepEntry = Union[PipelineStep, list[PipelineStep], tuple[PipelineStep, ...]] type
- New _run_parallel() method uses ThreadPoolExecutor(max_workers=len(active))
- Each parallel step gets a shallow dict(ctx) copy; results merged after all complete
- tasks.py: steps list now uses (VisualsStep(), AudioStep()) tuple for parallel group
- Specifics: Only steps 3+4 are parallelized (not 5+6) because SEO actually benefits from having the final video path, and Edit must complete before Upload. This is the safe, high-value parallel pair.

1.2 — Few-shot example in script prompt
- Added a complete 4-segment example JSON in _build_user() showing hook → segments → CTA structure
- Example uses a realistic AI-medical topic with proper word counts per segment
- Specifics: Combined with P0.2 implementation in the same step_02_script.py rewrite

1.3 — Cumulative memory (reflection carries forward)
- step_09_reflect.py now calls get_channel_memory(topic) before reflection
- Previous memory passed to _reflect() as prev_memory parameter
- LLM prompt includes PREVIOUS CHANNEL INSIGHTS block with instruction: "UPDATE these insights — keep valid, revise contradicted, add new patterns"
- Specifics: Memory is still upserted (one record per topic), but the LLM sees prior insights and evolves them rather than starting fresh each time

1.4 — Comment data in reflection
- _build_video_data() now queries CommentReply records (up to 5 per video, latest first)
- entry["viewer_comments"] = list of comment texts (truncated to 150 chars)
- Added audience_requests: list[str] field to ChannelMemorySchema
- Reflection prompt updated: "If viewer_comments are included, extract recurring themes, questions, or requests"
- memory_store.py updated: get_memory_context() now outputs audience requests

1.5 — Memory-informed trend selection
- Both _run_static and _run_dynamic in step_01_trends.py now query channel memory
- Injects best_topic_keywords as "prefer similar angles" and avoid_topic_keywords as "avoid these"
- Also fixed hardcoded "60-second short" → uses cfg.channel.target_duration_sec
- All LLM select methods accept optional llm parameter with fallback

1.6 — Memory-informed SEO
- step_06_seo.py imports get_memory_context and injects into system prompt
- Memory block: "Channel performance insights (use to optimize tags/title): ..."
- Limited to 150 tokens to avoid overwhelming the SEO prompt
- Fixed hardcoded "American" → uses {region} from config

1.7 — Random seed for Pollinations
- Changed seed=42 → seed = random.randint(1, 999999)
- Cache key updated to include seed: f"pollinations_{keyword}_{w}x{h}_{seed}"
- Specifics: Old cache lookup by keyword-only key was removed because it would always return stale results. Each generation now gets a unique image. Trade-off: no deduplication for same keyword within a run, but this is acceptable since segments should have different keywords anyway.

1.8 — MoviePy resource cleanup
- run() method wrapped in try/finally block
- All clips tracked in _open_clips: list throughout the method
- Finally block closes all clips in reverse order (composite first, then sources)
- Specifics: MoviePy clips don't support Python context managers (with), so explicit tracking + finally is the correct pattern. Reverse order ensures composite clips are closed before their source clips.

1.9 — Shared extract_json() utility
- Created app/utils/json_utils.py with single extract_json(text) -> str function
- Handles: markdown code blocks (\``json ... ```), raw JSON objects, passthrough - Removed duplicate copies fromstep_02_script.py,step_06_seo.py,step_09_reflect.py- All three files now importfrom app.utils.json_utils import extract_json as _extract_json`

1.10 — Single LLM provider instance per pipeline run
- orchestrator.py creates LLM once: ctx["llm"] = build_llm_provider(self.cfg.llm)
- All step files use pattern: llm = ctx.get("llm") or build_llm_provider(cfg.llm)
- Specifics: The or build_llm_provider() fallback preserves backward compatibility — steps can still be used standalone (e.g., test_pipeline.py --step seo) without the orchestrator. The _FallbackLLMProvider wrapper (P0.4) means the shared instance already has fallback baked in.

Priority 2 — Moderate (reliability/correctness)

Priority 3 — Low (nice-to-have improvements)

Priority 4 — Cosmetic / future enhancements

Implementation Summary

Implemented: 14 items (P0: 4/4, P1: 10/10)
Remaining: 22 items (P2: 12, P3: 12, P4: 10)

Files Modified

Files Created

Key Design Decisions

1. Parallel steps limited to Visuals+Audio only — SEO could theoretically run parallel with Edit, but it benefits from having the final output path, and the time savings would be marginal compared to the Visuals+Audio pair (which involves network I/O).

2. ctx.get("llm") or build_llm_provider() pattern — Preserves backward compatibility for standalone step usage (test_pipeline.py --step X) while eliminating redundant instantiation in normal pipeline runs.

3. Pollinations cache key includes seed — Breaking change from the old pollinations_{keyword}_{size} key. Old cached images won't be hit, but this is the correct behavior since the whole point is generating unique images.

4. Cumulative memory via LLM, not merge — Rather than programmatically merging old+new memory dicts (brittle, loses nuance), the previous memory is passed to the LLM with explicit instructions to update/revise/keep. This lets the LLM make qualitative judgments about what's still valid.

5. MoviePy cleanup via tracked list + finally — MoviePy clips don't implement __enter__/__exit__, so context managers aren't an option. Reverse-order closing (composite → source) prevents errors from closing source clips that are still referenced.