agenticraft_foundation.protocols.affinity¶
Protocol affinity scoring — measures how well an agent supports a given protocol.
Capability-protocol affinity matrix: α(c, p) → [0, 1].
Maps capabilities to optimal protocols based on protocol characteristics. Higher affinity indicates better suitability.
AffinityConfig
dataclass
¶
Configuration for affinity calculations.
default_affinity = 0.5
class-attribute
instance-attribute
¶
Default affinity for unknown capability-protocol pairs
min_affinity = 0.0
class-attribute
instance-attribute
¶
Minimum affinity value
max_affinity = 1.0
class-attribute
instance-attribute
¶
Maximum affinity value
aggregation_method = 'weighted_average'
class-attribute
instance-attribute
¶
Aggregation method: 'average', 'weighted_average', 'max', 'min'.
CapabilityAffinityMatrix
¶
Lookup capability-protocol affinities.
The affinity matrix maps capabilities to protocols, indicating how well each protocol supports specific capabilities. Higher values (closer to 1.0) indicate better fit.
Usage
matrix = CapabilityAffinityMatrix()
Get affinity for a single capability¶
affinity = matrix.get_affinity("code_execution", ProtocolName.MCP)
Get optimal protocol for a capability¶
best_protocol = matrix.get_optimal_protocol("task_delegation")
Score protocol for multiple capabilities¶
score = matrix.score_protocol_for_capabilities( ["code_execution", "resource_access"], ProtocolName.MCP )
__init__(affinity_data=None, config=None)
¶
Initialize affinity matrix.
| PARAMETER | DESCRIPTION |
|---|---|
affinity_data
|
Optional custom affinity data. Uses CAPABILITY_PROTOCOL_AFFINITY by default.
TYPE:
|
config
|
Configuration for affinity calculations.
TYPE:
|
get_affinity(capability, protocol)
¶
Get affinity score for a capability-protocol pair.
| PARAMETER | DESCRIPTION |
|---|---|
capability
|
Capability name
TYPE:
|
protocol
|
Protocol name
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
float
|
Affinity score (0.0 to 1.0) |
get_optimal_protocol(capability)
¶
Get the optimal protocol for a capability.
| PARAMETER | DESCRIPTION |
|---|---|
capability
|
Capability to optimize for
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ProtocolName
|
Protocol with highest affinity for this capability |
score_protocol_for_capabilities(capabilities, protocol, weights=None)
¶
Calculate aggregate affinity score for multiple capabilities.
| PARAMETER | DESCRIPTION |
|---|---|
capabilities
|
List of capabilities
TYPE:
|
protocol
|
Protocol to score
TYPE:
|
weights
|
Optional weights for each capability
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
float
|
Aggregate affinity score (0.0 to 1.0) |
get_best_protocol_for_capabilities(capabilities, weights=None, exclude_protocols=None)
¶
Find the best protocol for a set of capabilities.
| PARAMETER | DESCRIPTION |
|---|---|
capabilities
|
List of capabilities
TYPE:
|
weights
|
Optional weights for each capability
TYPE:
|
exclude_protocols
|
Protocols to exclude from consideration
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
tuple[ProtocolName, float]
|
Tuple of (best protocol, aggregate score) |
rank_protocols_for_capabilities(capabilities, weights=None)
¶
Rank all protocols for a set of capabilities.
| PARAMETER | DESCRIPTION |
|---|---|
capabilities
|
List of capabilities
TYPE:
|
weights
|
Optional weights for each capability
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[tuple[ProtocolName, float]]
|
List of (protocol, score) tuples, sorted by score descending |
get_capability_coverage(protocol, threshold=0.7)
¶
Get capabilities well-supported by a protocol.
| PARAMETER | DESCRIPTION |
|---|---|
protocol
|
Protocol to analyze
TYPE:
|
threshold
|
Minimum affinity threshold
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[str]
|
List of capabilities with affinity >= threshold |
register_affinity(capability, protocol, affinity)
¶
Register or update an affinity value.
| PARAMETER | DESCRIPTION |
|---|---|
capability
|
Capability name
TYPE:
|
protocol
|
Protocol name
TYPE:
|
affinity
|
Affinity value (0.0 to 1.0)
TYPE:
|
get_statistics()
¶
Get matrix statistics.
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any]
|
Dictionary of statistics |