@agtlantis/core 0.5.0 → 0.5.1

package/dist/prompt/prompt-template.d.ts

@@ -0,0 +1,64 @@
+import type { PromptRenderer, PromptTemplateData } from './types.js';
+/**
+ * Prompt template with compilation capabilities.
+ *
+ * Use `PromptTemplate.from()` to create from raw data, then call `compile()`
+ * to get compiled template functions.
+ *
+ * @example
+ * ```typescript
+ * // From raw data
+ * const template = PromptTemplate.from({
+ *   id: 'greeting',
+ *   version: '1.0.0',
+ *   system: 'You are helping {{studentName}}.',
+ *   userTemplate: 'Previous answers: {{answers}}',
+ * });
+ *
+ * // Compile to renderer
+ * interface SessionCtx { studentName: string }
+ * interface TurnCtx { answers: string[] }
+ *
+ * const renderer = template.compile<SessionCtx, TurnCtx>();
+ * const systemPrompt = renderer.renderSystemPrompt({ studentName: 'Kim' });
+ * const userPrompt = renderer.renderUserPrompt({ answers: ['A', 'B'] });
+ * ```
+ */
+export declare class PromptTemplate implements PromptTemplateData {
+    readonly id: string;
+    readonly version: string;
+    readonly system: string;
+    readonly userTemplate: string;
+    private constructor();
+    /**
+     * Creates a PromptTemplate instance from raw data.
+     *
+     * @param data - Raw prompt template data
+     * @returns PromptTemplate instance
+     */
+    static from(data: PromptTemplateData): PromptTemplate;
+    /**
+     * Compiles templates and returns a PromptRenderer.
+     *
+     * @typeParam TSystemInput - Type of input for system prompt template
+     * @typeParam TUserInput - Type of input for user prompt template (defaults to TSystemInput)
+     * @returns Compiled prompt renderer with renderSystemPrompt and renderUserPrompt functions
+     * @throws {PromptTemplateError} If template compilation fails
+     *
+     * @example
+     * ```typescript
+     * // Different input types for system and user prompts
+     * const renderer = template.compile<SessionCtx, TurnCtx>();
+     *
+     * // Same input type for both
+     * const simpleRenderer = template.compile<CommonCtx>();
+     * ```
+     */
+    compile<TSystemInput = unknown, TUserInput = TSystemInput>(): PromptRenderer<TSystemInput, TUserInput>;
+    /**
+     * Returns raw data representation.
+     * Useful for serialization or passing to repository.write().
+     */
+    toData(): PromptTemplateData;
+}
+//# sourceMappingURL=prompt-template.d.ts.map

package/dist/prompt/prompt-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-template.d.ts","sourceRoot":"","sources":["../../src/prompt/prompt-template.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,cAAe,YAAW,kBAAkB;IAEjD,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM;IAJjC,OAAO,eAKH;IAEJ;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,kBAAkB,GAAG,cAAc,CAEpD;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,YAAY,GAAG,OAAO,EAAE,UAAU,GAAG,YAAY,KAAK,cAAc,CACxE,YAAY,EACZ,UAAU,CACb,CAOA;IAED;;;OAGG;IACH,MAAM,IAAI,kBAAkB,CAO3B;CACJ"}

package/dist/prompt/prompt-template.js

@@ -0,0 +1,90 @@
+/**
+ * PromptTemplate class for prompt management.
+ *
+ * Provides a rich object for prompt templates with compilation capabilities.
+ */
+import { compileTemplate } from './template.js';
+/**
+ * Prompt template with compilation capabilities.
+ *
+ * Use `PromptTemplate.from()` to create from raw data, then call `compile()`
+ * to get compiled template functions.
+ *
+ * @example
+ * ```typescript
+ * // From raw data
+ * const template = PromptTemplate.from({
+ *   id: 'greeting',
+ *   version: '1.0.0',
+ *   system: 'You are helping {{studentName}}.',
+ *   userTemplate: 'Previous answers: {{answers}}',
+ * });
+ *
+ * // Compile to renderer
+ * interface SessionCtx { studentName: string }
+ * interface TurnCtx { answers: string[] }
+ *
+ * const renderer = template.compile<SessionCtx, TurnCtx>();
+ * const systemPrompt = renderer.renderSystemPrompt({ studentName: 'Kim' });
+ * const userPrompt = renderer.renderUserPrompt({ answers: ['A', 'B'] });
+ * ```
+ */
+export class PromptTemplate {
+    id;
+    version;
+    system;
+    userTemplate;
+    constructor(id, version, system, userTemplate) {
+        this.id = id;
+        this.version = version;
+        this.system = system;
+        this.userTemplate = userTemplate;
+    }
+    /**
+     * Creates a PromptTemplate instance from raw data.
+     *
+     * @param data - Raw prompt template data
+     * @returns PromptTemplate instance
+     */
+    static from(data) {
+        return new PromptTemplate(data.id, data.version, data.system, data.userTemplate);
+    }
+    /**
+     * Compiles templates and returns a PromptRenderer.
+     *
+     * @typeParam TSystemInput - Type of input for system prompt template
+     * @typeParam TUserInput - Type of input for user prompt template (defaults to TSystemInput)
+     * @returns Compiled prompt renderer with renderSystemPrompt and renderUserPrompt functions
+     * @throws {PromptTemplateError} If template compilation fails
+     *
+     * @example
+     * ```typescript
+     * // Different input types for system and user prompts
+     * const renderer = template.compile<SessionCtx, TurnCtx>();
+     *
+     * // Same input type for both
+     * const simpleRenderer = template.compile<CommonCtx>();
+     * ```
+     */
+    compile() {
+        return {
+            id: this.id,
+            version: this.version,
+            renderSystemPrompt: compileTemplate(this.system, this.id),
+            renderUserPrompt: compileTemplate(this.userTemplate, this.id),
+        };
+    }
+    /**
+     * Returns raw data representation.
+     * Useful for serialization or passing to repository.write().
+     */
+    toData() {
+        return {
+            id: this.id,
+            version: this.version,
+            system: this.system,
+            userTemplate: this.userTemplate,
+        };
+    }
+}
+//# sourceMappingURL=prompt-template.js.map

package/dist/prompt/prompt-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-template.js","sourceRoot":"","sources":["../../src/prompt/prompt-template.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,cAAc;IAEV,EAAE;IACF,OAAO;IACP,MAAM;IACN,YAAY;IAJzB,YACa,EAAU,EACV,OAAe,EACf,MAAc,EACd,YAAoB,EAC/B;kBAJW,EAAE;uBACF,OAAO;sBACP,MAAM;4BACN,YAAY;IACtB,CAAC;IAEJ;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,IAAwB,EAAkB;QAClD,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IAAA,CACpF;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,GAGL;QACE,OAAO;YACH,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,kBAAkB,EAAE,eAAe,CAAe,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;YACvE,gBAAgB,EAAE,eAAe,CAAa,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,EAAE,CAAC;SAC5E,CAAC;IAAA,CACL;IAED;;;OAGG;IACH,MAAM,GAAuB;QACzB,OAAO;YACH,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,YAAY,EAAE,IAAI,CAAC,YAAY;SAClC,CAAC;IAAA,CACL;CACJ"}

package/dist/prompt/template.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Template engine for prompt compilation.
+ *
+ * Uses Handlebars for template rendering with custom helpers.
+ */
+/**
+ * Compiles a Handlebars template string into a render function.
+ *
+ * @typeParam TInput - Type of the input object for template rendering
+ * @param template - Handlebars template string
+ * @param promptId - Prompt ID for error context
+ * @returns Compiled template function
+ * @throws {PromptTemplateError} If template compilation fails
+ *
+ * @example
+ * ```typescript
+ * const render = compileTemplate<{ name: string }>('Hello, {{name}}!', 'greeting');
+ * const result = render({ name: 'World' });
+ * // => 'Hello, World!'
+ * ```
+ */
+export declare function compileTemplate<TInput>(template: string, promptId: string): (input: TInput) => string;
+//# sourceMappingURL=template.d.ts.map

package/dist/prompt/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/prompt/template.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAsCH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,MAAM,EACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAiB3B"}

package/dist/prompt/template.js

@@ -0,0 +1,70 @@
+/**
+ * Template engine for prompt compilation.
+ *
+ * Uses Handlebars for template rendering with custom helpers.
+ */
+import Handlebars from 'handlebars';
+// Note: PromptTemplate class uses compileTemplate, not the other way around
+// This avoids circular dependencies
+import { PromptTemplateError } from './errors.js';
+// =============================================================================
+// Handlebars Instance Setup
+// =============================================================================
+/**
+ * Create a sandboxed Handlebars instance with custom helpers.
+ * Using a separate instance prevents pollution of the global Handlebars.
+ */
+const handlebars = Handlebars.create();
+// Register custom helpers
+handlebars.registerHelper('add', (a, b) => {
+    const numA = Number(a);
+    const numB = Number(b);
+    if (Number.isNaN(numA) || Number.isNaN(numB)) {
+        return NaN;
+    }
+    return numA + numB;
+});
+// =============================================================================
+// Template Compilation
+// =============================================================================
+function wrapTemplateError(promptId, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const cause = error instanceof Error ? error : undefined;
+    return new PromptTemplateError(promptId, message, { cause });
+}
+/**
+ * Compiles a Handlebars template string into a render function.
+ *
+ * @typeParam TInput - Type of the input object for template rendering
+ * @param template - Handlebars template string
+ * @param promptId - Prompt ID for error context
+ * @returns Compiled template function
+ * @throws {PromptTemplateError} If template compilation fails
+ *
+ * @example
+ * ```typescript
+ * const render = compileTemplate<{ name: string }>('Hello, {{name}}!', 'greeting');
+ * const result = render({ name: 'World' });
+ * // => 'Hello, World!'
+ * ```
+ */
+export function compileTemplate(template, promptId) {
+    try {
+        const compiled = handlebars.compile(template, {
+            strict: true,
+            noEscape: true,
+        });
+        return (input) => {
+            try {
+                return compiled(input);
+            }
+            catch (error) {
+                throw wrapTemplateError(promptId, error);
+            }
+        };
+    }
+    catch (error) {
+        throw wrapTemplateError(promptId, error);
+    }
+}
+//# sourceMappingURL=template.js.map

package/dist/prompt/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/prompt/template.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,UAAU,MAAM,YAAY,CAAC;AAEpC,4EAA4E;AAC5E,oCAAoC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;AAEvC,0BAA0B;AAC1B,UAAU,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC,CAAU,EAAE,CAAU,EAAE,EAAE,CAAC;IAC3D,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACvB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,IAAI,GAAG,IAAI,CAAC;AAAA,CACpB,CAAC,CAAC;AAEH,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF;AAEhF,SAAS,iBAAiB,CAAC,QAAgB,EAAE,KAAc,EAAuB;IAChF,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,MAAM,KAAK,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACzD,OAAO,IAAI,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;AAAA,CAC9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,QAAgB,EACW;IAC3B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,QAAQ,EAAE;YAC5C,MAAM,EAAE,IAAI;YACZ,QAAQ,EAAE,IAAI;SACf,CAAC,CAAC;QAEH,OAAO,CAAC,KAAa,EAAU,EAAE,CAAC;YAChC,IAAI,CAAC;gBACH,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,iBAAiB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YAC3C,CAAC;QAAA,CACF,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,iBAAiB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;AAAA,CACF"}

package/dist/prompt/types.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Prompt module types for @agtlantis/core.
+ *
+ * Provides structured prompt management with versioning, templating, and repository abstraction.
+ */
+/**
+ * Raw prompt template data as stored in the repository.
+ * This is the serialized form before template compilation.
+ *
+ * @example
+ * ```typescript
+ * const data: PromptTemplateData = {
+ *   id: 'greeting',
+ *   version: '1.0.0',
+ *   system: 'You are a helpful assistant.',
+ *   userTemplate: 'Hello, {{name}}!',
+ * };
+ * ```
+ */
+export interface PromptTemplateData {
+    /** Unique identifier for the prompt */
+    id: string;
+    /** Semantic version string (e.g., '1.0.0') */
+    version: string;
+    /** System prompt template (Handlebars syntax) */
+    system: string;
+    /** User prompt template (Handlebars syntax) */
+    userTemplate: string;
+}
+/**
+ * Compiled prompt renderer with template functions.
+ * Created from PromptTemplate.compile() after Handlebars compilation.
+ *
+ * @typeParam TSystemInput - Type of the input object for system prompt rendering
+ * @typeParam TUserInput - Type of the input object for user prompt rendering
+ *
+ * @example
+ * ```typescript
+ * interface SessionContext {
+ *   studentName: string;
+ * }
+ * interface TurnContext {
+ *   previousAnswers: string[];
+ * }
+ *
+ * const renderer: PromptRenderer<SessionContext, TurnContext> = template.compile();
+ *
+ * const systemPrompt = renderer.renderSystemPrompt({ studentName: 'Kim' });
+ * const userPrompt = renderer.renderUserPrompt({ previousAnswers: ['A', 'B'] });
+ * ```
+ */
+export interface PromptRenderer<TSystemInput = unknown, TUserInput = unknown> {
+    /** Unique identifier for the prompt */
+    id: string;
+    /** Semantic version string (e.g., '1.0.0') */
+    version: string;
+    /** Compiled template function that renders the system prompt */
+    renderSystemPrompt: (input: TSystemInput) => string;
+    /** Compiled template function that renders the user prompt */
+    renderUserPrompt: (input: TUserInput) => string;
+}
+/**
+ * Repository interface for prompt storage operations.
+ * Implementations can use file system, database, or other storage backends.
+ *
+ * @example
+ * ```typescript
+ * import { createFilePromptRepository, PromptTemplate } from '@agtlantis/core';
+ *
+ * const repo = createFilePromptRepository({ directory: './prompts' });
+ *
+ * // Read latest version
+ * const data = await repo.read('greeting');
+ * const renderer = PromptTemplate.from(data).compile<SessionCtx, TurnCtx>();
+ *
+ * // Read specific version
+ * const v1Data = await repo.read('greeting', '1.0.0');
+ *
+ * // Write new prompt
+ * await repo.write({
+ *   id: 'greeting',
+ *   version: '2.0.0',
+ *   system: 'You are a friendly assistant.',
+ *   userTemplate: 'Hi {{name}}! How are you?',
+ * });
+ * ```
+ */
+export interface PromptRepository {
+    /**
+     * Reads raw prompt template data from the repository.
+     *
+     * @param id - Prompt identifier
+     * @param version - Optional specific version. If omitted, returns the latest version.
+     * @returns Raw prompt template data
+     * @throws {PromptNotFoundError} If prompt with given id (and version) doesn't exist
+     * @throws {PromptInvalidFormatError} If prompt file has invalid format
+     */
+    read(id: string, version?: string): Promise<PromptTemplateData>;
+    /**
+     * Writes a prompt to the repository.
+     *
+     * @param content - Raw prompt template data to store
+     * @throws {PromptIOError} If write operation fails
+     */
+    write(content: PromptTemplateData): Promise<void>;
+}
+/**
+ * Minimal file system interface for repository operations.
+ * Abstracts Node.js fs/promises for easier testing and potential browser compatibility.
+ *
+ * @example
+ * ```typescript
+ * // Use default Node.js implementation
+ * const repo = createFilePromptRepository({ directory: './prompts' });
+ *
+ * // Use custom implementation for testing
+ * const mockFs: FileSystem = {
+ *   readFile: async (path) => mockFiles[path],
+ *   writeFile: async (path, content) => { mockFiles[path] = content; },
+ *   readdir: async (path) => Object.keys(mockFiles),
+ * };
+ * const repo = createFilePromptRepository({ directory: './prompts', fs: mockFs });
+ * ```
+ */
+export interface FileSystem {
+    /**
+     * Reads file content as UTF-8 string.
+     * @param path - Absolute or relative file path
+     * @returns File content as string
+     * @throws If file doesn't exist or read fails
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * Writes content to a file (creates or overwrites).
+     * @param path - Absolute or relative file path
+     * @param content - Content to write
+     * @throws If write operation fails
+     */
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Lists files in a directory.
+     * @param path - Directory path
+     * @returns Array of file/directory names (not full paths)
+     * @throws If directory doesn't exist or read fails
+     */
+    readdir(path: string): Promise<string[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/prompt/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/prompt/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAkB;IAC/B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,cAAc,CAAC,YAAY,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;IACxE,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,kBAAkB,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC;IACpD,8DAA8D;IAC9D,gBAAgB,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC;CACnD;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAEhE;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,UAAU;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC5C"}

package/dist/prompt/types.js

@@ -0,0 +1,7 @@
+/**
+ * Prompt module types for @agtlantis/core.
+ *
+ * Provides structured prompt management with versioning, templating, and repository abstraction.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/prompt/types.js.map

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

package/dist/provider/base-provider.d.ts

@@ -0,0 +1,41 @@
+import type { Logger } from '../observability/logger.js';
+import type { ProviderPricing } from '../pricing/index.js';
+import type { GenerationOptions } from '../session/index.js';
+import type { SessionEvent, StreamingExecution, SimpleExecution, ExecutionOptions } from '../execution/types.js';
+import type { SimpleSession } from '../session/simple-session.js';
+import type { StreamingSession } from '../session/streaming-session.js';
+import type { Provider } from './types.js';
+/**
+ * Abstract base class for AI providers.
+ *
+ * Provides common streamingExecution and simpleExecution implementation.
+ * Subclasses implement session creation and fluent configuration methods.
+ */
+export declare abstract class BaseProvider implements Provider {
+    /**
+     * Create a SimpleSession for non-streaming execution.
+     * @param signal - AbortSignal for cancellation support
+     */
+    protected abstract createSimpleSession(signal?: AbortSignal): SimpleSession;
+    /**
+     * Create a StreamingSession for streaming execution.
+     * @param signal - AbortSignal for cancellation support
+     */
+    protected abstract createStreamingSession<TEvent extends {
+        type: string;
+    }>(signal?: AbortSignal): StreamingSession<TEvent>;
+    abstract withDefaultModel(modelId: string): Provider;
+    abstract withLogger(logger: Logger): Provider;
+    abstract withPricing(pricing: ProviderPricing): Provider;
+    abstract withDefaultOptions(options: Record<string, unknown>): Provider;
+    abstract withDefaultGenerationOptions(options: GenerationOptions): Provider;
+    streamingExecution<TEvent extends {
+        type: string;
+    }>(generator: (session: StreamingSession<TEvent>) => AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent> | Promise<SessionEvent<TEvent>>>, options?: ExecutionOptions): StreamingExecution<TEvent>;
+    /**
+     * Execute a non-streaming function with cancellation support.
+     * Returns immediately - execution starts in the background.
+     */
+    simpleExecution<TResult>(fn: (session: SimpleSession) => Promise<TResult>, options?: ExecutionOptions): SimpleExecution<TResult>;
+}
+//# sourceMappingURL=base-provider.d.ts.map

package/dist/provider/base-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-provider.d.ts","sourceRoot":"","sources":["../../src/provider/base-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGjH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;GAKG;AACH,8BAAsB,YAAa,YAAW,QAAQ;IAClD;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC;IAE5E;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,sBAAsB,CACrC,MAAM,SAAS;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EACjC,MAAM,CAAC,EAAE,WAAW,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAElD,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;IAErD,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAE9C,QAAQ,CAAC,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CAAC;IAEzD,QAAQ,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC;IAExE,QAAQ,CAAC,4BAA4B,CAAC,OAAO,EAAE,iBAAiB,GAAG,QAAQ,CAAC;IAE5E,kBAAkB,CAAC,MAAM,SAAS;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAC9C,SAAS,EAAE,CACP,OAAO,EAAE,gBAAgB,CAAC,MAAM,CAAC,KAChC,cAAc,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAC/F,OAAO,CAAC,EAAE,gBAAgB,GAC3B,kBAAkB,CAAC,MAAM,CAAC,CAM5B;IAED;;;OAGG;IACH,eAAe,CAAC,OAAO,EACnB,EAAE,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,EAChD,OAAO,CAAC,EAAE,gBAAgB,GAC3B,eAAe,CAAC,OAAO,CAAC,CAM1B;CACJ"}

package/dist/provider/base-provider.js

@@ -0,0 +1,21 @@
+import { StreamingExecutionHost } from '../execution/streaming-host.js';
+import { SimpleExecutionHost } from '../execution/simple-host.js';
+/**
+ * Abstract base class for AI providers.
+ *
+ * Provides common streamingExecution and simpleExecution implementation.
+ * Subclasses implement session creation and fluent configuration methods.
+ */
+export class BaseProvider {
+    streamingExecution(generator, options) {
+        return new StreamingExecutionHost((signal) => this.createStreamingSession(signal), generator, options?.signal);
+    }
+    /**
+     * Execute a non-streaming function with cancellation support.
+     * Returns immediately - execution starts in the background.
+     */
+    simpleExecution(fn, options) {
+        return new SimpleExecutionHost((signal) => this.createSimpleSession(signal), fn, options?.signal);
+    }
+}
+//# sourceMappingURL=base-provider.js.map

package/dist/provider/base-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-provider.js","sourceRoot":"","sources":["../../src/provider/base-provider.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAKlE;;;;;GAKG;AACH,MAAM,OAAgB,YAAY;IAyB9B,kBAAkB,CACd,SAE+F,EAC/F,OAA0B,EACA;QAC1B,OAAO,IAAI,sBAAsB,CAC7B,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,sBAAsB,CAAS,MAAM,CAAC,EACvD,SAAS,EACT,OAAO,EAAE,MAAM,CAClB,CAAC;IAAA,CACL;IAED;;;OAGG;IACH,eAAe,CACX,EAAgD,EAChD,OAA0B,EACF;QACxB,OAAO,IAAI,mBAAmB,CAC1B,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAC5C,EAAE,EACF,OAAO,EAAE,MAAM,CAClB,CAAC;IAAA,CACL;CACJ"}

package/dist/provider/file-cache.d.ts

@@ -0,0 +1,14 @@
+import type { FileCache, UploadedFile } from './types.js';
+export interface InMemoryFileCacheOptions {
+    defaultTTL?: number;
+}
+export declare class InMemoryFileCache implements FileCache {
+    private readonly cache;
+    private readonly defaultTTL;
+    constructor(options?: InMemoryFileCacheOptions);
+    get(hash: string): UploadedFile | null;
+    set(hash: string, file: UploadedFile, ttl?: number): void;
+    delete(hash: string): void;
+    clear(): void;
+}
+//# sourceMappingURL=file-cache.d.ts.map

package/dist/provider/file-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cache.d.ts","sourceRoot":"","sources":["../../src/provider/file-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1D,MAAM,WAAW,wBAAwB;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAOD,qBAAa,iBAAkB,YAAW,SAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAEhD,YAAY,OAAO,CAAC,EAAE,wBAAwB,EAE7C;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAQrC;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAIxD;IAED,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEzB;IAED,KAAK,IAAI,IAAI,CAEZ;CACJ"}

package/dist/provider/file-cache.js

@@ -0,0 +1,29 @@
+export class InMemoryFileCache {
+    cache = new Map();
+    defaultTTL;
+    constructor(options) {
+        this.defaultTTL = options?.defaultTTL;
+    }
+    get(hash) {
+        const entry = this.cache.get(hash);
+        if (!entry)
+            return null;
+        if (entry.expiresAt !== undefined && Date.now() > entry.expiresAt) {
+            this.cache.delete(hash);
+            return null;
+        }
+        return entry.file;
+    }
+    set(hash, file, ttl) {
+        const effectiveTTL = ttl ?? this.defaultTTL;
+        const expiresAt = effectiveTTL !== undefined ? Date.now() + effectiveTTL : undefined;
+        this.cache.set(hash, { file, expiresAt });
+    }
+    delete(hash) {
+        this.cache.delete(hash);
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+//# sourceMappingURL=file-cache.js.map

package/dist/provider/file-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-cache.js","sourceRoot":"","sources":["../../src/provider/file-cache.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,iBAAiB;IACT,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IACtC,UAAU,CAAqB;IAEhD,YAAY,OAAkC,EAAE;QAC5C,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,UAAU,CAAC;IAAA,CACzC;IAED,GAAG,CAAC,IAAY,EAAuB;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YAChE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACxB,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC;IAAA,CACrB;IAED,GAAG,CAAC,IAAY,EAAE,IAAkB,EAAE,GAAY,EAAQ;QACtD,MAAM,YAAY,GAAG,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC;QAC5C,MAAM,SAAS,GAAG,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC;QACrF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;IAAA,CAC7C;IAED,MAAM,CAAC,IAAY,EAAQ;QACvB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAAA,CAC3B;IAED,KAAK,GAAS;QACV,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IAAA,CACtB;CACJ"}

package/dist/provider/file-source.d.ts

@@ -0,0 +1,32 @@
+import { FileSource } from './types.js';
+export declare const EXTENSION_TO_MIME: Record<string, string>;
+/** Infers MIME type from file extension (case-insensitive) */
+export declare function inferMediaType(filePath: string): string | undefined;
+export interface FoundFileSource {
+    part: FileSource;
+    path: (string | number)[];
+}
+/** Recursively scans an input for FileSources and returns them with their JSON paths */
+export declare function scanForFileSources(input: unknown, currentPath?: (string | number)[]): FoundFileSource[];
+export interface ResolveOptions {
+    basePath?: string;
+    maxSize?: number;
+}
+export declare const DEFAULT_MAX_SIZE: number;
+/**
+ * Resolves a FileSource to AI SDK compatible format.
+ * Path-based parts are read into Buffer; others returned unchanged.
+ */
+export declare function resolveFileSource(part: FileSource, options?: ResolveOptions): Promise<FileSource>;
+/** Resolves all FileSources in an input (returns new object, original unchanged) */
+export declare function resolveFileSourcesInInput<T>(input: T, options?: ResolveOptions): Promise<T>;
+export interface FileSourceDisplayInfo {
+    source: FileSource['source'];
+    description: string;
+    mediaType: string;
+    filename?: string;
+}
+/** Extracts display info from a FileSource for reporting (excludes raw data) */
+export declare function getFileSourceDisplayInfo(part: FileSource): FileSourceDisplayInfo;
+export declare function getFileSourcesDisplayInfo(input: unknown): FileSourceDisplayInfo[];
+//# sourceMappingURL=file-source.d.ts.map

package/dist/provider/file-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-source.d.ts","sourceRoot":"","sources":["../../src/provider/file-source.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAkD,MAAM,YAAY,CAAC;AAExF,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAgBpD,CAAC;AAEF,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGnE;AAED,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CAC7B;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,OAAO,EACd,WAAW,GAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAO,GACtC,eAAe,EAAE,CA+BnB;AAED,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,gBAAgB,QAAmB,CAAC;AAEjD;;;GAGG;AACH,wBAAsB,iBAAiB,CACnC,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,cAAmB,GAC7B,OAAO,CAAC,UAAU,CAAC,CAqCrB;AA4BD,oFAAoF;AACpF,wBAAsB,yBAAyB,CAAC,CAAC,EAC7C,KAAK,EAAE,CAAC,EACR,OAAO,GAAE,cAAmB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED,MAAM,WAAW,qBAAqB;IAClC,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,gFAAgF;AAChF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,UAAU,GAAG,qBAAqB,CAuChF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,EAAE,CAGjF"}