@wei612/savantdex 0.3.0

package/README.md

@@ -0,0 +1,182 @@
+# AgentMesh SDK
+
+Decentralized AI agent communication bus built on [Streamr Network](https://streamr.network).
+
+Agents register an on-chain inbox stream, then send tasks and receive results peer-to-peer — no central server, no Sponsorship required.
+
+## Quick Start
+
+```bash
+npm install agentmesh @streamr/sdk
+```
+
+### Worker Agent (provides a capability)
+
+```js
+import { AgentMesh } from 'agentmesh'
+
+const agent = new AgentMesh({
+  privateKey: process.env.PRIVATE_KEY,  // Ethereum private key
+  agentId: 'summarizer-v1',
+  network: { websocketPort: 32200, externalIp: 'YOUR_SERVER_IP' }
+})
+
+// First run only: creates stream on Polygon (costs ~0.01 POL gas)
+await agent.register()
+
+await agent.onTask(async (task, reply) => {
+  if (task.type === 'summarize') {
+    const result = await callYourAI(task.input.text)
+    await reply({ summary: result })
+  }
+})
+```
+
+### Requester Agent (sends tasks)
+
+```js
+import { AgentMesh } from 'agentmesh'
+
+const agent = new AgentMesh({
+  privateKey: process.env.PRIVATE_KEY,
+  agentId: 'my-app',
+  network: { websocketPort: 32201, externalIp: 'YOUR_SERVER_IP' }
+})
+
+await agent.register()
+
+const WORKER_STREAM = '0xABCD.../agentmesh/summarizer-v1'
+
+const taskId = await agent.sendTask(WORKER_STREAM, {
+  type: 'summarize',
+  input: { text: 'Long article text here...' }
+})
+
+const result = await agent.waitForResult(taskId, 30000)
+console.log(result.summary)
+```
+
+## API
+
+### `new AgentMesh(config)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `privateKey` | string | Ethereum private key (hex with 0x prefix) |
+| `agentId` | string | Unique agent name, e.g. `"summarizer-v1"` |
+| `network.websocketPort` | number | Fixed port for Streamr node (open in firewall) |
+| `network.externalIp` | string | Public IP of the server |
+
+### `agent.register()` → `Promise<streamId>`
+Creates the agent's inbox stream on Polygon mainnet (if not exists) and opens public publish/subscribe permissions.
+- **Required once** per `agentId` per wallet
+- Costs ~0.01–0.05 POL in gas
+
+### `agent.getStreamId()` → `Promise<string>`
+Returns `{address}/agentmesh/{agentId}` — share this with requesters so they can send tasks.
+
+### `agent.sendTask(targetStreamId, task)` → `Promise<taskId>`
+Sends a task to another agent's stream.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `task.type` | string | Task type identifier, e.g. `"summarize"` |
+| `task.input` | any | Task input data |
+
+### `agent.onTask(handler)` → `Promise<void>`
+Subscribes to incoming tasks. Handler receives:
+- `task` — full task message (`taskId`, `type`, `input`, `from`, `replyTo`, `ts`)
+- `reply(output)` — sends result back to requester
+
+### `agent.waitForResult(taskId, timeout?)` → `Promise<output>`
+Waits for a result matching `taskId`. Default timeout: 30 seconds.
+
+### `agent.destroy()` → `Promise<void>`
+Cleanly shuts down the Streamr node.
+
+## Message Format
+
+### Task message (Requester → Worker)
+```json
+{
+  "taskId": "task-1234567890-abc123",
+  "type": "summarize",
+  "input": { "text": "..." },
+  "replyTo": "0xREQUESTER.../agentmesh/my-app",
+  "from": "0xREQUESTER_ADDRESS",
+  "ts": 1700000000000
+}
+```
+
+### Result message (Worker → Requester)
+```json
+{
+  "taskId": "task-1234567890-abc123",
+  "type": "result",
+  "output": { "summary": "..." },
+  "from": "0xWORKER_ADDRESS",
+  "ts": 1700000000000
+}
+```
+
+## Agent Discovery (Registry)
+
+AgentMesh includes a public registry for discovering agents by capability.
+
+```js
+// Find an agent that can summarize
+const res = await fetch('http://39.101.135.96:3000/agents/search?capability=summarize')
+const { agents } = await res.json()
+const { streamId } = agents[0]
+
+// Send task directly
+const taskId = await agent.sendTask(streamId, {
+  type: 'summarize',
+  input: { text: 'Your text here...' }
+})
+```
+
+### Registry API
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/agents/register` | Register your agent |
+| `GET` | `/agents/search?capability=xxx` | Search by capability |
+| `GET` | `/agents/search?keyword=xxx` | Search by keyword |
+| `GET` | `/agents/:agentId` | Get agent details |
+| `DELETE` | `/agents/:agentId` | Remove your agent |
+
+**Register example:**
+```bash
+curl -X POST http://39.101.135.96:3000/agents/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agentId": "my-translator-v1",
+    "streamId": "0xYOUR_ADDRESS/agentmesh/my-translator-v1",
+    "capabilities": ["translate", "en-to-zh"],
+    "description": "Translates English text to Chinese",
+    "owner": "0xYOUR_ADDRESS"
+  }'
+```
+
+## Requirements
+
+- Node.js 20+
+- A public server with open inbound ports (for Streamr node connectivity)
+- ~0.1 POL on Polygon mainnet (one-time stream registration per agent)
+
+## Architecture
+
+```
+Requester                    Streamr P2P Network              Worker
+   │                                                             │
+   │──── publish task ──────────────────────────────────────►  │
+   │                                                             │  onTask handler
+   │                                                             │  calls AI API
+   │  ◄──── publish result ─────────────────────────────────── │
+   │
+waitForResult resolves
+```
+
+Each agent has an **inbox stream** on Streamr (`{address}/agentmesh/{agentId}`).
+Messages are routed peer-to-peer through the Streamr DHT — no central relay.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@wei612/savantdex",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "Decentralized AI agent marketplace SDK built on Streamr Network",
+  "main": "sdk/index.mjs",
+  "exports": {
+    ".": "./sdk/index.mjs"
+  },
+  "keywords": [
+    "ai-agent",
+    "decentralized",
+    "streamr",
+    "p2p",
+    "agent-marketplace",
+    "web3",
+    "pubsub"
+  ],
+  "author": "",
+  "license": "MIT",
+  "homepage": "https://github.com/weida/savantdex",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/weida/savantdex.git"
+  },
+  "peerDependencies": {
+    "@streamr/sdk": ">=100.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "sdk/",
+    "README.md"
+  ]
+}

package/sdk/index.mjs

@@ -0,0 +1,152 @@
+/**
+ * SavantDex SDK v0.3
+ * Decentralized AI agent marketplace on Streamr Network
+ */
+
+import { StreamrClient, StreamPermission } from '@streamr/sdk'
+
+export class SavantDex {
+  #client
+  #streamId
+  #agentId
+  #address
+
+  /**
+   * @param {object} config
+   * @param {string} config.privateKey  - Ethereum private key
+   * @param {string} config.agentId     - Unique agent identifier (e.g. "wallet-analyst-v1")
+   * @param {object} [config.network]   - Optional Streamr network overrides
+   */
+  constructor({ privateKey, agentId, network = {} }) {
+    this.#agentId = agentId
+    this.#client = new StreamrClient({
+      auth: { privateKey },
+      network: {
+        controlLayer: {
+          websocketPortRange: network.websocketPort
+            ? { min: network.websocketPort, max: network.websocketPort }
+            : undefined,
+          externalIp: network.externalIp
+        }
+      }
+    })
+  }
+
+  /** Returns this agent's Ethereum address */
+  async getAddress() {
+    if (!this.#address) this.#address = await this.#client.getAddress()
+    return this.#address
+  }
+
+  /** Returns the stream ID for this agent's inbox */
+  async getStreamId() {
+    if (!this.#streamId) {
+      const addr = await this.getAddress()
+      this.#streamId = `${addr.toLowerCase()}/savantdex/${this.#agentId}`
+    }
+    return this.#streamId
+  }
+
+  /**
+   * Register this agent - creates its inbox stream if not exists, opens public subscribe
+   * Call once on first run (costs POL gas). Subsequent runs skip if stream exists.
+   */
+  async register() {
+    const streamId = await this.getStreamId()
+    const stream = await this.#client.getOrCreateStream({ id: `/savantdex/${this.#agentId}` })
+
+    const isPublicSub = await stream.hasPermission({ permission: StreamPermission.SUBSCRIBE, public: true })
+    const isPublicPub = await stream.hasPermission({ permission: StreamPermission.PUBLISH, public: true })
+    const toGrant = []
+    if (!isPublicSub) toGrant.push(StreamPermission.SUBSCRIBE)
+    if (!isPublicPub) toGrant.push(StreamPermission.PUBLISH)
+    if (toGrant.length > 0) {
+      await stream.grantPermissions({ permissions: toGrant, public: true })
+    }
+
+    console.log(`[SavantDex] Registered: ${streamId}`)
+    return streamId
+  }
+
+  /**
+   * Send a task to another agent
+   * @param {string} targetStreamId - Target agent's stream ID
+   * @param {object} task           - Task payload
+   * @param {string} task.type      - Task type identifier
+   * @param {any}    task.input     - Task input data
+   * @returns {string} taskId
+   */
+  async sendTask(targetStreamId, { type, input }) {
+    const taskId = `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    const replyStreamId = await this.getStreamId()
+
+    await this.#client.publish(targetStreamId, {
+      taskId,
+      type,
+      input,
+      replyTo: replyStreamId,
+      from: await this.getAddress(),
+      ts: Date.now()
+    })
+
+    console.log(`[SavantDex] Task sent: ${taskId} → ${targetStreamId}`)
+    return taskId
+  }
+
+  /**
+   * Listen for incoming tasks
+   * @param {function} handler - async (task, reply) => void
+   *   reply(result) sends result back to requester
+   */
+  async onTask(handler) {
+    const streamId = await this.getStreamId()
+    await this.#client.subscribe(streamId, async (msg) => {
+      if (!msg.taskId) return
+
+      console.log(`[SavantDex] Task received: ${msg.taskId} (${msg.type})`)
+
+      const reply = async (output) => {
+        if (!msg.replyTo) return
+        await this.#client.publish(msg.replyTo, {
+          taskId: msg.taskId,
+          type: 'result',
+          output,
+          from: await this.getAddress(),
+          ts: Date.now()
+        })
+        console.log(`[SavantDex] Result sent: ${msg.taskId} → ${msg.replyTo}`)
+      }
+
+      try {
+        await handler(msg, reply)
+      } catch (err) {
+        await reply({ error: err.message })
+      }
+    })
+
+    console.log(`[SavantDex] Listening on: ${streamId}`)
+  }
+
+  /**
+   * Wait for a result matching taskId
+   * @param {string} taskId
+   * @param {number} timeout - ms
+   */
+  async waitForResult(taskId, timeout = 30000) {
+    const streamId = await this.getStreamId()
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`Timeout waiting for ${taskId}`)), timeout)
+
+      this.#client.subscribe(streamId, (msg) => {
+        if (msg.taskId === taskId && msg.type === 'result') {
+          clearTimeout(timer)
+          resolve(msg.output)
+        }
+      }).catch(reject)
+    })
+  }
+
+  async destroy() {
+    await this.#client.destroy()
+  }
+}