luckiest-co 1.0.0 → 1.0.3

package/skills/luckiest-trends/scripts/lib/transcribe.py

@@ -0,0 +1,235 @@
+"""Caption-free transcription: compress -> chunk -> provider-fallback.
+
+When a video/audio item has no captions, this turns the media into text via a
+Whisper API. Source-agnostic: the input is a media URL or local path, the output
+is transcript text. The pipeline:
+
+  1. Acquire audio (yt-dlp for a URL, or use a local file as-is).
+  2. Re-encode to a low-bitrate mono stream so most clips fit under the provider
+     upload limit.
+  3. If still over the limit, split into bounded-duration chunks.
+  4. Transcribe each chunk through an ordered provider list (Groq free tier
+     first, OpenAI paid backstop), with per-chunk fallback, then join.
+
+Never raises. Returns a typed :class:`TranscriptResult`; missing prerequisites
+(no ffmpeg, no provider key) yield a degraded result with a reason, consumed by
+the source-health layer, rather than a crash.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from typing import Optional
+
+from . import env, health, subproc
+
+# Whisper's documented upload ceiling. We compress to stay under it and chunk
+# when a single clip still exceeds it.
+MAX_UPLOAD_BYTES = 25 * 1024 * 1024
+CHUNK_SECONDS = 600  # 10-minute chunks when splitting is required
+
+_PROVIDER_ENDPOINTS = {
+    "groq": "https://api.groq.com/openai/v1/audio/transcriptions",
+    "openai": "https://api.openai.com/v1/audio/transcriptions",
+}
+_PROVIDER_MODELS = {
+    "groq": "whisper-large-v3",
+    "openai": "whisper-1",
+}
+
+
+@dataclass
+class TranscriptResult:
+    text: str = ""
+    ok: bool = False
+    reason: str = ""
+    provider: str = ""
+    chunks: int = 0
+    health: Optional[health.SourceHealth] = field(default=None)
+
+
+def is_available(config: dict) -> bool:
+    """True when ffmpeg is present AND at least one Whisper provider key is set."""
+    return bool(shutil.which("ffmpeg")) and bool(env.transcription_providers(config))
+
+
+def transcribe_media(
+    source: str,
+    config: dict,
+    timeout: float = 120.0,
+) -> TranscriptResult:
+    """Transcribe a media URL or local path. Never raises.
+
+    Returns a degraded result (ok=False, reason set) when prerequisites are
+    missing or every provider fails, so callers can report the gap honestly.
+    """
+    if not shutil.which("ffmpeg"):
+        return _degraded("ffmpeg not installed", health.MISSING)
+    providers = env.transcription_providers(config)
+    if not providers:
+        return _degraded(
+            "no transcription provider key (set GROQ_API_KEY or OPENAI_API_KEY)",
+            health.MISSING,
+        )
+
+    workdir = tempfile.mkdtemp(prefix="l30d-transcribe-")
+    try:
+        audio_path = _acquire_audio(source, workdir, timeout=timeout)
+        if not audio_path:
+            return _degraded("could not acquire/compress audio", health.ERROR)
+
+        chunk_paths = _chunk_audio(audio_path, workdir)
+        if not chunk_paths:
+            return _degraded("audio chunking produced no segments", health.ERROR)
+
+        texts: list[str] = []
+        used_provider = ""
+        for chunk in chunk_paths:
+            chunk_text, provider = _transcribe_chunk(chunk, providers, timeout=timeout)
+            if chunk_text is None:
+                return _degraded(
+                    f"all providers failed on a chunk ({len(texts)}/{len(chunk_paths)} done)",
+                    health.ERROR,
+                )
+            texts.append(chunk_text)
+            used_provider = provider or used_provider
+
+        joined = "\n".join(t.strip() for t in texts if t.strip())
+        if not joined:
+            return _degraded("transcription produced empty text", health.DEGRADED)
+        return TranscriptResult(
+            text=joined,
+            ok=True,
+            provider=used_provider,
+            chunks=len(chunk_paths),
+            health=health.SourceHealth(name="transcribe", state=health.OK),
+        )
+    finally:
+        shutil.rmtree(workdir, ignore_errors=True)
+
+
+def _degraded(reason: str, state: str) -> TranscriptResult:
+    return TranscriptResult(
+        ok=False,
+        reason=reason,
+        health=health.SourceHealth(name="transcribe", state=state, reason=reason),
+    )
+
+
+def _acquire_audio(source: str, workdir: str, timeout: float) -> Optional[str]:
+    """Produce a compressed mono/16kHz/low-bitrate audio file, or None.
+
+    For a URL, extract audio with yt-dlp; for a local path, transcode it. The
+    re-encode keeps most clips under the upload ceiling.
+    """
+    raw = source
+    if source.startswith("http"):
+        raw = os.path.join(workdir, "raw.m4a")
+        if not _run([
+            "yt-dlp", "-f", "bestaudio", "-o", raw, "--no-playlist", source
+        ], timeout=timeout):
+            return None
+        if not os.path.exists(raw):
+            return None
+    elif not os.path.exists(source):
+        return None
+
+    out = os.path.join(workdir, "audio.mp3")
+    # Mono, 16kHz, 32kbps keeps speech intelligible while shrinking the file.
+    if not _run([
+        "ffmpeg", "-y", "-i", raw, "-ac", "1", "-ar", "16000", "-b:a", "32k", out
+    ], timeout=timeout):
+        return None
+    return out if os.path.exists(out) else None
+
+
+def _chunk_audio(audio_path: str, workdir: str) -> list[str]:
+    """Return [audio_path] when small enough, else ffmpeg-segmented chunk paths."""
+    try:
+        size = os.path.getsize(audio_path)
+    except OSError:
+        return []
+    if size <= MAX_UPLOAD_BYTES:
+        return [audio_path]
+
+    pattern = os.path.join(workdir, "chunk_%03d.mp3")
+    if not _run([
+        "ffmpeg", "-y", "-i", audio_path, "-f", "segment",
+        "-segment_time", str(CHUNK_SECONDS), "-c", "copy", pattern
+    ]):
+        # Fall back to the single (oversized) file; the provider may still accept it.
+        return [audio_path]
+    chunks = sorted(
+        os.path.join(workdir, f) for f in os.listdir(workdir) if f.startswith("chunk_")
+    )
+    return chunks or [audio_path]
+
+
+def _transcribe_chunk(
+    path: str,
+    providers: list[tuple[str, str]],
+    timeout: float,
+) -> tuple[Optional[str], str]:
+    """Try each provider in order; return (text, provider) or (None, '')."""
+    for name, key in providers:
+        try:
+            text = _post_audio(name, path, key, timeout=timeout)
+        except Exception:  # noqa: BLE001 - any provider failure -> try the next
+            text = None
+        if text is not None:
+            return text, name
+    return None, ""
+
+
+def _post_audio(provider: str, path: str, api_key: str, timeout: float) -> Optional[str]:
+    """POST one audio file to a Whisper-compatible endpoint; return text or None."""
+    import json
+    import urllib.request
+
+    endpoint = _PROVIDER_ENDPOINTS[provider]
+    model = _PROVIDER_MODELS[provider]
+    boundary = "----l30dTranscribeBoundary"
+    with open(path, "rb") as fh:
+        audio = fh.read()
+
+    parts: list[bytes] = []
+    parts.append(f"--{boundary}\r\n".encode())
+    parts.append(b'Content-Disposition: form-data; name="model"\r\n\r\n')
+    parts.append(f"{model}\r\n".encode())
+    parts.append(f"--{boundary}\r\n".encode())
+    parts.append(
+        b'Content-Disposition: form-data; name="file"; filename="audio.mp3"\r\n'
+        b"Content-Type: audio/mpeg\r\n\r\n"
+    )
+    parts.append(audio)
+    parts.append(f"\r\n--{boundary}--\r\n".encode())
+    body = b"".join(parts)
+
+    req = urllib.request.Request(
+        endpoint,
+        data=body,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": f"multipart/form-data; boundary={boundary}",
+        },
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        data = json.loads(resp.read().decode("utf-8"))
+    return data.get("text")
+
+
+def _run(command: list[str], timeout: float = 120.0) -> bool:
+    """Run a subprocess; return True on exit 0, False on any failure. No raise.
+
+    Uses subproc.run_with_timeout so a timed-out yt-dlp/ffmpeg is killed at the
+    process-group level (os.setsid/killpg) instead of orphaning child trees.
+    """
+    try:
+        result = subproc.run_with_timeout(command, timeout=int(timeout))
+    except (subproc.SubprocTimeout, FileNotFoundError, OSError):
+        return False
+    return result.returncode == 0

package/skills/luckiest-trends/scripts/lib/trustpilot.py

@@ -0,0 +1,277 @@
+"""Trustpilot brand-sentiment source for last30days.
+
+Shells out to ``trustpilot-pp-cli`` to surface a company's TrustScore and
+Trustpilot's own AI review summary for brand/company topics. Trustpilot has no
+API key, but it sits behind AWS WAF: the CLI harvests an ``aws-waf-token`` via
+a one-time headless Chrome launch (~10s), then replays it over plain HTTP until
+it expires.
+
+Activation gate: only available when ``trustpilot-pp-cli`` is on PATH.
+``pipeline.available_sources`` checks ``shutil.which`` before including
+``trustpilot``.
+
+Default-on safety (three gates):
+  1. Brand-shape gate. The CLI is invoked only when the topic resolves to a
+     company/brand -- a domain-like token, or a short (<=2-word) capitalized
+     proper noun. Generic phrases ("AI coding agents", "agent memory") and
+     longer multi-word phrases never call the CLI, so Trustpilot stays quiet --
+     and never harvests Chrome -- on non-company topics.
+  2. Browser opt-out. Automated contexts (cron, CI, the eval harness) can set
+     ``LAST30DAYS_TRUSTPILOT_NO_BROWSER`` to disable the source entirely, so a
+     headless run never spawns the cookie harvest.
+  3. Graceful degradation. Any CLI failure (no Chrome, expired cookie that
+     cannot re-harvest, timeout) degrades to empty results, never an error.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+from typing import Any, Dict, List, Optional
+
+from . import dates, log, subproc
+from .relevance import token_overlap_relevance
+
+
+CLI_BIN = "trustpilot-pp-cli"
+
+SEARCH_TIMEOUT = 75  # generous: a cold run may harvest a WAF cookie (~10s).
+
+NO_BROWSER_ENV = "LAST30DAYS_TRUSTPILOT_NO_BROWSER"
+
+# Domain-like token, e.g. "chownow.com", "nothing.tech".
+_DOMAIN_RE = re.compile(r"\b[a-z0-9][a-z0-9-]*\.(com|io|co|net|org|app|ai|dev|gg|tech|shop|store)\b")
+
+# Generic tokens that disqualify a short capitalized phrase from being a brand.
+_GENERIC_TOKENS = {
+    "ai", "best", "top", "vs", "review", "reviews", "guide", "tutorial",
+    "how", "what", "why", "agents", "agent", "memory", "tips", "news",
+}
+
+# Single-word programming languages, frameworks, runtimes, OSes, and dev tools.
+# A bare capitalized "Python"/"React"/"Docker" query is overwhelmingly about the
+# technology, not a company's customer reviews -- letting it through would both
+# trigger the Chrome harvest and risk surfacing an unrelated company that shares
+# the name. A user who genuinely wants the company can use its domain
+# (e.g. "docker.com"), which still passes via the domain branch.
+_TECH_TOKENS = {
+    "python", "javascript", "typescript", "java", "rust", "ruby", "php",
+    "kotlin", "scala", "golang", "swift", "elixir", "erlang", "haskell",
+    "react", "vue", "angular", "svelte", "django", "flask", "rails", "spring",
+    "node", "nodejs", "deno", "bun", "express", "nextjs", "nuxt",
+    "linux", "ubuntu", "debian", "fedora", "windows", "macos", "android",
+    "docker", "kubernetes", "k8s", "terraform", "ansible", "nginx",
+    "redis", "postgres", "postgresql", "mysql", "sqlite", "mongodb", "kafka",
+    "graphql", "webpack", "vite", "rust", "wasm",
+}
+
+
+def _log(msg: str) -> None:
+    log.source_log("Trustpilot", msg, tty_only=False)
+
+
+def _is_available() -> bool:
+    """True when the trustpilot-pp-cli binary is on PATH."""
+    return shutil.which(CLI_BIN) is not None
+
+
+def _truthy(value: Any) -> bool:
+    return str(value or "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def _harvest_allowed(config: Optional[Dict[str, Any]]) -> bool:
+    """False when the browser opt-out is set (automated/headless contexts).
+
+    Reads the opt-out from the merged config AND directly from the process
+    environment. The env fallback is load-bearing: ``config`` is assembled from
+    an allowlist in ``env.get_config``, so a fallback here guarantees the
+    documented kill-switch works even when the key is not propagated into
+    config (e.g. a bare ``LAST30DAYS_TRUSTPILOT_NO_BROWSER=1`` in cron/CI).
+    """
+    if config and _truthy(config.get(NO_BROWSER_ENV)):
+        return False
+    if _truthy(os.environ.get(NO_BROWSER_ENV)):
+        return False
+    return True
+
+
+def is_brand_shaped(topic: str) -> bool:
+    """True when the topic looks like a company/brand Trustpilot can resolve.
+
+    A domain-like token always qualifies. Otherwise the topic must be a short
+    (<=2-word) capitalized proper noun with no generic tokens -- this lets
+    "ChowNow", "Nothing Phone", and "OpenAI" through while keeping "AI coding
+    agents", "agent memory", and "Golden State Warriors" out.
+    """
+    if not topic or not topic.strip():
+        return False
+    text = topic.strip()
+    if _DOMAIN_RE.search(text.lower()):
+        return True
+    words = text.split()
+    if len(words) > 2:
+        return False
+    if any(w.lower() in _GENERIC_TOKENS or w.lower() in _TECH_TOKENS for w in words):
+        return False
+    # At least one token must look like a proper noun (leading capital).
+    return any(w[:1].isupper() for w in words)
+
+
+def _company_identifier(topic: str) -> str:
+    """Pick the identifier to hand the CLI: a domain token if present, else the
+    cleaned topic string."""
+    m = _DOMAIN_RE.search(topic.lower())
+    if m:
+        return m.group(0)
+    return topic.strip()
+
+
+def _build_info_args(identifier: str) -> List[str]:
+    return [CLI_BIN, "info", identifier, "--agent"]
+
+
+def _run_cli(cmd: List[str], timeout: int) -> Dict[str, Any]:
+    """Invoke trustpilot-pp-cli and parse the JSON object. Never raises."""
+    if not _is_available():
+        return {"error": f"{CLI_BIN} not on PATH"}
+    try:
+        result = subproc.run_with_timeout(cmd, timeout=timeout)
+    except subproc.SubprocTimeout as exc:
+        _log(f"Timeout: {exc}")
+        return {"error": str(exc)}
+    except FileNotFoundError as exc:
+        _log(f"Binary missing: {exc}")
+        return {"error": str(exc)}
+    except OSError as exc:
+        _log(f"Spawn failed: {exc}")
+        return {"error": str(exc)}
+
+    if result.returncode != 0:
+        snippet = (result.stderr or "").strip().splitlines()[:1]
+        first = snippet[0] if snippet else f"exit {result.returncode}"
+        _log(f"CLI exit {result.returncode}: {first}")
+        return {"error": first}
+
+    stdout = result.stdout or ""
+    if not stdout.strip():
+        return {}
+    try:
+        data = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        _log(f"JSON decode failed: {exc}")
+        return {"error": f"json decode: {exc}"}
+    return data if isinstance(data, dict) else {}
+
+
+def search_trustpilot(
+    topic: str,
+    from_date: str,
+    to_date: str,
+    depth: str = "default",
+    config: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Look up a company's Trustpilot sentiment, gated on a brand-shaped topic.
+
+    Returns ``{"results": [info_dict]}`` for a resolved company, or
+    ``{"results": []}`` when the topic is not brand-shaped, the browser opt-out
+    is set, or the CLI fails.
+    """
+    if not is_brand_shaped(topic):
+        return {"results": []}
+    if not _is_available():
+        return {"results": [], "error": f"{CLI_BIN} not on PATH"}
+    if not _harvest_allowed(config):
+        _log("skipped: browser opt-out set")
+        return {"results": []}
+    identifier = _company_identifier(topic)
+    _log(f"info '{identifier}'")
+    data = _run_cli(_build_info_args(identifier), timeout=SEARCH_TIMEOUT)
+    if "error" in data or not data:
+        return {"results": []}
+    return {"results": [data]}
+
+
+def _coerce_float(value: Any) -> Optional[float]:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _coerce_int(value: Any) -> Optional[int]:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def parse_trustpilot_response(
+    response: Dict[str, Any],
+    query: str = "",
+) -> List[Dict[str, Any]]:
+    """Parse a Trustpilot ``info`` envelope into a single normalized item.
+
+    The AI summary is the body (it already balances positive and negative
+    sentiment). TrustScore and review count feed engagement and metadata.
+    Returns dicts ready for ``normalize._normalize_trustpilot``.
+    """
+    raw = response.get("results") if isinstance(response, dict) else None
+    if not isinstance(raw, list) or not raw:
+        return []
+    info = raw[0]
+    if not isinstance(info, dict):
+        return []
+
+    resolved_name = str(info.get("name") or info.get("displayName") or "").strip()
+    ai_summary = str(info.get("aiSummary") or info.get("summary") or "").strip()
+    trust_score = _coerce_float(info.get("trustScore") or info.get("score"))
+    review_count = _coerce_int(
+        info.get("reviewCount") or info.get("numberOfReviews") or info.get("total")
+    )
+    url = str(info.get("url") or "").strip()
+    domain = str(info.get("domain") or info.get("identifyingName") or "").strip()
+    if not url and domain:
+        url = f"https://www.trustpilot.com/review/{domain}"
+
+    # Require substantive content from the company record itself; do not
+    # fabricate an item from the query alone when the CLI returned nothing.
+    if not resolved_name and not ai_summary and trust_score is None and review_count is None:
+        return []
+
+    name = resolved_name or query.strip()
+
+    title = f"{name} on Trustpilot" if name else "Trustpilot reviews"
+    if trust_score is not None:
+        title = f"{name}: TrustScore {trust_score}" if name else title
+
+    engagement: Dict[str, float | int] = {}
+    if review_count is not None:
+        engagement["reviews"] = review_count
+    if trust_score is not None:
+        engagement["trustScore"] = trust_score
+
+    relevance = token_overlap_relevance(query, name) if (query and name) else 0.7
+
+    why = "Trustpilot brand sentiment"
+    if trust_score is not None and review_count is not None:
+        why = f"Trustpilot: TrustScore {trust_score} across {review_count} reviews"
+    elif trust_score is not None:
+        why = f"Trustpilot: TrustScore {trust_score}"
+
+    return [
+        {
+            "id": domain or name or "trustpilot",
+            "title": title,
+            "url": url,
+            "summary": ai_summary,
+            "name": name,
+            "trustScore": trust_score,
+            "reviewCount": review_count,
+            "date": dates.get_date_range(1)[0],
+            "engagement": engagement,
+            "relevance": round(min(1.0, max(0.4, relevance)), 2),
+            "why_relevant": why,
+        }
+    ]

package/skills/luckiest-trends/scripts/lib/truthsocial.py

@@ -0,0 +1,162 @@
+"""Truth Social search via Mastodon-compatible API (requires bearer token).
+
+Uses truthsocial.com/api/v2/search endpoint.
+Requires TRUTHSOCIAL_TOKEN env var (bearer token from browser dev tools).
+"""
+
+import math
+import re
+import sys
+from typing import Any, Dict, List, Optional
+
+from . import http, log
+
+TRUTHSOCIAL_SEARCH_URL = "https://truthsocial.com/api/v2/search"
+
+DEPTH_CONFIG = {
+    "quick": 15,
+    "default": 30,
+    "deep": 60,
+}
+
+
+def _log(msg: str):
+    log.source_log("TruthSocial", msg, tty_only=False)
+
+
+def _strip_html(html: str) -> str:
+    """Strip HTML tags from Truth Social post content."""
+    text = re.sub(r'<br\s*/?>', '\n', html)
+    text = re.sub(r'<[^>]+>', '', text)
+    return text.strip()
+
+
+def _extract_core_subject(topic: str) -> str:
+    """Extract core subject from verbose query for Truth Social search."""
+    from .query import SOCIAL_NOISE, extract_core_subject
+    return extract_core_subject(topic, noise=SOCIAL_NOISE)
+
+
+def _parse_date(status: Dict[str, Any]) -> Optional[str]:
+    """Parse date from Mastodon status to YYYY-MM-DD.
+
+    Mastodon uses ISO 8601 format in created_at field.
+    """
+    val = status.get("created_at")
+    if val and isinstance(val, str) and len(val) >= 10:
+        return val[:10]
+    return None
+
+
+def search_truthsocial(
+    topic: str,
+    from_date: str,
+    to_date: str,
+    depth: str = "default",
+    config: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Search Truth Social via Mastodon-compatible API.
+
+    Args:
+        topic: Search topic
+        from_date: Start date (YYYY-MM-DD)
+        to_date: End date (YYYY-MM-DD)
+        depth: 'quick', 'default', or 'deep'
+        config: Config dict with TRUTHSOCIAL_TOKEN
+
+    Returns:
+        Dict with 'statuses' list from Mastodon API response.
+    """
+    config = config or {}
+    token = config.get("TRUTHSOCIAL_TOKEN", "")
+
+    if not token:
+        return {"statuses": [], "error": "Truth Social token not configured"}
+
+    count = DEPTH_CONFIG.get(depth, DEPTH_CONFIG["default"])
+    core_topic = _extract_core_subject(topic)
+
+    _log(f"Searching for '{core_topic}' (depth={depth}, limit={count})")
+
+    from urllib.parse import urlencode
+    params = {
+        "q": core_topic,
+        "type": "statuses",
+        "limit": str(min(count, 40)),
+    }
+    url = f"{TRUTHSOCIAL_SEARCH_URL}?{urlencode(params)}"
+
+    try:
+        response = http.request(
+            "GET", url,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=30,
+        )
+    except http.HTTPError as e:
+        if e.status_code == 401:
+            _log("Token expired")
+            return {"statuses": [], "error": "Truth Social token expired"}
+        elif e.status_code == 403:
+            _log("Access denied (Cloudflare)")
+            return {"statuses": [], "error": "Truth Social access denied (Cloudflare)"}
+        elif e.status_code == 429:
+            _log("Rate limited")
+            return {"statuses": [], "error": "Truth Social rate limited"}
+        else:
+            _log(f"Search failed: {e}")
+            return {"statuses": [], "error": f"Truth Social search failed: {e.status_code}"}
+    except Exception as e:
+        _log(f"Search failed: {e}")
+        return {"statuses": [], "error": str(e)}
+
+    statuses = response.get("statuses", [])
+    _log(f"Found {len(statuses)} posts")
+    return response
+
+
+def parse_truthsocial_response(response: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """Parse Mastodon API response into normalized item dicts.
+
+    Returns:
+        List of item dicts ready for normalization.
+    """
+    statuses = response.get("statuses", [])
+    items = []
+
+    for i, status in enumerate(statuses):
+        content_html = status.get("content") or ""
+        text = _strip_html(content_html)
+
+        account = status.get("account") or {}
+        handle = account.get("acct") or account.get("username") or ""
+        display_name = account.get("display_name") or handle
+
+        url = status.get("url") or ""
+
+        likes = status.get("favourites_count") or 0
+        reposts = status.get("reblogs_count") or 0
+        replies = status.get("replies_count") or 0
+
+        date_str = _parse_date(status)
+
+        # Relevance: position-based (search results are ranked by relevance)
+        rank_score = max(0.3, 1.0 - (i * 0.02))
+        engagement_boost = min(0.2, math.log1p(likes + reposts) / 40)
+        relevance = min(1.0, rank_score * 0.7 + engagement_boost + 0.1)
+
+        items.append({
+            "handle": handle,
+            "display_name": display_name,
+            "text": text,
+            "url": url,
+            "date": date_str,
+            "engagement": {
+                "likes": likes,
+                "reposts": reposts,
+                "replies": replies,
+            },
+            "relevance": round(relevance, 2),
+            "why_relevant": f"Truth Social: @{handle}: {text[:60]}" if text else f"Truth Social: {handle}",
+        })
+
+    return items