@goreal-ai/echo-pdk 0.1.0

package/dist/index.js

@@ -0,0 +1,388 @@
+/**
+ * @fileoverview Echo PDK Core - Main entry point
+ *
+ * This is the main entry point for @goreal-ai/echo-pdk.
+ * It exports the createEcho factory function and all public types.
+ *
+ * @example
+ * ```typescript
+ * import { createEcho } from '@goreal-ai/echo-pdk';
+ *
+ * const echo = createEcho({
+ *   strict: false,
+ *   aiProvider: {
+ *     type: 'openai',
+ *     apiKey: process.env.OPENAI_API_KEY,
+ *   }
+ * });
+ *
+ * const result = await echo.render(template, { name: 'Alice' });
+ * ```
+ */
+// Import submodules
+import { parse } from './parser/parser.js';
+import { evaluate } from './evaluator/evaluator.js';
+import { render, formatErrors } from './renderer/renderer.js';
+import { builtinOperators, getOperator } from './evaluator/operators.js';
+import { createOpenAIProvider, withCache } from './ai-judge/index.js';
+// Re-export utilities for advanced usage
+export { parse } from './parser/parser.js';
+export { evaluate, resolveVariable, } from './evaluator/evaluator.js';
+export { render, renderTemplate, formatErrors } from './renderer/renderer.js';
+export { builtinOperators, getOperator } from './evaluator/operators.js';
+export { createTextNode, createVariableNode, createConditionalNode, createConditionExpr, createSectionNode, createImportNode, createIncludeNode, collectAiJudgeConditions, visitNode, visitNodes, prettyPrint, } from './parser/ast.js';
+/**
+ * Environment variable name for API key.
+ */
+const ENV_API_KEY = 'OPENAI_API_KEY';
+const ENV_ECHO_API_KEY = 'ECHO_API_KEY';
+/**
+ * Creates a new Echo instance with the given configuration.
+ *
+ * The Echo instance provides methods for parsing, validating, and rendering
+ * Echo templates with support for:
+ * - Variable interpolation: {{name}}, {{user.email}}
+ * - Conditionals: [#IF {{var}} #operator(arg)]...[END IF]
+ * - Sections: [#SECTION name="x"]...[END SECTION]
+ * - Includes: [#INCLUDE section_name]
+ * - AI-powered conditions: #ai_judge(question)
+ *
+ * @param config - Configuration options for the Echo instance
+ * @returns A configured Echo instance
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createEcho } from '@goreal-ai/echo-pdk';
+ *
+ * const echo = createEcho();
+ * const output = await echo.render('Hello {{name}}!', { name: 'World' });
+ * // Output: "Hello World!"
+ * ```
+ *
+ * @example With AI provider
+ * ```typescript
+ * const echo = createEcho({
+ *   aiProvider: {
+ *     type: 'openai',
+ *     apiKey: process.env.OPENAI_API_KEY,
+ *     model: 'gpt-4o-mini',
+ *   }
+ * });
+ *
+ * const template = `
+ * [#IF {{content}} #ai_judge(Is this appropriate for children?)]
+ *   Safe content: {{content}}
+ * [ELSE]
+ *   Content flagged for review.
+ * [END IF]
+ * `;
+ *
+ * const output = await echo.render(template, { content: userContent });
+ * ```
+ *
+ * @example With plugins
+ * ```typescript
+ * const echo = createEcho();
+ *
+ * echo.loadPlugin({
+ *   name: 'custom-operators',
+ *   version: '1.0.0',
+ *   operators: {
+ *     isEmpty: {
+ *       type: 'unary',
+ *       handler: (value) => !value || value === '',
+ *       description: 'Check if value is empty',
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export function createEcho(config = {}) {
+    // Custom operators registry (starts with built-in operators)
+    const operators = new Map();
+    // Register all built-in operators
+    for (const [name, definition] of Object.entries(builtinOperators)) {
+        operators.set(name, definition);
+    }
+    // Set up AI Judge operator if provider is configured
+    setupAiJudgeOperator(config, operators);
+    // Loaded plugins
+    const plugins = [];
+    // The Echo instance
+    const echo = {
+        /**
+         * Parse a template string into an AST.
+         */
+        parse(template) {
+            return parse(template);
+        },
+        /**
+         * Render a template with the given context.
+         */
+        async render(template, context) {
+            // Step 1: Parse
+            const parseResult = parse(template);
+            if (!parseResult.success || !parseResult.ast) {
+                const formattedErrors = formatErrors(template, parseResult.errors);
+                throw new Error(`Parse error:\n${formattedErrors}`);
+            }
+            // Step 2: Evaluate
+            const { ast: evaluatedAst } = await evaluate(parseResult.ast, context, config, operators);
+            // Step 3: Render
+            return render(evaluatedAst, {
+                context,
+                config,
+                trim: false,
+                collapseNewlines: true,
+            });
+        },
+        /**
+         * Validate a template for syntax and semantic errors.
+         */
+        validate(template) {
+            const errors = [];
+            const warnings = [];
+            // Step 1: Parse the template
+            const parseResult = parse(template);
+            if (!parseResult.success) {
+                return {
+                    valid: false,
+                    errors: parseResult.errors,
+                    warnings: [],
+                };
+            }
+            // Step 2: Semantic validation
+            if (parseResult.ast) {
+                validateAst(parseResult.ast, errors, warnings, config, operators);
+            }
+            return {
+                valid: errors.length === 0,
+                errors,
+                warnings,
+            };
+        },
+        /**
+         * Load a language definition from a YAML file.
+         */
+        loadLanguage(_yamlPath) {
+            // TODO: Implement language loading
+            // This would load custom operator definitions from a YAML file
+            // For now, we use the built-in operators
+            throw new Error('Language loading not yet implemented. Use registerOperator() to add custom operators.');
+        },
+        /**
+         * Register a custom operator.
+         */
+        registerOperator(name, definition) {
+            operators.set(name, definition);
+        },
+        /**
+         * Load a plugin.
+         */
+        loadPlugin(plugin) {
+            // Validate plugin structure
+            if (!plugin.name || typeof plugin.name !== 'string') {
+                throw new Error('Plugin must have a name');
+            }
+            if (!plugin.version || typeof plugin.version !== 'string') {
+                throw new Error('Plugin must have a version');
+            }
+            plugins.push(plugin);
+            // Register plugin operators
+            if (plugin.operators) {
+                for (const [name, definition] of Object.entries(plugin.operators)) {
+                    operators.set(name, definition);
+                }
+            }
+            // Call plugin's onLoad hook
+            if (plugin.onLoad) {
+                void plugin.onLoad();
+            }
+        },
+    };
+    // Load plugins specified in config
+    if (config.plugins && config.plugins.length > 0) {
+        // TODO: Implement plugin path loading
+        // For now, plugins must be loaded via loadPlugin()
+        console.warn('Plugin paths in config not yet supported. Use loadPlugin() instead.');
+    }
+    return echo;
+}
+/**
+ * Set up the AI Judge operator with the configured provider.
+ */
+function setupAiJudgeOperator(config, operators) {
+    // Check for API key from config or environment
+    const apiKey = config.aiProvider?.apiKey ||
+        process.env[ENV_ECHO_API_KEY] ||
+        process.env[ENV_API_KEY];
+    if (!apiKey) {
+        // No API key - AI Judge will throw when used
+        return;
+    }
+    // Create the provider based on type
+    const providerType = config.aiProvider?.type ?? 'openai';
+    if (providerType !== 'openai') {
+        console.warn(`AI provider type '${providerType}' not yet supported. Using OpenAI.`);
+    }
+    try {
+        // Resolve the model (default to gpt-4o-mini)
+        const model = config.aiProvider?.model ?? 'gpt-4o-mini';
+        // Create OpenAI provider with caching
+        const provider = createOpenAIProvider({
+            type: 'openai',
+            apiKey,
+            model,
+            timeout: config.aiProvider?.timeout,
+        });
+        // Wrap with cache, including provider/model for cache key isolation
+        const cachedProvider = withCache(provider, {
+            providerType: providerType,
+            model,
+        });
+        // Register the AI Judge operator with the provider
+        operators.set('ai_judge', {
+            type: 'ai',
+            description: 'LLM-evaluated boolean condition',
+            example: '{{content}} #ai_judge(Is this appropriate?)',
+            handler: async (value, question) => {
+                if (typeof question !== 'string') {
+                    throw new Error('AI Judge requires a question string as argument');
+                }
+                return cachedProvider.evaluate(value, question);
+            },
+        });
+    }
+    catch (error) {
+        // Provider creation failed - AI Judge will throw when used
+        console.warn('Failed to create AI provider:', error);
+    }
+}
+/**
+ * Validate the AST for semantic errors.
+ */
+function validateAst(ast, errors, warnings, config, operators) {
+    const knownSections = new Set();
+    // First pass: collect section names
+    collectSectionNames(ast, knownSections);
+    // Second pass: validate
+    validateNodes(ast, errors, warnings, knownSections, config, operators);
+}
+/**
+ * Collect all section names from the AST.
+ */
+function collectSectionNames(nodes, sections) {
+    for (const node of nodes) {
+        if (node.type === 'section') {
+            sections.add(node.name);
+            collectSectionNames(node.body, sections);
+        }
+        else if (node.type === 'conditional') {
+            collectSectionNames(node.consequent, sections);
+            if (node.alternate) {
+                if (Array.isArray(node.alternate)) {
+                    collectSectionNames(node.alternate, sections);
+                }
+                else {
+                    collectSectionNames([node.alternate], sections);
+                }
+            }
+        }
+    }
+}
+/**
+ * Validate AST nodes for semantic errors.
+ */
+function validateNodes(nodes, errors, warnings, knownSections, config, operators) {
+    for (const node of nodes) {
+        switch (node.type) {
+            case 'conditional': {
+                // Check if operator exists in instance operators or built-in operators
+                const operatorName = node.condition.operator;
+                const operator = operators.get(operatorName) ?? getOperator(operatorName);
+                if (!operator) {
+                    const error = {
+                        code: 'UNKNOWN_OPERATOR',
+                        message: `Unknown operator: #${operatorName}`,
+                        location: node.location,
+                    };
+                    if (config.strict) {
+                        errors.push(error);
+                    }
+                    else {
+                        warnings.push(error);
+                    }
+                }
+                // Recurse into branches
+                validateNodes(node.consequent, errors, warnings, knownSections, config, operators);
+                if (node.alternate) {
+                    if (Array.isArray(node.alternate)) {
+                        validateNodes(node.alternate, errors, warnings, knownSections, config, operators);
+                    }
+                    else {
+                        validateNodes([node.alternate], errors, warnings, knownSections, config, operators);
+                    }
+                }
+                break;
+            }
+            case 'include': {
+                // Check if section exists
+                if (!knownSections.has(node.name)) {
+                    const error = {
+                        code: 'UNKNOWN_SECTION',
+                        message: `Unknown section: ${node.name}`,
+                        location: node.location,
+                    };
+                    if (config.strict) {
+                        errors.push(error);
+                    }
+                    else {
+                        warnings.push(error);
+                    }
+                }
+                break;
+            }
+            case 'section': {
+                // Recurse into section body
+                validateNodes(node.body, errors, warnings, knownSections, config, operators);
+                break;
+            }
+            case 'import': {
+                // Warn about imports (not yet fully supported)
+                warnings.push({
+                    code: 'IMPORT_NOT_RESOLVED',
+                    message: `Import will not be resolved: ${node.path}`,
+                    location: node.location,
+                });
+                break;
+            }
+        }
+    }
+}
+/**
+ * Helper function for defining plugins with type safety.
+ *
+ * @param plugin - The plugin definition
+ * @returns The same plugin (for type inference)
+ *
+ * @example
+ * ```typescript
+ * import { definePlugin } from '@goreal-ai/echo-pdk';
+ *
+ * export default definePlugin({
+ *   name: 'my-operators',
+ *   version: '1.0.0',
+ *   operators: {
+ *     isEmpty: {
+ *       type: 'unary',
+ *       handler: (value) => !value,
+ *       description: 'Check if value is empty'
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export function definePlugin(plugin) {
+    return plugin;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/parser/ast.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview AST Utilities - Node creation and traversal
+ *
+ * This file provides utility functions for working with the Echo AST.
+ * Includes factory functions for creating nodes and visitor pattern helpers.
+ *
+ * IMPLEMENTATION GUIDE:
+ *
+ * 1. NODE FACTORIES
+ *    Factory functions ensure consistent node creation with proper defaults.
+ *
+ * 2. VISITOR PATTERN
+ *    Implement a visitor for AST traversal. This is the primary way to:
+ *    - Collect AI judge conditions
+ *    - Evaluate nodes
+ *    - Transform the AST
+ *
+ * 3. AST UTILITIES
+ *    - Clone nodes (deep copy)
+ *    - Find nodes by type
+ *    - Pretty print for debugging
+ */
+import type { ASTNode, TextNode, VariableNode, ConditionalNode, SectionNode, ImportNode, IncludeNode, SourceLocation, ConditionExpr } from '../types.js';
+/**
+ * Create a TextNode.
+ */
+export declare function createTextNode(value: string, location: SourceLocation): TextNode;
+/**
+ * Create a VariableNode.
+ */
+export declare function createVariableNode(path: string, location: SourceLocation, defaultValue?: string): VariableNode;
+/**
+ * Create a ConditionalNode.
+ */
+export declare function createConditionalNode(condition: ConditionExpr, consequent: ASTNode[], location: SourceLocation, alternate?: ConditionalNode | ASTNode[]): ConditionalNode;
+/**
+ * Create a ConditionExpr.
+ */
+export declare function createConditionExpr(variable: string, operator: string, argument?: string | number | string[]): ConditionExpr;
+/**
+ * Create a SectionNode.
+ */
+export declare function createSectionNode(name: string, body: ASTNode[], location: SourceLocation): SectionNode;
+/**
+ * Create an ImportNode.
+ */
+export declare function createImportNode(path: string, location: SourceLocation): ImportNode;
+/**
+ * Create an IncludeNode.
+ */
+export declare function createIncludeNode(name: string, location: SourceLocation): IncludeNode;
+/**
+ * Visitor interface for AST traversal.
+ * Implement this interface to walk the AST.
+ */
+export interface ASTVisitor<T = void> {
+    visitText?(node: TextNode): T;
+    visitVariable?(node: VariableNode): T;
+    visitConditional?(node: ConditionalNode): T;
+    visitSection?(node: SectionNode): T;
+    visitImport?(node: ImportNode): T;
+    visitInclude?(node: IncludeNode): T;
+}
+/**
+ * Walk an AST node with a visitor.
+ *
+ * @param node - The AST node to visit
+ * @param visitor - The visitor implementation
+ * @returns The result from the visitor (if any)
+ */
+export declare function visitNode<T>(node: ASTNode, visitor: ASTVisitor<T>): T | undefined;
+/**
+ * Walk an array of AST nodes with a visitor.
+ *
+ * @param nodes - The AST nodes to visit
+ * @param visitor - The visitor implementation
+ * @returns Array of results from the visitor
+ */
+export declare function visitNodes<T>(nodes: ASTNode[], visitor: ASTVisitor<T>): (T | undefined)[];
+/**
+ * Collect all AI judge conditions from an AST.
+ * This is used for parallel optimization.
+ *
+ * @param ast - The AST to search
+ * @returns Array of AI judge conditions with their locations
+ */
+export declare function collectAiJudgeConditions(ast: ASTNode[]): {
+    condition: ConditionExpr;
+    location: SourceLocation;
+}[];
+/**
+ * Deep clone an AST node.
+ *
+ * @param node - The node to clone
+ * @returns A deep copy of the node
+ */
+export declare function cloneNode<T extends ASTNode>(node: T): T;
+/**
+ * Pretty print an AST for debugging.
+ *
+ * @param ast - The AST to print
+ * @param indent - Current indentation level
+ * @returns Formatted string representation
+ */
+export declare function prettyPrint(ast: ASTNode[], indent?: number): string;
+//# sourceMappingURL=ast.d.ts.map

package/dist/parser/ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/parser/ast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAMrB;;GAEG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,cAAc,GACvB,QAAQ,CAMV;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,cAAc,EACxB,YAAY,CAAC,EAAE,MAAM,GACpB,YAAY,CAOd;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,aAAa,EACxB,UAAU,EAAE,OAAO,EAAE,EACrB,QAAQ,EAAE,cAAc,EACxB,SAAS,CAAC,EAAE,eAAe,GAAG,OAAO,EAAE,GACtC,eAAe,CAQjB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GACpC,aAAa,CAOf;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EAAE,EACf,QAAQ,EAAE,cAAc,GACvB,WAAW,CAOb;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,cAAc,GACvB,UAAU,CAMZ;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,cAAc,GACvB,WAAW,CAMb;AAMD;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,IAAI;IAClC,SAAS,CAAC,CAAC,IAAI,EAAE,QAAQ,GAAG,CAAC,CAAC;IAC9B,aAAa,CAAC,CAAC,IAAI,EAAE,YAAY,GAAG,CAAC,CAAC;IACtC,gBAAgB,CAAC,CAAC,IAAI,EAAE,eAAe,GAAG,CAAC,CAAC;IAC5C,YAAY,CAAC,CAAC,IAAI,EAAE,WAAW,GAAG,CAAC,CAAC;IACpC,WAAW,CAAC,CAAC,IAAI,EAAE,UAAU,GAAG,CAAC,CAAC;IAClC,YAAY,CAAC,CAAC,IAAI,EAAE,WAAW,GAAG,CAAC,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAoBjF;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,OAAO,EAAE,EAChB,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GACrB,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,CAEnB;AAMD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,OAAO,EAAE,GACb;IAAE,SAAS,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,EAAE,CAgC1D;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,MAAM,SAAI,GAAG,MAAM,CA6C9D"}