content-foundry 1.0.0__tar.gz

content_foundry-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pranshu Mishra
+
+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.

content_foundry-1.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: content-foundry
+Version: 1.0.0
+Summary: A resumable multi-agent pipeline that researches, writes, judges, narrates, and renders short-form YouTube videos for any niche.
+Author-email: Pranshu Mishra <pranshumshr.04@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/pranshu97/content-foundry
+Project-URL: Repository, https://github.com/pranshu97/content-foundry
+Project-URL: Issues, https://github.com/pranshu97/content-foundry/issues
+Keywords: youtube,video-generation,ai-agents,llm,gemini,content-automation,text-to-speech,ffmpeg,pipeline
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: lxml>=5.2
+Requires-Dist: ddgs>=6.0
+Requires-Dist: SQLAlchemy>=2.0
+Requires-Dist: typer>=0.12
+Requires-Dist: APScheduler>=3.10
+Requires-Dist: tenacity>=8.5
+Requires-Dist: structlog>=24.1
+Requires-Dist: rich>=13.7
+Requires-Dist: python-dateutil>=2.9
+Requires-Dist: python-ulid>=2.7
+Requires-Dist: Pillow>=10.4
+Requires-Dist: ffmpeg-python>=0.2
+Requires-Dist: pydub>=0.25
+Requires-Dist: edge-tts>=6.1
+Requires-Dist: anthropic>=0.39
+Requires-Dist: openai>=1.50
+Provides-Extra: youtube
+Requires-Dist: google-api-python-client>=2.140; extra == "youtube"
+Requires-Dist: google-auth-oauthlib>=1.2; extra == "youtube"
+Requires-Dist: google-auth-httplib2>=0.2; extra == "youtube"
+Provides-Extra: tts
+Requires-Dist: elevenlabs>=1.5; extra == "tts"
+Requires-Dist: piper-tts>=1.2; extra == "tts"
+Provides-Extra: image
+Requires-Dist: stability-sdk>=0.8; extra == "image"
+Provides-Extra: video
+Requires-Dist: moviepy>=1.0.3; extra == "video"
+Provides-Extra: whisper
+Requires-Dist: faster-whisper>=1.0; extra == "whisper"
+Provides-Extra: dashboard
+Requires-Dist: streamlit>=1.37; extra == "dashboard"
+Provides-Extra: avatar
+Requires-Dist: rembg>=2.0; extra == "avatar"
+Provides-Extra: clone
+Requires-Dist: chatterbox-tts>=0.1; extra == "clone"
+Provides-Extra: faceid
+Requires-Dist: diffusers==0.29.0; extra == "faceid"
+Requires-Dist: transformers==4.44.2; extra == "faceid"
+Requires-Dist: numpy<2.0.0; extra == "faceid"
+Requires-Dist: safetensors==0.5.3; extra == "faceid"
+Requires-Dist: accelerate>=0.28; extra == "faceid"
+Requires-Dist: insightface>=0.7; extra == "faceid"
+Requires-Dist: onnxruntime-gpu<1.23,>=1.19; extra == "faceid"
+Requires-Dist: opencv-python-headless>=4.9; extra == "faceid"
+Provides-Extra: all
+Requires-Dist: elevenlabs>=1.5; extra == "all"
+Requires-Dist: piper-tts>=1.2; extra == "all"
+Requires-Dist: stability-sdk>=0.8; extra == "all"
+Requires-Dist: moviepy>=1.0.3; extra == "all"
+Requires-Dist: faster-whisper>=1.0; extra == "all"
+Requires-Dist: streamlit>=1.37; extra == "all"
+Requires-Dist: rembg>=2.0; extra == "all"
+Requires-Dist: google-api-python-client>=2.140; extra == "all"
+Requires-Dist: google-auth-oauthlib>=1.2; extra == "all"
+Requires-Dist: google-auth-httplib2>=0.2; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-mock>=3.14; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: pre-commit>=3.8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# Content Foundry
+
+An autonomous, fully-resumable multi-agent pipeline that turns real labor-market data into a
+published (Private/Unlisted draft) YouTube video — grounded in data, gated by a
+strict quality rubric, and compliant with synthetic-content disclosure by default.
+
+**Pipeline:** Data Fetcher → Script Generator → Judge → Voiceover → Visuals → Render → Publish
+
+> The complete engineering specification (single source of truth) lives in [`spec/`](spec/README.md).
+> A high-level architecture summary is in [`TECH_REPORT.md`](TECH_REPORT.md), and the operator guide
+> in [`Tutorial.md`](Tutorial.md).
+
+## Live channel
+
+Watch the output live: **[youtube.com/@TheCrackedEng](https://www.youtube.com/@TheCrackedEng)**
+
+> **Disclaimer:** This channel is 100% generated, voiced, and published autonomously by this repository.
+
+## Quickstart
+
+```bash
+# 1. Create & activate a Python 3.11+ environment, then install
+pip install -r requirements.txt
+pip install -e .            # exposes the `content-foundry` CLI
+
+# 2. Configure
+cp .env.example .env        # fill in your keys (see Human_Tasks.md)
+
+# 3. Initialise the database
+python scripts/init_db.py
+
+# 4. Smoke test (no upload, stops at the Judge)
+content-foundry run --niche "tech careers" --to-stage judge
+
+# Or produce a vertical YouTube Short instead of a long video (one switch):
+content-foundry run --niche "tech careers" --idea "your topic" --format short
+```
+
+See [`spec/23-deployment-instructions.md`](spec/23-deployment-instructions.md) for full deployment,
+[`spec/17-cli-interface.md`](spec/17-cli-interface.md) for every command, and
+[`Human_Tasks.md`](Human_Tasks.md) for the manual setup checklist (API keys, OAuth, Telegram bot).
+
+## Project layout
+
+```
+src/content_foundry/    # the engine (models, agents, providers, pipeline, ...)
+dashboard/            # Streamlit review dashboard
+scripts/              # init_db, seed_demo
+tests/                # unit / agent / integration / e2e (dry-run)
+spec/                 # the authoritative specification (25 chapters)
+output/runs/<run_id>/ # per-run artifacts + media + package.md
+```
+
+## Cost discipline
+
+Only **Agent 2 (Script Generator)** always calls an LLM. The Data Fetcher, most of the Judge, and
+the Visuals prompt-builder are deterministic Python — free, fast, and hallucination-proof.
+
+Cost levers (cheapest first):
+- **Run the LLM locally** — `PRIMARY_PROVIDER=local` (Ollama / LM Studio / vLLM) makes generation free.
+- **Free voice** — `TTS_PROVIDER=edge` (Microsoft neural, free, no key) or `piper` (fully offline), or `chatterbox` to **clone your own voice** free & locally (MIT-licensed, safe to monetize; GPU recommended). Paid: elevenlabs / openai. Voices auto-alternate male/female by run number.
+- **Free visuals** — `IMAGE_PROVIDER=none` renders polished title cards; add free Pexels + Pixabay keys for real, moment-matched B-roll (a clip per narration beat), now held to a STRICT on-topic bar — a beat with no confidently-relevant clip falls back to a bespoke generated image (or a clean card when no image provider is set), never an off-topic clip.
+- **Free research (default)** — `ENABLED_SOURCES=search` runs free DuckDuckGo web research on your run's topic (no key), so it works on **any** niche out of the box; the labor-market feeds (adzuna/layoffs/bls) are opt-in add-ons.
+- **Free idea discovery** — `IDEA_MINING_ENABLED=true` + a free `YOUTUBE_API_KEY` mines *proven* outlier videos in your niche (views far above the channel's median) so each run builds a topic with demonstrated demand instead of a guess; best-effort, so it never blocks a run.
+- **Free polish** — bundled sound effects (`SFX_ENABLED`), scene crossfades, a warm grade, and a Subscribe nudge are all local/ffmpeg (no paid services).
+- **`--profile cheap`** — deterministic judge + Pillow cards (no image API) + a single revision.
+- **Hard budget cap** — `ENFORCE_BUDGET_CAP=true` aborts a run once estimated month-to-date spend
+  reaches `MONTHLY_BUDGET_USD` (on by default; cost safety, not just an alert).
+- **Resume reuses paid artifacts** — re-running a stage reuses existing voiceover/visuals instead of
+  paying again (use `--force` to regenerate).
+- **`FAIL_FAST_SCORE`** (opt-in) — stop paying for revisions a hopeless script can't recover from.
+
+Use `--profile quality` for publishing.
+
+## Testing
+
+```bash
+pytest                # unit + agent + integration + e2e dry-run, ≥85% coverage gate
+```
+
+All tests run offline — vendors are mocked behind their protocols; no real network or API calls.

content_foundry-1.0.0/README.md

@@ -0,0 +1,81 @@
+# Content Foundry
+
+An autonomous, fully-resumable multi-agent pipeline that turns real labor-market data into a
+published (Private/Unlisted draft) YouTube video — grounded in data, gated by a
+strict quality rubric, and compliant with synthetic-content disclosure by default.
+
+**Pipeline:** Data Fetcher → Script Generator → Judge → Voiceover → Visuals → Render → Publish
+
+> The complete engineering specification (single source of truth) lives in [`spec/`](spec/README.md).
+> A high-level architecture summary is in [`TECH_REPORT.md`](TECH_REPORT.md), and the operator guide
+> in [`Tutorial.md`](Tutorial.md).
+
+## Live channel
+
+Watch the output live: **[youtube.com/@TheCrackedEng](https://www.youtube.com/@TheCrackedEng)**
+
+> **Disclaimer:** This channel is 100% generated, voiced, and published autonomously by this repository.
+
+## Quickstart
+
+```bash
+# 1. Create & activate a Python 3.11+ environment, then install
+pip install -r requirements.txt
+pip install -e .            # exposes the `content-foundry` CLI
+
+# 2. Configure
+cp .env.example .env        # fill in your keys (see Human_Tasks.md)
+
+# 3. Initialise the database
+python scripts/init_db.py
+
+# 4. Smoke test (no upload, stops at the Judge)
+content-foundry run --niche "tech careers" --to-stage judge
+
+# Or produce a vertical YouTube Short instead of a long video (one switch):
+content-foundry run --niche "tech careers" --idea "your topic" --format short
+```
+
+See [`spec/23-deployment-instructions.md`](spec/23-deployment-instructions.md) for full deployment,
+[`spec/17-cli-interface.md`](spec/17-cli-interface.md) for every command, and
+[`Human_Tasks.md`](Human_Tasks.md) for the manual setup checklist (API keys, OAuth, Telegram bot).
+
+## Project layout
+
+```
+src/content_foundry/    # the engine (models, agents, providers, pipeline, ...)
+dashboard/            # Streamlit review dashboard
+scripts/              # init_db, seed_demo
+tests/                # unit / agent / integration / e2e (dry-run)
+spec/                 # the authoritative specification (25 chapters)
+output/runs/<run_id>/ # per-run artifacts + media + package.md
+```
+
+## Cost discipline
+
+Only **Agent 2 (Script Generator)** always calls an LLM. The Data Fetcher, most of the Judge, and
+the Visuals prompt-builder are deterministic Python — free, fast, and hallucination-proof.
+
+Cost levers (cheapest first):
+- **Run the LLM locally** — `PRIMARY_PROVIDER=local` (Ollama / LM Studio / vLLM) makes generation free.
+- **Free voice** — `TTS_PROVIDER=edge` (Microsoft neural, free, no key) or `piper` (fully offline), or `chatterbox` to **clone your own voice** free & locally (MIT-licensed, safe to monetize; GPU recommended). Paid: elevenlabs / openai. Voices auto-alternate male/female by run number.
+- **Free visuals** — `IMAGE_PROVIDER=none` renders polished title cards; add free Pexels + Pixabay keys for real, moment-matched B-roll (a clip per narration beat), now held to a STRICT on-topic bar — a beat with no confidently-relevant clip falls back to a bespoke generated image (or a clean card when no image provider is set), never an off-topic clip.
+- **Free research (default)** — `ENABLED_SOURCES=search` runs free DuckDuckGo web research on your run's topic (no key), so it works on **any** niche out of the box; the labor-market feeds (adzuna/layoffs/bls) are opt-in add-ons.
+- **Free idea discovery** — `IDEA_MINING_ENABLED=true` + a free `YOUTUBE_API_KEY` mines *proven* outlier videos in your niche (views far above the channel's median) so each run builds a topic with demonstrated demand instead of a guess; best-effort, so it never blocks a run.
+- **Free polish** — bundled sound effects (`SFX_ENABLED`), scene crossfades, a warm grade, and a Subscribe nudge are all local/ffmpeg (no paid services).
+- **`--profile cheap`** — deterministic judge + Pillow cards (no image API) + a single revision.
+- **Hard budget cap** — `ENFORCE_BUDGET_CAP=true` aborts a run once estimated month-to-date spend
+  reaches `MONTHLY_BUDGET_USD` (on by default; cost safety, not just an alert).
+- **Resume reuses paid artifacts** — re-running a stage reuses existing voiceover/visuals instead of
+  paying again (use `--force` to regenerate).
+- **`FAIL_FAST_SCORE`** (opt-in) — stop paying for revisions a hopeless script can't recover from.
+
+Use `--profile quality` for publishing.
+
+## Testing
+
+```bash
+pytest                # unit + agent + integration + e2e dry-run, ≥85% coverage gate
+```
+
+All tests run offline — vendors are mocked behind their protocols; no real network or API calls.

content_foundry-1.0.0/pyproject.toml

@@ -0,0 +1,158 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "content-foundry"
+dynamic = ["version"]
+description = "A resumable multi-agent pipeline that researches, writes, judges, narrates, and renders short-form YouTube videos for any niche."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Pranshu Mishra", email = "pranshumshr.04@gmail.com" }]
+keywords = [
+    "youtube", "video-generation", "ai-agents", "llm", "gemini",
+    "content-automation", "text-to-speech", "ffmpeg", "pipeline",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+# Lean core — everything the DEFAULT pipeline needs. Optional integrations live in the extras below
+# (install on demand, e.g. `pip install content-foundry[all]`); every vendor SDK is imported lazily.
+dependencies = [
+    "pydantic>=2.7",
+    "pydantic-settings>=2.3",
+    "httpx>=0.27",
+    "beautifulsoup4>=4.12",
+    "lxml>=5.2",
+    "ddgs>=6.0",
+    "SQLAlchemy>=2.0",
+    "typer>=0.12",
+    "APScheduler>=3.10",
+    "tenacity>=8.5",
+    "structlog>=24.1",
+    "rich>=13.7",
+    "python-dateutil>=2.9",
+    "python-ulid>=2.7",
+    "Pillow>=10.4",
+    "ffmpeg-python>=0.2",
+    "pydub>=0.25",
+    "edge-tts>=6.1",
+    "anthropic>=0.39",
+    "openai>=1.50",
+]
+
+[project.optional-dependencies]
+youtube = ["google-api-python-client>=2.140", "google-auth-oauthlib>=1.2", "google-auth-httplib2>=0.2"]
+tts = ["elevenlabs>=1.5", "piper-tts>=1.2"]
+image = ["stability-sdk>=0.8"]
+video = ["moviepy>=1.0.3"]
+whisper = ["faster-whisper>=1.0"]
+dashboard = ["streamlit>=1.37"]
+avatar = ["rembg>=2.0"]
+clone = ["chatterbox-tts>=0.1"]
+faceid = [
+    # Pinned to coexist with chatterbox-tts, which needs diffusers==0.29.0: a newer transformers or
+    # numpy>=2 breaks diffusers 0.29's Stable Diffusion import. See providers/faceid.py.
+    "diffusers==0.29.0", "transformers==4.44.2", "numpy<2.0.0", "safetensors==0.5.3",
+    # onnxruntime-gpu pinned to the CUDA 12 line (matches torch cu124); 1.23+ needs CUDA 13 libs this env lacks.
+    "accelerate>=0.28", "insightface>=0.7", "onnxruntime-gpu>=1.19,<1.23", "opencv-python-headless>=4.9",
+]
+all = [
+    "elevenlabs>=1.5", "piper-tts>=1.2", "stability-sdk>=0.8", "moviepy>=1.0.3",
+    "faster-whisper>=1.0", "streamlit>=1.37", "rembg>=2.0",
+    "google-api-python-client>=2.140", "google-auth-oauthlib>=1.2", "google-auth-httplib2>=0.2",
+]
+dev = [
+    "pytest>=8.3",
+    "pytest-mock>=3.14",
+    "pytest-cov>=5.0",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pre-commit>=3.8",
+    "build>=1.2",
+    "twine>=5.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/pranshu97/content-foundry"
+Repository = "https://github.com/pranshu97/content-foundry"
+Issues = "https://github.com/pranshu97/content-foundry/issues"
+
+[project.scripts]
+content-foundry = "content_foundry.cli:app"
+
+[tool.setuptools.dynamic]
+version = { attr = "content_foundry.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+content_foundry = ["prompts/*.txt", "data/sounds/*", "py.typed"]
+
+# ---------------------------------------------------------------------------
+# Tooling
+# ---------------------------------------------------------------------------
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C4", "SIM"]
+ignore = ["E501", "UP042"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_unused_ignores = true
+ignore_missing_imports = true
+plugins = ["pydantic.mypy"]
+packages = ["content_foundry"]
+mypy_path = "src"
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-q --cov=content_foundry --cov-report=term-missing"
+testpaths = ["tests"]
+pythonpath = ["src"]
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.coverage.run]
+source = ["content_foundry"]
+branch = true
+omit = [
+    # Thin vendor adapter glue (network/SDK side effects) — excluded per Ch. 22.5.
+    "*/providers/anthropic_provider.py",
+    "*/providers/openai_provider.py",
+    "*/providers/tts.py",
+    "*/providers/image.py",
+    "*/providers/broll.py",
+    "*/providers/render_backend.py",
+    "*/providers/youtube.py",
+    "*/notifications/telegram.py",
+    "*/scheduler.py",
+    "*/cli.py",
+]
+
+[tool.coverage.report]
+fail_under = 85
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "\\.\\.\\.",
+]

content_foundry-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

content_foundry-1.0.0/src/content_foundry/__init__.py

@@ -0,0 +1,4 @@
+"""Content Foundry — a resumable multi-agent pipeline that researches, writes, judges, narrates, and
+renders short-form YouTube videos for any niche."""
+
+__version__ = "1.0.0"

content_foundry-1.0.0/src/content_foundry/agents/__init__.py

@@ -0,0 +1,36 @@
+"""The seven agents (each owns exactly one transformation; no agent imports another)."""
+
+from __future__ import annotations
+
+from .brainstorm import Brainstormer
+from .broll_director import BrollDirector
+from .data_fetcher import DataFetcher
+from .idea_miner import IdeaMiner
+from .instruction_planner import InstructionPlanner
+from .judge import Judge
+from .publisher import Publisher
+from .renderer import Renderer
+from .research import Researcher
+from .scene_image_director import SceneImageDirector
+from .script_generator import ScriptGenerator
+from .thumbnail_director import ThumbnailDirector
+from .visuals import Visuals, build_image_prompt
+from .voiceover import Voiceover
+
+__all__ = [
+    "DataFetcher",
+    "Brainstormer",
+    "IdeaMiner",
+    "InstructionPlanner",
+    "Researcher",
+    "BrollDirector",
+    "ScriptGenerator",
+    "ThumbnailDirector",
+    "SceneImageDirector",
+    "Judge",
+    "Voiceover",
+    "Visuals",
+    "build_image_prompt",
+    "Renderer",
+    "Publisher",
+]

content_foundry-1.0.0/src/content_foundry/agents/brainstorm.py

@@ -0,0 +1,136 @@
+"""Agent 0 — Brainstormer. Proposes several fresh, specific, helpful video ideas from the brief so
+runs don't collapse onto the same topic. LLM-driven with a deterministic content-angle fallback."""
+
+from __future__ import annotations
+
+import json
+
+from ..errors import LLMError
+from ..logging import get_logger
+from ..models import DataBrief
+from ..prompts import load_prompt, render_prompt
+from ..providers.base import LLMProvider, extract_json
+from ..providers.tiering import TaskTier, select_model
+
+
+class Brainstormer:
+    def __init__(self, settings, llm_provider: LLMProvider):
+        self._settings = settings
+        self._llm = llm_provider
+        self._log = get_logger(component="brainstorm")
+
+    def propose(
+        self, brief: DataBrief, *, recent_ideas: list[str] | None = None, count: int = 5,
+        focus: str = "",
+    ) -> list[str]:
+        """Propose ``count`` distinct, specific video ideas. ``focus`` (e.g. the user's --idea) steers
+        every idea. The fetched data is used only as INSPIRATION / supporting stats, never the whole
+        basis. Falls back to deterministic content angles when the LLM is unavailable."""
+        recent = [r for r in (recent_ideas or []) if r]
+        fallback = self._fallback(brief, recent, focus, count)
+        try:
+            system = render_prompt(
+                load_prompt("brainstorm.system"),
+                niche=brief.niche,
+                count=str(count),
+                focus_line=(
+                    f'The viewer specifically asked for: "{focus}". EVERY idea MUST be a concrete, '
+                    "specific angle that delivers on this." if focus else ""
+                ),
+                facts_json=json.dumps([kf.statement for kf in brief.key_facts], ensure_ascii=False),
+                avoid_json=json.dumps(recent[:8], ensure_ascii=False),
+            )
+            resp = self._llm.complete(
+                "Return ONLY the JSON array now.",
+                system=system,
+                temperature=max(self._settings.llm_temperature, 0.8),
+                # A generous cap: reasoning models (e.g. Gemini flash) spend part of the budget
+                # THINKING, and a tight cap (700) left no room for the JSON -> empty/unusable reply.
+                max_tokens=self._settings.llm_max_tokens,
+                model=select_model(
+                    self._settings, TaskTier.HEAVY, fallback=self._settings.generator_model
+                ),
+            )
+            ideas = _parse_ideas(resp.text)
+            if ideas:
+                self._log.info("brainstormed_ideas", count=len(ideas))
+                return ideas[:count]
+        except (json.JSONDecodeError, LLMError, KeyError, ValueError, AttributeError, TypeError) as exc:
+            self._log.warning("brainstorm_fallback", error=str(exc))
+        return fallback
+
+    def run(self, brief: DataBrief, *, recent_ideas: list[str] | None = None) -> str:
+        """Back-compat single-idea helper."""
+        ideas = self.propose(brief, recent_ideas=recent_ideas, count=1)
+        return ideas[0] if ideas else ""
+
+    def _fallback(self, brief: DataBrief, recent: list[str], focus: str, count: int) -> list[str]:
+        """Deterministic: clean focus-based angles (or the brief's content angles when there is no
+        focus), skipping recently-made ones."""
+        pool: list[str] = []
+        if focus:
+            f = focus.strip().rstrip(".")
+            low = (f[:1].lower() + f[1:]) if f else f
+            pool += [
+                f"{f}: a practical step-by-step guide",
+                f"{f}: the mistakes that keep you stuck",
+                f"{f}: what actually works, backed by the data",
+                f"The truth about {low}",
+                f"{f}: what the {brief.niche} numbers really say",
+                f"{f} in 30 days: a realistic plan",
+                f"{f}: the first moves to make right now",
+            ]
+        pool += [a.hook for a in brief.content_angles]
+        if not pool:
+            pool = [f"A specific, data-backed {brief.niche} explainer that solves one real problem"]
+        recent_l = " ".join(recent).lower()
+        fresh = [h for h in _dedup(pool) if h[:25].lower() not in recent_l]
+        return (fresh or _dedup(pool))[:count]
+
+
+def _dedup(items) -> list[str]:
+    """Order-preserving de-dup + trim; coerces non-strings to str."""
+    seen: set[str] = set()
+    out: list[str] = []
+    for item in items:
+        text = (item if isinstance(item, str) else str(item)).strip()
+        if text and text.lower() not in seen:
+            seen.add(text.lower())
+            out.append(text)
+    return out
+
+
+def _slice_array(text: str) -> str:
+    """Slice the first ``[`` to the last ``]`` (recovers a JSON array wrapped in prose)."""
+    start, end = text.find("["), text.rfind("]")
+    return text[start : end + 1] if start != -1 and end > start else ""
+
+
+def _parse_ideas(text: str) -> list[str]:
+    """Robustly pull the list of idea strings from an LLM reply. Handles a bare JSON array, an object
+    ``{"ideas": [...]}``, an array of objects, or an array wrapped in prose. NOTE: a plain
+    ``extract_json`` MANGLES a top-level array (it slices first ``{`` to last ``}``), so we try a
+    direct parse and an array-slice too."""
+    raw = (text or "").strip()
+    data = None
+    for candidate in (raw, extract_json(raw), _slice_array(raw)):
+        if not candidate:
+            continue
+        try:
+            data = json.loads(candidate)
+            break
+        except (json.JSONDecodeError, ValueError):
+            continue
+    if isinstance(data, dict):
+        data = data.get("ideas") or data.get("items") or data.get("titles") or []
+    if not isinstance(data, list):
+        return []
+    out: list[str] = []
+    for item in data:
+        if isinstance(item, str):
+            out.append(item)
+        elif isinstance(item, dict):  # array of objects -> use the most title-like field
+            val = item.get("title") or item.get("idea") or item.get("angle") or item.get("text")
+            if isinstance(val, str):
+                out.append(val)
+    return _dedup(out)