ai-functions/dist/function-registry.d.ts

Core AI primitives for building intelligent applications

/**
 * Function Registry - Storage and management of defined AI functions
 *
 * This module provides the registry for storing and retrieving defined functions,
 * including the global registry and factory for creating isolated registries.
 */
import type { JSONSchema, FunctionDefinition, DefinedFunction, CodeGenerationDefinition, FunctionRegistry } from './types.js';
import { type SandboxEnv } from './sandbox.js';
/**
 * Convert args schema to JSON Schema
 */
export declare function convertArgsToJSONSchema(args: unknown): JSONSchema;
/**
 * Fill template with values
 */
export declare function fillTemplate(template: string, args: Record<string, unknown>): string;
/**
 * Author code with a model — the explicit, opt-in code-*generation* path.
 *
 * This is the behavior `type: 'code'` used to have implicitly at call time.
 * It has been split out so that `Code` functions can be deterministic. Calling
 * this **does** consult a model and returns the generated source as a string;
 * it does not produce a deterministic, repeatable handler.
 *
 * @param definition - The code-authoring spec ({@link CodeGenerationDefinition})
 * @param args - Concrete inputs / refinements for the requested code
 * @returns The generated source code as a string
 *
 * @example
 * ```ts
 * import { generateCode } from 'ai-functions'
 *
 * const src = await generateCode(
 *   { name: 'calculateTax', args: { amount: '(number)', rate: '(number)' }, language: 'typescript' },
 *   { amount: 100, rate: 0.2 }
 * )
 * ```
 */
export declare function generateCode<TInput>(definition: CodeGenerationDefinition<TInput>, args?: TInput): Promise<string>;
/**
 * Result of {@link generateAndRunCode}: the executed value plus the artifacts
 * that produced it.
 */
export interface GeneratedCodeRunResult<TOutput = unknown> {
    /** The value returned by running the authored code against the inputs. */
    value: TOutput;
    /** The model-authored module source that was executed. */
    code: string;
    /** The model-authored test source, if tests were requested. */
    tests?: string;
    /** Test results, if tests ran in the sandbox. */
    testResults?: {
        total: number;
        passed: number;
        failed: number;
        skipped: number;
    };
    /** Console logs captured during execution. */
    logs: {
        level: string;
        message: string;
    }[];
}
/**
 * The **non-deterministic** generate → run → test → return capability.
 *
 * This is the headline of the `generate('code', …)` primitive: a model
 * **authors** code, that code is **run** in ai-evaluate's V8-isolate sandbox,
 * optionally **tested** there, and the executed **result** is returned (not
 * just the source). This is deliberately separate from `type: 'code'`, which is
 * deterministic and never consults a model — so determinism is never blurred.
 *
 * Unlike {@link generateCode} (which only returns source text), this runs the
 * authored code. The authored module is expected to `export function ${name}`
 * (a NAMED export — the sandbox's module loader does not support `export
 * default`); the sandbox script invokes `${name}(args)` and returns its result.
 *
 * @param definition - The code-authoring spec ({@link CodeGenerationDefinition}).
 *   Set `includeTests: false` to skip test authoring (default: tests included).
 * @param args - Concrete inputs the authored code is invoked with.
 * @param env - Optional host Workers env. When it carries `LOADER` **and**
 *   `TEST`, tests run on the real Dynamic Workers loader; otherwise execution
 *   falls back to the Miniflare-backed Node runtime (whose dev worker has its
 *   own embedded test runner and needs no live `TEST` binding).
 * @returns The executed result plus authored artifacts.
 *
 * @example
 * ```ts
 * import { generateAndRunCode } from 'ai-functions'
 *
 * const { value } = await generateAndRunCode(
 *   { name: 'calculateTax', args: { amount: '(number)', rate: '(number)' } },
 *   { amount: 100, rate: 0.2 }
 * )
 * // value === 20  (the model authored the code, the sandbox ran it)
 * ```
 */
export declare function generateAndRunCode<TOutput = unknown, TInput = unknown>(definition: CodeGenerationDefinition<TInput>, args?: TInput, env?: SandboxEnv): Promise<GeneratedCodeRunResult<TOutput>>;
/**
 * Create a defined function from a function definition
 */
export declare function createDefinedFunction<TOutput, TInput>(definition: FunctionDefinition<TOutput, TInput>): DefinedFunction<TOutput, TInput>;
/**
 * Standalone function for defining AI functions
 *
 * @example
 * ```ts
 * import { defineFunction } from 'ai-functions'
 *
 * const summarize = defineFunction({
 *   type: 'generative',
 *   name: 'summarize',
 *   args: { text: 'Text to summarize' },
 *   output: 'string',
 *   promptTemplate: 'Summarize: {{text}}',
 * })
 *
 * const result = await summarize.call({ text: 'Long article...' })
 * ```
 */
export declare function defineFunction<TOutput, TInput>(definition: FunctionDefinition<TOutput, TInput>): DefinedFunction<TOutput, TInput>;
/**
 * Factory function to create a new isolated function registry instance.
 *
 * Use this when you need:
 * - Test isolation: Each test can have its own registry
 * - Scoped registries: Different parts of an app can have separate registries
 * - Custom lifecycle management: Control when registries are created/destroyed
 *
 * @example
 * ```ts
 * // Create isolated registry for tests
 * const registry = createFunctionRegistry()
 * const fn = defineFunction({ ... })
 * registry.set('myFunc', fn)
 *
 * // Later, registry can be discarded without affecting global state
 * ```
 *
 * @returns A new FunctionRegistry instance
 */
export declare function createFunctionRegistry(): FunctionRegistry;
/**
 * Global function registry
 *
 * Note: This is in-memory only. For persistence, use mdxai or mdxdb packages.
 *
 * **Lifecycle:**
 * - Created once at module load time
 * - Shared across the entire application
 * - Use `resetGlobalRegistry()` in tests to clear state between test runs
 * - For isolated registries, use `createFunctionRegistry()` instead
 */
export declare const functions: FunctionRegistry;
/**
 * Reset the global function registry to a clean state.
 *
 * **Important:** This is primarily intended for test cleanup to ensure
 * test isolation. In production code, prefer using `createFunctionRegistry()`
 * for isolated registries.
 *
 * @example
 * ```ts
 * // In test setup/teardown
 * beforeEach(() => {
 *   resetGlobalRegistry()
 * })
 *
 * // Or after each test
 * afterEach(() => {
 *   resetGlobalRegistry()
 * })
 * ```
 */
export declare function resetGlobalRegistry(): void;
//# sourceMappingURL=function-registry.d.ts.map