agenticraft_foundation.protocols.semantic

Semantic routing implementations for capability-based agent discovery.

Semantic preservation verification.

Verifies Definition 9 (Semantic Preservation): meaning(m) = meaning(T_{p→p'}(m)). Protocol translations must preserve semantic content, and round-trip preservation T⁻¹(T(m)) ≈ m.

SemanticViolationType

Bases: str, Enum

Types of semantic violations.

FIELD_MISSING = 'field_missing' class-attribute instance-attribute

Required field is missing after translation

FIELD_MODIFIED = 'field_modified' class-attribute instance-attribute

Field value was unexpectedly modified

TYPE_MISMATCH = 'type_mismatch' class-attribute instance-attribute

Field type changed during translation

STRUCTURE_CHANGED = 'structure_changed' class-attribute instance-attribute

Overall message structure was altered

ROUND_TRIP_FAILED = 'round_trip_failed' class-attribute instance-attribute

T⁻¹(T(m)) ≠ m

SEMANTIC_DRIFT = 'semantic_drift' class-attribute instance-attribute

Semantic meaning has drifted beyond threshold

SemanticViolation dataclass

A specific semantic violation detected during verification.

violation_type instance-attribute

Type of violation

field_path instance-attribute

Path to the affected field (e.g., 'payload.data.value')

original_value = None class-attribute instance-attribute

Original value before translation

translated_value = None class-attribute instance-attribute

Value after translation

message = '' class-attribute instance-attribute

Human-readable description

severity = 'warning' class-attribute instance-attribute

Severity: 'info', 'warning', 'error', 'critical'

SemanticVerificationResult dataclass

Result of semantic preservation check.

preserved instance-attribute

Whether semantics were fully preserved

original_hash instance-attribute

Semantic hash of original message

translated_hash instance-attribute

Semantic hash of translated message

round_trip_hash = None class-attribute instance-attribute

Semantic hash after round-trip translation (if performed)

semantic_distance = 0.0 class-attribute instance-attribute

Distance between original and translated (0.0 = identical, 1.0 = different)

violations = field(default_factory=list) class-attribute instance-attribute

List of detected violations

verification_time_ms = 0.0 class-attribute instance-attribute

Time taken for verification in milliseconds

has_violations property

Check if any violations were detected.

critical_violations property

Get only critical violations.

round_trip_preserved property

Check if round-trip preservation holds.

get_summary()

Get verification summary.

ProtocolMessage

Bases: Protocol

Protocol for messages that can be semantically verified.

semantic_fields property

Fields that carry semantic meaning.

protocol_metadata property

Protocol-specific metadata (not semantic).

ProtocolTranslator

Bases: Protocol

Protocol for translators that can translate messages.

translate(message)

Translate a message to target protocol.

reverse_translate(message)

Translate back to source protocol.

VerificationConfig dataclass

Configuration for semantic verification.

semantic_distance_threshold = 0.1 class-attribute instance-attribute

Maximum allowed semantic distance (0.0 to 1.0)

require_round_trip = False class-attribute instance-attribute

Whether to require round-trip verification

strict_type_checking = True class-attribute instance-attribute

Whether to check field types strictly

ignore_fields = field(default_factory=set) class-attribute instance-attribute

Fields to ignore during comparison

critical_fields = field(default_factory=set) class-attribute instance-attribute

Fields that must be preserved exactly

SemanticPreservationVerifier

Verify semantic preservation in protocol translations.

Implements Definition 9 (Semantic Preservation): meaning(m) = meaning(T_{p→p'}(m))

Checks: - Field preservation - Type preservation - Structure preservation - Round-trip preservation: T⁻¹(T(m)) ≈ m

Usage

verifier = SemanticPreservationVerifier()

Verify a translation

result = verifier.verify_translation( original=original_message, translated=translated_message, )

if not result.preserved: for violation in result.violations: print(f"Violation: {violation.message}")

Verify round-trip

result = verifier.verify_round_trip( message=original_message, forward_translator=mcp_to_a2a, reverse_translator=a2a_to_mcp, )

__init__(config=None)

Initialize semantic preservation verifier.

PARAMETER	DESCRIPTION
config	Verification configuration TYPE: VerificationConfig | None DEFAULT: None

verify_translation(original, translated)

Verify semantic preservation in a translation.

PARAMETER	DESCRIPTION
original	Original message TYPE: dict[str, Any] | ProtocolMessage
translated	Translated message TYPE: dict[str, Any] | ProtocolMessage

RETURNS	DESCRIPTION
SemanticVerificationResult	SemanticVerificationResult with preservation status

verify_round_trip(message, forward_translator, reverse_translator)

Verify round-trip preservation: T⁻¹(T(m)) ≈ m.

PARAMETER	DESCRIPTION
message	Original message TYPE: dict[str, Any] | ProtocolMessage
forward_translator	Translator from source to target protocol TYPE: ProtocolTranslator
reverse_translator	Translator from target back to source TYPE: ProtocolTranslator

RETURNS	DESCRIPTION
SemanticVerificationResult	SemanticVerificationResult with round-trip verification

verify_output(output, expected_schema)

Verify output matches expected schema semantically.

PARAMETER	DESCRIPTION
output	Actual output TYPE: dict[str, Any]
expected_schema	Expected schema with field types TYPE: dict[str, Any]

RETURNS	DESCRIPTION
SemanticVerificationResult	SemanticVerificationResult

get_statistics()

Get verification statistics.