@hashgraphonline/conversational-agent 0.0.1

package/src/conversational-agent.ts

@@ -0,0 +1,309 @@
+import {
+  ServerSigner,
+  HederaConversationalAgent,
+  getAllHederaCorePlugins,
+  BasePlugin,
+} from 'hedera-agent-kit';
+import type {
+  AgentOperationalMode,
+  AgentResponse,
+  HederaConversationalAgentConfig,
+  MirrorNodeConfig,
+} from 'hedera-agent-kit';
+import { HCS10Plugin } from './plugins/hcs-10/HCS10Plugin';
+import { HCS2Plugin } from './plugins/hcs-2/HCS2Plugin';
+import { InscribePlugin } from './plugins/inscribe/InscribePlugin';
+import { OpenConvaiState } from '@hashgraphonline/standards-agent-kit';
+import type { IStateManager } from '@hashgraphonline/standards-agent-kit';
+import {
+  Logger,
+  HederaMirrorNode,
+  type NetworkType,
+} from '@hashgraphonline/standards-sdk';
+import { PrivateKey } from '@hashgraph/sdk';
+import { SYSTEM_MESSAGE } from './config/system-message';
+
+export interface ConversationalAgentOptions {
+  accountId: string;
+  privateKey: string;
+  network?: NetworkType;
+  openAIApiKey: string;
+  openAIModelName?: string;
+  verbose?: boolean;
+  operationalMode?: AgentOperationalMode;
+  userAccountId?: string;
+  customSystemMessagePreamble?: string;
+  customSystemMessagePostamble?: string;
+  additionalPlugins?: BasePlugin[];
+  stateManager?: IStateManager;
+  scheduleUserTransactionsInBytesMode?: boolean;
+  mirrorNodeConfig?: MirrorNodeConfig;
+  disableLogging?: boolean;
+  enabledPlugins?: string[];
+}
+
+/**
+ * The ConversationalAgent class is an optional wrapper around the HederaConversationalAgent class,
+ * which includes the OpenConvAIPlugin and the OpenConvaiState by default.
+ * If you want to use a different plugin or state manager, you can pass them in the options.
+ * This class is not required and the plugin can be used directly with the HederaConversationalAgent class.
+ *
+ * @param options - The options for the ConversationalAgent.
+ * @returns A new instance of the ConversationalAgent class.
+ */
+export class ConversationalAgent {
+  public conversationalAgent?: HederaConversationalAgent;
+  public hcs10Plugin: HCS10Plugin;
+  public hcs2Plugin: HCS2Plugin;
+  public inscribePlugin: InscribePlugin;
+  public stateManager: IStateManager;
+  private options: ConversationalAgentOptions;
+  private logger: Logger;
+
+  constructor(options: ConversationalAgentOptions) {
+    this.options = options;
+    this.stateManager = options.stateManager || new OpenConvaiState();
+    this.hcs10Plugin = new HCS10Plugin();
+    this.hcs2Plugin = new HCS2Plugin();
+    this.inscribePlugin = new InscribePlugin();
+    this.logger = new Logger({ module: 'ConversationalAgent' });
+  }
+
+  async initialize(): Promise<void> {
+    const {
+      accountId,
+      privateKey,
+      network = 'testnet',
+      openAIApiKey,
+      openAIModelName = 'gpt-4o',
+      verbose = false,
+      operationalMode = 'autonomous',
+      userAccountId,
+      customSystemMessagePreamble,
+      customSystemMessagePostamble,
+      additionalPlugins = [],
+      scheduleUserTransactionsInBytesMode,
+      mirrorNodeConfig,
+      disableLogging,
+    } = this.options;
+
+    if (!accountId || !privateKey) {
+      throw new Error('Account ID and private key are required');
+    }
+
+    try {
+      const mirrorNode = new HederaMirrorNode(network, this.logger);
+      const accountInfo = await mirrorNode.requestAccount(accountId);
+      const keyType = accountInfo?.key?._type || '';
+
+      let privateKeyInstance: PrivateKey;
+      if (keyType?.toLowerCase()?.includes('ecdsa')) {
+        privateKeyInstance = PrivateKey.fromStringECDSA(privateKey);
+      } else {
+        privateKeyInstance = PrivateKey.fromStringED25519(privateKey);
+      }
+
+      const serverSigner = new ServerSigner(
+        accountId,
+        privateKeyInstance,
+        network
+      );
+
+      const standardPlugins = [
+        this.hcs10Plugin,
+        this.hcs2Plugin,
+        this.inscribePlugin,
+      ];
+
+      const corePlugins = getAllHederaCorePlugins();
+
+      let allPlugins: BasePlugin[];
+
+      if (this.options.enabledPlugins) {
+        const enabledSet = new Set(this.options.enabledPlugins);
+        const filteredPlugins = [...standardPlugins, ...corePlugins].filter(
+          (plugin) => enabledSet.has(plugin.id)
+        );
+        allPlugins = [...filteredPlugins, ...additionalPlugins];
+      } else {
+        allPlugins = [...standardPlugins, ...corePlugins, ...additionalPlugins];
+      }
+
+      const agentConfig: HederaConversationalAgentConfig = {
+        pluginConfig: {
+          plugins: allPlugins,
+          appConfig: {
+            stateManager: this.stateManager,
+          },
+        },
+        openAIApiKey,
+        openAIModelName,
+        verbose,
+        operationalMode,
+        userAccountId,
+        customSystemMessagePreamble:
+          customSystemMessagePreamble || SYSTEM_MESSAGE,
+        ...(customSystemMessagePostamble !== undefined && {
+          customSystemMessagePostamble,
+        }),
+        ...(scheduleUserTransactionsInBytesMode !== undefined && {
+          scheduleUserTransactionsInBytesMode,
+        }),
+        ...(mirrorNodeConfig !== undefined && { mirrorNodeConfig }),
+        ...(disableLogging !== undefined && { disableLogging }),
+      };
+
+      this.conversationalAgent = new HederaConversationalAgent(
+        serverSigner,
+        agentConfig
+      );
+
+      await this.conversationalAgent.initialize();
+    } catch (error) {
+      this.logger.error('Failed to initialize ConversationalAgent:', error);
+      throw error;
+    }
+  }
+
+  getPlugin(): HCS10Plugin {
+    return this.hcs10Plugin;
+  }
+
+  getStateManager(): IStateManager {
+    return this.stateManager;
+  }
+
+  getConversationalAgent(): HederaConversationalAgent {
+    if (!this.conversationalAgent) {
+      throw new Error(
+        'ConversationalAgent not initialized. Call initialize() first.'
+      );
+    }
+    return this.conversationalAgent;
+  }
+
+  async processMessage(
+    message: string,
+    chatHistory: {
+      type: 'human' | 'ai';
+      content: string;
+    }[] = []
+  ): Promise<AgentResponse> {
+    if (!this.conversationalAgent) {
+      throw new Error(
+        'ConversationalAgent not initialized. Call initialize() first.'
+      );
+    }
+    return this.conversationalAgent.processMessage(message, chatHistory);
+  }
+
+  /**
+   * Create a ConversationalAgent with only HTS (Hedera Token Service) tools enabled
+   */
+  static withHTS(options: ConversationalAgentOptions): ConversationalAgent {
+    return new ConversationalAgent({
+      ...options,
+      enabledPlugins: ['hts-token'],
+    });
+  }
+
+  /**
+   * Create a ConversationalAgent with only HCS-2 tools enabled
+   */
+  static withHCS2(options: ConversationalAgentOptions): ConversationalAgent {
+    return new ConversationalAgent({
+      ...options,
+      enabledPlugins: ['hcs-2'],
+    });
+  }
+
+  /**
+   * Create a ConversationalAgent with only HCS-10 tools enabled
+   */
+  static withHCS10(options: ConversationalAgentOptions): ConversationalAgent {
+    return new ConversationalAgent({
+      ...options,
+      enabledPlugins: ['hcs-10'],
+    });
+  }
+
+  /**
+   * Create a ConversationalAgent with only inscription tools enabled
+   */
+  static withInscribe(
+    options: ConversationalAgentOptions
+  ): ConversationalAgent {
+    return new ConversationalAgent({
+      ...options,
+      enabledPlugins: ['inscribe'],
+    });
+  }
+
+  /**
+   * Create a ConversationalAgent with only account management tools enabled
+   */
+  static withAccount(options: ConversationalAgentOptions): ConversationalAgent {
+    return new ConversationalAgent({
+      ...options,
+      enabledPlugins: ['account'],
+    });
+  }
+
+  /**
+   * Create a ConversationalAgent with only file service tools enabled
+   */
+  static withFileService(
+    options: ConversationalAgentOptions
+  ): ConversationalAgent {
+    return new ConversationalAgent({
+      ...options,
+      enabledPlugins: ['file-service'],
+    });
+  }
+
+  /**
+   * Create a ConversationalAgent with only consensus service tools enabled
+   */
+  static withConsensusService(
+    options: ConversationalAgentOptions
+  ): ConversationalAgent {
+    return new ConversationalAgent({
+      ...options,
+      enabledPlugins: ['consensus-service'],
+    });
+  }
+
+  /**
+   * Create a ConversationalAgent with only smart contract tools enabled
+   */
+  static withSmartContract(
+    options: ConversationalAgentOptions
+  ): ConversationalAgent {
+    return new ConversationalAgent({
+      ...options,
+      enabledPlugins: ['smart-contract'],
+    });
+  }
+
+  /**
+   * Create a ConversationalAgent with all HCS standards plugins
+   */
+  static withAllStandards(
+    options: ConversationalAgentOptions
+  ): ConversationalAgent {
+    return new ConversationalAgent({
+      ...options,
+      enabledPlugins: ['hcs-10', 'hcs-2', 'inscribe'],
+    });
+  }
+
+  /**
+   * Create a ConversationalAgent with minimal Hedera tools (no HCS standards)
+   */
+  static minimal(options: ConversationalAgentOptions): ConversationalAgent {
+    return new ConversationalAgent({
+      ...options,
+      enabledPlugins: [],
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { HCS10Plugin } from './plugins/hcs-10/HCS10Plugin';
+export { HCS2Plugin } from './plugins/hcs-2/HCS2Plugin';
+export { InscribePlugin } from './plugins/inscribe/InscribePlugin';
+export { ConversationalAgent } from './conversational-agent';
+export type { ConversationalAgentOptions } from './conversational-agent';
+
+export * from 'hedera-agent-kit';
+
+export type { IStateManager } from '@hashgraphonline/standards-agent-kit';

package/src/plugins/hcs-10/HCS10Plugin.ts

@@ -0,0 +1,152 @@
+import {
+  GenericPluginContext,
+  HederaTool,
+  BasePlugin,
+  HederaAgentKit,
+} from 'hedera-agent-kit';
+import {
+  IStateManager,
+  OpenConvaiState,
+  HCS10Builder,
+  RegisterAgentTool,
+  FindRegistrationsTool,
+  InitiateConnectionTool,
+  ListConnectionsTool,
+  SendMessageToConnectionTool,
+  CheckMessagesTool,
+  ConnectionMonitorTool,
+  ManageConnectionRequestsTool,
+  AcceptConnectionRequestTool,
+  RetrieveProfileTool,
+  ListUnapprovedConnectionRequestsTool,
+} from '@hashgraphonline/standards-agent-kit';
+
+export class HCS10Plugin extends BasePlugin {
+  id = 'hcs-10';
+  name = 'HCS-10 Plugin';
+  description =
+    'HCS-10 agent tools for decentralized agent registration, connections, and messaging on Hedera';
+  version = '1.0.0';
+  author = 'Hashgraph Online';
+  namespace = 'hcs10';
+
+  private stateManager?: IStateManager;
+  private tools: HederaTool[] = [];
+
+  override async initialize(context: GenericPluginContext): Promise<void> {
+    await super.initialize(context);
+
+    const hederaKit = context.config.hederaKit as HederaAgentKit;
+    if (!hederaKit) {
+      this.context.logger.warn(
+        'HederaKit not found in context. HCS-10 tools will not be available.'
+      );
+      return;
+    }
+
+    try {
+      this.stateManager =
+        (context.stateManager as IStateManager) || new OpenConvaiState();
+
+      this.initializeTools();
+
+      this.context.logger.info(
+        'HCS-10 Plugin initialized successfully'
+      );
+    } catch (error) {
+      this.context.logger.error(
+        'Failed to initialize HCS-10 plugin:',
+        error
+      );
+    }
+  }
+
+  private initializeTools(): void {
+    if (!this.stateManager) {
+      throw new Error('StateManager must be initialized before creating tools');
+    }
+
+    const hederaKit = this.context.config.hederaKit as HederaAgentKit;
+    if (!hederaKit) {
+      throw new Error('HederaKit not found in context config');
+    }
+
+    const hcs10Builder = new HCS10Builder(hederaKit, this.stateManager);
+
+    this.tools = [
+      new RegisterAgentTool({
+        hederaKit: hederaKit,
+        hcs10Builder: hcs10Builder,
+        logger: this.context.logger,
+      }),
+      new FindRegistrationsTool({
+        hederaKit: hederaKit,
+        hcs10Builder: hcs10Builder,
+        logger: this.context.logger,
+      }),
+      new RetrieveProfileTool({
+        hederaKit: hederaKit,
+        hcs10Builder: hcs10Builder,
+        logger: this.context.logger,
+      }),
+      new InitiateConnectionTool({
+        hederaKit: hederaKit,
+        hcs10Builder: hcs10Builder,
+        logger: this.context.logger,
+      }),
+      new ListConnectionsTool({
+        hederaKit: hederaKit,
+        hcs10Builder: hcs10Builder,
+        logger: this.context.logger,
+      }),
+      new SendMessageToConnectionTool({
+        hederaKit: hederaKit,
+        hcs10Builder: hcs10Builder,
+        logger: this.context.logger,
+      }),
+      new CheckMessagesTool({
+        hederaKit: hederaKit,
+        hcs10Builder: hcs10Builder,
+        logger: this.context.logger,
+      }),
+      new ConnectionMonitorTool({
+        hederaKit: hederaKit,
+        hcs10Builder: hcs10Builder,
+        logger: this.context.logger,
+      }),
+      new ManageConnectionRequestsTool({
+        hederaKit: hederaKit,
+        hcs10Builder: hcs10Builder,
+        logger: this.context.logger,
+      }),
+      new AcceptConnectionRequestTool({
+        hederaKit: hederaKit,
+        hcs10Builder: hcs10Builder,
+        logger: this.context.logger,
+      }),
+      new ListUnapprovedConnectionRequestsTool({
+        hederaKit: hederaKit,
+        hcs10Builder: hcs10Builder,
+        logger: this.context.logger,
+      }),
+    ];
+  }
+
+  getTools(): HederaTool[] {
+    return this.tools;
+  }
+
+  getStateManager(): IStateManager | undefined {
+    return this.stateManager;
+  }
+
+  override async cleanup(): Promise<void> {
+    this.tools = [];
+    delete this.stateManager;
+    if (this.context?.logger) {
+      this.context.logger.info(
+        'HCS-10 Plugin cleaned up'
+      );
+    }
+  }
+}

package/src/plugins/hcs-10/index.ts

@@ -0,0 +1 @@
+export { HCS10Plugin } from './HCS10Plugin';

package/src/plugins/hcs-2/HCS2Plugin.ts

@@ -0,0 +1,108 @@
+import {
+  GenericPluginContext,
+  HederaTool,
+  BasePlugin,
+  HederaAgentKit,
+} from 'hedera-agent-kit';
+import {
+  HCS2Builder,
+  CreateRegistryTool,
+  RegisterEntryTool,
+  UpdateEntryTool,
+  DeleteEntryTool,
+  MigrateRegistryTool,
+  QueryRegistryTool,
+} from '@hashgraphonline/standards-agent-kit';
+
+/**
+ * Plugin providing HCS-2 registry management tools
+ */
+export class HCS2Plugin extends BasePlugin {
+  id = 'hcs-2';
+  name = 'HCS-2 Plugin';
+  description =
+    'HCS-2 registry management tools for decentralized registries on Hedera';
+  version = '1.0.0';
+  author = 'Hashgraph Online';
+  namespace = 'hcs2';
+
+  private tools: HederaTool[] = [];
+
+  override async initialize(context: GenericPluginContext): Promise<void> {
+    await super.initialize(context);
+
+    const hederaKit = context.config.hederaKit as HederaAgentKit;
+    if (!hederaKit) {
+      this.context.logger.warn(
+        'HederaKit not found in context. HCS-2 tools will not be available.'
+      );
+      return;
+    }
+
+    try {
+      this.initializeTools();
+
+      this.context.logger.info(
+        'HCS-2 Plugin initialized successfully'
+      );
+    } catch (error) {
+      this.context.logger.error(
+        'Failed to initialize HCS-2 plugin:',
+        error
+      );
+    }
+  }
+
+  private initializeTools(): void {
+    const hederaKit = this.context.config.hederaKit as HederaAgentKit;
+    if (!hederaKit) {
+      throw new Error('HederaKit not found in context config');
+    }
+
+    const hcs2Builder = new HCS2Builder(hederaKit);
+
+    this.tools = [
+      new CreateRegistryTool({
+        hederaKit: hederaKit,
+        hcs2Builder: hcs2Builder,
+        logger: this.context.logger,
+      }),
+      new RegisterEntryTool({
+        hederaKit: hederaKit,
+        hcs2Builder: hcs2Builder,
+        logger: this.context.logger,
+      }),
+      new UpdateEntryTool({
+        hederaKit: hederaKit,
+        hcs2Builder: hcs2Builder,
+        logger: this.context.logger,
+      }),
+      new DeleteEntryTool({
+        hederaKit: hederaKit,
+        hcs2Builder: hcs2Builder,
+        logger: this.context.logger,
+      }),
+      new MigrateRegistryTool({
+        hederaKit: hederaKit,
+        hcs2Builder: hcs2Builder,
+        logger: this.context.logger,
+      }),
+      new QueryRegistryTool({
+        hederaKit: hederaKit,
+        hcs2Builder: hcs2Builder,
+        logger: this.context.logger,
+      }),
+    ];
+  }
+
+  getTools(): HederaTool[] {
+    return this.tools;
+  }
+
+  override async cleanup(): Promise<void> {
+    this.tools = [];
+    if (this.context?.logger) {
+      this.context.logger.info('HCS-2 Plugin cleaned up');
+    }
+  }
+}

package/src/plugins/hcs-2/index.ts

@@ -0,0 +1 @@
+export { HCS2Plugin } from './HCS2Plugin';

package/src/plugins/index.ts

@@ -0,0 +1,3 @@
+export { HCS10Plugin } from './hcs-10';
+export { HCS2Plugin } from './hcs-2';
+export { InscribePlugin } from './inscribe';

package/src/plugins/inscribe/InscribePlugin.ts

@@ -0,0 +1,102 @@
+import {
+  GenericPluginContext,
+  HederaTool,
+  BasePlugin,
+  HederaAgentKit,
+} from 'hedera-agent-kit';
+import {
+  InscriberBuilder,
+  InscribeFromUrlTool,
+  InscribeFromFileTool,
+  InscribeFromBufferTool,
+  InscribeHashinalTool,
+  RetrieveInscriptionTool,
+} from '@hashgraphonline/standards-agent-kit';
+
+/**
+ * Plugin providing content inscription tools for Hedera
+ */
+export class InscribePlugin extends BasePlugin {
+  id = 'inscribe';
+  name = 'Inscribe Plugin';
+  description =
+    'Content inscription tools for storing data on Hedera Consensus Service';
+  version = '1.0.0';
+  author = 'Hashgraph Online';
+  namespace = 'inscribe';
+
+  private tools: HederaTool[] = [];
+
+  override async initialize(context: GenericPluginContext): Promise<void> {
+    await super.initialize(context);
+
+    const hederaKit = context.config.hederaKit as HederaAgentKit;
+    if (!hederaKit) {
+      this.context.logger.warn(
+        'HederaKit not found in context. Inscription tools will not be available.'
+      );
+      return;
+    }
+
+    try {
+      this.initializeTools();
+
+      this.context.logger.info(
+        'Inscribe Plugin initialized successfully'
+      );
+    } catch (error) {
+      this.context.logger.error(
+        'Failed to initialize Inscribe plugin:',
+        error
+      );
+    }
+  }
+
+  private initializeTools(): void {
+    const hederaKit = this.context.config.hederaKit as HederaAgentKit;
+    if (!hederaKit) {
+      throw new Error('HederaKit not found in context config');
+    }
+
+    const inscriberBuilder = new InscriberBuilder(hederaKit);
+
+    this.tools = [
+      new InscribeFromUrlTool({
+        hederaKit: hederaKit,
+        inscriberBuilder: inscriberBuilder,
+        logger: this.context.logger,
+      }),
+      new InscribeFromFileTool({
+        hederaKit: hederaKit,
+        inscriberBuilder: inscriberBuilder,
+        logger: this.context.logger,
+      }),
+      new InscribeFromBufferTool({
+        hederaKit: hederaKit,
+        inscriberBuilder: inscriberBuilder,
+        logger: this.context.logger,
+      }),
+      new InscribeHashinalTool({
+        hederaKit: hederaKit,
+        inscriberBuilder: inscriberBuilder,
+        logger: this.context.logger,
+      }),
+      new RetrieveInscriptionTool({
+        hederaKit: hederaKit,
+        inscriberBuilder: inscriberBuilder,
+        logger: this.context.logger,
+      }),
+    ];
+  }
+
+  getTools(): HederaTool[] {
+    return this.tools;
+  }
+
+  override async cleanup(): Promise<void> {
+    this.tools = [];
+    if (this.context?.logger) {
+      this.context.logger.info('Inscribe Plugin cleaned up');
+    }
+  }
+}

package/src/plugins/inscribe/index.ts

@@ -0,0 +1 @@
+export { InscribePlugin } from './InscribePlugin';