ai-functions 2.1.3 → 2.4.0

package/dist/function-registry.d.ts

@@ -0,0 +1,176 @@
+/**
+ * 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

package/dist/function-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-registry.d.ts","sourceRoot":"","sources":["../src/function-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAEV,UAAU,EACV,kBAAkB,EAClB,eAAe,EAEf,wBAAwB,EAKxB,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAInB,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAA;AAM5D;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAuBjE;AAuDD;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAQpF;AAqHD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,YAAY,CAAC,MAAM,EACvC,UAAU,EAAE,wBAAwB,CAAC,MAAM,CAAC,EAC5C,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAmCjB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB,CAAC,OAAO,GAAG,OAAO;IACvD,0EAA0E;IAC1E,KAAK,EAAE,OAAO,CAAA;IACd,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,WAAW,CAAC,EAAE;QACZ,KAAK,EAAE,MAAM,CAAA;QACb,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;QACd,OAAO,EAAE,MAAM,CAAA;KAChB,CAAA;IACD,8CAA8C;IAC9C,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,EAC1E,UAAU,EAAE,wBAAwB,CAAC,MAAM,CAAC,EAC5C,IAAI,CAAC,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,UAAU,GACf,OAAO,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CA8F1C;AAwQD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EACnD,UAAU,EAAE,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,GAC9C,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,CA4BlC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAC5C,UAAU,EAAE,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,GAC9C,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,CAElC;AAqCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CAEzD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,EAAE,gBAAiD,CAAA;AAEzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}