kompass-sdk 0.1.0

package/src/router.ts

@@ -0,0 +1,279 @@
+/**
+ * Kompass Capability Router
+ *
+ * The core product logic. Given a task, figure out the best way to get it done.
+ *
+ * kompass.do("get DeFi yield data") →
+ *   1. Parse intent → what capability is needed
+ *   2. Search all sources → where can I get it
+ *   3. Rank options → cost, speed, reliability, reputation
+ *   4. Execute via right protocol → ACP, x402, MCP, skill, A2A
+ *   5. Return result
+ */
+
+import type { UnifiedAgent } from "./sources/types.js";
+import { Aggregator } from "./aggregator.js";
+import { rankAgents, parseIntent, type MatchResult } from "./matching.js";
+import { ProtocolBridge, type BridgeHireResult } from "./bridge.js";
+
+export type CostPreference = "cheapest" | "balanced" | "best-quality";
+
+export interface DoOptions {
+  /** What you want done — natural language */
+  task: string;
+  /** Cost preference */
+  costPreference?: CostPreference;
+  /** Max budget in USD (e.g., 1.0 = $1) */
+  maxBudgetUSD?: number;
+  /** Prefer specific protocol */
+  preferProtocol?: string;
+  /** Prefer specific source */
+  preferSource?: string;
+  /** Timeout per capability in ms */
+  timeout?: number;
+  /** Return options without executing (dry run) */
+  dryRun?: boolean;
+  /** Additional payload to send to the capability */
+  payload?: Record<string, unknown>;
+}
+
+export interface CapabilityOption {
+  agent: UnifiedAgent;
+  scores: MatchResult["scores"];
+  estimatedCost: number | null;
+  protocol: string;
+  source: string;
+  why: string;
+}
+
+export interface DoResult {
+  success: boolean;
+  /** The task that was requested */
+  task: string;
+  /** All options found across protocols */
+  options: CapabilityOption[];
+  /** The option that was selected and executed */
+  selected: CapabilityOption | null;
+  /** Result from executing the selected option */
+  execution: BridgeHireResult | null;
+  /** Discovery metadata */
+  discovery: {
+    sourcesQueried: number;
+    totalFound: number;
+    queryTimeMs: number;
+  };
+  /** Why this option was selected */
+  reasoning: string;
+}
+
+export class CapabilityRouter {
+  private aggregator: Aggregator;
+  private bridge: ProtocolBridge;
+
+  constructor(aggregator: Aggregator, bridge: ProtocolBridge) {
+    this.aggregator = aggregator;
+    this.bridge = bridge;
+  }
+
+  async do(options: DoOptions): Promise<DoResult> {
+    const { task, dryRun = false } = options;
+
+    // 1. Search all sources
+    const searchResult = await this.aggregator.search(task, {
+      limit: 30,
+      timeout: options.timeout ?? 15000,
+    });
+
+    if (searchResult.agents.length === 0) {
+      return {
+        success: false,
+        task,
+        options: [],
+        selected: null,
+        execution: null,
+        discovery: {
+          sourcesQueried: searchResult.sources.length,
+          totalFound: 0,
+          queryTimeMs: searchResult.queryTimeMs,
+        },
+        reasoning: "No capabilities found for this task across any registry.",
+      };
+    }
+
+    // 2. Rank with multi-layer matching
+    const ranked = rankAgents(searchResult.agents, task);
+
+    // 3. Build options with cost estimates
+    const capabilityOptions = ranked.map((r) => this.buildOption(r, options));
+
+    // 4. Filter by budget
+    const affordable = options.maxBudgetUSD
+      ? capabilityOptions.filter(
+          (o) => o.estimatedCost === null || o.estimatedCost <= options.maxBudgetUSD!
+        )
+      : capabilityOptions;
+
+    // 5. Apply preference-based reranking
+    const reranked = this.applyPreferences(affordable.length > 0 ? affordable : capabilityOptions, options);
+
+    // 6. Select best option
+    const selected = reranked[0] ?? null;
+
+    if (!selected) {
+      return {
+        success: false,
+        task,
+        options: capabilityOptions,
+        selected: null,
+        execution: null,
+        discovery: {
+          sourcesQueried: searchResult.sources.length,
+          totalFound: searchResult.totalFound,
+          queryTimeMs: searchResult.queryTimeMs,
+        },
+        reasoning: options.maxBudgetUSD
+          ? `Found ${capabilityOptions.length} options but none within budget ($${options.maxBudgetUSD}).`
+          : "No suitable options found after ranking.",
+      };
+    }
+
+    // 7. Execute (unless dry run)
+    let execution: BridgeHireResult | null = null;
+
+    if (!dryRun) {
+      execution = await this.bridge.hire(selected.agent, {
+        task,
+        timeout: options.timeout,
+        payload: options.payload,
+      });
+    }
+
+    const reasoning = this.explainChoice(selected, reranked, options);
+
+    return {
+      success: dryRun ? true : (execution?.success ?? false),
+      task,
+      options: capabilityOptions.slice(0, 10), // Top 10 options
+      selected,
+      execution,
+      discovery: {
+        sourcesQueried: searchResult.sources.length,
+        totalFound: searchResult.totalFound,
+        queryTimeMs: searchResult.queryTimeMs,
+      },
+      reasoning,
+    };
+  }
+
+  private buildOption(match: MatchResult, options: DoOptions): CapabilityOption {
+    const agent = match.agent;
+    let estimatedCost: number | null = null;
+
+    if (agent.pricing?.amount) {
+      estimatedCost = parseFloat(agent.pricing.amount);
+    } else if (agent.pricing?.model === "free") {
+      estimatedCost = 0;
+    }
+
+    let why = "";
+    if (match.scores.structured > 10) why += "Strong capability match. ";
+    if (match.scores.bm25 > 5) why += "High text relevance. ";
+    if (match.scores.multiCriteria > 15) why += "Good reputation/trust signals. ";
+    if (estimatedCost === 0) why += "Free. ";
+    if (estimatedCost !== null && estimatedCost > 0 && estimatedCost < 0.05) why += "Very affordable. ";
+
+    return {
+      agent,
+      scores: match.scores,
+      estimatedCost,
+      protocol: agent.protocol,
+      source: agent.source,
+      why: why.trim() || "General match.",
+    };
+  }
+
+  private applyPreferences(options: CapabilityOption[], doOptions: DoOptions): CapabilityOption[] {
+    let sorted = [...options];
+
+    // Protocol preference
+    if (doOptions.preferProtocol) {
+      sorted.sort((a, b) => {
+        const aMatch = a.protocol === doOptions.preferProtocol ? 1 : 0;
+        const bMatch = b.protocol === doOptions.preferProtocol ? 1 : 0;
+        return bMatch - aMatch;
+      });
+    }
+
+    // Source preference
+    if (doOptions.preferSource) {
+      sorted.sort((a, b) => {
+        const aMatch = a.source === doOptions.preferSource ? 1 : 0;
+        const bMatch = b.source === doOptions.preferSource ? 1 : 0;
+        return bMatch - aMatch;
+      });
+    }
+
+    // Cost preference reranking
+    switch (doOptions.costPreference) {
+      case "cheapest":
+        sorted.sort((a, b) => {
+          const aCost = a.estimatedCost ?? Infinity;
+          const bCost = b.estimatedCost ?? Infinity;
+          return aCost - bCost;
+        });
+        break;
+
+      case "best-quality":
+        // Already sorted by score, but boost high-reputation agents
+        sorted.sort((a, b) => {
+          const aRep = a.agent.reputation?.score ?? 0;
+          const bRep = b.agent.reputation?.score ?? 0;
+          return bRep - aRep || b.scores.total - a.scores.total;
+        });
+        break;
+
+      case "balanced":
+      default:
+        // Default: score-based with cost as tiebreaker
+        sorted.sort((a, b) => {
+          if (Math.abs(b.scores.total - a.scores.total) > 5) {
+            return b.scores.total - a.scores.total;
+          }
+          const aCost = a.estimatedCost ?? 1;
+          const bCost = b.estimatedCost ?? 1;
+          return aCost - bCost;
+        });
+        break;
+    }
+
+    return sorted;
+  }
+
+  private explainChoice(
+    selected: CapabilityOption,
+    alternatives: CapabilityOption[],
+    options: DoOptions
+  ): string {
+    const parts: string[] = [];
+
+    parts.push(
+      `Selected "${selected.agent.name}" via ${selected.protocol.toUpperCase()} from ${selected.source}.`
+    );
+
+    if (selected.estimatedCost !== null) {
+      parts.push(
+        selected.estimatedCost === 0
+          ? "This option is free."
+          : `Estimated cost: $${selected.estimatedCost}.`
+      );
+    }
+
+    parts.push(selected.why);
+
+    if (alternatives.length > 1) {
+      parts.push(`${alternatives.length - 1} other options available.`);
+    }
+
+    return parts.join(" ");
+  }
+}

package/src/simple.ts

@@ -0,0 +1,366 @@
+/**
+ * Kompass Simplified API
+ *
+ * Dead-simple interface for agent-to-agent commerce.
+ * Wraps ACP escrow + Kompass intelligence (reputation, x402, intent routing).
+ *
+ * Usage:
+ *   const kompass = await KompassSimple.create({ privateKey, network: "base-sepolia" });
+ *   const result = await kompass.hireAgent({ task: "Find best yield on Base", maxBudget: 1_000_000n });
+ */
+
+import type { Address, Hex } from "viem";
+import { createPublicClient, http } from "viem";
+import { baseSepolia, base } from "viem/chains";
+import { privateKeyToAccount } from "viem/accounts";
+import { AcpEscrowBackend, type AcpBackendConfig } from "./backends/acp.js";
+import type {
+  EscrowBackend,
+  AgentSearchResult,
+  JobResult,
+  IncomingJob,
+} from "./backends/types.js";
+import { getReputation } from "./reputation.js";
+import type { KompassConfig, ReputationSummary } from "./types.js";
+
+// ── Config ───────────────────────────────────────────────
+
+export interface KompassSimpleConfig {
+  /** Agent's private key */
+  privateKey: string;
+  /** Network: "base-sepolia" or "base" */
+  network?: "base-sepolia" | "base";
+  /** ACP entity/session key address (from ACP registration) */
+  acpEntityAddress?: string;
+  /** ACP wallet address */
+  acpWalletAddress?: string;
+  /** Kompass indexer URL for ENS discovery + reputation */
+  indexerUrl?: string;
+  /** ERC-8004 reputation registry address */
+  reputationRegistryAddress?: Address;
+  /** Custom RPC URL */
+  rpcUrl?: string;
+}
+
+// ── Hire Options ─────────────────────────────────────────
+
+export interface HireOptions {
+  /** What you want done — natural language task description */
+  task: string;
+  /** Max budget in USDC base units (6 decimals). 1_000_000 = $1 */
+  maxBudget?: bigint;
+  /** Minimum ERC-8004 reputation score to trust an agent */
+  minReputation?: number;
+  /** Search query override (defaults to task) */
+  searchQuery?: string;
+  /** Specific offering ID if known */
+  offeringId?: string;
+  /** Additional requirements to send to the agent */
+  requirements?: Record<string, unknown>;
+  /** Timeout in ms for waiting for deliverable (default 5 min) */
+  timeoutMs?: number;
+}
+
+export interface HireResult {
+  agent: AgentSearchResult;
+  jobId: string;
+  deliverable: unknown;
+  phase: string;
+  reputationChecked: boolean;
+  txHash?: string;
+}
+
+// ── Accept Options ───────────────────────────────────────
+
+export interface AcceptJobsOptions {
+  /** What capabilities this agent offers */
+  capabilities: string[];
+  /** Handler called when a job comes in — return the deliverable */
+  handler: (job: IncomingJob) => Promise<unknown>;
+}
+
+// ── Orchestrate Options ──────────────────────────────────
+
+export interface OrchestrateOptions {
+  /** High-level intent — will be decomposed into multiple agent hires */
+  intent: string;
+  /** Risk tolerance for DeFi intents */
+  riskTolerance?: "conservative" | "balanced" | "aggressive";
+  /** Total budget across all steps */
+  budget?: bigint;
+  /** Minimum reputation for any hired agent */
+  minReputation?: number;
+}
+
+export interface OrchestrateResult {
+  intent: string;
+  steps: {
+    role: string;
+    agent: AgentSearchResult | null;
+    result: HireResult | null;
+    skipped: boolean;
+    reason?: string;
+  }[];
+  totalCostUSDC: number;
+  completedSteps: number;
+}
+
+// ── Main Class ───────────────────────────────────────────
+
+export class KompassSimple {
+  private backend: EscrowBackend;
+  private config: KompassSimpleConfig;
+  private kompassConfig: KompassConfig | null = null;
+
+  private constructor(config: KompassSimpleConfig, backend: EscrowBackend) {
+    this.config = config;
+    this.backend = backend;
+  }
+
+  /**
+   * Create and initialize a Kompass instance.
+   *
+   * @example
+   * const kompass = await KompassSimple.create({
+   *   privateKey: "0x...",
+   *   network: "base-sepolia",
+   *   acpEntityAddress: "0x...",
+   *   acpWalletAddress: "0x...",
+   * });
+   */
+  static async create(config: KompassSimpleConfig): Promise<KompassSimple> {
+    const account = privateKeyToAccount(config.privateKey as Hex);
+    const chain = config.network === "base" ? base : baseSepolia;
+    const rpcUrl = config.rpcUrl ?? (config.network === "base" ? "https://mainnet.base.org" : "https://sepolia.base.org");
+
+    // Create ACP backend
+    const acpConfig: AcpBackendConfig = {
+      privateKey: config.privateKey,
+      walletAddress: (config.acpWalletAddress ?? account.address) as Address,
+      entityAddress: (config.acpEntityAddress ?? account.address) as Address,
+      network: config.network ?? "base-sepolia",
+      rpcUrl,
+    };
+
+    const backend = new AcpEscrowBackend(acpConfig);
+    await backend.init();
+
+    const instance = new KompassSimple(config, backend);
+
+    // Set up Kompass config for reputation queries if registry address provided
+    if (config.reputationRegistryAddress) {
+      const publicClient = createPublicClient({
+        chain,
+        transport: http(rpcUrl),
+      });
+      instance.kompassConfig = {
+        publicClient,
+        escrowAddress: "0x0000000000000000000000000000000000000000" as Address,
+        registryAddress: "0x0000000000000000000000000000000000000000" as Address,
+        reputationRegistryAddress: config.reputationRegistryAddress,
+        indexerUrl: config.indexerUrl ?? "",
+      } as KompassConfig;
+    }
+
+    return instance;
+  }
+
+  /**
+   * Hire an agent to do a task.
+   *
+   * Under the hood:
+   * 1. Searches ACP marketplace for matching agents
+   * 2. Checks ERC-8004 reputation (if configured)
+   * 3. Creates an ACP job and waits for delivery
+   * 4. Returns the deliverable
+   *
+   * @example
+   * const result = await kompass.hireAgent({
+   *   task: "Find the best yield for 1000 USDC on Base",
+   *   maxBudget: 1_000_000n,
+   * });
+   * console.log(result.deliverable);
+   */
+  async hireAgent(options: HireOptions): Promise<HireResult> {
+    const query = options.searchQuery ?? options.task;
+
+    // 1. Discover agents on ACP
+    const agents = await this.backend.browseAgents(query, {
+      limit: 10,
+      sortBy: "successRate",
+      onlineOnly: true,
+    });
+
+    if (agents.length === 0) {
+      throw new Error(`No agents found for: "${query}"`);
+    }
+
+    // 2. Check reputation (if configured)
+    let reputationChecked = false;
+    let filteredAgents = agents;
+
+    if (this.kompassConfig && options.minReputation !== undefined) {
+      filteredAgents = [];
+      for (const agent of agents) {
+        try {
+          const rep = await this.checkReputation(agent.address);
+          const score = Number(rep.summaryValue);
+          if (score >= options.minReputation || Number(rep.count) === 0) {
+            filteredAgents.push(agent);
+          }
+        } catch {
+          // If reputation check fails, include the agent (permissive)
+          filteredAgents.push(agent);
+        }
+      }
+      reputationChecked = true;
+
+      if (filteredAgents.length === 0) {
+        throw new Error(
+          `No agents meet reputation threshold (${options.minReputation}). Found ${agents.length} agents but none passed.`
+        );
+      }
+    }
+
+    // 3. Select best agent (first match after filtering)
+    const agent = filteredAgents[0];
+    const offering = agent.offerings[0];
+
+    if (!offering) {
+      throw new Error(`Agent "${agent.name}" has no offerings`);
+    }
+
+    // 4. Create job on ACP
+    const requirements = {
+      description: options.task,
+      ...options.requirements,
+    };
+
+    const job = await this.backend.hireAgent(
+      agent,
+      options.offeringId ?? offering.id,
+      requirements,
+      options.maxBudget
+    );
+
+    // 5. Wait for result
+    const result = await this.backend.waitForResult(
+      job.jobId,
+      options.timeoutMs ?? 300_000
+    );
+
+    return {
+      agent,
+      jobId: result.jobId,
+      deliverable: result.deliverable,
+      phase: result.phase,
+      reputationChecked,
+      txHash: result.txHash,
+    };
+  }
+
+  /**
+   * Start accepting jobs from other agents.
+   *
+   * Registers on ACP and listens for incoming jobs matching your capabilities.
+   * When a job arrives, your handler is called. Return the deliverable and
+   * the SDK handles ACP delivery automatically.
+   *
+   * @example
+   * await kompass.acceptJobs({
+   *   capabilities: ["defi-research", "yield-analysis"],
+   *   handler: async (job) => {
+   *     const report = await doResearch(job.description);
+   *     return report;
+   *   },
+   * });
+   */
+  async acceptJobs(options: AcceptJobsOptions): Promise<void> {
+    await this.backend.acceptJobs(options.capabilities, options.handler);
+  }
+
+  /**
+   * Orchestrate a multi-agent pipeline for a complex intent.
+   *
+   * Decomposes the intent into specialist roles (research, data, risk, execution),
+   * hires an agent for each role via ACP, chains results, and returns the combined output.
+   *
+   * @example
+   * const result = await kompass.orchestrate({
+   *   intent: "Find best yield for 1000 USDC on Base",
+   *   riskTolerance: "balanced",
+   *   budget: 5_000_000n,
+   * });
+   */
+  async orchestrate(options: OrchestrateOptions): Promise<OrchestrateResult> {
+    const roles = ["research", "premium-data", "risk", "execution"];
+    const perStepBudget = options.budget
+      ? options.budget / BigInt(roles.length)
+      : 1_000_000n;
+
+    const steps: OrchestrateResult["steps"] = [];
+    let totalCost = 0;
+
+    for (const role of roles) {
+      try {
+        const result = await this.hireAgent({
+          task: `[${role}] ${options.intent}`,
+          searchQuery: role === "premium-data" ? "data analytics" : role,
+          maxBudget: perStepBudget,
+          minReputation: options.minReputation,
+          timeoutMs: 120_000,
+        });
+
+        steps.push({
+          role,
+          agent: result.agent,
+          result,
+          skipped: false,
+        });
+
+        totalCost += Number(perStepBudget) / 1e6;
+      } catch (err) {
+        steps.push({
+          role,
+          agent: null,
+          result: null,
+          skipped: true,
+          reason: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    return {
+      intent: options.intent,
+      steps,
+      totalCostUSDC: totalCost,
+      completedSteps: steps.filter((s) => !s.skipped).length,
+    };
+  }
+
+  /**
+   * Check an agent's ERC-8004 on-chain reputation.
+   */
+  async checkReputation(agentAddress: Address): Promise<ReputationSummary> {
+    if (!this.kompassConfig) {
+      throw new Error("Reputation checking requires reputationRegistryAddress in config");
+    }
+    // Use agent address as ID (simplified — in production, look up erc8004Id)
+    return getReputation(this.kompassConfig, 0n);
+  }
+
+  /**
+   * Search for agents on ACP marketplace.
+   */
+  async discover(query: string, options?: { limit?: number }): Promise<AgentSearchResult[]> {
+    return this.backend.browseAgents(query, {
+      limit: options?.limit ?? 20,
+      sortBy: "successRate",
+    });
+  }
+
+  /** Get the backend name */
+  get backendName(): string {
+    return this.backend.name();
+  }
+}