ai-database 2.1.1 → 2.3.0

package/dist/schema/value-generators/ai.js

@@ -0,0 +1,136 @@
+/**
+ * AIValueGenerator Implementation
+ *
+ * Generates values using AI/LLM integration for production use.
+ * Supports context-aware generation with parent chain and array context.
+ *
+ * @packageDocumentation
+ */
+import { PlaceholderValueGenerator } from './placeholder.js';
+/**
+ * AIValueGenerator
+ *
+ * Generates values using an AI function for production use.
+ * Builds rich context from parent chain, previous generations, and array context.
+ */
+export class AIValueGenerator {
+    aiFunction;
+    model;
+    maxTokens;
+    temperature;
+    fallbackToPlaceholder;
+    placeholderGenerator;
+    constructor(config) {
+        this.aiFunction = config.aiFunction;
+        if (config.model !== undefined)
+            this.model = config.model;
+        if (config.maxTokens !== undefined)
+            this.maxTokens = config.maxTokens;
+        if (config.temperature !== undefined)
+            this.temperature = config.temperature;
+        this.fallbackToPlaceholder = config.fallbackToPlaceholder ?? false;
+        this.placeholderGenerator = new PlaceholderValueGenerator();
+    }
+    /**
+     * Generate a value using AI
+     *
+     * @param request - The generation request
+     * @returns Promise resolving to the generated value with metadata
+     */
+    async generate(request) {
+        try {
+            const prompt = this.buildPrompt(request);
+            const response = await this.aiFunction(prompt);
+            const metadata = {
+                source: 'ai',
+            };
+            if (this.model !== undefined)
+                metadata.model = this.model;
+            if (response.usage?.tokens !== undefined)
+                metadata.tokens = response.usage.tokens;
+            return {
+                value: response.text,
+                metadata,
+            };
+        }
+        catch (error) {
+            if (this.fallbackToPlaceholder) {
+                const placeholderResult = await this.placeholderGenerator.generate(request);
+                return {
+                    value: placeholderResult.value,
+                    metadata: {
+                        source: 'placeholder',
+                        fallback: true,
+                    },
+                };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Build a prompt from the generation request
+     *
+     * Combines field info, context, hints, and generation context
+     * into a comprehensive prompt for the AI.
+     */
+    buildPrompt(request) {
+        const parts = [];
+        // Add field and type context
+        parts.push(`Generate a value for field "${request.fieldName}" on type "${request.type}".`);
+        // Add full context if available
+        if (request.fullContext) {
+            parts.push(`Context: ${request.fullContext}`);
+        }
+        // Add hint if available
+        if (request.hint) {
+            parts.push(`Hint: ${request.hint}`);
+        }
+        // Add parent data context
+        if (request.parentData && Object.keys(request.parentData).length > 0) {
+            const parentEntries = Object.entries(request.parentData)
+                .filter(([key, value]) => !key.startsWith('$') && !key.startsWith('_') && typeof value === 'string')
+                .map(([key, value]) => `${key}: ${value}`)
+                .join(', ');
+            if (parentEntries) {
+                parts.push(`Parent data: ${parentEntries}`);
+            }
+        }
+        // Add generation context if available
+        const genCtx = request.generationContext;
+        if (genCtx) {
+            // Add parent chain context
+            if (genCtx.parentChain && genCtx.parentChain.length > 0) {
+                const chainInfo = genCtx.parentChain
+                    .map((entity) => {
+                    const name = entity['name'] || entity['title'] || entity.$id;
+                    return `${entity.$type}: ${name}`;
+                })
+                    .join(' > ');
+                parts.push(`Parent chain: ${chainInfo}`);
+            }
+            // Add previously generated entities
+            if (genCtx.previouslyGenerated && genCtx.previouslyGenerated.length > 0) {
+                const prevInfo = genCtx.previouslyGenerated
+                    .map((entity) => {
+                    const name = entity['name'] || entity['title'] || entity.$id;
+                    return `${entity.$type}: ${name}`;
+                })
+                    .join(', ');
+                parts.push(`Previously generated: ${prevInfo}`);
+            }
+            // Add array context
+            if (genCtx.arrayContext) {
+                const { fieldName, previousItems, index } = genCtx.arrayContext;
+                parts.push(`Array field: ${fieldName}, generating item ${index + 1}`);
+                if (previousItems.length > 0) {
+                    const prevItemsInfo = previousItems
+                        .map((item) => item['name'] || item['title'] || item.$id)
+                        .join(', ');
+                    parts.push(`Previous items: ${prevItemsInfo}`);
+                }
+            }
+        }
+        return parts.join('\n');
+    }
+}
+//# sourceMappingURL=ai.js.map

package/dist/schema/value-generators/ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.js","sourceRoot":"","sources":["../../../src/schema/value-generators/ai.ts"],"names":[],"mappings":"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"}

package/dist/schema/value-generators/index.d.ts

@@ -0,0 +1,126 @@
+/**
+ * ValueGenerator Module
+ *
+ * Strategy pattern for value generation during entity creation.
+ * Supports both placeholder (deterministic test fixtures) and
+ * AI-powered (production) generation.
+ *
+ * @example
+ * ```typescript
+ * // Use placeholder generator for testing
+ * const generator = createValueGenerator({ type: 'placeholder' })
+ * const result = await generator.generate({
+ *   fieldName: 'name',
+ *   type: 'Person',
+ *   fullContext: 'tech entrepreneur startup',
+ * })
+ *
+ * // Configure global generator for AI in production
+ * configureValueGenerator({
+ *   type: 'ai',
+ *   aiFunction: async (prompt) => ({ text: await callAI(prompt) }),
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { GenerationRequest, GenerationResult, GenerationMetadata, ValueGenerator, ValueGeneratorConfig, AIFunction, ArrayContext, GenerationContextData, } from './types.js';
+export { PlaceholderValueGenerator } from './placeholder.js';
+export { AIValueGenerator } from './ai.js';
+export type { AIValueGeneratorConfig } from './ai.js';
+import type { ValueGenerator, ValueGeneratorConfig } from './types.js';
+/**
+ * Create a ValueGenerator based on configuration
+ *
+ * @param config - Generator configuration
+ * @returns A new ValueGenerator instance
+ * @throws Error if AI type is specified without aiFunction
+ *
+ * @example
+ * ```typescript
+ * // Create placeholder generator (default)
+ * const placeholderGen = createValueGenerator()
+ *
+ * // Create placeholder generator explicitly
+ * const placeholderGen = createValueGenerator({ type: 'placeholder' })
+ *
+ * // Create AI generator
+ * const aiGen = createValueGenerator({
+ *   type: 'ai',
+ *   aiFunction: async (prompt) => ({ text: 'AI response' }),
+ * })
+ * ```
+ */
+export declare function createValueGenerator(config?: ValueGeneratorConfig): ValueGenerator;
+/**
+ * Configure the global default value generator
+ *
+ * Call this at application startup to set the default generator
+ * that will be used throughout the application.
+ *
+ * @param config - Generator configuration
+ *
+ * @example
+ * ```typescript
+ * // Use placeholder for testing
+ * configureValueGenerator({ type: 'placeholder' })
+ *
+ * // Use AI for production
+ * configureValueGenerator({
+ *   type: 'ai',
+ *   aiFunction: myAIFunction,
+ *   model: 'claude-3',
+ *   fallbackToPlaceholder: true,
+ * })
+ * ```
+ */
+export declare function configureValueGenerator(config: ValueGeneratorConfig): void;
+/**
+ * Get the current global value generator
+ *
+ * Returns the configured generator instance, creating one if needed.
+ * Use this to get the generator configured via configureValueGenerator.
+ *
+ * @returns The current ValueGenerator instance
+ *
+ * @example
+ * ```typescript
+ * const generator = getValueGenerator()
+ * const result = await generator.generate({
+ *   fieldName: 'description',
+ *   type: 'Product',
+ * })
+ * ```
+ */
+export declare function getValueGenerator(): ValueGenerator;
+/**
+ * Generate a context-aware value for a field
+ *
+ * This is a convenience function that uses the global generator.
+ * Equivalent to calling `getValueGenerator().generate(request)`.
+ *
+ * @deprecated Use `getValueGenerator().generate()` instead
+ *
+ * @param fieldName - The name of the field being generated
+ * @param type - The entity type name
+ * @param fullContext - Combined context string
+ * @param hint - Optional hint text for guiding generation
+ * @param parentData - Parent entity data for context inheritance
+ * @returns A generated string value
+ */
+export declare function generateContextAwareValue(fieldName: string, type: string, fullContext: string, hint: string | undefined, parentData?: Record<string, unknown>): Promise<string>;
+/**
+ * Synchronous wrapper for generateContextAwareValue
+ *
+ * Uses the PlaceholderValueGenerator directly for synchronous calls.
+ * This maintains backward compatibility with existing cascade.ts code.
+ *
+ * @param fieldName - The name of the field being generated
+ * @param type - The entity type name
+ * @param fullContext - Combined context string
+ * @param hint - Optional hint text for guiding generation
+ * @param parentData - Parent entity data for context inheritance
+ * @returns A generated string value
+ */
+export declare function generateContextAwareValueSync(fieldName: string, type: string, fullContext: string, hint: string | undefined, parentData?: Record<string, unknown>): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/schema/value-generators/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/schema/value-generators/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,YAAY,EACZ,qBAAqB,GACtB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAC1C,YAAY,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAA;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AActE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,GAAE,oBAAyB,GAAG,cAAc,CAmBtF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAG1E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAKlD;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACvC,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACvC,MAAM,CA8CR"}

package/dist/schema/value-generators/index.js

@@ -0,0 +1,219 @@
+/**
+ * ValueGenerator Module
+ *
+ * Strategy pattern for value generation during entity creation.
+ * Supports both placeholder (deterministic test fixtures) and
+ * AI-powered (production) generation.
+ *
+ * @example
+ * ```typescript
+ * // Use placeholder generator for testing
+ * const generator = createValueGenerator({ type: 'placeholder' })
+ * const result = await generator.generate({
+ *   fieldName: 'name',
+ *   type: 'Person',
+ *   fullContext: 'tech entrepreneur startup',
+ * })
+ *
+ * // Configure global generator for AI in production
+ * configureValueGenerator({
+ *   type: 'ai',
+ *   aiFunction: async (prompt) => ({ text: await callAI(prompt) }),
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Re-export implementations
+export { PlaceholderValueGenerator } from './placeholder.js';
+export { AIValueGenerator } from './ai.js';
+import { PlaceholderValueGenerator } from './placeholder.js';
+import { AIValueGenerator } from './ai.js';
+// =============================================================================
+// Global Generator Configuration
+// =============================================================================
+/** Current global generator instance */
+let currentGenerator = null;
+/** Current configuration */
+let currentConfig = { type: 'placeholder' };
+/**
+ * Create a ValueGenerator based on configuration
+ *
+ * @param config - Generator configuration
+ * @returns A new ValueGenerator instance
+ * @throws Error if AI type is specified without aiFunction
+ *
+ * @example
+ * ```typescript
+ * // Create placeholder generator (default)
+ * const placeholderGen = createValueGenerator()
+ *
+ * // Create placeholder generator explicitly
+ * const placeholderGen = createValueGenerator({ type: 'placeholder' })
+ *
+ * // Create AI generator
+ * const aiGen = createValueGenerator({
+ *   type: 'ai',
+ *   aiFunction: async (prompt) => ({ text: 'AI response' }),
+ * })
+ * ```
+ */
+export function createValueGenerator(config = {}) {
+    const type = config.type ?? 'placeholder';
+    if (type === 'ai') {
+        if (!config.aiFunction) {
+            throw new Error('aiFunction is required when creating an AI value generator');
+        }
+        const aiConfig = {
+            aiFunction: config.aiFunction,
+        };
+        if (config.model !== undefined)
+            aiConfig.model = config.model;
+        if (config.maxTokens !== undefined)
+            aiConfig.maxTokens = config.maxTokens;
+        if (config.temperature !== undefined)
+            aiConfig.temperature = config.temperature;
+        if (config.fallbackToPlaceholder !== undefined)
+            aiConfig.fallbackToPlaceholder = config.fallbackToPlaceholder;
+        return new AIValueGenerator(aiConfig);
+    }
+    return new PlaceholderValueGenerator();
+}
+/**
+ * Configure the global default value generator
+ *
+ * Call this at application startup to set the default generator
+ * that will be used throughout the application.
+ *
+ * @param config - Generator configuration
+ *
+ * @example
+ * ```typescript
+ * // Use placeholder for testing
+ * configureValueGenerator({ type: 'placeholder' })
+ *
+ * // Use AI for production
+ * configureValueGenerator({
+ *   type: 'ai',
+ *   aiFunction: myAIFunction,
+ *   model: 'claude-3',
+ *   fallbackToPlaceholder: true,
+ * })
+ * ```
+ */
+export function configureValueGenerator(config) {
+    currentConfig = { ...config };
+    currentGenerator = null; // Reset so next getValueGenerator creates a new instance
+}
+/**
+ * Get the current global value generator
+ *
+ * Returns the configured generator instance, creating one if needed.
+ * Use this to get the generator configured via configureValueGenerator.
+ *
+ * @returns The current ValueGenerator instance
+ *
+ * @example
+ * ```typescript
+ * const generator = getValueGenerator()
+ * const result = await generator.generate({
+ *   fieldName: 'description',
+ *   type: 'Product',
+ * })
+ * ```
+ */
+export function getValueGenerator() {
+    if (!currentGenerator) {
+        currentGenerator = createValueGenerator(currentConfig);
+    }
+    return currentGenerator;
+}
+// =============================================================================
+// Legacy Compatibility
+// =============================================================================
+/**
+ * Generate a context-aware value for a field
+ *
+ * This is a convenience function that uses the global generator.
+ * Equivalent to calling `getValueGenerator().generate(request)`.
+ *
+ * @deprecated Use `getValueGenerator().generate()` instead
+ *
+ * @param fieldName - The name of the field being generated
+ * @param type - The entity type name
+ * @param fullContext - Combined context string
+ * @param hint - Optional hint text for guiding generation
+ * @param parentData - Parent entity data for context inheritance
+ * @returns A generated string value
+ */
+export async function generateContextAwareValue(fieldName, type, fullContext, hint, parentData = {}) {
+    const generator = getValueGenerator();
+    const request = {
+        fieldName,
+        type,
+        fullContext,
+        parentData,
+    };
+    if (hint !== undefined)
+        request.hint = hint;
+    const result = await generator.generate(request);
+    return result.value;
+}
+/**
+ * Synchronous wrapper for generateContextAwareValue
+ *
+ * Uses the PlaceholderValueGenerator directly for synchronous calls.
+ * This maintains backward compatibility with existing cascade.ts code.
+ *
+ * @param fieldName - The name of the field being generated
+ * @param type - The entity type name
+ * @param fullContext - Combined context string
+ * @param hint - Optional hint text for guiding generation
+ * @param parentData - Parent entity data for context inheritance
+ * @returns A generated string value
+ */
+export function generateContextAwareValueSync(fieldName, type, fullContext, hint, parentData = {}) {
+    // Use placeholder generator directly for sync calls
+    const generator = new PlaceholderValueGenerator();
+    // Access the private generateValue method via the generate interface
+    // Since we know PlaceholderValueGenerator.generate is sync-compatible
+    const request = {
+        fieldName,
+        type,
+        fullContext,
+        parentData,
+    };
+    if (hint !== undefined)
+        request.hint = hint;
+    // We can safely synchronously return since PlaceholderValueGenerator
+    // doesn't actually do any async work in its current implementation
+    let result = '';
+    void generator.generate(request).then((r) => {
+        result = r.value;
+    });
+    // For true sync behavior, we need to inline the logic
+    // This duplicates the logic but maintains backward compatibility
+    const value = parentData[fieldName];
+    if (typeof value === 'string' && value) {
+        return value;
+    }
+    if (!fullContext || fullContext.trim() === '') {
+        return `Generated ${fieldName} for ${type}`;
+    }
+    const contextLower = fullContext.toLowerCase();
+    const hintLower = (hint || '').toLowerCase();
+    // Minimal subset of field handlers for common cases
+    // Full logic is in PlaceholderValueGenerator
+    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 all other fields, use a basic fallback
+    return `${fieldName}: ${fullContext}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/schema/value-generators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/schema/value-generators/index.ts"],"names":[],"mappings":"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"}

package/dist/schema/value-generators/placeholder.d.ts

@@ -0,0 +1,52 @@
+/**
+ * PlaceholderValueGenerator Implementation
+ *
+ * Provides deterministic, context-aware placeholder values for testing.
+ * This generator uses keyword matching on context and hints to produce
+ * appropriate values for common field names.
+ *
+ * **PURPOSE**: This is a test fixture generator that provides:
+ * - Deterministic, predictable outputs for testing
+ * - Expected behavior and API contract demonstration
+ * - Specific assertions about generated content
+ *
+ * In production, the AIValueGenerator would be used instead.
+ *
+ * @packageDocumentation
+ */
+import type { ValueGenerator, GenerationRequest, GenerationResult } from './types.js';
+/**
+ * PlaceholderValueGenerator
+ *
+ * Generates deterministic values based on field name and context keywords.
+ * Used for testing and development when AI generation is not needed.
+ */
+export declare class PlaceholderValueGenerator implements ValueGenerator {
+    /**
+     * Generate a context-aware placeholder value
+     *
+     * Uses keyword matching on the context and hint to produce contextually
+     * relevant values for common field names.
+     *
+     * @param request - The generation request
+     * @returns Promise resolving to the generated value with metadata
+     */
+    generate(request: GenerationRequest): Promise<GenerationResult>;
+    /**
+     * Synchronous value generation
+     *
+     * This is the core generation logic, exposed for callers that need
+     * synchronous operation (e.g., backward-compatible cascade.ts).
+     *
+     * @param request - The generation request
+     * @returns The generated value string
+     */
+    generateSync(request: GenerationRequest): string;
+    /**
+     * Core value generation logic
+     *
+     * Moved from cascade.ts generateContextAwareValue function.
+     */
+    private generateValue;
+}
+//# sourceMappingURL=placeholder.d.ts.map

package/dist/schema/value-generators/placeholder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder.d.ts","sourceRoot":"","sources":["../../../src/schema/value-generators/placeholder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAErF;;;;;GAKG;AACH,qBAAa,yBAA0B,YAAW,cAAc;IAC9D;;;;;;;;OAQG;IACG,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAQrE;;;;;;;;OAQG;IACH,YAAY,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM;IAIhD;;;;OAIG;IACH,OAAO,CAAC,aAAa;CAgTtB"}