@hashgraphonline/conversational-agent 0.1.217 → 0.1.219

package/src/forms/{FormEngine.ts → form-engine.ts}

@@ -52,7 +52,7 @@ export class FormEngine {
     const fullContext: FormGenerationContext = {
       tool,
       input,
-      ...context
+      ...context,
     };
 
     try {
@@ -75,7 +75,7 @@ export class FormEngine {
       return null;
     } catch (error) {
       this.logger.error(`Failed to generate form for tool: ${toolName}`, {
-        error: error instanceof Error ? error.message : String(error)
+        error: error instanceof Error ? error.message : String(error),
       });
       throw error;
     }
@@ -92,10 +92,10 @@ export class FormEngine {
     }
   ): Promise<Record<string, unknown>> {
     this.validateSubmission(submission);
-    
+
     const baseToolInput = this.extractBaseToolInput(context);
     const submissionData = this.extractSubmissionData(submission);
-    
+
     return this.mergeInputData(baseToolInput, submissionData);
   }
 
@@ -115,7 +115,10 @@ export class FormEngine {
         };
         return formValidatableTool.shouldGenerateForm(input);
       } catch (error) {
-        this.logger.error(`Error calling shouldGenerateForm() on ${tool.name}:`, error);
+        this.logger.error(
+          `Error calling shouldGenerateForm() on ${tool.name}:`,
+          error
+        );
         return false;
       }
     }
@@ -150,8 +153,13 @@ export class FormEngine {
     _context: FormGenerationContext
   ): Promise<FormMessage> {
     const { schemaToUse, isFocusedSchema } = this.resolveFormSchema(tool);
-    const missingFields = this.determineMissingFields(tool, input, schemaToUse, isFocusedSchema);
-    
+    const missingFields = this.determineMissingFields(
+      tool,
+      input,
+      schemaToUse,
+      isFocusedSchema
+    );
+
     return this.generateFormWithSchema(tool, input, schemaToUse, missingFields);
   }
 
@@ -170,22 +178,26 @@ export class FormEngine {
       input,
       {
         toolName: tool.name,
-        toolDescription: tool.description
+        toolDescription: tool.description,
       },
       context.missingFields
     );
 
     if (this.isZodObject(schema)) {
       try {
-        const { jsonSchema, uiSchema } = this.formGenerator.generateJsonSchemaForm(
-          schema,
-          input as Record<string, unknown> | undefined,
-          context.missingFields || new Set()
-        );
+        const { jsonSchema, uiSchema } =
+          this.formGenerator.generateJsonSchemaForm(
+            schema,
+            input as Record<string, unknown> | undefined,
+            context.missingFields || new Set()
+          );
         formMessage.jsonSchema = jsonSchema;
         formMessage.uiSchema = uiSchema;
       } catch (error) {
-        this.logger.warn('Failed to generate JSON Schema for schema-based tool:', error);
+        this.logger.warn(
+          'Failed to generate JSON Schema for schema-based tool:',
+          error
+        );
       }
     }
 
@@ -209,7 +221,7 @@ export class FormEngine {
       input,
       {
         toolName: tool.name,
-        toolDescription: tool.description
+        toolDescription: tool.description,
       },
       context.missingFields
     );
@@ -217,10 +229,10 @@ export class FormEngine {
     if (renderConfig) {
       formMessage.formConfig.metadata = {
         ...formMessage.formConfig.metadata,
-        renderConfig
+        renderConfig,
       };
     }
-    
+
     formMessage.partialInput = input;
     return formMessage;
   }
@@ -249,7 +261,11 @@ export class FormEngine {
     input: unknown
   ): { isValid: boolean; errors?: string[] } {
     try {
-      const zodSchema = tool.schema as z.ZodType<unknown, z.ZodTypeDef, unknown>;
+      const zodSchema = tool.schema as z.ZodType<
+        unknown,
+        z.ZodTypeDef,
+        unknown
+      >;
       zodSchema.parse(input);
       return { isValid: true };
     } catch (error) {
@@ -285,7 +301,9 @@ export class FormEngine {
   /**
    * Extract render configuration from tool
    */
-  private extractRenderConfig(tool: StructuredTool): Record<string, unknown> | undefined {
+  private extractRenderConfig(
+    tool: StructuredTool
+  ): Record<string, unknown> | undefined {
     const schema = tool.schema as Record<string, unknown>;
     return schema?._renderConfig as Record<string, unknown> | undefined;
   }
@@ -293,21 +311,21 @@ export class FormEngine {
   /**
    * Resolve form schema for FormValidatable tools
    */
-  private resolveFormSchema(tool: StructuredTool): { 
-    schemaToUse: z.ZodSchema; 
-    isFocusedSchema: boolean 
+  private resolveFormSchema(tool: StructuredTool): {
+    schemaToUse: z.ZodSchema;
+    isFocusedSchema: boolean;
   } {
     const formValidatableTool = tool as {
       getFormSchema?: () => z.ZodSchema | null;
     };
-    
+
     if (formValidatableTool.getFormSchema) {
       const focusedSchema = formValidatableTool.getFormSchema();
       if (focusedSchema) {
         return { schemaToUse: focusedSchema, isFocusedSchema: true };
       }
     }
-    
+
     return { schemaToUse: tool.schema as z.ZodSchema, isFocusedSchema: false };
   }
 
@@ -321,28 +339,30 @@ export class FormEngine {
     _isFocusedSchema: boolean
   ): Set<string> {
     const missingFields = new Set<string>();
-    
+
     if (!input || typeof input !== 'object') {
       return missingFields;
     }
-    
+
     const inputRecord = input as Record<string, unknown>;
     const formValidatableTool = tool as {
       isFieldEmpty?: (fieldName: string, value: unknown) => boolean;
       getEssentialFields?: () => string[];
     };
-    
+
     if (formValidatableTool.getEssentialFields) {
       const essentialFields = formValidatableTool.getEssentialFields();
       for (const field of essentialFields) {
-        if (!(field in inputRecord) || 
-            (formValidatableTool.isFieldEmpty && 
-             formValidatableTool.isFieldEmpty(field, inputRecord[field]))) {
+        if (
+          !(field in inputRecord) ||
+          (formValidatableTool.isFieldEmpty &&
+            formValidatableTool.isFieldEmpty(field, inputRecord[field]))
+        ) {
           missingFields.add(field);
         }
       }
     }
-    
+
     return missingFields;
   }
 
@@ -360,25 +380,26 @@ export class FormEngine {
       input,
       {
         toolName: tool.name,
-        toolDescription: tool.description
+        toolDescription: tool.description,
       },
       missingFields
     );
-    
+
     if (this.isZodObject(schema)) {
       try {
-        const { jsonSchema, uiSchema } = this.formGenerator.generateJsonSchemaForm(
-          schema,
-          input as Record<string, unknown> | undefined,
-          missingFields
-        );
+        const { jsonSchema, uiSchema } =
+          this.formGenerator.generateJsonSchemaForm(
+            schema,
+            input as Record<string, unknown> | undefined,
+            missingFields
+          );
         formMessage.jsonSchema = jsonSchema;
         formMessage.uiSchema = uiSchema;
       } catch (error) {
         this.logger.warn('Failed to generate JSON Schema:', error);
       }
     }
-    
+
     formMessage.partialInput = input;
     return formMessage;
   }
@@ -407,10 +428,12 @@ export class FormEngine {
   /**
    * Extract submission data
    */
-  private extractSubmissionData(submission: FormSubmission): Record<string, unknown> {
+  private extractSubmissionData(
+    submission: FormSubmission
+  ): Record<string, unknown> {
     return {
       ...submission.parameters,
-      __fromForm: true
+      __fromForm: true,
     };
   }
 
@@ -423,7 +446,7 @@ export class FormEngine {
   ): Record<string, unknown> {
     return {
       ...baseInput,
-      ...submissionData
+      ...submissionData,
     };
   }
 
@@ -440,4 +463,4 @@ export class FormEngine {
   getRegisteredMiddleware(): string[] {
     return ['FormSubmissionValidator'];
   }
-}
+}

package/src/forms/form-generator.ts

@@ -16,6 +16,16 @@ import {
 } from '@hashgraphonline/standards-agent-kit';
 import { Logger } from '@hashgraphonline/standards-sdk';
 import { fieldTypeRegistry } from './field-type-registry';
+import { fieldGuidanceRegistry } from './field-guidance-registry';
+import { FIELD_PRIORITIES } from '../constants';
+
+interface ZodObjectSchema extends z.ZodSchema {
+  shape?: Record<string, z.ZodSchema>;
+}
+
+function isZodObjectSchema(schema: z.ZodSchema): schema is ZodObjectSchema {
+  return typeof schema === 'object' && schema !== null && 'shape' in schema;
+}
 
 type FieldPriority = 'essential' | 'common' | 'advanced' | 'expert';
 
@@ -77,7 +87,7 @@ export class FormGenerator {
       toolName: context.toolName,
       partialInput,
       hasSchema: !!schema,
-      hasShape: !!(schema && (schema as any).shape),
+      hasShape: !!(schema && isZodObjectSchema(schema)),
       hasPreCalculatedFields: preCalculatedMissingFields !== undefined,
       preCalculatedFieldsSize: preCalculatedMissingFields?.size || 0,
     });
@@ -172,18 +182,28 @@ export class FormGenerator {
       extractedConfig,
       missingFields,
       fieldOrdering,
-      preCalculatedMissingFields
+      preCalculatedMissingFields,
+      toolName
     );
 
+    const globalGuidance = fieldGuidanceRegistry.getGlobalGuidance(toolName);
+    let description = this.generateFormDescription(toolName, missingFields.size);
+    
+    if (globalGuidance?.qualityStandards) {
+      description += '\n\nQuality Guidelines:\n' + 
+        globalGuidance.qualityStandards.map(standard => `• ${standard}`).join('\n');
+    }
+
     return {
       title: this.generateFormTitle(toolName),
-      description: this.generateFormDescription(toolName, missingFields.size),
+      description,
       fields,
       submitLabel: 'Continue',
       cancelLabel: 'Cancel',
       metadata: {
         toolName,
         missingFieldCount: missingFields.size,
+        globalGuidance
       },
     };
   }
@@ -242,25 +262,25 @@ export class FormGenerator {
   ): FieldPriority {
     if (renderConfig?.ui?.priority) {
       const priority = renderConfig.ui.priority as string;
-      if (['essential', 'common', 'advanced', 'expert'].includes(priority)) {
+      if (Object.values(FIELD_PRIORITIES).includes(priority as FieldPriority)) {
         return priority as FieldPriority;
       }
     }
 
     if (isRequired === true) {
-      return 'essential';
+      return FIELD_PRIORITIES.ESSENTIAL;
     }
 
     const ui = renderConfig?.ui as Record<string, unknown> | undefined;
     if (ui?.advanced === true) {
-      return 'advanced';
+      return FIELD_PRIORITIES.ADVANCED;
     }
 
     if (ui?.expert === true) {
-      return 'expert';
+      return FIELD_PRIORITIES.EXPERT;
     }
 
-    return 'common';
+    return FIELD_PRIORITIES.COMMON;
   }
 
   /**
@@ -334,7 +354,8 @@ export class FormGenerator {
     fieldsToInclude: Set<string>,
     fieldOrdering: { sections: Array<{ fields: string[] }> },
     extractedConfig: ExtractedRenderConfig,
-    schema: z.ZodSchema
+    schema: z.ZodSchema,
+    toolName?: string
   ): FormField[] {
     const fields: FormField[] = [];
     const processedFields = new Set<string>();
@@ -347,7 +368,8 @@ export class FormGenerator {
             fieldName,
             extractedConfig.fields[fieldName],
             schema,
-            fieldName
+            fieldName,
+            toolName
           );
           if (field) {
             fields.push(field);
@@ -363,7 +385,8 @@ export class FormGenerator {
           fieldName,
           extractedConfig.fields[fieldName],
           schema,
-          fieldName
+          fieldName,
+          toolName
         );
         if (field) {
           fields.push(field);
@@ -382,7 +405,8 @@ export class FormGenerator {
     extractedConfig: ExtractedRenderConfig,
     missingFields: Set<string>,
     fieldOrdering: { sections: Array<{ fields: string[] }> },
-    preCalculatedMissingFields?: Set<string>
+    preCalculatedMissingFields?: Set<string>,
+    toolName?: string
   ): FormField[] {
     const fieldsToInclude = this.determineFieldsToInclude(
       schema,
@@ -394,7 +418,8 @@ export class FormGenerator {
       fieldsToInclude,
       fieldOrdering,
       extractedConfig,
-      schema
+      schema,
+      toolName
     );
 
     if (fields.length === 0 && missingFields.size > 0) {
@@ -404,7 +429,8 @@ export class FormGenerator {
             fieldName,
             extractedConfig.fields[fieldName],
             schema,
-            fieldName
+            fieldName,
+            toolName
           )
         )
         .filter(
@@ -422,19 +448,67 @@ export class FormGenerator {
     fieldName: string,
     renderConfig?: RenderConfigSchema,
     schema?: z.ZodSchema,
-    fieldPath?: string
+    fieldPath?: string,
+    toolName?: string
   ): FormField {
     const type = this.mapFieldType(renderConfig?.fieldType, schema, fieldPath);
     const isRequired = this.isFieldRequired(schema, fieldPath || fieldName);
+    
+    const guidance = toolName ? fieldGuidanceRegistry.getFieldGuidance(toolName, fieldName) : null;
+    const finalType = guidance?.fieldTypeOverride || type;
 
     const field: FormField = {
       name: fieldName,
       label: renderConfig?.ui?.label || this.humanizeFieldName(fieldName),
-      type,
+      type: finalType,
       required: isRequired,
       priority: this.getFieldPriority(fieldName, renderConfig, isRequired),
     };
 
+    if (guidance) {
+      if (guidance.suggestions && guidance.suggestions.length > 0) {
+        field.suggestions = guidance.suggestions;
+        if (!field.placeholder) {
+          field.placeholder = `e.g., ${guidance.suggestions[0]}`;
+        }
+      }
+
+      if (guidance.predefinedOptions) {
+        field.options = [...(field.options || []), ...guidance.predefinedOptions];
+      }
+
+      if (guidance.contextualHelpText) {
+        field.helpText = guidance.contextualHelpText;
+      }
+
+      if (guidance.warnings) {
+        field.warnings = guidance.warnings.map(w => w.message);
+      }
+
+      if (guidance.validationRules) {
+        const { qualityChecks } = guidance.validationRules;
+        if (qualityChecks) {
+          field.contextualGuidance = {
+            qualityStandards: [],
+            examples: guidance.suggestions || [],
+            avoidPatterns: qualityChecks.forbidTechnicalTerms || []
+          };
+
+          if (qualityChecks.minNonTechnicalWords) {
+            field.contextualGuidance.qualityStandards?.push(
+              `Use at least ${qualityChecks.minNonTechnicalWords} meaningful words`
+            );
+          }
+
+          if (qualityChecks.forbidTechnicalTerms) {
+            field.contextualGuidance.qualityStandards?.push(
+              `Avoid technical terms like: ${qualityChecks.forbidTechnicalTerms.join(', ')}`
+            );
+          }
+        }
+      }
+    }
+
     if (renderConfig) {
       field.renderConfig = renderConfig;
     }
@@ -743,7 +817,7 @@ export class FormGenerator {
     zodSchema: z.ZodObject<z.ZodRawShape>,
     partialInput?: Record<string, unknown>,
     missingFields?: Set<string>
-  ) {
+  ): { jsonSchema: Record<string, unknown>; uiSchema: Record<string, unknown> } {
     const fullJsonSchema = zodToJsonSchema(zodSchema, {
       target: 'jsonSchema7',
     });

package/src/forms/index.ts

@@ -1,2 +1,5 @@
 export * from './types';
-export * from './form-generator';
+export * from './form-generator';
+export * from './form-engine';
+export * from './field-type-registry';
+export * from './field-guidance-registry';

package/src/forms/types.ts

@@ -52,6 +52,13 @@ export interface FormField {
   options?: FieldOption[];
   renderConfig?: RenderConfigSchema;
   priority?: 'essential' | 'common' | 'advanced' | 'expert';
+  suggestions?: string[];
+  warnings?: string[];
+  contextualGuidance?: {
+    qualityStandards?: string[];
+    examples?: string[];
+    avoidPatterns?: string[];
+  };
 }
 
 /**
@@ -88,6 +95,7 @@ export interface FieldOption {
   value: string;
   label: string;
   description?: string;
+  disabled?: boolean;
 }
 
 /**
@@ -110,7 +118,7 @@ export interface FormSubmission {
   context?: {
     originalPrompt?: string;
     partialInput?: Record<string, unknown>;
-    chatHistory?: Array<{type: 'human' | 'ai'; content: string}>;
+    chatHistory?: Array<{type: 'human' | 'ai' | 'system'; content: string}>;
   };
 }
 

package/src/index.ts

@@ -16,43 +16,13 @@ export {
   type ChatResponse,
   type UsageStats,
 } from './base-agent';
-export { LangChainAgent } from './langchain-agent';
 export { createAgent } from './agent-factory';
-export {
-  LangChainProvider,
-  type AIProvider,
-  type VercelAIProvider,
-  type BAMLProvider,
-} from './providers';
-
+export * from './providers';
 export * from 'hedera-agent-kit';
-
-export type { IStateManager } from '@hashgraphonline/standards-agent-kit';
-
-export type {
-  MCPServerConfig,
-  MCPConnectionStatus,
-  MCPToolInfo,
-} from './mcp/types';
-export {
-  MCPServers,
-  createMCPConfig,
-  validateServerConfig,
-} from './mcp/helpers';
-
+export * from './forms';
+export * from './mcp';
 export * from './memory';
-export {
-  createEntityTools,
-  ResolveEntitiesTool,
-  ExtractEntitiesTool,
-} from './tools/EntityResolverTool';
-export { ContentStoreManager } from './services/ContentStoreManager';
-
-export { FormGenerator } from './forms/form-generator';
-export {
-  FormValidatingToolWrapper,
-  wrapToolWithFormValidation,
-} from './langchain/FormValidatingToolWrapper';
-export type { FormValidationConfig } from './langchain/FormValidatingToolWrapper';
-export type { FormMessage, FormField, FormConfig, FormSubmission } from './forms/types';
-export { ResponseFormatter } from './utils/ResponseFormatter';
+export * from './services';
+export * from './langchain';
+export * from './tools';
+export * from './utils';

package/src/langchain/external-tool-wrapper.ts

@@ -0,0 +1,90 @@
+/**
+ * Mock external tool wrapper functionality
+ * These are placeholders to satisfy import statements in test scripts
+ */
+
+import { z as _z } from 'zod';
+
+export interface ExternalToolWrapper<T> {
+  name: string;
+  description: string;
+  schema: T;
+}
+
+export function wrapExternalToolWithRenderConfig<T>(
+  tool: { name: string; description: string; schema: T },
+  config: {
+    ui?: { label?: string; description?: string };
+    fieldConfigs?: Record<string, unknown>;
+  }
+): ExternalToolWrapper<T> {
+  return {
+    name: tool.name,
+    description: config.ui?.description || tool.description,
+    schema: tool.schema
+  };
+}
+
+export const renderConfigs = {
+  text: (label: string, placeholder?: string, help?: string) => ({
+    type: 'text',
+    label,
+    placeholder,
+    help
+  }),
+
+  number: (label: string, min?: number, max?: number, help?: string) => ({
+    type: 'number',
+    label,
+    min,
+    max,
+    help
+  }),
+
+  accountId: (label: string) => ({
+    type: 'accountId',
+    label,
+    placeholder: '0.0.12345'
+  }),
+
+  checkbox: (label: string, help?: string) => ({
+    type: 'checkbox',
+    label,
+    help
+  }),
+
+  currency: (label: string, currency: string, min?: number, max?: number) => ({
+    type: 'currency',
+    label,
+    currency,
+    min,
+    max
+  }),
+
+  tokenId: (label: string) => ({
+    type: 'tokenId',
+    label,
+    placeholder: '0.0.12345'
+  }),
+
+  select: (label: string, options: Array<{ value: string; label: string }>) => ({
+    type: 'select',
+    label,
+    options
+  })
+};
+
+export const hederaToolConfigs = {
+  hbarTransfer: () => ({
+    ui: {
+      label: 'HBAR Transfer',
+      description: 'Transfer HBAR between accounts'
+    },
+    fieldConfigs: {
+      fromAccountId: renderConfigs.accountId('From Account'),
+      toAccountId: renderConfigs.accountId('To Account'),
+      amount: renderConfigs.currency('Amount', 'HBAR', 0.00000001, 1000),
+      memo: renderConfigs.text('Memo', 'Optional memo')
+    }
+  })
+};