briefloop 0.11.12__py3-none-any.whl

multi_agent_brief/audience_memory/profile.py

@@ -0,0 +1,358 @@
+"""Audience profile runtime surface helpers.
+
+This module owns workspace-local taste context files. It deliberately does not
+import CLI profile types so runtime code can use it without a CLI dependency.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping
+
+import yaml
+
+
+AUDIENCE_MEMORY_FILES = {
+    "audience_profile": "audience_profile.md",
+    "audience_profile_snapshot": "output/intermediate/audience_profile_snapshot.md",
+}
+
+_SNAPSHOT_MARKER = "<!-- mabw:audience-profile-snapshot"
+_SNAPSHOT_END = "-->"
+
+
+@dataclass(frozen=True)
+class AudienceProfileResult:
+    path: Path
+    relative_path: str
+    created: bool
+    missing: bool
+    sha256: str
+
+
+@dataclass(frozen=True)
+class AudienceSnapshotResult:
+    path: Path
+    relative_path: str
+    created: bool
+    stale_rebuilt: bool
+    run_id: str
+    source_sha256: str
+    captured_body_sha256: str
+    snapshot_sha256: str
+    profile_created: bool
+    profile_missing: bool
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _workspace_path(workspace: str | Path, rel_path: str) -> Path:
+    ws = Path(workspace).expanduser().resolve()
+    path = (ws / rel_path).resolve()
+    try:
+        path.relative_to(ws)
+    except ValueError as exc:
+        raise ValueError(f"Audience memory path escapes workspace: {rel_path}") from exc
+    return path
+
+
+def _write_text_atomic(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
+    try:
+        tmp.write_text(text, encoding="utf-8")
+        os.replace(tmp, path)
+    finally:
+        try:
+            tmp.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+
+def _as_text(value: Any, default: str = "") -> str:
+    if value is None:
+        return default
+    text = str(value).strip()
+    return text if text else default
+
+
+def _as_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, (list, tuple, set)):
+        return [str(item).strip() for item in value if str(item).strip()]
+    text = str(value).strip()
+    if not text:
+        return []
+    return [part.strip() for part in text.replace(";", ",").split(",") if part.strip()]
+
+
+def profile_data_from_object(profile: Any) -> dict[str, Any]:
+    """Convert an arbitrary profile-like object into plain profile data."""
+    fields = [
+        "company",
+        "industry",
+        "industry_text",
+        "role",
+        "audience",
+        "audience_profile",
+        "brief_title",
+        "task_objective",
+        "interface_language",
+        "output_language",
+        "cadence",
+        "source_profile",
+        "focus_areas",
+        "forbidden_sources",
+        "output_formats",
+    ]
+    return {field: getattr(profile, field, "") for field in fields}
+
+
+def profile_data_from_workspace_config(workspace: str | Path) -> dict[str, Any]:
+    """Extract audience profile defaults from an existing workspace config."""
+    config_path = Path(workspace).expanduser().resolve() / "config.yaml"
+    if not config_path.exists():
+        return {}
+    data = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    if not isinstance(data, dict):
+        return {}
+
+    project = data.get("project") or {}
+    audience_profile = data.get("audience_profile") or {}
+    language = data.get("language") or {}
+    report = data.get("report") or {}
+    source = data.get("source") or {}
+    source_strategy = data.get("source_strategy") or {}
+    output = data.get("output") or {}
+    task = data.get("task") or {}
+
+    formats = output.get("formats") if isinstance(output, dict) else []
+    if not isinstance(formats, list):
+        formats = []
+
+    return {
+        "company": project.get("company") or project.get("organization") or project.get("name") or "",
+        "industry": project.get("industry") or "",
+        "industry_text": project.get("industry") or "",
+        "role": project.get("role") or "",
+        "audience": project.get("audience") or "",
+        "audience_profile": audience_profile.get("id") or "",
+        "brief_title": project.get("name") or "",
+        "task_objective": task.get("objective") or "",
+        "interface_language": language.get("interface") or "",
+        "output_language": language.get("output") or "",
+        "cadence": report.get("cadence") or "",
+        "source_profile": source.get("mode") or source_strategy.get("profile") or "",
+        "output_formats": formats,
+    }
+
+
+def build_default_audience_profile(profile_data: Mapping[str, Any] | None = None) -> str:
+    """Build a human-editable audience profile Markdown template."""
+    data = dict(profile_data or {})
+    company = _as_text(data.get("company"), "Unknown organization")
+    industry = _as_text(data.get("industry_text") or data.get("industry"), "Unknown industry/theme")
+    audience = _as_text(data.get("audience"), "management")
+    profile_id = _as_text(data.get("audience_profile"), "default")
+    title = _as_text(data.get("brief_title"), "Workspace brief")
+    objective = _as_text(data.get("task_objective"), "Summarize material updates for the target reader.")
+    language = _as_text(data.get("output_language") or data.get("interface_language"), "en-US")
+    cadence = _as_text(data.get("cadence"), "weekly")
+    role = _as_text(data.get("role"), "strategy_office")
+    source_profile = _as_text(data.get("source_profile"), "llm_decide")
+    focus_areas = _as_list(data.get("focus_areas"))
+    forbidden_sources = _as_list(data.get("forbidden_sources"))
+    output_formats = _as_list(data.get("output_formats"))
+
+    focus_lines = "\n".join(f"- {item}" for item in focus_areas) or "- Add durable audience priorities here."
+    avoid_lines = "\n".join(f"- {item}" for item in forbidden_sources) or "- Do not let taste preferences override evidence or audit constraints."
+    output_lines = "\n".join(f"- {item}" for item in output_formats) or "- Markdown\n- DOCX"
+
+    return (
+        "# Audience Profile\n\n"
+        "This workspace-local file records reader taste, department preferences, and recurring editorial guidance.\n"
+        "It is not source evidence, not a correctness contract, and not a stage gate.\n"
+        "Human edits are allowed. Mid-run edits apply to the next run after a new snapshot is created.\n\n"
+        "## Reader Context\n\n"
+        f"- Organization: {company}\n"
+        f"- Industry/theme: {industry}\n"
+        f"- Reader/audience: {audience}\n"
+        f"- Audience profile id: {profile_id}\n"
+        f"- Internal role/use context: {role}\n"
+        f"- Brief title: {title}\n"
+        f"- Cadence: {cadence}\n"
+        f"- Output language: {language}\n"
+        f"- Source mode: {source_profile}\n\n"
+        "## Decision Use\n\n"
+        f"{objective}\n\n"
+        "## Preferred Brief Style\n\n"
+        "- Start with the decision-useful conclusion when evidence supports it.\n"
+        "- Keep claims bounded by source quality, freshness, and uncertainty.\n"
+        "- Prefer concise, concrete implications over generic narrative.\n\n"
+        "## Tone And Structure Preferences\n\n"
+        "- Write for the stated reader, not for a generic public audience.\n"
+        "- Preserve auditability during drafting; reader-facing cleanup happens after audit.\n"
+        "- Surface risks, caveats, and missing evidence clearly when relevant.\n\n"
+        "## Focus Areas\n\n"
+        f"{focus_lines}\n\n"
+        "## Output Expectations\n\n"
+        f"{output_lines}\n\n"
+        "## Recurring Feedback\n\n"
+        "- Add durable feedback patterns here after human review.\n\n"
+        "## Avoid\n\n"
+        f"{avoid_lines}\n\n"
+        "## Human Notes\n\n"
+        "- Add workspace-specific taste notes here.\n"
+    )
+
+
+def ensure_audience_profile(
+    workspace: str | Path,
+    profile_data: Mapping[str, Any] | None = None,
+) -> AudienceProfileResult:
+    """Ensure the workspace has an audience profile."""
+    path = _workspace_path(workspace, AUDIENCE_MEMORY_FILES["audience_profile"])
+    missing = not path.exists()
+    created = False
+    if missing:
+        _write_text_atomic(path, build_default_audience_profile(profile_data))
+        created = True
+    return AudienceProfileResult(
+        path=path,
+        relative_path=AUDIENCE_MEMORY_FILES["audience_profile"],
+        created=created,
+        missing=missing,
+        sha256=sha256_file(path),
+    )
+
+
+def _parse_snapshot_metadata(text: str) -> dict[str, str] | None:
+    """Parse only the strict top-of-file audience snapshot metadata block."""
+    if not text.startswith(_SNAPSHOT_MARKER):
+        return None
+    end = text.find(_SNAPSHOT_END)
+    if end == -1:
+        return None
+    block = text[len(_SNAPSHOT_MARKER):end].strip()
+    metadata: dict[str, str] = {}
+    for line in block.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        if ":" not in line:
+            return None
+        key, value = line.split(":", 1)
+        key = key.strip()
+        value = value.strip()
+        if not key or not value:
+            return None
+        metadata[key] = value
+    required = {"run_id", "source", "created_at", "source_sha256", "captured_body_sha256"}
+    if not required.issubset(metadata):
+        return None
+    if metadata.get("source") != AUDIENCE_MEMORY_FILES["audience_profile"]:
+        return None
+    return metadata
+
+
+def _snapshot_text(
+    *,
+    run_id: str,
+    created_at: str,
+    source_sha256: str,
+    captured_body_sha256: str,
+    profile_body: str,
+) -> str:
+    body = profile_body.rstrip() + "\n"
+    return (
+        "<!-- mabw:audience-profile-snapshot\n"
+        f"run_id: {run_id}\n"
+        f"source: {AUDIENCE_MEMORY_FILES['audience_profile']}\n"
+        f"created_at: {created_at}\n"
+        f"source_sha256: {source_sha256}\n"
+        f"captured_body_sha256: {captured_body_sha256}\n"
+        "-->\n\n"
+        "# Audience Profile Snapshot\n\n"
+        f"- Run ID: {run_id}\n"
+        f"- Source: {AUDIENCE_MEMORY_FILES['audience_profile']}\n"
+        f"- Created at: {created_at}\n"
+        f"- Source SHA256: {source_sha256}\n"
+        f"- Captured Body SHA256: {captured_body_sha256}\n"
+        "- Run behavior: use this snapshot for the current run.\n"
+        f"- Mid-run edits to {AUDIENCE_MEMORY_FILES['audience_profile']} apply to later runs only.\n\n"
+        "## Captured Audience Profile\n\n"
+        f"{body}"
+    )
+
+
+def create_audience_profile_snapshot(
+    workspace: str | Path,
+    *,
+    run_id: str,
+    profile_data: Mapping[str, Any] | None = None,
+) -> AudienceSnapshotResult:
+    """Create or reuse the active run audience profile snapshot."""
+    profile = ensure_audience_profile(workspace, profile_data)
+    snapshot_path = _workspace_path(workspace, AUDIENCE_MEMORY_FILES["audience_profile_snapshot"])
+
+    if snapshot_path.exists():
+        existing_text = snapshot_path.read_text(encoding="utf-8")
+        metadata = _parse_snapshot_metadata(existing_text)
+        if metadata and metadata.get("run_id") == run_id:
+            return AudienceSnapshotResult(
+                path=snapshot_path,
+                relative_path=AUDIENCE_MEMORY_FILES["audience_profile_snapshot"],
+                created=False,
+                stale_rebuilt=False,
+                run_id=run_id,
+                source_sha256=metadata["source_sha256"],
+                captured_body_sha256=metadata["captured_body_sha256"],
+                snapshot_sha256=sha256_file(snapshot_path),
+                profile_created=profile.created,
+                profile_missing=profile.missing,
+            )
+
+    profile_body = profile.path.read_text(encoding="utf-8")
+    source_sha256 = sha256_text(profile_body)
+    captured_body_sha256 = source_sha256
+    text = _snapshot_text(
+        run_id=run_id,
+        created_at=utc_now(),
+        source_sha256=source_sha256,
+        captured_body_sha256=captured_body_sha256,
+        profile_body=profile_body,
+    )
+    stale_rebuilt = snapshot_path.exists()
+    _write_text_atomic(snapshot_path, text)
+    return AudienceSnapshotResult(
+        path=snapshot_path,
+        relative_path=AUDIENCE_MEMORY_FILES["audience_profile_snapshot"],
+        created=True,
+        stale_rebuilt=stale_rebuilt,
+        run_id=run_id,
+        source_sha256=source_sha256,
+        captured_body_sha256=captured_body_sha256,
+        snapshot_sha256=sha256_file(snapshot_path),
+        profile_created=profile.created,
+        profile_missing=profile.missing,
+    )

multi_agent_brief/audit/__init__.py

@@ -0,0 +1,36 @@
+"""Audit utilities."""
+
+from multi_agent_brief.audit.deterministic import DeterministicAuditAgent, run_deterministic_audit
+from multi_agent_brief.audit.final_quality import FinalQualityAuditAgent, FinalQualityConfig
+from multi_agent_brief.audit.harness import QualityHarnessAuditAgent
+from multi_agent_brief.audit.interfaces import AuditAgentInterface, CompositeAuditAgent
+from multi_agent_brief.audit.semantic import (
+    SEMANTIC_SUPPORT_CALIBRATION_METADATA_KEY,
+    SEMANTIC_SUPPORT_INVALID_CALIBRATION_LABEL,
+    SEMANTIC_SUPPORT_PROPOSAL_FINDING_TYPE,
+    SEMANTIC_SUPPORT_PROPOSAL_LABELS,
+    NoOpSemanticAuditAgent,
+    SemanticAuditPromptBuilder,
+    findings_from_semantic_proposal_rows,
+    normalize_calibration_label,
+    semantic_support_proposal_finding,
+)
+
+__all__ = [
+    "SEMANTIC_SUPPORT_CALIBRATION_METADATA_KEY",
+    "SEMANTIC_SUPPORT_INVALID_CALIBRATION_LABEL",
+    "SEMANTIC_SUPPORT_PROPOSAL_FINDING_TYPE",
+    "SEMANTIC_SUPPORT_PROPOSAL_LABELS",
+    "normalize_calibration_label",
+    "AuditAgentInterface",
+    "CompositeAuditAgent",
+    "DeterministicAuditAgent",
+    "FinalQualityAuditAgent",
+    "FinalQualityConfig",
+    "NoOpSemanticAuditAgent",
+    "QualityHarnessAuditAgent",
+    "SemanticAuditPromptBuilder",
+    "findings_from_semantic_proposal_rows",
+    "run_deterministic_audit",
+    "semantic_support_proposal_finding",
+]

multi_agent_brief/audit/case_applicability.py

@@ -0,0 +1,181 @@
+"""Comparable Case Applicability audit (v0.5.3 PR 3).
+
+Enforces boundaries on analogous/comparable evidence:
+1. evidence_relation=analogous MUST have applicability_reason.
+2. Single comparable case can only support hypothesis/to_verify, NOT strong action.
+3. No local direct evidence → must generate verification_path.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+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
+
+
+@dataclass
+class CaseApplicabilityFinding:
+    """One audit finding for case applicability."""
+
+    finding_type: str
+    severity: str  # "warning" or "fail"
+    block_id: str
+    claim_id: str
+    description: str
+    recommendation: str
+
+
+def audit_case_applicability(
+    blocks: list[AnalysisBlock],
+    ledger: ClaimLedger,
+) -> list[CaseApplicabilityFinding]:
+    """Audit case applicability across all analysis blocks.
+
+    Returns findings for:
+    - analogous claims without applicability_reason
+    - single comparable case supporting strong action
+    - missing verification_path when no local direct evidence
+    """
+    findings: list[CaseApplicabilityFinding] = []
+
+    for block in blocks:
+        _check_analogous_applicability(block, ledger, findings)
+        _check_single_case_action(block, ledger, findings)
+        _check_verification_path(block, findings)
+
+    return findings
+
+
+def _check_analogous_applicability(
+    block: AnalysisBlock,
+    ledger: ClaimLedger,
+    findings: list[CaseApplicabilityFinding],
+) -> None:
+    """Rule 1: analogous claims MUST have applicability_reason."""
+    for cid in block.case_claim_ids:
+        claim = ledger.get_claim(cid)
+        if not claim:
+            continue
+        if claim.evidence_relation == "analogous" and not claim.applicability_reason.strip():
+            findings.append(CaseApplicabilityFinding(
+                finding_type="missing_applicability_reason",
+                severity="warning",
+                block_id=block.block_id,
+                claim_id=cid,
+                description=(
+                    f"Claim {cid} uses analogous evidence but has no applicability_reason. "
+                    "Readers cannot judge when this comparison applies."
+                ),
+                recommendation=(
+                    "Add applicability_reason explaining why this comparable case is relevant "
+                    "and what dimensions are not comparable."
+                ),
+            ))
+
+
+def _check_single_case_action(
+    block: AnalysisBlock,
+    ledger: ClaimLedger,
+    findings: list[CaseApplicabilityFinding],
+) -> None:
+    """Rule 2: single comparable case cannot support strong action."""
+    # Check two scenarios:
+    # A) action_claim_ids contain analogous evidence (direct action on analogy)
+    # B) case_claim_ids contain epistemic_type=action (builder classified by evidence_relation first)
+    if not block.case_claim_ids:
+        return
+    if block.fact_claim_ids:
+        # There are direct facts, so analogous evidence is supplementary
+        return
+
+    # Scenario A: explicit action claims with analogous evidence
+    for action_cid in block.action_claim_ids:
+        action_claim = ledger.get_claim(action_cid)
+        if not action_claim:
+            continue
+        if action_claim.evidence_relation == "analogous":
+            findings.append(CaseApplicabilityFinding(
+                finding_type="analogous_evidence_supports_action",
+                severity="fail",
+                block_id=block.block_id,
+                claim_id=action_cid,
+                description=(
+                    f"Action claim {action_cid} is supported only by comparable/analogous evidence "
+                    "with no direct fact backing. Single comparable cases cannot support strong actions."
+                ),
+                recommendation=(
+                    "Downgrade to 'to_verify' or add direct evidence. "
+                    "Comparable cases can support hypothesis or trend judgment, not actionable recommendations."
+                ),
+            ))
+
+    # Scenario B: case claims that were originally action-type (builder put them in case due to analogous)
+    for case_cid in block.case_claim_ids:
+        case_claim = ledger.get_claim(case_cid)
+        if not case_claim:
+            continue
+        if case_claim.epistemic_type == "action":
+            findings.append(CaseApplicabilityFinding(
+                finding_type="analogous_evidence_supports_action",
+                severity="fail",
+                block_id=block.block_id,
+                claim_id=case_cid,
+                description=(
+                    f"Claim {case_cid} has epistemic_type='action' but evidence_relation='analogous'. "
+                    "It was classified as a case (correct), but an action claim based solely on "
+                    "comparable evidence cannot support a strong recommendation."
+                ),
+                recommendation=(
+                    "Downgrade epistemic_type to 'hypothesis' or 'interpreted', "
+                    "or add direct local evidence to support the action."
+                ),
+            ))
+
+
+def _check_verification_path(
+    block: AnalysisBlock,
+    findings: list[CaseApplicabilityFinding],
+) -> None:
+    """Rule 3: no local direct evidence → must have verification_path."""
+    has_direct_fact = bool(block.fact_claim_ids)
+    has_case = bool(block.case_claim_ids)
+    has_verification = bool(block.verification_path.strip())
+
+    if has_case and not has_direct_fact and not has_verification:
+        findings.append(CaseApplicabilityFinding(
+            finding_type="missing_verification_path",
+            severity="warning",
+            block_id=block.block_id,
+            claim_id="",
+            description=(
+                f"Block '{block.title}' uses comparable cases but has no direct local facts "
+                "and no verification_path. Readers don't know how to validate the comparison."
+            ),
+            recommendation=(
+                "Add verification_path describing what data or action would confirm "
+                "whether the comparable case applies locally."
+            ),
+        ))
+
+
+def format_case_applicability_report(findings: list[CaseApplicabilityFinding]) -> str:
+    """Format findings into a readable report."""
+    if not findings:
+        return "Case applicability audit: all checks passed.\n"
+
+    lines = ["Case Applicability Audit Report", "=" * 34, ""]
+    for f in findings:
+        icon = "❌" if f.severity == "fail" else "⚠️"
+        lines.append(f"{icon} [{f.severity.upper()}] {f.finding_type}")
+        lines.append(f"   Block: {f.block_id}")
+        if f.claim_id:
+            lines.append(f"   Claim: {f.claim_id}")
+        lines.append(f"   {f.description}")
+        lines.append(f"   → {f.recommendation}")
+        lines.append("")
+
+    fails = sum(1 for f in findings if f.severity == "fail")
+    warns = sum(1 for f in findings if f.severity == "warning")
+    lines.append(f"Result: {fails} fail(s), {warns} warning(s)")
+    return "\n".join(lines)