agentprop 0.1.0a1__py3-none-any.whl

agentprop/__init__.py

@@ -0,0 +1,5 @@
+"""AgentProp: graph optimization for multi-agent LLM workflows."""
+
+from agentprop.core import AgentEdge, AgentGraph, AgentNode, NodeType
+
+__all__ = ["AgentEdge", "AgentGraph", "AgentNode", "NodeType"]

agentprop/algorithms/__init__.py

@@ -0,0 +1,68 @@
+"""Classical graph optimization algorithms."""
+
+from agentprop.algorithms.bottlenecks import (
+    articulation_bottlenecks,
+    bottleneck_nodes,
+    bridge_bottlenecks,
+    edge_bottlenecks,
+    failure_sensitive_nodes,
+    low_reliability_cut_points,
+)
+from agentprop.algorithms.observability import (
+    observability_coverage,
+    observability_scores,
+    verifier_observability_placement,
+)
+from agentprop.algorithms.pruning import high_cost_low_relevance_edges, low_weight_edges
+from agentprop.algorithms.seed_selection import (
+    betweenness_seed_selection,
+    celf_seed_selection,
+    closeness_seed_selection,
+    cost_aware_greedy_seed_selection,
+    degree_seed_selection,
+    greedy_seed_selection,
+    k_core_seed_selection,
+    pagerank_seed_selection,
+    quality_aware_greedy_seed_selection,
+    random_seed_selection,
+)
+from agentprop.algorithms.verifier_placement import (
+    betweenness_verifier_placement,
+    context_sensitive_verifier_placement,
+    error_propagation_centrality,
+    error_propagation_verifier_placement,
+    greedy_correction_coverage_placement,
+    pagerank_verifier_placement,
+    risk_aware_verifier_placement,
+)
+
+__all__ = [
+    "articulation_bottlenecks",
+    "betweenness_seed_selection",
+    "betweenness_verifier_placement",
+    "bottleneck_nodes",
+    "bridge_bottlenecks",
+    "celf_seed_selection",
+    "closeness_seed_selection",
+    "cost_aware_greedy_seed_selection",
+    "context_sensitive_verifier_placement",
+    "degree_seed_selection",
+    "edge_bottlenecks",
+    "error_propagation_centrality",
+    "error_propagation_verifier_placement",
+    "failure_sensitive_nodes",
+    "greedy_seed_selection",
+    "greedy_correction_coverage_placement",
+    "k_core_seed_selection",
+    "high_cost_low_relevance_edges",
+    "low_reliability_cut_points",
+    "low_weight_edges",
+    "observability_coverage",
+    "observability_scores",
+    "pagerank_seed_selection",
+    "pagerank_verifier_placement",
+    "quality_aware_greedy_seed_selection",
+    "random_seed_selection",
+    "risk_aware_verifier_placement",
+    "verifier_observability_placement",
+]

agentprop/algorithms/bottlenecks.py

@@ -0,0 +1,103 @@
+"""Workflow bottleneck detection."""
+
+from __future__ import annotations
+
+import networkx as nx
+
+from agentprop.core import AgentGraph
+
+
+def bottleneck_nodes(graph: AgentGraph, *, limit: int = 5) -> list[tuple[str, float]]:
+    """Return nodes that look structurally important or operationally risky."""
+
+    nx_graph = graph.to_networkx()
+    if not nx_graph:
+        return []
+
+    betweenness = nx.betweenness_centrality(nx_graph, weight="weight")
+    scores: dict[str, float] = {}
+    for node in graph.nodes():
+        scores[node.id] = (
+            float(betweenness.get(node.id, 0.0))
+            + 0.05 * float(nx_graph.out_degree(node.id))
+            + 0.05 * float(nx_graph.in_degree(node.id))
+            + 0.25 * (1.0 - node.reliability)
+            + 0.25 * node.error_rate
+        )
+
+    return sorted(scores.items(), key=lambda item: (-item[1], item[0]))[:limit]
+
+
+def articulation_bottlenecks(graph: AgentGraph, *, limit: int = 5) -> list[str]:
+    """Return nodes whose removal disconnects the weak workflow structure."""
+
+    undirected = graph.to_networkx().to_undirected()
+    if graph.node_count < 3:
+        return []
+    points = [str(node_id) for node_id in nx.articulation_points(undirected)]
+    points.sort()
+    return points[:limit]
+
+
+def bridge_bottlenecks(graph: AgentGraph, *, limit: int = 5) -> list[tuple[str, str]]:
+    """Return communication edges that are weak bridges in the workflow graph."""
+
+    undirected = graph.to_networkx().to_undirected()
+    bridges = [(str(source), str(target)) for source, target in nx.bridges(undirected)]
+    bridges.sort()
+    return bridges[:limit]
+
+
+def edge_bottlenecks(graph: AgentGraph, *, limit: int = 5) -> list[tuple[str, str, float]]:
+    """Rank edges by structural centrality and operational cost."""
+
+    nx_graph = graph.to_networkx()
+    if not nx_graph:
+        return []
+    edge_centrality = nx.edge_betweenness_centrality(nx_graph, weight="weight")
+    scored: list[tuple[str, str, float]] = []
+    for edge in graph.edges():
+        centrality = float(edge_centrality.get((edge.source, edge.target), 0.0))
+        cost_risk = 0.001 * edge.message_cost + 0.1 * (1.0 - edge.reliability)
+        scored.append((edge.source, edge.target, centrality + cost_risk))
+    return sorted(scored, key=lambda item: (-item[2], item[0], item[1]))[:limit]
+
+
+def low_reliability_cut_points(graph: AgentGraph, *, limit: int = 5) -> list[tuple[str, float]]:
+    """Rank structurally central nodes with low reliability or high error rate."""
+
+    nx_graph = graph.to_networkx()
+    if not nx_graph:
+        return []
+    betweenness = nx.betweenness_centrality(nx_graph, weight="weight")
+    scores = {}
+    for node in graph.nodes():
+        reliability_risk = 1.0 - node.reliability + node.error_rate
+        scores[node.id] = reliability_risk * (1.0 + float(betweenness.get(node.id, 0.0)))
+    return sorted(scores.items(), key=lambda item: (-item[1], item[0]))[:limit]
+
+
+def failure_sensitive_nodes(graph: AgentGraph, *, limit: int = 5) -> list[tuple[str, float]]:
+    """Rank nodes by reachable-pair loss after node removal."""
+
+    nx_graph = graph.to_networkx()
+    if not nx_graph:
+        return []
+    baseline_pairs = _reachable_pair_count(nx_graph)
+    if baseline_pairs == 0:
+        return []
+
+    scored = []
+    for node_id in nx_graph.nodes:
+        reduced = nx_graph.copy()
+        reduced.remove_node(node_id)
+        loss = baseline_pairs - _reachable_pair_count(reduced)
+        scored.append((str(node_id), loss / baseline_pairs))
+    return sorted(scored, key=lambda item: (-item[1], item[0]))[:limit]
+
+
+def _reachable_pair_count(nx_graph: nx.DiGraph) -> float:
+    total = 0
+    for source in nx_graph.nodes:
+        total += len(nx.descendants(nx_graph, source))
+    return float(total)

agentprop/algorithms/observability.py

@@ -0,0 +1,56 @@
+"""Observability and verifier-placement metrics."""
+
+from __future__ import annotations
+
+import networkx as nx
+
+from agentprop.core import AgentGraph
+
+
+def observability_scores(graph: AgentGraph) -> dict[str, float]:
+    """Score nodes by usefulness for observing failures and corrections."""
+
+    nx_graph = graph.to_networkx()
+    if graph.node_count == 0:
+        return {}
+
+    betweenness = nx.betweenness_centrality(nx_graph, weight="weight")
+    scores: dict[str, float] = {}
+    max_reachable = max(graph.node_count - 1, 1)
+
+    for node in graph.nodes():
+        descendants = nx.descendants(nx_graph, node.id)
+        ancestors = nx.ancestors(nx_graph, node.id)
+        reach_score = len(descendants) / max_reachable
+        attribution_score = len(ancestors) / max_reachable
+        reliability_risk = 1.0 - node.reliability + node.error_rate
+        scores[node.id] = (
+            0.35 * reach_score
+            + 0.25 * attribution_score
+            + 0.25 * float(betweenness.get(node.id, 0.0))
+            + 0.15 * reliability_risk
+        )
+
+    return scores
+
+
+def observability_coverage(graph: AgentGraph, observers: list[str]) -> float:
+    """Return fraction of nodes observable by the selected observer nodes."""
+
+    nx_graph = graph.to_networkx()
+    observed = set(observers)
+    for observer in observers:
+        if observer in nx_graph:
+            observed.update(str(node_id) for node_id in nx.ancestors(nx_graph, observer))
+            observed.update(str(node_id) for node_id in nx.descendants(nx_graph, observer))
+    return len(observed) / max(graph.node_count, 1)
+
+
+def verifier_observability_placement(graph: AgentGraph, k: int) -> list[str]:
+    """Choose verifier/logging nodes by observability score."""
+
+    if k < 1:
+        raise ValueError("k must be at least 1")
+    scores = observability_scores(graph)
+    ranked = sorted(scores.items(), key=lambda item: (-item[1], item[0]))
+    return [node_id for node_id, _ in ranked[:k]]

agentprop/algorithms/pruning.py

@@ -0,0 +1,26 @@
+"""Edge pruning heuristics."""
+
+from __future__ import annotations
+
+from agentprop.core import AgentGraph
+
+
+def low_weight_edges(graph: AgentGraph, *, fraction: float = 0.2) -> list[tuple[str, str]]:
+    """Return the lowest-weight edges as pruning candidates."""
+
+    if not 0 <= fraction <= 1:
+        raise ValueError("fraction must be between 0 and 1")
+    edges = sorted(graph.edges(), key=lambda edge: (edge.weight, edge.relevance, edge.reliability))
+    keep_count = int(round(len(edges) * fraction))
+    return [(edge.source, edge.target) for edge in edges[:keep_count]]
+
+
+def high_cost_low_relevance_edges(graph: AgentGraph, *, limit: int = 5) -> list[tuple[str, str]]:
+    """Return expensive edges with low relevance/reliability."""
+
+    scored = []
+    for edge in graph.edges():
+        quality = max(edge.relevance * edge.reliability, 0.01)
+        score = edge.message_cost / quality
+        scored.append((score, edge.source, edge.target))
+    return [(source, target) for _, source, target in sorted(scored, reverse=True)[:limit]]