briefloop 0.11.12__py3-none-any.whl

multi_agent_brief/core/__init__.py

@@ -0,0 +1,2 @@
+"""Core pipeline primitives."""
+

multi_agent_brief/core/citations.py

@@ -0,0 +1,14 @@
+"""Shared helpers for internal claim citation markers."""
+
+from __future__ import annotations
+
+import re
+
+
+CLAIM_ID_RE_FRAGMENT = r"[A-Za-z0-9][A-Za-z0-9_-]{1,127}"
+SRC_REF_PATTERN = re.compile(rf"\[src:({CLAIM_ID_RE_FRAGMENT})\]")
+VALID_SRC_REF_PATTERN = re.compile(rf"\[src:{CLAIM_ID_RE_FRAGMENT}\]")
+
+
+def extract_src_ref_ids(markdown: str) -> list[str]:
+    return SRC_REF_PATTERN.findall(markdown)

multi_agent_brief/core/claim_ledger.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from multi_agent_brief.core.schemas import Claim
+
+
+class ClaimLedger:
+    """In-memory claim store with validation helpers."""
+
+    def __init__(self, claims: list[Claim] | None = None) -> None:
+        self._claims: dict[str, Claim] = {}
+        for claim in claims or []:
+            self.add_claim(claim)
+
+    def __len__(self) -> int:
+        return len(self._claims)
+
+    def __iter__(self):
+        return iter(self._claims.values())
+
+    @staticmethod
+    def build_claim_id(statement: str, source_id: str) -> str:
+        digest = hashlib.sha1(f"{source_id}|{statement}".encode("utf-8")).hexdigest()[:10]
+        prefix = "".join(ch for ch in source_id.upper() if ch.isalnum())[:8] or "CLAIM"
+        return f"{prefix}_{digest.upper()}"
+
+    def add_claim(self, claim: Claim) -> Claim:
+        if not claim.claim_id:
+            claim.claim_id = self.build_claim_id(claim.statement, claim.source_id)
+        self._claims[claim.claim_id] = claim
+        return claim
+
+    def get_claim(self, claim_id: str) -> Claim | None:
+        return self._claims.get(claim_id)
+
+    def to_list(self) -> list[dict]:
+        return [claim.to_dict() for claim in self._claims.values()]
+
+    def export_json(self, path: str | Path) -> None:
+        Path(path).write_text(json.dumps(self.to_list(), ensure_ascii=False, indent=2), encoding="utf-8")
+
+    @classmethod
+    def import_json(cls, path: str | Path) -> "ClaimLedger":
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+        claims_data = cls._claim_items_from_json(data)
+        return cls([Claim.from_dict(item) for item in claims_data])
+
+    @staticmethod
+    def _claim_items_from_json(data: Any) -> list[dict[str, Any]]:
+        if isinstance(data, list):
+            claims = data
+        elif isinstance(data, dict):
+            claims = None
+            for key in ("claims", "claim_ledger", "items"):
+                value = data.get(key)
+                if isinstance(value, list):
+                    claims = value
+                    break
+            if claims is None:
+                raise ValueError("Claim Ledger JSON object must contain a claims list.")
+        else:
+            raise ValueError("Claim Ledger JSON must be a list or an object containing a claims list.")
+        if not all(isinstance(item, dict) for item in claims):
+            raise ValueError("Claim Ledger claims must be JSON objects.")
+        return claims
+
+    def detect_missing_sources(self) -> list[Claim]:
+        return [
+            claim
+            for claim in self._claims.values()
+            if not claim.source_id or not claim.evidence_text.strip()
+        ]
+
+    def detect_duplicate_claims(self) -> list[list[Claim]]:
+        buckets: dict[str, list[Claim]] = {}
+        for claim in self._claims.values():
+            normalized = " ".join(claim.statement.lower().split())
+            buckets.setdefault(normalized, []).append(claim)
+        return [claims for claims in buckets.values() if len(claims) > 1]
+
+    def validate_claims(self) -> list[str]:
+        errors: list[str] = []
+        for claim in self._claims.values():
+            if not claim.statement.strip():
+                errors.append(f"{claim.claim_id}: missing statement")
+            if claim.requires_audit and not claim.evidence_text.strip():
+                errors.append(f"{claim.claim_id}: missing evidence_text")
+            if not claim.source_id.strip():
+                errors.append(f"{claim.claim_id}: missing source_id")
+        return errors

multi_agent_brief/core/config.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from multi_agent_brief.outputs.naming import DEFAULT_FILENAME_TEMPLATE
+
+try:
+    import yaml
+except ModuleNotFoundError:  # pragma: no cover - exercised when PyYAML is not installed
+    yaml = None
+
+
+def _parse_scalar(value: str) -> Any:
+    value = value.strip()
+    if value in {"true", "false"}:
+        return value == "true"
+    if (value.startswith('"') and value.endswith('"')) or (value.startswith("'") and value.endswith("'")):
+        return value[1:-1]
+    return value
+
+
+def _minimal_yaml_load(text: str) -> dict[str, Any]:
+    """Small fallback parser for the simple config files used by the MVP."""
+    data: dict[str, Any] = {}
+    current_section: dict[str, Any] | None = None
+
+    for raw_line in text.splitlines():
+        if not raw_line.strip() or raw_line.lstrip().startswith("#"):
+            continue
+        indent = len(raw_line) - len(raw_line.lstrip(" "))
+        line = raw_line.strip()
+        if indent == 0 and line.endswith(":"):
+            section_name = line[:-1]
+            current_section = {}
+            data[section_name] = current_section
+            continue
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        target = current_section if indent > 0 and current_section is not None else data
+        target[key.strip()] = _parse_scalar(value)
+    return data
+
+
+def load_config(path: str | Path) -> dict[str, Any]:
+    config_path = Path(path)
+    if not config_path.exists():
+        raise FileNotFoundError(f"Config file not found: {config_path}")
+    config_text = config_path.read_text(encoding="utf-8")
+    data = yaml.safe_load(config_text) if yaml is not None else _minimal_yaml_load(config_text)
+    data = data or {}
+    if not isinstance(data, dict):
+        raise ValueError(f"Config must be a mapping: {config_path}")
+    data = normalize_language_config(data)
+    data["_config_dir"] = str(config_path.parent)
+    return data
+
+
+def normalize_language_config(config: dict[str, Any]) -> dict[str, Any]:
+    project = config.get("project", {}) or {}
+    language_config = config.get("language", {}) or {}
+    if not isinstance(language_config, dict):
+        language_config = {}
+
+    output_language = language_config.get("output") or project.get("language") or "zh-CN"
+    interface_language = language_config.get("interface") or output_language
+    source_handling = language_config.get("source_handling") or "preserve_original"
+
+    config["language"] = {
+        **language_config,
+        "interface": interface_language,
+        "output": output_language,
+        "source_handling": source_handling,
+    }
+    return config
+
+
+def get_output_config(config: dict[str, Any] | None) -> dict[str, Any]:
+    """Return canonical output config, with legacy outputs alias support."""
+    config = config or {}
+    output_config = config.get("output")
+    if isinstance(output_config, dict):
+        return output_config
+    legacy_output_config = config.get("outputs")
+    if isinstance(legacy_output_config, dict):
+        return legacy_output_config
+    return {}
+
+
+def _as_bool(value: Any, default: bool = False) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "y", "on"}
+    return bool(value)
+
+
+def build_run_settings(
+    *,
+    config: dict[str, Any] | None,
+    input_dir: str | None,
+    output_dir: str | None,
+    name: str | None,
+    language: str | None,
+    audience: str | None,
+) -> dict[str, Any]:
+    config = config or {}
+    project = config.get("project", {}) or {}
+    language_config = config.get("language", {}) or {}
+    report = config.get("report", {}) or {}
+    previous = config.get("previous", {}) or {}
+    selection = config.get("selection", {}) or {}
+
+    # Resolve report.date: "auto" → today's date
+    raw_date = report.get("date", "")
+    if raw_date == "auto":
+        from datetime import date
+        raw_date = date.today().isoformat()
+    selector = config.get("selector", {}) or {}
+    input_config = config.get("input", {}) or {}
+    output_config = get_output_config(config)
+    config_dir = Path(config.get("_config_dir", "."))
+
+    resolved_input = input_dir or input_config.get("path")
+    if not resolved_input:
+        raise ValueError("Input directory is required. Pass input_dir or set input.path in config.")
+
+    input_path = Path(str(resolved_input))
+    if input_dir is None and not input_path.is_absolute():
+        input_path = config_dir / input_path
+
+    resolved_output = output_dir or output_config.get("path") or "output/demo"
+    output_path = Path(str(resolved_output))
+    if output_dir is None and output_config.get("path") and not output_path.is_absolute():
+        output_path = config_dir / output_path
+
+    project_name = name or project.get("name") or "Weekly Intelligence Brief"
+    resolved_language = language or language_config.get("output") or project.get("language") or "zh-CN"
+    resolved_audience = audience or project.get("audience") or "management"
+
+    # Resolve audience profile from config or map from audience text
+    audience_profile_config = config.get("audience_profile", {}) or {}
+    resolved_audience_profile = audience_profile_config.get("id", "")
+    if not resolved_audience_profile:
+        from multi_agent_brief.audience.profiles import map_audience_to_profile
+        resolved_audience_profile = map_audience_to_profile(resolved_audience)
+
+    output_filename_template = (
+        output_config.get("filename_template")
+        or output_config.get("file_name_template")
+        or output_config.get("name_template")
+        or output_config.get("filename")
+        or DEFAULT_FILENAME_TEMPLATE
+    )
+    output_filename_tokens = {
+        "project_name": str(project_name),
+        "title": str(project_name),
+        "company": str(project.get("company", "")),
+        "industry": str(project.get("industry", "")),
+        "audience": str(resolved_audience),
+        "cadence": str(report.get("cadence", "")),
+        "report_date": str(raw_date),
+        "date": str(raw_date),
+        "language": str(resolved_language),
+    }
+
+    return {
+        "project_name": project_name,
+        "input_dir": str(input_path),
+        "output_dir": str(output_path),
+        "language": resolved_language,
+        "audience": resolved_audience,
+        "audience_profile": resolved_audience_profile,
+        "report_date": str(raw_date),
+        "max_source_age_days": int(report["max_source_age_days"]) if "max_source_age_days" in report else None,
+        "fail_on_stale_source": _as_bool(report.get("fail_on_stale_source"), False),
+        "previous_report_dir": str(previous.get("path", "")),
+        "max_claims": (
+            int(selector["max_items"]) if selector.get("max_items") is not None
+            else int(selection.get("max_claims", 160))
+        ),
+        "quiet_week_min_claims": int(selection.get("quiet_week_min_claims", 5)),
+        "output_formats": output_config.get("formats", ["markdown"]),
+        "output_footer": output_config.get("footer", ""),
+        "output_filename_template": str(output_filename_template),
+        "output_filename_tokens": output_filename_tokens,
+        "output_named_outputs": _as_bool(output_config.get("named_outputs"), True),
+    }

multi_agent_brief/core/env.py

@@ -0,0 +1,69 @@
+"""Safe workspace environment helpers."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+KNOWN_WORKSPACE_ENV_KEYS = frozenset(
+    {
+        "TAVILY_API_KEY",
+        "EXA_API_KEY",
+        "BRAVE_SEARCH_API_KEY",
+        "FIRECRAWL_API_KEY",
+        "SERPER_API_KEY",
+        "NEWSAPI_API_KEY",
+        "MINERU_API_TOKEN",
+    }
+)
+
+
+def _parse_env_line(line: str) -> tuple[str, str] | None:
+    text = line.strip()
+    if not text or text.startswith("#") or "=" not in text:
+        return None
+    if text.startswith("export "):
+        text = text[len("export "):].lstrip()
+    key, value = text.split("=", 1)
+    key = key.strip()
+    if key not in KNOWN_WORKSPACE_ENV_KEYS:
+        return None
+    value = value.strip()
+    if (
+        len(value) >= 2
+        and value[0] == value[-1]
+        and value[0] in {"'", '"'}
+    ):
+        value = value[1:-1]
+    return key, value
+
+
+def read_workspace_env_key(workspace_dir: str | Path | None, key: str) -> str:
+    """Return a known env key from workspace .env without exporting it."""
+    if key not in KNOWN_WORKSPACE_ENV_KEYS or not workspace_dir:
+        return ""
+    path = Path(workspace_dir) / ".env"
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return ""
+    for line in lines:
+        parsed = _parse_env_line(line)
+        if not parsed:
+            continue
+        parsed_key, value = parsed
+        if parsed_key == key and value:
+            return value
+    return ""
+
+
+def get_known_env_value(key: str, workspace_dir: str | Path | None = None) -> str:
+    """Return shell env value first, then known workspace .env value."""
+    if key not in KNOWN_WORKSPACE_ENV_KEYS:
+        return ""
+    return os.environ.get(key, "") or read_workspace_env_key(workspace_dir, key)
+
+
+def known_env_key_is_set(key: str, workspace_dir: str | Path | None = None) -> bool:
+    """Return whether a known key is set without exposing its value."""
+    return bool(get_known_env_value(key, workspace_dir))

multi_agent_brief/core/previous.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import re
+import zipfile
+import xml.etree.ElementTree as ET
+from datetime import datetime
+from pathlib import Path
+
+
+def load_previous_report_baseline(directory: str | Path, report_date: str = "", limit: int = 5) -> tuple[str, list[str]]:
+    """Load previous md/txt/docx reports as a deduplication baseline."""
+    root = Path(directory)
+    if not directory or not root.exists():
+        return "", []
+
+    current = _parse_report_date(report_date)
+    candidates = [
+        path
+        for path in root.iterdir()
+        if path.is_file() and path.suffix.lower() in {".md", ".txt", ".docx"}
+    ]
+    eligible = []
+    for path in candidates:
+        file_date = _date_from_name(path)
+        if current and file_date and file_date >= current:
+            continue
+        eligible.append(path)
+
+    eligible.sort(key=lambda path: (_date_from_name(path) or datetime.min.date(), path.stat().st_mtime), reverse=True)
+
+    parts: list[str] = []
+    names: list[str] = []
+    for path in eligible[:limit]:
+        text = _read_report_text(path).strip()
+        if not text:
+            continue
+        names.append(path.name)
+        parts.append(f"===== {path.name} =====\n{text}")
+    return "\n\n".join(parts), names
+
+
+def _parse_report_date(value: str):
+    if not value:
+        return None
+    for fmt in ("%Y%m%d", "%Y-%m-%d"):
+        try:
+            return datetime.strptime(value, fmt).date()
+        except ValueError:
+            continue
+    return None
+
+
+def _date_from_name(path: Path):
+    match = re.search(r"(20\d{6})", path.name)
+    if not match:
+        return None
+    return _parse_report_date(match.group(1))
+
+
+def _read_report_text(path: Path) -> str:
+    if path.suffix.lower() == ".docx":
+        return _extract_docx_text(path)
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return path.read_text(errors="ignore")
+
+
+def _extract_docx_text(path: Path) -> str:
+    try:
+        with zipfile.ZipFile(path) as zf:
+            xml = zf.read("word/document.xml")
+    except Exception:
+        return ""
+    root = ET.fromstring(xml)
+    ns = {"w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"}
+    lines = []
+    for paragraph in root.findall(".//w:p", ns):
+        texts = [node.text for node in paragraph.findall(".//w:t", ns) if node.text]
+        if texts:
+            lines.append("".join(texts))
+    return "\n".join(lines)
+

multi_agent_brief/core/schemas.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Literal
+
+# Re-export SourceItem from the canonical location (sources.base)
+from multi_agent_brief.sources.base import SourceItem  # noqa: F401
+
+
+ClaimType = Literal["fact", "number", "date", "interpretation", "forecast", "risk"]
+Confidence = Literal["low", "medium", "high"]
+AuditSeverity = Literal["low", "medium", "high"]
+AuditStatus = Literal["pass", "warning", "fail"]
+
+# v2 epistemic types
+SchemaVersion = Literal["v1", "v2"]
+EpistemicType = Literal["observed", "interpreted", "hypothesis", "action", "analogy"]
+EvidenceRelation = Literal["direct", "indirect", "inferred", "analogous"]
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+@dataclass
+class CandidateItem:
+    item_id: str
+    title: str
+    summary: str
+    source_id: str
+    topic: str = "general"
+    importance: str = "medium"
+    reason_for_inclusion: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class Claim:
+    claim_id: str
+    statement: str
+    source_id: str
+    evidence_text: str
+    source_url: str = ""
+    source_type: str = "local_file"
+    claim_type: ClaimType = "fact"
+    confidence: Confidence = "medium"
+    requires_audit: bool = True
+    created_by: str = "scout"
+    used_in_sections: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    # v2 epistemic fields — new Claims default to v2
+    schema_version: SchemaVersion = "v2"
+    epistemic_type: EpistemicType = "observed"
+    evidence_relation: EvidenceRelation = "direct"
+    applicability_reason: str = ""
+    limitations: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Claim":
+        known = {f.name for f in cls.__dataclass_fields__.values()}
+        filtered = {k: v for k, v in data.items() if k in known}
+        claim = cls(**filtered)
+        # v1→v2 migration: fill missing epistemic fields from claim_type
+        if "epistemic_type" not in data:
+            claim.epistemic_type = cls._migrate_epistemic(claim.claim_type)
+        if "schema_version" not in data:
+            claim.schema_version = "v1"
+        return claim
+
+    @staticmethod
+    def _migrate_epistemic(claim_type: str) -> EpistemicType:
+        mapping: dict[str, EpistemicType] = {
+            "interpretation": "interpreted",
+            "forecast": "hypothesis",
+            "risk": "hypothesis",
+        }
+        return mapping.get(claim_type, "observed")
+
+
+@dataclass
+class BriefSection:
+    title: str
+    body: str
+    claim_ids: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+BlockingLevel = Literal[
+    "editor_fixable",       # editor can fix in-place (residue, filler, labels)
+    "analyst_blocking",     # must return to analyst (unsupported certainty, hypothesis misuse)
+    "source_blocking",      # must return to source collection (missing sources, stale, needs_recrawl)
+    "configuration_error",  # user must fix config (no API key, missing search_tasks)
+    "rendering_error",      # docx/markdown rendering issue
+    "safety_blocking",      # investment advice, redaction risk — cannot ship
+]
+
+RepairOwner = Literal["editor", "analyst", "source", "configuration", "rendering", "safety"]
+
+
+@dataclass
+class AuditFinding:
+    finding_id: str
+    severity: AuditSeverity
+    finding_type: str
+    description: str
+    recommendation: str = ""
+    related_claim_id: str = ""
+    line_number: int | None = None
+    evidence: str = ""
+    blocking_level: BlockingLevel = "editor_fixable"
+    repair_owner: RepairOwner = "editor"
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class AuditReport:
+    audit_status: AuditStatus
+    audit_score: int
+    findings: list[AuditFinding] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["findings"] = [finding.to_dict() for finding in self.findings]
+        return data
+
+
+@dataclass
+class AgentOutput:
+    agent_name: str
+    summary: str
+    artifacts: dict[str, Any] = field(default_factory=dict)
+    created_at: str = field(default_factory=utc_now_iso)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class ReportState:
+    draft_markdown: str = ""
+    prepared_markdown: str = ""
+    sections: list[BriefSection] = field(default_factory=list)
+    audit_report: AuditReport | None = None
+    final_clean_report: dict[str, Any] | None = None
+
+
+@dataclass
+class PipelineContext:
+    project_name: str
+    input_dir: str
+    output_dir: str
+    language: str = "en-US"
+    audience: str = "management"
+    audience_profile: str = ""  # mapped profile ID (management, research, ir, legal_compliance, default)
+    report_date: str = ""
+    max_source_age_days: int | None = None
+    fail_on_stale_source: bool = False
+    previous_report_dir: str = ""
+    previous_report_text: str = ""
+    max_claims: int = 160
+    quiet_week_min_claims: int = 5
+    sources: list[SourceItem] = field(default_factory=list)
+    candidates: list[CandidateItem] = field(default_factory=list)
+    report_state: ReportState = field(default_factory=ReportState)
+    output_formats: list[str] = field(default_factory=lambda: ["markdown"])
+    output_footer: str = ""
+    output_filename_template: str = ""
+    output_filename_tokens: dict[str, str] = field(default_factory=dict)
+    output_named_outputs: bool = True
+    metadata: dict[str, Any] = field(default_factory=dict)