agentclaimguard 0.3.1__py3-none-any.whl

agentclaimguard/__init__.py

@@ -0,0 +1,23 @@
+from agentclaimguard.core.claim import Claim
+from agentclaimguard.core.evidence import Evidence
+from agentclaimguard.core.policy import Policy
+from agentclaimguard.core.result import (
+    ClaimVerificationResult,
+    VerificationResult,
+    Violation,
+)
+from agentclaimguard.core.runtime import AgentClaimGuard, verify_claims
+from agentclaimguard.core.tool_result import ToolResult
+
+__all__ = [
+    "Claim",
+    "AgentClaimGuard",
+    "ClaimVerificationResult",
+    "Evidence",
+    "Policy",
+    "ToolResult",
+    "VerificationResult",
+    "Violation",
+    "verify_claims",
+]
+

agentclaimguard/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Framework adapter namespace.
+
+The v0.1 release focuses on the core SDK and OpenAPI server. Framework-specific
+adapters will live under this package as they are added.
+"""
+

agentclaimguard/adapters/dify/__init__.py

@@ -0,0 +1,2 @@
+"""Dify adapter placeholder."""
+

agentclaimguard/adapters/dspy/__init__.py

@@ -0,0 +1,2 @@
+"""DSPy adapter placeholder."""
+

agentclaimguard/adapters/langchain/__init__.py

@@ -0,0 +1,18 @@
+"""LangChain adapter for claim-level evidence gating."""
+
+from .runnable import GuardedRunnable, create_guarded_runnable
+from .types import (
+    FieldExtractor,
+    FieldMapper,
+    LangChainAdapterInput,
+    LangChainAdapterOutput,
+)
+
+__all__ = [
+    "FieldExtractor",
+    "FieldMapper",
+    "GuardedRunnable",
+    "LangChainAdapterInput",
+    "LangChainAdapterOutput",
+    "create_guarded_runnable",
+]

agentclaimguard/adapters/langchain/runnable.py

@@ -0,0 +1,126 @@
+from collections.abc import Mapping
+from typing import Any
+
+from langchain_core.runnables import Runnable, RunnableSerializable
+from pydantic import ConfigDict
+
+from agentclaimguard.core.policy import Policy
+from agentclaimguard.core.result import VerificationResult
+from agentclaimguard.core.runtime import AgentClaimGuard
+
+from .types import FieldExtractor, FieldMapper
+
+
+_DEFAULT_FIELD_MAP: dict[str, str] = {
+    "claims": "claims",
+    "evidence": "evidence",
+    "tool_results": "tool_results",
+}
+
+
+class GuardedRunnable(RunnableSerializable[Any, Any]):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    runnable: Runnable[Any, Any]
+    policy: Policy
+    field_map: FieldMapper = None
+    result_key: str = "guard_result"
+    output_key: str = "output"
+    overwrite_result: bool = False
+
+    def invoke(self, input: Any, config=None, **kwargs: Any) -> Any:
+        output = self.runnable.invoke(input, config=config, **kwargs)
+        guard_result = self._run_guard(input=input, output=output)
+        return self._merge_output(output=output, guard_result=guard_result)
+
+    async def ainvoke(self, input: Any, config=None, **kwargs: Any) -> Any:
+        output = await self.runnable.ainvoke(input, config=config, **kwargs)
+        guard_result = self._run_guard(input=input, output=output)
+        return self._merge_output(output=output, guard_result=guard_result)
+
+    def _run_guard(self, *, input: Any, output: Any) -> VerificationResult:
+        guard = AgentClaimGuard(policy=self.policy)
+        field_map = dict(_DEFAULT_FIELD_MAP)
+        if self.field_map:
+            field_map.update(self.field_map)
+
+        claims = _resolve_field(field_map["claims"], input=input, output=output) or []
+        evidence = (
+            _resolve_field(field_map["evidence"], input=input, output=output) or []
+        )
+        tool_results = (
+            _resolve_field(field_map["tool_results"], input=input, output=output) or []
+        )
+
+        return guard.verify(
+            claims=claims,
+            evidence=evidence,
+            tool_results=tool_results,
+        )
+
+    def _merge_output(self, *, output: Any, guard_result: VerificationResult) -> Any:
+        if isinstance(output, Mapping):
+            if self.result_key in output and not self.overwrite_result:
+                raise ValueError(
+                    f"LangChain adapter output already contains '{self.result_key}'. "
+                    "Use a different result_key or set overwrite_result=True."
+                )
+            merged = dict(output)
+            merged[self.result_key] = guard_result
+            return merged
+
+        return {
+            self.output_key: output,
+            self.result_key: guard_result,
+        }
+
+
+def create_guarded_runnable(
+    runnable: Runnable[Any, Any],
+    policy: Policy,
+    *,
+    field_map: FieldMapper = None,
+    result_key: str = "guard_result",
+    output_key: str = "output",
+    overwrite_result: bool = False,
+) -> GuardedRunnable:
+    """Wrap a LangChain Runnable and attach AgentClaimGuard verification."""
+    return GuardedRunnable(
+        runnable=runnable,
+        policy=policy,
+        field_map=field_map,
+        result_key=result_key,
+        output_key=output_key,
+        overwrite_result=overwrite_result,
+    )
+
+
+def _resolve_field(
+    extractor: FieldExtractor,
+    *,
+    input: Any,
+    output: Any,
+) -> list[Any] | None:
+    if callable(extractor):
+        value = extractor(input, output)
+    elif isinstance(extractor, str):
+        value = _lookup_value(output, extractor)
+        if value is None:
+            value = _lookup_value(input, extractor)
+    else:
+        value = None
+
+    if value is None:
+        return None
+    if isinstance(value, list):
+        return value
+    raise TypeError(
+        "LangChain adapter field extractors must resolve to a list or None. "
+        f"Got {type(value).__name__}."
+    )
+
+
+def _lookup_value(source: Any, key: str) -> Any:
+    if isinstance(source, Mapping):
+        return source.get(key)
+    return None

agentclaimguard/adapters/langchain/types.py

@@ -0,0 +1,8 @@
+from collections.abc import Callable, Mapping
+from typing import Any, TypeAlias
+
+
+LangChainAdapterInput: TypeAlias = Any
+LangChainAdapterOutput: TypeAlias = Any
+FieldExtractor: TypeAlias = str | Callable[[Any, Any], list[Any] | None]
+FieldMapper: TypeAlias = Mapping[str, FieldExtractor] | None

agentclaimguard/adapters/langgraph/__init__.py

@@ -0,0 +1,18 @@
+"""LangGraph adapter for claim-level evidence gating."""
+
+from .node import create_evidence_guard_node, route_by_guard_status
+from .types import (
+    EvidenceGuardNode,
+    GuardRoute,
+    LangGraphGuardState,
+    LangGraphGuardUpdate,
+)
+
+__all__ = [
+    "EvidenceGuardNode",
+    "GuardRoute",
+    "LangGraphGuardState",
+    "LangGraphGuardUpdate",
+    "create_evidence_guard_node",
+    "route_by_guard_status",
+]

agentclaimguard/adapters/langgraph/node.py

@@ -0,0 +1,78 @@
+from collections.abc import Mapping
+from typing import Any
+
+from pydantic import ValidationError
+
+from agentclaimguard.core.policy import Policy
+from agentclaimguard.core.result import VerificationResult
+from agentclaimguard.core.runtime import AgentClaimGuard
+
+from .types import EvidenceGuardNode, GuardRoute
+
+
+_ROUTABLE_CLAIM_STATUSES: set[GuardRoute] = {
+    "need_check",
+    "insufficient_evidence",
+    "conflicting_evidence",
+}
+
+
+def create_evidence_guard_node(
+    policy: Policy,
+    *,
+    claims_key: str = "claims",
+    evidence_key: str = "evidence",
+    tool_results_key: str = "tool_results",
+    result_key: str = "guard_result",
+) -> EvidenceGuardNode:
+    """Create a LangGraph-compatible node for AgentClaimGuard verification."""
+    guard = AgentClaimGuard(policy=policy)
+
+    def evidence_guard_node(state: Mapping[str, Any]) -> dict[str, VerificationResult]:
+        result = guard.verify(
+            claims=state.get(claims_key, []),
+            evidence=state.get(evidence_key, []),
+            tool_results=state.get(tool_results_key, []),
+        )
+        return {result_key: result}
+
+    return evidence_guard_node
+
+
+def route_by_guard_status(
+    state: Mapping[str, Any],
+    *,
+    result_key: str = "guard_result",
+) -> GuardRoute:
+    result = _coerce_result(state.get(result_key))
+    if result is None:
+        return "need_check"
+
+    if result.status == "passed":
+        return "passed"
+
+    claim_status = _first_non_passed_claim_status(result)
+    if claim_status in _ROUTABLE_CLAIM_STATUSES:
+        return claim_status
+
+    return "blocked"
+
+
+def _coerce_result(value: Any) -> VerificationResult | None:
+    if value is None:
+        return None
+    if isinstance(value, VerificationResult):
+        return value
+    if isinstance(value, Mapping):
+        try:
+            return VerificationResult.model_validate(value)
+        except ValidationError:
+            return None
+    return None
+
+
+def _first_non_passed_claim_status(result: VerificationResult) -> str | None:
+    for claim_result in result.claim_results:
+        if claim_result.status != "passed":
+            return claim_result.status
+    return None

agentclaimguard/adapters/langgraph/types.py

@@ -0,0 +1,16 @@
+from collections.abc import Callable, Mapping
+from typing import Any, Literal, TypeAlias
+
+from agentclaimguard.core.result import VerificationResult
+
+
+LangGraphGuardState: TypeAlias = Mapping[str, Any]
+LangGraphGuardUpdate: TypeAlias = dict[str, VerificationResult]
+EvidenceGuardNode: TypeAlias = Callable[[LangGraphGuardState], LangGraphGuardUpdate]
+GuardRoute: TypeAlias = Literal[
+    "passed",
+    "blocked",
+    "need_check",
+    "insufficient_evidence",
+    "conflicting_evidence",
+]

agentclaimguard/adapters/ragflow/__init__.py

@@ -0,0 +1,2 @@
+"""RAGFlow adapter placeholder."""
+

agentclaimguard/core/__init__.py

@@ -0,0 +1,23 @@
+from agentclaimguard.core.claim import Claim
+from agentclaimguard.core.evidence import Evidence
+from agentclaimguard.core.policy import Policy
+from agentclaimguard.core.result import (
+    ClaimVerificationResult,
+    VerificationResult,
+    Violation,
+)
+from agentclaimguard.core.runtime import AgentClaimGuard, verify_claims
+from agentclaimguard.core.tool_result import ToolResult
+
+__all__ = [
+    "Claim",
+    "AgentClaimGuard",
+    "ClaimVerificationResult",
+    "Evidence",
+    "Policy",
+    "ToolResult",
+    "VerificationResult",
+    "Violation",
+    "verify_claims",
+]
+

agentclaimguard/core/claim.py

@@ -0,0 +1,15 @@
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Claim(BaseModel):
+    id: str
+    text: str
+    type: str
+    verdict: str | None = None
+    evidence_refs: list[str] = Field(default_factory=list)
+    tool_result_refs: list[str] = Field(default_factory=list)
+    confidence: float | None = Field(default=None, ge=0.0, le=1.0)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+

agentclaimguard/core/evidence.py

@@ -0,0 +1,13 @@
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Evidence(BaseModel):
+    id: str
+    type: str
+    source: str | None = None
+    locator: str | None = None
+    content: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+

agentclaimguard/core/policy.py

@@ -0,0 +1,83 @@
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+from agentclaimguard.utils.yaml_loader import load_yaml
+
+
+class EvidenceRequirement(BaseModel):
+    type: str
+    min_count: int = Field(default=1, ge=1)
+
+
+class ToolRequirement(BaseModel):
+    tool_name: str
+    min_count: int = Field(default=1, ge=1)
+
+    @model_validator(mode="before")
+    @classmethod
+    def parse_string_requirement(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return {"tool_name": value}
+        if isinstance(value, dict) and "name" in value and "tool_name" not in value:
+            return {**value, "tool_name": value["name"]}
+        return value
+
+
+class FallbackRule(BaseModel):
+    verdict: str = "need_check"
+    reason: str | None = None
+
+
+class ClaimTypePolicy(BaseModel):
+    required_evidence: list[EvidenceRequirement] = Field(default_factory=list)
+    required_tool_results: list[ToolRequirement] = Field(default_factory=list)
+    forbidden: list[str] = Field(default_factory=list)
+    fallback: FallbackRule | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Policy(BaseModel):
+    name: str = "default"
+    version: str = "0.1"
+    claim_types: dict[str, ClaimTypePolicy] = Field(default_factory=dict)
+    default_fallback: FallbackRule = Field(
+        default_factory=lambda: FallbackRule(
+            verdict="need_check",
+            reason="The claim could not be verified by the active policy.",
+        )
+    )
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def load(cls, path: str | Path) -> "Policy":
+        data = load_yaml(path)
+        return cls.model_validate(data)
+
+    @classmethod
+    def load_builtin(cls, name: str) -> "Policy":
+        policy_name = name.removesuffix(".yaml")
+        if "/" in policy_name or "\\" in policy_name:
+            raise ValueError("Built-in policy names must not include path separators.")
+
+        path = Path(__file__).resolve().parents[1] / "policies" / f"{policy_name}.yaml"
+        if not path.exists():
+            available = ", ".join(cls.list_builtin())
+            raise ValueError(
+                f"Unknown built-in policy '{name}'. Available policies: {available}."
+            )
+
+        return cls.load(path)
+
+    @classmethod
+    def list_builtin(cls) -> list[str]:
+        policy_dir = Path(__file__).resolve().parents[1] / "policies"
+        return sorted(path.stem for path in policy_dir.glob("*.yaml"))
+
+    def policy_for_claim_type(self, claim_type: str) -> ClaimTypePolicy:
+        return self.claim_types.get(claim_type, ClaimTypePolicy())
+
+    def fallback_for_claim_type(self, claim_type: str) -> FallbackRule:
+        claim_policy = self.policy_for_claim_type(claim_type)
+        return claim_policy.fallback or self.default_fallback

agentclaimguard/core/result.py

@@ -0,0 +1,41 @@
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+ClaimStatus = Literal[
+    "passed",
+    "blocked",
+    "need_check",
+    "insufficient_evidence",
+    "conflicting_evidence",
+    "tool_required",
+    "tool_error",
+    "repair_required",
+]
+
+
+class Violation(BaseModel):
+    claim_id: str
+    type: str
+    message: str
+    required: str | None = None
+    found: int | None = None
+    refs: list[str] = Field(default_factory=list)
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class ClaimVerificationResult(BaseModel):
+    claim_id: str
+    status: ClaimStatus
+    violations: list[Violation] = Field(default_factory=list)
+    safe_verdict: str | None = None
+    reason: str | None = None
+
+
+class VerificationResult(BaseModel):
+    status: Literal["passed", "blocked"]
+    claim_results: list[ClaimVerificationResult] = Field(default_factory=list)
+    violations: list[Violation] = Field(default_factory=list)
+    safe_output: dict[str, Any] = Field(default_factory=dict)
+

agentclaimguard/core/runtime.py

@@ -0,0 +1,54 @@
+from collections.abc import Iterable
+
+from agentclaimguard.core.claim import Claim
+from agentclaimguard.core.evidence import Evidence
+from agentclaimguard.core.policy import Policy
+from agentclaimguard.core.result import VerificationResult
+from agentclaimguard.core.tool_result import ToolResult
+from agentclaimguard.core.verifier import verify_claims as run_verifier
+
+
+class AgentClaimGuard:
+    def __init__(self, policy: Policy):
+        self.policy = policy
+
+    def verify(
+        self,
+        claims: Iterable[Claim | dict],
+        evidence: Iterable[Evidence | dict] | None = None,
+        tool_results: Iterable[ToolResult | dict] | None = None,
+    ) -> VerificationResult:
+        parsed_claims = [Claim.model_validate(item) for item in claims]
+        parsed_evidence = [Evidence.model_validate(item) for item in evidence or []]
+        parsed_tool_results = [
+            ToolResult.model_validate(item) for item in tool_results or []
+        ]
+        return run_verifier(
+            claims=parsed_claims,
+            evidence=parsed_evidence,
+            tool_results=parsed_tool_results,
+            policy=self.policy,
+        )
+
+    def repair(
+        self,
+        claims: Iterable[Claim | dict],
+        evidence: Iterable[Evidence | dict] | None = None,
+        tool_results: Iterable[ToolResult | dict] | None = None,
+    ) -> dict:
+        result = self.verify(claims=claims, evidence=evidence, tool_results=tool_results)
+        return result.safe_output
+
+
+def verify_claims(
+    claims: Iterable[Claim | dict],
+    evidence: Iterable[Evidence | dict],
+    tool_results: Iterable[ToolResult | dict],
+    policy: Policy,
+) -> VerificationResult:
+    return AgentClaimGuard(policy=policy).verify(
+        claims=claims,
+        evidence=evidence,
+        tool_results=tool_results,
+    )
+

agentclaimguard/core/tool_result.py

@@ -0,0 +1,14 @@
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class ToolResult(BaseModel):
+    id: str
+    tool_name: str
+    status: Literal["success", "error", "skipped"] = "success"
+    input: dict[str, Any] = Field(default_factory=dict)
+    output: Any = None
+    evidence_refs: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+

agentclaimguard/core/verifier.py

@@ -0,0 +1,97 @@
+from collections.abc import Iterable
+
+from agentclaimguard.core.claim import Claim
+from agentclaimguard.core.evidence import Evidence
+from agentclaimguard.core.policy import Policy
+from agentclaimguard.core.result import (
+    ClaimVerificationResult,
+    ClaimStatus,
+    VerificationResult,
+    Violation,
+)
+from agentclaimguard.core.tool_result import ToolResult
+from agentclaimguard.validators.citation_binding import validate_citation_binding
+from agentclaimguard.validators.conflict_check import validate_conflicting_evidence
+from agentclaimguard.validators.evidence_required import validate_required_evidence
+from agentclaimguard.validators.forbidden_verdict import validate_forbidden_rules
+from agentclaimguard.validators.tool_required import validate_required_tools
+
+
+def verify_claims(
+    claims: Iterable[Claim],
+    evidence: Iterable[Evidence],
+    tool_results: Iterable[ToolResult],
+    policy: Policy,
+) -> VerificationResult:
+    evidence_by_id = {item.id: item for item in evidence}
+    tool_results_by_id = {item.id: item for item in tool_results}
+
+    claim_results: list[ClaimVerificationResult] = []
+    all_violations: list[Violation] = []
+
+    for claim in claims:
+        claim_policy = policy.policy_for_claim_type(claim.type)
+        violations: list[Violation] = []
+        violations.extend(validate_citation_binding(claim, evidence_by_id, tool_results_by_id))
+        violations.extend(validate_required_evidence(claim, evidence_by_id, claim_policy))
+        violations.extend(validate_required_tools(claim, tool_results_by_id, claim_policy))
+        violations.extend(validate_forbidden_rules(claim, evidence_by_id, tool_results_by_id, claim_policy))
+        violations.extend(validate_conflicting_evidence(claim, evidence_by_id))
+
+        if violations:
+            fallback = policy.fallback_for_claim_type(claim.type)
+            status = _status_from_violations(violations)
+            claim_result = ClaimVerificationResult(
+                claim_id=claim.id,
+                status=status,
+                violations=violations,
+                safe_verdict=fallback.verdict,
+                reason=fallback.reason,
+            )
+            all_violations.extend(violations)
+        else:
+            claim_result = ClaimVerificationResult(claim_id=claim.id, status="passed")
+
+        claim_results.append(claim_result)
+
+    status = "passed" if not all_violations else "blocked"
+    return VerificationResult(
+        status=status,
+        claim_results=claim_results,
+        violations=all_violations,
+        safe_output=_safe_output(claim_results),
+    )
+
+
+def _status_from_violations(violations: list[Violation]) -> ClaimStatus:
+    violation_types = {violation.type for violation in violations}
+    if "conflicting_evidence" in violation_types:
+        return "conflicting_evidence"
+    if "required_tool_error" in violation_types:
+        return "tool_error"
+    if "missing_required_tool_result" in violation_types:
+        return "tool_required"
+    if {
+        "missing_required_evidence",
+        "missing_citation",
+        "invalid_evidence_ref",
+    } & violation_types:
+        return "insufficient_evidence"
+    return "blocked"
+
+
+def _safe_output(
+    claim_results: list[ClaimVerificationResult],
+) -> dict[str, list[dict[str, str | None]]]:
+    blocked = [
+        {
+            "claim_id": result.claim_id,
+            "safe_verdict": result.safe_verdict,
+            "reason": result.reason,
+            "status": result.status,
+        }
+        for result in claim_results
+        if result.status != "passed"
+    ]
+    return {"blocked_claims": blocked}
+

agentclaimguard/policies/generic_compliance.yaml

@@ -0,0 +1,17 @@
+name: generic_compliance
+version: "0.1"
+
+claim_types:
+  compliance_judgement:
+    required_evidence:
+      - type: regulation
+        min_count: 1
+      - type: source_fact
+        min_count: 1
+    forbidden:
+      - use_model_memory_as_authority
+      - unsupported_pass_fail
+    fallback:
+      verdict: need_check
+      reason: Compliance judgments require rule evidence and source facts.
+