@goreal-ai/echo-pdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,255 @@
+/**
+ * @fileoverview Core type definitions for Echo PDK
+ *
+ * IMPLEMENTATION NOTES:
+ * This file defines all the core types used throughout the Echo engine.
+ * Keep types here to maintain a single source of truth and enable easy imports.
+ */
+/**
+ * Represents a position in the source template for error reporting.
+ */
+export interface SourceLocation {
+    /** Starting line number (1-indexed) */
+    startLine: number;
+    /** Starting column number (1-indexed) */
+    startColumn: number;
+    /** Ending line number (1-indexed) */
+    endLine: number;
+    /** Ending column number (1-indexed) */
+    endColumn: number;
+    /** Optional: the source text at this location */
+    source?: string;
+}
+/**
+ * Base interface for all AST nodes.
+ * Every node must have a type and location for error reporting.
+ */
+export interface BaseNode {
+    type: string;
+    location: SourceLocation;
+}
+/**
+ * Plain text content in the template.
+ * Example: "Hello world" in "Hello world {{name}}"
+ */
+export interface TextNode extends BaseNode {
+    type: 'text';
+    value: string;
+}
+/**
+ * Variable reference in the template.
+ * Example: {{user.name}} or {{value ?? "default"}}
+ */
+export interface VariableNode extends BaseNode {
+    type: 'variable';
+    /** The variable path, e.g., "user.name" or "items[0]" */
+    path: string;
+    /** Optional default value if variable is undefined */
+    defaultValue?: string;
+}
+/**
+ * A condition expression used in [#IF] blocks.
+ */
+export interface ConditionExpr {
+    /** The variable being tested */
+    variable: string;
+    /** The operator name, e.g., 'equals', 'contains', 'ai_judge' */
+    operator: string;
+    /** The argument to the operator (if any) */
+    argument?: string | number | string[];
+    /** Flag for optimization: true if this is an AI judge condition */
+    isAiJudge: boolean;
+}
+/**
+ * Conditional block: [#IF]...[ELSE IF]...[ELSE]...[END IF]
+ */
+export interface ConditionalNode extends BaseNode {
+    type: 'conditional';
+    /** The condition to evaluate */
+    condition: ConditionExpr;
+    /** Nodes to render if condition is true */
+    consequent: ASTNode[];
+    /** Optional: ELSE IF or ELSE branch */
+    alternate?: ConditionalNode | ASTNode[];
+}
+/**
+ * Section definition: [#SECTION name="..."]...[END SECTION]
+ */
+export interface SectionNode extends BaseNode {
+    type: 'section';
+    /** The section name for later reference */
+    name: string;
+    /** The content of the section */
+    body: ASTNode[];
+}
+/**
+ * Import directive: [#IMPORT ./path/to/file.echo]
+ */
+export interface ImportNode extends BaseNode {
+    type: 'import';
+    /** The path to import (relative or absolute) */
+    path: string;
+}
+/**
+ * Include directive: [#INCLUDE section_name]
+ */
+export interface IncludeNode extends BaseNode {
+    type: 'include';
+    /** The name of the section to include */
+    name: string;
+}
+/**
+ * Union type of all possible AST nodes.
+ */
+export type ASTNode = TextNode | VariableNode | ConditionalNode | SectionNode | ImportNode | IncludeNode;
+/**
+ * Handler function for a comparison operator.
+ * Called with the variable value and the operator argument.
+ */
+export type OperatorHandler = (value: unknown, argument?: unknown) => boolean | Promise<boolean>;
+/**
+ * Definition of an operator for the plugin system.
+ */
+export interface OperatorDefinition {
+    /** Type of operator: comparison (takes arg), unary (no arg), or ai (async) */
+    type: 'comparison' | 'unary' | 'ai';
+    /** The handler function */
+    handler: OperatorHandler;
+    /** Human-readable description */
+    description: string;
+    /** Example usage */
+    example?: string;
+    /** Autocomplete configuration for IDEs */
+    autocomplete?: {
+        trigger: string;
+        snippet: string;
+    };
+}
+/**
+ * AI provider configuration for #ai_judge operator.
+ */
+export interface AIProviderConfig {
+    /** The provider type */
+    type: 'openai' | 'anthropic';
+    /** API key (can also be set via ECHO_AI_API_KEY env var) */
+    apiKey: string;
+    /** Model to use (defaults to provider's default) */
+    model?: string;
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Main Echo configuration object.
+ */
+export interface EchoConfig {
+    /** Strict mode: fail on errors vs warn and continue */
+    strict?: boolean;
+    /** AI provider configuration for #ai_judge */
+    aiProvider?: AIProviderConfig;
+    /** Plugin paths to load */
+    plugins?: string[];
+    /** Language definition file path */
+    languagePath?: string;
+}
+/**
+ * Result of parsing a template.
+ */
+export interface ParseResult {
+    /** Whether parsing succeeded */
+    success: boolean;
+    /** The AST if successful */
+    ast?: ASTNode[];
+    /** Errors encountered during parsing */
+    errors: EchoError[];
+}
+/**
+ * Result of validating a template.
+ */
+export interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Errors found */
+    errors: EchoError[];
+    /** Warnings (non-fatal issues) */
+    warnings: EchoWarning[];
+}
+/**
+ * An error in the Echo template.
+ */
+export interface EchoError {
+    /** Error code for programmatic handling */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Location in source */
+    location?: SourceLocation;
+}
+/**
+ * A warning (non-fatal issue) in the Echo template.
+ */
+export interface EchoWarning {
+    /** Warning code */
+    code: string;
+    /** Human-readable warning message */
+    message: string;
+    /** Location in source */
+    location?: SourceLocation;
+}
+/**
+ * Plugin definition for extending Echo.
+ */
+export interface EchoPlugin {
+    /** Plugin name (unique identifier) */
+    name: string;
+    /** Plugin version */
+    version: string;
+    /** Custom operators provided by this plugin */
+    operators?: Record<string, OperatorDefinition>;
+    /** Hook called when plugin is loaded */
+    onLoad?: () => void | Promise<void>;
+}
+/**
+ * Helper function type for defining plugins.
+ */
+export type DefinePlugin = (plugin: EchoPlugin) => EchoPlugin;
+/**
+ * The main Echo interface for parsing and rendering templates.
+ */
+export interface Echo {
+    /**
+     * Parse a template string into an AST.
+     * @param template - The Echo template string
+     * @returns ParseResult with AST or errors
+     */
+    parse(template: string): ParseResult;
+    /**
+     * Render a template with the given context.
+     * @param template - The Echo template string
+     * @param context - Variables to substitute
+     * @returns The rendered string
+     */
+    render(template: string, context: Record<string, unknown>): Promise<string>;
+    /**
+     * Validate a template for syntax and semantic errors.
+     * @param template - The Echo template string
+     * @returns ValidationResult with errors and warnings
+     */
+    validate(template: string): ValidationResult;
+    /**
+     * Load a language definition from a YAML file.
+     * @param yamlPath - Path to the echo.lang.yaml file
+     */
+    loadLanguage(yamlPath: string): void;
+    /**
+     * Register a custom operator.
+     * @param name - The operator name (without #)
+     * @param definition - The operator definition
+     */
+    registerOperator(name: string, definition: OperatorDefinition): void;
+    /**
+     * Load a plugin.
+     * @param plugin - The plugin to load
+     */
+    loadPlugin(plugin: EchoPlugin): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,QAAS,SAAQ,QAAQ;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC5C,IAAI,EAAE,UAAU,CAAC;IACjB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;IACtC,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,QAAQ;IAC/C,IAAI,EAAE,aAAa,CAAC;IACpB,gCAAgC;IAChC,SAAS,EAAE,aAAa,CAAC;IACzB,2CAA2C;IAC3C,UAAU,EAAE,OAAO,EAAE,CAAC;IACtB,uCAAuC;IACvC,SAAS,CAAC,EAAE,eAAe,GAAG,OAAO,EAAE,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC3C,IAAI,EAAE,SAAS,CAAC;IAChB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,UAAW,SAAQ,QAAQ;IAC1C,IAAI,EAAE,QAAQ,CAAC;IACf,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC3C,IAAI,EAAE,SAAS,CAAC;IAChB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,MAAM,OAAO,GACf,QAAQ,GACR,YAAY,GACZ,eAAe,GACf,WAAW,GACX,UAAU,GACV,WAAW,CAAC;AAMhB;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,OAAO,EACd,QAAQ,CAAC,EAAE,OAAO,KACf,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,IAAI,EAAE,YAAY,GAAG,OAAO,GAAG,IAAI,CAAC;IACpC,2BAA2B;IAC3B,OAAO,EAAE,eAAe,CAAC;IACzB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,YAAY,CAAC,EAAE;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC7B,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,4BAA4B;IAC5B,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC;IAChB,wCAAwC;IACxC,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,mBAAmB;IACnB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,kCAAkC;IAClC,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAMD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC/C,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,UAAU,KAAK,UAAU,CAAC;AAM9D;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC;IAErC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5E;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAE7C;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAErC;;;;OAIG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAErE;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;CACtC"}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Core type definitions for Echo PDK
+ *
+ * IMPLEMENTATION NOTES:
+ * This file defines all the core types used throughout the Echo engine.
+ * Keep types here to maintain a single source of truth and enable easy imports.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@goreal-ai/echo-pdk",
+  "version": "0.1.0",
+  "description": "Echo PDK core rendering engine - parser, evaluator, and renderer",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "chevrotain": "^11.0.0",
+    "yaml": "^2.3.0"
+  },
+  "peerDependencies": {
+    "openai": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "openai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "openai": "^4.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "echo",
+    "pdk",
+    "prompt",
+    "dsl",
+    "parser",
+    "templating"
+  ],
+  "license": "MIT"
+}