crowdsonar 0.1.2__py3-none-any.whl

crowdsonar/__init__.py

@@ -0,0 +1,3 @@
+"""CrowdSonar — social signal synthesis engine (Reddit listening → LLM classification → briefings)."""
+
+__version__ = "0.1.2"

crowdsonar/arctic_shift.py

@@ -0,0 +1,248 @@
+"""Arctic Shift API adapter — credential-free Reddit ingestion (primary source).
+
+Replaces PullPush (dead 2026-09) as the default ingestion path. Source-selection
+rationale, in brief: PullPush's API went dark in September 2026; the official
+Reddit API was a poor fit for research-scale reads (paid tier, per-request
+costs, and 2026-09 policy shifts that killed several projects in this niche);
+Arctic Shift is a volunteer-run public archive with a free, key-less JSON API
+covering full Reddit history. Cost of the trade-off: single-operator
+availability risk — mitigated by per-run local snapshots and a pluggable
+source layer (PRAW overlay retained, HN/RSS adapters planned).
+
+Strategy: fetch the full post window per subreddit (server-side time filter,
+paginated), then filter by keywords locally using the same `_matches_keywords`
+semantics as the PRAW path. Server-side keyword search (`title=`/`selftext=`/
+`body=` params) is deliberately avoided — it times out on active subreddits
+and the API docs mark its behavior as "not guaranteed".
+
+Comment recovery mirrors PRAW: for each keyword-matched post, fetch comments
+via `link_id`, sort by score locally, keep the top `comments_per_post`.
+
+Be polite: this is a free volunteer-run service. Requests are throttled below
+"a couple per second" (their stated safe zone); 429 and query-timeout get
+retried with backoff and a shrunk limit.
+"""
+
+import logging
+import time
+from datetime import datetime, timedelta, timezone
+
+import httpx
+
+from .ingest import IngestResult, RawPost, _matches_keywords
+
+log = logging.getLogger(__name__)
+
+BASE_URL = "https://arctic-shift.photon-reddit.com"
+POST_FIELDS = "id,title,selftext,subreddit,author,score,created_utc"
+COMMENT_FIELDS = "id,body,author,score,created_utc,link_id"
+PAGE_SIZE = 100           # explicit (not "auto") so cursor pagination is predictable
+MAX_PAGES_PER_SUB = 20    # safety cap: 20 × 100 = 2000 posts per sub per window
+REQUEST_INTERVAL = 0.6    # seconds between requests — inside their "couple/sec" tolerance
+
+TIME_FILTER_DAYS = {
+    "hour": 1 / 24,
+    "day": 1,
+    "week": 7,
+    "month": 30,
+    "year": 365,
+    "all": None,
+}
+
+
+def _iso(ts: float) -> str:
+    """Epoch seconds → ISO string in the format the API accepts (validated)."""
+    return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+
+
+class ArcticShiftClient:
+    """Throttled wrapper over the Arctic Shift search endpoints."""
+
+    def __init__(self, base_url: str = BASE_URL, timeout: float = 30.0,
+                 request_interval: float = REQUEST_INTERVAL):
+        self._http = httpx.Client(base_url=base_url, timeout=timeout)
+        self._interval = request_interval
+        self._last = 0.0
+
+    def close(self) -> None:
+        self._http.close()
+
+    def search(self, kind: str, params: dict) -> list[dict]:
+        """GET /api/{kind}/search with 429 / query-timeout retry. Returns data list."""
+        p = dict(params)
+        path = f"/api/{kind}/search"
+        for attempt in range(3):
+            wait = self._interval - (time.monotonic() - self._last)
+            if wait > 0:
+                time.sleep(wait)
+            self._last = time.monotonic()
+            try:
+                resp = self._http.get(path, params=p)
+            except httpx.HTTPError as e:
+                log.warning("Arctic Shift %s: %s (attempt %d/3)", path, e, attempt + 1)
+                time.sleep(2 ** attempt)
+                continue
+            if resp.status_code == 429:
+                reset = float(resp.headers.get("X-RateLimit-Reset") or 30)
+                log.warning("Arctic Shift: rate limited, sleeping %.0fs", min(reset, 120))
+                time.sleep(min(reset, 120))
+                continue
+            resp.raise_for_status()
+            body = resp.json()
+            err = body.get("error")
+            if err:
+                msg = str(err)
+                if "imeout" in msg:  # "Query timed out" / "Timeout. Maybe slow down a bit"
+                    p = dict(p)
+                    lim = p.get("limit", PAGE_SIZE)
+                    # "auto" (comment search) has no numeric half — drop to 100.
+                    p["limit"] = max(10, lim // 2) if isinstance(lim, int) else 100
+                    log.warning("Arctic Shift: query timed out — retrying with limit=%s", p["limit"])
+                    time.sleep(2 ** attempt)
+                    continue
+                raise RuntimeError(f"Arctic Shift error: {msg}")
+            return body.get("data") or []
+        return []  # retries exhausted; caller sees a short/empty page
+
+
+def fetch_window_posts(client: ArcticShiftClient, subreddit: str,
+                       window_days: float | None) -> list[dict]:
+    """All posts in r/<subreddit> within `window_days` (None = no lower bound)."""
+    items: list[dict] = []
+    cursor: float | None = None
+    for _ in range(MAX_PAGES_PER_SUB):
+        params = {
+            "subreddit": subreddit,
+            "limit": PAGE_SIZE,
+            "sort": "asc",
+            "fields": POST_FIELDS,
+        }
+        if cursor is not None:
+            params["after"] = _iso(cursor)
+        elif window_days is not None:
+            params["after"] = _iso(
+                (datetime.now(timezone.utc) - timedelta(days=window_days)).timestamp()
+            )
+        batch = client.search("posts", params)
+        if not batch:
+            break
+        items.extend(batch)
+        if len(batch) < PAGE_SIZE:
+            break
+        new_cursor = float(batch[-1].get("created_utc") or 0)
+        if cursor is not None and new_cursor <= cursor:
+            break  # cursor stalled (same-second pileup); dedup handles overlap
+        cursor = new_cursor
+    return items
+
+
+def fetch_post_comments(client: ArcticShiftClient, post_id: str) -> list[dict]:
+    """Comments under a post (up to ~1000 via limit=auto); caller sorts/filters."""
+    return client.search("comments", {
+        "link_id": f"t3_{post_id}",
+        "limit": "auto",
+        "fields": COMMENT_FIELDS,
+    })
+
+
+def _post_raw(item: dict, kw: str) -> RawPost:
+    pid = item.get("id", "")
+    sub = item.get("subreddit", "")
+    return RawPost(
+        source="arctic",
+        post_id=pid,
+        post_title=item.get("title", ""),
+        post_url=f"https://reddit.com/r/{sub}/comments/{pid}",
+        post_subreddit=sub,
+        post_author=item.get("author") or "[deleted]",
+        post_score=int(item.get("score") or 0),
+        post_created_utc=float(item.get("created_utc") or 0),
+        post_body=item.get("selftext") or "",
+        keyword_match=kw,
+    )
+
+
+def _comment_raw(item: dict, parent: RawPost, kw: str) -> RawPost:
+    return RawPost(
+        source="arctic",
+        post_id=parent.post_id,
+        post_title=parent.post_title,
+        post_url=parent.post_url,
+        post_subreddit=parent.post_subreddit,
+        post_author=parent.post_author,
+        post_score=parent.post_score,
+        post_created_utc=parent.post_created_utc,
+        post_body=parent.post_body,
+        comment_id=item.get("id", ""),
+        comment_body=item.get("body") or "",
+        comment_author=item.get("author") or "[deleted]",
+        comment_score=int(item.get("score") or 0),
+        comment_created_utc=float(item.get("created_utc") or 0),
+        keyword_match=kw,
+    )
+
+
+def ingest_arctic(
+    subreddits: list[str],
+    keywords: list[str],
+    time_filter: str = "week",
+    post_limit: int = 50,
+    comments_per_post: int = 20,
+    backfill_days: int = 0,
+    base_url: str = BASE_URL,
+) -> IngestResult:
+    """Ingest via Arctic Shift — semantics mirror ingest_praw.
+
+    Posts matching any keyword (title or body, case-insensitive substring)
+    within the time window, plus the top `comments_per_post` comments (by
+    score) of each matched post. `backfill_days > 0` widens the window
+    (replaces the dead PullPush backfill). `post_limit` caps matched posts
+    per subreddit (newest kept).
+    """
+    result = IngestResult()
+    window = backfill_days if backfill_days > 0 else TIME_FILTER_DAYS.get(time_filter, 7)
+    client = ArcticShiftClient(base_url=base_url)
+    try:
+        for sub in subreddits:
+            try:
+                items = fetch_window_posts(client, sub, window)
+            except Exception as e:
+                result.errors.append(f"posts r/{sub}: {e}")
+                continue
+
+            # Pagination can straddle a boundary second — dedupe by post id.
+            seen: set[str] = set()
+            unique = [x for x in items
+                      if not ((x.get("id") or "") in seen or seen.add(x.get("id") or ""))]
+            log.info("Arctic Shift: r/%s → %d posts in %.1f-day window",
+                     sub, len(unique), window if window is not None else -1)
+
+            matched: list[tuple[dict, str]] = []
+            for it in unique:
+                kw = _matches_keywords(
+                    (it.get("title") or "") + " " + (it.get("selftext") or ""), keywords
+                )
+                if kw:
+                    matched.append((it, kw))
+
+            if post_limit and len(matched) > post_limit:
+                matched.sort(key=lambda x: x[0].get("created_utc") or 0, reverse=True)
+                matched = matched[:post_limit]
+
+            for it, kw in matched:
+                parent = _post_raw(it, kw)
+                result.posts.append(parent)
+                if comments_per_post > 0:
+                    try:
+                        cs = fetch_post_comments(client, it.get("id", ""))
+                    except Exception as e:
+                        result.errors.append(f"comments t3_{it.get('id')}: {e}")
+                        cs = []
+                    cs.sort(key=lambda c: c.get("score") or 0, reverse=True)
+                    for c in cs[:comments_per_post]:
+                        result.posts.append(_comment_raw(c, parent, kw))
+    finally:
+        client.close()
+
+    log.info("Arctic Shift: collected %d items, %d errors", len(result.posts), len(result.errors))
+    return result

crowdsonar/classify.py

@@ -0,0 +1,147 @@
+"""LLM classification — batch posts through a cheap model, return structured signals."""
+
+import json
+import logging
+import os
+from importlib import resources
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+PROMPT_DIR = resources.files("crowdsonar") / "prompts"
+
+
+def _load_prompt(name: str) -> str:
+    return (PROMPT_DIR / f"{name}.md").read_text(encoding="utf-8")
+
+
+def _build_batch_items(raw_posts) -> list[dict]:
+    """Convert RawPost list into compact items for the LLM."""
+    items = []
+    for i, p in enumerate(raw_posts):
+        text = p.post_title
+        if p.comment_body:
+            text += f"\n\nComment: {p.comment_body}"
+        elif p.post_body:
+            text += f"\n\n{p.post_body}"
+
+        items.append({
+            "idx": i,
+            "text": text[:1500],  # truncate to save tokens
+            "subreddit": p.post_subreddit,
+            "keyword_match": p.keyword_match,
+        })
+    return items
+
+
+def classify_batch(
+    raw_posts: list,
+    model: str = "gpt-4o-mini",
+    api_key: str | None = None,
+    base_url: str | None = None,
+    batch_size: int = 25,
+) -> list[dict]:
+    """Classify a list of RawPost objects via LLM.
+
+    Returns a list of classification dicts, one per input post,
+    aligned by index.
+    """
+    api_key = api_key or os.environ.get("OPENAI_API_KEY", "")
+    base_url = base_url or os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1")
+
+    if not api_key:
+        raise ValueError("No API key provided. Set OPENAI_API_KEY or pass api_key.")
+
+    system_prompt = _load_prompt("classify")
+    all_classifications: list[dict] = []
+
+    # Process in batches
+    for start in range(0, len(raw_posts), batch_size):
+        batch = raw_posts[start:start + batch_size]
+        items = _build_batch_items(batch)
+
+        user_msg = json.dumps(items, ensure_ascii=False)
+
+        log.info("Classifying batch %d-%d (%d items) via %s",
+                 start, start + len(batch), len(batch), model)
+
+        try:
+            resp = httpx.post(
+                f"{base_url}/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "model": model,
+                    "messages": [
+                        {"role": "system", "content": system_prompt},
+                        {"role": "user", "content": user_msg},
+                    ],
+                    "temperature": 0.1,
+# Some backends spend reasoning tokens inside max_tokens —
+                    # pin effort explicitly so content never gets starved.
+                    "reasoning_effort": "low",
+                    "thinking": {"type": "enabled"},
+"max_tokens": 4096,
+                },
+                timeout=120,
+            )
+            resp.raise_for_status()
+            content = resp.json()["choices"][0]["message"]["content"].strip()
+
+            # Strip markdown fences if present
+            if content.startswith("```"):
+                content = content.split("\n", 1)[1] if "\n" in content else content[3:]
+            if content.endswith("```"):
+                content = content[:-3]
+            content = content.strip()
+
+            parsed = json.loads(content)
+            if not isinstance(parsed, list):
+                parsed = [parsed]
+
+            # Pad with defaults if LLM returned fewer items
+            default = {
+                "signal_type": "noise",
+                "sentiment": "neutral",
+                "strength": "casual",
+                "confirmation_status": "self_announced",
+                "entities": [],
+                "summary": "",
+            }
+            while len(parsed) < len(batch):
+                parsed.append({**default, "idx": len(parsed)})
+
+            all_classifications.extend(parsed)
+
+        except (json.JSONDecodeError, KeyError, IndexError) as e:
+            log.error("Failed to parse LLM response: %s", e)
+            # Fill batch with noise defaults
+            for i in range(len(batch)):
+                all_classifications.append({
+                    "idx": start + i,
+                    "signal_type": "noise",
+                    "sentiment": "neutral",
+                    "strength": "casual",
+                    "confirmation_status": "self_announced",
+                    "entities": [],
+                    "summary": f"[classification failed: {e}]",
+                })
+        except Exception as e:
+            log.error("LLM call failed: %s", e)
+            for i in range(len(batch)):
+                all_classifications.append({
+                    "idx": start + i,
+                    "signal_type": "noise",
+                    "sentiment": "neutral",
+                    "strength": "casual",
+                    "confirmation_status": "self_announced",
+                    "entities": [],
+                    "summary": f"[classification failed: {e}]",
+                })
+
+    # Sort by idx to align with input
+    all_classifications.sort(key=lambda x: x.get("idx", 0))
+    return all_classifications

crowdsonar/cli.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""CrowdSonar CLI — ingest, classify, synthesize social signals.
+
+Usage:
+    crowdsonar --topic example
+    crowdsonar --topic example --dry-run
+    crowdsonar --topic example --source arctic
+    crowdsonar --topic example --backfill
+    crowdsonar --topic example --classify-only
+    crowdsonar --topic example --synthesize-only
+    crowdsonar --list
+"""
+
+import argparse
+import logging
+import os
+import sys
+from datetime import datetime, timezone
+
+from crowdsonar import __version__
+from crowdsonar.config import load_topic, list_topics
+from crowdsonar.ingest import (
+    IngestResult,
+    RawPost,
+    ingest_praw,
+    create_praw_client,
+)
+from crowdsonar.arctic_shift import ingest_arctic
+from crowdsonar.classify import classify_batch
+from crowdsonar.storage import (
+    save_signals,
+    save_raw_posts,
+    pending_classifications,
+)
+from crowdsonar.synthesize import synthesize_briefing
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    datefmt="%H:%M:%S",
+)
+log = logging.getLogger("crowdsonar")
+
+
+def _raw_row_to_post(row: dict) -> RawPost:
+    """Convert a raw-store row dict back into a RawPost for classification."""
+    return RawPost(
+        source=row["source"],
+        post_id=row["post_id"],
+        post_title=row["post_title"],
+        post_url=row["post_url"],
+        post_subreddit=row["post_subreddit"],
+        post_author=row["post_author"],
+        post_score=row["post_score"],
+        post_created_utc=row["post_created_utc"],
+        post_body=row["post_body"],
+        comment_id=row["comment_id"],
+        comment_body=row["comment_body"],
+        comment_author=row["comment_author"],
+        comment_score=row["comment_score"],
+        comment_created_utc=row["comment_created_utc"],
+        keyword_match=row["keyword_match"],
+    )
+
+
+def parse_args():
+    p = argparse.ArgumentParser(description="CrowdSonar — social signal synthesis engine")
+    p.add_argument("--topic", "-t", help="Topic config name (from configs/)")
+    p.add_argument("--list", "-l", action="store_true", help="List available topics")
+    p.add_argument("--dry-run", action="store_true", help="Ingest and persist the raw store, skip all LLM calls")
+    p.add_argument("--source", choices=["auto", "arctic", "praw"], default="auto",
+                   help="Ingestion source: arctic = Arctic Shift API (credential-free, "
+                        "default); praw = Reddit OAuth only; auto = arctic + PRAW overlay "
+                        "when REDDIT_CLIENT_ID/SECRET are set")
+    p.add_argument("--backfill", action="store_true",
+                   help="Widen the ingest window to backfill_days from the topic config "
+                        "(one-off deep backfill; default window is time_filter)")
+    p.add_argument("--classify-only", action="store_true", help="Classify the pending raw/classified delta via LLM, append to signals (idempotent)")
+    p.add_argument("--synthesize-only", action="store_true", help="Only generate briefing from classified data")
+    p.add_argument("--model", default="gpt-4o-mini", help="LLM model for classification")
+    p.add_argument("--synth-model", default=None, help="LLM model for synthesis (default: same as --model)")
+    p.add_argument("--config-dir", default=None, help="Override configs directory")
+    return p.parse_args()
+
+
+def main():
+    args = parse_args()
+
+    if args.list:
+        topics = list_topics(args.config_dir)
+        if not topics:
+            print("No topic configs found in configs/")
+        else:
+            print("Available topics:")
+            for t in topics:
+                print(f"  - {t}")
+        return
+
+    if not args.topic:
+        print("Error: --topic is required (or use --list to see available topics)")
+        sys.exit(1)
+
+    # Load config
+    cfg = load_topic(args.topic, args.config_dir)
+    topic_name = cfg["name"]
+    reddit_cfg = cfg["sources"]["reddit"]
+    run_id = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+
+    log.info("Topic: %s | Run: %s | Source: %s", topic_name, run_id, args.source)
+
+    # ── Phase 1: Ingest ──
+    all_posts: list[RawPost] = []
+    pending: list[dict] = []  # raw/classified delta; computed in Phase 1 or --classify-only
+
+    if not args.synthesize_only and not args.classify_only:
+        backfill_days = reddit_cfg.get("backfill_days", 0) if args.backfill else 0
+
+        # Arctic Shift — primary, credential-free
+        if args.source in ("auto", "arctic"):
+            label = f"window={backfill_days}d (backfill)" if backfill_days else \
+                    f"time_filter={reddit_cfg.get('time_filter', 'week')}"
+            log.info("Phase 1a: Arctic Shift ingestion (%s)", label)
+            arctic_result = ingest_arctic(
+                subreddits=reddit_cfg["subreddits"],
+                keywords=reddit_cfg["keywords"],
+                time_filter=reddit_cfg.get("time_filter", "week"),
+                post_limit=reddit_cfg.get("post_limit", 50),
+                comments_per_post=reddit_cfg.get("comments_per_post", 20),
+                backfill_days=backfill_days,
+            )
+            all_posts.extend(arctic_result.posts)
+            for e in arctic_result.errors:
+                log.warning("Arctic Shift: %s", e)
+
+        # PRAW — optional real-time overlay
+        if args.source in ("auto", "praw"):
+            client_id = os.environ.get("REDDIT_CLIENT_ID")
+            client_secret = os.environ.get("REDDIT_CLIENT_SECRET")
+            if client_id and client_secret:
+                log.info("Phase 1b: PRAW real-time ingestion (overlay)")
+                reddit = create_praw_client(
+                    client_id=client_id,
+                    client_secret=client_secret,
+                    user_agent=f"crowdsonar/{__version__} (research project)",
+                )
+                praw_result = ingest_praw(
+                    reddit=reddit,
+                    subreddits=reddit_cfg["subreddits"],
+                    keywords=reddit_cfg["keywords"],
+                    sort=reddit_cfg.get("sort", "new"),
+                    time_filter=reddit_cfg.get("time_filter", "week"),
+                    post_limit=reddit_cfg.get("post_limit", 50),
+                    comments_per_post=reddit_cfg.get("comments_per_post", 20),
+                )
+                all_posts.extend(praw_result.posts)
+                for e in praw_result.errors:
+                    log.warning("PRAW: %s", e)
+            elif args.source == "praw":
+                log.error("--source praw requires REDDIT_CLIENT_ID and REDDIT_CLIENT_SECRET")
+                sys.exit(1)
+            else:
+                log.info("No REDDIT_CLIENT_ID/SECRET — PRAW overlay skipped (Arctic Shift only)")
+
+        # Deduplicate by (post_id, comment_id)
+        seen = set()
+        deduped = []
+        for p in all_posts:
+            key = (p.post_id, p.comment_id)
+            if key not in seen:
+                seen.add(key)
+                deduped.append(p)
+        all_posts = deduped
+
+        log.info("Ingest complete: %d unique items", len(all_posts))
+
+        # Persist raw BEFORE any LLM call (raw store) —
+        # banks the fetch even when we stop here (dry-run / empty window).
+        raw_path, new_raw = save_raw_posts(all_posts, topic_name, run_id)
+        log.info("Raw store: %d new rows -> %s", new_raw, raw_path)
+
+        # Classification operates on the raw/classified delta — idempotent
+        # across re-ingest and crash-resume (raw persists pre-LLM).
+        pending = pending_classifications(topic_name)
+
+        if args.dry_run:
+            print(f"\n[DRY RUN] {len(all_posts)} items ingested from {len(reddit_cfg['subreddits'])} subreddits; "
+                  f"{new_raw} new raw rows persisted to {raw_path}.")
+            print(f"Pending classification delta: {len(pending)} item(s). No LLM calls made.")
+            for p in all_posts[:5]:
+                label = "comment" if p.comment_id else "post"
+                print(f"  [{label}] r/{p.post_subreddit} ({p.keyword_match}) score={p.post_score} — {p.post_title[:80]}")
+            if len(all_posts) > 5:
+                print(f"  ... and {len(all_posts) - 5} more")
+            return
+
+        if not all_posts:
+            print(f"\nNo new items ingested this run (raw store: {raw_path}); "
+                  f"{len(pending)} pending item(s) in the classification delta.")
+            # fall through to Phase 2 — the delta may hold crash-resume work
+
+    # ── Phase 2: Classify ──
+    if not args.synthesize_only:
+        if args.classify_only:
+            # Skip ingest; operate purely on the raw/classified delta.
+            pending = pending_classifications(topic_name)
+            if not pending:
+                print(f"\n--classify-only: 0 pending — raw store for '{topic_name}' is fully classified.")
+                return
+            print(f"--classify-only: {len(pending)} pending item(s) in the raw/classified delta")
+
+        all_posts = [_raw_row_to_post(r) for r in pending]
+
+        if all_posts:
+            log.info("Phase 2: Classifying %d items via %s", len(all_posts), args.model)
+            classifications = classify_batch(all_posts, model=args.model)
+
+            # Save to Parquet
+            from crowdsonar.storage import _row_dict
+            rows = []
+            for raw, cls in zip(all_posts, classifications):
+                rows.append(_row_dict(raw, cls, run_id, topic_name))
+
+            path = save_signals(rows, topic_name, run_id)
+            print(f"\nSaved {len(rows)} classified signals to {path}")
+
+            # Quick summary
+            type_counts = {}
+            for r in rows:
+                t = r["signal_type"]
+                type_counts[t] = type_counts.get(t, 0) + 1
+            print("Signal breakdown:")
+            for t, c in sorted(type_counts.items(), key=lambda x: -x[1]):
+                print(f"  {t}: {c}")
+        else:
+            log.info("Phase 2: classification delta is empty — nothing to classify")
+
+    # ── Phase 3: Synthesize ──
+    if not args.dry_run and not args.classify_only:
+        synth_model = args.synth_model or args.model
+        log.info("Phase 3: Synthesizing briefing via %s", synth_model)
+        briefing = synthesize_briefing(
+            topic=topic_name,
+            topic_cfg=cfg,
+            run_id=run_id,
+            model=synth_model,
+        )
+        print(f"\n{'='*60}")
+        print(f"BRIEFING: {topic_name}")
+        print(f"{'='*60}")
+        print(briefing)
+
+        # Persist briefing to Zone 1
+        from crowdsonar.storage import DATA_DIR
+        briefings_dir = DATA_DIR / "briefings"
+        briefings_dir.mkdir(parents=True, exist_ok=True)
+        briefing_path = briefings_dir / f"{topic_name}_{run_id}.md"
+        briefing_path.write_text(briefing, encoding="utf-8")
+        log.info("Briefing saved to %s", briefing_path)
+
+
+if __name__ == "__main__":
+    main()