briefloop 0.11.12__py3-none-any.whl

multi_agent_brief/core/selection.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from multi_agent_brief.audit.deterministic import parse_date
+from multi_agent_brief.core.claim_ledger import ClaimLedger
+from multi_agent_brief.core.schemas import Claim, PipelineContext
+
+
+@dataclass
+class SelectionResult:
+    selected: list[Claim]
+    excluded: list[dict] = field(default_factory=list)
+    stats: dict = field(default_factory=dict)
+
+
+TOPIC_CAPS = {
+    "policy": 24,
+    "compliance": 18,
+    "earnings": 24,
+    "competitor": 18,
+    "market": 24,
+    "demand": 18,
+    "rates": 12,
+    "capital": 14,
+    "technology": 12,
+    "general": 18,
+}
+
+
+def select_reportable_claims(
+    ledger: ClaimLedger,
+    context: PipelineContext,
+    previous_report_text: str = "",
+) -> SelectionResult:
+    scored: list[tuple[str, int, Claim]] = []
+    excluded: list[dict] = []
+
+    for claim in ledger:
+        reason = exclusion_reason(claim, context)
+        if reason:
+            claim.metadata["excluded_reason"] = reason
+            excluded.append({"claim_id": claim.claim_id, "reason": reason, "statement": claim.statement})
+            continue
+
+        topic = infer_topic(claim)
+        repeat = previous_report_topic_hit(claim_search_text(claim), previous_report_text)
+        score = novelty_score(claim, topic, repeat)
+        claim.metadata.update({"topic": topic, "repeat": repeat, "novelty_score": score})
+        scored.append((topic, score, claim))
+
+    selected: list[Claim] = []
+    omitted_by_topic: dict[str, int] = {}
+    for topic, cap in TOPIC_CAPS.items():
+        bucket = [item for item in scored if item[0] == topic]
+        bucket.sort(key=lambda item: item[1], reverse=True)
+        selected.extend(item[2] for item in bucket[:cap])
+        if len(bucket) > cap:
+            omitted_by_topic[topic] = len(bucket) - cap
+
+    selected.sort(key=lambda claim: int(claim.metadata.get("novelty_score", 0)), reverse=True)
+    selected = selected[: context.max_claims]
+
+    return SelectionResult(
+        selected=selected,
+        excluded=excluded,
+        stats={
+            "input_claims": len(ledger),
+            "selected_claims": len(selected),
+            "excluded_claims": len(excluded),
+            "omitted_by_topic": omitted_by_topic,
+            "repeat_claims": sum(1 for claim in selected if claim.metadata.get("repeat") is True),
+            "quiet_week": len(selected) < context.quiet_week_min_claims,
+        },
+    )
+
+
+def ledger_from_selected(result: SelectionResult) -> ClaimLedger:
+    return ClaimLedger(result.selected)
+
+
+def exclusion_reason(claim: Claim, context: PipelineContext) -> str:
+    if claim.claim_type == "needs_recrawl":
+        return "needs_recrawl"
+    if str(claim.metadata.get("source_tier", "")) == "T5":
+        return "low_confidence_source"
+    report_day = parse_date(context.report_date)
+    published_day = parse_date(str(claim.metadata.get("published_at", "")))
+    if report_day and published_day and context.max_source_age_days is not None:
+        if (report_day - published_day).days > context.max_source_age_days:
+            return "stale_source"
+    return ""
+
+
+def claim_search_text(claim: Claim) -> str:
+    return " ".join(
+        str(part or "")
+        for part in (
+            claim.claim_id,
+            claim.statement,
+            claim.evidence_text,
+            claim.source_id,
+            claim.source_url,
+            claim.claim_type,
+            claim.metadata.get("source_tier", ""),
+        )
+    )
+
+
+def compact_text_for_match(text: str) -> str:
+    return re.sub(r"[\W_]+", "", (text or "").lower(), flags=re.UNICODE)
+
+
+def previous_report_topic_hit(text: str, previous_report_text: str) -> bool:
+    if not text or not previous_report_text:
+        return False
+    compact = compact_text_for_match(text)
+    previous = compact_text_for_match(previous_report_text)
+    if len(compact) >= 32 and (compact[:80] in previous or compact[:48] in previous):
+        return True
+    theme_groups = [
+        ("adcvd", "antidumping", "countervailing"),
+        ("feoc", "45x", "48e"),
+        ("uflpa", "detain", "forcedlabor"),
+        ("chapter11", "bankrupt", "residential"),
+        ("section337", "topcon", "patent"),
+    ]
+    for group in theme_groups:
+        hits = sum(1 for term in group if term in compact and term in previous)
+        if hits >= 2:
+            return True
+    return False
+
+
+def infer_topic(claim: Claim) -> str:
+    text = claim_search_text(claim).lower()
+    if any(term in text for term in ("ad/cvd", "antidumping", "countervailing", "tariff", "section 337", "policy", "regulation")):
+        return "policy"
+    if any(term in text for term in ("uflpa", "cbp", "detain", "forced labor", "compliance")):
+        return "compliance"
+    if any(term in text for term in ("revenue", "eps", "ebitda", "gross margin", "earnings", "backlog", "guidance")):
+        return "earnings"
+    if any(term in text for term in ("competitor", "capacity", "expansion", "plant", "launch")):
+        return "competitor"
+    if any(term in text for term in ("price", "demand", "inventory", "market")):
+        return "market"
+    if any(term in text for term in ("installation", "generation", "ppa", "interconnection", "load growth")):
+        return "demand"
+    if any(term in text for term in ("treasury", "yield", "sofr", "fed", "rate")):
+        return "rates"
+    if any(term in text for term in ("acquisition", "investment", "fund", "capital")):
+        return "capital"
+    if any(term in text for term in ("topcon", "hjt", "bc", "technology", "efficiency")):
+        return "technology"
+    return "general"
+
+
+def novelty_score(claim: Claim, topic: str, repeat: bool) -> int:
+    text = claim_search_text(claim).lower()
+    score = 10
+    tier = str(claim.metadata.get("source_tier", "") or "")
+    score += {"T1": 28, "T2": 24, "T3": 18, "T4": 14, "T5": 2}.get(tier, 8)
+    if claim.claim_type in {"number", "date"}:
+        score += 8
+    if claim.claim_type in {"risk", "forecast"}:
+        score += 6
+    high_signal_terms = [
+        "tariff",
+        "section 337",
+        "investigation",
+        "earnings",
+        "eps",
+        "ebitda",
+        "backlog",
+        "guidance",
+        "bankrupt",
+        "acquisition",
+        "capex",
+        "data center",
+        "storage",
+    ]
+    score += sum(6 for term in high_signal_terms if term in text)
+    if topic in {"policy", "earnings", "market"}:
+        score += 4
+    if repeat:
+        score -= 35
+    return score
+

multi_agent_brief/delivery/__init__.py

@@ -0,0 +1,6 @@
+"""Delivery connector interfaces."""
+
+from multi_agent_brief.delivery.base import DeliveryArtifact, DeliveryResult, DeliveryTarget
+
+__all__ = ["DeliveryArtifact", "DeliveryResult", "DeliveryTarget"]
+

multi_agent_brief/delivery/base.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class DeliveryArtifact:
+    path: str
+    title: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class DeliveryTarget:
+    channel: str
+    recipient: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class DeliveryResult:
+    connector_name: str
+    delivered: bool
+    message: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class DeliveryConnector(ABC):
+    name = "delivery-connector"
+
+    @abstractmethod
+    def deliver(self, artifact: DeliveryArtifact, target: DeliveryTarget) -> DeliveryResult:
+        raise NotImplementedError
+

multi_agent_brief/delivery/feishu.py

@@ -0,0 +1,204 @@
+"""Feishu/Lark delivery connector using lark-cli.
+
+Sends briefs to Feishu via:
+  - IM message (lark-cli im +messages-send --as bot)
+  - Document creation (lark-cli docs +create)
+  - File upload (lark-cli drive +upload)
+
+Requires lark-cli to be installed and authenticated.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from multi_agent_brief.delivery.base import DeliveryArtifact, DeliveryConnector, DeliveryResult, DeliveryTarget
+
+# Max text length for IM messages (Feishu limit ~150k chars, conservative)
+IM_MAX_LENGTH = 50000
+
+
+class FeishuDeliveryConnector(DeliveryConnector):
+    """Deliver brief artifacts to Feishu via lark-cli.
+
+    Supported channels:
+      - chat: send as text message to a group or user chat
+      - doc: create a Feishu document with the brief content
+      - drive: upload the brief file to Feishu Drive
+
+    Target recipient format:
+      - chat: chat_id (oc_xxx) or user open_id (ou_xxx)
+      - doc: folder_token (optional, defaults to root)
+      - drive: folder_token (optional, defaults to root)
+    """
+
+    name = "feishu"
+
+    def deliver(self, artifact: DeliveryArtifact, target: DeliveryTarget) -> DeliveryResult:
+        """Deliver a brief artifact to a Feishu target.
+
+        Args:
+            artifact: The brief file to deliver (path + title).
+            target:
+                - channel='chat', recipient='oc_xxx' (chat_id) or 'ou_xxx' (user_id)
+                - channel='doc', recipient='folder_token' (optional)
+                - channel='drive', recipient='folder_token' (optional)
+
+        Returns:
+            DeliveryResult with delivery status and message.
+        """
+        # Check prerequisites
+        if not shutil.which("lark-cli"):
+            return DeliveryResult(
+                self.name, False,
+                "feishu: 'lark-cli' not found. Install: npx @larksuite/cli@latest install",
+            )
+
+        path = Path(artifact.path)
+        if not path.exists():
+            return DeliveryResult(self.name, False, f"feishu: artifact not found: {artifact.path}")
+
+        title = artifact.title or path.stem
+
+        channel = target.channel or "chat"
+
+        if channel == "chat":
+            return self._deliver_chat(path, title, target)
+        elif channel == "doc":
+            return self._deliver_doc(path, title, target)
+        elif channel == "drive":
+            return self._deliver_drive(path, title, target)
+        else:
+            return DeliveryResult(
+                self.name, False,
+                f"feishu: unknown channel '{channel}'. Supported: chat, doc, drive",
+            )
+
+    def _check_auth(self) -> str | None:
+        """Check lark-cli auth status. Returns error message or None if OK."""
+        try:
+            result = subprocess.run(
+                ["lark-cli", "auth", "status"],
+                capture_output=True, text=True, timeout=10,
+            )
+            if result.returncode != 0:
+                return "feishu: not authenticated. Run: lark-cli auth login --recommend"
+            return None
+        except (FileNotFoundError, subprocess.TimeoutExpired) as e:
+            return f"feishu: unable to check auth: {e}"
+
+    def _run_lark_cli(self, args: list[str]) -> subprocess.CompletedProcess | None:
+        """Run lark-cli and return result.
+
+        Disables proxy (LARK_CLI_NO_PROXY=1) so lark-cli does not route
+        credentials through HTTPS_PROXY.  Also resolves any file path
+        arguments to absolute paths to avoid lark-cli's cwd-traversal guard.
+        """
+        env = {**os.environ, "LARK_CLI_NO_PROXY": "1"}
+        # Resolve --file paths to absolute to avoid lark-cli rejecting ".."
+        resolved_args: list[str] = []
+        skip_next = False
+        for i, arg in enumerate(args):
+            if skip_next:
+                resolved_args.append(arg)
+                skip_next = False
+                continue
+            if arg == "--file" and i + 1 < len(args):
+                resolved_args.append("--file")
+                resolved_args.append(str(Path(args[i + 1]).resolve()))
+                skip_next = True
+            else:
+                resolved_args.append(arg)
+
+        try:
+            return subprocess.run(
+                ["lark-cli"] + resolved_args,
+                capture_output=True, text=True, timeout=60, env=env,
+            )
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return None
+
+    def _deliver_chat(self, path: Path, title: str, target: DeliveryTarget) -> DeliveryResult:
+        """Send brief content as IM message."""
+        auth_err = self._check_auth()
+        if auth_err:
+            return DeliveryResult(self.name, False, auth_err)
+
+        chat_id = target.recipient or target.metadata.get("chat_id", "")
+        if not chat_id:
+            return DeliveryResult(self.name, False, "feishu (chat): no chat_id provided")
+
+        # Read file content (truncate for IM limits)
+        try:
+            content = path.read_text(encoding="utf-8")[:IM_MAX_LENGTH]
+        except Exception as e:
+            return DeliveryResult(self.name, False, f"feishu (chat): failed to read artifact: {e}")
+
+        result = self._run_lark_cli([
+            "im", "+messages-send",
+            "--chat-id", chat_id,
+            "--as", "bot",
+            "--text", content,
+        ])
+        if result is None or result.returncode != 0:
+            stderr = (result.stderr or "").strip() if result else "command failed"
+            return DeliveryResult(self.name, False, f"feishu (chat): {stderr[:200]}")
+
+        return DeliveryResult(self.name, True, f"Sent to chat {chat_id}")
+
+    def _deliver_doc(self, path: Path, title: str, target: DeliveryTarget) -> DeliveryResult:
+        """Create a Feishu document from brief content."""
+        auth_err = self._check_auth()
+        if auth_err:
+            return DeliveryResult(self.name, False, auth_err)
+
+        try:
+            content = path.read_text(encoding="utf-8")
+        except Exception as e:
+            return DeliveryResult(self.name, False, f"feishu (doc): failed to read artifact: {e}")
+
+        # Build doc content with title
+        doc_content = f"<title>{title}</title>\n{content}"
+
+        result = self._run_lark_cli([
+            "docs", "+create",
+            "--api-version", "v2",
+            "--doc-format", "markdown",
+            "--content", doc_content,
+        ])
+        if result is None or result.returncode != 0:
+            stderr = (result.stderr or "").strip()[:200] if result else "command failed"
+            return DeliveryResult(self.name, False, f"feishu (doc): {stderr}")
+
+        # Try to extract the doc URL from output
+        try:
+            output = json.loads(result.stdout) if result.stdout else {}
+            doc_url = output.get("url", output.get("data", {}).get("url", ""))
+        except (json.JSONDecodeError, AttributeError):
+            doc_url = ""
+
+        msg = f"Doc created: {title}"
+        if doc_url:
+            msg += f" ({doc_url})"
+        return DeliveryResult(self.name, True, msg, metadata={"url": doc_url})
+
+    def _deliver_drive(self, path: Path, title: str, target: DeliveryTarget) -> DeliveryResult:
+        """Upload brief file to Feishu Drive."""
+        auth_err = self._check_auth()
+        if auth_err:
+            return DeliveryResult(self.name, False, auth_err)
+
+        folder_token = target.recipient or ""
+        args = ["drive", "+upload", "--file", str(path)]
+        if folder_token:
+            args.extend(["--folder-token", folder_token])
+
+        result = self._run_lark_cli(args)
+        if result is None or result.returncode != 0:
+            stderr = (result.stderr or "").strip()[:200] if result else "command failed"
+            return DeliveryResult(self.name, False, f"feishu (drive): {stderr}")
+
+        return DeliveryResult(self.name, True, f"Uploaded {path.name} to Drive")

multi_agent_brief/delivery/gws.py

@@ -0,0 +1,237 @@
+"""Gmail delivery connector using the optional gws CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from multi_agent_brief.delivery.base import DeliveryArtifact, DeliveryConnector, DeliveryResult, DeliveryTarget
+
+
+@dataclass(frozen=True)
+class _GwsTimeout:
+    args: tuple[str, ...]
+
+
+class GwsGmailDeliveryConnector(DeliveryConnector):
+    """Create Gmail drafts or send Gmail messages through the optional gws CLI."""
+
+    name = "gmail"
+
+    def deliver(self, artifact: DeliveryArtifact, target: DeliveryTarget) -> DeliveryResult:
+        if target.channel not in {"draft", "send"}:
+            return DeliveryResult(self.name, False, "gmail: supported channels are 'draft' and 'send'")
+        if not target.recipient:
+            return DeliveryResult(self.name, False, "gmail: --recipient is required")
+
+        path = Path(artifact.path)
+        if not path.exists():
+            return DeliveryResult(self.name, False, f"gmail: artifact not found: {artifact.path}")
+
+        if not shutil.which("gws"):
+            return DeliveryResult(
+                self.name,
+                False,
+                "gmail: 'gws' not found. Install googleworkspace/cli and run gws auth setup/login.",
+            )
+
+        auth_error = self._check_auth()
+        if auth_error:
+            return DeliveryResult(self.name, False, auth_error)
+
+        subject = _metadata_text(target.metadata.get("subject")) or artifact.title or path.stem
+        body = _metadata_text(target.metadata.get("body")) or "Please review the attached BriefLoop delivery."
+        attachments = _metadata_list(target.metadata.get("attachments")) or [str(path)]
+        attachment_paths = [Path(attachment).expanduser().resolve() for attachment in attachments]
+        if any(not attachment.exists() for attachment in attachment_paths):
+            return DeliveryResult(self.name, False, "gmail: attachment not found")
+        attachment_cwd = Path(os.path.commonpath([str(attachment.parent) for attachment in attachment_paths]))
+
+        args = [
+            "gmail",
+            "+send",
+            "--to",
+            target.recipient,
+            "--subject",
+            subject,
+            "--body",
+            body,
+        ]
+        if target.channel == "draft":
+            args.append("--draft")
+        for attachment in attachment_paths:
+            args.extend(["--attach", attachment.relative_to(attachment_cwd).as_posix()])
+
+        result = self._run_gws(args, cwd=attachment_cwd)
+        if isinstance(result, _GwsTimeout):
+            action = "draft creation" if target.channel == "draft" else "send"
+            inspect_target = "Gmail Drafts" if target.channel == "draft" else "Gmail Sent Mail"
+            return DeliveryResult(
+                self.name,
+                False,
+                f"gmail: gws {action} timed out after the Gmail request may have been accepted. "
+                f"Inspect {inspect_target} before retrying; do not retry blindly.",
+                metadata={
+                    "outcome_unknown": True,
+                    "timeout": True,
+                    "inspect_target": inspect_target,
+                },
+            )
+        if result is None:
+            return DeliveryResult(self.name, False, "gmail: gws command failed")
+        if result.returncode != 0:
+            action = "draft creation" if target.channel == "draft" else "send"
+            return DeliveryResult(
+                self.name,
+                False,
+                f"gmail: gws {action} failed. Check gws auth, Gmail permissions, recipient, and attachment access.",
+            )
+
+        if target.channel == "draft":
+            metadata = _draft_metadata(result.stdout)
+            if not metadata.get("draft_id_present"):
+                return DeliveryResult(
+                    self.name,
+                    False,
+                    "gmail: gws did not confirm Gmail draft creation. "
+                    "Inspect Gmail Drafts before retrying; do not retry blindly.",
+                )
+            return DeliveryResult(
+                self.name,
+                True,
+                "Gmail draft created",
+                metadata=metadata,
+            )
+
+        metadata = _message_metadata(result.stdout)
+        if not metadata.get("sent_message_present"):
+            return DeliveryResult(
+                self.name,
+                False,
+                "gmail: gws did not confirm Gmail send. "
+                "Inspect Gmail Sent Mail before retrying; do not retry blindly.",
+            )
+        return DeliveryResult(
+            self.name,
+            True,
+            "Gmail message sent",
+            metadata=metadata,
+        )
+
+    def _check_auth(self) -> str | None:
+        result = self._run_gws(["auth", "status"], timeout=10)
+        if result is None or isinstance(result, _GwsTimeout):
+            return "gmail: unable to check gws auth. Run: gws auth setup; gws auth login"
+        if result.returncode != 0:
+            if _has_external_auth_signal():
+                return None
+            return "gmail: gws is not authenticated. Run: gws auth setup; gws auth login"
+        payload = _json_object_from_output(result.stdout)
+        if payload is None:
+            return None
+        if isinstance(payload, dict) and payload.get("auth_method") == "none" and not _has_external_auth_signal():
+            return "gmail: gws is not authenticated. Run: gws auth setup; gws auth login"
+        return None
+
+    def _run_gws(
+        self,
+        args: list[str],
+        *,
+        timeout: int = 60,
+        cwd: Path | None = None,
+    ) -> subprocess.CompletedProcess[str] | _GwsTimeout | None:
+        env = {**os.environ}
+        try:
+            return subprocess.run(
+                ["gws", *args],
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                cwd=str(cwd) if cwd is not None else None,
+                env=env,
+            )
+        except FileNotFoundError:
+            return None
+        except subprocess.TimeoutExpired:
+            return _GwsTimeout(tuple(args))
+
+
+def _metadata_text(value: Any) -> str:
+    return value.strip() if isinstance(value, str) and value.strip() else ""
+
+
+def _metadata_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [str(item) for item in value if str(item).strip()]
+
+
+def _has_external_auth_signal() -> bool:
+    if any(
+        os.environ.get(name)
+        for name in (
+            "GOOGLE_WORKSPACE_CLI_TOKEN",
+            "GWS_TOKEN",
+            "GOOGLE_APPLICATION_CREDENTIALS",
+        )
+    ):
+        return True
+    return any(path.exists() for path in _well_known_adc_paths())
+
+
+def _well_known_adc_paths() -> list[Path]:
+    paths: list[Path] = []
+    cloudsdk_config = os.environ.get("CLOUDSDK_CONFIG")
+    if cloudsdk_config:
+        paths.append(Path(cloudsdk_config).expanduser() / "application_default_credentials.json")
+    paths.append(Path.home() / ".config" / "gcloud" / "application_default_credentials.json")
+    appdata = os.environ.get("APPDATA")
+    if appdata:
+        paths.append(Path(appdata).expanduser() / "gcloud" / "application_default_credentials.json")
+    return paths
+
+
+def _json_object_from_output(stdout: str) -> dict[str, Any] | None:
+    text = stdout.strip()
+    if not text:
+        return {}
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError:
+        start = text.find("{")
+        end = text.rfind("}")
+        if start < 0 or end < start:
+            return None
+        try:
+            payload = json.loads(text[start : end + 1])
+        except json.JSONDecodeError:
+            return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _draft_metadata(stdout: str) -> dict[str, Any]:
+    payload = _json_object_from_output(stdout)
+    if payload is None:
+        return {}
+    data = payload.get("data") if isinstance(payload.get("data"), dict) else {}
+    draft_id = payload.get("id") or payload.get("draft_id") or data.get("id")
+    if isinstance(draft_id, str) and draft_id.strip():
+        return {"draft_id_present": True}
+    return {}
+
+
+def _message_metadata(stdout: str) -> dict[str, Any]:
+    payload = _json_object_from_output(stdout)
+    if payload is None:
+        return {}
+    data = payload.get("data") if isinstance(payload.get("data"), dict) else {}
+    message = payload.get("message") if isinstance(payload.get("message"), dict) else {}
+    sent_ref = payload.get("message" + "_id") or payload.get("id") or message.get("id") or data.get("id")
+    if isinstance(sent_ref, str) and sent_ref.strip():
+        return {"sent_message_present": True}
+    return {}

multi_agent_brief/evaluation_cases/__init__.py

@@ -0,0 +1,15 @@
+"""Public-safe evaluation case runner for MABW control surfaces."""
+
+from __future__ import annotations
+
+from multi_agent_brief.evaluation_cases.runner import (
+    list_evaluation_cases,
+    run_evaluation_cases,
+    validate_evaluation_cases,
+)
+
+__all__ = [
+    "list_evaluation_cases",
+    "run_evaluation_cases",
+    "validate_evaluation_cases",
+]