briefloop 0.11.12__py3-none-any.whl

multi_agent_brief/contracts/schemas/claim_support_matrix.py

@@ -0,0 +1,334 @@
+"""Contract for experimental Claim-Support Matrix artifacts."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, ClassVar
+
+from multi_agent_brief.contracts.base import Contract, SchemaRegistry
+from multi_agent_brief.contracts.errors import FieldViolation
+
+CLAIM_SUPPORT_MATRIX_SCHEMA_VERSION = "mabw.claim_support_matrix.v1"
+SUPPORT_ROW_ID_RE = re.compile(r"^CSM-\d{4}$")
+ATOM_ID_RE = re.compile(r"^AC-(\d{4})-\d{2}$")
+CLAIM_ID_RE = re.compile(r"^CL-(\d{4})$")
+EVIDENCE_SPAN_ID_RE = re.compile(r"^ESP-\d{3,4}-\d{2}$")
+
+VALID_SUPPORT_LABELS = {
+    "direct_support",
+    "partial_support",
+    "inferential_support",
+    "weak_support",
+    "unsupported",
+    "contradicted",
+    "insufficient_evidence",
+    "not_applicable",
+}
+VALID_SUPPORT_STRENGTHS = {"high", "medium", "low", "none"}
+VALID_REQUIRED_ACTIONS = {
+    "none",
+    "block_release",
+    "downgrade_wording",
+    "remove_claim",
+    "add_evidence_span",
+    "human_adjudication",
+    "clarify_inference",
+    "mark_as_inference",
+    "repair_source_pack",
+}
+VALID_REPAIR_OWNERS = {"none", "analyst", "editor", "auditor", "claim-ledger", "human_review"}
+VALID_DECISION_SOURCES = {
+    "human",
+    "llm_assisted_human",
+    "llm_only",
+    "deterministic_policy",
+    "imported",
+    "unknown",
+}
+
+
+@SchemaRegistry.register
+class ClaimSupportMatrixContract(Contract):
+    """Validate experimental atom-to-evidence-span support rows.
+
+    This contract validates shape, IDs, and vocabulary only. It does not judge
+    semantic support, enforce blocking policy, route repairs, or verify that
+    referenced atoms/spans exist in sibling artifacts.
+    """
+
+    schema_id: ClassVar[str] = "claim_support_matrix"
+    schema_version: ClassVar[str] = "v1"
+
+    @classmethod
+    def json_schema(cls) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "required": ["schema_version", "rows"],
+            "properties": {
+                "schema_version": {
+                    "type": "string",
+                    "enum": [CLAIM_SUPPORT_MATRIX_SCHEMA_VERSION],
+                },
+                "rows": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "type": "object",
+                        "required": [
+                            "row_id",
+                            "atom_id",
+                            "claim_id",
+                            "evidence_span_id",
+                            "support_label",
+                            "support_strength",
+                            "support_reason",
+                            "required_action",
+                            "repair_owner",
+                            "decision_source",
+                        ],
+                        "properties": {
+                            "row_id": {"type": "string", "pattern": SUPPORT_ROW_ID_RE.pattern},
+                            "atom_id": {"type": "string", "pattern": ATOM_ID_RE.pattern},
+                            "claim_id": {"type": "string", "pattern": CLAIM_ID_RE.pattern},
+                            "evidence_span_id": {
+                                "type": ["string", "null"],
+                                "pattern": EVIDENCE_SPAN_ID_RE.pattern,
+                            },
+                            "support_label": {
+                                "type": "string",
+                                "enum": sorted(VALID_SUPPORT_LABELS),
+                            },
+                            "support_strength": {
+                                "type": "string",
+                                "enum": sorted(VALID_SUPPORT_STRENGTHS),
+                            },
+                            "support_reason": {"type": "string"},
+                            "required_action": {
+                                "type": "string",
+                                "enum": sorted(VALID_REQUIRED_ACTIONS),
+                            },
+                            "repair_owner": {
+                                "type": "string",
+                                "enum": sorted(VALID_REPAIR_OWNERS),
+                            },
+                            "decision_source": {
+                                "type": "string",
+                                "enum": sorted(VALID_DECISION_SOURCES),
+                            },
+                            "metadata": {"type": "object"},
+                        },
+                        "additionalProperties": True,
+                    },
+                },
+                "metadata": {"type": "object"},
+            },
+            "additionalProperties": True,
+        }
+
+    @classmethod
+    def validate(cls, data: dict[str, Any]) -> list[FieldViolation]:
+        if not isinstance(data, dict):
+            return [FieldViolation(field="<root>", error="must be an object")]
+
+        violations: list[FieldViolation] = []
+        schema_version = data.get("schema_version")
+        if not _non_empty_string(schema_version):
+            violations.append(FieldViolation(field="schema_version", error="required field is missing"))
+        elif schema_version != CLAIM_SUPPORT_MATRIX_SCHEMA_VERSION:
+            violations.append(
+                FieldViolation(
+                    field="schema_version",
+                    error=f"must be {CLAIM_SUPPORT_MATRIX_SCHEMA_VERSION}",
+                )
+            )
+
+        metadata = data.get("metadata")
+        if metadata is not None and not isinstance(metadata, dict):
+            violations.append(FieldViolation(field="metadata", error="must be an object"))
+
+        rows = data.get("rows")
+        if not isinstance(rows, list):
+            violations.append(FieldViolation(field="rows", error="must be a non-empty list"))
+            return violations
+        if not rows:
+            violations.append(FieldViolation(field="rows", error="must be a non-empty list"))
+
+        seen_row_ids: set[str] = set()
+        seen_relation_keys: set[tuple[str, str | None]] = set()
+        for row_idx, row in enumerate(rows):
+            violations.extend(
+                _validate_row_entry(
+                    row,
+                    idx=row_idx,
+                    seen_row_ids=seen_row_ids,
+                    seen_relation_keys=seen_relation_keys,
+                )
+            )
+
+        return violations
+
+    @classmethod
+    def migrate(cls, data: dict[str, Any], from_version: str) -> dict[str, Any]:
+        return dict(data)
+
+
+def _validate_row_entry(
+    row: Any,
+    *,
+    idx: int,
+    seen_row_ids: set[str],
+    seen_relation_keys: set[tuple[str, str | None]],
+) -> list[FieldViolation]:
+    prefix = f"rows[{idx}]"
+    violations: list[FieldViolation] = []
+    if not isinstance(row, dict):
+        return [FieldViolation(field=prefix, error="must be an object")]
+
+    row_id = row.get("row_id")
+    if not _non_empty_string(row_id) or not SUPPORT_ROW_ID_RE.match(str(row_id).strip()):
+        violations.append(FieldViolation(field=f"{prefix}.row_id", error="must match CSM-####"))
+    else:
+        normalized_row_id = str(row_id).strip()
+        if normalized_row_id in seen_row_ids:
+            violations.append(FieldViolation(field=f"{prefix}.row_id", error=f"duplicate row_id:{normalized_row_id}"))
+        seen_row_ids.add(normalized_row_id)
+
+    atom_id = row.get("atom_id")
+    atom_match = ATOM_ID_RE.match(atom_id.strip()) if _non_empty_string(atom_id) else None
+    if not atom_match:
+        violations.append(FieldViolation(field=f"{prefix}.atom_id", error="must match AC-####-##"))
+
+    claim_id = row.get("claim_id")
+    claim_match = CLAIM_ID_RE.match(claim_id.strip()) if _non_empty_string(claim_id) else None
+    if not claim_match:
+        violations.append(FieldViolation(field=f"{prefix}.claim_id", error="must match CL-####"))
+    elif atom_match and atom_match.group(1) != claim_match.group(1):
+        violations.append(
+            FieldViolation(
+                field=f"{prefix}.atom_id",
+                error=f"must use AC-{claim_match.group(1)}-## for matching claim_id",
+            )
+        )
+
+    support_label = row.get("support_label")
+    if not _non_empty_string(support_label):
+        violations.append(FieldViolation(field=f"{prefix}.support_label", error="must be a non-empty string"))
+    elif support_label not in VALID_SUPPORT_LABELS:
+        violations.append(
+            FieldViolation(
+                field=f"{prefix}.support_label",
+                error=f"invalid support_label '{support_label}', must be one of {sorted(VALID_SUPPORT_LABELS)}",
+            )
+        )
+
+    if "evidence_span_id" not in row:
+        violations.append(FieldViolation(field=f"{prefix}.evidence_span_id", error="required field is missing"))
+    else:
+        violations.extend(_validate_evidence_span_id(row.get("evidence_span_id"), prefix=prefix))
+        relation_key = _relation_key(atom_id=row.get("atom_id"), evidence_span_id=row.get("evidence_span_id"))
+        if relation_key is not None:
+            if relation_key in seen_relation_keys:
+                evidence_label = relation_key[1] if relation_key[1] is not None else "null"
+                violations.append(
+                    FieldViolation(
+                        field=f"{prefix}.evidence_span_id",
+                        error=f"duplicate atom_evidence_relation:{relation_key[0]}:{evidence_label}",
+                    )
+                )
+            seen_relation_keys.add(relation_key)
+
+    _validate_enum_field(
+        row,
+        field="support_strength",
+        prefix=prefix,
+        allowed=VALID_SUPPORT_STRENGTHS,
+        violations=violations,
+    )
+    _validate_enum_field(
+        row,
+        field="required_action",
+        prefix=prefix,
+        allowed=VALID_REQUIRED_ACTIONS,
+        violations=violations,
+    )
+    _validate_enum_field(
+        row,
+        field="repair_owner",
+        prefix=prefix,
+        allowed=VALID_REPAIR_OWNERS,
+        violations=violations,
+    )
+    _validate_enum_field(
+        row,
+        field="decision_source",
+        prefix=prefix,
+        allowed=VALID_DECISION_SOURCES,
+        violations=violations,
+    )
+
+    if not _non_empty_string(row.get("support_reason")):
+        violations.append(FieldViolation(field=f"{prefix}.support_reason", error="must be a non-empty string"))
+
+    metadata = row.get("metadata")
+    if metadata is not None and not isinstance(metadata, dict):
+        violations.append(FieldViolation(field=f"{prefix}.metadata", error="must be an object"))
+
+    return violations
+
+
+def _validate_evidence_span_id(
+    value: Any,
+    *,
+    prefix: str,
+) -> list[FieldViolation]:
+    if value is None:
+        return []
+    if not _non_empty_string(value):
+        return [FieldViolation(field=f"{prefix}.evidence_span_id", error="must be a string or null")]
+    if not EVIDENCE_SPAN_ID_RE.match(str(value).strip()):
+        return [FieldViolation(field=f"{prefix}.evidence_span_id", error="must match ESP-###-## or be null")]
+    return []
+
+
+def _relation_key(
+    *,
+    atom_id: Any,
+    evidence_span_id: Any,
+) -> tuple[str, str | None] | None:
+    if not _non_empty_string(atom_id):
+        return None
+    normalized_atom_id = str(atom_id).strip()
+    if not ATOM_ID_RE.match(normalized_atom_id):
+        return None
+    if evidence_span_id is None:
+        return (normalized_atom_id, None)
+    if not _non_empty_string(evidence_span_id):
+        return None
+    normalized_span_id = str(evidence_span_id).strip()
+    if not EVIDENCE_SPAN_ID_RE.match(normalized_span_id):
+        return None
+    return (normalized_atom_id, normalized_span_id)
+
+
+def _validate_enum_field(
+    row: dict[str, Any],
+    *,
+    field: str,
+    prefix: str,
+    allowed: set[str],
+    violations: list[FieldViolation],
+) -> None:
+    value = row.get(field)
+    if not _non_empty_string(value):
+        violations.append(FieldViolation(field=f"{prefix}.{field}", error="must be a non-empty string"))
+    elif value not in allowed:
+        violations.append(
+            FieldViolation(
+                field=f"{prefix}.{field}",
+                error=f"invalid {field} '{value}', must be one of {sorted(allowed)}",
+            )
+        )
+
+
+def _non_empty_string(value: Any) -> bool:
+    return isinstance(value, str) and bool(value.strip())

multi_agent_brief/contracts/schemas/evidence_span_registry.py

@@ -0,0 +1,270 @@
+"""Contract for experimental Evidence Span Registry artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Any, ClassVar
+
+from multi_agent_brief.contracts.base import Contract, SchemaRegistry
+from multi_agent_brief.contracts.errors import FieldViolation
+
+EVIDENCE_SPAN_REGISTRY_SCHEMA_VERSION = "mabw.evidence_span_registry.v1"
+SOURCE_ID_RE = re.compile(r"^SRC-(\d{3,4})$")
+EVIDENCE_SPAN_ID_RE = re.compile(r"^ESP-(\d{3,4})-\d{2}$")
+SHA256_RE = re.compile(r"^sha256:[0-9a-fA-F]{64}$")
+
+VALID_EVIDENCE_SPAN_ROLES = {
+    "direct_statement",
+    "numeric_observation",
+    "date_or_timing",
+    "context",
+    "limitation",
+    "contradiction",
+    "methodology",
+    "background",
+}
+
+
+@SchemaRegistry.register
+class EvidenceSpanRegistryContract(Contract):
+    """Validate deterministic Evidence Span Registry structure.
+
+    This contract validates source/span identity, machine-checkable metadata,
+    span roles, and raw excerpt hashes only. It does not judge whether a span
+    semantically supports a claim or atom.
+    """
+
+    schema_id: ClassVar[str] = "evidence_span_registry"
+    schema_version: ClassVar[str] = "v1"
+
+    @classmethod
+    def json_schema(cls) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "required": ["schema_version", "sources"],
+            "properties": {
+                "schema_version": {
+                    "type": "string",
+                    "enum": [EVIDENCE_SPAN_REGISTRY_SCHEMA_VERSION],
+                },
+                "sources": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "type": "object",
+                        "required": ["source_id", "source_type", "source_tier", "spans"],
+                        "properties": {
+                            "source_id": {"type": "string"},
+                            "source_type": {"type": "string"},
+                            "source_tier": {"type": "string"},
+                            "url": {"type": "string"},
+                            "source_path": {"type": "string"},
+                            "published_at": {"type": "string"},
+                            "retrieved_at": {"type": "string"},
+                            "spans": {
+                                "type": "array",
+                                "minItems": 1,
+                                "items": {
+                                    "type": "object",
+                                    "required": ["span_id", "raw_excerpt", "hash", "span_role"],
+                                    "properties": {
+                                        "span_id": {"type": "string", "pattern": EVIDENCE_SPAN_ID_RE.pattern},
+                                        "raw_excerpt": {"type": "string"},
+                                        "hash": {"type": "string", "pattern": SHA256_RE.pattern},
+                                        "span_role": {
+                                            "type": "string",
+                                            "enum": sorted(VALID_EVIDENCE_SPAN_ROLES),
+                                        },
+                                        "char_start": {"type": "integer", "minimum": 0},
+                                        "char_end": {"type": "integer", "minimum": 0},
+                                    },
+                                    "additionalProperties": True,
+                                },
+                            },
+                            "metadata": {"type": "object"},
+                        },
+                        "additionalProperties": True,
+                    },
+                },
+                "metadata": {"type": "object"},
+            },
+            "additionalProperties": True,
+        }
+
+    @classmethod
+    def validate(cls, data: dict[str, Any]) -> list[FieldViolation]:
+        if not isinstance(data, dict):
+            return [FieldViolation(field="<root>", error="must be an object")]
+
+        violations: list[FieldViolation] = []
+        schema_version = data.get("schema_version")
+        if not _non_empty_string(schema_version):
+            violations.append(FieldViolation(field="schema_version", error="required field is missing"))
+        elif schema_version != EVIDENCE_SPAN_REGISTRY_SCHEMA_VERSION:
+            violations.append(
+                FieldViolation(
+                    field="schema_version",
+                    error=f"must be {EVIDENCE_SPAN_REGISTRY_SCHEMA_VERSION}",
+                )
+            )
+
+        metadata = data.get("metadata")
+        if metadata is not None and not isinstance(metadata, dict):
+            violations.append(FieldViolation(field="metadata", error="must be an object"))
+
+        sources = data.get("sources")
+        if not isinstance(sources, list):
+            violations.append(FieldViolation(field="sources", error="must be a non-empty list"))
+            return violations
+        if not sources:
+            violations.append(FieldViolation(field="sources", error="must be a non-empty list"))
+
+        seen_source_ids: set[str] = set()
+        seen_span_ids: set[str] = set()
+        for source_idx, source in enumerate(sources):
+            violations.extend(
+                _validate_source_entry(
+                    source,
+                    idx=source_idx,
+                    seen_source_ids=seen_source_ids,
+                    seen_span_ids=seen_span_ids,
+                )
+            )
+
+        return violations
+
+    @classmethod
+    def migrate(cls, data: dict[str, Any], from_version: str) -> dict[str, Any]:
+        return dict(data)
+
+
+def _validate_source_entry(
+    source: Any,
+    *,
+    idx: int,
+    seen_source_ids: set[str],
+    seen_span_ids: set[str],
+) -> list[FieldViolation]:
+    prefix = f"sources[{idx}]"
+    violations: list[FieldViolation] = []
+    if not isinstance(source, dict):
+        return [FieldViolation(field=prefix, error="must be an object")]
+
+    source_id = source.get("source_id")
+    canonical_source_match: re.Match[str] | None = None
+    if not _non_empty_string(source_id):
+        violations.append(FieldViolation(field=f"{prefix}.source_id", error="must be a non-empty string"))
+    else:
+        normalized_source_id = str(source_id).strip()
+        canonical_source_match = SOURCE_ID_RE.match(normalized_source_id)
+        if normalized_source_id in seen_source_ids:
+            violations.append(
+                FieldViolation(field=f"{prefix}.source_id", error=f"duplicate source_id:{normalized_source_id}")
+            )
+        seen_source_ids.add(normalized_source_id)
+
+    for field in ("source_type", "source_tier"):
+        if not _non_empty_string(source.get(field)):
+            violations.append(FieldViolation(field=f"{prefix}.{field}", error="must be a non-empty string"))
+
+    if not (_non_empty_string(source.get("url")) or _non_empty_string(source.get("source_path"))):
+        violations.append(FieldViolation(field=f"{prefix}.source_identity", error="requires url or source_path"))
+    if not (_non_empty_string(source.get("published_at")) or _non_empty_string(source.get("retrieved_at"))):
+        violations.append(FieldViolation(field=f"{prefix}.source_date", error="requires published_at or retrieved_at"))
+
+    metadata = source.get("metadata")
+    if metadata is not None and not isinstance(metadata, dict):
+        violations.append(FieldViolation(field=f"{prefix}.metadata", error="must be an object"))
+
+    spans = source.get("spans")
+    if not isinstance(spans, list):
+        violations.append(FieldViolation(field=f"{prefix}.spans", error="must be a non-empty list"))
+        return violations
+    if not spans:
+        violations.append(FieldViolation(field=f"{prefix}.spans", error="must be a non-empty list"))
+
+    expected_span_prefix = canonical_source_match.group(1) if canonical_source_match else None
+    for span_idx, span in enumerate(spans):
+        violations.extend(
+            _validate_span_entry(
+                span,
+                source_prefix=prefix,
+                span_idx=span_idx,
+                expected_span_prefix=expected_span_prefix,
+                seen_span_ids=seen_span_ids,
+            )
+        )
+
+    return violations
+
+
+def _validate_span_entry(
+    span: Any,
+    *,
+    source_prefix: str,
+    span_idx: int,
+    expected_span_prefix: str | None,
+    seen_span_ids: set[str],
+) -> list[FieldViolation]:
+    prefix = f"{source_prefix}.spans[{span_idx}]"
+    violations: list[FieldViolation] = []
+    if not isinstance(span, dict):
+        return [FieldViolation(field=prefix, error="must be an object")]
+
+    span_id = span.get("span_id")
+    span_match = EVIDENCE_SPAN_ID_RE.match(span_id.strip()) if _non_empty_string(span_id) else None
+    if not span_match:
+        violations.append(FieldViolation(field=f"{prefix}.span_id", error="must match ESP-###-##"))
+    else:
+        normalized_span_id = str(span_id).strip()
+        if normalized_span_id in seen_span_ids:
+            violations.append(FieldViolation(field=f"{prefix}.span_id", error=f"duplicate span_id:{normalized_span_id}"))
+        seen_span_ids.add(normalized_span_id)
+        if expected_span_prefix is not None and span_match.group(1) != expected_span_prefix:
+            violations.append(
+                FieldViolation(
+                    field=f"{prefix}.span_id",
+                    error=f"must use ESP-{expected_span_prefix}-## for matching source_id",
+                )
+            )
+
+    raw_excerpt = span.get("raw_excerpt")
+    if not _non_empty_string(raw_excerpt):
+        violations.append(FieldViolation(field=f"{prefix}.raw_excerpt", error="must be a non-empty string"))
+
+    declared_hash = span.get("hash")
+    if not _non_empty_string(declared_hash):
+        violations.append(FieldViolation(field=f"{prefix}.hash", error="must be a non-empty string"))
+    elif not SHA256_RE.match(str(declared_hash).strip()):
+        violations.append(FieldViolation(field=f"{prefix}.hash", error="must match sha256:<64 hex chars>"))
+    elif _non_empty_string(raw_excerpt):
+        expected_hash = "sha256:" + hashlib.sha256(str(raw_excerpt).encode("utf-8")).hexdigest()
+        if str(declared_hash).strip().lower() != expected_hash:
+            violations.append(FieldViolation(field=f"{prefix}.hash", error="must match sha256(raw_excerpt)"))
+
+    span_role = span.get("span_role")
+    if not _non_empty_string(span_role):
+        violations.append(FieldViolation(field=f"{prefix}.span_role", error="must be a non-empty string"))
+    elif span_role not in VALID_EVIDENCE_SPAN_ROLES:
+        violations.append(
+            FieldViolation(
+                field=f"{prefix}.span_role",
+                error=f"invalid span_role '{span_role}', must be one of {sorted(VALID_EVIDENCE_SPAN_ROLES)}",
+            )
+        )
+
+    char_start = span.get("char_start")
+    char_end = span.get("char_end")
+    if char_start is not None and (not isinstance(char_start, int) or char_start < 0):
+        violations.append(FieldViolation(field=f"{prefix}.char_start", error="must be a non-negative integer"))
+    if char_end is not None and (not isinstance(char_end, int) or char_end < 0):
+        violations.append(FieldViolation(field=f"{prefix}.char_end", error="must be a non-negative integer"))
+    if isinstance(char_start, int) and isinstance(char_end, int) and char_end < char_start:
+        violations.append(FieldViolation(field=f"{prefix}.char_end", error="must be greater than or equal to char_start"))
+
+    return violations
+
+
+def _non_empty_string(value: Any) -> bool:
+    return isinstance(value, str) and bool(value.strip())