@oobe-protocol-labs/synapse-client-sdk 1.2.2 → 2.0.0

package/dist/esm/ai/sap/scoring.js

@@ -0,0 +1,262 @@
+/**
+ * @module ai/sap/scoring
+ * @description SAP — Agent health scoring and network analytics.
+ *
+ * Computes composite health scores for individual agents and entire
+ * sub-networks, factoring in reputation, uptime, latency, call volume,
+ * capability coverage, and pricing competitiveness.
+ *
+ * Also provides **network-level analytics**: protocol concentration,
+ * Gini coefficient for call distribution, and trend detection.
+ *
+ * @example
+ * ```ts
+ * import { computeAgentHealthScore, computeNetworkAnalytics } from '@oobe-protocol-labs/synapse-client-sdk/ai/sap';
+ *
+ * const health = computeAgentHealthScore(agentPDA);
+ * console.log(health.composite);   // 0..100
+ * console.log(health.breakdown);   // { reputation, uptime, latency, activity, pricing }
+ *
+ * const analytics = computeNetworkAnalytics(allAgents);
+ * console.log(analytics.giniCoefficient);     // 0..1 (0 = perfectly even)
+ * console.log(analytics.protocolConcentration);
+ * ```
+ *
+ * @since 1.4.0
+ */
+/* ═══════════════════════════════════════════════════════════════
+ *  Scoring Weights
+ * ═══════════════════════════════════════════════════════════════ */
+const DEFAULT_WEIGHTS = {
+    reputation: 0.30,
+    uptime: 0.25,
+    latency: 0.20,
+    activity: 0.15,
+    pricing: 0.10,
+};
+/* ═══════════════════════════════════════════════════════════════
+ *  Single Agent Scoring
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Compute a composite health score for a single agent.
+ *
+ * @param {AgentPDAAccount} agent - The agent to score
+ * @param {Object} [context] - Optional context for relative scoring
+ * @param {number} [context.networkAvgCalls] - Network average calls (for activity scoring)
+ * @param {bigint} [context.networkAvgPrice] - Network average price per call
+ * @param {Partial<typeof DEFAULT_WEIGHTS>} [weights] - Override default weights
+ * @returns {AgentHealthScore}
+ *
+ * @since 1.4.0
+ */
+export function computeAgentHealthScore(agent, context, weights) {
+    const w = { ...DEFAULT_WEIGHTS, ...weights };
+    // Reputation: 0–1000 → 0–100
+    const reputation = Math.min(100, (agent.reputation.score / 1000) * 100);
+    // Uptime: direct mapping (0–100)
+    const uptime = Math.min(100, Math.max(0, agent.reputation.uptimePercent));
+    // Latency: log scale, 0ms = 100, 100ms = 80, 1s = 50, 10s = 10, 30s+ = 0
+    const latency = computeLatencyScore(agent.reputation.avgLatencyMs);
+    // Activity: relative to network average (or absolute if no context)
+    const avgCalls = context?.networkAvgCalls ?? 1000;
+    const callRatio = Number(agent.reputation.totalCallsServed) / Math.max(avgCalls, 1);
+    const activity = Math.min(100, callRatio * 50); // 2x average = 100
+    // Pricing: lower is better (relative to network average)
+    const agentPrice = agent.pricing[0]?.pricePerCall ?? 0n;
+    const avgPrice = context?.networkAvgPrice ?? 5000n;
+    const pricing = avgPrice > 0n
+        ? Math.min(100, Math.max(0, 100 - Number((agentPrice * 100n) / avgPrice)))
+        : 50;
+    const breakdown = {
+        reputation: Math.round(reputation),
+        uptime: Math.round(uptime),
+        latency: Math.round(latency),
+        activity: Math.round(activity),
+        pricing: Math.round(pricing),
+    };
+    const composite = Math.round(w.reputation * reputation +
+        w.uptime * uptime +
+        w.latency * latency +
+        w.activity * activity +
+        w.pricing * pricing);
+    const tier = scoreTier(composite);
+    const recommendations = generateRecommendations(agent, breakdown);
+    return {
+        walletPubkey: agent.walletPubkey,
+        name: agent.name,
+        composite,
+        breakdown,
+        tier,
+        summary: `${agent.name}: ${composite}/100 (${tier})`,
+        recommendations,
+    };
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  Network Analytics
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Compute network-level analytics across all discovered agents.
+ *
+ * @param {AgentPDAAccount[]} agents - All agents in the network
+ * @returns {NetworkAnalytics}
+ *
+ * @since 1.4.0
+ */
+export function computeNetworkAnalytics(agents) {
+    if (agents.length === 0) {
+        return {
+            totalAgents: 0,
+            activeAgents: 0,
+            avgHealthScore: 0,
+            tierDistribution: { excellent: 0, good: 0, fair: 0, poor: 0, critical: 0 },
+            giniCoefficient: 0,
+            protocolConcentration: [],
+            capabilityCoverage: [],
+            topAgents: [],
+            needsAttention: [],
+        };
+    }
+    // Context for relative scoring
+    const totalCalls = agents.reduce((s, a) => s + Number(a.reputation.totalCallsServed), 0);
+    const networkAvgCalls = totalCalls / agents.length;
+    const totalPrice = agents.reduce((s, a) => s + (a.pricing[0]?.pricePerCall ?? 0n), 0n);
+    const networkAvgPrice = totalPrice / BigInt(agents.length);
+    // Score each agent
+    const scores = agents.map(a => computeAgentHealthScore(a, { networkAvgCalls, networkAvgPrice }));
+    const active = agents.filter(a => a.isActive).length;
+    const avgScore = Math.round(scores.reduce((s, h) => s + h.composite, 0) / scores.length);
+    // Tier distribution
+    const tierDist = {
+        excellent: 0, good: 0, fair: 0, poor: 0, critical: 0,
+    };
+    for (const s of scores)
+        tierDist[s.tier]++;
+    // Gini coefficient (for call distribution fairness)
+    const gini = computeGini(agents.map(a => Number(a.reputation.totalCallsServed)));
+    // Protocol concentration
+    const protocolMap = new Map();
+    for (const agent of agents) {
+        for (const cap of agent.capabilities) {
+            const protocol = cap.protocol ?? cap.id.split(':')[0];
+            protocolMap.set(protocol, (protocolMap.get(protocol) ?? 0) + 1);
+        }
+    }
+    const protocolConcentration = [...protocolMap.entries()]
+        .map(([protocol, agentCount]) => ({
+        protocol,
+        agentCount,
+        pct: Math.round((agentCount / agents.length) * 100),
+    }))
+        .sort((a, b) => b.agentCount - a.agentCount);
+    // Capability coverage
+    const capMap = new Map();
+    for (const agent of agents) {
+        for (const cap of agent.capabilities) {
+            capMap.set(cap.id, (capMap.get(cap.id) ?? 0) + 1);
+        }
+    }
+    const capabilityCoverage = [...capMap.entries()]
+        .map(([capability, agentCount]) => ({ capability, agentCount }))
+        .sort((a, b) => b.agentCount - a.agentCount);
+    // Top agents
+    const topAgents = [...scores]
+        .sort((a, b) => b.composite - a.composite)
+        .slice(0, 10)
+        .map(s => ({ walletPubkey: s.walletPubkey, name: s.name, score: s.composite }));
+    // Needs attention
+    const needsAttention = scores
+        .filter(s => s.composite < 40)
+        .map(s => ({
+        walletPubkey: s.walletPubkey,
+        name: s.name,
+        score: s.composite,
+        reasons: s.recommendations,
+    }));
+    return {
+        totalAgents: agents.length,
+        activeAgents: active,
+        avgHealthScore: avgScore,
+        tierDistribution: tierDist,
+        giniCoefficient: gini,
+        protocolConcentration,
+        capabilityCoverage,
+        topAgents,
+        needsAttention,
+    };
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  Internal Helpers
+ * ═══════════════════════════════════════════════════════════════ */
+function computeLatencyScore(ms) {
+    if (ms <= 0)
+        return 100;
+    if (ms <= 50)
+        return 95;
+    if (ms <= 100)
+        return 85;
+    if (ms <= 500)
+        return 70;
+    if (ms <= 1000)
+        return 55;
+    if (ms <= 3000)
+        return 35;
+    if (ms <= 10000)
+        return 15;
+    return 5;
+}
+function scoreTier(composite) {
+    if (composite >= 85)
+        return 'excellent';
+    if (composite >= 65)
+        return 'good';
+    if (composite >= 45)
+        return 'fair';
+    if (composite >= 25)
+        return 'poor';
+    return 'critical';
+}
+function generateRecommendations(agent, breakdown) {
+    const recs = [];
+    if (breakdown.uptime < 50) {
+        recs.push('Improve uptime — current uptime is below 50%, causing automatic filtering by discovery queries');
+    }
+    if (breakdown.reputation < 30) {
+        recs.push('Reputation is very low — consider reducing pricing to attract initial calls and build reputation');
+    }
+    if (breakdown.latency < 30) {
+        recs.push(`Reduce response latency (currently ${agent.reputation.avgLatencyMs}ms) — high latency reduces selection probability`);
+    }
+    if (breakdown.activity < 20) {
+        recs.push('Very low call volume — register more capabilities or reduce pricing to increase visibility');
+    }
+    if (breakdown.pricing < 20) {
+        recs.push('Pricing is significantly above network average — consider competitive pricing to increase call volume');
+    }
+    if (agent.capabilities.length < 2) {
+        recs.push('Register additional capabilities — multi-capable agents are preferred by SubnetworkBuilder');
+    }
+    if (!agent.x402Endpoint) {
+        recs.push('Add an x402 endpoint to enable pay-per-call via the x402 protocol');
+    }
+    return recs;
+}
+/**
+ * @description Compute the Gini coefficient for a distribution of values.
+ * 0 = perfectly equal, 1 = maximum inequality.
+ * @internal
+ */
+function computeGini(values) {
+    const n = values.length;
+    if (n === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const sum = sorted.reduce((a, b) => a + b, 0);
+    if (sum === 0)
+        return 0;
+    let giniSum = 0;
+    for (let i = 0; i < n; i++) {
+        giniSum += (2 * (i + 1) - n - 1) * sorted[i];
+    }
+    return Math.round((giniSum / (n * sum)) * 1000) / 1000;
+}
+//# sourceMappingURL=scoring.js.map

package/dist/esm/ai/sap/scoring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoring.js","sourceRoot":"","sources":["../../../../src/ai/sap/scoring.ts"],"names":[],"mappings":"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"}

package/dist/esm/ai/sap/subnetwork.d.ts

@@ -0,0 +1,201 @@
+/**
+ * @module ai/sap/subnetwork
+ * @description SAP — Subnetwork builder for composing multi-agent task forces.
+ *
+ * Given a set of **required capabilities**, discovers the optimal set of
+ * agents that collectively cover all capabilities, then provides utilities
+ * to orchestrate them (cost estimation, health checks, failover selection).
+ *
+ * Think of it as a **query planner** for an agent-based microservice mesh:
+ * you describe WHAT you need, and the SubnetworkBuilder finds WHO can do it,
+ * optimizing for cost, reputation, latency, or a weighted combination.
+ *
+ * @example
+ * ```ts
+ * import { SubnetworkBuilder, SAPDiscovery } from '@oobe-protocol-labs/synapse-client-sdk/ai/sap';
+ *
+ * const discovery = new SAPDiscovery(client, { programId });
+ * const subnet = new SubnetworkBuilder(discovery);
+ *
+ * // Build a subnetwork that can swap, lend, and analyze risk
+ * const result = await subnet.build({
+ *   requiredCapabilities: ['jupiter:swap', 'solend:lend', 'ai:riskScore'],
+ *   strategy: 'balanced',
+ *   maxCostPerCall: 5000n,
+ * });
+ *
+ * if (result.complete) {
+ *   for (const assignment of result.assignments) {
+ *     console.log(`${assignment.capability} → ${assignment.agent.name}`);
+ *   }
+ *   console.log(`Total cost: ${result.estimatedCostPerCall}`);
+ * }
+ * ```
+ *
+ * @since 1.4.0
+ */
+import type { AgentPDAAccount, AgentPricingOnChain } from './types';
+import type { SAPDiscovery } from './discovery';
+/**
+ * @description Optimization strategy for agent selection.
+ * @since 1.4.0
+ */
+export type SelectionStrategy = 'cheapest' | 'reputable' | 'fastest' | 'balanced';
+/**
+ * @description Configuration for building a subnetwork.
+ * @since 1.4.0
+ */
+export interface SubnetworkConfig {
+    /** Capabilities the subnetwork must collectively support. */
+    requiredCapabilities: string[];
+    /** Optimization strategy. @default 'balanced' */
+    strategy?: SelectionStrategy;
+    /** Maximum acceptable cost per call (total across all agents). */
+    maxCostPerCall?: bigint;
+    /** Minimum reputation score for any agent in the subnetwork. @default 0 */
+    minReputation?: number;
+    /** Minimum uptime for any agent. @default 0 */
+    minUptime?: number;
+    /** Pricing tier to use for cost calculations. @default 'standard' */
+    pricingTier?: string;
+    /** Maximum number of agents in the subnetwork. @default 10 */
+    maxAgents?: number;
+    /** Prefer agents that cover multiple required capabilities (reduces hop count). @default true */
+    preferMultiCapable?: boolean;
+}
+/**
+ * @description A single capability → agent assignment in a subnetwork.
+ * @since 1.4.0
+ */
+export interface CapabilityAssignment {
+    /** The capability ID. */
+    capability: string;
+    /** The agent assigned to provide this capability. */
+    agent: AgentPDAAccount;
+    /** The pricing tier selected for this agent. */
+    pricing: AgentPricingOnChain;
+    /** The agent's reputation score. */
+    reputationScore: number;
+    /** The agent's average latency. */
+    latencyMs: number;
+    /** Alternative agents that could provide this capability (sorted by score). */
+    alternatives: AgentPDAAccount[];
+}
+/**
+ * @description Result of a subnetwork build operation.
+ * @since 1.4.0
+ */
+export interface SubnetworkResult {
+    /** Whether ALL required capabilities were assigned. */
+    complete: boolean;
+    /** Capability → agent assignments. */
+    assignments: CapabilityAssignment[];
+    /** Capabilities that could NOT be assigned (no agents found). */
+    unassigned: string[];
+    /** Unique agents in this subnetwork (deduplicated). */
+    agents: AgentPDAAccount[];
+    /** Estimated total cost per call (sum across all agents). */
+    estimatedCostPerCall: bigint;
+    /** Average reputation across all agents. */
+    avgReputation: number;
+    /** Max latency across all agents (bottleneck). */
+    maxLatencyMs: number;
+    /** Time taken to build the subnetwork (ms). */
+    buildTimeMs: number;
+    /** The strategy used. */
+    strategy: SelectionStrategy;
+}
+/**
+ * @description Health status of the subnetwork.
+ * @since 1.4.0
+ */
+export interface SubnetworkHealth {
+    /** Overall health: 'healthy' | 'degraded' | 'critical'. */
+    status: 'healthy' | 'degraded' | 'critical';
+    /** Per-agent health. */
+    agents: Array<{
+        agent: AgentPDAAccount;
+        capabilities: string[];
+        isHealthy: boolean;
+        reason?: string;
+    }>;
+    /** Capabilities at risk (only one agent, low reputation or uptime). */
+    atRisk: string[];
+    /** Capabilities with redundancy (2+ agents can provide them). */
+    redundant: string[];
+}
+/**
+ * @description Builds and manages agent sub-networks for multi-capability tasks.
+ *
+ * The builder:
+ * 1. Discovers agents for each required capability via {@link SAPDiscovery}
+ * 2. Scores candidates using the selected strategy
+ * 3. Assigns agents to capabilities, preferring multi-capable agents
+ * 4. Computes cost, reputation, and latency estimates
+ * 5. Identifies failover alternatives for each assignment
+ *
+ * @since 1.4.0
+ */
+export declare class SubnetworkBuilder {
+    private readonly discovery;
+    constructor(discovery: SAPDiscovery);
+    /**
+     * @description Build an optimal subnetwork covering all required capabilities.
+     *
+     * @param {SubnetworkConfig} config - Subnetwork requirements
+     * @returns {Promise<SubnetworkResult>} The built subnetwork with assignments
+     *
+     * @example
+     * ```ts
+     * const result = await subnet.build({
+     *   requiredCapabilities: ['jupiter:swap', 'pyth:getPrice', 'ai:riskScore'],
+     *   strategy: 'balanced',
+     *   minReputation: 500,
+     *   maxCostPerCall: 10000n,
+     * });
+     * ```
+     *
+     * @since 1.4.0
+     */
+    build(config: SubnetworkConfig): Promise<SubnetworkResult>;
+    /**
+     * @description Evaluate the health of an existing subnetwork result.
+     *
+     * Checks each assigned agent's reputation, uptime, and latency,
+     * and identifies capabilities at risk (single provider) or with
+     * redundancy (multiple alternatives).
+     *
+     * @param {SubnetworkResult} subnet - A previously built subnetwork
+     * @returns {SubnetworkHealth} Health assessment
+     *
+     * @since 1.4.0
+     */
+    evaluateHealth(subnet: SubnetworkResult): SubnetworkHealth;
+    /**
+     * @description Rebuild a subnetwork, replacing unhealthy agents with alternatives.
+     *
+     * @param {SubnetworkResult} current - The current subnetwork
+     * @param {SubnetworkConfig} config - Original config (for constraints)
+     * @returns {Promise<SubnetworkResult>} A rebuilt subnetwork
+     *
+     * @since 1.4.0
+     */
+    rebuild(current: SubnetworkResult, config: SubnetworkConfig): Promise<SubnetworkResult>;
+    /**
+     * @description Estimate the total cost for N calls through the subnetwork.
+     * @param {SubnetworkResult} subnet - Built subnetwork
+     * @param {number} calls - Number of calls to estimate for
+     * @returns {{ totalCost: bigint; perAgent: Array<{ agent: string; cost: bigint }> }}
+     * @since 1.4.0
+     */
+    estimateCost(subnet: SubnetworkResult, calls: number): {
+        totalCost: bigint;
+        perAgent: Array<{
+            agent: string;
+            cost: bigint;
+        }>;
+    };
+    private scoreAgent;
+    private findPricing;
+}
+//# sourceMappingURL=subnetwork.d.ts.map

package/dist/esm/ai/sap/subnetwork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subnetwork.d.ts","sourceRoot":"","sources":["../../../../src/ai/sap/subnetwork.ts"],"names":[],"mappings":"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"}