@teneo-protocol/sdk 1.0.0 → 2.0.0

package/examples/usage/03-pick-agent.ts

@@ -0,0 +1,201 @@
+/**
+ * Example 3: Pick and Communicate with Specific Agent
+ *
+ * This example demonstrates:
+ * - Finding a specific agent by ID or name
+ * - Sending a direct command to an agent (bypassing coordinator)
+ * - Waiting for and receiving agent responses
+ * - Handling response formats (raw, humanized, both)
+ *
+ * Run: npx tsx examples/usage/03-pick-agent.ts [agent-name-or-id]
+ * Example: npx tsx examples/usage/03-pick-agent.ts "X Platform Agent"
+ */
+
+import "dotenv/config";
+import { TeneoSDK, SDKConfigBuilder, FormattedResponse } from "../../dist/index.js";
+
+// Load configuration from environment
+const WS_URL =
+  process.env.WS_URL || "wss://your-teneo-server.com/ws";
+const PRIVATE_KEY = process.env.PRIVATE_KEY || "";
+const DEFAULT_ROOM = process.env.DEFAULT_ROOM || "general";
+
+async function main() {
+  console.log("🚀 Example 3: Pick and Communicate with Specific Agent\n");
+
+  if (!PRIVATE_KEY) {
+    console.error("❌ ERROR: PRIVATE_KEY environment variable is required\n");
+    process.exit(1);
+  }
+
+  // Get agent name/ID from command line or use default
+  const targetAgentName = process.argv[2];
+
+  // Build SDK with response format set to 'both' to see raw and humanized
+  const config = new SDKConfigBuilder()
+    .withWebSocketUrl(WS_URL)
+    .withAuthentication(PRIVATE_KEY)
+    // .withAutoJoinRooms([DEFAULT_ROOM])
+    .withResponseFormat({ format: "both", includeMetadata: true })
+    .withLogging("info")
+    .build();
+
+  const sdk = new TeneoSDK(config);
+
+  // Listen for agent responses
+  sdk.on("agent:response", (response) => {
+    console.log("📨 Agent response event received:");
+    console.log(`   Agent: ${response.agentName || response.agentId}`);
+    console.log(`   Task ID: ${response.taskId}`);
+    console.log(`   Success: ${response.success}`);
+  });
+
+  try {
+    // Connect
+    console.log("🔌 Connecting to Teneo network...");
+    await sdk.connect();
+    console.log("✅ Connected!\n");
+
+    // Wait for agents to load
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    // Step 1: List available agents
+    console.log("⚙️  Step 1: Getting available agents...");
+    const agents = sdk.getAgents();
+    console.log(`✅ Found ${agents.length} agents\n`);
+
+    if (agents.length === 0) {
+      console.log("❌ No agents available");
+      return;
+    }
+
+    // Display available agents
+    console.log("📋 Available Agents:");
+    agents.forEach((agent, index) => {
+      console.log(`   ${index + 1}. ${agent.name || "Unnamed"} (${agent.id})`);
+      console.log(`      Status: ${agent.status}`);
+      if (agent.description) {
+        console.log(`      ${agent.description}`);
+      }
+    });
+    console.log("");
+
+    // Step 2: Pick an agent
+    console.log("⚙️  Step 2: Selecting agent...");
+    let selectedAgent;
+
+    if (targetAgentName) {
+      // Find by name or ID from command line
+      console.log(`   Searching for: "${targetAgentName}"`);
+      selectedAgent = agents.find(
+        (a) =>
+          a.name?.toLowerCase().includes(targetAgentName.toLowerCase()) ||
+          a.id.toLowerCase() === targetAgentName.toLowerCase()
+      );
+
+      if (!selectedAgent) {
+        console.log(`❌ Agent "${targetAgentName}" not found`);
+        console.log("   Available agents listed above");
+        return;
+      }
+    } else {
+      // Pick first online agent
+      selectedAgent =
+        agents.find((a) => a.status === "online" && a.id !== "solidity-agent-v3") || agents[0];
+      console.log("   No agent specified, selecting first online agent");
+    }
+
+    console.log(`✅ Selected: ${selectedAgent.name || selectedAgent.id}`);
+    console.log(`   ID: ${selectedAgent.id}`);
+    console.log(`   Status: ${selectedAgent.status}`);
+    console.log("");
+
+    // Step 3: Send a direct command to the agent
+    console.log("⚙️  Step 3: Sending command to agent...");
+
+    // Construct a simple command based on agent type
+    let command;
+    if (
+      selectedAgent.name?.toLowerCase().includes("x platform") ||
+      selectedAgent.name?.toLowerCase().includes("twitter")
+    ) {
+      command = "timeline @elonmusk 3";
+      console.log(`   Command: ${command}`);
+      console.log("   (Getting Twitter timeline for @elonmusk)");
+    } else if (selectedAgent.commands && selectedAgent.commands.length > 0) {
+      // Use first available command
+      const firstCmd = selectedAgent.commands[0];
+      command = `${firstCmd.trigger} ${firstCmd.argument || "test"}`;
+      console.log(`   Command: ${command}`);
+      console.log(`   (Using agent's first command: ${firstCmd.description})`);
+    } else {
+      command = "hello";
+      console.log(`   Command: ${command}`);
+      console.log("   (Sending simple greeting)");
+    }
+
+    console.log("   Waiting for response (timeout: 30s)...");
+    console.log("");
+
+    const startTime = Date.now();
+
+    // Send direct command and wait for response
+    const response = await sdk.sendDirectCommand(
+      {
+        agent: selectedAgent.id,
+        command: command,
+        room: DEFAULT_ROOM
+      },
+      true
+    ); // waitForResponse = true
+
+    if (!response) {
+      console.log("❌ No response received");
+      return;
+    }
+
+    const duration = Date.now() - startTime;
+
+    // Step 4: Display the response
+    console.log("✅ Response received!\n");
+    console.log("📊 Response Details:");
+    console.log("=".repeat(80));
+
+    if (response.humanized) {
+      console.log("\n📝 Humanized Response:");
+      console.log(response.humanized);
+    }
+
+    if (response.raw) {
+      console.log("\n📄 Raw Response:");
+      console.log(JSON.stringify(response.raw, null, 2));
+    }
+
+    if (response.metadata) {
+      console.log("\n📋 Metadata:");
+      console.log(`   Task ID: ${response.metadata.taskId}`);
+      console.log(`   Agent ID: ${response.metadata.agentId}`);
+      console.log(`   Agent Name: ${response.metadata.agentName}`);
+      console.log(`   Timestamp: ${response.metadata.timestamp}`);
+      console.log(`   Duration: ${duration}ms`);
+    }
+
+    console.log("\n" + "=".repeat(80));
+  } catch (error) {
+    console.error("\n❌ Error:", error);
+    if (error instanceof Error) {
+      console.error("   Message:", error.message);
+      if ("code" in error) {
+        console.error("   Code:", (error as any).code);
+      }
+    }
+    process.exit(1);
+  } finally {
+    sdk.disconnect();
+    sdk.destroy();
+    console.log("\n✅ Disconnected");
+    console.log("🎉 Example completed!");
+  }
+}
+
+main().catch(console.error);

package/examples/usage/04-find-by-capability.ts

@@ -0,0 +1,237 @@
+/**
+ * Example 4: Find Agents by Capability
+ *
+ * This example demonstrates:
+ * - PERF-3: O(1) indexed agent lookups by capability
+ * - Finding agents by specific capabilities
+ * - Finding agents by status (online/offline)
+ * - Finding agents by name (token-based search)
+ * - Performance comparison of different search methods
+ *
+ * Run: npx tsx examples/usage/04-find-by-capability.ts
+ */
+
+import "dotenv/config";
+import { TeneoSDK, SDKConfigBuilder } from "../../dist/index.js";
+
+// Load configuration from environment
+const WS_URL =
+  process.env.WS_URL || "wss://your-teneo-server.com/ws";
+const PRIVATE_KEY = process.env.PRIVATE_KEY || "";
+const DEFAULT_ROOM = process.env.DEFAULT_ROOM || "general";
+
+async function main() {
+  console.log("🚀 Example 4: Find Agents by Capability\n");
+
+  if (!PRIVATE_KEY) {
+    console.error("❌ ERROR: PRIVATE_KEY environment variable is required\n");
+    process.exit(1);
+  }
+
+  // Build SDK
+  const config = new SDKConfigBuilder()
+    .withWebSocketUrl(WS_URL)
+    .withAuthentication(PRIVATE_KEY)
+    // .withAutoJoinRooms([DEFAULT_ROOM])
+    .withLogging("info")
+    .build();
+
+  const sdk = new TeneoSDK(config);
+
+  try {
+    // Connect
+    console.log("🔌 Connecting to Teneo network...");
+    await sdk.connect();
+    console.log("✅ Connected!\n");
+
+    // Wait for agents
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    // Get all agents
+    const allAgents = sdk.getAgents();
+    console.log(`📊 Total agents in network: ${allAgents.length}\n`);
+
+    if (allAgents.length === 0) {
+      console.log("❌ No agents available");
+      return;
+    }
+
+    // Step 1: Display all available capabilities
+    console.log("⚙️  Step 1: Discovering available capabilities...");
+    const capabilitiesSet = new Set<string>();
+
+    allAgents.forEach((agent) => {
+      if (agent.capabilities) {
+        agent.capabilities.forEach((cap) => {
+          capabilitiesSet.add(cap.name);
+        });
+      }
+    });
+
+    const capabilities = Array.from(capabilitiesSet).sort();
+    console.log(`✅ Found ${capabilities.length} unique capabilities:\n`);
+
+    if (capabilities.length > 0) {
+      console.log("📋 Available Capabilities:");
+      capabilities.forEach((cap, index) => {
+        const agentsWithCap = allAgents.filter((a) => a.capabilities?.some((c) => c.name === cap));
+        console.log(`   ${index + 1}. ${cap} (${agentsWithCap.length} agents)`);
+      });
+      console.log("");
+    } else {
+      console.log("⚠️  No capabilities defined for any agents\n");
+    }
+
+    // Step 2: Find agents by capability (O(1) lookup)
+    if (capabilities.length > 0) {
+      console.log("⚙️  Step 2: Finding agents by capability (O(1) indexed lookup)...");
+
+      // Try to find agents with specific capabilities
+      const testCapabilities = [
+        capabilities[0], // First capability
+        "weather-forecast",
+        "social-media",
+        "data-analysis"
+      ];
+
+      for (const capability of testCapabilities) {
+        console.log(`\n🔍 Searching for capability: "${capability}"`);
+        const startTime = performance.now();
+        const agentsWithCap = sdk.findAgentsByCapability(capability);
+        const duration = performance.now() - startTime;
+
+        if (agentsWithCap.length > 0) {
+          console.log(`✅ Found ${agentsWithCap.length} agent(s) (${duration.toFixed(3)}ms):`);
+          agentsWithCap.forEach((agent) => {
+            console.log(`   • ${agent.name || agent.id}`);
+            const cap = agent.capabilities?.find((c) => c.name === capability);
+            if (cap) {
+              console.log(`     ${cap.description}`);
+            }
+          });
+        } else {
+          console.log(
+            `❌ No agents found with capability "${capability}" (${duration.toFixed(3)}ms)`
+          );
+        }
+      }
+    }
+
+    // Step 3: Find agents by status (O(1) lookup)
+    console.log("\n⚙️  Step 3: Finding agents by status (O(1) indexed lookup)...");
+
+    console.log("\n🔍 Online agents:");
+    const startTimeOnline = performance.now();
+    const onlineAgents = sdk.findAgentsByStatus("online");
+    const durationOnline = performance.now() - startTimeOnline;
+    console.log(`✅ Found ${onlineAgents.length} online agents (${durationOnline.toFixed(3)}ms):`);
+    onlineAgents.forEach((agent) => {
+      console.log(`   • ${agent.name || agent.id} (${agent.status})`);
+    });
+
+    console.log("\n🔍 Offline agents:");
+    const startTimeOffline = performance.now();
+    const offlineAgents = sdk.findAgentsByStatus("offline");
+    const durationOffline = performance.now() - startTimeOffline;
+    console.log(
+      `✅ Found ${offlineAgents.length} offline agents (${durationOffline.toFixed(3)}ms):`
+    );
+    offlineAgents.forEach((agent) => {
+      console.log(`   • ${agent.name || agent.id} (${agent.status})`);
+    });
+
+    // Step 4: Find agents by name (O(k) token-based search)
+    console.log("\n⚙️  Step 4: Finding agents by name (token-based search)...");
+
+    const searchTerms = ["agent", "bot", "platform", "weather"];
+
+    for (const term of searchTerms) {
+      console.log(`\n🔍 Searching for name containing: "${term}"`);
+      const startTime = performance.now();
+      const foundAgents = sdk.findAgentsByName(term);
+      const duration = performance.now() - startTime;
+
+      if (foundAgents.length > 0) {
+        console.log(`✅ Found ${foundAgents.length} agent(s) (${duration.toFixed(3)}ms):`);
+        foundAgents.forEach((agent) => {
+          console.log(`   • ${agent.name || agent.id}`);
+        });
+      } else {
+        console.log(`❌ No agents found with "${term}" in name (${duration.toFixed(3)}ms)`);
+      }
+    }
+
+    // Step 5: Performance summary
+    console.log("\n📊 Performance Summary:");
+    console.log("=".repeat(80));
+    console.log("\nThe SDK uses indexed lookups for optimal performance:");
+    console.log("   • Capability search: O(1) - constant time");
+    console.log("   • Status search: O(1) - constant time");
+    console.log("   • Name search: O(k) - where k is the number of tokens");
+    console.log("\nAll searches complete in < 1ms even with many agents!");
+    console.log("=".repeat(80));
+
+    // Step 6: Practical example - find best agent for a task
+    console.log("\n⚙️  Step 6: Practical example - finding best agent for a task...");
+    console.log('\nTask: "Get Twitter timeline for a user"');
+    console.log("Strategy: Find online agents with social-media or twitter capabilities\n");
+
+    // First, try to find by specific capabilities
+    let candidates = sdk.findAgentsByCapability("social-media");
+    if (candidates.length === 0) {
+      candidates = sdk.findAgentsByCapability("twitter");
+    }
+    if (candidates.length === 0) {
+      candidates = sdk.findAgentsByCapability("x-platform");
+    }
+
+    // Filter to only online agents
+    candidates = candidates.filter((a) => a.status === "online");
+
+    // If no capability match, try name search
+    if (candidates.length === 0) {
+      console.log("⚠️  No capability match, trying name search...");
+      const nameResults = sdk
+        .findAgentsByName("twitter")
+        .concat(sdk.findAgentsByName("x platform"))
+        .concat(sdk.findAgentsByName("social"));
+
+      // Remove duplicates and filter online
+      const uniqueIds = new Set<string>();
+      candidates = nameResults.filter((a) => {
+        if (uniqueIds.has(a.id) || a.status !== "online") {
+          return false;
+        }
+        uniqueIds.add(a.id);
+        return true;
+      });
+    }
+
+    if (candidates.length > 0) {
+      console.log(`✅ Found ${candidates.length} suitable agent(s):`);
+      candidates.forEach((agent, index) => {
+        console.log(`\n   ${index + 1}. ${agent.name || agent.id}`);
+        console.log(`      Status: ${agent.status}`);
+        if (agent.description) {
+          console.log(`      Description: ${agent.description}`);
+        }
+        if (agent.capabilities && agent.capabilities.length > 0) {
+          console.log(`      Capabilities: ${agent.capabilities.map((c) => c.name).join(", ")}`);
+        }
+      });
+      console.log(`\n💡 Recommendation: Use "${candidates[0].name || candidates[0].id}"`);
+    } else {
+      console.log("❌ No suitable agents found for this task");
+    }
+  } catch (error) {
+    console.error("\n❌ Error:", error);
+    process.exit(1);
+  } finally {
+    sdk.disconnect();
+    sdk.destroy();
+    console.log("\n✅ Disconnected");
+    console.log("🎉 Example completed!");
+  }
+}
+
+main().catch(console.error);