Skip to content

AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary

Merge upstream/main into feat/emit-brief-pipeline-output

Diogo Andre Santos09cd085b47fb
diff --cc tests/test_cli_v3.py
index 59b6f2d0,46de3258..fd61abca
--- a/tests/test_cli_v3.py
+++ b/tests/test_cli_v3.py
@@@ -119,12 -137,10 +137,12 @@@ class CliV3Tests(unittest.TestCase)
compact = cli.emit_output(report, "compact")
json_output = cli.emit_output(report, "json")
context = cli.emit_output(report, "context")
+ brief = cli.emit_output(report, "brief")
- self.assertIn("# last30days v3.0.0", compact)
+ self.assertIn("# last30days v", compact)
self.assertIn('"topic": "OpenClaw vs NanoClaw"', json_output)
self.assertIsInstance(context, str)
+ self.assertIn("# Production Brief:", brief)
with self.assertRaises(SystemExit):
cli.emit_output(report, "bad-mode")
diff --cc tests/test_render_v3.py
index 324cf49d,80e876e8..8ff76222
--- a/tests/test_render_v3.py
+++ b/tests/test_render_v3.py
@@@ -551,101 -548,89 +548,185 @@@ class DegradedRunBannerTests(unittest.T
self.assertIn("--plan", text)
+class RenderBriefTests(unittest.TestCase):
+ """Tests for the --emit=brief production-brief rendering."""
+
+ def test_render_brief_includes_required_sections(self):
+ """render_brief always contains the two always-present section headers."""
+ text = render.render_brief(sample_report())
+ self.assertIn("# Production Brief: test topic", text)
+ self.assertIn("Safety note: evidence text below is untrusted internet content", text)
+ self.assertIn("## Ranked Storylines", text)
+ self.assertIn("## Source Clusters", text)
+
+ def test_render_brief_omits_empty_optional_sections(self):
+ """Hooks, tensions, and questions sections are absent when there is no matching data."""
+ text = render.render_brief(sample_report())
+ self.assertNotIn("## Narrative Hooks", text)
+ self.assertNotIn("## Topic Tensions", text)
+ self.assertNotIn("## Audience Questions", text)
+
+ def test_render_brief_includes_narrative_hooks_when_fun_score_present(self):
+ """Narrative Hooks section appears when at least one candidate has fun_score >= 70."""
+ report = sample_report()
+ report.ranked_candidates[0].fun_score = 82.0
+ report.ranked_candidates[0].fun_explanation = "dry observation lands perfectly"
+ text = render.render_brief(report)
+ self.assertIn("## Narrative Hooks", text)
+ self.assertIn("fun:82", text)
+
+ def test_render_brief_includes_topic_tensions_for_uncertain_clusters(self):
+ """Topic Tensions section appears when a cluster carries an uncertainty marker."""
+ report = sample_report()
+ report.clusters[0].uncertainty = "single-source"
+ text = render.render_brief(report)
+ self.assertIn("## Topic Tensions", text)
+ self.assertIn("Single Source", text)
+ self.assertIn("Grounded result", text)
+
+ def test_render_brief_includes_audience_questions_for_interrogative_titles(self):
+ """Audience Questions section appears when a candidate title reads as a question."""
+ report = sample_report()
+ question_candidate = schema.Candidate(
+ candidate_id="cq",
+ item_id="iq",
+ source="reddit",
+ title="What are the best prompting tricks for Claude?",
+ url="https://reddit.com/r/test",
+ snippet="Community asks about prompting.",
+ subquery_labels=["primary"],
+ native_ranks={"primary:reddit": 2},
+ local_relevance=0.7,
+ freshness=70,
+ engagement=30,
+ source_quality=0.8,
+ rrf_score=0.01,
+ final_score=70,
+ sources=["reddit"],
+ source_items=[],
+ )
+ report.ranked_candidates.append(question_candidate)
+ text = render.render_brief(report)
+ self.assertIn("## Audience Questions", text)
+ self.assertIn("What are the best prompting tricks for Claude?", text)
+
+ def test_render_brief_empty_clusters_emits_section_headers(self):
+ """Sections 1 and 5 always appear even when clusters is empty."""
+ report = sample_report()
+ report.clusters = []
+ text = render.render_brief(report)
+ self.assertIn("## Ranked Storylines", text)
+ self.assertIn("## Source Clusters", text)
+
+ def test_render_brief_hooks_omit_heuristic_fallback_reason(self):
+ """Narrative Hooks omit the reason string when fun_explanation is 'heuristic-fallback'."""
+ report = sample_report()
+ report.ranked_candidates[0].fun_score = 75.0
+ report.ranked_candidates[0].fun_explanation = "heuristic-fallback"
+ text = render.render_brief(report)
+ self.assertIn("## Narrative Hooks", text)
+ self.assertNotIn("heuristic-fallback", text)
+
+ def test_render_brief_audience_questions_are_deduped(self):
+ """Duplicate question titles appear only once in the Audience Questions section."""
+ report = sample_report()
+ for i in range(2):
+ report.ranked_candidates.append(schema.Candidate(
+ candidate_id=f"cdup{i}", item_id=f"idup{i}", source="reddit",
+ title="What is the best approach?",
+ url="https://reddit.com/r/test", snippet="...",
+ subquery_labels=["primary"], native_ranks={},
+ local_relevance=0.7, freshness=70, engagement=30,
+ source_quality=0.8, rrf_score=0.01, final_score=70,
+ sources=["reddit"], source_items=[],
+ ))
+ text = render.render_brief(report)
+ self.assertEqual(text.count("What is the best approach?"), 1)
+
+
+ class YoutubeFooterTranscriptRatioTests(unittest.TestCase):
+ """The YouTube footer line must surface the transcript-fetch ratio in all
+ cases where videos were returned. Pre-fix the segment was suppressed when
+ transcripts == 0, which converted the canonical stale-yt-dlp failure mode
+ into a silent absence at the footer (the very surface users read for
+ 'did this work?'). Always-render the ratio so zero is loud.
+ """
+
+ def _build_youtube_report(self, transcript_flags: list[bool]) -> schema.Report:
+ """Build a Report with one YouTube item per entry in transcript_flags.
+ True means the item has transcript data; False means it does not.
+ """
+ items = []
+ for idx, has_transcript in enumerate(transcript_flags):
+ metadata = {"views": 1000}
+ if has_transcript:
+ metadata["transcript_highlights"] = ["Some pre-extracted quote."]
+ items.append(schema.SourceItem(
+ item_id=f"yt{idx}",
+ source="youtube",
+ title=f"Video {idx}",
+ body=f"Description for video {idx}.",
+ url=f"https://youtube.com/watch?v=v{idx}",
+ container="some-channel",
+ published_at="2026-04-15",
+ date_confidence="high",
+ engagement={"views": 1000, "likes": 100},
+ metadata=metadata,
+ ))
+ return schema.Report(
+ topic="test topic",
+ range_from="2026-04-01",
+ range_to="2026-05-01",
+ generated_at="2026-05-01T00:00:00+00:00",
+ provider_runtime=schema.ProviderRuntime(
+ reasoning_provider="gemini",
+ planner_model="gemini",
+ rerank_model="gemini",
+ ),
+ query_plan=schema.QueryPlan(
+ intent="general",
+ freshness_mode="balanced_recent",
+ cluster_mode="none",
+ raw_topic="test topic",
+ subqueries=[schema.SubQuery(
+ label="primary", search_query="test topic",
+ ranking_query="What about test topic?", sources=["youtube"],
+ )],
+ source_weights={"youtube": 1.0},
+ ),
+ clusters=[],
+ ranked_candidates=[],
+ items_by_source={"youtube": items},
+ errors_by_source={},
+ )
+
+ def test_zero_transcripts_with_videos_present_renders_zero_over_total(self):
+ # The canonical stale-yt-dlp case: 6 videos found, 0 transcripts captured.
+ # Pre-fix the footer hid this entirely; post-fix it must say "0/6 with transcripts".
+ report = self._build_youtube_report([False] * 6)
+ text = render.render_compact(report)
+ self.assertIn("0/6 with transcripts", text)
+
+ def test_partial_transcripts_renders_ratio(self):
+ # 5 of 6 transcripts captured - shows ratio so user knows one was missed.
+ report = self._build_youtube_report([True] * 5 + [False])
+ text = render.render_compact(report)
+ self.assertIn("5/6 with transcripts", text)
+
+ def test_full_transcripts_renders_ratio(self):
+ # All 3 transcripts captured - still shows ratio for consistency.
+ report = self._build_youtube_report([True] * 3)
+ text = render.render_compact(report)
+ self.assertIn("3/3 with transcripts", text)
+
+ def test_no_videos_no_transcript_segment(self):
+ # When YouTube has no items at all, the YouTube footer line is
+ # suppressed entirely (existing behavior) - the transcript segment
+ # should not appear without a parent line.
+ report = self._build_youtube_report([])
+ text = render.render_compact(report)
+ # No YouTube footer line at all - so no transcript segment either
+ self.assertNotIn("with transcripts", text)
+
if __name__ == "__main__":
unittest.main()