ai-database 2.1.1 → 2.3.0

package/dist/schema/cascade.js

@@ -6,21 +6,208 @@
  *
  * @packageDocumentation
  */
+import { AIGenerationError } from '../errors.js';
 import { isPrimitiveType } from './parse.js';
-import { resolveNestedPending, prefetchContext, resolveInstructions } from './resolve.js';
+import { resolveNestedPending, prefetchContext, resolveInstructions, isPromptField, } from './resolve.js';
+import { PlaceholderValueGenerator } from './value-generators/index.js';
+/**
+ * Hard safety limit for cascade/entity generation recursion depth.
+ * Applied even when maxDepth is not explicitly configured to prevent
+ * infinite recursion with circular schemas.
+ */
+export const DEFAULT_MAX_DEPTH = 10;
+// Create a singleton placeholder generator for synchronous calls
+const placeholderGenerator = new PlaceholderValueGenerator();
+// =============================================================================
+// Value Generator Configuration
+// =============================================================================
+/**
+ * Current value generator instance
+ * Defaults to PlaceholderValueGenerator
+ */
+let currentValueGenerator = placeholderGenerator;
+/**
+ * Configure the value generator to use for field generation
+ *
+ * @param generator - The value generator instance to use
+ */
+export function setValueGenerator(generator) {
+    currentValueGenerator = generator;
+}
+/**
+ * Get the current value generator
+ *
+ * @returns The current value generator instance
+ */
+export function getValueGenerator() {
+    return currentValueGenerator;
+}
+// =============================================================================
+// AI Generation Configuration
+// =============================================================================
+// Default configuration - uses 'sonnet' as the default model
+let aiConfig = {
+    model: 'sonnet',
+    enabled: true,
+};
+/**
+ * Configure AI generation settings
+ *
+ * @param config - Partial configuration to merge with defaults
+ */
+export function configureAIGeneration(config) {
+    aiConfig = { ...aiConfig, ...config };
+}
+/**
+ * Get current AI generation configuration
+ */
+export function getAIGenerationConfig() {
+    return { ...aiConfig };
+}
+// =============================================================================
+// AI-Powered Entity Generation
+// =============================================================================
+/**
+ * Build a simple schema object for generateObject from entity fields
+ *
+ * @param entity - The parsed entity definition
+ * @returns A simple schema object mapping field names to type descriptions
+ */
+function buildSchemaForEntity(entity) {
+    const schema = {};
+    for (const [fieldName, field] of entity.fields) {
+        // Only include non-relation scalar fields
+        if (!field.isRelation) {
+            const isPrompt = isPromptField(field);
+            if (field.type === 'string') {
+                // Use the field prompt if available, otherwise a generic description
+                schema[fieldName] = field.prompt || `Generate a ${fieldName}`;
+            }
+            else if (isPrompt) {
+                // For prompt fields, use the type (which is the prompt) as the schema
+                schema[fieldName] = field.type;
+            }
+            else if (field.type === 'number') {
+                schema[fieldName] = `number`;
+            }
+            else if (field.type === 'boolean') {
+                schema[fieldName] = `boolean`;
+            }
+            // Note: Arrays handled separately for now
+        }
+    }
+    return schema;
+}
+/**
+ * Generate entity data using AI via generateObject from ai-functions
+ *
+ * @param type - The type name of the entity to generate
+ * @param entity - The parsed entity definition
+ * @param prompt - The generation prompt (from field definition)
+ * @param context - Context from parent entity for informed generation
+ * @param injectedConfig - Optional AI config to use instead of module-level config (for DI)
+ * @returns Generated entity data, or null if AI generation failed/unavailable
+ */
+async function generateEntityDataWithAI(type, entity, prompt, context, injectedConfig) {
+    // Use injected config if provided, otherwise fall back to module-level config
+    const config = injectedConfig ?? aiConfig;
+    if (!config.enabled) {
+        return null;
+    }
+    try {
+        // Dynamically import generateObject to avoid circular dependencies
+        // and to allow the mock to work in tests
+        const { generateObject } = await import('ai-functions');
+        // Build schema for the target entity
+        const schema = buildSchemaForEntity(entity);
+        // If no fields to generate, return null
+        if (Object.keys(schema).length === 0) {
+            return null;
+        }
+        // Build comprehensive prompt with context
+        const promptParts = [];
+        // Add the field prompt (e.g., "What problem does this solve?")
+        if (prompt && prompt.trim()) {
+            promptParts.push(prompt);
+        }
+        // Add $instructions if available
+        if (context.instructions) {
+            promptParts.push(`Context: ${context.instructions}`);
+        }
+        // Add $context if available
+        if (context.schemaContext) {
+            promptParts.push(context.schemaContext);
+        }
+        // Add relevant parent data for context
+        const parentContextEntries = [];
+        for (const [key, value] of Object.entries(context.parentData)) {
+            if (!key.startsWith('$') && !key.startsWith('_') && typeof value === 'string' && value) {
+                parentContextEntries.push(`${key}: ${value}`);
+            }
+        }
+        if (parentContextEntries.length > 0) {
+            promptParts.push(`Parent entity: ${parentContextEntries.join(', ')}`);
+        }
+        // Add type context
+        promptParts.push(`Generate a ${type} entity with the following fields.`);
+        const fullPrompt = promptParts.join('\n');
+        // Call generateObject with the schema and prompt, tracking timing
+        const startTime = Date.now();
+        const result = await generateObject({
+            model: config.model,
+            schema,
+            prompt: fullPrompt,
+        });
+        const latencyMs = Date.now() - startTime;
+        // Call onGenerate callback if configured
+        if (config.onGenerate) {
+            config.onGenerate({
+                entityType: type,
+                model: config.model,
+                prompt: fullPrompt,
+                result: result.object,
+                latencyMs,
+                timestamp: new Date(),
+            });
+        }
+        return result.object;
+    }
+    catch (error) {
+        // Call onGenerate callback with error if configured
+        if (config.onGenerate) {
+            config.onGenerate({
+                entityType: type,
+                model: config.model,
+                prompt: prompt || '',
+                result: null,
+                latencyMs: 0,
+                error: error instanceof Error ? error.message : String(error),
+                timestamp: new Date(),
+            });
+        }
+        // Throw AIGenerationError - don't silently fall back to placeholder
+        const cause = error instanceof Error ? error : undefined;
+        throw new AIGenerationError(cause?.message || 'Unknown AI generation failure', type, undefined, cause);
+    }
+}
 // =============================================================================
 // Context-Aware Value Generation
 // =============================================================================
 /**
  * Generate a context-aware value for a field
  *
- * Uses hint, instructions, schema context, and parent data to generate
- * contextually appropriate values. This is a minimal deterministic implementation
- * for testing - real AI generation would integrate with LLMs.
+ * **DELEGATED TO VALUE-GENERATORS MODULE**
  *
- * The function uses keyword matching on the context and hint to produce
- * contextually relevant values for common field names like 'name', 'description',
- * 'headline', 'background', etc.
+ * This function now delegates to PlaceholderValueGenerator for backward
+ * compatibility. The actual generation logic has been extracted to:
+ * `./value-generators/placeholder.ts`
+ *
+ * For new code, prefer using the ValueGenerator interface directly:
+ * ```ts
+ * import { getValueGenerator } from './value-generators/index.js'
+ * const generator = getValueGenerator()
+ * const result = await generator.generate({ fieldName, type, fullContext, hint, parentData })
+ * ```
  *
  * @param fieldName - The name of the field being generated
  * @param type - The entity type name
@@ -39,180 +226,108 @@ import { resolveNestedPending, prefetchContext, resolveInstructions } from './re
  * ```
  */
 export function generateContextAwareValue(fieldName, type, fullContext, hint, parentData = {}) {
-    // If parent has the same field, copy its value (for self-referential types like Company.competitor)
-    const parentValue = parentData[fieldName];
-    if (typeof parentValue === 'string' && parentValue) {
-        return parentValue;
-    }
-    // If no context provided, fall back to static placeholder
-    if (!fullContext || fullContext.trim() === '') {
-        return `Generated ${fieldName} for ${type}`;
-    }
-    const contextLower = fullContext.toLowerCase();
-    const hintLower = (hint || '').toLowerCase();
-    // For 'name' field, use hint-based generation with keyword matching
-    if (fieldName === 'name') {
-        if (hintLower.includes('philosopher') || contextLower.includes('philosopher'))
-            return 'Aristotle';
-        if (hintLower.includes('tech entrepreneur') || hintLower.includes('startup'))
-            return 'Alex Chen';
-        if (hint && hint.trim())
-            return `${type}: ${hint}`;
-        return `Generated ${fieldName} for ${type}`;
-    }
-    // For 'style' field
-    if (fieldName === 'style') {
-        if (hintLower.includes('energetic') || contextLower.includes('energetic'))
-            return 'Energetic and engaging presentation style';
-        if (contextLower.includes('horror') || contextLower.includes('dark'))
-            return 'Dark and atmospheric horror style';
-        if (contextLower.includes('sci-fi') || contextLower.includes('futuristic'))
-            return 'Atmospheric sci-fi suspense style';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'background' field
-    if (fieldName === 'background') {
-        if (hintLower.includes('tech entrepreneur') || hintLower.includes('startup'))
-            return 'Tech startup founder with 10 years experience';
-        if (hintLower.includes('aristocrat') || hintLower.includes('noble'))
-            return 'English aristocrat from old noble family';
-        if (contextLower.includes('renewable') || contextLower.includes('energy'))
-            return 'Background in renewable energy sector';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'specialty' field
-    if (fieldName === 'specialty') {
-        if (contextLower.includes('french') || contextLower.includes('restaurant'))
-            return 'French classical cuisine';
-        if (hintLower.includes('security') || contextLower.includes('security'))
-            return 'Security and authentication systems';
-        if (hintLower.includes('history') || hintLower.includes('medieval'))
-            return 'Medieval history specialist';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'training' field
-    if (fieldName === 'training') {
-        if (contextLower.includes('french') || contextLower.includes('restaurant'))
-            return 'Trained in classical French culinary techniques';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'backstory' field
-    if (fieldName === 'backstory') {
-        if (contextLower.includes('medieval') || contextLower.includes('fantasy'))
-            return 'A noble knight who served the King in the great castle, completing many quests across the kingdom';
-        if (contextLower.includes('sci-fi') || contextLower.includes('space'))
-            return 'A starship captain with years of deep space exploration';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'headline' field
-    if (fieldName === 'headline') {
-        // Check for name mentions in context for personalized headlines
-        if (contextLower.includes('codehelper'))
-            return 'CodeHelper: Dev Tools';
-        if (contextLower.includes('techcorp'))
-            return 'TechCorp Solutions';
-        if (contextLower.includes('software engineer'))
-            return 'For Dev Teams';
-        if (contextLower.includes('tech') || contextLower.includes('startup'))
-            return 'Tech Startup Solutions';
-        return `Headline for ${type}`.slice(0, 30);
-    }
-    // For 'copy' field
-    if (fieldName === 'copy') {
-        if (contextLower.includes('tech') || contextLower.includes('startup'))
-            return 'Innovative tech solutions for startups and growing companies';
-        if (contextLower.includes('marketing') || contextLower.includes('campaign'))
-            return 'Effective marketing campaign for tech launch';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'tagline' field
-    if (fieldName === 'tagline') {
-        if (contextLower.includes('luxury') || contextLower.includes('premium'))
-            return 'Luxury craftsmanship meets elegant design';
-        if (contextLower.includes('quality') || contextLower.includes('craftsmanship'))
-            return 'Premium quality with expert craftsmanship';
-        if (contextLower.includes('tech'))
-            return 'Technology for the future';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'description' field
-    if (fieldName === 'description') {
-        if (contextLower.includes('cyberpunk') || contextLower.includes('neon') || contextLower.includes('futuristic'))
-            return 'Cyberpunk character with neural augmentations';
-        if (contextLower.includes('luxury') || contextLower.includes('high-end') || contextLower.includes('premium'))
-            return 'A luxury premium product with elegant craftsmanship';
-        if (contextLower.includes('enterprise') || contextLower.includes('b2b'))
-            return 'Enterprise solution for business customers';
-        if (contextLower.includes('nurse') || contextLower.includes('healthcare'))
-            return 'Healthcare documentation solution for nurses and medical staff';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'abilities' field
-    if (fieldName === 'abilities') {
-        if (contextLower.includes('cyberpunk') || contextLower.includes('futuristic'))
-            return 'Neural hacking and digital infiltration';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'method' field
-    if (fieldName === 'method') {
-        if (hintLower.includes('wit') || hintLower.includes('sharp'))
-            return 'Brilliant deduction and clever observation';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'expertise' field
-    if (fieldName === 'expertise') {
-        if (contextLower.includes('machine learning') || contextLower.includes('medical') || contextLower.includes('ai'))
-            return 'Machine learning for medical applications';
-        if (hintLower.includes('physics') || hintLower.includes('professor'))
-            return 'Physics professor specializing in quantum mechanics';
-        if (hintLower.includes('journalist') || hintLower.includes('science'))
-            return 'Science journalist covering physics research';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'focus' field
-    if (fieldName === 'focus') {
-        if (contextLower.includes('renewable') || contextLower.includes('energy') || contextLower.includes('green'))
-            return 'Focus on sustainable energy transformation';
-        if (contextLower.includes('tech') || contextLower.includes('programming'))
-            return 'Focus on technical programming topics';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'qualifications' field
-    if (fieldName === 'qualifications') {
-        if (contextLower.includes('astrophysics') || contextLower.includes('astronomy') || contextLower.includes('space'))
-            return 'PhD in Astrophysics from MIT';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'teachingStyle' field
-    if (fieldName === 'teachingStyle') {
-        if (contextLower.includes('beginner') || contextLower.includes('introduct'))
-            return 'Patient and accessible approach for beginners';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'experience' field
-    if (fieldName === 'experience') {
-        if (contextLower.includes('horror') || contextLower.includes('film'))
-            return 'Experience in horror film production';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'role' field
-    if (fieldName === 'role') {
-        if (hintLower.includes('research') || hintLower.includes('machine learning') || hintLower.includes('phd'))
-            return 'Machine learning researcher';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // For 'portfolio' field
-    if (fieldName === 'portfolio') {
-        if (hintLower.includes('award') || hintLower.includes('beaux-arts') || hintLower.includes('ecole'))
-            return 'Award-winning design portfolio from Beaux-Arts';
-        return `${fieldName}: ${fullContext}`;
-    }
-    // Default: include context in the generated value
-    return `${fieldName}: ${fullContext}`;
+    // Use the configured value generator
+    // Note: This is synchronous, so we rely on PlaceholderValueGenerator's sync method
+    // If a custom generator is configured, it must support synchronous generation
+    const generator = currentValueGenerator;
+    // If it's a PlaceholderValueGenerator, use the sync method
+    if (generator instanceof PlaceholderValueGenerator) {
+        return generator.generateSync({
+            fieldName,
+            type,
+            fullContext,
+            parentData,
+            ...(hint !== undefined && { hint }),
+        });
+    }
+    // For non-PlaceholderValueGenerator instances, fall back to placeholder
+    // for backward compatibility (async generators require different call pattern)
+    return placeholderGenerator.generateSync({
+        fieldName,
+        type,
+        fullContext,
+        parentData,
+        ...(hint !== undefined && { hint }),
+    });
 }
 // =============================================================================
 // AI Field Generation
 // =============================================================================
+/**
+ * Build a combined entity object with pre-fetched context data merged in.
+ * This replaces UUID references with actual entity objects for template resolution.
+ */
+function buildCombinedEntityWithContext(entityData, contextData) {
+    const combined = { ...entityData };
+    // Sort context keys by length so we process parent paths before nested paths
+    // This ensures 'project' is set before 'project.lead'
+    const sortedKeys = [...contextData.keys()].sort((a, b) => a.length - b.length);
+    for (const key of sortedKeys) {
+        const value = contextData.get(key);
+        const pathParts = key.split('.');
+        if (pathParts.length === 1) {
+            // Simple path like 'project' - set at top level if currently a UUID
+            const currentValue = combined[key];
+            const isCurrentUUID = typeof currentValue === 'string' && currentValue.includes('-');
+            if (!combined[key] || isCurrentUUID) {
+                combined[key] = { ...value };
+            }
+        }
+        else {
+            // Nested path like 'project.lead' - traverse and set nested value
+            let current = combined;
+            for (let i = 0; i < pathParts.length - 1; i++) {
+                const part = pathParts[i];
+                if (current[part] && typeof current[part] === 'object') {
+                    current = current[part];
+                }
+                else {
+                    break;
+                }
+            }
+            const lastPart = pathParts[pathParts.length - 1];
+            if (current && typeof current === 'object') {
+                current[lastPart] = value;
+            }
+        }
+        // Add leaf entity at top level for direct access (e.g., {lead.name})
+        if (pathParts.length > 1 && typeof value === 'object' && value !== null) {
+            const leafKey = pathParts[pathParts.length - 1];
+            if (!combined[leafKey]) {
+                combined[leafKey] = value;
+            }
+        }
+    }
+    return combined;
+}
+/**
+ * Build a context string from entity data and pre-fetched context.
+ * Extracts string fields (excluding internal fields) and formats them for AI context.
+ */
+function buildContextString(resolvedInstructions, entityData, contextData) {
+    const parts = [];
+    if (resolvedInstructions) {
+        parts.push(resolvedInstructions);
+    }
+    // Add entity data fields
+    for (const [key, value] of Object.entries(entityData)) {
+        if (!key.startsWith('$') && !key.startsWith('_') && typeof value === 'string' && value) {
+            parts.push(`${key}: ${value}`);
+        }
+    }
+    // Add context from pre-fetched entities
+    for (const [key, ctxEntity] of contextData) {
+        for (const [fieldName, fieldValue] of Object.entries(ctxEntity)) {
+            if (!fieldName.startsWith('$') &&
+                !fieldName.startsWith('_') &&
+                typeof fieldValue === 'string' &&
+                fieldValue) {
+                parts.push(`${key}.${fieldName}: ${fieldValue}`);
+            }
+        }
+    }
+    return parts.join(' | ');
+}
 /**
  * Generate AI fields based on $instructions and field prompts
  *
@@ -224,13 +339,15 @@ export function generateContextAwareValue(fieldName, type, fullContext, hint, pa
  * @param entityDef - The parsed entity definition
  * @param schema - The parsed schema
  * @param provider - The database provider
+ * @param injectedConfig - Optional AI config to use instead of module-level config (for DI)
  * @returns The data with AI-generated fields populated
  */
-export async function generateAIFields(data, typeName, entityDef, schema, provider) {
+export async function generateAIFields(data, typeName, entityDef, schema, provider, injectedConfig) {
+    const config = injectedConfig ?? aiConfig;
     const result = { ...data };
     const entitySchema = entityDef.schema || {};
-    const instructions = entitySchema.$instructions;
-    const contextDeps = entitySchema.$context;
+    const instructions = entitySchema['$instructions'];
+    const contextDeps = entitySchema['$context'];
     // Pre-fetch context dependencies if declared
     let contextData = new Map();
     if (contextDeps && Array.isArray(contextDeps)) {
@@ -239,54 +356,91 @@ export async function generateAIFields(data, typeName, entityDef, schema, provid
     // Resolve instructions template variables
     let resolvedInstructions = instructions;
     if (instructions) {
-        // Build a combined entity with context data for template resolution
-        const combinedEntity = { ...result };
-        for (const [key, value] of contextData) {
-            const topLevelKey = key.split('.')[0];
-            if (!combinedEntity[topLevelKey]) {
-                combinedEntity[topLevelKey] = value;
-            }
-        }
+        const combinedEntity = buildCombinedEntityWithContext(result, contextData);
         resolvedInstructions = await resolveInstructions(instructions, combinedEntity, typeName, schema, provider);
     }
-    // Build context string from resolved instructions and entity data
-    const contextParts = [];
-    if (resolvedInstructions)
-        contextParts.push(resolvedInstructions);
-    // Add relevant entity data as context
-    for (const [key, value] of Object.entries(result)) {
-        if (!key.startsWith('$') && !key.startsWith('_') && typeof value === 'string' && value) {
-            contextParts.push(`${key}: ${value}`);
+    const fullContext = buildContextString(resolvedInstructions, result, contextData);
+    // Collect fields that need generation
+    const fieldsToGenerate = [];
+    // When entity has $context or template variables, allow regenerating draft-generated prompt fields
+    const hasRichContext = !!(contextDeps && contextDeps.length > 0) || !!(instructions && instructions.includes('{'));
+    for (const [fieldName, field] of entityDef.fields) {
+        // Skip relation fields (handled separately)
+        if (field.isRelation) {
+            continue;
+        }
+        const isPrompt = isPromptField(field);
+        // Skip if value already provided (unless AI can improve it)
+        if (result[fieldName] !== undefined && result[fieldName] !== null) {
+            // When AI is enabled, always attempt to generate prompt fields
+            // (overriding draft-generated placeholder values with AI-generated content).
+            // When AI is disabled, skip already-populated fields unless rich context is available.
+            if (isPrompt && (config.enabled || hasRichContext)) {
+                fieldsToGenerate.push({ fieldName, prompt: field.type });
+            }
+            continue;
+        }
+        if (isPrompt) {
+            // Use the field type (which is actually the prompt) as the prompt
+            fieldsToGenerate.push({ fieldName, prompt: field.type });
+        }
+        else if (field.type === 'string' && instructions) {
+            // Generate plain string fields when we have $instructions context
+            fieldsToGenerate.push({ fieldName, prompt: undefined });
         }
     }
-    // Add context from pre-fetched entities
-    for (const [key, ctxEntity] of contextData) {
-        for (const [fieldName, fieldValue] of Object.entries(ctxEntity)) {
-            if (!fieldName.startsWith('$') && !fieldName.startsWith('_') && typeof fieldValue === 'string' && fieldValue) {
-                contextParts.push(`${key}.${fieldName}: ${fieldValue}`);
+    // Try AI generation for all fields that need it
+    if (fieldsToGenerate.length > 0 && config.enabled) {
+        try {
+            const { generateObject } = await import('ai-functions');
+            // Build a schema for all fields to generate
+            const fieldsSchema = {};
+            for (const { fieldName, prompt } of fieldsToGenerate) {
+                fieldsSchema[fieldName] = prompt || `Generate a ${fieldName}`;
+            }
+            // Build prompt with resolved instructions
+            const promptParts = [];
+            if (resolvedInstructions) {
+                promptParts.push(resolvedInstructions);
+            }
+            promptParts.push(`Generate a ${typeName} with the following fields.`);
+            const aiPrompt = promptParts.join('\n');
+            const aiResult = await generateObject({
+                model: config.model,
+                schema: fieldsSchema,
+                prompt: aiPrompt,
+            });
+            // Apply generated values
+            const generated = aiResult.object;
+            for (const { fieldName } of fieldsToGenerate) {
+                if (generated[fieldName] !== undefined) {
+                    result[fieldName] = generated[fieldName];
+                }
             }
         }
+        catch (error) {
+            // Throw AIGenerationError - don't silently fall back to placeholder
+            const cause = error instanceof Error ? error : undefined;
+            throw new AIGenerationError(cause?.message || 'Unknown AI field generation failure', typeName, undefined, cause);
+        }
     }
-    const fullContext = contextParts.join(' | ');
-    // Generate values for prompt fields that don't have values
-    for (const [fieldName, field] of entityDef.fields) {
-        // Skip if value already provided
-        if (result[fieldName] !== undefined && result[fieldName] !== null)
-            continue;
-        // Skip relation fields (handled separately)
-        if (field.isRelation)
-            continue;
-        // Check if this is a prompt field (type contains spaces) or needs generation
-        const fieldDef = entitySchema[fieldName];
-        const isPrompt = typeof fieldDef === 'string' && fieldDef.includes(' ') && !fieldDef.includes('->');
-        if (isPrompt || (field.type === 'string' && !isPrimitiveType(field.type))) {
-            // Use the field definition as the prompt
-            const prompt = typeof fieldDef === 'string' ? fieldDef : undefined;
+    // Fill in any remaining fields with placeholder values
+    for (const { fieldName, prompt } of fieldsToGenerate) {
+        if (result[fieldName] === undefined || result[fieldName] === null) {
             result[fieldName] = generateContextAwareValue(fieldName, typeName, fullContext, prompt, result);
         }
-        else if (field.type === 'string' && instructions) {
-            // Generate string fields when we have $instructions context
-            result[fieldName] = generateContextAwareValue(fieldName, typeName, fullContext, undefined, result);
+    }
+    // Enforce length constraints from field type hints like 'string (30 chars)'
+    for (const { fieldName, prompt } of fieldsToGenerate) {
+        if (typeof result[fieldName] === 'string' && prompt) {
+            const charMatch = prompt.match(/\((\d+)\s*chars?\)/);
+            if (charMatch) {
+                const maxLen = parseInt(charMatch[1], 10);
+                const value = result[fieldName];
+                if (value.length > maxLen) {
+                    result[fieldName] = value.slice(0, maxLen);
+                }
+            }
         }
     }
     return result;
@@ -294,27 +448,87 @@ export async function generateAIFields(data, typeName, entityDef, schema, provid
 // =============================================================================
 // Entity Generation
 // =============================================================================
+/**
+ * Check if a field is a backward relation to a specific parent type
+ */
+function isBackwardRelationToParent(field, parentType) {
+    return (field.operator === '<-' && field.direction === 'backward' && field.relatedType === parentType);
+}
+/**
+ * Check if a field is a required forward single relation (not array, not optional)
+ */
+function isRequiredForwardSingleRelation(field) {
+    return (field.operator === '->' && field.direction === 'forward' && !field.isArray && !field.isOptional);
+}
+/**
+ * Process relation fields and populate data with backward refs and pending forward relations
+ *
+ * This shared helper handles relations consistently whether AI generation succeeded
+ * or fell back to placeholder generation.
+ */
+async function processRelationFields(data, entity, type, context, schema, _depth, injectedConfig) {
+    for (const [fieldName, field] of entity.fields) {
+        if (!field.isRelation)
+            continue;
+        if (isBackwardRelationToParent(field, context.parent) && context.parentId) {
+            data[fieldName] = context.parentId;
+        }
+        else if (isRequiredForwardSingleRelation(field)) {
+            const nestedGenerated = await generateEntity(field.relatedType, field.prompt, { parent: type, parentData: data }, schema, _depth + 1, injectedConfig);
+            data[`_pending_${fieldName}`] = { type: field.relatedType, data: nestedGenerated };
+        }
+    }
+}
 /**
  * Generate an entity based on its type and context
  *
- * For testing, generates deterministic content based on the prompt and type.
- * In production, this would integrate with AI generation.
+ * Uses AI generation via generateObject from ai-functions when available,
+ * falling back to deterministic placeholder values for testing or when AI fails.
  *
  * @param type - The type of entity to generate
  * @param prompt - Optional prompt for generation context
  * @param context - Parent context information (parent type name, parentData, and optional parentId)
  * @param schema - The parsed schema
+ * @param _depth - Current recursion depth (internal)
+ * @param injectedConfig - Optional AI config to use instead of module-level config (for DI)
  */
-export async function generateEntity(type, prompt, context, schema) {
+export async function generateEntity(type, prompt, context, schema, _depth = 0, injectedConfig) {
+    // Hard recursion guard to prevent infinite recursion with circular schemas
+    if (_depth >= DEFAULT_MAX_DEPTH) {
+        return {};
+    }
     const entity = schema.entities.get(type);
     if (!entity)
         throw new Error(`Unknown type: ${type}`);
     // Gather context for generation
     const parentEntity = schema.entities.get(context.parent);
     const parentSchema = parentEntity?.schema || {};
-    const instructions = parentSchema.$instructions;
-    const schemaContext = parentSchema.$context;
-    // Extract relevant parent data for context (excluding metadata fields)
+    const instructions = parentSchema['$instructions'];
+    const schemaContext = parentSchema['$context'];
+    // Try AI-powered generation first
+    let aiGeneratedData = null;
+    try {
+        aiGeneratedData = await generateEntityDataWithAI(type, entity, prompt, {
+            parentData: context.parentData,
+            ...(instructions !== undefined && { instructions }),
+            ...(schemaContext !== undefined && { schemaContext }),
+        }, injectedConfig);
+    }
+    catch (error) {
+        // If AI generation fails (e.g., ai-functions not available in tests),
+        // fall through to placeholder generation below
+        if (!(error instanceof AIGenerationError)) {
+            throw error; // Re-throw unexpected errors
+        }
+        // AIGenerationError: fall through to placeholder generation
+    }
+    // If AI generation succeeded, use that data but still handle relations
+    if (aiGeneratedData) {
+        const data = { ...aiGeneratedData };
+        await processRelationFields(data, entity, type, context, schema, _depth, injectedConfig);
+        return data;
+    }
+    // Fallback to placeholder generation if AI is not available or failed
     const parentContextFields = [];
     for (const [key, value] of Object.entries(context.parentData)) {
         if (!key.startsWith('$') && !key.startsWith('_') && typeof value === 'string' && value) {
@@ -335,35 +549,21 @@ export async function generateEntity(type, prompt, context, schema) {
     const data = {};
     for (const [fieldName, field] of entity.fields) {
         if (!field.isRelation) {
-            if (field.type === 'string') {
-                // Generate context-aware content
-                data[fieldName] = generateContextAwareValue(fieldName, type, fullContext, prompt, context.parentData);
-            }
-            else if (field.isArray && field.type === 'string') {
-                // Generate array of strings
-                data[fieldName] = [generateContextAwareValue(fieldName, type, fullContext, prompt, context.parentData)];
-            }
-        }
-        else if (field.operator === '<-' && field.direction === 'backward') {
-            // Backward relation to parent - set the parent's ID if this entity's
-            // related type matches the parent type
-            if (field.relatedType === context.parent && context.parentId) {
-                // Store the parent ID directly - this is a reference back to the parent
-                data[fieldName] = context.parentId;
+            const isPrompt = isPromptField(field);
+            if (field.type === 'string' || isPrompt) {
+                const fieldHint = isPrompt ? field.type : prompt;
+                data[fieldName] = generateContextAwareValue(fieldName, type, fullContext, fieldHint, context.parentData);
             }
-        }
-        else if (field.operator === '->' && field.direction === 'forward') {
-            // Recursively generate nested forward exact relations
-            // This handles cases like Person.bio -> Bio
-            if (!field.isOptional) {
-                const nestedGenerated = await generateEntity(field.relatedType, field.prompt, { parent: type, parentData: data }, schema);
-                // We need to create the nested entity too, but we can't do that here
-                // because we don't have access to the provider yet.
-                // This will be handled by resolveForwardExact when it calls us
-                data[`_pending_${fieldName}`] = { type: field.relatedType, data: nestedGenerated };
+            else if (field.isArray && (field.type === 'string' || isPrompt)) {
+                const fieldHint = isPrompt ? field.type : prompt;
+                data[fieldName] = [
+                    generateContextAwareValue(fieldName, type, fullContext, fieldHint, context.parentData),
+                ];
             }
         }
     }
+    // Process relation fields using shared helper
+    await processRelationFields(data, entity, type, context, schema, _depth, injectedConfig);
     return data;
 }
 // =============================================================================
@@ -402,7 +602,11 @@ export async function resolveForwardExact(typeName, data, entity, schema, provid
                 continue;
             if (field.isArray) {
                 // Forward array relation - check if we should auto-generate
-                const relatedEntity = schema.entities.get(field.relatedType);
+                // For union types, use the first union type as the generation target
+                const generateType = field.unionTypes && field.unionTypes.length > 0
+                    ? field.unionTypes[0]
+                    : field.relatedType;
+                const relatedEntity = schema.entities.get(generateType);
                 if (!relatedEntity)
                     continue;
                 // Check if related entity has a backward ref to this type (symmetric relationship)
@@ -426,31 +630,41 @@ export async function resolveForwardExact(typeName, data, entity, schema, provid
                 // Decide whether to auto-generate:
                 // - If there's a symmetric backward ref AND required scalars, skip (prevents duplicates)
                 // - Otherwise, generate if the related entity can be meaningfully generated
-                const shouldSkip = hasBackwardRef && hasRequiredScalarFields;
-                const canGenerate = !shouldSkip && (hasBackwardRef || // Symmetric ref without required scalars
-                    field.prompt || // Has a generation prompt
-                    !hasRequiredScalarFields // No required fields to worry about
-                );
+                // - For union types, always allow generation (we have explicit type to generate)
+                const hasUnionTypes = field.unionTypes && field.unionTypes.length > 0;
+                const shouldSkip = hasBackwardRef && hasRequiredScalarFields && !hasUnionTypes;
+                const canGenerate = !shouldSkip &&
+                    (hasBackwardRef || // Symmetric ref without required scalars
+                        field.prompt || // Has a generation prompt
+                        !hasRequiredScalarFields || // No required fields to worry about
+                        hasUnionTypes); // Union types should generate the first type
                 if (!canGenerate)
                     continue;
-                const generated = await generateEntity(field.relatedType, field.prompt, { parent: typeName, parentData: data, parentId }, schema);
+                const generated = await generateEntity(generateType, field.prompt, { parent: typeName, parentData: data, parentId }, schema);
                 // Resolve any pending nested relations in the generated data
                 const resolvedGenerated = await resolveNestedPending(generated, relatedEntity, schema, provider);
-                const created = await provider.create(field.relatedType, undefined, resolvedGenerated);
-                resolved[fieldName] = [created.$id];
+                const created = await provider.create(generateType, undefined, {
+                    ...resolvedGenerated,
+                    $matchedType: generateType,
+                });
+                resolved[fieldName] = [created['$id']];
+                resolved[`${fieldName}$matchedType`] = generateType;
                 // Queue relationship creation for after parent entity is created
-                pendingRelations.push({ fieldName, targetType: field.relatedType, targetId: created.$id });
+                pendingRelations.push({
+                    fieldName,
+                    targetType: generateType,
+                    targetId: created['$id'],
+                });
             }
             else {
                 // Single non-optional forward relation - generate the related entity
-                // Generate single entity
                 const generated = await generateEntity(field.relatedType, field.prompt, { parent: typeName, parentData: data, parentId }, schema);
                 // Resolve any pending nested relations in the generated data
                 const relatedEntity = schema.entities.get(field.relatedType);
                 if (relatedEntity) {
                     const resolvedGenerated = await resolveNestedPending(generated, relatedEntity, schema, provider);
                     const created = await provider.create(field.relatedType, undefined, resolvedGenerated);
-                    resolved[fieldName] = created.$id;
+                    resolved[fieldName] = created['$id'];
                 }
             }
         }
@@ -472,10 +686,10 @@ export function generateNaturalLanguageContent(fieldName, prompt, targetType, co
         // Extract key words from prompt for natural language
         const keyWords = prompt.toLowerCase();
         if (keyWords.includes('idea') || keyWords.includes('concept')) {
-            return `A innovative idea for ${context.name || targetType}`;
+            return `A innovative idea for ${context['name'] || targetType}`;
         }
         if (keyWords.includes('customer') || keyWords.includes('buyer') || keyWords.includes('user')) {
-            return `The target customer segment for ${context.name || targetType}`;
+            return `The target customer segment for ${context['name'] || targetType}`;
         }
         if (keyWords.includes('related') || keyWords.includes('similar')) {
             return `Related ${targetType.toLowerCase()} content`;
@@ -487,37 +701,41 @@ export function generateNaturalLanguageContent(fieldName, prompt, targetType, co
     // Generate based on field name patterns
     const fieldLower = fieldName.toLowerCase();
     if (fieldLower.includes('idea')) {
-        return `A compelling idea for ${context.name || 'the project'}`;
+        return `A compelling idea for ${context['name'] || 'the project'}`;
     }
     if (fieldLower.includes('customer')) {
-        return `The ideal customer for ${context.name || 'the business'}`;
+        return `The ideal customer for ${context['name'] || 'the business'}`;
     }
-    if (fieldLower.includes('founder') || fieldLower.includes('lead') || fieldLower.includes('ceo') || fieldLower.includes('cto') || fieldLower.includes('cfo')) {
+    if (fieldLower.includes('founder') ||
+        fieldLower.includes('lead') ||
+        fieldLower.includes('ceo') ||
+        fieldLower.includes('cto') ||
+        fieldLower.includes('cfo')) {
         return `A qualified ${fieldName} candidate`;
     }
     if (fieldLower.includes('author') || fieldLower.includes('reviewer')) {
         return `An experienced ${fieldName}`;
     }
     if (fieldLower.includes('assignee') || fieldLower.includes('owner')) {
-        return `The right person for ${context.title || context.name || 'this task'}`;
+        return `The right person for ${context['title'] || context['name'] || 'this task'}`;
     }
     if (fieldLower.includes('department') || fieldLower.includes('team')) {
-        return `A department for ${context.name || 'the organization'}`;
+        return `A department for ${context['name'] || 'the organization'}`;
     }
     if (fieldLower.includes('client') || fieldLower.includes('sponsor')) {
-        return `A ${fieldName} for ${context.name || context.title || 'the project'}`;
+        return `A ${fieldName} for ${context['name'] || context['title'] || 'the project'}`;
     }
     if (fieldLower.includes('item') || fieldLower.includes('component')) {
         return `${targetType} component`;
     }
     if (fieldLower.includes('member') || fieldLower.includes('project')) {
-        return `${targetType} for ${context.name || 'the team'}`;
+        return `${targetType} for ${context['name'] || 'the team'}`;
     }
     if (fieldLower.includes('character')) {
-        return `A character for ${context.title || context.name || 'the story'}`;
+        return `A character for ${context['title'] || context['name'] || 'the story'}`;
     }
     if (fieldLower.includes('setting') || fieldLower.includes('location')) {
-        return `A setting for ${context.title || context.name || 'the story'}`;
+        return `A setting for ${context['title'] || context['name'] || 'the story'}`;
     }
     if (fieldLower.includes('address')) {
         return `Address information`;