briefloop 0.11.12__py3-none-any.whl

multi_agent_brief/analysis_modules/market_competitor/event_builder.py

@@ -0,0 +1,226 @@
+"""Event Builder — deterministically merge entity-tagged Claims into MarketEvents.
+
+Reads the screened ClaimLedger, groups claims by entity_id + event_type +
+dimension, and produces MarketEvent objects for the renderer.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from multi_agent_brief.analysis_modules.market_competitor.schemas import (
+    CompetitorUniverse,
+    MarketEvent,
+    Materiality,
+    Confidence,
+    Dimension,
+    EventType,
+    EventStatus,
+    ChangeStatus,
+)
+from multi_agent_brief.core.claim_ledger import ClaimLedger
+from multi_agent_brief.core.schemas import Claim
+
+
+def build_events(
+    ledger: ClaimLedger,
+    universe: CompetitorUniverse,
+    *,
+    state_dir: str | None = None,
+) -> list[MarketEvent]:
+    """Build MarketEvents from entity-tagged Claim Ledger entries.
+
+    Only claims with ``metadata.entity_ids`` are considered.  Claims sharing
+    the same (entity_id, event_type, dimension) are merged into a single
+    MarketEvent.
+
+    If ``state_dir`` is provided, compares current events against the previous
+    period's event history and marks each event's ``change_status``.
+    """
+    # Group claims by composite key
+    groups: dict[str, list[Claim]] = {}
+    for claim in ledger:
+        entity_ids = claim.metadata.get("entity_ids")
+        if not entity_ids:
+            continue
+        if not isinstance(entity_ids, list) or len(entity_ids) == 0:
+            continue
+
+        event_type = claim.metadata.get("event_type", "other")
+        dimension = claim.metadata.get("dimension", "other")
+
+        for eid in entity_ids:
+            key = f"{eid}|{event_type}|{dimension}"
+            groups.setdefault(key, []).append(claim)
+
+    events: list[MarketEvent] = []
+    idx = 0
+    for key, claims in groups.items():
+        eid, etype, dim = key.split("|", 2)
+
+        # Determine status from claim metadata
+        status: EventStatus = _pick_status(claims)
+        # Geography from first claim that has one
+        geo = ""
+        for c in claims:
+            g = c.metadata.get("geography", "")
+            if g:
+                geo = g
+                break
+
+        # Best event date
+        event_date = ""
+        for c in claims:
+            d = c.metadata.get("published_at") or c.metadata.get("retrieved_at", "")
+            if d:
+                event_date = d
+                break
+
+        # Summary: first claim's statement
+        summary = claims[0].statement if claims else ""
+
+        # Supporting claim IDs
+        supporting = [c.claim_id for c in claims]
+
+        # Confidence: high if ≥2 sources, else medium
+        confidence: Confidence = "high" if len(claims) >= 2 else "medium"
+
+        # Materiality: high if any event in priority dimensions
+        materiality: Materiality = "high" if dim in ("capacity", "technology", "financials") else "medium"
+
+        idx += 1
+        event_id = f"EVT_{eid}_{etype}_{dim}_{idx:03d}"
+
+        events.append(MarketEvent(
+            event_id=event_id,
+            entity_ids=[eid],
+            event_type=etype,  # type: ignore[arg-type]
+            dimension=dim,  # type: ignore[arg-type]
+            status=status,
+            geography=geo,
+            event_date=event_date,
+            summary=summary[:200],
+            supporting_claim_ids=supporting,
+            source_count=len(supporting),
+            confidence=confidence,
+            materiality=materiality,
+        ))
+
+    # Cross-period comparison
+    if state_dir:
+        history_path = Path(state_dir) / "market_competitor" / "event_history.jsonl"
+        prev = _load_history(history_path)
+        events = _compare_events(events, prev)
+        _save_history(events, history_path)
+
+    return events
+
+
+def _pick_status(claims: list[Claim]) -> EventStatus:
+    """Infer event status from claim text."""
+    text = " ".join(c.statement.lower() + " " + c.evidence_text.lower() for c in claims)
+    if any(w in text for w in ("cancelled", "canceled", "terminated", "scrapped")):
+        return "cancelled"
+    if any(w in text for w in ("delayed", "pushed back", "postponed")):
+        return "delayed"
+    if any(w in text for w in ("operational", "producing", "production started")):
+        return "operational"
+    if any(w in text for w in ("commissioning", "testing", "ramping up")):
+        return "commissioning"
+    if any(w in text for w in ("under construction", "building", "groundbreaking")):
+        return "under_construction"
+    if any(w in text for w in ("planned", "planning", "proposed")):
+        return "planned"
+    if any(w in text for w in ("announced", "revealed", "unveiled", "disclosed")):
+        return "announced"
+    if any(w in text for w in ("rumored", "speculated", "reportedly considering")):
+        return "rumored"
+    return ""
+
+
+# ── History tracking ────────────────────────────────────────────────────────
+
+def _event_match_key(ev: MarketEvent) -> str:
+    """Composite key for matching events across periods.
+
+    Uses entity_id + event_type + dimension — status changes are still the
+    same event, just progressed.
+    """
+    eid = ev.entity_ids[0] if ev.entity_ids else ""
+    return f"{eid}|{ev.event_type}|{ev.dimension}"
+
+
+def _load_history(history_path: Path) -> dict[str, dict[str, Any]]:
+    """Load previous period's event history. Returns empty dict if no history."""
+    if not history_path.exists():
+        return {}
+    prev: dict[str, dict[str, Any]] = {}
+    try:
+        with open(history_path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                rec = json.loads(line)
+                key = _event_match_key(MarketEvent(**rec))
+                # Keep the latest record for each key
+                prev[key] = rec
+    except (json.JSONDecodeError, TypeError):
+        pass
+    return prev
+
+
+def _compare_events(
+    current: list[MarketEvent],
+    previous: dict[str, dict[str, Any]],
+) -> list[MarketEvent]:
+    """Compare current events against history, mark change_status."""
+    for ev in current:
+        key = _event_match_key(ev)
+        if key not in previous:
+            ev.change_status = "new"
+            continue
+
+        prev_status = previous[key].get("status", "")
+        if ev.status == prev_status:
+            ev.change_status = "unchanged"
+        elif ev.status == "":
+            ev.change_status = "unchanged"
+        elif prev_status == "cancelled":
+            ev.change_status = "new"  # re-emerged after cancellation
+        elif ev.status == "cancelled":
+            ev.change_status = "cancelled"
+        else:
+            ev.change_status = "changed"
+
+    # Mark previous events not seen in current period as resolved/cancelled
+    current_keys = {_event_match_key(ev) for ev in current}
+    for key, rec in previous.items():
+        if key not in current_keys and rec.get("status") != "cancelled":
+            eid = rec.get("entity_ids", [""])[0]
+            current.append(MarketEvent(
+                event_id=f"EVT_{eid}_resolved_{len(current)+1:03d}",
+                entity_ids=rec.get("entity_ids", []),
+                event_type=rec.get("event_type", "other"),
+                dimension=rec.get("dimension", "other"),
+                status=rec.get("status", ""),
+                geography=rec.get("geography", ""),
+                event_date=rec.get("event_date", ""),
+                summary=rec.get("summary", ""),
+                supporting_claim_ids=rec.get("supporting_claim_ids", []),
+                source_count=rec.get("source_count", 0),
+                confidence=rec.get("confidence", "medium"),
+                materiality="low",
+                change_status="resolved",
+            ))
+
+    return current
+
+
+def _save_history(events: list[MarketEvent], history_path: Path) -> None:
+    """Append all current events to history file."""
+    history_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(history_path, "a", encoding="utf-8") as f:
+        for ev in events:
+            f.write(json.dumps(ev.to_dict(), ensure_ascii=False) + "\n")

multi_agent_brief/analysis_modules/market_competitor/renderer.py

@@ -0,0 +1,199 @@
+"""Renderer — write market_competitor intermediate artifacts to disk."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from multi_agent_brief.analysis_modules.market_competitor.schemas import (
+    CompetitorEntity,
+    CompetitorMatrix,
+    CompetitorMatrixCell,
+    CompetitorUniverse,
+    CoverageReport,
+    Dimension,
+    MarketEvent,
+    Watchlist,
+    WatchlistItem,
+)
+from multi_agent_brief.core.claim_ledger import ClaimLedger
+from multi_agent_brief.core.schemas import Claim, utc_now_iso
+
+
+def _write_json(path: Path, data: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(data, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+
+def render_events_json(events: list[MarketEvent], output_dir: Path) -> Path:
+    """Write events.json."""
+    p = output_dir / "intermediate" / "market_competitor" / "events.json"
+    _write_json(p, {
+        "events": [ev.to_dict() for ev in events],
+        "count": len(events),
+        "generated_at": utc_now_iso(),
+    })
+    return p
+
+
+def render_competitor_matrix(
+    events: list[MarketEvent],
+    universe: CompetitorUniverse,
+    output_dir: Path,
+) -> Path:
+    """Write competitor_matrix.json — entity × dimension comparison table."""
+    entities = [universe.target] + universe.entities
+    entity_ids = [e.entity_id for e in entities if e.entity_id]
+    entity_names = {e.entity_id: e.name for e in entities}
+
+    dimensions: list[Dimension] = [
+        "capacity", "technology", "customers_partnerships",
+        "financials", "policy_compliance", "market_demand",
+    ]
+
+    cells: list[CompetitorMatrixCell] = []
+    for eid in entity_ids:
+        for dim in dimensions:
+            # Find events for this entity × dimension
+            cell_events = [
+                ev for ev in events
+                if eid in ev.entity_ids and ev.dimension == dim
+            ]
+            if not cell_events:
+                continue
+
+            claim_ids: list[str] = []
+            summaries: list[str] = []
+            for ev in cell_events:
+                claim_ids.extend(ev.supporting_claim_ids)
+                if ev.summary:
+                    summaries.append(ev.summary)
+
+            cells.append(CompetitorMatrixCell(
+                entity_id=eid,
+                dimension=dim,
+                summary="; ".join(summaries[:3]),
+                evidence_claim_ids=claim_ids[:10],
+                status=cell_events[0].status if cell_events else "",
+            ))
+
+    matrix = CompetitorMatrix(
+        entities=[entity_names.get(eid, eid) for eid in entity_ids],
+        dimensions=dimensions,
+        cells=cells,
+        report_date=utc_now_iso(),
+    )
+
+    p = output_dir / "intermediate" / "market_competitor" / "competitor_matrix.json"
+    _write_json(p, matrix.to_dict())
+    return p
+
+
+def render_coverage_report(
+    events: list[MarketEvent],
+    universe: CompetitorUniverse,
+    output_dir: Path,
+) -> Path:
+    """Write coverage_report.json."""
+    primary_ids = [e.entity_id for e in universe.primary_competitors]
+    primary_total = len(primary_ids)
+
+    entities_with_evidence: set[str] = set()
+    dimensions_seen: set[str] = set()
+    for ev in events:
+        for eid in ev.entity_ids:
+            entities_with_evidence.add(eid)
+        if ev.dimension:
+            dimensions_seen.add(ev.dimension)
+
+    missing = [eid for eid in primary_ids if eid not in entities_with_evidence]
+
+    # absence_of_evidence: entities present in history but with no NEW events
+    # resolved events (change_status=resolved, materiality=low) count as absence
+    resolved_entities = {
+        eid for ev in events
+        if ev.change_status == "resolved"
+        for eid in ev.entity_ids
+    }
+
+    all_dims: list[Dimension] = [
+        "capacity", "technology", "customers_partnerships",
+        "financials", "policy_compliance", "market_demand",
+    ]
+    undercovered = [d for d in all_dims if d not in dimensions_seen]
+
+    report = CoverageReport(
+        primary_competitors_total=primary_total,
+        primary_competitors_with_recent_evidence=(
+            primary_total - len(missing)
+        ),
+        missing_entities=missing,
+        undercovered_dimensions=undercovered,
+        absence_of_evidence_entities=sorted(resolved_entities),
+        generated_at=utc_now_iso(),
+    )
+
+    p = output_dir / "intermediate" / "market_competitor" / "coverage_report.json"
+    _write_json(p, report.to_dict())
+    return p
+
+
+def render_watchlist(output_dir: Path) -> Path:
+    """Write watchlist.json — empty template (cross-period tracking in PR #6)."""
+    wl = Watchlist(generated_at=utc_now_iso())
+    p = output_dir / "intermediate" / "market_competitor" / "watchlist.json"
+    _write_json(p, wl.to_dict())
+    return p
+
+
+def render_evidence_pack(
+    events: list[MarketEvent],
+    ledger: ClaimLedger,
+    output_dir: Path,
+) -> Path:
+    """Write evidence_pack.json — all structured evidence for LLM subagent consumption."""
+    claim_index: dict[str, Any] = {}
+    for claim in ledger:
+        claim_index[claim.claim_id] = {
+            "claim_id": claim.claim_id,
+            "statement": claim.statement,
+            "evidence_text": claim.evidence_text,
+            "source_url": claim.source_url,
+            "source_type": claim.source_type,
+            "metadata": claim.metadata,
+        }
+
+    event_pack: list[dict[str, Any]] = []
+    for ev in events:
+        evidence = [claim_index.get(cid) for cid in ev.supporting_claim_ids if cid in claim_index]
+        event_pack.append({
+            **ev.to_dict(),
+            "claims": evidence,
+        })
+
+    p = output_dir / "intermediate" / "market_competitor" / "evidence_pack.json"
+    _write_json(p, {
+        "events": event_pack,
+        "event_count": len(event_pack),
+        "generated_at": utc_now_iso(),
+    })
+    return p
+
+
+def render_all(
+    events: list[MarketEvent],
+    ledger: ClaimLedger,
+    universe: CompetitorUniverse,
+    output_dir: Path,
+) -> dict[str, str]:
+    """Write all 5 intermediate artifacts. Returns path map."""
+    return {
+        "events": str(render_events_json(events, output_dir)),
+        "competitor_matrix": str(render_competitor_matrix(events, universe, output_dir)),
+        "coverage_report": str(render_coverage_report(events, universe, output_dir)),
+        "watchlist": str(render_watchlist(output_dir)),
+        "evidence_pack": str(render_evidence_pack(events, ledger, output_dir)),
+    }