@hashgraphonline/conversational-agent 0.2.215 → 0.2.217

package/src/plugins/community/swarm/README.md

@@ -0,0 +1,279 @@
+# Swarm Plugin
+
+The Swarm Plugin provides tools for interacting with the Swarm decentralized storage.
+
+To upload data to Swarm, you must first purchase storage capcity in the form of postage stamps. These stamps represent the right to store a certain amount of data for a specific duration. Swarm Gateways will use their underlying postage stamp batches for uploads.
+
+## Features
+
+- Upload text data to Swarm.
+- Download text data from Swarm.
+- Upload files and folders to Swarm.
+- Download files and folders from Swarm.
+- Update data on a Swarm feed.
+- Read latest data from a Swarm feed.
+- Create postage stamp batches for storage.
+- Get a postage stamp batch.
+- List postage stamp batches.
+- Extend storage and duration of a postage stamp batch.
+
+
+## Configuration Options
+
+| Option                             | Type          | Default       | Description                                                                                                                                                |
+| -----------------------------------| --------------| --------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------  |
+| `beeApiUrl`                        | string        | **required**  | The URL of the Bee node or of the Swarm Gateway. When using a gateway, its postage stamp will be used for uploads and postage stamp tools won't function.  |
+| `beeFeedPK`                        | string        | **required**  | The signer's private key used for updating the feed.                                                                                                       |
+| `autoAssignStamp`                  | boolean       | undefined     | If true, the batch with highest capacity is used for uploads.                                                                                              |
+| `deferredUploadSizeThresholdMB`    | number        | undefined     | The threshold above which file upload is deferred. Default is 5 MB.                                                                                        |
+
+
+## Quick Start
+
+```typescript
+import { ConversationalAgent, SwarmPlugin, SwarmConfig } from "@hashgraphonline/conversational-agent";
+
+const swarmConfig: SwarmConfig = {
+  beeApiUrl: process.env.SWARM_BEE_API_URL || "https://api.gateway.ethswarm.org",
+  beeFeedPK: process.env.SWARM_BEE_FEED_PK!,
+  autoAssignStamp: true,
+  deferredUploadSizeThresholdMB: Number(process.env.DEFERRED_UPLOAD_SIZE_THRESHOLD_MB!),
+};
+
+// Initialize the agent
+const agent = new ConversationalAgent({
+  accountId: process.env.HEDERA_ACCOUNT_ID!,
+  privateKey: process.env.HEDERA_PRIVATE_KEY!,
+  network: 'testnet',
+  openAIApiKey: process.env.OPENAI_API_KEY!,
+  openAIModelName: 'gpt-4o',
+  verbose: true,
+  additionalPlugins: [new SwarmPlugin(swarmConfig)],
+});
+
+// Initialize (automatically detects key type)
+await agent.initialize();
+
+// Process a message
+const response = await agent.processMessage(
+  "List my stamps."
+);
+
+```
+
+
+## Plugin Tools
+
+The plugin provides the following tools:
+
+
+### `swarm-create-postage-stamp`
+
+Buy postage stamp batch based on size in megabytes and duration.
+
+**Parameters:**
+
+- `size`: The storage size in MB (Megabytes). These other size units convert like this to MB: 1 byte = 0.000001 MB, 1  KB = 0.001 MB, 1GB= 1000MB.
+- `duration`: Duration for which the data should be stored. Time to live of the postage stamp batch, e.g. 1d - 1 day, 1w - 1 week, 1month - 1 month.
+- `label`: (Optional) Sets label for the postage stamp batch.
+
+**Sample prompt:**
+
+```bash
+Create new stamp with 4 days, 10 megabytes.
+```
+
+### `swarm-get-postage-stamp`
+
+Get a specific postage stamp batch based on batch id.
+
+**Parameters:**
+
+- `postageBatchId`: The id of the postage stamp batch which is requested.
+
+**Sample prompt:**
+
+```bash
+Give me the details for batch 3b3881ac37f936a4023a4562c69f1f138df8c1c24994f7b047514fbcbe9388fa.
+```
+
+
+### `swarm-list-postage-stamps`
+
+List the available postage stamp batches.
+
+**Parameters:**
+
+- `leastUsed`: (Optional) A boolean value that tells if postage stamp batches are sorted so least used comes first.
+- `limit`: (Optional) Limit is the maximum number of returned postage stamp batches.
+- `minUsage`: (Optional) Only list postage stamp batches with at least this usage percentage.
+- `maxUsage`: (Optional) Only list postage stamp batches with at most this usage percentage.
+
+**Sample prompt:**
+
+```bash
+List my stamps.
+```
+
+
+### `swarm-extend-postage-stamp`
+
+Increase the duration (relative to current duration) or size (in megabytes) of a postage stamp batch.
+
+**Parameters:**
+
+- `postageBatchId`: The id of the postage stamp batch for which extend is performed.
+- `size`: (Optional) The storage size in MB (Megabytes). These other size units convert like this to MB: 1 byte = 0.000001 MB, 1  KB = 0.001 MB, 1GB= 1000MB.
+- `duration`: (Optional) Duration for which the data should be stored. Time to live of the postage stamp batch, e.g. 1d - 1 day, 1w - 1 week, 1month - 1 month.
+
+**Sample prompt:**
+
+```bash
+Extend 3b3881ac37f936a4023a4562c69f1f138df8c1c24994f7b047514fbcbe9388fa to 5 days.
+```
+
+
+### `swarm-upload-data`
+
+Upload text data to Swarm.
+
+**Parameters:**
+
+- `data`: Arbitrary string to upload.
+- `redundancyLevel`: (Optional) Redundancy level for fault tolerance: 0 - none, 1 - medium, 2 - strong, 3 - insane, 4 - paranoid (higher values provide better fault tolerance but increase storage overhead). Optional, value is 0 if not requested.
+- `postageBatchId`: (Optional) The postage stamp batch ID which will be used to perform the upload, if it is provided.
+
+**Sample prompt:**
+
+```bash
+Upload data to Swarm: Hello World!.
+```
+
+
+### `swarm-download-data`
+
+Downloads immutable data from a Swarm content address hash.
+
+**Parameters:**
+
+- `reference`: Swarm reference hash.
+
+**Sample prompt:**
+
+```bash
+Download data from Swarm: 76d133e2798d2b15db55b6c3de01303acd86e43998eab372e25c5a2115bf3f0b.
+```
+
+
+### `swarm-update-feed`
+
+Update the feed of a given topic with new data.
+
+**Parameters:**
+
+- `data`: Arbitrary string to upload.
+- `memoryTopic`: If provided, uploads the lastes data to a feed with this topic. It is the label of the memory that can be used later to retrieve the data instead of its content hash. If not a hex string, it will be hashed to create a feed topic.
+- `postageBatchId`: (Optional) The postage stamp batch ID which will be used to perform the upload, if it is provided.
+
+**Sample prompt:**
+
+```bash
+Update the Swarm feed of Topic1 with: Message1 using postage batch id 3b3881ac37f936a4023a4562c69f1f138df8c1c24994f7b047514fbcbe9388fa.
+```
+
+
+### `swarm-read-feed`
+
+Retrieve the latest data from the feed of a given topic.
+
+**Parameters:**
+
+- `memoryTopic`: Feed topic.
+- `owner`: (Optional) When accessing external memory or feed, ethereum address of the owner must be set..
+
+**Sample prompt:**
+
+```bash
+Read the Swarm feed of Topic1.
+```
+
+
+### `swarm-upload-file`
+
+Upload a file to Swarm.
+
+**Parameters:**
+
+- `data`: base64 encoded file content or file path.
+- `isPath`: Wether the data parameter is a path.
+- `redundancyLevel`: (Optional) Redundancy level for fault tolerance (higher values provide better fault tolerance but increase storage overhead). 0 - none, 1 - medium, 2 - strong, 3 - insane, 4 - paranoid.
+- `postageBatchId`: (Optional) The postage stamp batch ID which will be used to perform the upload, if it is provided.
+
+**Sample prompt:**
+
+```bash
+Upload to Swarm the file: uploads/file.txt.
+```
+
+
+### `swarm-upload-folder`
+
+Upload a folder to Swarm.
+
+**Parameters:**
+
+- `folderPath`: Path to the folder to upload. 
+- `redundancyLevel`: (Optional) Redundancy level for fault tolerance (higher values provide better fault tolerance but increase storage overhead). 0 - none, 1 - medium, 2 - strong, 3 - insane, 4 - paranoid. 
+- `postageBatchId`: (Optional) The postage stamp batch ID which will be used to perform the upload, if it is provided.
+
+**Sample prompt:**
+
+```bash
+Upload to Swarm folder: /home/conversational-agent-client/uploads.
+```
+
+
+### `swarm-download-files`
+
+Download folder, files from a Swarm reference and save to file path or return file list of the reference.
+
+
+**Parameters:**
+
+- `reference`: Swarm reference hash.
+- `filePath`: (Optional) Optional file path to save the downloaded content. If not provided list of files in the manifest will be returned.
+
+**Sample prompt:**
+
+```bash
+Download from Swarm the file with reference ba35af06601ddf5ac3d71ee33da0db7537215a914fd6a5414b5597bb3d618bdb to folder downloads.
+```
+
+
+### `swarm-query-upload-progress`
+
+Query upload progress for a specific upload session identified with the returned Tag ID.
+
+**Parameters:**
+
+- `tagId`: Tag ID returned by swarm-upload-file and swarm-upload-folder tools to track upload progress.
+
+**Sample prompt:**
+
+```bash
+Query Swarm for upload tag with id: 1.
+```
+
+
+## Run tests
+
+
+```bash
+npm run test src/plugins/community/swarm
+```
+
+
+## Resources
+
+- [Official Swarm Documentation](https://docs.ethswarm.org/)
+- [The Book Of Swarm](https://papers.ethswarm.org/p/book-of-swarm/)

package/src/plugins/community/swarm/SwarmPlugin.ts

@@ -0,0 +1,178 @@
+import {
+  BasePlugin,
+  type GenericPluginContext,
+  type HederaAgentKit,
+  type HederaTool,
+} from "hedera-agent-kit";
+import { Bee } from "@ethersphere/bee-js";
+import { ListPostageStampsTool } from "./tools/ListPostageStampsTool";
+import { UploadDataTool } from "./tools/UploadDataTool";
+import { DownloadDataTool } from "./tools/DownloadDataTool";
+import { CreatePostageStampTool } from "./tools/CreatePostageStampTool";
+import { ExtendPostageStampTool } from "./tools/ExtendPostageStampTool";
+import { QueryUploadProgressTool } from "./tools/QueryUploadProgressTool";
+import { DownloadFilesTool } from "./tools/DownloadFilesTool";
+import { GetPostageStampTool } from "./tools/GetPostageStampTool";
+import { ReadFeedTool } from "./tools/ReadFeedTool";
+import { UpdateFeedTool } from "./tools/UpdateFeedTool";
+import { UploadFileTool } from "./tools/UploadFileTool";
+import { UploadFolderTool } from "./tools/UploadFolderTool";
+import { SwarmConfig } from "./config";
+
+export class SwarmPlugin extends BasePlugin<GenericPluginContext> {
+  id = "swarm";
+  name = "Swarm Plugin";
+  description =
+    "Swarm operations: tools for interacting with the Swarm decentralized storage.";
+  version = "1.0.0";
+  author = "Solar Punk";
+  namespace = "swarm";
+
+  private config: SwarmConfig | null;
+  private tools: HederaTool[] = [];
+
+  constructor(
+    config?: SwarmConfig
+  ) {
+    super();
+    this.config = config || null;
+  }
+
+  override async initialize(context: GenericPluginContext): Promise<void> {
+    
+    await super.initialize(context);
+
+    const hederaKit = context.config.hederaKit as HederaAgentKit | undefined;
+
+    if (!hederaKit) {
+      this.context.logger.warn(
+        'SwarmPlugin skipped because HederaAgentKit was not present in plugin context.'
+      );
+      this.tools = [];
+      return;
+    }
+    
+    if (!this.config) {
+      this.context.logger.warn(
+        'SwarmPlugin skipped because Swarm config was not present.'
+      );
+      this.tools = [];
+      return;
+    }
+    
+    const beeURL = this.config.beeApiUrl;
+    
+    const bee = new Bee(beeURL);
+
+    const createPostageStampTool = new CreatePostageStampTool({
+      hederaKit,
+      bee,
+      config: this.config,
+      logger: this.context.logger,
+    });
+
+    const downloadDataTool = new DownloadDataTool({
+      hederaKit,
+      bee,
+      config: this.config,
+      logger: this.context.logger,
+    });
+    
+    const downloadFilesTool = new DownloadFilesTool({
+      hederaKit,
+      bee,
+      config: this.config,
+      logger: this.context.logger,
+    });
+    
+    const extendPostageStampTool = new ExtendPostageStampTool({
+      hederaKit,
+      bee,
+      config: this.config,
+      logger: this.context.logger,
+    });
+
+    const getPostageStampsTool = new GetPostageStampTool({
+      hederaKit,
+      bee,
+      config: this.config,
+      logger: this.context.logger,
+    });
+    
+    const listPostageStampsTool = new ListPostageStampsTool({
+      hederaKit,
+      bee,
+      config: this.config,
+      logger: this.context.logger,
+    });
+    
+    const queryUploadProgressTool = new QueryUploadProgressTool({
+      hederaKit,
+      bee,
+      config: this.config,
+      logger: this.context.logger,
+    });
+    
+    const readFeedTool = new ReadFeedTool({
+      hederaKit,
+      bee,
+      config: this.config,
+      logger: this.context.logger,
+    });
+    
+    const updateFeedTool = new UpdateFeedTool({
+      hederaKit,
+      bee,
+      config: this.config,
+      logger: this.context.logger,
+    });
+    
+    const uploadDataTool = new UploadDataTool({
+      hederaKit,
+      bee,
+      config: this.config,
+      logger: this.context.logger,
+    });
+    
+    const uploadFileTool = new UploadFileTool({
+      hederaKit,
+      bee,
+      config: this.config,
+      logger: this.context.logger,
+    });
+    
+    const uploadFolderTool = new UploadFolderTool({
+      hederaKit,
+      bee,
+      config: this.config,
+      logger: this.context.logger,
+    });
+    
+    this.tools = [
+      createPostageStampTool,
+      downloadDataTool,
+      downloadFilesTool,
+      extendPostageStampTool,
+      getPostageStampsTool,
+      listPostageStampsTool,
+      queryUploadProgressTool,
+      readFeedTool,
+      updateFeedTool,
+      uploadDataTool,
+      uploadFileTool,
+      uploadFolderTool
+    ];
+
+    this.context.logger.info(
+      "Swarm Plugin initialized."
+    );
+  }
+
+  override getTools(): HederaTool[] {
+    return this.tools;
+  }
+
+  override async cleanup(): Promise<void> {
+    this.tools = [];
+  }
+}

package/src/plugins/community/swarm/__tests__/SwarmPlugin.mocks.ts

@@ -0,0 +1,105 @@
+// Must be imported before SwarmPlugin
+import { jest } from '@jest/globals';
+
+// Mock hedera-agent-kit
+jest.mock('hedera-agent-kit', () => {
+  class MockBasePlugin {
+    context = {
+      logger: {
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+        debug: jest.fn(),
+      },
+      config: {},
+    };
+
+    async initialize(context) {
+      this.context = { ...this.context, ...context };
+    }
+
+    async cleanup() {}
+  }
+
+  return {
+    GenericPluginContext: jest.fn(),
+    HederaTool: jest.fn(),
+    BasePlugin: MockBasePlugin,
+  };
+});
+
+jest.mock('../tools/ListPostageStampsTool', () => ({
+  ListPostageStampsTool: class {
+    executeQuery = jest.fn();
+  },
+}));
+
+jest.mock('../tools/UploadDataTool', () => ({
+  UploadDataTool: class {
+    executeQuery = jest.fn();
+  },
+}));
+
+jest.mock('../tools/DownloadDataTool', () => ({
+  DownloadDataTool: class {
+    executeQuery = jest.fn();
+  },
+}));
+
+jest.mock('../tools/CreatePostageStampTool', () => ({
+  CreatePostageStampTool: class {
+    executeQuery = jest.fn();
+  },
+}));
+
+jest.mock('../tools/ExtendPostageStampTool', () => ({
+  ExtendPostageStampTool: class {
+    executeQuery = jest.fn();
+  },
+}));
+
+jest.mock('../tools/QueryUploadProgressTool', () => ({
+  QueryUploadProgressTool: class {
+    executeQuery = jest.fn();
+  },
+}));
+
+jest.mock('../tools/DownloadFilesTool', () => ({
+  DownloadFilesTool: class {
+    executeQuery = jest.fn();
+  },
+}));
+
+jest.mock('../tools/GetPostageStampTool', () => ({
+  GetPostageStampTool: class {
+    executeQuery = jest.fn();
+  },
+}));
+
+jest.mock('../tools/ReadFeedTool', () => ({
+  ReadFeedTool: class {
+    executeQuery = jest.fn();
+  },
+}));
+
+jest.mock('../tools/UpdateFeedTool', () => ({
+  UpdateFeedTool: class {
+    executeQuery = jest.fn();
+  },
+}));
+
+jest.mock('../tools/UploadFileTool', () => ({
+  UploadFileTool: class {
+    executeQuery = jest.fn();
+  },
+}));
+
+jest.mock('../tools/UploadFolderTool', () => ({
+  UploadFolderTool: class {
+    executeQuery = jest.fn();
+  },
+}));
+
+jest.mock('@ethersphere/bee-js', () => ({
+  Bee: class {},
+}));

package/src/plugins/community/swarm/__tests__/SwarmPlugin.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Comprehensive tests for SwarmPlugin
+ * Tests all public methods and initialization scenarios.
+ */
+
+import { describe, expect, beforeEach, jest } from '@jest/globals';
+
+import './SwarmPlugin.mocks';
+
+import { BasePlugin, type GenericPluginContext, type HederaAgentKit } from "hedera-agent-kit";
+import { SwarmConfig } from '../config';
+import { SwarmPlugin } from "../SwarmPlugin";
+
+describe("SwarmPlugin", () => {
+  let plugin: SwarmPlugin;
+  let mockContext: GenericPluginContext;
+  let hederaKitMock: HederaAgentKit;
+  let loggerMock: { info: jest.Mock; warn: jest.Mock };
+  let swarmConfig: SwarmConfig;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    loggerMock = {
+      info: jest.fn(),
+      warn: jest.fn(),
+    };
+    hederaKitMock = {} as HederaAgentKit; // Mock minimal HederaAgentKit
+    mockContext = {
+      config: {
+        hederaKit: hederaKitMock,
+      },
+      logger: loggerMock,
+    } as unknown as GenericPluginContext;
+
+    swarmConfig = { 
+      beeApiUrl: "http://127.0.0.1:1633",
+      beeFeedPK: "",
+      autoAssignStamp: true,
+      deferredUploadSizeThresholdMB: 5 
+    };
+
+    plugin = new SwarmPlugin(swarmConfig);
+  });
+
+  it("should construct with config", () => {
+    plugin = new SwarmPlugin(swarmConfig);
+    expect(plugin).toBeInstanceOf(SwarmPlugin);
+  });
+
+  it("should skip initialization if hederaKit is missing", async () => {
+    plugin = new SwarmPlugin(swarmConfig);
+    const contextWithoutKit = { ...mockContext, config: {} };
+    await plugin.initialize(contextWithoutKit);
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      "SwarmPlugin skipped because HederaAgentKit was not present in plugin context."
+    );
+    expect(plugin.getTools()).toHaveLength(0);
+  });
+
+  it("should skip initialization if config is missing", async () => {
+    plugin = new SwarmPlugin();
+    await plugin.initialize(mockContext);
+    expect(loggerMock.warn).toHaveBeenCalledWith(
+      "SwarmPlugin skipped because Swarm config was not present."
+    );
+    expect(plugin.getTools()).toHaveLength(0);
+  });
+
+  it("should initialize all tools and log info with valid config and hederaKit", async () => {
+    plugin = new SwarmPlugin(swarmConfig);
+
+    // Spy on super.initialize (BasePlugin's initialize)
+    const superInitializeSpy = jest.spyOn(BasePlugin.prototype, "initialize");
+
+    await plugin.initialize(mockContext);
+
+    expect(superInitializeSpy).toHaveBeenCalledWith(mockContext);
+    expect(plugin.getTools()).toHaveLength(12);
+
+    expect(loggerMock.info).toHaveBeenCalledWith(
+      "Swarm Plugin initialized."
+    );
+  });
+
+  it("getTools returns empty array after cleanup", async () => {
+    plugin = new SwarmPlugin(swarmConfig);
+    await plugin.initialize(mockContext);
+    expect(plugin.getTools()).toHaveLength(12);
+
+    await plugin.cleanup();
+    expect(plugin.getTools()).toHaveLength(0);
+  });
+});