ai-functions 2.1.3 → 2.3.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> ai-functions@2.1.3 build /Users/nathanclevenger/projects/primitives.org.ai/packages/ai-functions
+> ai-functions@2.2.0 build /Users/nathanclevenger/projects/primitives.org.ai/packages/ai-functions
 > tsc -p tsconfig.json
 

package/CHANGELOG.md

@@ -1,10 +1,62 @@
 # ai-functions
 
+## 2.3.0
+
+### Minor Changes
+
+- 9e2779a: Make `kind: 'code'` deterministic.
+
+  Previously `defineFunction({ type: 'code' })` LLM-**generated** code at call time. A `CodeFunctionDefinition` now carries a deterministic `handler: (input) => output` (or an inline `code` string body), and `executeCodeFunction` runs it with **no model in the call path**. This aligns `Code` with the documented "Code = deterministic" contract (a fetch/transform/rule handler), keeping `Generative` / `Agentic` / `Human` semantics intact.
+
+  The code-**authoring** behavior (have a model write code) is preserved but moved to an explicit, opt-in path so the change is not silent:
+
+  - New `generateCode(definition, args)` export — returns generated source as a string.
+  - New `CodeGenerationDefinition` type for that path.
+  - `define.code(...)` now defines a deterministic handler function.
+  - Auto-define (`define(name, args)`) authors a self-contained body once at define time and carries it as an inline `code` body, so the resulting function is deterministic on every call.
+  - The `generate('code', prompt)` primitive is unchanged (a string-prompt code-authoring helper, distinct from the `FunctionDefinition` union).
+
+  `CodeFunctionDefinition` drops `includeTests` / `includeExamples` (relocated to `CodeGenerationDefinition`). The four `*FunctionDefinition` shapes and the `FunctionDefinition` union remain source-compatible for consumers binding to the type surface.
+
+### Patch Changes
+
+- Updated dependencies [2787830]
+  - language-models@2.3.0
+  - ai-providers@2.3.0
+  - @org.ai/types@2.3.0
+
+## 2.2.0
+
+### Minor Changes
+
+- Make `kind: 'code'` deterministic. A `CodeFunctionDefinition` now carries a
+  deterministic `handler: (input) => output` (or an inline `code` string body)
+  and `executeCodeFunction` runs it with **no model in the call path** — the
+  documented "Code = deterministic" contract. The previous call-time code
+  _generation_ behavior is preserved but moved to an explicit opt-in path: the
+  new `generateCode()` export (+ `CodeGenerationDefinition` type). `define.code`
+  now defines a handler; auto-define authors a body once at define time and
+  carries it as inline `code`. `Generative` / `Agentic` / `Human` semantics are
+  unchanged; the `generate('code', prompt)` primitive is unchanged.
+  `CodeFunctionDefinition` drops `includeTests` / `includeExamples` (relocated
+  to `CodeGenerationDefinition`).
+- Deepen `language-models` with per-model resilience and tier policy data
+  (aip-70mk). The `ModelPolicy` MDXLD type (`$type: 'ModelPolicy'`) and
+  `policyFor()` derivation layer now live in `language-models`. The runtime
+  machinery in `ai-functions` (`RetryPolicy`, `CircuitBreaker`,
+  `FallbackChain`) gains `forModel(alias)` factories that read policy from
+  the catalog. Default behaviour is preserved when no alias is provided.
+- New helpers: `tiersForModel(alias)`, `modelSupportsTier(alias, tier)`,
+  re-exported `modelPolicyFor` (alias for `policyFor`).
+- New types re-exported: `ModelPolicy`, `BatchTier`, `RetryPolicyData`,
+  `CircuitBreakerPolicyData`, `ErrorCategoryName`, `FlexAdapter`.
+
 ## 2.1.3
 
 ### Patch Changes
 
 - Documentation and testing improvements
+
   - Add deterministic AI testing suite with self-validating patterns
   - Apply StoryBrand narrative to all package READMEs
   - Update TESTING.md with four principles of deterministic AI testing
@@ -20,12 +72,14 @@
 ### Patch Changes
 
 - 6beb531: Add TDD RED phase tests for type system unification
+
   - ai-functions: Add tests for AIFunction<Output, Input> generic order flip
   - ai-workflows: Add tests for EventHandler<TOutput, TInput> order and OnProxy/EveryProxy autocomplete
   - ai-database: Existing package - no changes in this release
-  - @primitives/types: New shared types package with failing tests for RED phase
+  - @org.ai/types: New shared types package with failing tests for RED phase
 
   These tests document the expected behavior for the GREEN phase implementation where generic type parameters will be reordered to put Output first (matching Promise<T> convention).
+
   - ai-providers@2.1.1
   - language-models@2.1.1
 

package/README.md

@@ -1,5 +1,7 @@
 # ai-functions
 
+![Stability: Stable](https://img.shields.io/badge/stability-stable-green)
+
 **Calling AI models shouldn't require 50 lines of boilerplate.**
 
 You just want to get a response from Claude, GPT, or Gemini. Instead, you're drowning in SDK initialization, error handling, retry logic, JSON parsing, and type coercion. Every AI call becomes a small engineering project.
@@ -386,6 +388,42 @@ const trip = await planTrip.call({ destination: 'Paris', travelers: 4 })
 const summary = await summarize.call({ text: longArticle, maxLength: 100 })
 ```
 
+### The four Function kinds
+
+`defineFunction` accepts a discriminated union (`FunctionDefinition`). Each `type` has a distinct execution contract:
+
+| `type` | Meaning | At call time |
+|--------|---------|--------------|
+| `code` | **Deterministic handler** — a fetch/transform/rule | Runs your `handler` (or inline `code` body). **No model.** |
+| `generative` | One-shot generation | `generateObject` / `generateText` |
+| `agentic` | Plan-execute-observe tool loop | Iterative model + tool calls |
+| `human` | Human/approval step | Generates channel UI, returns a pending result |
+
+```typescript
+// Code = deterministic. Supply a handler (or an inline `code` string).
+const calculateTax = defineFunction({
+  type: 'code',
+  name: 'calculateTax',
+  args: { amount: 'Amount (number)', rate: 'Rate (number)' },
+  handler: ({ amount, rate }) => amount * rate, // runs every call, no LLM
+})
+await calculateTax.call({ amount: 100, rate: 0.2 }) // => 20
+```
+
+> **Migration (breaking, as of this release):** previously `type: 'code'` LLM-**generated** code at call time. `Code` is now **deterministic** — it requires a `handler` or inline `code` body and never calls a model. A `code` function with neither now throws.
+>
+> If you relied on the old behavior (have a model *author* code), use the new explicit `generateCode()` export, or a `generative` function whose output is source text:
+>
+> ```typescript
+> import { generateCode } from 'ai-functions'
+> const src = await generateCode(
+>   { name: 'fib', args: { n: '(number)' }, language: 'typescript' },
+>   { n: 10 }
+> ) // => string of generated source
+> ```
+>
+> The `generate('code', prompt)` primitive is unchanged — it is a string-prompt code-authoring helper, distinct from the `FunctionDefinition` union.
+
 ## API Reference
 
 ### Core Primitives

package/dist/ai-promise.d.ts

@@ -1,7 +1,7 @@
 /**
- * AIPromise - RPC-style promise pipelining for AI functions
+ * AIPromise - Promise pipelining for AI functions
  *
- * Inspired by capnweb's RpcPromise, this enables:
+ * This enables:
  * - Property access tracking for dynamic schema inference
  * - Promise pipelining without await
  * - Magical .map() for batch processing
@@ -76,7 +76,7 @@ export interface AIPromiseOptions extends FunctionOptions {
     propertyPath?: string[];
 }
 /**
- * AIPromise - Like capnweb's RpcPromise but for AI functions
+ * AIPromise - Promise wrapper for AI functions
  *
  * Acts as both a Promise AND a stub that:
  * - Tracks property accesses for dynamic schema inference

package/dist/ai-promise.d.ts.map

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

package/dist/ai-promise.js

@@ -1,7 +1,7 @@
 /**
- * AIPromise - RPC-style promise pipelining for AI functions
+ * AIPromise - Promise pipelining for AI functions
  *
- * Inspired by capnweb's RpcPromise, this enables:
+ * This enables:
  * - Property access tracking for dynamic schema inference
  * - Promise pipelining without await
  * - Magical .map() for batch processing
@@ -54,7 +54,7 @@ let resolutionScheduled = false;
 // AIPromise Implementation
 // ============================================================================
 /**
- * AIPromise - Like capnweb's RpcPromise but for AI functions
+ * AIPromise - Promise wrapper for AI functions
  *
  * Acts as both a Promise AND a stub that:
  * - Tracks property accesses for dynamic schema inference
@@ -150,19 +150,25 @@ export class AIPromise {
             model: this._options.model || 'sonnet',
             schema,
             prompt: finalPrompt,
-            system: this._options.system,
-            temperature: this._options.temperature,
-            maxTokens: this._options.maxTokens,
+            ...(this._options.system !== undefined && { system: this._options.system }),
+            ...(this._options.temperature !== undefined && { temperature: this._options.temperature }),
+            ...(this._options.maxTokens !== undefined && { maxTokens: this._options.maxTokens }),
         });
         // Extract the value based on type
         // Type assertions here are safe because:
         // 1. Runtime type checking validates the response structure
         // 2. The type parameter T corresponds to the expected output type for each mode
         let value = result.object;
-        if (this._options.type === 'text' && typeof value === 'object' && value !== null && 'text' in value) {
+        if (this._options.type === 'text' &&
+            typeof value === 'object' &&
+            value !== null &&
+            'text' in value) {
             value = value.text;
         }
-        else if (this._options.type === 'boolean' && typeof value === 'object' && value !== null && 'answer' in value) {
+        else if (this._options.type === 'boolean' &&
+            typeof value === 'object' &&
+            value !== null &&
+            'answer' in value) {
             const answer = value.answer;
             // When type === 'boolean', T is constrained to boolean at the call site.
             // TypeScript can't express this dependent relationship, so we use a simple cast.
@@ -170,7 +176,10 @@ export class AIPromise {
             const booleanValue = answer === 'true' || answer === true;
             value = booleanValue;
         }
-        else if ((this._options.type === 'list' || this._options.type === 'extract') && typeof value === 'object' && value !== null && 'items' in value) {
+        else if ((this._options.type === 'list' || this._options.type === 'extract') &&
+            typeof value === 'object' &&
+            value !== null &&
+            'items' in value) {
             value = value.items;
         }
         this._resolvedValue = value;
@@ -193,7 +202,11 @@ export class AIPromise {
                 case 'list':
                     return { items: ['List items'] };
                 case 'extract':
-                    return { items: ['Extracted items'] };
+                    return {
+                        items: [
+                            'Array of extracted items as strings - extract ALL matching items from the text',
+                        ],
+                    };
                 case 'lists':
                     return { categories: ['Category names'], data: 'JSON object with categorized lists' };
                 case 'boolean':
@@ -268,17 +281,23 @@ export class AIPromise {
         // Create a wrapper that resolves this promise first, then maps
         const mapPromise = new BatchMapPromise([], [], {});
         // Override the resolve to first get the list items
-        const originalResolve = mapPromise.resolve.bind(mapPromise);
-        mapPromise.resolve = async () => {
-            // First, resolve the list
-            const items = await this.resolve();
-            if (!Array.isArray(items)) {
-                throw new Error('Cannot map over non-array result');
-            }
-            // Now create the actual batch map with the resolved items
-            const actualBatchMap = createBatchMap(items, callback);
-            return actualBatchMap.resolve();
-        };
+        // Type assertion: BatchMapPromise.resolve is a public method that we're replacing
+        // with a compatible async function returning Promise<U[]>
+        const self = this;
+        Object.defineProperty(mapPromise, 'resolve', {
+            value: async function () {
+                // First, resolve the list
+                const items = await self.resolve();
+                if (!Array.isArray(items)) {
+                    throw new Error('Cannot map over non-array result');
+                }
+                // Now create the actual batch map with the resolved items
+                const actualBatchMap = createBatchMap(items, callback);
+                return actualBatchMap.resolve();
+            },
+            writable: true,
+            configurable: true,
+        });
         return mapPromise;
     }
     /**
@@ -295,26 +314,36 @@ export class AIPromise {
      */
     mapImmediate(callback) {
         const mapPromise = new BatchMapPromise([], [], { immediate: true });
-        mapPromise.resolve = async () => {
-            const items = await this.resolve();
-            if (!Array.isArray(items)) {
-                throw new Error('Cannot map over non-array result');
-            }
-            const actualBatchMap = createBatchMap(items, callback, { immediate: true });
-            return actualBatchMap.resolve();
-        };
+        const self = this;
+        Object.defineProperty(mapPromise, 'resolve', {
+            value: async function () {
+                const items = await self.resolve();
+                if (!Array.isArray(items)) {
+                    throw new Error('Cannot map over non-array result');
+                }
+                const actualBatchMap = createBatchMap(items, callback, { immediate: true });
+                return actualBatchMap.resolve();
+            },
+            writable: true,
+            configurable: true,
+        });
         return mapPromise;
     }
     mapDeferred(callback) {
         const mapPromise = new BatchMapPromise([], [], { deferred: true });
-        mapPromise.resolve = async () => {
-            const items = await this.resolve();
-            if (!Array.isArray(items)) {
-                throw new Error('Cannot map over non-array result');
-            }
-            const actualBatchMap = createBatchMap(items, callback, { deferred: true });
-            return actualBatchMap.resolve();
-        };
+        const self = this;
+        Object.defineProperty(mapPromise, 'resolve', {
+            value: async function () {
+                const items = await self.resolve();
+                if (!Array.isArray(items)) {
+                    throw new Error('Cannot map over non-array result');
+                }
+                const actualBatchMap = createBatchMap(items, callback, { deferred: true });
+                return actualBatchMap.resolve();
+            },
+            writable: true,
+            configurable: true,
+        });
         return mapPromise;
     }
     /**
@@ -335,6 +364,7 @@ export class AIPromise {
             }
         }
         else {
+            // When T is not an array, the conditional type T extends (infer I)[] ? I : T resolves to T
             await callback(items, 0);
         }
     }
@@ -345,10 +375,12 @@ export class AIPromise {
         const items = await this.resolve();
         if (Array.isArray(items)) {
             for (const item of items) {
+                // Each array item is the inferred element type I when T extends I[]
                 yield item;
             }
         }
         else {
+            // When T is not an array, the item type is T itself
             yield items;
         }
     }
@@ -423,7 +455,7 @@ export class AIPromise {
 // Proxy Handlers
 // ============================================================================
 const PROXY_HANDLERS = {
-    get(target, prop, receiver) {
+    get(target, prop, _receiver) {
         // Handle symbols
         if (typeof prop === 'symbol') {
             if (prop === AI_PROMISE_SYMBOL)
@@ -436,14 +468,26 @@ const PROXY_HANDLERS = {
         }
         // Handle promise methods
         if (prop === 'then' || prop === 'catch' || prop === 'finally') {
-            return target[prop].bind(target);
+            const method = target[prop];
+            return method?.bind(target);
         }
         // Handle AIPromise methods
-        if (prop === 'map' || prop === 'forEach' || prop === 'resolve' || prop === 'stream' || prop === 'addDependency' || prop === 'mapImmediate' || prop === 'mapDeferred') {
-            return target[prop].bind(target);
+        if (prop === 'map' ||
+            prop === 'forEach' ||
+            prop === 'resolve' ||
+            prop === 'stream' ||
+            prop === 'addDependency' ||
+            prop === 'mapImmediate' ||
+            prop === 'mapDeferred') {
+            const method = target[prop];
+            return method?.bind(target);
         }
         // Handle internal properties
-        if (prop.startsWith('_') || prop === 'prompt' || prop === 'path' || prop === 'isResolved' || prop === 'accessedProps') {
+        if (prop.startsWith('_') ||
+            prop === 'prompt' ||
+            prop === 'path' ||
+            prop === 'isResolved' ||
+            prop === 'accessedProps') {
             return target[prop];
         }
         // Track property access for schema inference
@@ -467,10 +511,11 @@ const PROXY_HANDLERS = {
         throw new Error('AIPromise properties cannot be deleted');
     },
     // Handle function calls (for chained methods)
-    apply(target, thisArg, args) {
+    apply(target, _thisArg, args) {
         // If the target is callable (e.g., from a template function), call it
-        if (typeof target._call === 'function') {
-            return target._call(...args);
+        const call = target['_call'];
+        if (typeof call === 'function') {
+            return call(...args);
         }
         throw new Error('AIPromise is not callable');
     },
@@ -510,10 +555,12 @@ function analyzeRecordingResult(result, recording) {
             const aiPromise = getRawPromise(value);
             // Infer schema from the promise's accessed properties or type
             if (aiPromise.accessedProps.size > 0) {
-                schema[key] = Object.fromEntries(Array.from(aiPromise.accessedProps).map(p => [p, `The ${p}`]));
+                schema[key] = Object.fromEntries(Array.from(aiPromise.accessedProps).map((p) => [p, `The ${p}`]));
             }
             else {
-                const type = aiPromise._options?.type;
+                // Access private _options through type-safe assertion
+                const options = aiPromise._options;
+                const type = options?.type;
                 if (type === 'boolean') {
                     schema[key] = 'true | false';
                 }
@@ -549,10 +596,8 @@ export function isAIPromise(value) {
  * Get the raw AIPromise from a proxied value
  */
 export function getRawPromise(value) {
-    if (RAW_PROMISE_SYMBOL in value) {
-        return value[RAW_PROMISE_SYMBOL];
-    }
-    return value;
+    const raw = value[RAW_PROMISE_SYMBOL];
+    return raw ?? value;
 }
 // ============================================================================
 // Factory Functions
@@ -644,16 +689,26 @@ export function createAITemplateFunction(type, baseOptions) {
         }
         // If we're in recording mode (inside a .map() callback), capture this operation
         if (isInRecordingMode()) {
-            const batchType = type === 'text' ? 'text' : type === 'boolean' ? 'boolean' : type === 'list' ? 'list' : 'object';
+            const batchType = type === 'text'
+                ? 'text'
+                : type === 'boolean'
+                    ? 'boolean'
+                    : type === 'list'
+                        ? 'list'
+                        : 'object';
             captureOperation(prompt, batchType, options.baseSchema, options.system);
         }
-        const promise = new AIPromise(prompt, { ...options, type });
+        const promise = new AIPromise(prompt, {
+            ...options,
+            ...(type !== undefined && { type }),
+        });
         // Add dependencies
         for (const dep of dependencies) {
             promise.addDependency(dep.promise, dep.path);
         }
         return promise;
     }
+    // Return type matches the declared intersection type
     return templateFn;
 }
 // ============================================================================
@@ -709,10 +764,16 @@ function createStreamingAIPromise(promise, options) {
     // 2. The type parameter T corresponds to the expected output type for each mode
     const extractFinalValue = (obj) => {
         let value = obj;
-        if (promiseOptions.type === 'text' && typeof value === 'object' && value !== null && 'text' in value) {
+        if (promiseOptions.type === 'text' &&
+            typeof value === 'object' &&
+            value !== null &&
+            'text' in value) {
             value = value.text;
         }
-        else if (promiseOptions.type === 'boolean' && typeof value === 'object' && value !== null && 'answer' in value) {
+        else if (promiseOptions.type === 'boolean' &&
+            typeof value === 'object' &&
+            value !== null &&
+            'answer' in value) {
             const answer = value.answer;
             // When type === 'boolean', T is constrained to boolean at the call site.
             // TypeScript can't express this dependent relationship, so we use a simple cast.
@@ -720,7 +781,10 @@ function createStreamingAIPromise(promise, options) {
             const booleanValue = answer === 'true' || answer === true;
             value = booleanValue;
         }
-        else if ((promiseOptions.type === 'list' || promiseOptions.type === 'extract') && typeof value === 'object' && value !== null && 'items' in value) {
+        else if ((promiseOptions.type === 'list' || promiseOptions.type === 'extract') &&
+            typeof value === 'object' &&
+            value !== null &&
+            'items' in value) {
             value = value.items;
         }
         return value;
@@ -744,10 +808,12 @@ function createStreamingAIPromise(promise, options) {
             const result = await streamText({
                 model: promiseOptions.model || 'sonnet',
                 prompt: finalPrompt,
-                system: promiseOptions.system,
-                temperature: promiseOptions.temperature,
-                maxTokens: promiseOptions.maxTokens,
-                abortSignal: options?.abortSignal,
+                ...(promiseOptions.system !== undefined && { system: promiseOptions.system }),
+                ...(promiseOptions.temperature !== undefined && {
+                    temperature: promiseOptions.temperature,
+                }),
+                ...(promiseOptions.maxTokens !== undefined && { maxTokens: promiseOptions.maxTokens }),
+                ...(options?.abortSignal !== undefined && { abortSignal: options.abortSignal }),
             });
             let fullText = '';
             for await (const chunk of result.textStream) {
@@ -785,10 +851,12 @@ function createStreamingAIPromise(promise, options) {
                 model: promiseOptions.model || 'sonnet',
                 schema,
                 prompt: finalPrompt,
-                system: promiseOptions.system,
-                temperature: promiseOptions.temperature,
-                maxTokens: promiseOptions.maxTokens,
-                abortSignal: options?.abortSignal,
+                ...(promiseOptions.system !== undefined && { system: promiseOptions.system }),
+                ...(promiseOptions.temperature !== undefined && {
+                    temperature: promiseOptions.temperature,
+                }),
+                ...(promiseOptions.maxTokens !== undefined && { maxTokens: promiseOptions.maxTokens }),
+                ...(options?.abortSignal !== undefined && { abortSignal: options.abortSignal }),
             });
             let lastPartial = {};
             for await (const partial of result.partialObjectStream) {
@@ -809,6 +877,7 @@ function createStreamingAIPromise(promise, options) {
     async function* createMainStream() {
         if (promiseOptions.type === 'text') {
             for await (const chunk of createTextStream()) {
+                // When type is 'text', T is string, so the conditional type resolves to string
                 yield chunk;
             }
         }
@@ -818,6 +887,7 @@ function createStreamingAIPromise(promise, options) {
             for await (const partial of createPartialObjectStream()) {
                 const items = partial.items || [];
                 for (let i = lastLength; i < items.length; i++) {
+                    // List items are strings, cast to the conditional return type
                     yield items[i];
                 }
                 lastLength = items.length;
@@ -825,6 +895,7 @@ function createStreamingAIPromise(promise, options) {
         }
         else {
             for await (const partial of createPartialObjectStream()) {
+                // For object types, T is not string, so conditional type resolves to Partial<T>
                 yield partial;
             }
         }