@lawrenceliang-btc/atel-sdk 0.8.7

package/dist/graph/index.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Module 8: Trust Graph
+ *
+ * Multi-dimensional trust graph tracking agent collaboration,
+ * scene performance, and trust propagation.
+ *
+ * Core formulas:
+ *   DirectTrust(A,B,scene) = success_weighted_rate × recency × consistency × confidence
+ *   IndirectTrust(A,C)     = max path trust × hop_decay^(hops-1)
+ *   CompositeTrust         = α·Direct + β·Indirect + γ·ReputationBonus
+ */
+/** Graph node representing an Agent */
+export interface GraphNode {
+    agent_id: string;
+    registered_at: string;
+    total_interactions: number;
+    scenes: Set<string>;
+    metadata?: Record<string, any>;
+}
+/** Collaboration edge between two Agents in a specific scene */
+export interface GraphEdge {
+    from: string;
+    to: string;
+    scene: string;
+    total_tasks: number;
+    successful_tasks: number;
+    failed_tasks: number;
+    total_weight: number;
+    successful_weight: number;
+    avg_duration_ms: number;
+    last_interaction: string;
+    consistency_score: number;
+}
+/** Trust query result */
+export interface TrustResult {
+    trust_score: number;
+    confidence: number;
+    source: 'direct' | 'indirect' | 'composite';
+    path?: string[];
+    details: {
+        direct_trust?: number;
+        indirect_trust?: number;
+        reputation_bonus?: number;
+    };
+}
+/** Parameters for task weight calculation */
+export interface TaskWeightParams {
+    tool_calls: number;
+    duration_ms: number;
+    max_cost: number;
+    risk_level: 'low' | 'medium' | 'high' | 'critical';
+    similar_task_count: number;
+}
+/** Interaction record for updating the graph */
+export interface InteractionRecord {
+    from: string;
+    to: string;
+    scene: string;
+    success: boolean;
+    task_weight: number;
+    duration_ms: number;
+}
+/**
+ * Calculate task weight from execution parameters.
+ *
+ * Formula:
+ *   task_weight = complexity × value × risk × novelty
+ *
+ * Where:
+ *   complexity = min(1, tool_calls × 0.2 + duration_ms / 10000 × 0.3)
+ *   value      = min(1, max_cost / 10)
+ *   risk       = {low:0.5, medium:1.0, high:2.0, critical:3.0}
+ *   novelty    = 1 / (1 + ln(1 + similar_task_count))
+ *
+ * Example: tool_calls=5, duration_ms=8000, max_cost=5, risk='medium', similar=2
+ *   complexity = min(1, 5×0.2 + 0.8×0.3) = min(1, 1.24) = 1
+ *   value      = min(1, 0.5) = 0.5
+ *   risk       = 1.0
+ *   novelty    = 1/(1+ln(3)) ≈ 0.476
+ *   weight     = 1 × 0.5 × 1.0 × 0.476 ≈ 0.238
+ */
+export declare function calculateTaskWeight(params: TaskWeightParams): number;
+/**
+ * Multi-dimensional trust graph.
+ *
+ * Nodes = agents, edges = per-scene collaboration records.
+ * Supports direct, indirect, and composite trust queries,
+ * anomaly detection, and graph export.
+ */
+export declare class TrustGraph {
+    private nodes;
+    private edges;
+    /** Register a new agent node. Idempotent — re-adding updates metadata. */
+    addNode(agentId: string, metadata?: Record<string, any>): void;
+    getNode(agentId: string): GraphNode | undefined;
+    /** Remove a node and all its edges. */
+    removeNode(agentId: string): void;
+    /**
+     * Record a single collaboration interaction.
+     * Auto-creates nodes if they don't exist.
+     * Updates edge statistics and node interaction counts.
+     *
+     * Consistency score is maintained as a running exponential moving average
+     * of success (1) / failure (0) variance across recent interactions.
+     */
+    recordInteraction(interaction: InteractionRecord): void;
+    getEdge(from: string, to: string, scene: string): GraphEdge | undefined;
+    /** Get all edges involving a given agent (as from or to). */
+    getEdges(agentId: string): GraphEdge[];
+    /**
+     * Direct trust between two agents in a scene.
+     *
+     * Formula:
+     *   DirectTrust = swr × recency × consistency × confidence
+     *
+     *   swr        = successful_weight / total_weight
+     *   recency    = exp(-0.01 × days_since_last)
+     *   consistency = edge.consistency_score
+     *   confidence = min(1, total_tasks / 20)
+     *
+     * Example: swr=0.8, 10 days ago, consistency=0.9, 15 tasks
+     *   recency    = exp(-0.01×10) ≈ 0.905
+     *   confidence = min(1, 15/20) = 0.75
+     *   trust      = 0.8 × 0.905 × 0.9 × 0.75 ≈ 0.489
+     *
+     * Returns trust_score=0 when no edge exists.
+     */
+    directTrust(from: string, to: string, scene: string): TrustResult;
+    /**
+     * Indirect trust via intermediate nodes (BFS, max depth 3).
+     *
+     * For each path P from A to B:
+     *   path_trust = ∏(DirectTrust(edge_i)) × 0.7^(|P|-1)
+     *
+     * Returns the strongest path.
+     *
+     * Example: A→M trust=0.8, M→B trust=0.7, depth=2
+     *   path_trust = 0.8 × 0.7 × 0.7^(2-1) = 0.8 × 0.7 × 0.7 = 0.392
+     */
+    indirectTrust(from: string, to: string, scene: string, maxDepth?: number): TrustResult;
+    /**
+     * Composite trust combining direct, indirect, and reputation.
+     *
+     * CompositeTrust = α×Direct + β×Indirect + γ×ReputationBonus
+     *   α=0.6, β=0.3, γ=0.1
+     *
+     * If no direct trust exists, α's weight transfers to β:
+     *   β_effective = β + α = 0.9
+     *
+     * ReputationBonus = global_success_rate × 0.5
+     */
+    compositeTrust(from: string, to: string, scene: string): TrustResult;
+    /** Global success rate across all edges. */
+    private _globalSuccessRate;
+    /**
+     * Scene reputation: average incoming trust for an agent in a scene.
+     * Averages directTrust from all agents that have interacted with this agent.
+     */
+    sceneReputation(agentId: string, scene: string): number;
+    /** Top-K partners by composite trust (across all scenes). */
+    topPartners(agentId: string, k: number): Array<{
+        agent_id: string;
+        trust: number;
+    }>;
+    /** Top-K agents for a scene by reputation. */
+    topAgentsForScene(scene: string, k: number): Array<{
+        agent_id: string;
+        reputation: number;
+    }>;
+    /**
+     * Strongest trust path from A to B (any depth up to 3).
+     * Uses the same BFS as indirectTrust but also considers direct (1-hop).
+     */
+    strongestPath(from: string, to: string, scene: string): {
+        path: string[];
+        trust: number;
+    } | null;
+    /**
+     * Behavior Consistency Score (BCS).
+     *
+     * BCS = 1 - (max_success_rate - min_success_rate) across all partners.
+     * Suspicious if BCS < 0.7 (agent treats different partners very differently).
+     */
+    behaviorConsistencyScore(agentId: string): {
+        score: number;
+        suspicious: boolean;
+        details: Record<string, number>;
+    };
+    /**
+     * Detect suspicious clusters (simplified Sybil detection).
+     *
+     * For each pair of agents, compute internal vs external interaction ratio.
+     * Groups with internal_ratio >> external_ratio are suspicious.
+     */
+    detectSuspiciousClusters(minClusterSize?: number): Array<{
+        agents: string[];
+        suspicion_score: number;
+    }>;
+    /** Generate combinations of size k from array. */
+    private _combinations;
+    private _rankAgentsByActivity;
+    /** Export the full graph as plain objects (Sets converted to arrays). */
+    exportGraph(): {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    };
+    /** Aggregate statistics. */
+    getStats(): {
+        total_nodes: number;
+        total_edges: number;
+        total_interactions: number;
+        scenes: string[];
+        avg_trust: number;
+    };
+}