briefloop 0.11.12__py3-none-any.whl

multi_agent_brief/analysis_modules/market_competitor/auditor.py

@@ -0,0 +1,290 @@
+"""Market & Competitor specialist audits.
+
+Implements AuditAgentInterface — plugs into CompositeAuditAgent when the
+market_competitor module is enabled.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from multi_agent_brief.audit.interfaces import AuditAgentInterface
+from multi_agent_brief.core.claim_ledger import ClaimLedger
+from multi_agent_brief.core.schemas import AuditFinding, AuditReport, PipelineContext
+
+
+class MarketCompetitorAuditor(AuditAgentInterface):
+    """6 specialist audit checks for market & competitor analysis quality."""
+
+    name = "market-competitor-auditor"
+
+    def run_audit(
+        self,
+        markdown: str,
+        ledger: ClaimLedger,
+        context: PipelineContext | None = None,
+    ) -> AuditReport:
+        findings: list[AuditFinding] = []
+        idx = 0
+
+        # Load analysis_cards.json if available
+        analysis_cards = self._load_analysis_cards(context)
+        events_data = self._load_events(context)
+
+        # 1 — comparison_missing_entity_evidence
+        idx, findings = _check_comparison_evidence(
+            analysis_cards, ledger, idx, findings,
+        )
+
+        # 2 — capacity_status_missing
+        idx, findings = _check_capacity_status(events_data, idx, findings)
+
+        # 3 — metric_basis_missing
+        idx, findings = _check_metric_basis(analysis_cards, ledger, idx, findings)
+
+        # 4 — unsupported_market_trend
+        idx, findings = _check_market_trend(analysis_cards, idx, findings)
+
+        # 5 — single_source_interpretation
+        idx, findings = _check_single_source(analysis_cards, idx, findings)
+
+        # 6 — competitor_coverage_gap
+        idx, findings = _check_coverage_gap(context, idx, findings)
+
+        return AuditReport(
+            audit_status="pass",
+            audit_score=100,
+            findings=findings,
+            metadata={"module": "market_competitor", "check_count": idx},
+        )
+
+    def _load_analysis_cards(self, context: PipelineContext | None) -> list[dict[str, Any]]:
+        if not context:
+            return []
+        output_dir = context.output_dir
+        path = Path(output_dir) / "intermediate" / "market_competitor" / "analysis_cards.json"
+        if path.exists():
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+                return data.get("cards", data.get("analysis_cards", []))
+            except (json.JSONDecodeError, TypeError):
+                return []
+        return []
+
+    def _load_events(self, context: PipelineContext | None) -> list[dict[str, Any]]:
+        if not context:
+            return []
+        output_dir = context.output_dir
+        path = Path(output_dir) / "intermediate" / "market_competitor" / "events.json"
+        if path.exists():
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+                return data.get("events", [])
+            except (json.JSONDecodeError, TypeError):
+                return []
+        return []
+
+
+# ── Audit checks ────────────────────────────────────────────────────────────
+
+def _check_comparison_evidence(
+    cards: list[dict[str, Any]],
+    ledger: ClaimLedger,
+    idx: int,
+    findings: list[AuditFinding],
+) -> tuple[int, list[AuditFinding]]:
+    """Comparison findings require evidence for each entity cited."""
+    comp_keywords = ("relative_position", "comparison", "gap", "narrowing", "widening",
+                     "closing", "wider than", "narrower than", "vs", "versus", "领先",
+                     "落后", "差距", "缩小", "扩大")
+    for card in cards:
+        headline = (card.get("headline") or "").lower()
+        observation = (card.get("observation") or "").lower()
+        text = headline + " " + observation
+        if not any(kw in text for kw in comp_keywords):
+            continue
+
+        claim_ids = card.get("supporting_claim_ids", [])
+        entities_with_evidence: set[str] = set()
+        for cid in claim_ids:
+            claim = ledger.get_claim(cid)
+            if claim:
+                for eid in claim.metadata.get("entity_ids", []):
+                    entities_with_evidence.add(eid)
+
+        if len(entities_with_evidence) < 2:
+            idx += 1
+            findings.append(AuditFinding(
+                finding_id=f"MC_COMP_{idx:03d}",
+                severity="high",
+                finding_type="comparison_missing_entity_evidence",
+                description=(
+                    f"Analysis comparison in card '{card.get('analysis_id', '?')}' "
+                    f"references entities but only has evidence for "
+                    f"{len(entities_with_evidence)} side(s)."
+                ),
+                recommendation="Each entity in a comparison must have its own supporting claim.",
+            ))
+    return idx, findings
+
+
+def _check_capacity_status(
+    events: list[dict[str, Any]],
+    idx: int,
+    findings: list[AuditFinding],
+) -> tuple[int, list[AuditFinding]]:
+    """Capacity events must have a status (announced/under_construction/etc)."""
+    for ev in events:
+        if ev.get("event_type") not in ("capacity_expansion", "capacity_delay",
+                                         "plant_opening", "plant_closure"):
+            continue
+        if not ev.get("status"):
+            idx += 1
+            findings.append(AuditFinding(
+                finding_id=f"MC_CAP_{idx:03d}",
+                severity="medium",
+                finding_type="capacity_status_missing",
+                description=(
+                    f"Capacity event '{ev.get('event_id', '?')}' has no status. "
+                    f"Announced capacity must be distinguished from operational capacity."
+                ),
+                recommendation="Set event status to announced/under_construction/operational/etc.",
+            ))
+    return idx, findings
+
+
+def _check_metric_basis(
+    cards: list[dict[str, Any]],
+    ledger: ClaimLedger,
+    idx: int,
+    findings: list[AuditFinding],
+) -> tuple[int, list[AuditFinding]]:
+    """Numbers in analysis cards must have period + unit in supporting claims."""
+    import re
+    num_pat = re.compile(r"\b\d+(?:\.\d+)?\s*(?:%|GW|MW|GWh|billion|million|元|美元)")
+    for card in cards:
+        text = " ".join(str(v) for v in [
+            card.get("headline", ""), card.get("observation", ""),
+            card.get("implication_for_target", ""),
+        ])
+        numbers = num_pat.findall(text)
+        if not numbers:
+            continue
+
+        claim_ids = card.get("supporting_claim_ids", [])
+        for cid in claim_ids:
+            claim = ledger.get_claim(cid)
+            if not claim:
+                continue
+            evidence = (claim.evidence_text or "").lower()
+            has_unit = any(u in evidence for u in ("gw", "mw", "gwh", "mwh", "billion",
+                                                    "million", "percent", "%", "元", "美元"))
+            has_period = any(p in evidence for p in ("q1", "q2", "q3", "q4", "fy", "fiscal",
+                                                      "annual", "quarterly", "h1", "h2",
+                                                      "年", "季度", "上半年", "下半年"))
+            if not has_unit or not has_period:
+                idx += 1
+                findings.append(AuditFinding(
+                    finding_id=f"MC_METRIC_{idx:03d}",
+                    severity="medium",
+                    finding_type="metric_basis_missing",
+                    description=(
+                        f"Analysis card '{card.get('analysis_id', '?')}' contains "
+                        f"numeric values but claim '{cid}' lacks period and/or unit."
+                    ),
+                    recommendation="Ensure supporting claims include time period and measurement unit.",
+                ))
+    return idx, findings
+
+
+def _check_market_trend(
+    cards: list[dict[str, Any]],
+    idx: int,
+    findings: list[AuditFinding],
+) -> tuple[int, list[AuditFinding]]:
+    """Market trend claims need at least 2 supporting claims."""
+    trend_keywords = ("trend", "shifting", "momentum", "trajectory", "outlook",
+                      "趋势", "势头", "走向", "前景", "market shift")
+    for card in cards:
+        headline = (card.get("headline") or "").lower()
+        observation = (card.get("observation") or "").lower()
+        text = headline + " " + observation
+        if not any(kw in text for kw in trend_keywords):
+            continue
+
+        claim_ids = card.get("supporting_claim_ids", [])
+        if len(claim_ids) < 2:
+            idx += 1
+            findings.append(AuditFinding(
+                finding_id=f"MC_TREND_{idx:03d}",
+                severity="high",
+                finding_type="unsupported_market_trend",
+                description=(
+                    f"Analysis card '{card.get('analysis_id', '?')}' makes a market "
+                    f"trend claim with only {len(claim_ids)} supporting claim(s). "
+                    f"Trend claims need at least 2."
+                ),
+                recommendation="Add more supporting evidence or weaken the claim language.",
+            ))
+    return idx, findings
+
+
+def _check_single_source(
+    cards: list[dict[str, Any]],
+    idx: int,
+    findings: list[AuditFinding],
+) -> tuple[int, list[AuditFinding]]:
+    """Single-source interpretations must have confidence=low."""
+    for card in cards:
+        claim_ids = card.get("supporting_claim_ids", [])
+        if len(claim_ids) == 1 and card.get("confidence", "medium") != "low":
+            # Only flag analytical cards, not fact-type
+            if card.get("finding_type", "fact") != "fact":
+                idx += 1
+                findings.append(AuditFinding(
+                    finding_id=f"MC_SINGLE_{idx:03d}",
+                    severity="medium",
+                    finding_type="single_source_interpretation",
+                    description=(
+                        f"Analysis card '{card.get('analysis_id', '?')}' has only 1 "
+                        f"supporting claim but confidence is '{card.get('confidence', '?')}'. "
+                        f"Single-source interpretations must set confidence='low'."
+                    ),
+                    recommendation="Set confidence='low' or add more supporting claims.",
+                ))
+    return idx, findings
+
+
+def _check_coverage_gap(
+    context: PipelineContext | None,
+    idx: int,
+    findings: list[AuditFinding],
+) -> tuple[int, list[AuditFinding]]:
+    """Primary competitors must have coverage."""
+    if not context:
+        return idx, findings
+    output_dir = context.output_dir
+    path = Path(output_dir) / "intermediate" / "market_competitor" / "coverage_report.json"
+    if not path.exists():
+        return idx, findings
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, TypeError):
+        return idx, findings
+
+    missing = data.get("missing_entities", [])
+    primary_total = data.get("primary_competitors_total", 0)
+    if missing and primary_total > 0:
+        idx += 1
+        findings.append(AuditFinding(
+            finding_id=f"MC_COV_{idx:03d}",
+            severity="high" if primary_total - len(missing) < primary_total / 2 else "medium",
+            finding_type="competitor_coverage_gap",
+            description=(
+                f"Coverage gap: {len(missing)} of {primary_total} primary competitors "
+                f"have no recent evidence ({', '.join(missing)})."
+            ),
+            recommendation="Expand search scope or mark quiet-week exception.",
+        ))
+    return idx, findings

multi_agent_brief/analysis_modules/market_competitor/config.py

@@ -0,0 +1,187 @@
+"""Load, save, and merge competitor_universe.yaml and competitor_candidates.yaml."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ModuleNotFoundError:
+    yaml = None  # type: ignore[assignment]
+
+from multi_agent_brief.analysis_modules.market_competitor.schemas import CompetitorEntity, CompetitorUniverse
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    if yaml is None:
+        raise RuntimeError("PyYAML is required: pip install pyyaml")
+    if not path.exists():
+        return {}
+    with open(path, encoding="utf-8") as f:
+        return yaml.safe_load(f) or {}
+
+
+def _save_yaml(path: Path, data: dict[str, Any]) -> None:
+    if yaml is None:
+        raise RuntimeError("PyYAML is required: pip install pyyaml")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        yaml.dump(data, f, allow_unicode=True, default_flow_style=False, sort_keys=False)
+
+
+def load_competitor_universe(path: str | Path) -> CompetitorUniverse:
+    """Load a CompetitorUniverse from a YAML file.
+
+    Returns a valid (possibly empty) CompetitorUniverse even when the file
+    does not exist — the caller checks ``universe.enabled`` and
+    ``universe.entities`` to decide whether to activate.
+    """
+    p = Path(path)
+    data = _load_yaml(p)
+    if not data:
+        return CompetitorUniverse(
+            target=CompetitorEntity(entity_id="", name=""),
+            enabled=False,
+        )
+
+    target_data = data.get("target", {}) or {}
+    target = CompetitorEntity(
+        entity_id=target_data.get("entity_id", ""),
+        name=target_data.get("name", ""),
+        aliases=target_data.get("aliases", []),
+        relation=target_data.get("relation", "direct_competitor"),
+        priority=target_data.get("priority", "primary"),
+        geographies=target_data.get("geographies", []),
+        technologies=target_data.get("technologies", []),
+    )
+
+    entities: list[CompetitorEntity] = []
+    for ent in data.get("entities", []) or []:
+        entities.append(CompetitorEntity(
+            entity_id=ent.get("entity_id", ""),
+            name=ent.get("name", ""),
+            aliases=ent.get("aliases", []),
+            relation=ent.get("relation", "direct_competitor"),
+            priority=ent.get("priority", "primary"),
+            geographies=ent.get("geographies", []),
+            technologies=ent.get("technologies", []),
+        ))
+
+    # Deduplicate by entity_id
+    seen: set[str] = set()
+    deduped: list[CompetitorEntity] = []
+    if target.entity_id:
+        seen.add(target.entity_id)
+    for ent in entities:
+        if ent.entity_id not in seen:
+            deduped.append(ent)
+            seen.add(ent.entity_id)
+
+    return CompetitorUniverse(
+        target=target,
+        market_scope=data.get("market_scope", {}),
+        entities=deduped,
+        mode=data.get("mode", "weekly_monitor"),
+        enabled=bool(data.get("enabled", False)),
+    )
+
+
+def save_competitor_universe(universe: CompetitorUniverse, path: str | Path) -> None:
+    """Serialize a CompetitorUniverse to YAML."""
+    _save_yaml(Path(path), universe.to_dict())
+
+
+def load_competitor_candidates(path: str | Path) -> list[dict[str, Any]]:
+    """Load candidate competitors from competitor_candidates.yaml.
+
+    Returns the ``candidates`` list, or an empty list if the file does
+    not exist / is empty.
+    """
+    data = _load_yaml(Path(path))
+    return data.get("candidates", []) or []
+
+
+def save_competitor_candidates(candidates: list[dict[str, Any]], path: str | Path) -> None:
+    """Write candidate competitors to competitor_candidates.yaml."""
+    _save_yaml(Path(path), {"candidates": candidates})
+
+
+def merge_candidates_to_universe(
+    candidates_path: str | Path,
+    universe_path: str | Path,
+) -> int:
+    """Merge approved candidates (``approved: true``) from
+    competitor_candidates.yaml into competitor_universe.yaml.
+
+    Returns the number of entities added.
+    """
+    candidates = load_competitor_candidates(candidates_path)
+    universe = load_competitor_universe(universe_path)
+
+    existing_ids = {universe.target.entity_id} if universe.target.entity_id else set()
+    for ent in universe.entities:
+        existing_ids.add(ent.entity_id)
+
+    added = 0
+    for c in candidates:
+        if not c.get("approved", False):
+            continue
+        entity_id = c.get("entity_id", "").strip()
+        if not entity_id:
+            continue
+        if entity_id in existing_ids:
+            continue
+
+        universe.entities.append(CompetitorEntity(
+            entity_id=entity_id,
+            name=c.get("name", entity_id),
+            aliases=c.get("aliases", []),
+            relation=c.get("relation", "direct_competitor"),
+            priority=c.get("priority", "primary"),
+            geographies=c.get("market_overlap", {}).get("geography", [])
+                       if isinstance(c.get("market_overlap"), dict)
+                       else [],
+            technologies=c.get("market_overlap", {}).get("product", [])
+                        if isinstance(c.get("market_overlap"), dict)
+                        else [],
+        ))
+        existing_ids.add(entity_id)
+        added += 1
+
+    if added > 0:
+        save_competitor_universe(universe, universe_path)
+
+    return added
+
+
+# ── Template generators ─────────────────────────────────────────────────────
+
+
+def generate_universe_template(target_entity: CompetitorEntity | None = None) -> dict[str, Any]:
+    """Generate the default competitor_universe.yaml template."""
+    tgt = target_entity or CompetitorEntity(entity_id="", name="")
+    return {
+        "target": {
+            "entity_id": tgt.entity_id,
+            "name": tgt.name,
+            "aliases": tgt.aliases,
+            "relation": tgt.relation,
+            "priority": tgt.priority,
+            "geographies": tgt.geographies,
+            "technologies": tgt.technologies,
+        },
+        "market_scope": {
+            "geographies": [],
+            "products": [],
+            "customer_segments": [],
+            "value_chain_positions": [],
+        },
+        "entities": [],
+        "mode": "weekly_monitor",
+        "enabled": False,
+    }
+
+
+def generate_candidates_template() -> dict[str, Any]:
+    """Generate the default competitor_candidates.yaml template."""
+    return {"candidates": []}