@hashgraphonline/conversational-agent 0.2.0 → 0.2.101

package/src/services/attachment-processor.ts

@@ -0,0 +1,163 @@
+import { Logger } from '@hashgraphonline/standards-sdk';
+import type { ContentStoreManager as PackageContentStoreManager } from './content-store-manager';
+
+export interface AttachmentData {
+  name: string;
+  data: string;
+  type: string;
+  size: number;
+}
+
+type ContentStoreManager = PackageContentStoreManager;
+
+/**
+ * Utility for processing file attachments and content references
+ */
+export class AttachmentProcessor {
+  private logger: Logger;
+
+  constructor() {
+    this.logger = new Logger({ module: 'AttachmentProcessor' });
+  }
+
+  /**
+   * Process attachments and create content references
+   */
+  async processAttachments(
+    content: string,
+    attachments: AttachmentData[],
+    contentStoreManager?: ContentStoreManager
+  ): Promise<string> {
+    if (attachments.length === 0) {
+      return content;
+    }
+
+    this.logger.info('Processing attachments with content reference system:', {
+      attachmentCount: attachments.length,
+      totalSize: attachments.reduce((sum, att) => sum + att.size, 0),
+    });
+
+    if (contentStoreManager && contentStoreManager.isInitialized()) {
+      return this.processWithContentStore(content, attachments, contentStoreManager);
+    } else {
+      this.logger.warn('Content storage not available, creating simple file references');
+      return this.processWithSimpleReferences(content, attachments);
+    }
+  }
+
+  /**
+   * Process attachments using content store manager
+   */
+  private async processWithContentStore(
+    content: string,
+    attachments: AttachmentData[],
+    contentStoreManager: ContentStoreManager
+  ): Promise<string> {
+    const contentReferences: string[] = [];
+
+    for (const attachment of attachments) {
+      try {
+        const base64Data = attachment.data.includes('base64,')
+          ? attachment.data.split('base64,')[1]
+          : attachment.data;
+        const buffer = Buffer.from(base64Data, 'base64');
+
+        const contentRef = await contentStoreManager.storeContentIfLarge(
+          buffer,
+          {
+            mimeType: attachment.type,
+            source: 'user_upload',
+            fileName: attachment.name,
+            tags: ['attachment', 'user_file'],
+          }
+        );
+
+        if (contentRef) {
+          if (attachment.type.startsWith('image/')) {
+            contentReferences.push(
+              `[Image File: ${attachment.name}] (content-ref:${contentRef.referenceId})`
+            );
+          } else {
+            contentReferences.push(
+              `[File: ${attachment.name}] (content-ref:${contentRef.referenceId})`
+            );
+          }
+        } else {
+          contentReferences.push(
+            this.createInlineReference(attachment, base64Data)
+          );
+        }
+      } catch (error) {
+        this.logger.error('Failed to process attachment:', {
+          fileName: attachment.name,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        });
+        contentReferences.push(
+          `[File: ${attachment.name} - Error processing file: ${
+            error instanceof Error ? error.message : 'Unknown error'
+          }]`
+        );
+      }
+    }
+
+    const fileList = this.createFileList(attachments);
+    return content
+      ? `${content}\n\nAttached files:\n${fileList}\n\n${contentReferences.join('\n')}`
+      : `Attached files:\n${fileList}\n\n${contentReferences.join('\n')}`;
+  }
+
+  /**
+   * Process attachments with simple file references
+   */
+  private processWithSimpleReferences(content: string, attachments: AttachmentData[]): string {
+    const fileReferences = attachments.map((attachment) => {
+      const sizeStr = this.formatFileSize(attachment.size);
+
+      if (attachment.type.startsWith('image/')) {
+        return `📎 Image: ${attachment.name} (${sizeStr}, ${attachment.type})`;
+      } else {
+        return `📎 File: ${attachment.name} (${sizeStr}, ${attachment.type})`;
+      }
+    });
+
+    return content
+      ? `${content}\n\nAttached files:\n${fileReferences.join('\n')}`
+      : `Attached files:\n${fileReferences.join('\n')}`;
+  }
+
+  /**
+   * Create inline reference for small files
+   */
+  private createInlineReference(attachment: AttachmentData, base64Data: string): string {
+    if (attachment.size < 50000) {
+      if (attachment.type.startsWith('image/')) {
+        return `![${attachment.name}](data:${attachment.type};base64,${base64Data})`;
+      } else {
+        return `[File: ${attachment.name} (${this.formatFileSize(attachment.size)})]\nContent: ${base64Data}`;
+      }
+    } else {
+      return `[File: ${attachment.name} (${this.formatFileSize(attachment.size)}) - Content too large to include inline]`;
+    }
+  }
+
+  /**
+   * Create formatted file list
+   */
+  private createFileList(attachments: AttachmentData[]): string {
+    return attachments
+      .map((file) => {
+        const sizeStr = this.formatFileSize(file.size);
+        return `📎 ${file.name} (${sizeStr})`;
+      })
+      .join('\n');
+  }
+
+  /**
+   * Format file size for display
+   */
+  private formatFileSize(size: number): string {
+    return size >= 1024 * 1024
+      ? `${(size / (1024 * 1024)).toFixed(1)}MB`
+      : `${(size / 1024).toFixed(1)}KB`;
+  }
+}

package/src/services/content-store-manager.ts

@@ -165,8 +165,26 @@ export class ContentStoreManager {
     }
 
     try {
-      await ContentStoreService.setInstance(this.adapter);
-      ContentResolverRegistry.register(this.resolver);
+      if (
+        ContentStoreService &&
+        typeof (ContentStoreService as unknown as { setInstance?: Function }).setInstance === 'function'
+      ) {
+        await (ContentStoreService as unknown as { setInstance: (adapter: unknown) => Promise<void> }).setInstance(
+          this.adapter
+        );
+      } else {
+        this.logger.warn('ContentStoreService.setInstance is unavailable; skipping registration');
+      }
+      if (
+        ContentResolverRegistry &&
+        typeof (ContentResolverRegistry as unknown as { register?: Function }).register === 'function'
+      ) {
+        (ContentResolverRegistry as unknown as { register: (resolver: unknown) => void }).register(
+          this.resolver
+        );
+      } else {
+        this.logger.warn('ContentResolverRegistry.register is unavailable; skipping registration');
+      }
       this.isRegistered = true;
       this.logger.info(
         'ContentStoreManager initialized and registered for cross-package access'
@@ -236,8 +254,18 @@ export class ContentStoreManager {
   async dispose(): Promise<void> {
     if (this.isRegistered) {
       this.contentStorage.dispose();
-      ContentStoreService.dispose();
-      ContentResolverRegistry.unregister();
+      if (
+        ContentStoreService &&
+        typeof (ContentStoreService as unknown as { dispose?: Function }).dispose === 'function'
+      ) {
+        (ContentStoreService as unknown as { dispose: () => void }).dispose();
+      }
+      if (
+        ContentResolverRegistry &&
+        typeof (ContentResolverRegistry as unknown as { unregister?: Function }).unregister === 'function'
+      ) {
+        (ContentResolverRegistry as unknown as { unregister: () => void }).unregister();
+      }
       this.isRegistered = false;
       this.logger.info('ContentStoreManager disposed and unregistered');
     }

package/src/services/index.ts

@@ -1,3 +1,5 @@
 export * from './entity-resolver';
 export * from './content-store-manager';
 export * from './formatters';
+export * from './parameter-service';
+export * from './attachment-processor';

package/src/services/parameter-service.ts

@@ -0,0 +1,430 @@
+import { Logger, type NetworkType } from '@hashgraphonline/standards-sdk';
+import { EntityFormat, FormatConverterRegistry } from './formatters';
+import type { EntityAssociation } from '../memory/smart-memory-manager';
+
+/**
+ * Service for processing tool parameters and applying entity format conversions
+ */
+export class ParameterService {
+  private logger: Logger;
+  private formatConverterRegistry: FormatConverterRegistry;
+  private networkType: NetworkType;
+
+  constructor(
+    formatConverterRegistry: FormatConverterRegistry,
+    networkType: NetworkType
+  ) {
+    this.logger = new Logger({ module: 'ParameterService' });
+    this.formatConverterRegistry = formatConverterRegistry;
+    this.networkType = networkType;
+  }
+
+  /**
+   * Unified preprocessing entrypoint (DRY):
+   * - Optional AI-driven resolution via provided entityResolver
+   * - Deterministic post-pass for safe format enforcement
+   */
+  async preprocessParameters(
+    toolName: string,
+    parameters: Record<string, unknown>,
+    entities: EntityAssociation[] = [],
+    options?: {
+      entityResolver?: {
+        resolveReferences: (
+          message: string,
+          entities: EntityAssociation[]
+        ) => Promise<string>;
+      };
+      sessionId?: string;
+      preferences?: Record<string, string>;
+    }
+  ): Promise<Record<string, unknown>> {
+    const sessionId = options?.sessionId;
+    const entityResolver = options?.entityResolver;
+    const preferences = options?.preferences;
+
+    let working: Record<string, unknown> = { ...parameters };
+
+    if (entityResolver && entities.length > 0) {
+      try {
+        this.logger.info('AI-driven preprocessing phase', {
+          toolName,
+          entityCount: entities.length,
+          sessionId,
+        });
+
+        const aiProcessed: Record<string, unknown> = { ...working };
+        for (const [paramName, paramValue] of Object.entries(working)) {
+          if (typeof paramValue === 'string') {
+            const resolved = await entityResolver.resolveReferences(
+              paramValue,
+              entities
+            );
+            const converted = await this.convertParameterEntities(
+              resolved,
+              entities,
+              preferences
+            );
+            aiProcessed[paramName] = converted;
+          } else if (Array.isArray(paramValue)) {
+            const out: unknown[] = [];
+            for (const item of paramValue) {
+              if (typeof item === 'string') {
+                const resolved = await entityResolver.resolveReferences(
+                  item,
+                  entities
+                );
+                const converted = await this.convertParameterEntities(
+                  resolved,
+                  entities,
+                  preferences
+                );
+                out.push(converted);
+              } else {
+                out.push(item);
+              }
+            }
+            aiProcessed[paramName] = out;
+          }
+        }
+        working = aiProcessed;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'unknown';
+        this.logger.warn(
+          'AI phase failed; continuing with deterministic pass',
+          {
+            toolName,
+            error: message,
+          }
+        );
+      }
+    }
+
+    try {
+      const processed: Record<string, unknown> = { ...working };
+      for (const [paramName, paramValue] of Object.entries(working)) {
+        if (typeof paramValue === 'string') {
+          const converted = await this.convertParameterEntities(
+            paramValue,
+            entities,
+            preferences
+          );
+          processed[paramName] = converted;
+        } else if (Array.isArray(paramValue)) {
+          const out: unknown[] = [];
+          for (const item of paramValue) {
+            if (typeof item === 'string') {
+              const converted = await this.convertParameterEntities(
+                item,
+                entities,
+                preferences
+              );
+              out.push(converted);
+            } else {
+              out.push(item);
+            }
+          }
+          processed[paramName] = out;
+        }
+      }
+      working = processed;
+    } catch (e) {
+      this.logger.warn('Deterministic post-pass failed', {
+        toolName,
+        error: e instanceof Error ? e.message : 'unknown',
+      });
+    }
+
+    return working;
+  }
+
+  /**
+   * Attach unified preprocessing callback directly to the agent.
+   */
+  attachToAgent(
+    agent: unknown,
+    deps?: {
+      getSessionId?: () => string | null;
+      getEntities?: (sessionId: string | null) => Promise<EntityAssociation[]>;
+      entityResolver?: {
+        resolveReferences: (
+          message: string,
+          entities: EntityAssociation[]
+        ) => Promise<string>;
+      };
+    }
+  ): void {
+    const getSessionId = deps?.getSessionId ?? (() => null);
+    const getEntities =
+      deps?.getEntities ?? (async () => [] as EntityAssociation[]);
+    const entityResolver = deps?.entityResolver;
+
+    const maybe = agent as {
+      setParameterPreprocessingCallback?: (
+        callback: (
+          toolName: string,
+          parameters: Record<string, unknown>,
+          toolContext?: {
+            entityResolutionPreferences?: Record<string, string>;
+          }
+        ) => Promise<Record<string, unknown>>
+      ) => void;
+      getAgent?: () => unknown;
+    };
+
+    const attach = (target: unknown): boolean => {
+      const t = target as {
+        setParameterPreprocessingCallback?: (
+          callback: (
+            toolName: string,
+            parameters: Record<string, unknown>,
+            toolContext?: {
+              entityResolutionPreferences?: Record<string, string>;
+            }
+          ) => Promise<Record<string, unknown>>
+        ) => void;
+      };
+      if (typeof t.setParameterPreprocessingCallback === 'function') {
+        t.setParameterPreprocessingCallback(
+          async (
+            toolName: string,
+            parameters: Record<string, unknown>
+          ): Promise<Record<string, unknown>> => {
+            const sessionId = getSessionId();
+            const entities = await getEntities(sessionId);
+            const opts: {
+              entityResolver?: {
+                resolveReferences: (
+                  message: string,
+                  entities: EntityAssociation[]
+                ) => Promise<string>;
+              };
+              sessionId?: string;
+              preferences?: Record<string, string>;
+            } = {};
+            if (entityResolver) {
+              opts.entityResolver = entityResolver;
+            }
+            if (sessionId) {
+              opts.sessionId = sessionId;
+            }
+            return this.preprocessParameters(toolName, parameters, entities, opts);
+          }
+        );
+        this.logger.info('Parameter preprocessing callback attached');
+        return true;
+      }
+      return false;
+    };
+
+    if (!attach(agent) && typeof maybe.getAgent === 'function') {
+      const underlying = maybe.getAgent();
+      if (underlying) {
+        void attach(underlying);
+      }
+    }
+  }
+
+  /**
+   * Preprocess tool parameters by applying format conversions based on tool's entity resolution preferences
+   */
+  async preprocessToolParameters(
+    toolName: string,
+    parameters: Record<string, unknown>,
+    entities?: EntityAssociation[],
+    sessionId?: string
+  ): Promise<Record<string, unknown>> {
+    try {
+      if (!entities || entities.length === 0) {
+        this.logger.info(
+          'Tool parameter preprocessing skipped - no entities provided:',
+          {
+            toolName,
+            originalParams: Object.keys(parameters),
+          }
+        );
+        return parameters;
+      }
+
+      const processedParameters = { ...parameters };
+      const preferences: Record<string, string> | undefined = undefined;
+      let hasChanges = false;
+
+      for (const [paramName, paramValue] of Object.entries(parameters)) {
+        if (typeof paramValue === 'string') {
+          const convertedValue = await this.convertParameterEntities(
+            paramValue,
+            entities,
+            preferences
+          );
+
+          if (convertedValue !== paramValue) {
+            processedParameters[paramName] = convertedValue;
+            hasChanges = true;
+
+            this.logger.info('Parameter entity conversion applied:', {
+              toolName,
+              paramName,
+              original: paramValue,
+              converted: convertedValue,
+            });
+          }
+        } else if (Array.isArray(paramValue)) {
+          const originalArray = paramValue as unknown[];
+          const convertedArray: unknown[] = [];
+          let arrayChanged = false;
+
+          for (const item of originalArray) {
+            if (typeof item === 'string') {
+              const convertedItem = await this.convertParameterEntities(
+                item,
+                entities,
+                preferences
+              );
+
+              convertedArray.push(convertedItem);
+
+              if (convertedItem !== item) {
+                arrayChanged = true;
+                this.logger.info('Parameter array item conversion applied:', {
+                  toolName,
+                  paramName,
+                  original: item,
+                  converted: convertedItem,
+                });
+              }
+            } else {
+              convertedArray.push(item);
+            }
+          }
+
+          if (arrayChanged) {
+            processedParameters[paramName] = convertedArray;
+            hasChanges = true;
+          }
+        }
+      }
+
+      this.logger.info('Tool parameter preprocessing completed:', {
+        toolName,
+        originalParams: Object.keys(parameters),
+        hasChanges,
+        sessionId,
+      });
+
+      return processedParameters;
+    } catch (error) {
+      this.logger.warn('Tool parameter preprocessing failed:', {
+        toolName,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      });
+      return parameters;
+    }
+  }
+
+  /**
+   * Convert entity references in a parameter value based on tool preferences
+   */
+  async convertParameterEntities(
+    parameterValue: string,
+    entities: EntityAssociation[],
+    preferences?: Record<string, string>
+  ): Promise<string> {
+    let convertedValue = parameterValue;
+
+    for (const entity of entities) {
+      const containsEntityId = convertedValue.includes(entity.entityId);
+      const containsEntityName = convertedValue.includes(entity.entityName);
+
+      if (!containsEntityId && !containsEntityName) {
+        continue;
+      }
+
+      let targetFormat: EntityFormat | null = null;
+
+      if (entity.entityType === EntityFormat.TOPIC_ID) {
+        if (
+          preferences?.inscription === 'hrl' ||
+          preferences?.topic === 'hrl'
+        ) {
+          targetFormat = EntityFormat.HRL;
+        } else if (
+          preferences?.inscription === 'topicId' ||
+          preferences?.topic === 'topicId'
+        ) {
+          targetFormat = EntityFormat.TOPIC_ID;
+        }
+      } else if (entity.entityType === EntityFormat.TOKEN_ID) {
+        if (preferences?.token === 'tokenId') {
+          targetFormat = EntityFormat.TOKEN_ID;
+        } else if (preferences?.token === 'symbol') {
+          targetFormat = EntityFormat.SYMBOL;
+        }
+      } else if (entity.entityType === EntityFormat.ACCOUNT_ID) {
+        if (
+          preferences?.account === 'accountId' ||
+          preferences?.supplyKey === 'accountId' ||
+          preferences?.adminKey === 'accountId'
+        ) {
+          targetFormat = EntityFormat.ACCOUNT_ID;
+        } else if (preferences?.account === 'alias') {
+          targetFormat = EntityFormat.ALIAS;
+        }
+      }
+
+      if (targetFormat) {
+        try {
+          const context: {
+            networkType?: string | NetworkType;
+            sessionId?: string;
+            toolPreferences?: Record<string, string>;
+          } = {
+            networkType: this.networkType,
+            sessionId: 'unknown',
+          };
+          if (preferences) {
+            context.toolPreferences = preferences;
+          }
+          const convertedEntityValue = await this.formatConverterRegistry.convertEntity(
+            entity.entityId,
+            targetFormat,
+            context as never
+          );
+
+          if (containsEntityId) {
+            convertedValue = convertedValue.replace(
+              new RegExp(`\\b${entity.entityId.replace(/\./g, '\\.')}\\b`, 'g'),
+              convertedEntityValue
+            );
+          }
+
+          if (containsEntityName) {
+            convertedValue = convertedValue.replace(
+              new RegExp(
+                `\\b${entity.entityName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`,
+                'g'
+              ),
+              convertedEntityValue
+            );
+          }
+
+          this.logger.info('Applied format conversion to parameter:', {
+            entityId: entity.entityId,
+            entityType: entity.entityType,
+            targetFormat,
+            convertedValue: convertedEntityValue,
+            parameterValue: convertedValue,
+          });
+        } catch (error) {
+          this.logger.warn('Format conversion failed for parameter:', {
+            entityId: entity.entityId,
+            targetFormat,
+            error: error instanceof Error ? error.message : 'Unknown error',
+          });
+        }
+      }
+    }
+
+    return convertedValue;
+  }
+}