@hashgraphonline/conversational-agent 0.1.217 → 0.1.218

package/dist/types/context/ReferenceContextManager.d.ts

@@ -1,84 +0,0 @@
-import { ContentReference, ReferenceId } from '../types/content-reference';
-import { ContentStorage } from '../memory/ContentStorage';
-import { Logger } from '@hashgraphonline/standards-sdk';
-
-export interface ReferenceContext {
-    reference: ContentReference;
-    displayedAt: Date;
-    lastAccessedAt: Date;
-    contextId: string;
-    conversationTurn: number;
-}
-export interface ReferenceDisplayOptions {
-    maxPreviewLength?: number;
-    showMetadata?: boolean;
-    showSize?: boolean;
-    includeActions?: boolean;
-    format?: 'inline' | 'card' | 'compact';
-}
-export interface DisplayResult {
-    displayText: string;
-    hasValidReference: boolean;
-    contextId?: string;
-    suggestedActions?: string[];
-}
-/**
- * Manages content references within agent conversation context
- * Tracks reference usage, provides display formatting, and handles reference validation
- */
-export declare class ReferenceContextManager {
-    private activeReferences;
-    private contentStorage;
-    private logger;
-    private conversationTurn;
-    constructor(contentStorage: ContentStorage, logger: Logger);
-    /**
-     * Add a reference to the current conversation context
-     */
-    addReference(reference: ContentReference): string;
-    /**
-     * Generate display text for a content reference
-     */
-    displayReference(reference: ContentReference, options?: ReferenceDisplayOptions): Promise<DisplayResult>;
-    /**
-     * Get the most recent reference for "inscribe it" commands
-     */
-    getMostRecentReference(): ContentReference | null;
-    /**
-     * Get reference by context ID
-     */
-    getReferenceByContextId(contextId: string): ContentReference | null;
-    /**
-     * Validate all active references and remove invalid ones
-     */
-    validateReferences(): Promise<{
-        valid: number;
-        invalid: number;
-        removed: ReferenceId[];
-    }>;
-    /**
-     * Clear old references based on age and usage
-     */
-    cleanupOldReferences(maxAgeMs?: number): number;
-    /**
-     * Get current context statistics
-     */
-    getContextStats(): {
-        activeReferences: number;
-        conversationTurn: number;
-        oldestReference: number | null;
-        mostRecentReference: number | null;
-    };
-    /**
-     * Clear all references from context
-     */
-    clear(): void;
-    private formatCardReference;
-    private formatInlineReference;
-    private formatCompactReference;
-    private formatInvalidReference;
-    private formatErrorReference;
-    private truncateText;
-    private getOldestReferenceAge;
-    private getMostRecentReferenceAge;
-}

package/dist/types/context/ReferenceResponseProcessor.d.ts

@@ -1,76 +0,0 @@
-import { ContentReference, ReferenceId } from '../types/content-reference';
-import { ReferenceContextManager, ReferenceDisplayOptions } from './ReferenceContextManager';
-import { Logger } from '@hashgraphonline/standards-sdk';
-
-export interface ResponseProcessingOptions {
-    autoDisplayReferences?: boolean;
-    displayOptions?: ReferenceDisplayOptions;
-    includeReferenceInstructions?: boolean;
-    contextualizeReferences?: boolean;
-}
-export interface ProcessedResponse {
-    content: string;
-    hasReferences: boolean;
-    referenceCount: number;
-    contextIds: string[];
-    suggestedActions: string[];
-}
-export interface ReferenceDetectionResult {
-    hasReferences: boolean;
-    references: Array<{
-        reference: ContentReference;
-        position: number;
-        originalText: string;
-    }>;
-    plainReferences: Array<{
-        referenceId: ReferenceId;
-        position: number;
-        originalText: string;
-    }>;
-}
-/**
- * Processes agent responses to detect and display content references
- * Handles both structured references and plain reference IDs
- */
-export declare class ReferenceResponseProcessor {
-    private contextManager;
-    private logger;
-    constructor(contextManager: ReferenceContextManager, logger: Logger);
-    /**
-     * Process an agent response to handle content references
-     */
-    processResponse(responseContent: string, options?: ResponseProcessingOptions): Promise<ProcessedResponse>;
-    /**
-     * Detect references in response content
-     */
-    private detectReferences;
-    /**
-     * Create a preview from content buffer
-     */
-    private createPreviewFromContent;
-    /**
-     * Validate reference ID format
-     */
-    private isValidReferenceId;
-    /**
-     * Get reference context statistics
-     */
-    getContextStats(): {
-        activeReferences: number;
-        conversationTurn: number;
-        oldestReference: number | null;
-        mostRecentReference: number | null;
-    };
-    /**
-     * Validate all references in context
-     */
-    validateAllReferences(): Promise<{
-        valid: number;
-        invalid: number;
-        removed: ReferenceId[];
-    }>;
-    /**
-     * Clean up old references
-     */
-    cleanupOldReferences(maxAgeMs?: number): number;
-}

package/dist/types/langchain/FormValidatingToolWrapper.d.ts

@@ -1,81 +0,0 @@
-import { StructuredTool } from '@langchain/core/tools';
-import { z } from 'zod';
-import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
-import { FormGenerator } from '../forms/form-generator';
-
-export interface FormValidationConfig {
-    requireAllFields?: boolean;
-    skipFields?: string[];
-    customValidation?: (input: unknown) => boolean;
-}
-/**
- * Generic wrapper for StructuredTools that intercepts execution to check for missing required fields
- * and generates forms when validation would benefit from user input.
- *
- * Tools can implement the FormValidatable interface to provide custom validation logic.
- * Otherwise, falls back to schema-based validation.
- */
-export declare class FormValidatingToolWrapper<TSchema extends z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny>> extends StructuredTool<TSchema> {
-    private originalTool;
-    private formGenerator;
-    private validationConfig;
-    private logger;
-    name: string;
-    description: string;
-    schema: TSchema;
-    constructor(originalTool: StructuredTool<TSchema>, formGenerator: FormGenerator, config?: FormValidationConfig);
-    /**
-     * Validate the input against the schema
-     */
-    private validateInput;
-    /**
-     * Gets the shape keys from the schema if it's a ZodObject
-     */
-    private getSchemaShape;
-    /**
-     * Executes the wrapped tool's original implementation directly, bypassing wrapper logic.
-     */
-    executeOriginal(input: Record<string, unknown>, runManager?: CallbackManagerForToolRun): Promise<string>;
-    /**
-     * Provides access to the wrapped tool instance for executors that want to bypass the wrapper.
-     */
-    getOriginalTool(): StructuredTool<TSchema>;
-    /**
-     * Checks if tool implements FormValidatable method
-     */
-    private hasFormValidatableMethod;
-    /**
-     * Expose FormValidatable methods by delegating to the underlying tool when available.
-     */
-    getFormSchema(): z.ZodSchema;
-    getEssentialFields(): string[];
-    isFieldEmpty(fieldName: string, value: unknown): boolean;
-    /**
-     * Calculates which fields are missing from the input
-     */
-    private calculateMissingFields;
-    /**
-     * Creates a form message with optional JSON schema
-     */
-    private createFormMessage;
-    /**
-     * Type guard to check if a schema is a ZodObject
-     */
-    private isZodObject;
-    /**
-     * Check if we should generate a form for this tool invocation
-     */
-    private shouldGenerateForm;
-    /**
-     * Checks if input has bypass flags that skip form generation
-     */
-    private hasFormBypassFlags;
-    /**
-     * Override _call to intercept tool execution
-     */
-    protected _call(input: z.infer<TSchema>, runManager?: CallbackManagerForToolRun): Promise<string>;
-}
-/**
- * Wrap a tool with form validation capabilities
- */
-export declare function wrapToolWithFormValidation<TSchema extends z.ZodObject<z.ZodRawShape, z.UnknownKeysParam, z.ZodTypeAny>>(tool: StructuredTool<TSchema>, formGenerator: FormGenerator, config?: FormValidationConfig): FormValidatingToolWrapper<TSchema>;

package/dist/types/services/EntityResolver.d.ts

@@ -1,26 +0,0 @@
-import { EntityAssociation } from '../memory/SmartMemoryManager';
-
-export interface EntityResolverConfig {
-    apiKey: string;
-    modelName?: string;
-}
-/**
- * LLM-based entity resolver that replaces brittle regex patterns
- */
-export declare class EntityResolver {
-    private llm;
-    constructor(config: EntityResolverConfig);
-    /**
-     * Resolve entity references using LLM instead of regex
-     */
-    resolveReferences(message: string, entities: EntityAssociation[]): Promise<string>;
-    /**
-     * Extract entities from agent response using LLM
-     */
-    extractEntities(response: unknown, userMessage: string): Promise<Array<{
-        id: string;
-        name: string;
-        type: string;
-        transactionId?: string;
-    }>>;
-}

package/src/context/ReferenceContextManager.ts

@@ -1,350 +0,0 @@
-import type { ContentReference, ReferenceId } from '../types/content-reference';
-import type { ContentStorage } from '../memory/ContentStorage';
-import { Logger } from '@hashgraphonline/standards-sdk';
-
-export interface ReferenceContext {
-  reference: ContentReference;
-  displayedAt: Date;
-  lastAccessedAt: Date;
-  contextId: string;
-  conversationTurn: number;
-}
-
-export interface ReferenceDisplayOptions {
-  maxPreviewLength?: number;
-  showMetadata?: boolean;
-  showSize?: boolean;
-  includeActions?: boolean;
-  format?: 'inline' | 'card' | 'compact';
-}
-
-export interface DisplayResult {
-  displayText: string;
-  hasValidReference: boolean;
-  contextId?: string;
-  suggestedActions?: string[];
-}
-
-/**
- * Manages content references within agent conversation context
- * Tracks reference usage, provides display formatting, and handles reference validation
- */
-export class ReferenceContextManager {
-  private activeReferences: Map<ReferenceId, ReferenceContext> = new Map();
-  private contentStorage: ContentStorage;
-  private logger: Logger;
-  private conversationTurn = 0;
-
-  constructor(contentStorage: ContentStorage, logger: Logger) {
-    this.contentStorage = contentStorage;
-    this.logger = logger;
-  }
-
-  /**
-   * Add a reference to the current conversation context
-   */
-  addReference(reference: ContentReference): string {
-    this.conversationTurn++;
-    const contextId = `ctx_${Date.now()}_${reference.referenceId.substring(0, 8)}`;
-    
-    const context: ReferenceContext = {
-      reference,
-      displayedAt: new Date(),
-      lastAccessedAt: new Date(),
-      contextId,
-      conversationTurn: this.conversationTurn
-    };
-
-    this.activeReferences.set(reference.referenceId, context);
-    
-    this.logger.debug(`Added reference to conversation context: ${reference.referenceId} (${contextId})`);
-    
-    return contextId;
-  }
-
-  /**
-   * Generate display text for a content reference
-   */
-  async displayReference(
-    reference: ContentReference,
-    options: ReferenceDisplayOptions = {}
-  ): Promise<DisplayResult> {
-    const {
-      maxPreviewLength = 150,
-      showMetadata = true,
-      showSize = true,
-      includeActions = true,
-      format = 'card'
-    } = options;
-
-    try {
-      const isValid = await this.contentStorage.hasReference(reference.referenceId);
-      if (!isValid) {
-        return {
-          displayText: this.formatInvalidReference(reference, includeActions),
-          hasValidReference: false,
-          suggestedActions: ['Request fresh content', 'Use alternative content source']
-        };
-      }
-
-      const contextId = this.addReference(reference);
-      
-      let displayText = '';
-      
-      switch (format) {
-        case 'inline':
-          displayText = this.formatInlineReference(reference, maxPreviewLength);
-          break;
-        case 'compact':
-          displayText = this.formatCompactReference(reference, showSize);
-          break;
-        case 'card':
-        default:
-          displayText = this.formatCardReference(reference, {
-            maxPreviewLength,
-            showMetadata,
-            showSize,
-            includeActions,
-            contextId
-          });
-          break;
-      }
-
-      return {
-        displayText,
-        hasValidReference: true,
-        contextId
-      };
-    } catch (error) {
-      this.logger.error('Error displaying reference:', error);
-      return {
-        displayText: this.formatErrorReference(reference, error),
-        hasValidReference: false,
-        suggestedActions: ['Check reference validity', 'Try again', 'Contact administrator']
-      };
-    }
-  }
-
-  /**
-   * Get the most recent reference for "inscribe it" commands
-   */
-  getMostRecentReference(): ContentReference | null {
-    if (this.activeReferences.size === 0) {
-      return null;
-    }
-
-    let mostRecent: ReferenceContext | null = null;
-    for (const context of this.activeReferences.values()) {
-      if (!mostRecent || context.displayedAt > mostRecent.displayedAt) {
-        mostRecent = context;
-      }
-    }
-
-    if (mostRecent) {
-      mostRecent.lastAccessedAt = new Date();
-      return mostRecent.reference;
-    }
-
-    return null;
-  }
-
-  /**
-   * Get reference by context ID
-   */
-  getReferenceByContextId(contextId: string): ContentReference | null {
-    for (const context of this.activeReferences.values()) {
-      if (context.contextId === contextId) {
-        context.lastAccessedAt = new Date();
-        return context.reference;
-      }
-    }
-    return null;
-  }
-
-  /**
-   * Validate all active references and remove invalid ones
-   */
-  async validateReferences(): Promise<{ valid: number; invalid: number; removed: ReferenceId[] }> {
-    const removed: ReferenceId[] = [];
-    let valid = 0;
-    let invalid = 0;
-
-    for (const [referenceId] of this.activeReferences.entries()) {
-      try {
-        const isValid = await this.contentStorage.hasReference(referenceId);
-        if (isValid) {
-          valid++;
-        } else {
-          invalid++;
-          removed.push(referenceId);
-          this.activeReferences.delete(referenceId);
-          this.logger.debug(`Removed invalid reference from context: ${referenceId}`);
-        }
-      } catch (error) {
-        invalid++;
-        removed.push(referenceId);
-        this.activeReferences.delete(referenceId);
-        this.logger.warn(`Error validating reference ${referenceId}:`, error);
-      }
-    }
-
-    return { valid, invalid, removed };
-  }
-
-  /**
-   * Clear old references based on age and usage
-   */
-  cleanupOldReferences(maxAgeMs: number = 30 * 60 * 1000): number {
-    const cutoffTime = new Date(Date.now() - maxAgeMs);
-    const toRemove: ReferenceId[] = [];
-
-    for (const [referenceId, context] of this.activeReferences.entries()) {
-      if (context.lastAccessedAt < cutoffTime) {
-        toRemove.push(referenceId);
-      }
-    }
-
-    toRemove.forEach(referenceId => {
-      this.activeReferences.delete(referenceId);
-    });
-
-    if (toRemove.length > 0) {
-      this.logger.debug(`Cleaned up ${toRemove.length} old references from context`);
-    }
-
-    return toRemove.length;
-  }
-
-  /**
-   * Get current context statistics
-   */
-  getContextStats(): {
-    activeReferences: number;
-    conversationTurn: number;
-    oldestReference: number | null;
-    mostRecentReference: number | null;
-  } {
-    return {
-      activeReferences: this.activeReferences.size,
-      conversationTurn: this.conversationTurn,
-      oldestReference: this.getOldestReferenceAge(),
-      mostRecentReference: this.getMostRecentReferenceAge()
-    };
-  }
-
-  /**
-   * Clear all references from context
-   */
-  clear(): void {
-    this.activeReferences.clear();
-    this.conversationTurn = 0;
-    this.logger.debug('Cleared all references from context');
-  }
-
-  private formatCardReference(
-    reference: ContentReference,
-    options: {
-      maxPreviewLength: number;
-      showMetadata: boolean;
-      showSize: boolean;
-      includeActions: boolean;
-      contextId: string;
-    }
-  ): string {
-    const { maxPreviewLength, showMetadata, showSize, includeActions, contextId } = options;
-    
-    let display = `📄 **Large Content Reference**\n`;
-    display += `**Preview:** ${this.truncateText(reference.preview, maxPreviewLength)}\n`;
-    
-    if (showSize) {
-      const sizeKB = Math.round(reference.metadata.sizeBytes / 1024);
-      display += `**Size:** ${sizeKB}KB`;
-      if (reference.metadata.contentType !== 'binary') {
-        display += ` (${reference.metadata.contentType})`;
-      }
-      display += '\n';
-    }
-    
-    if (showMetadata) {
-      if (reference.metadata.fileName) {
-        display += `**File:** ${reference.metadata.fileName}\n`;
-      }
-      if (reference.metadata.source) {
-        display += `**Source:** ${reference.metadata.source}\n`;
-      }
-    }
-    
-    if (includeActions) {
-      display += `\n💡 You can say "inscribe it" to inscribe this content to the Hedera Hashgraph.`;
-    }
-    
-    display += `\n\n*Reference ID: ${reference.referenceId.substring(0, 12)}...*`;
-    display += `\n*Context: ${contextId}*`;
-    
-    return display;
-  }
-
-  private formatInlineReference(reference: ContentReference, maxPreviewLength: number): string {
-    const sizeKB = Math.round(reference.metadata.sizeBytes / 1024);
-    return `📄 [${sizeKB}KB ${reference.metadata.contentType}] ${this.truncateText(reference.preview, maxPreviewLength)}`;
-  }
-
-  private formatCompactReference(reference: ContentReference, showSize: boolean): string {
-    const sizeKB = Math.round(reference.metadata.sizeBytes / 1024);
-    const sizeText = showSize ? ` (${sizeKB}KB)` : '';
-    return `📄 Referenced content${sizeText}: ${reference.metadata.fileName || 'large content'}`;
-  }
-
-  private formatInvalidReference(reference: ContentReference, includeActions: boolean): string {
-    let display = `❌ **Content Reference Expired**\n`;
-    display += `The referenced content is no longer available.\n`;
-    display += `**Original:** ${this.truncateText(reference.preview, 100)}\n`;
-    
-    if (includeActions) {
-      display += `\n💡 Please request fresh content from the original source.`;
-    }
-    
-    return display;
-  }
-
-  private formatErrorReference(reference: ContentReference, error: unknown): string {
-    const errorMsg = error instanceof Error ? error.message : 'Unknown error';
-    let display = `⚠️ **Reference Error**\n`;
-    display += `Error accessing referenced content: ${errorMsg}\n`;
-    display += `**Reference:** ${this.truncateText(reference.preview, 100)}\n`;
-    return display;
-  }
-
-  private truncateText(text: string, maxLength: number): string {
-    if (text.length <= maxLength) {
-      return text;
-    }
-    return text.substring(0, maxLength) + '...';
-  }
-
-  private getOldestReferenceAge(): number | null {
-    if (this.activeReferences.size === 0) return null;
-    
-    let oldest: Date | null = null;
-    for (const context of this.activeReferences.values()) {
-      if (!oldest || context.displayedAt < oldest) {
-        oldest = context.displayedAt;
-      }
-    }
-    
-    return oldest ? Date.now() - oldest.getTime() : null;
-  }
-
-  private getMostRecentReferenceAge(): number | null {
-    if (this.activeReferences.size === 0) return null;
-    
-    let newest: Date | null = null;
-    for (const context of this.activeReferences.values()) {
-      if (!newest || context.displayedAt > newest) {
-        newest = context.displayedAt;
-      }
-    }
-    
-    return newest ? Date.now() - newest.getTime() : null;
-  }
-}