@hashgraphonline/standards-agent-kit 0.2.1 → 0.2.102

package/src/tools/inscriber/InscribeFromUrlTool.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+import { BaseInscriberQueryTool } from './base-inscriber-tools';
+import { InscriptionOptions } from '@hashgraphonline/standards-sdk';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for inscribing from URL
+ */
+const inscribeFromUrlSchema = z.object({
+  url: z.string().url().describe('The URL of the content to inscribe'),
+  mode: z
+    .enum(['file', 'hashinal'])
+    .optional()
+    .describe('Inscription mode: file or hashinal NFT'),
+  metadata: z
+    .record(z.unknown())
+    .optional()
+    .describe('Metadata to attach to the inscription'),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe('Tags to categorize the inscription'),
+  chunkSize: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Chunk size for large files'),
+  waitForConfirmation: z
+    .boolean()
+    .optional()
+    .describe('Whether to wait for inscription confirmation'),
+  apiKey: z
+    .string()
+    .optional()
+    .describe('API key for inscription service'),
+});
+
+
+/**
+ * Tool for inscribing content from URL
+ */
+export class InscribeFromUrlTool extends BaseInscriberQueryTool<typeof inscribeFromUrlSchema> {
+  name = 'inscribeFromUrl';
+  description = 'Inscribe content from a URL to the Hedera network';
+
+  get specificInputSchema() {
+    return inscribeFromUrlSchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof inscribeFromUrlSchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    const options: InscriptionOptions = {
+      mode: params.mode,
+      metadata: params.metadata,
+      tags: params.tags,
+      chunkSize: params.chunkSize,
+      waitForConfirmation: params.waitForConfirmation ?? true,
+      waitMaxAttempts: 10,
+      waitIntervalMs: 3000,
+      apiKey: params.apiKey,
+      network: this.inscriberBuilder['hederaKit'].client.network.toString().includes('mainnet') ? 'mainnet' : 'testnet',
+    };
+
+    try {
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error('Inscription timed out after 30 seconds')), 30000);
+      });
+
+      const result = await Promise.race([
+        this.inscriberBuilder.inscribe(
+          { type: 'url', url: params.url },
+          options
+        ),
+        timeoutPromise
+      ]) as any;
+
+      if (result.confirmed) {
+        const topicId = result.inscription?.topic_id || result.result.topicId;
+        const network = options.network || 'testnet';
+        const cdnUrl = topicId ? `https://kiloscribe.com/api/inscription-cdn/${topicId}?network=${network}` : null;
+        return `Successfully inscribed and confirmed content on the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\nTopic ID: ${topicId || 'N/A'}${cdnUrl ? `\nView inscription: ${cdnUrl}` : ''}\n\nThe inscription is now available.`;
+      } else {
+        return `Successfully submitted inscription to the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\n\nThe inscription is processing and will be confirmed shortly.`;
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to inscribe from URL';
+      throw new Error(`Inscription failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/inscriber/InscribeHashinalTool.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import { BaseInscriberQueryTool } from './base-inscriber-tools';
+import { InscriptionOptions } from '@hashgraphonline/standards-sdk';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for inscribing Hashinal NFT
+ */
+const inscribeHashinalSchema = z.object({
+  url: z.string().url().describe('The URL of the content to inscribe as Hashinal NFT'),
+  name: z.string().describe('Name of the Hashinal NFT'),
+  creator: z.string().describe('Creator account ID or name'),
+  description: z.string().describe('Description of the Hashinal NFT'),
+  type: z.string().describe('Type of NFT (e.g., "image", "video", "audio")'),
+  attributes: z
+    .array(
+      z.object({
+        trait_type: z.string(),
+        value: z.union([z.string(), z.number()]),
+      })
+    )
+    .optional()
+    .describe('NFT attributes'),
+  properties: z
+    .record(z.unknown())
+    .optional()
+    .describe('Additional properties'),
+  jsonFileURL: z
+    .string()
+    .url()
+    .optional()
+    .describe('URL to JSON metadata file'),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe('Tags to categorize the NFT'),
+  chunkSize: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Chunk size for large files'),
+  waitForConfirmation: z
+    .boolean()
+    .optional()
+    .describe('Whether to wait for inscription confirmation'),
+  apiKey: z
+    .string()
+    .optional()
+    .describe('API key for inscription service'),
+});
+
+
+/**
+ * Tool for inscribing Hashinal NFTs
+ */
+export class InscribeHashinalTool extends BaseInscriberQueryTool<typeof inscribeHashinalSchema> {
+  name = 'inscribeHashinal';
+  description = 'Inscribe content as a Hashinal NFT on the Hedera network';
+
+  get specificInputSchema() {
+    return inscribeHashinalSchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof inscribeHashinalSchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    const metadata = {
+      name: params.name,
+      creator: params.creator,
+      description: params.description,
+      type: params.type,
+      attributes: params.attributes,
+      properties: params.properties,
+    };
+
+    const options: InscriptionOptions = {
+      mode: 'hashinal',
+      metadata,
+      jsonFileURL: params.jsonFileURL,
+      tags: params.tags,
+      chunkSize: params.chunkSize,
+      waitForConfirmation: params.waitForConfirmation ?? true,
+      waitMaxAttempts: 10,
+      waitIntervalMs: 3000,
+      apiKey: params.apiKey,
+      network: this.inscriberBuilder['hederaKit'].client.network.toString().includes('mainnet') ? 'mainnet' : 'testnet',
+    };
+
+    try {
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error('Inscription timed out after 30 seconds')), 30000);
+      });
+
+      const result = await Promise.race([
+        this.inscriberBuilder.inscribe(
+          { type: 'url', url: params.url },
+          options
+        ),
+        timeoutPromise
+      ]) as any;
+
+      if (result.confirmed) {
+        const topicId = result.inscription?.topic_id || result.result.topicId;
+        const network = options.network || 'testnet';
+        const cdnUrl = topicId ? `https://kiloscribe.com/api/inscription-cdn/${topicId}?network=${network}` : null;
+        return `Successfully inscribed and confirmed Hashinal NFT on the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\nTopic ID: ${topicId || 'N/A'}${cdnUrl ? `\nView inscription: ${cdnUrl}` : ''}\n\nThe Hashinal NFT is now available.`;
+      } else {
+        return `Successfully submitted Hashinal NFT inscription to the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\n\nThe inscription is processing and will be confirmed shortly.`;
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to inscribe Hashinal NFT';
+      throw new Error(`Inscription failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/inscriber/RetrieveInscriptionTool.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { BaseInscriberQueryTool } from './base-inscriber-tools';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for retrieving inscription
+ */
+const retrieveInscriptionSchema = z.object({
+  transactionId: z
+    .string()
+    .describe('The transaction ID of the inscription to retrieve'),
+  apiKey: z
+    .string()
+    .optional()
+    .describe('API key for inscription service'),
+});
+
+
+/**
+ * Tool for retrieving inscriptions
+ */
+export class RetrieveInscriptionTool extends BaseInscriberQueryTool<typeof retrieveInscriptionSchema> {
+  name = 'retrieveInscription';
+  description = 'Retrieve details of an existing inscription from the Hedera network';
+
+  get specificInputSchema() {
+    return retrieveInscriptionSchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof retrieveInscriptionSchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    const result = await this.inscriberBuilder.retrieveInscription(
+      params.transactionId,
+      {
+        apiKey: params.apiKey,
+        network: this.inscriberBuilder['hederaKit'].client.network.toString().includes('mainnet') ? 'mainnet' : 'testnet',
+      }
+    );
+
+    return {
+      inscriptionId: (result as any).inscriptionId,
+      transactionId: result.transactionId,
+      topicId: (result as any).topic_id,
+      status: result.status,
+      holderId: (result as any).holderId,
+      metadata: result.metadata,
+      tags: (result as any).tags,
+      mode: result.mode,
+      chunks: (result as any).chunks,
+      createdAt: (result as any).createdAt,
+      completedAt: (result as any).completed || (result as any).completedAt,
+      fileUrl: result.fileUrl,
+      mimeType: (result as any).mimeType,
+      fileSize: (result as any).fileSize,
+    };
+  }
+}

package/src/tools/inscriber/base-inscriber-tools.ts

@@ -0,0 +1,65 @@
+import {
+  BaseHederaTransactionTool,
+  BaseHederaQueryTool,
+  BaseServiceBuilder,
+} from 'hedera-agent-kit';
+import { InscriberBuilder } from '../../builders/inscriber/inscriber-builder';
+import {
+  InscriberTransactionToolParams,
+  InscriberQueryToolParams,
+} from './inscriber-tool-params';
+import { z } from 'zod';
+
+/**
+ * Base class for Inscriber transaction tools
+ */
+export abstract class BaseInscriberTransactionTool<
+  T extends z.ZodObject<
+    z.ZodRawShape,
+    z.UnknownKeysParam,
+    z.ZodTypeAny
+  > = z.ZodObject<z.ZodRawShape>
+> extends BaseHederaTransactionTool<T> {
+  protected inscriberBuilder: InscriberBuilder;
+  namespace = 'inscriber' as const;
+
+  constructor(params: InscriberTransactionToolParams) {
+    super(params);
+    this.inscriberBuilder = params.inscriberBuilder;
+  }
+
+  /**
+   * Override to return the InscriberBuilder
+   */
+  protected getServiceBuilder(): BaseServiceBuilder {
+    return this.inscriberBuilder;
+  }
+}
+
+/**
+ * Base class for Inscriber query tools
+ */
+export abstract class BaseInscriberQueryTool<
+  T extends z.ZodObject<
+    z.ZodRawShape,
+    z.UnknownKeysParam,
+    z.ZodTypeAny,
+    Record<string, unknown>,
+    Record<string, unknown>
+  > = z.ZodObject<z.ZodRawShape>
+> extends BaseHederaQueryTool<T> {
+  protected inscriberBuilder: InscriberBuilder;
+  namespace = 'inscriber' as const;
+
+  constructor(params: InscriberQueryToolParams) {
+    super(params);
+    this.inscriberBuilder = params.inscriberBuilder;
+  }
+
+  /**
+   * Override to return the InscriberBuilder
+   */
+  protected getServiceBuilder(): BaseServiceBuilder {
+    return this.inscriberBuilder;
+  }
+}

package/src/tools/inscriber/index.ts

@@ -0,0 +1,7 @@
+export * from './base-inscriber-tools';
+export * from './inscriber-tool-params';
+export * from './InscribeFromUrlTool';
+export * from './InscribeFromFileTool';
+export * from './InscribeFromBufferTool';
+export * from './InscribeHashinalTool';
+export * from './RetrieveInscriptionTool';

package/src/tools/inscriber/inscriber-tool-params.ts

@@ -0,0 +1,21 @@
+import { HederaAgentKit } from 'hedera-agent-kit';
+import type { BasePluginContext } from 'hedera-agent-kit';
+import { InscriberBuilder } from '../../builders/inscriber/inscriber-builder';
+
+/**
+ * Parameters for Inscriber transaction tools
+ */
+export interface InscriberTransactionToolParams {
+  hederaKit: HederaAgentKit;
+  inscriberBuilder: InscriberBuilder;
+  logger?: BasePluginContext['logger'];
+}
+
+/**
+ * Parameters for Inscriber query tools
+ */
+export interface InscriberQueryToolParams {
+  hederaKit: HederaAgentKit;
+  inscriberBuilder: InscriberBuilder;
+  logger?: BasePluginContext['logger'];
+}