agenticraft_foundation.protocols.transformers¶
Composable protocol message transformers \(T: M_p \to M_{p'} \cup \{\bot\}\) with lossless, lossy, and destructive classification.
Composable Protocol Transformers.
Models protocol transformers as composable algebraic objects:
T_{p→p'}: Mₚ → Mₚ' ∪ {⊥}
With identity and composition laws: - Identity: T_{p→p} = id (no transformation) - Composition: T_{p→p''} = T_{p'→p''} ∘ T_{p→p'}
Implements Theorem 6: Lossless/lossy classification. A transformer is lossless iff T⁻¹(T(m)) = m for all m ∈ Mₚ.
Usage::
registry = TransformerRegistry()
registry.register(mcp_to_a2a)
registry.register(a2a_to_mcp)
# Auto-compose: MCP → A2A → ANP
composed = registry.get_transformer(ProtocolName.MCP, ProtocolName.ANP)
result = composed.transform(message)
TransformerClassification
¶
Bases: str, Enum
Classification of a protocol transformer (Theorem 6).
LOSSLESS = 'lossless'
class-attribute
instance-attribute
¶
T⁻¹(T(m)) = m for all m — perfect round-trip
LOSSY = 'lossy'
class-attribute
instance-attribute
¶
T⁻¹(T(m)) ≈ m — some information loss
DESTRUCTIVE = 'destructive'
class-attribute
instance-attribute
¶
T⁻¹(T(m)) may be ⊥ — significant information loss
TransformResult
dataclass
¶
Result of a protocol transformation.
success
instance-attribute
¶
Whether the transformation succeeded
message = None
class-attribute
instance-attribute
¶
Transformed message (None if failed, i.e., ⊥)
source_protocol = None
class-attribute
instance-attribute
¶
Source protocol
target_protocol = None
class-attribute
instance-attribute
¶
Target protocol
fields_preserved = 0
class-attribute
instance-attribute
¶
Number of semantic fields preserved
fields_lost = 0
class-attribute
instance-attribute
¶
Number of semantic fields lost
metadata = field(default_factory=dict)
class-attribute
instance-attribute
¶
Transformation metadata
preservation_ratio
property
¶
Ratio of preserved fields to total fields.
BaseProtocolTransformer
¶
Bases: ABC
Base class for protocol transformers.
T_{p→p'}: Mₚ → Mₚ' ∪ {⊥}
Subclasses implement the actual transformation logic for specific protocol pairs.
source_protocol
abstractmethod
property
¶
Source protocol.
target_protocol
abstractmethod
property
¶
Target protocol.
classification
property
¶
Transformer classification (default: lossy).
transform(message)
abstractmethod
¶
Transform a message from source to target protocol.
| PARAMETER | DESCRIPTION |
|---|---|
message
|
Message in source protocol format
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
TransformResult
|
TransformResult with transformed message or failure (⊥) |
IdentityTransformer
¶
Bases: BaseProtocolTransformer
Identity transformer: T_{p→p} = id.
Returns the message unchanged. Always lossless.
ComposedTransformer
¶
Bases: BaseProtocolTransformer
Composition of two transformers: T_{p→p''} = T_{p'→p''} ∘ T_{p→p'}.
Applies first transformer, then second transformer to the result.
classification
property
¶
Composition classification: worst of the two.
TransformerRegistry
¶
Registry of protocol transformers with automatic composition.
Manages registered transformers and computes composed transformers for protocol pairs that don't have direct transformers.
Usage::
registry = TransformerRegistry()
registry.register(mcp_to_a2a_transformer)
registry.register(a2a_to_anp_transformer)
# Direct lookup
t = registry.get_transformer(ProtocolName.MCP, ProtocolName.A2A)
# Auto-composed (MCP→A2A→ANP)
t = registry.get_transformer(ProtocolName.MCP, ProtocolName.ANP)
registered_pairs
property
¶
Get all registered transformer pairs (excluding identity).
register(transformer)
¶
Register a transformer.
has_transformer(source, target)
¶
Check if a direct transformer exists.
get_direct_transformer(source, target)
¶
Get a direct (non-composed) transformer.
get_transformer(source, target)
¶
Get a transformer, composing if needed.
First checks for a direct transformer. If not found, attempts to compose via a single intermediate protocol (BFS depth 1).
| PARAMETER | DESCRIPTION |
|---|---|
source
|
Source protocol
TYPE:
|
target
|
Target protocol
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
BaseProtocolTransformer | None
|
Transformer or None if no path exists |
get_all_paths(source, target, max_hops=3)
¶
Find all transformation paths from source to target.
Uses BFS to find paths up to max_hops length.
| PARAMETER | DESCRIPTION |
|---|---|
source
|
Source protocol
TYPE:
|
target
|
Target protocol
TYPE:
|
max_hops
|
Maximum number of intermediate transformations
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[list[ProtocolName]]
|
List of protocol paths (including source and target) |
compose_path(path)
¶
Compose a transformer from a protocol path.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
List of protocols [p1, p2, ..., pn]
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
BaseProtocolTransformer | None
|
Composed transformer p1→p2→...→pn, or None if any hop is missing |
verify_round_trip(protocol_a, protocol_b, test_message)
¶
Verify round-trip preservation: T⁻¹(T(m)) = m.
| PARAMETER | DESCRIPTION |
|---|---|
protocol_a
|
First protocol
TYPE:
|
protocol_b
|
Second protocol
TYPE:
|
test_message
|
Test message to verify with
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True if round-trip preserves the message |
get_statistics()
¶
Get registry statistics.