@hashgraphonline/conversational-agent 0.1.214 → 0.1.217

package/dist/cjs/forms/FormEngine.d.ts

@@ -0,0 +1,121 @@
+import { StructuredTool } from '@langchain/core/tools';
+import { ZodError, z } from 'zod';
+import { Logger } from '@hashgraphonline/standards-sdk';
+import { FormMessage, FormSubmission } from './types';
+
+/**
+ * Tool execution result with optional form requirement
+ */
+export interface ToolExecutionResult {
+    success: boolean;
+    output: string;
+    metadata?: Record<string, unknown>;
+    requiresForm?: boolean;
+    formMessage?: FormMessage;
+    error?: string;
+}
+/**
+ * Context for form generation operations
+ */
+export interface FormGenerationContext {
+    tool: StructuredTool;
+    input: unknown;
+    sessionId?: string;
+    userId?: string;
+    missingFields?: Set<string>;
+}
+/**
+ * FormEngine handles all form generation and validation logic
+ */
+export declare class FormEngine {
+    private formGenerator;
+    private logger;
+    constructor(logger?: Logger);
+    /**
+     * Generate a form for a tool with the given input
+     */
+    generateForm(toolName: string, tool: StructuredTool, input: unknown, context?: Partial<FormGenerationContext>): Promise<FormMessage | null>;
+    /**
+     * Process a form submission
+     */
+    processSubmission(submission: FormSubmission, context?: {
+        originalInput?: Record<string, unknown>;
+        schema?: unknown;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Check if a tool requires form generation based on input
+     */
+    shouldGenerateForm(tool: StructuredTool, input: unknown): boolean;
+    /**
+     * Generate form from error context
+     */
+    generateFormFromError(error: ZodError, toolName: string, toolSchema: z.ZodSchema, originalPrompt: string): Promise<FormMessage>;
+    /**
+     * Generate form for FormValidatable tools
+     */
+    private generateFormValidatableForm;
+    /**
+     * Generate form based on schema validation
+     */
+    private generateSchemaBasedForm;
+    /**
+     * Generate form based on render config
+     */
+    private generateRenderConfigForm;
+    /**
+     * Generate form from Zod validation error
+     */
+    private generateErrorBasedForm;
+    /**
+     * Validate input against tool schema
+     */
+    private validateInput;
+    /**
+     * Check if schema is ZodObject
+     */
+    private isZodObject;
+    /**
+     * Check if tool has render configuration
+     */
+    private hasRenderConfig;
+    /**
+     * Extract render configuration from tool
+     */
+    private extractRenderConfig;
+    /**
+     * Resolve form schema for FormValidatable tools
+     */
+    private resolveFormSchema;
+    /**
+     * Determine missing fields for form generation
+     */
+    private determineMissingFields;
+    /**
+     * Generate form with resolved schema
+     */
+    private generateFormWithSchema;
+    /**
+     * Validate form submission
+     */
+    private validateSubmission;
+    /**
+     * Extract base tool input from context
+     */
+    private extractBaseToolInput;
+    /**
+     * Extract submission data
+     */
+    private extractSubmissionData;
+    /**
+     * Merge input data
+     */
+    private mergeInputData;
+    /**
+     * Get registered strategies
+     */
+    getRegisteredStrategies(): string[];
+    /**
+     * Get registered middleware
+     */
+    getRegisteredMiddleware(): string[];
+}

package/dist/cjs/forms/field-type-registry.d.ts

@@ -0,0 +1,51 @@
+import { FormFieldType } from './types';
+
+/**
+ * Pattern-based field type detection rule
+ */
+export interface FieldTypePattern {
+    pattern: RegExp | string[];
+    type: FormFieldType;
+    priority?: number;
+}
+/**
+ * Registry for managing field type detection patterns
+ */
+export declare class FieldTypeRegistry {
+    private static instance;
+    private patterns;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): FieldTypeRegistry;
+    /**
+     * Initialize default field type patterns
+     */
+    private initializeDefaultPatterns;
+    /**
+     * Register a field type pattern
+     */
+    register(key: string, pattern: FieldTypePattern): void;
+    /**
+     * Unregister a field type pattern
+     */
+    unregister(key: string): boolean;
+    /**
+     * Detect field type based on field name
+     */
+    detectType(fieldName: string): FormFieldType | null;
+    /**
+     * Get all registered patterns
+     */
+    getPatterns(): Map<string, FieldTypePattern>;
+    /**
+     * Clear all patterns
+     */
+    clear(): void;
+    /**
+     * Reset to default patterns
+     */
+    reset(): void;
+}
+export declare const fieldTypeRegistry: FieldTypeRegistry;

package/dist/cjs/forms/form-generator.d.ts

@@ -0,0 +1,123 @@
+import { z, ZodError } from 'zod';
+import { FormMessage } from './types';
+
+/**
+ * Generates forms from Zod validation failures
+ */
+export declare class FormGenerator {
+    private logger;
+    constructor();
+    /**
+     * Creates a form message from a Zod validation error
+     * @param error The Zod validation error
+     * @param schema The original Zod schema
+     * @param toolName Name of the tool that failed validation
+     * @param originalPrompt The user's original request
+     * @returns FormMessage to send to the chat UI
+     */
+    generateFormFromError(error: ZodError, schema: z.ZodSchema, toolName: string, originalPrompt: string): FormMessage;
+    /**
+     * Generates a form from a schema and partial input
+     * @param schema The Zod schema to generate a form from
+     * @param partialInput Any partial input already provided
+     * @param context Additional context about the tool
+     * @param preCalculatedMissingFields Optional pre-calculated missing fields set. If undefined, includes all fields from schema.
+     * @returns FormMessage to send to the chat UI
+     */
+    generateFormFromSchema(schema: z.ZodSchema, partialInput: unknown, context: {
+        toolName: string;
+        toolDescription?: string;
+    }, preCalculatedMissingFields?: Set<string>): Promise<FormMessage>;
+    /**
+     * Extracts validation errors from ZodError
+     */
+    private extractValidationErrors;
+    /**
+     * Identifies which fields are missing or invalid from validation errors
+     */
+    private identifyMissingFields;
+    /**
+     * Creates form configuration from schema
+     */
+    private createFormConfig;
+    /**
+     * Safely extracts render configs from schema
+     */
+    private extractRenderConfigsSafely;
+    /**
+     * Safely generates field ordering from schema
+     */
+    private generateFieldOrderingSafely;
+    /**
+     * Determines field priority for progressive disclosure
+     */
+    private getFieldPriority;
+    /**
+     * Determines which fields should be included in the form
+     */
+    private determineFieldsToInclude;
+    /**
+     * Includes required fields that are missing
+     */
+    private includeRequiredMissingFields;
+    /**
+     * Creates form fields from ordered field names
+     */
+    private createOrderedFields;
+    /**
+     * Generates form fields from schema and validation errors
+     */
+    private generateFormFields;
+    /**
+     * Creates a single form field
+     */
+    private createFormField;
+    /**
+     * Maps render config field type to form field type with fallback inference
+     */
+    private mapFieldType;
+    /**
+     * Converts field name to human-readable label
+     */
+    private humanizeFieldName;
+    /**
+     * Generates a title for the form
+     */
+    private generateFormTitle;
+    /**
+     * Safely extracts ZodObject from a schema, returns null if not an object schema
+     */
+    private extractZodObject;
+    /**
+     * Extracts field names from Zod schema structure
+     */
+    private extractFieldsFromSchema;
+    /**
+     * Infers field type from Zod schema
+     */
+    private inferTypeFromSchema;
+    /**
+     * Determines if a field is required based on the Zod schema
+     */
+    private isFieldRequired;
+    /**
+     * Generates a description for the form
+     */
+    private generateFormDescription;
+    /**
+     * Generates JSON Schema and uiSchema from a Zod schema for use with @rjsf/core
+     * @param zodSchema The Zod schema to convert
+     * @param partialInput Existing input data to filter out fields that already have values
+     * @param missingFields Set of fields that are missing and should be shown
+     * @returns Object containing jsonSchema and uiSchema
+     */
+    generateJsonSchemaForm(zodSchema: z.ZodObject<z.ZodRawShape>, partialInput?: Record<string, unknown>, missingFields?: Set<string>): {
+        jsonSchema: import('zod-to-json-schema').JsonSchema7Type & {
+            $schema?: string | undefined;
+            definitions?: {
+                [key: string]: import('zod-to-json-schema').JsonSchema7Type;
+            } | undefined;
+        };
+        uiSchema: Record<string, Record<string, unknown>>;
+    };
+}

package/dist/cjs/forms/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './form-generator';

package/dist/cjs/forms/types.d.ts

@@ -0,0 +1,108 @@
+import { RenderConfigSchema } from '@hashgraphonline/standards-agent-kit';
+
+/**
+ * JSON Schema definition for form rendering
+ */
+export type JSONSchemaDefinition = Record<string, unknown>;
+/**
+ * UI Schema configuration for form rendering customization
+ */
+export type UISchemaDefinition = Record<string, unknown>;
+/**
+ * Represents a form message that can be sent to the chat UI
+ */
+export interface FormMessage {
+    type: 'form';
+    id: string;
+    formConfig: FormConfig;
+    originalPrompt: string;
+    toolName: string;
+    validationErrors?: ValidationError[];
+    partialInput?: unknown;
+    jsonSchema?: JSONSchemaDefinition;
+    uiSchema?: UISchemaDefinition;
+}
+/**
+ * Configuration for generating a form from Zod schema
+ */
+export interface FormConfig {
+    title: string;
+    description?: string;
+    fields: FormField[];
+    submitLabel?: string;
+    cancelLabel?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Individual form field configuration
+ */
+export interface FormField {
+    name: string;
+    label: string;
+    type: FormFieldType;
+    required: boolean;
+    placeholder?: string;
+    helpText?: string;
+    defaultValue?: unknown;
+    validation?: FieldValidation;
+    options?: FieldOption[];
+    renderConfig?: RenderConfigSchema;
+    priority?: 'essential' | 'common' | 'advanced' | 'expert';
+}
+/**
+ * Form field types supported by the UI
+ */
+export type FormFieldType = 'text' | 'number' | 'select' | 'checkbox' | 'textarea' | 'file' | 'array' | 'object' | 'currency' | 'percentage';
+/**
+ * Field validation rules
+ */
+export interface FieldValidation {
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    custom?: string;
+}
+/**
+ * Option for select/radio fields
+ */
+export interface FieldOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+/**
+ * Validation error from Zod
+ */
+export interface ValidationError {
+    path: string[];
+    message: string;
+    code: string;
+}
+/**
+ * Form submission data
+ */
+export interface FormSubmission {
+    formId: string;
+    toolName: string;
+    parameters: Record<string, unknown>;
+    timestamp: number;
+    context?: {
+        originalPrompt?: string;
+        partialInput?: Record<string, unknown>;
+        chatHistory?: Array<{
+            type: 'human' | 'ai';
+            content: string;
+        }>;
+    };
+}
+/**
+ * Response after form submission
+ */
+export interface FormResponse {
+    success: boolean;
+    message?: string;
+    data?: unknown;
+    error?: string;
+}