RATED (arXiv:2610.13889): Reliability-Aware AI Agent Tool Retrieval via Execution Dynamics, EcoAgent Benchmark 5.172 Tools, dan Solusi 2.9% Fault Selection Rate di Bawah Pemadaman API Ekstrem

// Production Implementation: RATED Runtime Execution Engine & Contextual Bandit Adapter
// Mengimplementasikan Two-Stage Decoupled Retrieval, Tri-Signal Static Prior,
// Discounted LinUCB Online Re-ranking, dan Feedback Dynamic Updates
// Berdasarkan formulasi formal arXiv:2610.13889 (ACM CIKM 2026)

export interface ToolMetadata {
  id: string;
  name: string;
  description: string;
  platform: 'official' | 'langchain' | 'crewai' | 'llamaindex' | 'n8n' | 'custom';
  tags: string[];
}

export interface ToolExecutionContext {
  queryEmbedding: number[]; // e_q \in R^d
  selectedToolId: string;
  executionSuccess: boolean; // y_t \in {0, 1}
  timestamp: number;
}

export interface BanditArmState {
  A_diag: number[]; // Diagonal covariance matrix representation for O(d) scoring
  b_vec: number[];  // Bias vector b_a \in R^d
  usageCount: number;
  lastExecutedTimestamp: number;
}

export interface RATEDConfig {
  d_dim: number;               // Embedding dimension (default: 768 for DRAGON)
  topKCandidates: number;      // K candidate pool from semantic retrieval (default: 10)
  discountFactorGamma: number; // \gamma: discount factor for non-stationary outage recovery (default: 0.95)
  explorationAlpha: number;    // \alpha: exploration trade-off coefficient (default: 0.10)
  weights: {
    w1_semantic: number;       // w1: Semantic similarity weight (default: 0.75)
    w2_bandit: number;         // w2: Online contextual bandit score weight (default: 0.15)
    w3_static: number;         // w3: Metadata static prior weight (default: 0.10)
  };
  staticPriorLambdas: {
    lambda1_cons: number;      // \lambda1: Name-description consistency (default: 0.50)
    lambda2_source: number;    // \lambda2: Source platform credibility (default: 0.30)
    lambda3_quality: number;   // \lambda3: Documentation length quality (default: 0.20)
  };
}

export class RATEDExecutionEngine {
  private config: RATEDConfig;
  private arms: Map = new Map();
  private staticPriors: Map = new Map();

  constructor(config?: Partial) {
    this.config = {
      d_dim: config?.d_dim ?? 768,
      topKCandidates: config?.topKCandidates ?? 10,
      discountFactorGamma: config?.discountFactorGamma ?? 0.95,
      explorationAlpha: config?.explorationAlpha ?? 0.10,
      weights: {
        w1_semantic: config?.weights?.w1_semantic ?? 0.75,
        w2_bandit: config?.weights?.w2_bandit ?? 0.15,
        w3_static: config?.weights?.w3_static ?? 0.10,
      },
      staticPriorLambdas: {
        lambda1_cons: config?.staticPriorLambdas?.lambda1_cons ?? 0.50,
        lambda2_source: config?.staticPriorLambdas?.lambda2_source ?? 0.30,
        lambda3_quality: config?.staticPriorLambdas?.lambda3_quality ?? 0.20,
      },
    };
  }

  /**
   * 1. Inisialisasi Static Reliability Prior r_static(a)
   * Formula Eq. (4) & (5):
   * r_cons = cos(f_Enc(name), f_Enc(desc))
   * r_static = lambda1 * r_cons + lambda2 * w_src + lambda3 * r_qual
   */
  public registerTool(tool: ToolMetadata, nameDescCosine: number): void {
    const { lambda1_cons, lambda2_source, lambda3_quality } = this.config.staticPriorLambdas;

    // Platform credibility weight w_src
    const sourceWeights: Record = {
      official: 1.0,
      langchain: 0.9,
      crewai: 0.9,
      llamaindex: 0.9,
      n8n: 0.8,
      custom: 0.6,
    };
    const w_src = sourceWeights[tool.platform] ?? 0.6;

    // Documentation quality r_qual (logistic scaling based on normalized length)
    const normLen = Math.min(1.0, tool.description.length / 500);
    const r_qual = 1 / (1 + Math.exp(-4 * (normLen - 0.5)));

    // Composite static prior
    const r_static = (lambda1_cons * Math.max(0, nameDescCosine)) +
                     (lambda2_source * w_src) +
                     (lambda3_quality * r_qual);

    this.staticPriors.set(tool.id, r_static);

    // Inisialisasi arm bandit dengan cold-start bias b_a <- r_static * (1 / sqrt(d))
    const initialBias = r_static / Math.sqrt(this.config.d_dim);
    this.arms.set(tool.id, {
      A_diag: new Array(this.config.d_dim).fill(1.0), // I_d diagonal
      b_vec: new Array(this.config.d_dim).fill(initialBias),
      usageCount: 0,
      lastExecutedTimestamp: Date.now(),
    });
  }

  /**
   * 2. Menghitung Skor LinUCB Bandit S_bandit(x_t, a)
   * Formula Eq. (6), (7), & (8):
   * theta_a = A_a^(-1) * b_a
   * S_bandit = theta_a^T * x_t + alpha * sqrt(x_t^T * A_a^(-1) * x_t)
   */
  public computeBanditScore(toolId: string, queryEmbedding: number[]): number {
    const arm = this.arms.get(toolId);
    if (!arm) return 0.5;

    const { explorationAlpha, d_dim } = this.config;
    let expectedReward = 0;
    let variance = 0;

    for (let i = 0; i < d_dim; i++) {
      const invA = 1.0 / arm.A_diag[i];
      const theta_i = invA * arm.b_vec[i];
      const x_i = queryEmbedding[i] || 0;

      expectedReward += theta_i * x_i;
      variance += x_i * invA * x_i;
    }

    const ucbBonus = explorationAlpha * Math.sqrt(Math.max(0, variance));
    return expectedReward + ucbBonus;
  }

  /**
   * 3. Hybrid Fusion Re-ranking
   * Formula Eq. (9):
   * S_final(q_t, a) = w1 * S_sem(q_t, a) + w2 * S_bandit(x_t, a) + w3 * r_static(a)
   */
  public rankCandidates(
    candidates: Array<{ toolId: string; semanticScore: number }>,
    queryEmbedding: number[]
  ): Array<{ toolId: string; finalScore: number; semanticScore: number; banditScore: number; staticPrior: number }> {
    const { w1_semantic, w2_bandit, w3_static } = this.config.weights;

    return candidates
      .map((c) => {
        const banditScore = this.computeBanditScore(c.toolId, queryEmbedding);
        const staticPrior = this.staticPriors.get(c.toolId) ?? 0.5;
        const finalScore = (w1_semantic * c.semanticScore) +
                           (w2_bandit * banditScore) +
                           (w3_static * staticPrior);

        return {
          toolId: c.toolId,
          finalScore,
          semanticScore: c.semanticScore,
          banditScore,
          staticPrior,
        };
      })
      .sort((a, b) => b.finalScore - a.finalScore);
  }

  /**
   * 4. Online Feedback Update (Discounted LinUCB)
   * Formula Eq. (10) & (11):
   * A_a <- gamma * A_a + (1 - gamma) * I_d + x_t * x_t^T
   * b_a <- gamma * b_a + y_t * x_t
   */
  public updateExecutionFeedback(
    toolId: string,
    queryEmbedding: number[],
    success: boolean
  ): void {
    const arm = this.arms.get(toolId);
    if (!arm) return;

    const { discountFactorGamma: gamma, d_dim } = this.config;
    const y_t = success ? 1.0 : 0.0;

    for (let i = 0; i < d_dim; i++) {
      const x_i = queryEmbedding[i] || 0;
      // Discounted update menjaga bobot arm adaptif terhadap error temporal
      arm.A_diag[i] = (gamma * arm.A_diag[i]) + ((1.0 - gamma) * 1.0) + (x_i * x_i);
      arm.b_vec[i] = (gamma * arm.b_vec[i]) + (y_t * x_i);
    }

    arm.usageCount += 1;
    arm.lastExecutedTimestamp = Date.now();
  }
}