Skip to content

Witnesses

witnesses

Base classes for witness validation.

WitnessResult represents validation outcomes. ValidationFeedback provides structured error information. WitnessRule is the Protocol for validation rules.

This module lives in axm (core) so that external packages (axm-n8n, axm-mail, …) can implement witnesses without depending on axm-engine. The engine re-exports these symbols from axm_engine.services.witnesses.base for backward compatibility.

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
Python
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
@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
Python
39
40
41
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
Python
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
@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
Python
69
70
71
72
73
74
75
76
77
78
79
@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
Python
60
61
62
63
64
65
66
67
@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
Python
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
@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
Python
86
87
88
89
90
91
92
93
94
95
96
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
    """
    ...