agenticraft_foundation.protocols.cost¶
Path cost function \(\text{cost}(\pi, \sigma) = \sum w_{e_i}(p_i) + \sum \tau(p_i, p_{i+1}, v_i)\) with configurable edge cost models for routing optimization.
Path cost function: cost(π, σ).
Computes cost(π, σ) = Σ wₑ(p) + Σ τ(pᵢ, pᵢ₊₁, vᵢ) where π is the path, σ is the protocol sequence, wₑ(p) is the edge weight for protocol p, and τ is the translation cost at each node.
Based on Definition 12 (Path Cost Function) from the formal multi-protocol mesh model.
TranslationCost
dataclass
¶
Cost of translating between protocols at a node.
Represents τ(pᵢₙ, pₒᵤₜ, v) — the cost incurred when translating from pᵢₙ to pₒᵤₜ at node v.
source_protocol
instance-attribute
¶
Incoming protocol (pᵢₙ)
target_protocol
instance-attribute
¶
Outgoing protocol (pₒᵤₜ)
base_cost = 0.1
class-attribute
instance-attribute
¶
τ_base — base translation overhead
semantic_loss_penalty = 0.0
class-attribute
instance-attribute
¶
τ_semantic — penalty for semantic loss during translation
latency_ms = 10.0
class-attribute
instance-attribute
¶
Expected latency in milliseconds for this translation
node_id = None
class-attribute
instance-attribute
¶
Node where translation occurs (v)
total_cost
property
¶
Total translation cost.
τ(pᵢₙ, pₒᵤₜ, v) = τ_base + τ_semantic
is_identity
property
¶
Check if this is an identity translation (same protocol).
PathCost
dataclass
¶
Complete cost breakdown for a protocol-aware path.
Represents cost(π, σ) = Σ wₑ(p) + Σ τ(pᵢ, pᵢ₊₁, vᵢ) with detailed breakdown.
edge_costs = field(default_factory=list)
class-attribute
instance-attribute
¶
wₑ(p) for each edge in the path
translation_costs = field(default_factory=list)
class-attribute
instance-attribute
¶
τ(pᵢ, pᵢ₊₁, vᵢ) for each translation point
path = field(default_factory=list)
class-attribute
instance-attribute
¶
Agent IDs in the path
protocol_sequence = field(default_factory=list)
class-attribute
instance-attribute
¶
Protocols used on each edge
total_edge_cost
property
¶
Sum of all edge costs: Σ wₑ(p)
total_translation_cost
property
¶
Sum of all translation costs: Σ τ(pᵢ, pᵢ₊₁, vᵢ)
total_cost
property
¶
Total path cost.
cost(π, σ) = Σ wₑ(p) + Σ τ(pᵢ, pᵢ₊₁, vᵢ)
total_latency_ms
property
¶
Estimated total latency in milliseconds.
num_translations
property
¶
Number of protocol translations (excluding identity).
semantic_loss_estimate
property
¶
Estimated semantic loss across all translations.
Compounds multiplicatively: (1 - loss1) * (1 - loss2) * ...
get_summary()
¶
Get cost summary dictionary.
CostConfig
dataclass
¶
Configuration for path cost calculation.
default_edge_weight = 1.0
class-attribute
instance-attribute
¶
Default weight for edges without explicit weights
default_translation_base_cost = 0.1
class-attribute
instance-attribute
¶
Default base cost for protocol translations
semantic_loss_multiplier = 2.0
class-attribute
instance-attribute
¶
Multiplier for semantic loss in cost calculation
latency_weight = 0.01
class-attribute
instance-attribute
¶
Weight for latency in cost calculation (cost per ms)
identity_translation_cost = 0.0
class-attribute
instance-attribute
¶
Cost for identity translations (same protocol)
PathCostCalculator
¶
Calculate path cost for protocol-aware routing.
Implements Definition 12 (Path Cost Function) from the formal model::
cost(π, σ) = Σ wₑᵢ(pᵢ) + Σ τ(pᵢ, pᵢ₊₁, vᵢ)
Where:
- π is the path (sequence of agents)
- σ is the protocol sequence
- wₑᵢ(pᵢ) is the weight of edge i using protocol pᵢ
- τ(pᵢ, pᵢ₊₁, vᵢ) is the translation cost at intermediate nodes
Usage
calculator = PathCostCalculator(graph, compatibility_matrix)
Calculate cost for a path¶
cost = calculator.calculate_path_cost( path=["agent1", "agent2", "agent3"], protocol_sequence=[ProtocolName.MCP, ProtocolName.A2A] )
Get detailed cost breakdown¶
path_cost = calculator.get_path_cost_breakdown(path, protocol_sequence) print(f"Total: {path_cost.total_cost}") print(f"Translations: {path_cost.num_translations}")
__init__(graph, compatibility_matrix, config=None)
¶
Initialize path cost calculator.
| PARAMETER | DESCRIPTION |
|---|---|
graph
|
Protocol graph with agents and edges
TYPE:
|
compatibility_matrix
|
Protocol compatibility information |
config
|
Cost calculation configuration
TYPE:
|
calculate_path_cost(path, protocol_sequence)
¶
Calculate total cost for a protocol-aware path.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
Sequence of agent IDs
TYPE:
|
protocol_sequence
|
Protocol to use on each edge
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
float
|
Total path cost (infinity if path is invalid) |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If path and protocol_sequence lengths don't match |
get_path_cost_breakdown(path, protocol_sequence)
¶
Get detailed cost breakdown for a path.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
Sequence of agent IDs
TYPE:
|
protocol_sequence
|
Protocol to use on each edge
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
PathCost
|
PathCost with detailed breakdown |
get_translation_cost(source_protocol, target_protocol, at_node=None)
¶
Get cost of translating between protocols at a node.
| PARAMETER | DESCRIPTION |
|---|---|
source_protocol
|
Incoming protocol
TYPE:
|
target_protocol
|
Outgoing protocol
TYPE:
|
at_node
|
Node where translation occurs
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
TranslationCost
|
TranslationCost for this translation |
estimate_minimum_cost(source, target, source_protocol, target_protocol=None)
¶
Estimate minimum possible cost between two agents.
Useful for A* heuristic or early termination.
| PARAMETER | DESCRIPTION |
|---|---|
source
|
Source agent ID
TYPE:
|
target
|
Target agent ID
TYPE:
|
source_protocol
|
Starting protocol
TYPE:
|
target_protocol
|
Required ending protocol (optional)
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
float
|
Lower bound on path cost |
compare_paths(path1, path2)
¶
Compare two paths by cost.
| PARAMETER | DESCRIPTION |
|---|---|
path1
|
First (path, protocol_sequence) tuple
TYPE:
|
path2
|
Second (path, protocol_sequence) tuple
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
int
|
-1 if path1 cheaper, 1 if path2 cheaper, 0 if equal |
clear_cache()
¶
Clear the translation cost cache.
get_statistics()
¶
Get calculator statistics.