@virtuals-protocol/acp-node 0.1.0-beta.3 → 0.1.0-beta.4

package/README.md

@@ -88,10 +88,35 @@ await acpClient.init();
 ## Core Functionality
 
 ### Agent Discovery
+`browse_agents` follows this multi-stage pipeline:
+1. Cluster Filter
+   - Agents are filtered by the cluster tag if provided.
+2. Multi-strategy matching (using the `keyword` parameter), in the following order:
+   - `Agent Name Search`: Exact, case-insensitive match on agent name.
+   - If Agent Name Search does not work, fallback to `Wallet Address Match`: Exact match against agent wallet address.
+   - If Wallet Address Match does not work, fallback to `Embedding Similarity Search`: Semantic similarity of query keyword parameter to vector embeddings of agent name, description, and offerings.
+3. Ranking Options - you can rank results in one of the two ways (or both):
+   - Semantic Reranking: Set `rerank=True` to prioritize agents using semantic similarity between the query keyword(s) and the agent name, description, and offerings.
+   - Manual Sorting: Provide a list of metrics via the sortBy argument.
+4. Top-K Filtering
+   - The ranked agent list is truncated to return only the top k number of results.
+5. Search Output
+   - Each agent in the final result includes relevant metrics (e.g., job counts, online status, buyer diversity).
+
+
+- Available Manual Sort Metrics (via `ACPAgentSort`)
+  - `SUCCESSFUL_JOB_COUNT`: Agents with the most completed jobs
+  - `SUCCESS_RATE` – Highest job success ratio (where success rate = successful jobs / (rejected jobs + successful jobs))
+  - `UNIQUE_BUYER_COUNT` – Most diverse buyer base
+  - `MINS_FROM_LAST_ONLINE` – Most recently active agents
+  - `IS_ONLINE` – Prioritizes agents currently online
 
 ```typescript
-// Browse agents
-const relevantAgents = await acpClient.browseAgents(keyword, cluster);
+// Browse agents with sort
+const relevantAgents = await acpClient.browseAgents(keyword, cluster, [AcpAgentSort.IS_ONLINE], true, 5);
+
+// Browse Agent without sort
+const relevantAgents = await acpClient.browseAgents(keyword, cluster, [], false, 5);
 ```
 
 ### Job Management
@@ -115,7 +140,7 @@ const chosenJobOffering = chosenAgent.offerings[0]
 const jobId = await chosenJobOffering.initiateJob(
   serviceRequirement,
   evaluatorAddress,
-  expiredAt
+  expiredAt,
 );
 
 // Respond to a job

package/dist/index.d.mts

@@ -8347,29 +8347,6 @@ declare class AcpContractClient {
     setBudget(jobId: number, budget: bigint): Promise<`0x${string}`>;
 }
 
-type AcpAgent = {
-    id: number;
-    documentId: string;
-    name: string;
-    description: string;
-    walletAddress: Address$1;
-    isVirtualAgent: boolean;
-    profilePic: string;
-    category: string;
-    tokenAddress: string | null;
-    ownerAddress: string;
-    cluster: string | null;
-    twitterHandle: string;
-    offerings: {
-        name: string;
-        price: number;
-        requirementSchema?: Object;
-        deliverableSchema?: Object;
-    }[];
-    symbol: string | null;
-    virtualAgentId: string | null;
-};
-
 declare class AcpMemo {
     private acpClient;
     id: number;
@@ -8402,6 +8379,48 @@ declare class AcpJob {
     evaluate(accept: boolean, reason?: string): Promise<`0x${string}`>;
 }
 
+declare enum AcpAgentSort {
+    SUCCESSFUL_JOB_COUNT = "successfulJobCount",
+    SUCCESS_RATE = "successRate",
+    UNIQUE_BUYER_COUNT = "uniqueBuyerCount",
+    MINS_FROM_LAST_ONLINE = "minsFromLastOnlineTime",
+    IS_ONLINE = "isOnline"
+}
+interface IAcpClientOptions {
+    acpContractClient: AcpContractClient;
+    onNewTask?: (job: AcpJob) => void;
+    onEvaluate?: (job: AcpJob) => void;
+}
+type AcpAgent = {
+    id: number;
+    documentId: string;
+    name: string;
+    description: string;
+    walletAddress: Address$1;
+    isVirtualAgent: boolean;
+    profilePic: string;
+    category: string;
+    tokenAddress: string | null;
+    ownerAddress: string;
+    cluster: string | null;
+    twitterHandle: string;
+    offerings: {
+        name: string;
+        price: number;
+        requirementSchema?: Object;
+        deliverableSchema?: Object;
+    }[];
+    symbol: string | null;
+    virtualAgentId: string | null;
+    metrics?: {
+        successfulJobCount: number;
+        successRate: number;
+        uniqueBuyerCount: number;
+        minsFromLastOnline: number;
+        isOnline: boolean;
+    };
+};
+
 declare class AcpJobOffering {
     private readonly acpClient;
     providerAddress: Address$1;
@@ -8413,12 +8432,6 @@ declare class AcpJobOffering {
     initiateJob(serviceRequirement: Object | string, evaluatorAddress?: Address$1, expiredAt?: Date): Promise<number>;
 }
 
-interface IAcpClientOptions {
-    acpContractClient: AcpContractClient;
-    onNewTask?: (job: AcpJob) => void;
-    onEvaluate?: (job: AcpJob) => void;
-}
-
 declare class AcpClient {
     private acpUrl;
     acpContractClient: AcpContractClient;
@@ -8427,13 +8440,20 @@ declare class AcpClient {
     constructor(options: IAcpClientOptions);
     private defaultOnEvaluate;
     init(): Promise<void>;
-    browseAgents(keyword: string, cluster?: string): Promise<{
+    browseAgents(keyword: string, cluster?: string, sort_by?: AcpAgentSort[], rerank?: boolean, top_k?: number): Promise<{
         id: number;
         name: string;
         description: string;
         offerings: AcpJobOffering[];
         twitterHandle: string;
         walletAddress: `0x${string}`;
+        metrics: {
+            successfulJobCount: number;
+            successRate: number;
+            uniqueBuyerCount: number;
+            minsFromLastOnline: number;
+            isOnline: boolean;
+        } | undefined;
     }[]>;
     initiateJob(providerAddress: Address$1, serviceRequirement: Object | string, amount: number, evaluatorAddress?: Address$1, expiredAt?: Date): Promise<number>;
     respondJob(jobId: number, memoId: number, accept: boolean, reason?: string): Promise<`0x${string}`>;
@@ -8447,4 +8467,4 @@ declare class AcpClient {
     getAgent(walletAddress: Address$1): Promise<AcpAgent | undefined>;
 }
 
-export { ACP_ABI, AcpContractClient, type AcpContractConfig, AcpJob, AcpJobPhases, AcpMemo, MemoType, baseSepoliaAcpConfig, AcpClient as default };
+export { ACP_ABI, AcpAgentSort, AcpContractClient, type AcpContractConfig, AcpJob, AcpJobPhases, AcpMemo, MemoType, baseSepoliaAcpConfig, AcpClient as default };

package/dist/index.d.ts

@@ -8347,29 +8347,6 @@ declare class AcpContractClient {
     setBudget(jobId: number, budget: bigint): Promise<`0x${string}`>;
 }
 
-type AcpAgent = {
-    id: number;
-    documentId: string;
-    name: string;
-    description: string;
-    walletAddress: Address$1;
-    isVirtualAgent: boolean;
-    profilePic: string;
-    category: string;
-    tokenAddress: string | null;
-    ownerAddress: string;
-    cluster: string | null;
-    twitterHandle: string;
-    offerings: {
-        name: string;
-        price: number;
-        requirementSchema?: Object;
-        deliverableSchema?: Object;
-    }[];
-    symbol: string | null;
-    virtualAgentId: string | null;
-};
-
 declare class AcpMemo {
     private acpClient;
     id: number;
@@ -8402,6 +8379,48 @@ declare class AcpJob {
     evaluate(accept: boolean, reason?: string): Promise<`0x${string}`>;
 }
 
+declare enum AcpAgentSort {
+    SUCCESSFUL_JOB_COUNT = "successfulJobCount",
+    SUCCESS_RATE = "successRate",
+    UNIQUE_BUYER_COUNT = "uniqueBuyerCount",
+    MINS_FROM_LAST_ONLINE = "minsFromLastOnlineTime",
+    IS_ONLINE = "isOnline"
+}
+interface IAcpClientOptions {
+    acpContractClient: AcpContractClient;
+    onNewTask?: (job: AcpJob) => void;
+    onEvaluate?: (job: AcpJob) => void;
+}
+type AcpAgent = {
+    id: number;
+    documentId: string;
+    name: string;
+    description: string;
+    walletAddress: Address$1;
+    isVirtualAgent: boolean;
+    profilePic: string;
+    category: string;
+    tokenAddress: string | null;
+    ownerAddress: string;
+    cluster: string | null;
+    twitterHandle: string;
+    offerings: {
+        name: string;
+        price: number;
+        requirementSchema?: Object;
+        deliverableSchema?: Object;
+    }[];
+    symbol: string | null;
+    virtualAgentId: string | null;
+    metrics?: {
+        successfulJobCount: number;
+        successRate: number;
+        uniqueBuyerCount: number;
+        minsFromLastOnline: number;
+        isOnline: boolean;
+    };
+};
+
 declare class AcpJobOffering {
     private readonly acpClient;
     providerAddress: Address$1;
@@ -8413,12 +8432,6 @@ declare class AcpJobOffering {
     initiateJob(serviceRequirement: Object | string, evaluatorAddress?: Address$1, expiredAt?: Date): Promise<number>;
 }
 
-interface IAcpClientOptions {
-    acpContractClient: AcpContractClient;
-    onNewTask?: (job: AcpJob) => void;
-    onEvaluate?: (job: AcpJob) => void;
-}
-
 declare class AcpClient {
     private acpUrl;
     acpContractClient: AcpContractClient;
@@ -8427,13 +8440,20 @@ declare class AcpClient {
     constructor(options: IAcpClientOptions);
     private defaultOnEvaluate;
     init(): Promise<void>;
-    browseAgents(keyword: string, cluster?: string): Promise<{
+    browseAgents(keyword: string, cluster?: string, sort_by?: AcpAgentSort[], rerank?: boolean, top_k?: number): Promise<{
         id: number;
         name: string;
         description: string;
         offerings: AcpJobOffering[];
         twitterHandle: string;
         walletAddress: `0x${string}`;
+        metrics: {
+            successfulJobCount: number;
+            successRate: number;
+            uniqueBuyerCount: number;
+            minsFromLastOnline: number;
+            isOnline: boolean;
+        } | undefined;
     }[]>;
     initiateJob(providerAddress: Address$1, serviceRequirement: Object | string, amount: number, evaluatorAddress?: Address$1, expiredAt?: Date): Promise<number>;
     respondJob(jobId: number, memoId: number, accept: boolean, reason?: string): Promise<`0x${string}`>;
@@ -8447,4 +8467,4 @@ declare class AcpClient {
     getAgent(walletAddress: Address$1): Promise<AcpAgent | undefined>;
 }
 
-export { ACP_ABI, AcpContractClient, type AcpContractConfig, AcpJob, AcpJobPhases, AcpMemo, MemoType, baseSepoliaAcpConfig, AcpClient as default };
+export { ACP_ABI, AcpAgentSort, AcpContractClient, type AcpContractConfig, AcpJob, AcpJobPhases, AcpMemo, MemoType, baseSepoliaAcpConfig, AcpClient as default };

package/dist/index.js

@@ -65,6 +65,7 @@ var __async = (__this, __arguments, generator) => {
 var index_exports = {};
 __export(index_exports, {
   ACP_ABI: () => acpAbi_default,
+  AcpAgentSort: () => AcpAgentSort,
   AcpContractClient: () => acpContractClient_default,
   AcpJob: () => acpJob_default,
   AcpJobPhases: () => AcpJobPhases,
@@ -1213,9 +1214,21 @@ var AcpClient = class {
       process.on("SIGTERM", cleanup);
     });
   }
-  browseAgents(keyword, cluster) {
+  browseAgents(keyword, cluster, sort_by, rerank = false, top_k = 5) {
     return __async(this, null, function* () {
-      let url = `${this.acpUrl}/api/agents?search=${keyword}&filters[walletAddress][$notIn]=${this.acpContractClient.walletAddress}`;
+      let url = `${this.acpUrl}/api/agents?search=${keyword}`;
+      if (sort_by && sort_by.length > 0) {
+        url += `&sort=${sort_by.map((s) => s).join(",")}`;
+      }
+      if (top_k) {
+        url += `&top_k=${top_k}`;
+      }
+      if (rerank) {
+        url += `&rerank=true`;
+      }
+      if (this.acpContractClient.walletAddress) {
+        url += `&filters[walletAddress][$notIn]=${this.acpContractClient.walletAddress}`;
+      }
       if (cluster) {
         url += `&filters[cluster]=${cluster}`;
       }
@@ -1236,7 +1249,8 @@ var AcpClient = class {
             );
           }),
           twitterHandle: agent.twitterHandle,
-          walletAddress: agent.walletAddress
+          walletAddress: agent.walletAddress,
+          metrics: agent.metrics
         };
       });
     });
@@ -1498,6 +1512,16 @@ var AcpClient = class {
 };
 var acpClient_default = AcpClient;
 
+// src/interfaces.ts
+var AcpAgentSort = /* @__PURE__ */ ((AcpAgentSort2) => {
+  AcpAgentSort2["SUCCESSFUL_JOB_COUNT"] = "successfulJobCount";
+  AcpAgentSort2["SUCCESS_RATE"] = "successRate";
+  AcpAgentSort2["UNIQUE_BUYER_COUNT"] = "uniqueBuyerCount";
+  AcpAgentSort2["MINS_FROM_LAST_ONLINE"] = "minsFromLastOnlineTime";
+  AcpAgentSort2["IS_ONLINE"] = "isOnline";
+  return AcpAgentSort2;
+})(AcpAgentSort || {});
+
 // src/configs.ts
 var import_infra2 = require("@account-kit/infra");
 var baseSepoliaAcpConfig = {
@@ -1513,6 +1537,7 @@ var index_default = acpClient_default;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACP_ABI,
+  AcpAgentSort,
   AcpContractClient,
   AcpJob,
   AcpJobPhases,

package/dist/index.mjs

@@ -1175,9 +1175,21 @@ var AcpClient = class {
       process.on("SIGTERM", cleanup);
     });
   }
-  browseAgents(keyword, cluster) {
+  browseAgents(keyword, cluster, sort_by, rerank = false, top_k = 5) {
     return __async(this, null, function* () {
-      let url = `${this.acpUrl}/api/agents?search=${keyword}&filters[walletAddress][$notIn]=${this.acpContractClient.walletAddress}`;
+      let url = `${this.acpUrl}/api/agents?search=${keyword}`;
+      if (sort_by && sort_by.length > 0) {
+        url += `&sort=${sort_by.map((s) => s).join(",")}`;
+      }
+      if (top_k) {
+        url += `&top_k=${top_k}`;
+      }
+      if (rerank) {
+        url += `&rerank=true`;
+      }
+      if (this.acpContractClient.walletAddress) {
+        url += `&filters[walletAddress][$notIn]=${this.acpContractClient.walletAddress}`;
+      }
       if (cluster) {
         url += `&filters[cluster]=${cluster}`;
       }
@@ -1198,7 +1210,8 @@ var AcpClient = class {
             );
           }),
           twitterHandle: agent.twitterHandle,
-          walletAddress: agent.walletAddress
+          walletAddress: agent.walletAddress,
+          metrics: agent.metrics
         };
       });
     });
@@ -1460,6 +1473,16 @@ var AcpClient = class {
 };
 var acpClient_default = AcpClient;
 
+// src/interfaces.ts
+var AcpAgentSort = /* @__PURE__ */ ((AcpAgentSort2) => {
+  AcpAgentSort2["SUCCESSFUL_JOB_COUNT"] = "successfulJobCount";
+  AcpAgentSort2["SUCCESS_RATE"] = "successRate";
+  AcpAgentSort2["UNIQUE_BUYER_COUNT"] = "uniqueBuyerCount";
+  AcpAgentSort2["MINS_FROM_LAST_ONLINE"] = "minsFromLastOnlineTime";
+  AcpAgentSort2["IS_ONLINE"] = "isOnline";
+  return AcpAgentSort2;
+})(AcpAgentSort || {});
+
 // src/configs.ts
 import { baseSepolia, base } from "@account-kit/infra";
 var baseSepoliaAcpConfig = {
@@ -1474,6 +1497,7 @@ var baseSepoliaAcpConfig = {
 var index_default = acpClient_default;
 export {
   acpAbi_default as ACP_ABI,
+  AcpAgentSort,
   acpContractClient_default as AcpContractClient,
   acpJob_default as AcpJob,
   AcpJobPhases,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@virtuals-protocol/acp-node",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.4",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",