briefloop 0.11.12__py3-none-any.whl

multi_agent_brief/analysis_blocks/builder.py

@@ -0,0 +1,206 @@
+"""Build AnalysisBlocks from a ClaimLedger.
+
+Classification rules (from v0.5.3 PR 1 acceptance criteria):
+- observed + direct        → Fact
+- analogous                → Case
+- hypothesis / interpreted → Interpretation
+- action + direct evidence → Action
+- action without evidence  → To Verify (downgraded)
+- hypothesis               → also To Verify (pending validation)
+- any claim with limitations → Limitation
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+
+from multi_agent_brief.analysis_blocks.schemas import AnalysisBlock, CaseApplicability
+from multi_agent_brief.core.claim_ledger import ClaimLedger
+from multi_agent_brief.core.schemas import Claim
+
+
+def _infer_section(statement: str) -> str:
+    """Infer a topic from claim statement keywords.
+
+    Kept in sync with the analysis-block topic inference helper to avoid topic drift
+    between analysis_blocks (governance artifact) and legacy brief.md.
+    """
+    lowered = statement.lower()
+    if any(word in lowered for word in ["policy", "tariff", "regulation"]):
+        return "policy"
+    if any(word in lowered for word in ["compliance", "uflpa", "forced labor"]):
+        return "compliance"
+    if any(word in lowered for word in ["revenue", "margin", "earnings"]):
+        return "earnings"
+    if any(word in lowered for word in ["competitor", "capacity", "launch"]):
+        return "competitor"
+    if any(word in lowered for word in ["market", "price", "demand"]):
+        return "market"
+    if any(word in lowered for word in ["installation", "generation", "ppa"]):
+        return "demand"
+    if any(word in lowered for word in ["treasury", "yield", "sofr", "fed", "rate"]):
+        return "rates"
+    if any(word in lowered for word in ["acquisition", "investment", "fund", "capital"]):
+        return "capital"
+    if any(word in lowered for word in ["topcon", "hjt", "technology", "efficiency"]):
+        return "technology"
+    return "general"
+
+
+def build_analysis_blocks(ledger: ClaimLedger) -> list[AnalysisBlock]:
+    """Group ledger claims into AnalysisBlocks by topic.
+
+    Each topic becomes one block. Claims are classified into epistemic
+    buckets based on their epistemic_type and evidence_relation.
+    """
+    # Group claims by topic — fall back to keyword inference for topicless claims,
+    # keeping parity with analysis-block topic inference.
+    by_topic: dict[str, list[Claim]] = defaultdict(list)
+    for claim in ledger:
+        topic = claim.metadata.get("topic") or _infer_section(claim.statement)
+        by_topic[topic].append(claim)
+
+    blocks: list[AnalysisBlock] = []
+    for topic, claims in by_topic.items():
+        block = _build_block(topic, claims)
+        blocks.append(block)
+
+    return blocks
+
+
+def _build_block(topic: str, claims: list[Claim]) -> AnalysisBlock:
+    block_id = topic.replace(" ", "_").lower()
+    block = AnalysisBlock(block_id=block_id, title=topic.replace("_", " ").title())
+
+    for claim in claims:
+        _classify_claim(block, claim)
+
+    block.confidence = _compute_confidence(block, claims)
+    return block
+
+
+def _classify_claim(block: AnalysisBlock, claim: Claim) -> None:
+    """Classify a single claim into the appropriate epistemic bucket."""
+    ep_type = claim.epistemic_type
+    ev_rel = claim.evidence_relation
+    has_evidence = bool(claim.evidence_text.strip())
+    has_limitations = bool(claim.limitations)
+
+    # 1. observed + direct → Fact
+    if ep_type == "observed" and ev_rel == "direct":
+        block.fact_claim_ids.append(claim.claim_id)
+        if has_limitations:
+            block.limitation_claim_ids.append(claim.claim_id)
+        return
+
+    # 2. analogous → Case (but hypothesis still goes to To Verify)
+    if ev_rel == "analogous":
+        block.case_claim_ids.append(claim.claim_id)
+        # Populate case_applicability from claim metadata if available
+        _populate_case_applicability(block, claim)
+        # hypothesis+analogous: must also be tracked for verification
+        if ep_type == "hypothesis":
+            block.to_verify_claim_ids.append(claim.claim_id)
+        if has_limitations:
+            block.limitation_claim_ids.append(claim.claim_id)
+        return
+
+    # 3. hypothesis / interpreted → Interpretation
+    if ep_type in ("hypothesis", "interpreted"):
+        block.interpretation_claim_ids.append(claim.claim_id)
+        # hypothesis also goes to To Verify
+        if ep_type == "hypothesis":
+            block.to_verify_claim_ids.append(claim.claim_id)
+        if has_limitations:
+            block.limitation_claim_ids.append(claim.claim_id)
+        return
+
+    # 4. action — gate on evidence
+    if ep_type == "action":
+        if has_evidence and ev_rel == "direct":
+            block.action_claim_ids.append(claim.claim_id)
+        else:
+            # Downgrade: action without direct evidence → To Verify
+            block.to_verify_claim_ids.append(claim.claim_id)
+        if has_limitations:
+            block.limitation_claim_ids.append(claim.claim_id)
+        return
+
+    # 5. observed + indirect/inferred → Interpretation (not strong enough for Fact)
+    if ep_type == "observed" and ev_rel in ("indirect", "inferred"):
+        block.interpretation_claim_ids.append(claim.claim_id)
+        block.to_verify_claim_ids.append(claim.claim_id)
+        if has_limitations:
+            block.limitation_claim_ids.append(claim.claim_id)
+        return
+
+    # Fallback: anything else goes to Interpretation + To Verify
+    block.interpretation_claim_ids.append(claim.claim_id)
+    block.to_verify_claim_ids.append(claim.claim_id)
+    if has_limitations:
+        block.limitation_claim_ids.append(claim.claim_id)
+
+
+def _populate_case_applicability(block: AnalysisBlock, claim: Claim) -> None:
+    """Extract case applicability from claim metadata (PR 3)."""
+    meta = claim.metadata
+    if not meta:
+        return
+
+    comparable = meta.get("comparable_dimensions", [])
+    non_comparable = meta.get("non_comparable_dimensions", [])
+    market_ctx = meta.get("market_context", "")
+    stage_ctx = meta.get("stage_context", "")
+    audience_fit = meta.get("price_band_or_audience_fit", "")
+    needs_local = meta.get("local_verification_needed", False)
+    applicability = claim.applicability_reason or meta.get("applicability_reason", "")
+
+    if any([comparable, non_comparable, market_ctx, stage_ctx, audience_fit, needs_local, applicability]):
+        if block.case_applicability is None:
+            block.case_applicability = CaseApplicability()
+        if comparable:
+            block.case_applicability.comparable_dimensions.extend(comparable)
+        if non_comparable:
+            block.case_applicability.non_comparable_dimensions.extend(non_comparable)
+        if market_ctx:
+            block.case_applicability.market_context = market_ctx
+        if stage_ctx:
+            block.case_applicability.stage_context = stage_ctx
+        if audience_fit:
+            block.case_applicability.price_band_or_audience_fit = audience_fit
+        if needs_local:
+            block.case_applicability.local_verification_needed = True
+        if applicability:
+            if not block.applicability_note:
+                block.applicability_note = applicability
+            elif applicability not in block.applicability_note:
+                block.applicability_note += "; " + applicability
+
+
+def _compute_confidence(block: AnalysisBlock, claims: list[Claim]) -> float:
+    """Compute block confidence from claim evidence quality.
+
+    Epistemic hierarchy (strongest → weakest):
+      observed+direct (1.0) > interpreted (0.5) > analogous (0.4) > hypothesis (0.2)
+    Action claims with direct evidence score 1.0 (equivalent to observed+direct).
+    """
+    if not claims:
+        return 0.0
+
+    score = 0.0
+    for claim in claims:
+        ep_type = claim.epistemic_type
+        ev_rel = claim.evidence_relation
+        if ep_type == "observed" and ev_rel == "direct":
+            score += 1.0
+        elif ep_type == "action" and ev_rel == "direct":
+            score += 1.0
+        elif ev_rel == "analogous":
+            score += 0.4
+        elif ep_type == "hypothesis":
+            score += 0.2
+        elif ep_type == "interpreted":
+            score += 0.5
+        else:
+            score += 0.3
+
+    return round(min(score / len(claims), 1.0), 2)

multi_agent_brief/analysis_blocks/renderer.py

@@ -0,0 +1,237 @@
+"""Render AnalysisBlocks to structured markdown.
+
+Produces a fixed-block format instead of prose:
+  Fact → Case/Comparison → Interpretation → Limitations → Action/To Verify
+
+Different audiences get different heading labels, but the underlying
+block structure is always the same.
+"""
+from __future__ import annotations
+
+from multi_agent_brief.analysis_blocks.schemas import AnalysisBlock
+from multi_agent_brief.core.claim_ledger import ClaimLedger
+from multi_agent_brief.core.schemas import Claim
+
+# Audience-specific heading maps
+_HEADING_MAPS: dict[str, dict[str, str]] = {
+    "management": {
+        "fact": "What Happened",
+        "case": "Comparable Context",
+        "interpretation": "Why It Matters",
+        "limitations": "Evidence Boundary",
+        "action": "What To Do",
+        "to_verify": "What To Verify Next",
+    },
+    "research": {
+        "fact": "Observed Facts",
+        "case": "Comparable Cases",
+        "interpretation": "Interpretation",
+        "limitations": "Limitations",
+        "action": "Recommended Actions",
+        "to_verify": "Pending Verification",
+    },
+    "default": {
+        "fact": "Fact",
+        "case": "Case / Comparison",
+        "interpretation": "Interpretation",
+        "limitations": "Limitations",
+        "action": "Action",
+        "to_verify": "To Verify",
+    },
+}
+
+
+def render_analysis_blocks(
+    blocks: list[AnalysisBlock],
+    ledger: ClaimLedger,
+    *,
+    project_name: str = "",
+    audience: str = "default",
+    language: str = "en-US",
+) -> str:
+    """Render analysis blocks to structured markdown.
+
+    Args:
+        blocks: AnalysisBlock instances from builder.
+        ledger: ClaimLedger for resolving claim details.
+        project_name: Optional project title shown at the top.
+        audience: Heading style key ("management", "research", "default").
+        language: "en-US" or "zh-CN".
+
+    Returns:
+        Structured markdown string.
+    """
+    headings = _HEADING_MAPS.get(audience, _HEADING_MAPS["default"])
+    is_zh = language.startswith("zh")
+
+    parts: list[str] = []
+    if project_name:
+        parts.append(f"# {project_name}")
+
+    sections: list[str] = []
+    for block in blocks:
+        section = _render_block(block, ledger, headings, is_zh)
+        if section:
+            sections.append(section)
+
+    if not sections:
+        return _empty_message(is_zh)
+
+    parts.extend(sections)
+    return "\n\n".join(parts) + "\n"
+
+
+def _render_block(
+    block: AnalysisBlock,
+    ledger: ClaimLedger,
+    headings: dict[str, str],
+    is_zh: bool,
+) -> str:
+    lines: list[str] = [f"## {block.title}", ""]
+
+    # Fact section — conditional like all other sections
+    if block.fact_claim_ids:
+        lines.append(f"### {headings['fact']}")
+        lines.append("")
+        fact_lines = _render_claim_list(block.fact_claim_ids, ledger)
+        if fact_lines:
+            lines.extend(fact_lines)
+        else:
+            lines.append(_no_fact_message(is_zh))
+        lines.append("")
+
+    # Case / Comparison section
+    case_lines = _render_claim_list(block.case_claim_ids, ledger)
+    if case_lines:
+        lines.append(f"### {headings['case']}")
+        lines.append("")
+        lines.extend(case_lines)
+        # Applicability note (PR 3)
+        if block.applicability_note:
+            lines.append("")
+            lines.append(f"> **{ _applicability_label(is_zh) }:** {block.applicability_note}")
+        if block.case_applicability:
+            ca = block.case_applicability
+            if ca.comparable_dimensions:
+                lines.append(f"> **{ _comparable_label(is_zh) }:** {', '.join(ca.comparable_dimensions)}")
+            if ca.non_comparable_dimensions:
+                lines.append(f"> **{ _non_comparable_label(is_zh) }:** {', '.join(ca.non_comparable_dimensions)}")
+            if ca.local_verification_needed:
+                lines.append(f"> ⚠️ { _local_verify_label(is_zh) }")
+        lines.append("")
+
+    # Interpretation section
+    interp_lines = _render_claim_list(block.interpretation_claim_ids, ledger)
+    if interp_lines:
+        lines.append(f"### {headings['interpretation']}")
+        lines.append("")
+        lines.extend(interp_lines)
+        lines.append("")
+
+    # Limitations section
+    limit_lines = _render_limitations(block, ledger, is_zh)
+    if limit_lines:
+        lines.append(f"### {headings['limitations']}")
+        lines.append("")
+        lines.extend(limit_lines)
+        lines.append("")
+
+    # Action section (only claims with direct evidence)
+    action_lines = _render_claim_list(block.action_claim_ids, ledger)
+    if action_lines:
+        lines.append(f"### {headings['action']}")
+        lines.append("")
+        lines.extend(action_lines)
+        lines.append("")
+
+    # To Verify section
+    verify_lines = _render_claim_list(block.to_verify_claim_ids, ledger)
+    if verify_lines:
+        lines.append(f"### {headings['to_verify']}")
+        lines.append("")
+        lines.extend(verify_lines)
+        if block.verification_path:
+            lines.append("")
+            lines.append(f"> **{ _verification_path_label(is_zh) }:** {block.verification_path}")
+        lines.append("")
+
+    # Confidence footer (qualitative label, not percentage — avoids audit false positives)
+    lines.append(f"_{ _confidence_label(is_zh) }: { _confidence_level(block.confidence, is_zh) }_")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def _render_claim_list(claim_ids: list[str], ledger: ClaimLedger) -> list[str]:
+    lines = []
+    for cid in claim_ids:
+        claim = ledger.get_claim(cid)
+        if claim:
+            date_str = claim.metadata.get("published_at") or claim.metadata.get("retrieved_at", "")
+            date_prefix = f"{date_str} | " if date_str else ""
+            lines.append(f"- {date_prefix}{claim.statement} [src:{cid}]")
+    return lines
+
+
+def _render_limitations(block: AnalysisBlock, ledger: ClaimLedger, is_zh: bool) -> list[str]:
+    lines = []
+    seen: set[str] = set()
+    for cid in block.limitation_claim_ids:
+        claim = ledger.get_claim(cid)
+        if not claim:
+            continue
+        for lim in claim.limitations:
+            normalized = lim.strip().lower()
+            if normalized not in seen:
+                seen.add(normalized)
+                lines.append(f"- {lim}")
+    return lines
+
+
+def _no_fact_message(is_zh: bool) -> str:
+    if is_zh:
+        return "_未找到本期直接事实依据。_"
+    return "_No current-period direct fact found._"
+
+
+def _empty_message(is_zh: bool) -> str:
+    if is_zh:
+        return "# 无可报告信号\n\n未发现符合条件的事实声明。\n"
+    return "# No Reportable Signals\n\nNo candidate claims were found.\n"
+
+
+def _applicability_label(is_zh: bool) -> str:
+    return "适用性说明" if is_zh else "Applicability"
+
+
+def _comparable_label(is_zh: bool) -> str:
+    return "可比维度" if is_zh else "Comparable Dimensions"
+
+
+def _non_comparable_label(is_zh: bool) -> str:
+    return "不可比维度" if is_zh else "Non-Comparable Dimensions"
+
+
+def _local_verify_label(is_zh: bool) -> str:
+    return "需要本地验证" if is_zh else "Local verification needed"
+
+
+def _verification_path_label(is_zh: bool) -> str:
+    return "验证路径" if is_zh else "Verification Path"
+
+
+def _confidence_label(is_zh: bool) -> str:
+    return "置信度" if is_zh else "Confidence"
+
+
+def _confidence_level(score: float, is_zh: bool) -> str:
+    """Map numeric confidence to qualitative label.
+
+    Avoids precise percentages that trigger audit false positives
+    (e.g. '100%' flagged as number_without_source).
+    """
+    if score >= 0.8:
+        return "高" if is_zh else "High"
+    if score >= 0.5:
+        return "中" if is_zh else "Medium"
+    return "低" if is_zh else "Low"

multi_agent_brief/analysis_blocks/schemas.py

@@ -0,0 +1,52 @@
+"""Analysis Block schemas — epistemic presentation layer."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass
+class CaseApplicability:
+    """Comparable case boundary metadata (PR 3 of v0.5.3)."""
+
+    comparable_dimensions: list[str] = field(default_factory=list)
+    non_comparable_dimensions: list[str] = field(default_factory=list)
+    market_context: str = ""
+    stage_context: str = ""
+    price_band_or_audience_fit: str = ""
+    local_verification_needed: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class AnalysisBlock:
+    """One observation unit with epistemic classification.
+
+    Groups claim IDs by their epistemic role so the renderer can
+    present facts, cases, interpretations, limitations, and actions
+    in a fixed structure instead of prose.
+    """
+
+    block_id: str
+    title: str
+    # Claim IDs by epistemic role
+    fact_claim_ids: list[str] = field(default_factory=list)          # epistemic_type=observed, evidence_relation=direct
+    case_claim_ids: list[str] = field(default_factory=list)          # evidence_relation=analogous
+    interpretation_claim_ids: list[str] = field(default_factory=list) # epistemic_type=hypothesis or interpreted
+    limitation_claim_ids: list[str] = field(default_factory=list)    # claims with limitations
+    action_claim_ids: list[str] = field(default_factory=list)        # epistemic_type=action WITH direct evidence
+    to_verify_claim_ids: list[str] = field(default_factory=list)     # action without evidence, or hypothesis
+    # Metadata
+    applicability_note: str = ""
+    verification_path: str = ""
+    confidence: float = 0.0
+    # PR 3: comparable case boundary
+    case_applicability: CaseApplicability | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        if self.case_applicability:
+            data["case_applicability"] = self.case_applicability.to_dict()
+        return data

multi_agent_brief/analysis_modules/__init__.py

@@ -0,0 +1,8 @@
+"""Analysis Modules — pluggable post-Screener analysis pipeline extensions.
+
+Each module consumes a screened ClaimLedger and produces structured artifacts
+(AnalysisCards, events, coverage reports, etc.) before the Analyst agent
+writes the final brief.  Modules are registered in MODULE_REGISTRY and enabled
+via config.yaml's ``modules`` section.
+"""
+

multi_agent_brief/analysis_modules/base.py

@@ -0,0 +1,87 @@
+"""Pluggable Analysis Module interface.
+
+AnalysisModules run between Screener and Analyst in the pipeline.
+They consume a screened ClaimLedger and produce structured artifacts
+(analysis cards, events, coverage reports, etc.) — deterministically,
+without external model calls.  LLM subagents consume the artifacts
+later to generate the final human-readable analysis.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, TYPE_CHECKING
+
+from multi_agent_brief.core.schemas import AuditFinding
+
+if TYPE_CHECKING:
+    from multi_agent_brief.core.claim_ledger import ClaimLedger
+    from multi_agent_brief.core.schemas import PipelineContext
+
+
+@dataclass
+class ModuleOutput:
+    """Output from a single AnalysisModule.analyze() call."""
+
+    module_name: str
+    artifacts: dict[str, Any] = field(default_factory=dict)
+    findings: list[AuditFinding] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "module_name": self.module_name,
+            "artifacts": self.artifacts,
+            "findings": [f.to_dict() for f in self.findings],
+            "metadata": self.metadata,
+        }
+
+
+class AnalysisModule(ABC):
+    """Abstract base class for pluggable analysis modules.
+
+    Each module must provide:
+
+    - ``name`` — unique string key (e.g. ``"market_competitor"``).
+    - ``validate_config(config: dict) -> list[str]`` — return a list of
+      human-readable config errors (empty = valid).
+    - ``analyze(context, ledger) -> ModuleOutput`` — run the module's
+      deterministic analysis pass.
+    """
+
+    name: str = ""
+
+    @abstractmethod
+    def validate_config(self, config: dict[str, Any]) -> list[str]:
+        """Validate module-specific configuration.
+
+        Args:
+            config: The module's section from config.yaml's ``modules`` block
+                    (e.g. ``config["modules"]["market_competitor"]``), or an
+                    empty dict if not present.
+
+        Returns:
+            A list of error messages.  An empty list means "valid".
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def analyze(
+        self,
+        context: "PipelineContext",
+        ledger: "ClaimLedger",
+    ) -> ModuleOutput:
+        """Run the module's analysis on a screened ClaimLedger.
+
+        Modules MUST NOT modify the ClaimLedger — only read it.
+        Modules MUST NOT make external model/API calls — deterministic only.
+
+        Args:
+            context: The pipeline context containing sources, metadata, etc.
+            ledger: The screened ClaimLedger (post-Screener).
+
+        Returns:
+            A ModuleOutput with artifacts, findings, and metadata.
+        """
+        raise NotImplementedError

multi_agent_brief/analysis_modules/market_competitor/__init__.py

@@ -0,0 +1,68 @@
+"""Market & Competitor Intelligence Analysis Module.
+
+Pluggable analysis module that transforms Claim Ledger entries into structured
+competitive intelligence artifacts:
+- MarketEvent — source-grounded competitor/market events
+- AnalysisCard — multi-source analytical judgments (LLM-generated)
+- CompetitorMatrix — entity × dimension comparison table
+- CoverageReport — entity/dimension coverage gaps
+- Watchlist — cross-period tracking items
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from multi_agent_brief.analysis_modules.base import AnalysisModule, ModuleOutput
+from multi_agent_brief.analysis_modules.market_competitor.config import (
+    load_competitor_universe,
+)
+from multi_agent_brief.analysis_modules.market_competitor.event_builder import (
+    build_events,
+)
+from multi_agent_brief.analysis_modules.market_competitor.renderer import render_all
+from multi_agent_brief.core.claim_ledger import ClaimLedger
+from multi_agent_brief.core.schemas import PipelineContext
+
+
+class MarketCompetitorModule(AnalysisModule):
+    name = "market_competitor"
+
+    def validate_config(self, config: dict[str, Any]) -> list[str]:
+        errors: list[str] = []
+        if not isinstance(config, dict):
+            errors.append("market_competitor config must be a dict")
+            return errors
+        return errors
+
+    def analyze(self, context: PipelineContext, ledger: ClaimLedger) -> ModuleOutput:
+        config_dir = context.metadata.get("_config_dir", "")
+        output_dir = Path(context.output_dir)
+
+        # Load universe
+        universe_path = Path(config_dir) / "competitor_universe.yaml" if config_dir else None
+        universe = None
+        if universe_path and universe_path.exists():
+            universe = load_competitor_universe(universe_path)
+
+        if universe is None or not universe.enabled or not universe.entities:
+            return ModuleOutput(
+                module_name=self.name,
+                metadata={"status": "disabled", "reason": "no_entities"},
+            )
+
+        # Build events from entity-tagged claims
+        state_dir = str(Path(config_dir).parent / "state") if config_dir else None
+        events = build_events(ledger, universe, state_dir=state_dir)
+
+        # Render artifacts
+        artifact_paths = render_all(events, ledger, universe, output_dir)
+
+        return ModuleOutput(
+            module_name=self.name,
+            artifacts=artifact_paths,
+            metadata={
+                "event_count": len(events),
+                "entity_count": len(universe.entities),
+            },
+        )