osintengine 1.0.2__py3-none-any.whl

src/watson/orchestration/synthesis.py

@@ -0,0 +1,726 @@
+"""Intelligence synthesis — turn gathered findings into an analyst's brief.
+
+This is the step that separates Watson from a clipping service. The reasoning
+loop gathers sources; synthesis READS them and produces:
+
+  - Executive summary (2-3 sentences: what's the bottom line)
+  - Key risk themes (grouped: antitrust, labor, tax, data/privacy, sanctions…)
+  - Severity per theme (HIGH / MEDIUM / LOW) with the evidence behind it
+  - Notable entities (people, orgs, regulators involved)
+  - Timeline (chronological events: career, criminal, legal, financial, education)
+  - Evidence gaps (what couldn't be verified)
+  - Recommended next steps
+  - Source list with credibility
+
+Every claim is grounded in a finding — synthesis NEVER invents facts.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+
+# Try to import Finding from wherever it lives
+try:
+    from watson.agents.protocol import Finding
+except ImportError:
+    try:
+        from watson.engine import Finding
+    except ImportError:
+        from dataclasses import dataclass
+
+        @dataclass
+        class Finding:
+            title: str = ""
+            description: str = ""
+            source_url: str = ""
+            source_type: str = ""
+            confidence: float = 0.5
+            raw_data: dict | None = None
+
+logger = logging.getLogger("watson.synthesis")
+
+_SYNTHESIS_PROMPT = """You are an intelligence analyst writing a due-diligence brief.
+
+TARGET: {query}
+TARGET TYPE: {target_type}
+FOCUS: {focus}
+
+You have gathered the following raw findings (sources already read). Synthesize
+them into a structured intelligence brief. Use ONLY information present in these
+findings — do NOT add outside knowledge or invent facts. If something is unclear
+or unverified, say so.
+
+{target_specific_guidance}
+
+FINDINGS:
+{findings}
+
+{resolved_entities}
+
+{cross_platform_correlation}
+
+Produce STRICT JSON (no markdown fences) with this shape:
+{{
+  "executive_summary": "2-3 sentence bottom line for a decision-maker",
+  "risk_themes": [
+    {{"theme": "Antitrust / Competition", "severity": "HIGH|MEDIUM|LOW",
+      "summary": "what the evidence shows", "source_titles": ["..."]}}
+  ],
+  "notable_entities": [
+    {{"name": "...", "role": "regulator|executive|company|court|cybercriminal", "context": "..."}}
+  ],
+  "timeline": [
+    {{"date": "YYYY or YYYY-MM or YYYY-MM-DD", "category": "career|criminal|legal|education|personal|financial",
+      "event": "what happened", "source_title": "which finding this came from"}}
+  ],
+  "evidence_gaps": ["what could not be verified or is missing"],
+  "recommended_next_steps": [
+    {{"entity": "the specific target (wallet, domain, name, IP, etc.) — NOT the full instruction",
+      "action": "what to do with it (trace, investigate, search, etc.)",
+      "tool_hint": "best tool category (blockchain, sanctions, corporate, domain, social, web)"}}
+  ]
+}}
+
+Rules:
+- 2-5 risk themes, ordered by severity.
+- severity reflects evidence strength + impact, not your opinion.
+- notable_entities: real orgs/people/regulators that appear in the findings.
+- TIMELINE: extract every date-backed event from findings. Birth dates, employment
+  start/end, arrests, convictions, sentencing, sanctions designations, company
+  founding, acquisitions, lawsuits filed/resolved. Use partial dates when exact
+  unknown (e.g., "2025" or "2025-07"). Order chronologically. Max 15 events.
+  Categories: career, criminal, legal, education, personal, financial.
+  NEVER invent dates — if a finding says "sentenced in 2023", use "2023", not a guess.
+- Be specific: name the regulator, the amount, the year when the finding states it.
+- If findings are thin, say so in executive_summary and keep themes minimal.
+- CRITICAL for recommended_next_steps: do NOT suggest steps that were ALREADY
+  executed. The tools listed below already ran — recommending them again is wrong.
+  Only suggest genuinely new follow-up vectors that haven't been tried.
+
+TOOLS ALREADY EXECUTED (do NOT re-recommend these):
+{executed_tools}
+"""
+
+_TARGET_GUIDANCE = {
+    "person": (
+        "PERSON INVESTIGATION GUIDANCE:\n"
+        "- The goal is to IDENTIFY this individual: who they are, what they do, their affiliations,\n"
+        "  professional background, and digital footprint.\n"
+        "- LinkedIn, ResearchGate, GitHub, Behance, Twitter profiles ARE substantive findings —\n"
+        "  they establish identity, career, and expertise. Do NOT dismiss these as 'not intelligence.'\n"
+        "- Social media profiles, professional pages, and news mentions are the PRIMARY deliverables\n"
+        "  for a person investigation — not a failure or thin result.\n"
+        "- Risk themes are OPTIONAL for persons. If no sanctions/criminal findings exist, that's\n"
+        "  NORMAL for most people. Don't fabricate risk themes to fill space.\n"
+        "- The executive summary should state WHO this person is (role, org, location) based on\n"
+        "  available findings, even if partial.\n"
+        "- ENTITY DISAMBIGUATION: If findings describe what appear to be MULTIPLE DIFFERENT PEOPLE\n"
+        "  sharing the same name (e.g., a wanted fugitive AND an academic researcher), you MUST\n"
+        "  flag this ambiguity. In notable_entities, list each distinct identity separately with\n"
+        "  'role' indicating what's known about EACH. Add a risk_theme with theme 'Entity Disambiguation'\n"
+        "  explaining whether these are likely the same person or different individuals. This is\n"
+        "  CRITICAL — conflating two people with the same name is a catastrophic intelligence failure."
+    ),
+    "email": (
+        "EMAIL INVESTIGATION GUIDANCE:\n"
+        "- Identify the person behind the email, their affiliations, breach history, and accounts.\n"
+        "- Breach data, social profiles, and username pivots are substantive findings."
+    ),
+    "domain": (
+        "DOMAIN INVESTIGATION GUIDANCE:\n"
+        "- Focus on infrastructure: WHOIS, DNS, TLS certs, subdomain enumeration, technologies.\n"
+        "- Identify the organization behind the domain and assess its legitimacy."
+    ),
+    "company": (
+        "COMPANY INVESTIGATION GUIDANCE:\n"
+        "- Focus on corporate structure, ownership, regulatory actions, sanctions, controversies.\n"
+        "- Executive leadership, subsidiaries, and legal risks are key.\n"
+        "- EMPLOYEE PIVOT FINDINGS: Findings prefixed with 👤 [Name] are key people detected\n"
+        "  during the investigation. Cross-reference them in risk themes and notable entities.\n"
+        "  If an executive has sanctions, lawsuits, or controversy findings, surface that in\n"
+        "  the executive summary — it's often the most actionable intelligence in the report.\n"
+        "- Risk themes should include 'Executive / Leadership Risk' when key people have\n"
+        "  adverse findings (lawsuits, sanctions, controversies)."
+    ),
+    "wallet": (
+        "WALLET INVESTIGATION GUIDANCE:\n"
+        "- Trace transactions, identify counterparties, check sanctions lists, and assess risk.\n"
+        "- Exchange interactions and token holdings are substantive."
+    ),
+}
+
+_PERSON_DEEP_GUIDANCE = (
+    "PERSON DEEP INVESTIGATION GUIDANCE:\n"
+    "- This is a CRIMINAL/LEGAL investigation. Look for: criminal charges, convictions, sentences,\n"
+    "  court cases, arrests, indictments, Interpol notices, sanctions (OFAC/UN/EU), asset freezes,\n"
+    "  travel bans, organized crime connections, cartel affiliations, prison records, wanted status.\n"
+    "- Wikipedia, sanctions databases, and crime/legal news articles ARE the primary evidence.\n"
+    "- Risk themes ARE expected — criminal/legal findings ARE the deliverable. Rank by severity.\n"
+    "- The executive summary should state who this person is, their criminal/legal status,\n"
+    "  and key charges/sanctions with dates and jurisdictions.\n"
+    "- If no criminal findings were found, state that clearly — do not fabricate."
+)
+
+_PERSON_DUE_DILIGENCE_GUIDANCE = (
+    "PERSON DUE DILIGENCE GUIDANCE:\n"
+    "- This is a PROFESSIONAL/BUSINESS investigation. Focus on: employment history, board positions,\n"
+    "  business affiliations, corporate connections, professional reputation.\n"
+    "- Also check for: lawsuits, regulatory actions, fines, penalties, adverse media,\n"
+    "  fraud allegations, ethics violations, professional misconduct.\n"
+    "- Risk themes may include regulatory risk, reputational risk, litigation risk.\n"
+    "- The executive summary should state who this person is professionally, their role,\n"
+    "  and any adverse findings that would concern a business partner or employer."
+)
+
+
+def _format_executed_tools(executed: set[tuple[str, str]] | None) -> str:
+    """Format executed tool+target pairs for injection into the synthesis prompt."""
+    if not executed:
+        return "(no tools were executed — this was a direct analysis)"
+    lines = []
+    for tool, target in sorted(executed):
+        lines.append(f"  • {tool}: {target[:120]}")
+    return "\n".join(lines) if lines else "(no tools executed)"
+
+
+def _format_resolved_entities(resolved: list | None) -> str:
+    """Format resolved entities for the synthesis prompt."""
+    if not resolved:
+        return ""
+    lines = ["RESOLVED ENTITIES (cross-referenced, deduplicated):"]
+    for e in resolved:
+        # ResolvedEntity is a dataclass — use getattr, not .get()
+        name = getattr(e, "canonical_name", None) or getattr(e, "canonical", str(e))
+        etype = getattr(e, "entity_type", None) or getattr(e, "etype", "unknown")
+        confidence = getattr(e, "confidence", 0)
+        src_count = getattr(e, "total_sources", None)
+        if src_count is None:
+            src_findings = getattr(e, "source_findings", None)
+            src_count = len(src_findings) if src_findings else len(getattr(e, "finding_ids", []))
+        aliases = getattr(e, "aliases", [])
+        lines.append(
+            f"  • {name} [{etype}] — confidence {confidence:.0%}, "
+            f"{src_count} sources"
+        )
+        if aliases:
+            lines.append(f"    aliases: {', '.join(list(aliases)[:5])}")
+    return "\n".join(lines)
+
+
+def _findings_block(findings, max_chars: int = 6000) -> str:
+    """Build a condensed findings block for the synthesis prompt. 
+    Caps at max_chars and prioritizes findings with source URLs."""
+    # Sort: findings with URLs first (higher quality), then by confidence
+    sorted_findings = sorted(
+        findings,
+        key=lambda f: (
+            not (getattr(f, "source_url", "") or ""),
+            -(getattr(f, "confidence", 0.5) or 0.5)
+        )
+    )
+    lines = []
+    total = 0
+    for i, f in enumerate(sorted_findings, 1):
+        title = getattr(f, "title", str(f)[:100]) or ""
+        desc = getattr(f, "description", "") or ""
+        desc = desc.replace("\n", " ").replace("**Extracted text", "").lstrip("(")
+        chunk = f"[{i}] {title}\n    {desc[:400]}\n"
+        if total + len(chunk) > max_chars:
+            break
+        lines.append(chunk)
+        total += len(chunk)
+    return "\n".join(lines)
+
+
+def _has_substantive_content(findings: list) -> bool:
+    """Check if findings contain more than social media noise.
+    
+    Returns True if findings include Wikipedia articles, FBI data, criminal/legal
+    content — anything the deterministic brief can't handle. Prevents the class of
+    bugs where "verified digital footprint with 2 professional profiles" is
+    reported for a mafia boss or convicted murderer.
+    """
+    substantive_keywords = [
+        "wikipedia", "fbi", "wanted", "convicted", "sanctions",
+        "sentenced", "arrested", "indictment", "mafia", "cartel",
+        "money laundering", "fraud ", "racketeering", "murder",
+        "assassination", "trafficking", "conspiracy", "wire fraud",
+        "life imprisonment", "organized crime", "bratva",
+        "opensanctions", "interpol", "bureau of investigation",
+        "justice department", "court records", "prison",
+    ]
+    for f in findings:
+        title = (getattr(f, "title", "") or "").lower()
+        desc = (getattr(f, "description", "") or "").lower()
+        combined = title + " " + desc
+        for kw in substantive_keywords:
+            if kw in combined:
+                return True
+    return False
+
+
+def _deterministic_person_brief(query: str, findings: list) -> dict:
+    """Build a person identity brief from findings WITHOUT an LLM.
+    
+    Extracts: name variants, professional profiles (LinkedIn, GitHub, etc.),
+    content mentions (articles, posts), and gaps. Never gaslights.
+    """
+    import re as _re
+    
+    profiles: list[dict] = []
+    mentions: list[dict] = []
+    name_variants = set()
+    
+    for f in findings:
+        title = getattr(f, "title", "") or ""
+        desc = getattr(f, "description", "") or ""
+        url = getattr(f, "source_url", "") or ""
+        combined = f"{title} {desc}"
+        
+        # Extract name variants — prioritize ones matching the query terms
+        query_parts = set(query.lower().split())
+        for match in _re.finditer(r'\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,3})\b', combined):
+            name = match.group(1)
+            name_parts = set(name.lower().split())
+            if name_parts & query_parts:
+                name_variants.add(name)
+        
+        # Detect professional profiles by URL pattern
+        if any(domain in url for domain in [
+            'linkedin.com/in/', 'linkedin.com/posts/', 
+            'github.com/', 'twitter.com/', 'x.com/',
+            'researchgate.net/profile/', 'behance.net/',
+        ]):
+            followers_match = _re.search(r'([\d,]+)\s*(?:followers|Posts)', combined)
+            profiles.append({
+                "url": url, "title": title[:120],
+                "followers": followers_match.group(1) if followers_match else None,
+            })
+        
+        # Detect content mentions by keyword
+        if any(kw in combined.lower() for kw in ['author', 'editor', 'analyst', 'journalist', 
+                                                    'founder', 'defense', 'tech', 'security']):
+            mentions.append({"url": url, "title": title[:120], "snippet": desc[:200] if desc else ""})
+    
+    # Determine best name: prefer longest variant matching all query words
+    name_str = query
+    if name_variants:
+        query_words = set(query.lower().split())
+        for v in sorted(name_variants, key=len, reverse=True):
+            if query_words.issubset(set(v.lower().split())):
+                name_str = v
+                break
+        else:
+            name_str = max(name_variants, key=len)
+    pc, mc = len(profiles), len(mentions)
+    
+    if pc >= 2:
+        sources = [p['url'].split('/')[2] for p in profiles[:3]]
+        topics = set()
+        for m in mentions:
+            for kw in ['defense', 'security', 'tech', 'startup', 'founder', 'editor', 'analyst']:
+                if kw in m['title'].lower() or kw in m['snippet'].lower():
+                    topics.add(kw)
+        summary = (f"{name_str} has a verified digital footprint with {pc} professional profiles "
+                   f"and {mc} content mentions. Sources: {', '.join(sources)}. "
+                   + (f"Topics: {', '.join(sorted(topics))}." if topics else ""))
+    elif pc == 1:
+        summary = (f"{name_str} has a limited digital footprint — one profile found. "
+                   f"{mc} content mentions. Further investigation recommended.")
+    else:
+        # Count actual unique URLs checked (not total findings — those include tool output noise)
+        urls_checked = len(set(
+            f.source_url for f in findings
+            if hasattr(f, 'source_url') and f.source_url
+        ))
+        sources_text = f"{urls_checked} sources checked" if urls_checked else "sources checked"
+        
+        # Detect location confusion — if findings look like business/geographic results
+        combined_text = " ".join(
+            (getattr(f, "title", "") + " " + getattr(f, "description", "")).lower()
+            for f in findings
+        )
+        location_keywords = ["comune", "municipality", "province", "via ", "p.iva",
+                             "impresa", "telefono", "orari", "cap ", "business directory"]
+        looks_like_location = any(kw in combined_text for kw in location_keywords)
+        
+        if looks_like_location:
+            summary = (f"No person found for '{name_str}'. "
+                       f"Results suggest this may be a geographic location or business name, "
+                       f"not an individual. {sources_text}. "
+                       f"Try re-running with a different query or check for name variants.")
+        else:
+            summary = (f"No professional profiles found for {name_str}. "
+                       f"{sources_text}. Possible private individual, pseudonym, or name collision.")
+    
+    return {
+        "executive_summary": summary[:500],
+        "risk_themes": [],
+        "notable_entities": [{"name": name_str, "role": "person", 
+                              "context": f"Profiles: {pc}, Mentions: {mc}"}],
+        "evidence_gaps": [g for g in [
+            "No verified employer or organization" if not any(
+                'company' in str(m).lower() or 'firm' in str(m).lower() for m in mentions
+            ) else None,
+            "Limited digital footprint — try alternative spellings" if pc < 2 else None,
+        ] if g],
+        "recommended_next_steps": (
+            [{"entity": p['url'], "action": "View profile", "tool_hint": "social"} for p in profiles[:3]]
+            + [{"entity": m['url'], "action": "Read article", "tool_hint": "web"} for m in mentions[:2]]
+        ),
+        "_synthesized": True, "_deterministic": True,
+    }
+
+async def synthesize_brief(
+    query: str,
+    focus: str,
+    findings: list,
+    call_llm,
+    target_type: str = "",
+    executed_tools: set[tuple[str, str]] | None = None,
+    resolved_entities: list | None = None,
+    investigation_mode: str = "",
+    graph_context: dict | None = None,
+    correlation: dict | None = None,
+) -> dict | None:
+    """Produce a structured intelligence brief from findings. Returns dict or None."""
+    # Filter out pure fetch-failures
+    real = []
+    for f in findings:
+        title = getattr(f, "title", "")
+        if not title.lower().startswith(("could not read",)):
+            real.append(f)
+    usable = real or findings
+    
+    if not usable:
+        return None
+
+    # ── Inject graph context into findings for cross-case intelligence ──
+    if graph_context and graph_context.get("known_entities"):
+        from ..core.models import Finding, FindingSeverity, FindingSource
+        known = graph_context["known_entities"]
+        cases = graph_context.get("relevant_cases", [])
+        for ent in known[:5]:
+            usable.append(Finding(
+                id=f"graph-{ent.get('id', ent.get('value', 'unknown'))[:20]}",
+                source=FindingSource.OSINT,
+                tool="knowledge_graph",
+                title=f"📊 [Graph] Known entity: {ent.get('value', '')[:120]}",
+                description=f"Previously found in case(s): {', '.join(cases[:3])}. "
+                            f"Type: {ent.get('type', 'unknown')}. "
+                            f"Confidence: PRIMARY (community graph — cross-case intelligence).",
+                evidence=[],
+                confidence=1.0,
+                severity=FindingSeverity.INFO,
+            ))
+
+    # Person targets: deterministic extraction for background_check and due_diligence.
+    # BUT: if findings contain Wikipedia, FBI, criminal, or legal content,
+    # the deterministic brief (which only knows LinkedIn/GitHub profiles) will
+    # produce garbage like "verified digital footprint with 2 professional profiles"
+    # for a mafia boss. Use LLM synthesis when there's substantive content.
+    if target_type == "person" and investigation_mode != "deep_investigation":
+        if not _has_substantive_content(usable):
+            return _deterministic_person_brief(query, usable)
+        # Criminal/legal content detected — fall through to LLM synthesis
+        logger.debug("synthesis: substantive content detected, using LLM for %s", query[:60])
+    
+    # Non-person targets: LLM synthesis
+
+    target_guidance = _TARGET_GUIDANCE.get(target_type, "") if target_type else ""
+    
+    # Deep investigation on persons: use criminal/legal guidance, not generic identity
+    if target_type == "person" and investigation_mode == "deep_investigation":
+        target_guidance = _PERSON_DEEP_GUIDANCE
+
+    prompt = _SYNTHESIS_PROMPT.format(
+        query=query,
+        target_type=target_type or "unknown",
+        focus=focus or "general due diligence",
+        target_specific_guidance=target_guidance,
+        findings=_findings_block(usable),
+        resolved_entities=_format_resolved_entities(resolved_entities),
+        cross_platform_correlation=_format_correlation(correlation),
+        executed_tools=_format_executed_tools(executed_tools),
+    )
+
+    try:
+        raw = await call_llm(prompt, timeout=180, max_tokens=4096)
+        if not raw or not raw.strip():
+            logger.info("synthesis: first LLM attempt empty, retrying with higher tokens")
+            raw = await call_llm(prompt, timeout=180, max_tokens=8192)
+        if not raw or not raw.strip():
+            logger.warning("synthesis: both LLM attempts returned empty — using fallback")
+            return _fallback_brief(query, usable)
+    except TypeError:
+        try:
+            raw = await call_llm(prompt, timeout=120, max_tokens=4096)
+        except TypeError:
+            raw = await call_llm(prompt, max_tokens=4096)
+    except Exception as e:
+        logger.warning("synthesis_llm_failed: %s", e)
+        raw = None
+
+    if not raw:
+        return _fallback_brief(query, usable)
+
+    brief = _parse_json(raw)
+    if not brief or "executive_summary" not in brief:
+        return _fallback_brief(query, usable)
+
+    brief["_synthesized"] = True
+    return brief
+
+
+def _parse_json(text: str) -> dict | None:
+    import re
+    text = (text or "").strip()
+    if text.startswith("```"):
+        text = re.sub(r"^```(?:json)?\s*", "", text)
+        text = re.sub(r"\s*```$", "", text)
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        m = re.search(r"\{.*\}", text, re.DOTALL)
+        if m:
+            try:
+                return json.loads(m.group(0))
+            except json.JSONDecodeError:
+                return None
+    return None
+
+
+def _fallback_brief(query: str, findings: list) -> dict:
+    """Deterministic structural brief when the LLM is unavailable.
+    Extracts real data from findings instead of just giving up."""
+    import re as _re
+    
+    sources = []
+    titles = []
+    entities_found: dict[str, list[str]] = {}  # type -> [values]
+    for f in findings:
+        url = getattr(f, "source_url", "") or (getattr(f, "raw_data", {}) or {}).get("url", "")
+        if not url:
+            m = _re.search(r"https?://\S+", f"{getattr(f, 'title', '')} {getattr(f, 'description', '')}")
+            if m:
+                url = m.group(0).rstrip(".,)")
+        if url and url not in sources:
+            sources.append(url)
+        title = getattr(f, "title", "")
+        if title and not title.lower().startswith(("check_", "could not read")):
+            titles.append(title[:150])
+        # Extract entity types from graph findings
+        ft = getattr(f, "finding_type", "") or ""
+        fval = getattr(f, "source_type", "") or ""
+        if ft in ("domain", "ip_address", "person", "organization", "email", "location"):
+            if ft not in entities_found:
+                entities_found[ft] = []
+            entities_found[ft].append(title[:80])
+        # Employee pivot findings carry embedded entities
+        for ent in getattr(f, "entities", []) or []:
+            ent_type = ent.get("type", "person") if isinstance(ent, dict) else "person"
+            ent_name = ent.get("name", title[:60]) if isinstance(ent, dict) else str(ent)
+            if ent_type not in entities_found:
+                entities_found[ent_type] = []
+            entities_found[ent_type].append(str(ent_name)[:80])
+    
+    # Build a real summary
+    confirmed = sum(1 for f in findings if getattr(f, "tier", "") == "CONFIRMED")
+    total = len(findings)
+    
+    # Extract meaningful content from findings
+    people = entities_found.get("person", [])
+    orgs = entities_found.get("organization", [])
+    domains = entities_found.get("domain", [])
+    locations = entities_found.get("location", [])
+    
+    parts = [f"Investigation of '{query}' gathered {total} findings ({confirmed} confirmed) from {len(sources)} verified sources."]
+    
+    if people:
+        parts.append(f"Key individuals: {', '.join(people[:3])}.")
+    if orgs:
+        parts.append(f"Connected organizations: {', '.join(orgs[:3])}.")
+    if domains:
+        parts.append(f"Infrastructure mapped: {len(domains)} domains, {len(entities_found.get('ip_address', []))} IPs across {len(locations)} locations.")
+    
+    # If no entities found, use titles
+    if not any([people, orgs, domains]):
+        top = [t for t in titles[:5] if not t.startswith("🔗")]
+        if top:
+            parts.append("Notable findings: " + "; ".join(top[:3]) + ".")
+    
+    # Detect themes from finding content (more thorough)
+    theme_keywords = {
+        "Regulatory / Legal": ["sanction", "fine", "settlement", "regulator", "sec", "cftc", "doj",
+                                "lawsuit", "indictment", "charged", "plead guilty", "convicted",
+                                "class action", "arbitration", "court", "ruling", "securities"],
+        "Corporate / Leadership": ["ceo", "founder", "executive", "board", "chairman", "director",
+                                    "resigned", "appointed", "named", "co-founder"],
+        "Financial": ["revenue", "profit", "loss", "billion", "million", "funding", "valuation",
+                      "stock", "share", "investor", "ipo", "acquisition"],
+        "Crime / Investigation": ["criminal", "arrest", "prison", "jail", "fraud", "money laundering",
+                                   "investigation", "probe", "allegation", "misconduct"],
+        "Infrastructure / Technical": ["dns", "ip address", "nameserver", "hosting", "cdn",
+                                        "subdomain", "resolves_to", "mx record"],
+    }
+    themes = []
+    all_text = " ".join(titles + [getattr(f, "description", "") or "" for f in findings]).lower()
+    for theme, keywords in theme_keywords.items():
+        matches = [kw for kw in keywords if kw in all_text]
+        if matches:
+            # Extract a relevant finding snippet
+            for f in findings:
+                desc = (getattr(f, "description", "") or "").lower()
+                title_l = (getattr(f, "title", "") or "").lower()
+                for kw in matches:
+                    if kw in title_l or kw in desc:
+                        themes.append({
+                            "theme": theme,
+                            "severity": "HIGH" if theme.startswith("Crime") else "MEDIUM",
+                            "summary": getattr(f, "title", "")[:200] or f"Evidence of {kw} found",
+                            "source_titles": [getattr(f, "title", "")[:100]],
+                        })
+                        break
+                if any(t["theme"] == theme for t in themes):
+                    break
+            else:
+                themes.append({
+                    "theme": theme,
+                    "severity": "MEDIUM",
+                    "summary": f"Keywords detected: {', '.join(matches[:4])}",
+                    "source_titles": [],
+                })
+    
+    # Extract timeline events from findings (dates in titles/descriptions)
+    timeline_events: list[dict] = []
+    date_pattern = _re.compile(
+        r'\b((?:19|20)\d{2}(?:-(?:0[1-9]|1[0-2])(?:-(?:0[1-9]|[12]\d|3[01]))?)?)\b'
+    )
+    seen_dates: set[str] = set()
+    for f in findings:
+        title = getattr(f, "title", "") or ""
+        desc = getattr(f, "description", "") or ""
+        combined = f"{title} {desc}"
+        for m in date_pattern.finditer(combined):
+            d = m.group(1)
+            if d in seen_dates or len(d) < 4:
+                continue
+            seen_dates.add(d)
+            # Categorize
+            cat = "personal"
+            lower = combined.lower()
+            if any(kw in lower for kw in ("sentenced", "convicted", "arrested", "charged", "murder", "prison")):
+                cat = "criminal"
+            elif any(kw in lower for kw in ("lawsuit", "court", "trial", "ruling", "indictment")):
+                cat = "legal"
+            elif any(kw in lower for kw in ("ceo", "founder", "joined", "hired", "appointed", "director", "board")):
+                cat = "career"
+            elif any(kw in lower for kw in ("graduated", "university", "degree", "phd", "bachelor", "master")):
+                cat = "education"
+            elif any(kw in lower for kw in ("revenue", "funding", "ipo", "acquired", "valuation", "million", "billion")):
+                cat = "financial"
+            snippet = (title or desc)[:120]
+            timeline_events.append({
+                "date": d, "category": cat, "event": snippet,
+                "source_title": title[:100] if title else "",
+            })
+    timeline_events.sort(key=lambda e: e["date"])
+
+    return {
+        "executive_summary": " ".join(parts),
+        "risk_themes": themes if themes else [],
+        "notable_entities": [
+            {"name": v[0][:80], "type": k, "role": "discovered", "confidence": 0.7}
+            for k, vals in entities_found.items() for v in vals[:1]
+        ],
+        "timeline": timeline_events[:15],
+        "evidence_gaps": [],
+        "recommended_next_steps": [{"entity": u, "action": "Review source", "tool_hint": "web"}
+                                   for u in sources[:5]],
+        "_synthesized": False,
+        "_sources": sources[:15],
+    }
+
+
+def _format_correlation(correlation: dict | None) -> str:
+    """Format cross-platform identity correlation for the synthesis prompt."""
+    if not correlation or not correlation.get("total_matches"):
+        return ""
+    lines = ["CROSS-PLATFORM IDENTITY CORRELATION:"]
+    lines.append(correlation.get("summary", ""))
+    confirmed = correlation.get("confirmed", [])
+    if confirmed:
+        lines.append("\nConfirmed matches (confidence ≥ 0.9):")
+        for m in confirmed[:3]:
+            lines.append(f"  • {m['finding_a'][:60]} ↔ {m['finding_b'][:60]}")
+            lines.append(f"    Signals: {', '.join(m['signals'])} | Confidence: {m['confidence']}")
+    probable = correlation.get("probable", [])
+    if probable:
+        lines.append("\nProbable matches (confidence ≥ 0.7):")
+        for m in probable[:3]:
+            lines.append(f"  • {m['finding_a'][:60]} ↔ {m['finding_b'][:60]}")
+    return "\n".join(lines)
+
+
+def brief_to_markdown(brief: dict, query: str) -> str:
+    """Render a brief dict as a readable markdown report."""
+    out = [f"# Intelligence Brief: {query}", ""]
+    out.append(f"**Bottom line:** {brief.get('executive_summary', 'N/A')}")
+    out.append("")
+
+    themes = brief.get("risk_themes", [])
+    if themes:
+        out.append("## Risk Themes")
+        for t in themes:
+            sev = t.get("severity", "?")
+            badge = {"HIGH": "🔴", "MEDIUM": "🟠", "LOW": "🟡"}.get(sev, "⚪")
+            out.append(f"### {badge} {t.get('theme', 'Theme')} — {sev}")
+            out.append(t.get("summary", ""))
+            srcs = t.get("source_titles", [])
+            if srcs:
+                out.append("Sources: " + "; ".join(srcs[:4]))
+            out.append("")
+
+    ents = brief.get("notable_entities", [])
+    if ents:
+        out.append("## Notable Entities")
+        for e in ents:
+            out.append(f"- **{e.get('name','?')}** ({e.get('role','?')}): {e.get('context','')}")
+        out.append("")
+
+    timeline = brief.get("timeline", [])
+    if timeline:
+        out.append("## Timeline")
+        cat_icons = {
+            "criminal": "🔴", "legal": "⚖️", "career": "💼",
+            "education": "🎓", "personal": "👤", "financial": "💰",
+        }
+        for event in timeline:
+            icon = cat_icons.get(event.get("category", ""), "📌")
+            date = event.get("date", "?")
+            evt = event.get("event", "")
+            src = event.get("source_title", "")
+            out.append(f"- {icon} **{date}** — {evt}")
+            if src:
+                out.append(f"  *Source: {src[:120]}*")
+        out.append("")
+
+    gaps = brief.get("evidence_gaps", [])
+    if gaps:
+        out.append("## Evidence Gaps")
+        for g in gaps:
+            out.append(f"- 🔍 {g}")
+        out.append("")
+
+    nxt = brief.get("recommended_next_steps", [])
+    if nxt:
+        out.append("## Recommended Next Steps")
+        for n in nxt:
+            if isinstance(n, dict):
+                out.append(f"- **{n.get('entity','?')}**: {n.get('action','?')} [{n.get('tool_hint','?')}]")
+            else:
+                out.append(f"- {n}")
+        out.append("")
+
+    return "\n".join(out)