@goreal-ai/echo-pdk 0.7.1 → 0.8.1

package/dist/providers/base.js

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Shared provider utilities
+ *
+ * Common functions used by all provider implementations:
+ * - HTTP helpers (fetchWithTimeout, extractApiError)
+ * - Judge/similarity prompt builders and parsers
+ * - toLLMProvider adapter for backward compatibility with eval system
+ */
+// =============================================================================
+// HTTP HELPERS
+// =============================================================================
+/**
+ * Fetch with an AbortController-based timeout.
+ */
+export async function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Extract a human-readable error message from an API response.
+ */
+export async function extractApiError(response, providerName) {
+    const body = await response.text();
+    return `${providerName} API error (${response.status}): ${body}`;
+}
+// =============================================================================
+// JUDGE PROMPTS
+// =============================================================================
+/**
+ * Build the prompt for LLM-as-judge evaluation.
+ */
+export function buildJudgePrompt(response, question) {
+    return `You are evaluating an LLM response. First provide a brief reasoning (1-2 sentences), then on a new line answer exactly "VERDICT: YES" or "VERDICT: NO".
+
+Response to evaluate:
+${response}
+
+Question: ${question}`;
+}
+/**
+ * Parse a judge response into pass/fail + reasoning.
+ */
+export function parseJudgeResponse(text) {
+    const trimmed = text.trim();
+    const pass = trimmed.toUpperCase().includes('VERDICT: YES');
+    const reasoning = trimmed
+        .replace(/\n?\s*VERDICT:\s*(YES|NO)\s*$/i, '')
+        .trim();
+    return { pass, reasoning };
+}
+// =============================================================================
+// SIMILARITY PROMPTS
+// =============================================================================
+/**
+ * Build the prompt for semantic similarity scoring.
+ */
+export function buildSimilarityPrompt(textA, textB) {
+    return `Rate the semantic similarity between these two texts on a scale of 0.0 to 1.0. Answer with only a number.
+
+Text A:
+${textA}
+
+Text B:
+${textB}`;
+}
+/**
+ * Parse a similarity response into a 0.0-1.0 score.
+ */
+export function parseSimilarityResponse(text) {
+    const score = parseFloat(text.trim());
+    return isNaN(score) ? 0 : Math.max(0, Math.min(1, score));
+}
+// =============================================================================
+// ADAPTER
+// =============================================================================
+/**
+ * Adapt an AIProviderInstance to the eval system's LLMProvider interface.
+ *
+ * The eval runner uses LLMProvider with `complete(prompt, model?)`.
+ * This bridges the gap so the new provider system works with existing eval code.
+ */
+export function toLLMProvider(instance) {
+    return {
+        async complete(prompt, model) {
+            const response = await instance.complete([{ role: 'user', content: prompt }], { model });
+            return {
+                text: response.text,
+                tokens: response.tokens,
+                latencyMs: response.latencyMs,
+                model: response.model,
+            };
+        },
+        async judge(response, question) {
+            return instance.judge(response, question);
+        },
+        async similarity(textA, textB) {
+            return instance.similarity(textA, textB);
+        },
+    };
+}
+//# sourceMappingURL=base.js.map

package/dist/providers/base.js.map

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

package/dist/providers/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Providers module - barrel exports
+ *
+ * Unified AI provider system for echo-pdk.
+ * Provides discovery, model listing, completion, and high-level prompt execution.
+ */
+export type { ProviderType, ProviderInfo, ProviderConfig, ModelInfo, ChatMessage, CompletionResponse, CompletionOptions, AIProviderInstance, } from './types.js';
+export { isProviderType, getProviders, getProvider, createProvider, listModels, } from './registry.js';
+export { createOpenAIProvider } from './openai.js';
+export { createAnthropicProvider } from './anthropic.js';
+export { runPrompt } from './run-prompt.js';
+export type { RunPromptOptions, RunPromptResult } from './run-prompt.js';
+export { toLLMProvider } from './base.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,SAAS,EACT,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,WAAW,EACX,cAAc,EACd,UAAU,GACX,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAGzD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGzE,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}

package/dist/providers/index.js

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Providers module - barrel exports
+ *
+ * Unified AI provider system for echo-pdk.
+ * Provides discovery, model listing, completion, and high-level prompt execution.
+ */
+// Registry
+export { isProviderType, getProviders, getProvider, createProvider, listModels, } from './registry.js';
+// Provider factories (for direct use)
+export { createOpenAIProvider } from './openai.js';
+export { createAnthropicProvider } from './anthropic.js';
+// High-level API
+export { runPrompt } from './run-prompt.js';
+// Utilities (for advanced use / testing)
+export { toLLMProvider } from './base.js';
+//# sourceMappingURL=index.js.map

package/dist/providers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH,WAAW;AACX,OAAO,EACL,cAAc,EACd,YAAY,EACZ,WAAW,EACX,cAAc,EACd,UAAU,GACX,MAAM,eAAe,CAAC;AAEvB,sCAAsC;AACtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,iBAAiB;AACjB,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5C,yCAAyC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}

package/dist/providers/openai.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview OpenAI provider implementation
+ *
+ * Implements AIProviderInstance for OpenAI's API:
+ * - POST /v1/chat/completions for completions
+ * - GET /v1/models for model listing
+ * - Judge and similarity via shared prompts
+ */
+import type { AIProviderInstance, ProviderConfig, ProviderInfo } from './types.js';
+export declare const OPENAI_INFO: ProviderInfo;
+/**
+ * Create an OpenAI provider instance.
+ *
+ * @param config - Provider configuration with API key
+ * @returns AIProviderInstance for OpenAI
+ */
+export declare function createOpenAIProvider(config: ProviderConfig): AIProviderInstance;
+//# sourceMappingURL=openai.d.ts.map

package/dist/providers/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAGlB,cAAc,EACd,YAAY,EACb,MAAM,YAAY,CAAC;AAcpB,eAAO,MAAM,WAAW,EAAE,YAMR,CAAC;AA8BnB;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,kBAAkB,CA2G/E"}

package/dist/providers/openai.js

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview OpenAI provider implementation
+ *
+ * Implements AIProviderInstance for OpenAI's API:
+ * - POST /v1/chat/completions for completions
+ * - GET /v1/models for model listing
+ * - Judge and similarity via shared prompts
+ */
+import { fetchWithTimeout, extractApiError, buildJudgePrompt, parseJudgeResponse, buildSimilarityPrompt, parseSimilarityResponse, } from './base.js';
+// =============================================================================
+// PROVIDER INFO
+// =============================================================================
+export const OPENAI_INFO = Object.freeze({
+    type: 'openai',
+    name: 'OpenAI',
+    baseUrl: 'https://api.openai.com',
+    defaultModel: 'gpt-4o',
+    envKeys: Object.freeze(['OPENAI_API_KEY', 'ECHO_API_KEY']),
+});
+// =============================================================================
+// FACTORY
+// =============================================================================
+/**
+ * Create an OpenAI provider instance.
+ *
+ * @param config - Provider configuration with API key
+ * @returns AIProviderInstance for OpenAI
+ */
+export function createOpenAIProvider(config) {
+    const apiKey = config.apiKey;
+    const baseUrl = config.baseUrl ?? OPENAI_INFO.baseUrl;
+    const defaultModel = config.model ?? OPENAI_INFO.defaultModel;
+    const timeout = config.timeout ?? 30000;
+    if (!apiKey) {
+        throw new Error('OpenAI API key is required. Set OPENAI_API_KEY environment variable or pass it in config.');
+    }
+    const headers = {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+    };
+    const instance = {
+        info: OPENAI_INFO,
+        async complete(messages, options) {
+            const model = options?.model ?? defaultModel;
+            const start = Date.now();
+            const body = {
+                model,
+                messages: messages.map((m) => ({
+                    role: m.role,
+                    content: m.content, // string or ContentBlock[] — OpenAI accepts both natively
+                })),
+            };
+            if (options?.temperature !== undefined) {
+                body.temperature = options.temperature;
+            }
+            if (options?.maxTokens !== undefined) {
+                body.max_tokens = options.maxTokens;
+            }
+            const response = await fetchWithTimeout(`${baseUrl}/v1/chat/completions`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+            }, timeout);
+            if (!response.ok) {
+                throw new Error(await extractApiError(response, 'OpenAI'));
+            }
+            const data = (await response.json());
+            const text = data.choices[0]?.message?.content ?? '';
+            return {
+                text,
+                tokens: data.usage
+                    ? {
+                        prompt: data.usage.prompt_tokens,
+                        completion: data.usage.completion_tokens,
+                        total: data.usage.total_tokens,
+                    }
+                    : undefined,
+                latencyMs: Date.now() - start,
+                model: data.model ?? model,
+                provider: 'openai',
+            };
+        },
+        async listModels() {
+            const response = await fetchWithTimeout(`${baseUrl}/v1/models`, { method: 'GET', headers }, timeout);
+            if (!response.ok) {
+                throw new Error(await extractApiError(response, 'OpenAI'));
+            }
+            const data = (await response.json());
+            return data.data.map((m) => ({
+                id: m.id,
+                provider: 'openai',
+                createdAt: m.created,
+                ownedBy: m.owned_by,
+            }));
+        },
+        async judge(responseText, question) {
+            const prompt = buildJudgePrompt(responseText, question);
+            const result = await instance.complete([{ role: 'user', content: prompt }]);
+            return parseJudgeResponse(result.text);
+        },
+        async similarity(textA, textB) {
+            const prompt = buildSimilarityPrompt(textA, textB);
+            const result = await instance.complete([{ role: 'user', content: prompt }]);
+            return parseSimilarityResponse(result.text);
+        },
+    };
+    return instance;
+}
+//# sourceMappingURL=openai.js.map

package/dist/providers/openai.js.map

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

package/dist/providers/registry.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview Provider registry
+ *
+ * Static map of known providers. No runtime registration needed.
+ * Adding a new provider = 1 new file + 2 entries here.
+ */
+import type { AIProviderInstance, ModelInfo, ProviderConfig, ProviderInfo, ProviderType } from './types.js';
+/**
+ * Check if a string is a valid provider type.
+ *
+ * Use this to validate user input or config values before passing them
+ * to functions that expect a ProviderType.
+ *
+ * @param value - String to check
+ * @returns true if value is a known ProviderType
+ *
+ * @example
+ * ```typescript
+ * const raw = config.provider; // string
+ * if (isProviderType(raw)) {
+ *   createProvider({ type: raw, apiKey: '...' });
+ * }
+ * ```
+ */
+export declare function isProviderType(value: string): value is ProviderType;
+/**
+ * Get metadata for all known providers.
+ *
+ * @returns Array of ProviderInfo for all registered providers
+ *
+ * @example
+ * ```typescript
+ * const providers = getProviders();
+ * // → [{ type: 'openai', name: 'OpenAI', ... }, { type: 'anthropic', name: 'Anthropic', ... }]
+ * ```
+ */
+export declare function getProviders(): ProviderInfo[];
+/**
+ * Get metadata for a specific provider.
+ *
+ * @param type - Provider type
+ * @returns ProviderInfo for the requested provider
+ * @throws If provider type is unknown
+ */
+export declare function getProvider(type: ProviderType): ProviderInfo;
+/**
+ * Create a configured provider instance.
+ *
+ * @param config - Provider configuration with type and API key
+ * @returns AIProviderInstance ready to use
+ * @throws If provider type is unknown or config is invalid
+ *
+ * @example
+ * ```typescript
+ * const provider = createProvider({
+ *   type: 'openai',
+ *   apiKey: 'sk-...',
+ *   model: 'gpt-4o',
+ * });
+ * const response = await provider.complete([{ role: 'user', content: 'Hello' }]);
+ * ```
+ */
+export declare function createProvider(config: ProviderConfig): AIProviderInstance;
+/**
+ * Convenience: list models for a provider type.
+ * Creates a temporary provider instance, calls listModels(), and returns the result.
+ *
+ * @param type - Provider type
+ * @param apiKey - API key for authentication
+ * @param baseUrl - Optional custom base URL
+ * @returns Array of ModelInfo from the live API
+ *
+ * @example
+ * ```typescript
+ * const models = await listModels('openai', 'sk-...');
+ * // → [{ id: 'gpt-4o', provider: 'openai', ... }, ...]
+ * ```
+ */
+export declare function listModels(type: ProviderType, apiKey: string, baseUrl?: string): Promise<ModelInfo[]>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/providers/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/providers/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,YAAY,EACZ,YAAY,EACb,MAAM,YAAY,CAAC;AA2BpB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAEnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,IAAI,YAAY,EAAE,CAE7C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CAM5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,kBAAkB,CAMzE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,EAAE,CAAC,CAGtB"}

package/dist/providers/registry.js

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview Provider registry
+ *
+ * Static map of known providers. No runtime registration needed.
+ * Adding a new provider = 1 new file + 2 entries here.
+ */
+import { createOpenAIProvider, OPENAI_INFO } from './openai.js';
+import { createAnthropicProvider, ANTHROPIC_INFO } from './anthropic.js';
+// =============================================================================
+// REGISTRY
+// =============================================================================
+/** Known provider metadata. */
+const PROVIDERS = {
+    openai: OPENAI_INFO,
+    anthropic: ANTHROPIC_INFO,
+};
+/** Factory functions for each provider. */
+const FACTORIES = {
+    openai: createOpenAIProvider,
+    anthropic: createAnthropicProvider,
+};
+/** Set of valid provider type strings for runtime validation. */
+const VALID_TYPES = new Set(Object.keys(PROVIDERS));
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+/**
+ * Check if a string is a valid provider type.
+ *
+ * Use this to validate user input or config values before passing them
+ * to functions that expect a ProviderType.
+ *
+ * @param value - String to check
+ * @returns true if value is a known ProviderType
+ *
+ * @example
+ * ```typescript
+ * const raw = config.provider; // string
+ * if (isProviderType(raw)) {
+ *   createProvider({ type: raw, apiKey: '...' });
+ * }
+ * ```
+ */
+export function isProviderType(value) {
+    return VALID_TYPES.has(value);
+}
+/**
+ * Get metadata for all known providers.
+ *
+ * @returns Array of ProviderInfo for all registered providers
+ *
+ * @example
+ * ```typescript
+ * const providers = getProviders();
+ * // → [{ type: 'openai', name: 'OpenAI', ... }, { type: 'anthropic', name: 'Anthropic', ... }]
+ * ```
+ */
+export function getProviders() {
+    return Object.values(PROVIDERS);
+}
+/**
+ * Get metadata for a specific provider.
+ *
+ * @param type - Provider type
+ * @returns ProviderInfo for the requested provider
+ * @throws If provider type is unknown
+ */
+export function getProvider(type) {
+    const info = PROVIDERS[type];
+    if (!info) {
+        throw new Error(`Unknown provider type: ${type}`);
+    }
+    return info;
+}
+/**
+ * Create a configured provider instance.
+ *
+ * @param config - Provider configuration with type and API key
+ * @returns AIProviderInstance ready to use
+ * @throws If provider type is unknown or config is invalid
+ *
+ * @example
+ * ```typescript
+ * const provider = createProvider({
+ *   type: 'openai',
+ *   apiKey: 'sk-...',
+ *   model: 'gpt-4o',
+ * });
+ * const response = await provider.complete([{ role: 'user', content: 'Hello' }]);
+ * ```
+ */
+export function createProvider(config) {
+    const factory = FACTORIES[config.type];
+    if (!factory) {
+        throw new Error(`Unknown provider type: ${config.type}`);
+    }
+    return factory(config);
+}
+/**
+ * Convenience: list models for a provider type.
+ * Creates a temporary provider instance, calls listModels(), and returns the result.
+ *
+ * @param type - Provider type
+ * @param apiKey - API key for authentication
+ * @param baseUrl - Optional custom base URL
+ * @returns Array of ModelInfo from the live API
+ *
+ * @example
+ * ```typescript
+ * const models = await listModels('openai', 'sk-...');
+ * // → [{ id: 'gpt-4o', provider: 'openai', ... }, ...]
+ * ```
+ */
+export async function listModels(type, apiKey, baseUrl) {
+    const provider = createProvider({ type, apiKey, baseUrl });
+    return provider.listModels();
+}
+//# sourceMappingURL=registry.js.map

package/dist/providers/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/providers/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEzE,gFAAgF;AAChF,WAAW;AACX,gFAAgF;AAEhF,+BAA+B;AAC/B,MAAM,SAAS,GAAuC;IACpD,MAAM,EAAE,WAAW;IACnB,SAAS,EAAE,cAAc;CAC1B,CAAC;AAEF,2CAA2C;AAC3C,MAAM,SAAS,GAAyE;IACtF,MAAM,EAAE,oBAAoB;IAC5B,SAAS,EAAE,uBAAuB;CACnC,CAAC;AAEF,iEAAiE;AACjE,MAAM,WAAW,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;AAE5D,gFAAgF;AAChF,aAAa;AACb,gFAAgF;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAkB;IAC5C,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,cAAc,CAAC,MAAsB;IACnD,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAkB,EAClB,MAAc,EACd,OAAgB;IAEhB,MAAM,QAAQ,GAAG,cAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3D,OAAO,QAAQ,CAAC,UAAU,EAAE,CAAC;AAC/B,CAAC"}

package/dist/providers/run-prompt.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview High-level runPrompt API
+ *
+ * Renders an echo-pdk template with variables, sends the result to an LLM
+ * provider, and returns both the rendered prompt and the LLM response.
+ *
+ * Import note: We import parse/evaluate/render directly from their modules
+ * (not from ../index.ts) to avoid circular dependencies, since index.ts
+ * imports from ai-judge which imports from providers.
+ */
+import type { ProviderConfig, CompletionResponse } from './types.js';
+/**
+ * Options for runPrompt.
+ */
+export interface RunPromptOptions {
+    /** Echo DSL template string */
+    template: string;
+    /** Variables to substitute in the template */
+    variables: Record<string, unknown>;
+    /** Provider configuration (type, apiKey, model, etc.) */
+    provider: ProviderConfig;
+    /** Optional system message prepended to the LLM call */
+    systemMessage?: string;
+    /** Temperature for LLM call */
+    temperature?: number;
+    /** Max tokens for LLM response */
+    maxTokens?: number;
+}
+/**
+ * Result from runPrompt.
+ */
+export interface RunPromptResult {
+    /** The rendered prompt (after template + variable resolution) */
+    renderedPrompt: string;
+    /** The LLM completion response */
+    response: CompletionResponse;
+}
+/**
+ * Render a template and send it to an LLM in one call.
+ *
+ * Steps:
+ * 1. Parse the Echo DSL template
+ * 2. Evaluate conditions with the provided variables
+ * 3. Render to a string
+ * 4. Send to the specified LLM provider
+ * 5. Return both the rendered prompt and the response
+ *
+ * **Limitation:** Templates using `#ai_gate` conditionals are not supported
+ * by this function. Use `createEcho()` with an `aiProvider` config for
+ * templates that require AI-evaluated conditions.
+ *
+ * @param options - Template, variables, and provider configuration
+ * @returns The rendered prompt and LLM response
+ *
+ * @example
+ * ```typescript
+ * const result = await runPrompt({
+ *   template: 'Recommend a {{genre}} movie for {{companions}}.',
+ *   variables: { genre: 'Comedy', companions: 'Family' },
+ *   provider: { type: 'openai', apiKey: 'sk-...', model: 'gpt-4o' },
+ * });
+ * console.log(result.renderedPrompt);
+ * // → "Recommend a Comedy movie for Family."
+ * console.log(result.response.text);
+ * // → "I'd recommend..."
+ * ```
+ */
+export declare function runPrompt(options: RunPromptOptions): Promise<RunPromptResult>;
+//# sourceMappingURL=run-prompt.d.ts.map

package/dist/providers/run-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-prompt.d.ts","sourceRoot":"","sources":["../../src/providers/run-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAMrE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,yDAAyD;IACzD,QAAQ,EAAE,cAAc,CAAC;IACzB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAqCnF"}

package/dist/providers/run-prompt.js

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview High-level runPrompt API
+ *
+ * Renders an echo-pdk template with variables, sends the result to an LLM
+ * provider, and returns both the rendered prompt and the LLM response.
+ *
+ * Import note: We import parse/evaluate/render directly from their modules
+ * (not from ../index.ts) to avoid circular dependencies, since index.ts
+ * imports from ai-judge which imports from providers.
+ */
+import { parse } from '../parser/parser.js';
+import { evaluate } from '../evaluator/index.js';
+import { render, formatErrors } from '../renderer/renderer.js';
+import { createProvider } from './registry.js';
+// =============================================================================
+// IMPLEMENTATION
+// =============================================================================
+/**
+ * Render a template and send it to an LLM in one call.
+ *
+ * Steps:
+ * 1. Parse the Echo DSL template
+ * 2. Evaluate conditions with the provided variables
+ * 3. Render to a string
+ * 4. Send to the specified LLM provider
+ * 5. Return both the rendered prompt and the response
+ *
+ * **Limitation:** Templates using `#ai_gate` conditionals are not supported
+ * by this function. Use `createEcho()` with an `aiProvider` config for
+ * templates that require AI-evaluated conditions.
+ *
+ * @param options - Template, variables, and provider configuration
+ * @returns The rendered prompt and LLM response
+ *
+ * @example
+ * ```typescript
+ * const result = await runPrompt({
+ *   template: 'Recommend a {{genre}} movie for {{companions}}.',
+ *   variables: { genre: 'Comedy', companions: 'Family' },
+ *   provider: { type: 'openai', apiKey: 'sk-...', model: 'gpt-4o' },
+ * });
+ * console.log(result.renderedPrompt);
+ * // → "Recommend a Comedy movie for Family."
+ * console.log(result.response.text);
+ * // → "I'd recommend..."
+ * ```
+ */
+export async function runPrompt(options) {
+    const { template, variables, provider: providerConfig, systemMessage } = options;
+    // 1. Parse
+    const parseResult = parse(template);
+    if (!parseResult.success || !parseResult.ast) {
+        const formattedErrors = formatErrors(template, parseResult.errors);
+        throw new Error(`Parse error:\n${formattedErrors}`);
+    }
+    // 2. Evaluate (resolve conditionals with the given variables)
+    const { ast: evaluatedAst } = await evaluate(parseResult.ast, variables, {});
+    // 3. Render
+    const renderedPrompt = render(evaluatedAst, {
+        context: variables,
+        config: {},
+        trim: false,
+        collapseNewlines: true,
+    });
+    // 4. Create provider and send to LLM
+    const instance = createProvider(providerConfig);
+    const messages = [];
+    if (systemMessage) {
+        messages.push({ role: 'system', content: systemMessage });
+    }
+    messages.push({ role: 'user', content: renderedPrompt });
+    const response = await instance.complete(messages, {
+        model: providerConfig.model,
+        temperature: options.temperature,
+        maxTokens: options.maxTokens,
+    });
+    return { renderedPrompt, response };
+}
+//# sourceMappingURL=run-prompt.js.map

package/dist/providers/run-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-prompt.js","sourceRoot":"","sources":["../../src/providers/run-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAmC/C,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAyB;IACvD,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IAEjF,WAAW;IACX,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;IACpC,IAAI,CAAC,WAAW,CAAC,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;QAC7C,MAAM,eAAe,GAAG,YAAY,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QACnE,MAAM,IAAI,KAAK,CAAC,iBAAiB,eAAe,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,8DAA8D;IAC9D,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;IAE7E,YAAY;IACZ,MAAM,cAAc,GAAG,MAAM,CAAC,YAAY,EAAE;QAC1C,OAAO,EAAE,SAAS;QAClB,MAAM,EAAE,EAAE;QACV,IAAI,EAAE,KAAK;QACX,gBAAgB,EAAE,IAAI;KACvB,CAAC,CAAC;IAEH,qCAAqC;IACrC,MAAM,QAAQ,GAAG,cAAc,CAAC,cAAc,CAAC,CAAC;IAEhD,MAAM,QAAQ,GAAG,EAAE,CAAC;IACpB,IAAI,aAAa,EAAE,CAAC;QAClB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAiB,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;IAElE,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE;QACjD,KAAK,EAAE,cAAc,CAAC,KAAK;QAC3B,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC,CAAC;IAEH,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC;AACtC,CAAC"}