agenticraft_foundation.protocols.semantic_routing

Semantic routing using capability embeddings and protocol affinity scoring.

Semantic Protocol-Aware Routing (Algorithm 4).

Routes messages based on semantic similarity of capabilities, combined with protocol affinity and path cost.

Score: similarity(cap_q, cap_a) × affinity(p, cap_a) / (1 + cost(π))

Zero external dependencies — uses pure Python bag-of-words with cosine similarity for capability embeddings.

Falls back to ProtocolAwareDijkstra when embeddings are unavailable.

CapabilityEmbedding dataclass

Vector representation of a capability for semantic matching.

Uses bag-of-words (BoW) with optional TF-IDF weighting. Zero external dependencies.

capability instance-attribute

Original capability string

vector = field(default_factory=dict) class-attribute instance-attribute

Sparse vector: token → weight

from_text(capability) classmethod

Create embedding from capability text.

Tokenizes on underscores, hyphens, spaces, and camelCase boundaries.

similarity(other)

Compute cosine similarity with another embedding.

SemanticRouteCandidate dataclass

A candidate agent for semantic routing.

agent_id instance-attribute

Agent identifier

capability_similarity instance-attribute

Semantic similarity of agent's capabilities to query

protocol_affinity instance-attribute

Protocol affinity score

path_cost instance-attribute

Estimated path cost from source

composite_score instance-attribute

Combined routing score

matched_capability instance-attribute

Best matching capability on this agent

SemanticRouter

Semantic protocol-aware routing.

Finds the best agent to handle a capability query by balancing: 1. Semantic similarity between requested and available capabilities 2. Protocol affinity for the agent's protocols 3. Path cost from source to agent

Score = similarity × affinity / (1 + cost)

__init__(graph, affinity_matrix=None, similarity_threshold=0.1)

Initialize semantic router.

PARAMETER	DESCRIPTION
graph	Protocol graph TYPE: ProtocolGraph
affinity_matrix	Capability-protocol affinity matrix TYPE: CapabilityAffinityMatrix | None DEFAULT: None
similarity_threshold	Minimum similarity to consider a match TYPE: float DEFAULT: 0.1

find_best_agent(query_capability, source, source_protocol, top_k=5)

Find best agents for a capability query.

PARAMETER	DESCRIPTION
query_capability	Requested capability TYPE: str
source	Source agent ID TYPE: str
source_protocol	Source agent's protocol TYPE: ProtocolName
top_k	Number of top candidates to return TYPE: int DEFAULT: 5

RETURNS	DESCRIPTION
list[SemanticRouteCandidate]	Sorted list of SemanticRouteCandidate (best first)