Witnesses

These validation contracts are distinct from tool results. The SDK supplies types and helpers; it does not execute validators or enforce a gate.

A WitnessRule supplies validate(content: str, **kwargs) -> WitnessResult. Unlike ToolResult, the result uses the boolean field passed. Its optional verdict is routing information for a consumer, not a validated enumeration or a scheduler action.

Python

from axm import ValidationFeedback, WitnessResult

feedback = ValidationFeedback(
    what="Title missing",
    why="The document requires a title",
    how="Add a level-one heading",
)
result = WitnessResult.failure(feedback, verdict="repair")
assert not result.passed
assert feedback.to_dict()["how"] == "Add a level-one heading"

accepted = WitnessResult.success(verdict="continue", metadata={"checked": 1})
assert accepted.passed

All three feedback strings (what, why, how) are required. to_dict() returns those same three keys. The helpers success and failure populate a result; they do not execute a validator or constrain the caller's choice of verdict.

ValidationFeedback dataclass

Structured feedback for validation failures.

Attributes:

Name	Type	Description
what	str	What failed (brief description)
why	str	Why it failed (expected vs actual)
how	str	How to fix it (actionable guidance)

Source code in packages/axm/src/axm/witnesses.py

@dataclass(frozen=True)
class ValidationFeedback:
    """Structured feedback for validation failures.

    Attributes:
        what: What failed (brief description)
        why: Why it failed (expected vs actual)
        how: How to fix it (actionable guidance)
    """

    what: str
    why: str
    how: str

    def to_dict(self) -> dict[str, str]:
        """Serialize to dictionary."""
        return {"what": self.what, "why": self.why, "how": self.how}

to_dict()

Serialize to dictionary.

Source code in packages/axm/src/axm/witnesses.py

def to_dict(self) -> dict[str, str]:
    """Serialize to dictionary."""
    return {"what": self.what, "why": self.why, "how": self.how}

WitnessResult dataclass

Result of a witness validation.

Attributes:

Name	Type	Description
passed	bool	Whether validation passed
feedback	ValidationFeedback | None	Feedback if validation failed
verdict	str | None	Optional routing decision for Gates
metadata	dict[str, Any]	Optional execution metadata

Source code in packages/axm/src/axm/witnesses.py

@dataclass(frozen=True)
class WitnessResult:
    """Result of a witness validation.

    Attributes:
        passed: Whether validation passed
        feedback: Feedback if validation failed
        verdict: Optional routing decision for Gates
        metadata: Optional execution metadata
    """

    passed: bool
    feedback: ValidationFeedback | None = None
    verdict: str | None = None
    metadata: dict[str, Any] = field(default_factory=dict)

    @classmethod
    def success(
        cls,
        verdict: str | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> WitnessResult:
        """Create a passing result."""
        return cls(passed=True, verdict=verdict, metadata=metadata or {})

    @classmethod
    def failure(
        cls,
        feedback: ValidationFeedback,
        verdict: str | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> WitnessResult:
        """Create a failing result with feedback."""
        return cls(
            passed=False, feedback=feedback, verdict=verdict, metadata=metadata or {}
        )

failure(feedback, verdict=None, metadata=None) classmethod

Create a failing result with feedback.

Source code in packages/axm/src/axm/witnesses.py

@classmethod
def failure(
    cls,
    feedback: ValidationFeedback,
    verdict: str | None = None,
    metadata: dict[str, Any] | None = None,
) -> WitnessResult:
    """Create a failing result with feedback."""
    return cls(
        passed=False, feedback=feedback, verdict=verdict, metadata=metadata or {}
    )

success(verdict=None, metadata=None) classmethod

Create a passing result.

Source code in packages/axm/src/axm/witnesses.py

@classmethod
def success(
    cls,
    verdict: str | None = None,
    metadata: dict[str, Any] | None = None,
) -> WitnessResult:
    """Create a passing result."""
    return cls(passed=True, verdict=verdict, metadata=metadata or {})

WitnessRule

Bases: Protocol

Protocol for witness validation rules.

Source code in packages/axm/src/axm/witnesses.py

@runtime_checkable
class WitnessRule(Protocol):
    """Protocol for witness validation rules."""

    def validate(self, content: str, **kwargs: Any) -> WitnessResult:
        """Validate content.

        Args:
            content: The content to validate
            **kwargs: Additional validation parameters

        Returns:
            WitnessResult indicating pass/fail with feedback
        """
        ...

validate(content, **kwargs)

Validate content.

Parameters:

Name	Type	Description	Default
content	str	The content to validate	required
**kwargs	Any	Additional validation parameters	{}

Returns:

Type	Description
WitnessResult	WitnessResult indicating pass/fail with feedback

Source code in packages/axm/src/axm/witnesses.py

def validate(self, content: str, **kwargs: Any) -> WitnessResult:
    """Validate content.

    Args:
        content: The content to validate
        **kwargs: Additional validation parameters

    Returns:
        WitnessResult indicating pass/fail with feedback
    """
    ...