@hashgraphonline/conversational-agent 0.2.216 → 0.2.218

package/src/plugins/community/swarm/tools/CreatePostageStampTool.ts

@@ -0,0 +1,137 @@
+import {
+  BaseHederaQueryTool,
+  HederaAgentKit,
+  type GenericPluginContext,
+} from "hedera-agent-kit";
+import { BatchId, Bee, Duration, Size } from "@ethersphere/bee-js";
+import { z } from "zod";
+import {
+  errorHasStatus,
+  getErrorMessage,
+  makeDate,
+  runWithTimeout,
+  ToolResponse,
+} from "../utils";
+import { BAD_REQUEST_STATUS, CALL_TIMEOUT, GATEWAY_STAMP_ERROR_MESSAGE, NOT_FOUND_STATUS, POSTAGE_CREATE_TIMEOUT_MESSAGE } from "../constants";
+import { SwarmConfig } from "../config";
+
+const CreatePostageStampSchema = z.object({
+  size: z.number(),
+  duration: z.string(),
+  label: z.string().optional(),
+});
+
+export class CreatePostageStampTool extends BaseHederaQueryTool<typeof CreatePostageStampSchema> {
+  name = "swarm-create-postage-stamp";
+  description = `
+    Buy postage stamp based on size in megabytes and duration.
+    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, e.g. 1d - 1 day, 1w - 1 week, 1month - 1 month.
+    label: Sets label for the postage batch (omit if the user didn't ask for one). Do not set a label with with specific capacity values because they can get misleading.
+  `;
+  namespace = "swarm";
+  specificInputSchema = CreatePostageStampSchema;
+  bee: Bee;
+  config: SwarmConfig;
+  
+  constructor(params: {
+    hederaKit: HederaAgentKit;
+    config: SwarmConfig;
+    logger?: GenericPluginContext['logger'];
+    bee: Bee;
+  }) {
+    const { bee, config, ...rest } = params;
+    super(rest);
+    this.bee = bee;
+    this.config = config;
+  }
+  
+  protected async executeQuery(
+      input: z.infer<typeof CreatePostageStampSchema>
+  ): Promise<ToolResponse | string> {
+    const { size, duration, label } = input;
+
+    if (!size) {
+      this.logger.error(
+        'Missing required parameter: size.'
+      );
+      
+      throw new Error('Missing required parameter: size.');
+    } else if (!duration) {
+      this.logger.error(
+        'Missing required parameter: duration.'
+      );
+      
+      throw new Error('Missing required parameter: duration.');
+    }
+
+    let durationMs;
+
+    try {
+      durationMs = makeDate(duration);
+    } catch (makeDateError) {
+      this.logger.error(
+        'Invalid parameter: duration.'
+      );
+
+      throw new Error('Invalid parameter: duration.');
+    }
+
+    let buyStorageResponse: BatchId;
+
+    try {
+      let options = {};
+      if (label !== undefined) {
+        options = {
+          label
+        };
+      }
+      const buyStoragePromise = this.bee.buyStorage(
+        Size.fromMegabytes(size),
+        Duration.fromMilliseconds(durationMs),
+        options
+      );
+      const [response, hasTimedOut] = await runWithTimeout(
+        buyStoragePromise,
+        CALL_TIMEOUT
+      );
+
+      if (hasTimedOut) {
+        return JSON.stringify({
+          content: [
+            {
+              type: 'text',
+              text: POSTAGE_CREATE_TIMEOUT_MESSAGE,
+            },
+          ],
+        });
+      }
+
+      buyStorageResponse = response as BatchId;
+    } catch (error) {
+      let errorMessage = 'Unable to buy storage.';
+
+      if (errorHasStatus(error, NOT_FOUND_STATUS)) {
+        errorMessage = GATEWAY_STAMP_ERROR_MESSAGE;
+      } else if (errorHasStatus(error, BAD_REQUEST_STATUS)) {
+        errorMessage = getErrorMessage(error);
+      }
+
+      this.logger.error(
+        errorMessage,
+        error
+      );
+
+      throw new Error(errorMessage);
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Postage batch ID: ${buyStorageResponse.toHex()}`,
+        },
+      ],
+    };
+  }
+}

package/src/plugins/community/swarm/tools/DownloadDataTool.ts

@@ -0,0 +1,79 @@
+import { Bee } from "@ethersphere/bee-js";
+import { z } from "zod";
+import { errorHasStatus, getErrorMessage, getResponseWithStructuredContent, ToolResponse } from "../utils";
+import { BaseHederaQueryTool, GenericPluginContext, HederaAgentKit } from "hedera-agent-kit";
+import { SwarmConfig } from "../config";
+import { BAD_REQUEST_STATUS } from "../constants";
+
+const DownloadDataSchema = z.object({
+  reference: z.string(),
+});
+
+export class DownloadDataTool extends BaseHederaQueryTool<typeof DownloadDataSchema> {
+  name = "swarm-download-data";
+  description = `
+    Downloads immutable data from a Swarm content address hash.
+    reference: Swarm reference hash.
+  `;
+  namespace = "swarm";
+  specificInputSchema = DownloadDataSchema;
+  bee: Bee;
+  config: SwarmConfig;
+  
+  constructor(params: {
+    hederaKit: HederaAgentKit;
+    config: SwarmConfig;
+    logger?: GenericPluginContext['logger'];
+    bee: Bee;
+  }) {
+    const { bee, config, ...rest } = params;
+    super(rest);
+    this.bee = bee;
+    this.config = config;
+  }
+
+  protected async executeQuery(
+      input: z.infer<typeof DownloadDataSchema>
+  ): Promise<ToolResponse | string> {
+    const { reference } = input;
+
+    if (!reference) {
+      this.logger.error(
+        'Missing required parameter: reference.'
+      );
+
+      throw new Error("Missing required parameter: reference.");
+    }
+
+    const isRefNotSwarmHash =
+      reference.length !== 64 && reference.length !== 66;
+
+    if (isRefNotSwarmHash) {
+      this.logger.error(
+        'Invalid Swarm content address hash value for reference.'
+      );
+
+      throw new Error("Invalid Swarm content address hash value for reference.");
+    }
+
+    let data;
+    try {
+      data = await this.bee.downloadData(reference);
+    } catch (error) {
+      let errorMessage = 'Downloading data failed.';
+
+      if (errorHasStatus(error, BAD_REQUEST_STATUS)) {
+        errorMessage = getErrorMessage(error);
+      }
+
+      this.logger.error(errorMessage, error);
+      throw new Error(errorMessage);
+    }
+
+    const textData = data.toUtf8();
+
+    return getResponseWithStructuredContent({
+      textData,
+    });
+  }
+}

package/src/plugins/community/swarm/tools/DownloadFilesTool.ts

@@ -0,0 +1,155 @@
+import { Bee, MantarayNode } from "@ethersphere/bee-js";
+import { z } from "zod";
+import fs from "fs";
+import path from "path";
+import { BaseHederaQueryTool, GenericPluginContext, HederaAgentKit } from "hedera-agent-kit";
+import { promisify } from "util";
+import { ToolResponse } from "../utils";
+import { SwarmConfig } from "../config";
+
+const DownloadFilesSchema = z.object({
+  reference: z.string(),
+  filePath: z.string().optional()
+});
+
+export class DownloadFilesTool extends BaseHederaQueryTool<typeof DownloadFilesSchema> {
+  name = "swarm-download-files";
+  description = `Download folder, files from a Swarm reference and save to file path or return file list of the reference.
+    Prioritizes this tool over swarm-download-data if there is no assumption about the data type.
+    reference: Swarm reference hash.
+    filePath: Optional file path to save the downloaded content (only available in stdio mode). If not provided list of files in the manifest will be returned.
+  `;
+  namespace = "swarm";
+  specificInputSchema = DownloadFilesSchema;
+  bee: Bee; 
+  config: SwarmConfig;
+
+  constructor(params: {
+    hederaKit: HederaAgentKit;
+    config: SwarmConfig;
+    logger?: GenericPluginContext['logger'];
+    bee: Bee;
+  }) {
+    const { bee, config, ...rest } = params;
+    super(rest);
+    this.bee = bee;
+    this.config = config;
+  }
+
+  protected async executeQuery(
+      input: z.infer<typeof DownloadFilesSchema>
+  ): Promise<ToolResponse | string> {
+    const { reference, filePath } = input;
+    
+    if (!reference) {
+      this.logger.error(
+        'Missing required parameter: reference.'
+      );
+      
+      throw new Error("Missing required parameter: reference.");
+    }
+
+    this.logger.info(`[API] Downloading folder from Swarm with reference: ${reference}.`);
+
+    // Check if the reference is a manifest
+    let isManifest = false;
+    let node: MantarayNode;
+
+    try {
+      node = await MantarayNode.unmarshal(this.bee, reference);
+      await node.loadRecursively(this.bee);
+      isManifest = true;
+    } catch (error) {
+      // ignore
+    }
+
+    if (isManifest) {
+      if (filePath) {
+        const destinationFolder = filePath;
+
+        if (!fs.existsSync(destinationFolder)) {
+          await promisify(fs.mkdir)(destinationFolder, { recursive: true });
+        }
+
+        const nodes = node!.collect();
+
+        if (nodes.length === 1) {
+          const node = nodes[0];
+          const data = await this.bee.downloadData(node.targetAddress);
+          await promisify(fs.writeFile)(
+            path.join(
+              destinationFolder,
+              node.fullPathString.split("\\").slice(-1)[0]
+            ),
+            data.toUint8Array()
+          );
+        } else {
+          // Download each node
+          for (const node of nodes) {
+            const parsedPath = path.parse(node.fullPathString);
+            const nodeDestFolder = path.join(destinationFolder, parsedPath.dir);
+            // Create subdirectories if necessary
+            if (!fs.existsSync(nodeDestFolder)) {
+              await promisify(fs.mkdir)(nodeDestFolder, { recursive: true });
+            }
+
+            const data = await this.bee.downloadData(node.targetAddress);
+            await promisify(fs.writeFile)(
+              path.join(destinationFolder, node.fullPathString),
+              data.toUint8Array()
+            );
+          }
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  reference: reference,
+                  manifestNodeCount: nodes.length,
+                  savedTo: destinationFolder,
+                  message: `Manifest content (${nodes.length} files) successfully downloaded to ${destinationFolder}`,
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      } else {
+        // regular file
+        const nodes = node!.collect();
+        const filesList = nodes.map((node) => ({
+          path: node.fullPathString || "/",
+          targetAddress: Array.from(node.targetAddress)
+            .map((e) => e.toString(16).padStart(2, "0"))
+            .join(""),
+          metadata: node.metadata,
+        }));
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  reference: reference,
+                  type: "manifest",
+                  files: filesList,
+                  message:
+                    "This is a manifest with multiple files. Provide a filePath to download all files or download individual files using their specific references.",
+                },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      }
+    } else {
+      return "Try swarm-download-data tool instead since the given reference is not a manifest.";
+    }
+  }
+}

package/src/plugins/community/swarm/tools/ExtendPostageStampTool.ts

@@ -0,0 +1,112 @@
+import {
+  BaseHederaQueryTool,
+  HederaAgentKit,
+  type GenericPluginContext,
+} from "hedera-agent-kit";
+import { BatchId, Bee, Duration, Size } from "@ethersphere/bee-js";
+import { z } from "zod";
+import {
+  errorHasStatus,
+  getErrorMessage,
+  getResponseWithStructuredContent,
+  makeDate,
+  ToolResponse,
+} from "../utils";
+import { BAD_REQUEST_STATUS, GATEWAY_STAMP_ERROR_MESSAGE, NOT_FOUND_STATUS } from "../constants";
+import { SwarmConfig } from "../config";
+
+const ExtendPostageStampSchema = z.object({
+  postageBatchId: z.string(),
+  duration: z.string().optional(),
+  size: z.number().optional(),
+});
+
+export class ExtendPostageStampTool extends BaseHederaQueryTool<typeof ExtendPostageStampSchema> {
+  name = "swarm-extend-postage-stamp";
+  description = `Increase the duration (relative to current duration) or size (in megabytes) of a postage stamp.
+    postageBatchId: The id of the batch for which extend is performed.
+    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, e.g. 1d - 1 day, 1w - 1 week, 1month - 1 month.
+  `;
+  namespace = "swarm";
+  specificInputSchema = ExtendPostageStampSchema;
+  bee: Bee;
+  config: SwarmConfig;
+    
+  constructor(params: {
+    hederaKit: HederaAgentKit;
+    config: SwarmConfig;
+    logger?: GenericPluginContext['logger'];
+    bee: Bee;
+  }) {
+    const { bee, config, ...rest } = params;
+    super(rest);
+    this.bee = bee;
+    this.config = config;
+  }
+  
+  protected async executeQuery(
+    input: z.infer<typeof ExtendPostageStampSchema>
+  ): Promise<ToolResponse | string> {
+    const { postageBatchId, duration, size } = input;
+
+    if (!postageBatchId) {
+      this.logger.error(
+        'Missing required parameter: postageBatchId.'
+      );
+
+      throw new Error('Missing required parameter: postageBatchId.');
+    } else if (!duration && !size) {
+      this.logger.error(
+        'You need at least one parameter from duration and size.'
+      );
+
+      throw new Error('You need at least one parameter from duration and size.');
+    }
+
+    // If size is missing, Size.fromBytes(1) will get smallest depth and not increase size.
+    const extendSize = !!size ? Size.fromMegabytes(size) : Size.fromBytes(1); 
+    let extendDuration = Duration.ZERO;
+
+    try {
+      if (duration) {
+        extendDuration = Duration.fromMilliseconds(makeDate(duration));
+      }
+    } catch (makeDateError) {
+      this.logger.error(
+        'Invalid parameter: duration.'
+      );
+
+      throw new Error('Invalid parameter: duration.');
+    }
+
+    let extendStorageResponse;
+
+    try {
+      extendStorageResponse = await this.bee.extendStorage(
+        postageBatchId,
+        extendSize,
+        extendDuration
+      );
+    } catch (error) {
+      let errorMessage = 'Extend failed.';
+
+      if (errorHasStatus(error, NOT_FOUND_STATUS)) {
+        errorMessage = GATEWAY_STAMP_ERROR_MESSAGE;
+      } else if (errorHasStatus(error, BAD_REQUEST_STATUS)) {
+        errorMessage = getErrorMessage(error);
+      }
+
+      this.logger.error(
+        errorMessage,
+        error
+      );
+
+      throw new Error(errorMessage);
+    }
+
+    return getResponseWithStructuredContent({
+      postageBatchId: extendStorageResponse.toHex(),
+    });
+  }
+}

package/src/plugins/community/swarm/tools/GetPostageStampTool.ts

@@ -0,0 +1,92 @@
+import {
+  type GenericPluginContext,
+  BaseHederaQueryTool,
+  type HederaAgentKit,
+} from "hedera-agent-kit";
+import { Bee } from "@ethersphere/bee-js";
+import { z } from "zod";
+import {
+  PostageBatchCurated,
+  PostageBatchSummary,
+  ResponseContent,
+} from "../model";
+import {
+  errorHasStatus,
+  getBatchSummary,
+  getResponseWithStructuredContent,
+  ToolResponse,
+} from "../utils";
+import { GATEWAY_STAMP_ERROR_MESSAGE, NOT_FOUND_STATUS } from "../constants";
+import { SwarmConfig } from "../config";
+
+const GetPostageStampSchema = z.object({
+  postageBatchId: z.string(),
+});
+
+export class GetPostageStampTool extends BaseHederaQueryTool<typeof GetPostageStampSchema> {
+  name = "swarm-get-postage-stamp";
+  description = `Get a specific postage stamp based on postageBatchId.
+    postageBatchId: The id of the stamp which is requested.
+  `;
+  namespace = "swarm";
+  specificInputSchema = GetPostageStampSchema;
+  bee: Bee;
+  config: SwarmConfig;
+      
+  constructor(params: {
+    hederaKit: HederaAgentKit;
+    config: SwarmConfig;
+    logger?: GenericPluginContext['logger'];
+    bee: Bee;
+  }) {
+    const { bee, config, ...rest } = params;
+    super(rest);
+    this.bee = bee;
+    this.config = config;
+  }
+
+  protected async executeQuery(
+      input: z.infer<typeof GetPostageStampSchema>
+  ): Promise<ToolResponse | string> {
+    const { postageBatchId } = input;
+    if (!postageBatchId) {
+      this.logger.error(
+        'Missing required parameter: postageBatchId.'
+      );
+
+      throw new Error("Missing required parameter: postageBatchId.");
+    }
+
+    let rawPostageBatch;
+
+    try {
+      rawPostageBatch = await this.bee.getPostageBatch(postageBatchId);
+    } catch (error) {
+      let errorMessage = 'Retrieval of postage batch failed.';
+    
+      if (errorHasStatus(error, NOT_FOUND_STATUS)) {
+        errorMessage = GATEWAY_STAMP_ERROR_MESSAGE;
+      }
+
+      this.logger.error(
+        errorMessage,
+        error
+      );
+
+      throw new Error(errorMessage);
+    }
+
+    const batch: PostageBatchCurated = {
+      ...rawPostageBatch,
+      batchID: rawPostageBatch.batchID.toHex(),
+    };
+    const batchSummary: PostageBatchSummary = getBatchSummary(rawPostageBatch);
+
+    const content: ResponseContent<PostageBatchCurated, PostageBatchSummary> = {
+      raw: batch,
+      summary: batchSummary,
+    };
+
+    return getResponseWithStructuredContent(content);
+  }
+}

package/src/plugins/community/swarm/tools/ListPostageStampsTool.ts

@@ -0,0 +1,124 @@
+import {
+  type GenericPluginContext,
+  BaseHederaQueryTool,
+  type HederaAgentKit,
+} from "hedera-agent-kit";
+import { Bee } from "@ethersphere/bee-js";
+import { z } from "zod";
+import {
+  PostageBatchCurated,
+  PostageBatchSummary,
+  ResponseContent,
+} from "../model";
+import {
+  errorHasStatus,
+  getBatchSummary,
+  getResponseWithStructuredContent,
+  ToolResponse,
+} from "../utils";
+import { GATEWAY_STAMP_ERROR_MESSAGE, NOT_FOUND_STATUS } from "../constants";
+import { SwarmConfig } from "../config";
+
+const ListPostageStampsSchema = z.object({
+  leastUsed: z.boolean().optional(),
+  limit: z.number().optional(),
+  minUsage: z.number().optional(),
+  maxUsage: z.number().optional(),
+});
+
+export class ListPostageStampsTool extends BaseHederaQueryTool<typeof ListPostageStampsSchema> {
+  name = "swarm-list-postage-stamps";
+  description =`
+    List the available postage stamps.
+    leastUsed: A boolean value that tells if stamps are sorted so least used comes first.
+    limit: Limit is the maximum number of returned stamps.
+    minUsage: Only list stamps with at least this usage percentage.
+    maxUsage: Only list stamps with at most this usage percentage.  
+  `;
+  namespace = "swarm";
+  specificInputSchema = ListPostageStampsSchema;
+  bee: Bee;
+  config: SwarmConfig;
+  
+  constructor(params: {
+    hederaKit: HederaAgentKit;
+    config: SwarmConfig;
+    logger?: GenericPluginContext['logger'];
+    bee: Bee;
+  }) {
+    const { bee, config, ...rest } = params;
+    super(rest);
+    this.bee = bee;
+    this.config = config;
+  }
+
+  protected async executeQuery(
+      input: z.infer<typeof ListPostageStampsSchema>
+  ): Promise<ToolResponse | string> {
+    const { leastUsed, limit, minUsage, maxUsage } = input;
+
+    let rawPostageBatches;
+
+    try {
+      rawPostageBatches = await this.bee.getPostageBatches();
+    } catch (error) {
+      let errorMessage = 'Retrieval of postage batches failed.';
+
+      if (errorHasStatus(error, NOT_FOUND_STATUS)) {
+        errorMessage = GATEWAY_STAMP_ERROR_MESSAGE;
+      }
+    
+      this.logger.error(
+        errorMessage,
+        error
+      );
+    
+      throw new Error(errorMessage);
+    }
+
+    const batches: PostageBatchCurated[] = rawPostageBatches.map((batch) => ({
+      ...batch,
+      batchID: batch.batchID.toHex(),
+    }));
+    let filteredPostageBatches = batches.filter((batch) => {
+      if (!batch.usable) {
+        return false;
+      }
+
+      const usagePercentage = batch.usage * 100;
+
+      if (minUsage !== undefined && usagePercentage < minUsage) {
+        return false;
+      }
+
+      if (maxUsage !== undefined && usagePercentage > maxUsage) {
+        return false;
+      }
+
+      return true;
+    });
+
+    if (Boolean(leastUsed) && filteredPostageBatches.length) {
+      filteredPostageBatches = filteredPostageBatches.sort(
+        (batch1, batch2) => batch1.usage - batch2.usage
+      );
+    }
+
+    if (limit !== undefined && limit < filteredPostageBatches.length) {
+      filteredPostageBatches = filteredPostageBatches.slice(0, limit);
+    }
+
+    const computedPostageBatches: PostageBatchSummary[] =
+      filteredPostageBatches.map((batch) => getBatchSummary(batch));
+
+    const content: ResponseContent<
+      PostageBatchCurated[],
+      PostageBatchSummary[]
+    > = {
+      raw: filteredPostageBatches,
+      summary: computedPostageBatches,
+    };
+
+    return getResponseWithStructuredContent(content);
+  }
+}