ai-functions 2.1.3 → 2.4.0

package/src/primitives.ts

@@ -39,7 +39,23 @@ import {
 } from './ai-promise.js'
 import { generateObject, generateText } from './generate.js'
 import type { SimpleSchema } from './schema.js'
-import type { HumanChannel } from './types.js'
+import type {
+  AgenticFunctionDefinition,
+  AutoDefineResult,
+  CodeFunctionDefinition,
+  DefinedFunction,
+  FunctionDefinition,
+  FunctionRegistry,
+  GenerativeFunctionDefinition,
+  HumanChannel,
+  HumanFunctionDefinition,
+} from './types.js'
+import {
+  createDefinedFunction,
+  defineFunction,
+  functions,
+  generateCode,
+} from './function-registry.js'
 
 // ============================================================================
 // Types
@@ -122,42 +138,77 @@ export async function generate(
 }
 
 // Helper functions
-async function generateTextContent(prompt: string, model: string, options: GenerateOptions): Promise<string> {
-  const result = await generateText({ model, prompt, system: options.system, temperature: options.temperature, maxTokens: options.maxTokens })
+async function generateTextContent(
+  prompt: string,
+  model: string,
+  options: GenerateOptions
+): Promise<string> {
+  const result = await generateText({
+    model,
+    prompt,
+    ...(options.system !== undefined && { system: options.system }),
+    ...(options.temperature !== undefined && { temperature: options.temperature }),
+    ...(options.maxTokens !== undefined && { maxTokens: options.maxTokens }),
+  })
   return result.text
 }
 
-async function generateJsonContent(prompt: string, model: string, schema: SimpleSchema | undefined, options: GenerateOptions): Promise<unknown> {
+async function generateJsonContent(
+  prompt: string,
+  model: string,
+  schema: SimpleSchema | undefined,
+  options: GenerateOptions
+): Promise<unknown> {
   const effectiveSchema = schema || { result: 'The generated result' }
-  const result = await generateObject({ model, schema: effectiveSchema, prompt, system: options.system, temperature: options.temperature, maxTokens: options.maxTokens })
+  const result = await generateObject({
+    model,
+    schema: effectiveSchema,
+    prompt,
+    ...(options.system !== undefined && { system: options.system }),
+    ...(options.temperature !== undefined && { temperature: options.temperature }),
+    ...(options.maxTokens !== undefined && { maxTokens: options.maxTokens }),
+  })
   return result.object
 }
 
-async function generateCodeContent(prompt: string, model: string, language: string, options: GenerateOptions): Promise<string> {
+async function generateCodeContent(
+  prompt: string,
+  model: string,
+  language: string,
+  options: GenerateOptions
+): Promise<string> {
   const result = await generateObject({
     model,
     schema: { code: `The ${language} implementation code` },
     prompt: `Generate ${language} code for: ${prompt}`,
     system: `You are an expert ${language} developer. Generate clean, well-documented code.`,
-    temperature: options.temperature,
-    maxTokens: options.maxTokens,
+    ...(options.temperature !== undefined && { temperature: options.temperature }),
+    ...(options.maxTokens !== undefined && { maxTokens: options.maxTokens }),
   })
   return (result.object as { code: string }).code
 }
 
-async function generateListContent(prompt: string, model: string, options: GenerateOptions): Promise<string[]> {
+async function generateListContent(
+  prompt: string,
+  model: string,
+  options: GenerateOptions
+): Promise<string[]> {
   const result = await generateObject({
     model,
     schema: { items: ['List items'] },
     prompt,
     system: options.system || 'Generate a list of items based on the prompt.',
-    temperature: options.temperature,
-    maxTokens: options.maxTokens,
+    ...(options.temperature !== undefined && { temperature: options.temperature }),
+    ...(options.maxTokens !== undefined && { maxTokens: options.maxTokens }),
   })
   return (result.object as { items: string[] }).items
 }
 
-async function generateListsContent(prompt: string, model: string, options: GenerateOptions): Promise<Record<string, string[]>> {
+async function generateListsContent(
+  prompt: string,
+  model: string,
+  options: GenerateOptions
+): Promise<Record<string, string[]>> {
   const result = await generateObject({
     model,
     schema: {
@@ -165,9 +216,11 @@ async function generateListsContent(prompt: string, model: string, options: Gene
       data: 'JSON string containing the categorized lists',
     },
     prompt: `Generate categorized lists for: ${prompt}\n\nFirst identify appropriate category names, then provide the lists as a JSON object.`,
-    system: options.system || 'Generate multiple categorized lists. Determine appropriate categories based on the prompt.',
-    temperature: options.temperature,
-    maxTokens: options.maxTokens,
+    system:
+      options.system ||
+      'Generate multiple categorized lists. Determine appropriate categories based on the prompt.',
+    ...(options.temperature !== undefined && { temperature: options.temperature }),
+    ...(options.maxTokens !== undefined && { maxTokens: options.maxTokens }),
   })
   const obj = result.object as { categories: string[]; data: string }
   try {
@@ -181,79 +234,114 @@ async function generateListsContent(prompt: string, model: string, options: Gene
   }
 }
 
-async function generateBooleanContent(prompt: string, model: string, options: GenerateOptions): Promise<boolean> {
+async function generateBooleanContent(
+  prompt: string,
+  model: string,
+  options: GenerateOptions
+): Promise<boolean> {
   const result = await generateObject({
     model,
     schema: { answer: 'true | false' },
     prompt,
     system: options.system || 'Answer the question with true or false.',
     temperature: options.temperature ?? 0,
-    maxTokens: options.maxTokens,
+    ...(options.maxTokens !== undefined && { maxTokens: options.maxTokens }),
   })
   return (result.object as { answer: string }).answer === 'true'
 }
 
-async function generateSummaryContent(prompt: string, model: string, options: GenerateOptions): Promise<string> {
+async function generateSummaryContent(
+  prompt: string,
+  model: string,
+  options: GenerateOptions
+): Promise<string> {
   const result = await generateObject({
     model,
     schema: { summary: 'A concise summary of the content' },
     prompt: `Summarize the following:\n\n${prompt}`,
     system: options.system || 'Create a clear, concise summary.',
-    temperature: options.temperature,
-    maxTokens: options.maxTokens,
+    ...(options.temperature !== undefined && { temperature: options.temperature }),
+    ...(options.maxTokens !== undefined && { maxTokens: options.maxTokens }),
   })
   return (result.object as { summary: string }).summary
 }
 
-async function generateExtractContent(prompt: string, model: string, schema: SimpleSchema | undefined, options: GenerateOptions): Promise<unknown[]> {
-  const effectiveSchema = schema || { items: ['Extracted items'] }
+async function generateExtractContent(
+  prompt: string,
+  model: string,
+  schema: SimpleSchema | undefined,
+  options: GenerateOptions
+): Promise<unknown[]> {
+  const effectiveSchema = schema || {
+    items: ['Array of extracted items as strings - extract ALL matching items from the text'],
+  }
   const result = await generateObject({
     model,
     schema: effectiveSchema,
-    prompt: `Extract from the following:\n\n${prompt}`,
-    system: options.system || 'Extract the requested information.',
-    temperature: options.temperature,
-    maxTokens: options.maxTokens,
+    prompt: `Extract the following from the text below. Return ALL matching items in the items array.
+
+Task: ${prompt}
+
+IMPORTANT: Return the extracted items as an array. If the task asks for email addresses, return all email addresses found. If it asks for names, return all names found. Do not return an empty array if there are items to extract.`,
+    system:
+      options.system ||
+      'You are a precise data extraction assistant. Extract exactly what is requested and return it as an array of items. Be thorough - find ALL matching items in the text.',
+    temperature: options.temperature ?? 0, // Use low temperature for extraction tasks
+    ...(options.maxTokens !== undefined && { maxTokens: options.maxTokens }),
   })
   const obj = result.object as Record<string, unknown>
-  if ('items' in obj && Array.isArray(obj.items)) {
-    return obj.items
+  if ('items' in obj && Array.isArray(obj['items'])) {
+    return obj['items']
   }
   return Object.values(obj).flat() as unknown[]
 }
 
-async function generateYamlContent(prompt: string, model: string, options: GenerateOptions): Promise<string> {
+async function generateYamlContent(
+  prompt: string,
+  model: string,
+  options: GenerateOptions
+): Promise<string> {
   const result = await generateObject({
     model,
     schema: { yaml: 'The YAML content' },
     prompt: `Generate YAML for: ${prompt}`,
     system: options.system || 'Generate valid YAML content.',
-    temperature: options.temperature,
-    maxTokens: options.maxTokens,
+    ...(options.temperature !== undefined && { temperature: options.temperature }),
+    ...(options.maxTokens !== undefined && { maxTokens: options.maxTokens }),
   })
   return (result.object as { yaml: string }).yaml
 }
 
-async function generateDiagramContent(prompt: string, model: string, format: string, options: GenerateOptions): Promise<string> {
+async function generateDiagramContent(
+  prompt: string,
+  model: string,
+  format: string,
+  options: GenerateOptions
+): Promise<string> {
   const result = await generateObject({
     model,
     schema: { diagram: `The ${format} diagram code` },
     prompt: `Generate a ${format} diagram for: ${prompt}`,
     system: options.system || `Generate ${format} diagram syntax.`,
-    temperature: options.temperature,
-    maxTokens: options.maxTokens,
+    ...(options.temperature !== undefined && { temperature: options.temperature }),
+    ...(options.maxTokens !== undefined && { maxTokens: options.maxTokens }),
   })
   return (result.object as { diagram: string }).diagram
 }
 
-async function generateSlidesContent(prompt: string, model: string, slideCount: number, options: GenerateOptions): Promise<string> {
+async function generateSlidesContent(
+  prompt: string,
+  model: string,
+  slideCount: number,
+  options: GenerateOptions
+): Promise<string> {
   const result = await generateObject({
     model,
     schema: { slides: `Slidev/Marp markdown with ${slideCount} slides` },
     prompt: `Generate a ${slideCount}-slide presentation about: ${prompt}`,
     system: options.system || 'Generate markdown slides in Slidev/Marp format.',
-    temperature: options.temperature,
-    maxTokens: options.maxTokens,
+    ...(options.temperature !== undefined && { temperature: options.temperature }),
+    ...(options.maxTokens !== undefined && { maxTokens: options.maxTokens }),
   })
   return (result.object as { slides: string }).slides
 }
@@ -445,17 +533,14 @@ function doImpl(
     prompt = promptOrStrings as string
   }
 
-  const promise = new AIPromise<{ summary: string; actions: string[] }>(
-    prompt,
-    {
-      type: 'object',
-      baseSchema: {
-        summary: 'Summary of what was done',
-        actions: ['List of actions taken'],
-      },
-      system: 'You are a task executor. Describe what actions you would take.',
-    }
-  )
+  const promise = new AIPromise<{ summary: string; actions: string[] }>(prompt, {
+    type: 'object',
+    baseSchema: {
+      summary: 'Summary of what was done',
+      actions: ['List of actions taken'],
+    },
+    system: 'You are a task executor. Describe what actions you would take.',
+  })
 
   for (const dep of dependencies) {
     promise.addDependency(dep.promise, dep.path)
@@ -474,7 +559,11 @@ export { doImpl as do }
  * const { summary, findings, sources } = await research`${competitor} vs our product`
  * ```
  */
-export const research = createAITemplateFunction<{ summary: string; findings: string[]; sources: string[] }>('object', {
+export const research = createAITemplateFunction<{
+  summary: string
+  findings: string[]
+  sources: string[]
+}>('object', {
   system: 'You are a research analyst. Provide thorough research.',
 })
 
@@ -545,10 +634,7 @@ export function decide(
   let criteria: string
 
   if (Array.isArray(criteriaOrStrings) && 'raw' in criteriaOrStrings) {
-    criteria = criteriaOrStrings.reduce(
-      (acc, str, i) => acc + str + (templateArgs[i] ?? ''),
-      ''
-    )
+    criteria = criteriaOrStrings.reduce((acc, str, i) => acc + str + (templateArgs[i] ?? ''), '')
   } else {
     criteria = criteriaOrStrings as string
   }
@@ -571,11 +657,12 @@ export function decide(
 
     // Override resolve to return the actual option
     const originalResolve = promise.resolve.bind(promise)
-    ;(promise as any).resolve = async () => {
-      const result = await originalResolve() as { chosenIndex: string | number }
-      const index = typeof result.chosenIndex === 'string'
-        ? parseInt(result.chosenIndex, 10)
-        : result.chosenIndex
+    ;(promise as { resolve: () => Promise<T> }).resolve = async () => {
+      const result = (await originalResolve()) as { chosenIndex: string | number }
+      const index =
+        typeof result.chosenIndex === 'string'
+          ? parseInt(result.chosenIndex, 10)
+          : result.chosenIndex
       return options[index - 1] as T
     }
 
@@ -618,13 +705,453 @@ export const ask = createAITemplateFunction<HumanResult<string>>('object', {
 /**
  * Request human approval
  */
-export const approve = createAITemplateFunction<HumanResult<{ approved: boolean; notes?: string }>>('object', {
-  system: 'Generate an approval request.',
-})
+export const approve = createAITemplateFunction<HumanResult<{ approved: boolean; notes?: string }>>(
+  'object',
+  {
+    system: 'Generate an approval request.',
+  }
+)
 
 /**
  * Request human review
  */
-export const review = createAITemplateFunction<HumanResult<{ rating?: number; feedback: string; approved?: boolean }>>('object', {
+export const review = createAITemplateFunction<
+  HumanResult<{ rating?: number; feedback: string; approved?: boolean }>
+>('object', {
   system: 'Generate a review request.',
 })
+
+// ============================================================================
+// Auto-Define Functions
+//
+// Inlined from former ai-proxy.ts. These helpers provide the auto-define
+// convenience layer (analyze a name + example args, infer a function type and
+// schema, register it). Property-access tracking lives entirely in
+// ai-promise.ts; this section is a shallow dispatch over define() and
+// generateObject().
+// ============================================================================
+
+/**
+ * Analyze a function call and determine what type of function it should be
+ */
+async function analyzeFunction(
+  name: string,
+  args: Record<string, unknown>
+): Promise<AutoDefineResult> {
+  // Convert camelCase/snake_case to readable name
+  const readableName = name
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/_/g, ' ')
+    .toLowerCase()
+    .trim()
+
+  const argDescriptions = Object.entries(args)
+    .map(([key, value]) => {
+      const type = Array.isArray(value) ? 'array' : typeof value
+      return `  - ${key}: ${type} (example: ${JSON.stringify(value).slice(0, 50)})`
+    })
+    .join('\n')
+
+  const result = await generateObject({
+    model: 'sonnet',
+    schema: {
+      type: 'code | generative | agentic | human',
+      reasoning: 'Why this function type is appropriate (1-2 sentences)',
+      description: 'What this function does',
+      output: 'string | object | image | video | audio',
+      returnType: 'Schema for the return type as a SimpleSchema object',
+      system: 'System prompt for the AI (if generative/agentic)',
+      promptTemplate: 'Prompt template with {{arg}} placeholders',
+      instructions: 'Instructions for agentic/human functions',
+      needsTools: 'true | false',
+      suggestedTools: ['Names of tools that might be needed'],
+      channel: 'slack | email | web | sms | custom',
+    },
+    system: `You are an expert at designing AI functions. Analyze the function name and arguments to determine the best function type.
+
+Function Types:
+- "code": A DETERMINISTIC algorithm with no model at run time — a pure calculation, data transformation, or rule that always produces the same output for the same input (e.g. tax math, parsing, formatting). A self-contained TypeScript body can be written for it once.
+- "generative": For generating content (text, summaries, translations, creative writing, structured data) — needs a model on every call
+- "agentic": For complex tasks requiring multiple steps, research, or tool use (research, planning, multi-step workflows)
+- "human": For tasks requiring human judgment, approval, or input (approvals, reviews, decisions)
+
+Guidelines:
+- Most functions should be "generative" - they generate content or structured data
+- Use "code" ONLY when the task is a deterministic algorithm expressible as a self-contained function body (no model, no external state). If it needs a model at run time, it is "generative", not "code".
+- Use "agentic" when the task requires research, multiple steps, or external tool use
+- Use "human" when human judgment/approval is essential`,
+    prompt: `Analyze this function call and determine how to define it:
+
+Function Name: ${name}
+Readable Name: ${readableName}
+Arguments:
+${argDescriptions || '  (no arguments)'}
+
+Determine:
+1. What type of function this should be
+2. What it should return
+3. How it should be implemented`,
+  })
+
+  const analysis = result.object as {
+    type: string
+    reasoning: string
+    description: string
+    output: string
+    returnType: unknown
+    system: string
+    promptTemplate: string
+    instructions: string
+    needsTools: string
+    suggestedTools: string[]
+    channel: string
+  }
+
+  // Build the function definition based on the analysis
+  let definition: FunctionDefinition
+
+  const baseDefinition = {
+    name,
+    description: analysis.description,
+    args: inferArgsSchema(args),
+    returnType: analysis.returnType as SimpleSchema,
+  }
+
+  switch (analysis.type) {
+    case 'code': {
+      // `Code` is deterministic — it cannot be a call-time model invocation.
+      // Author a self-contained TS body ONCE here (at define time), then carry
+      // it as an inline `code` body so every subsequent call is deterministic.
+      const authored = await generateCode(
+        {
+          name,
+          description: analysis.description,
+          args: baseDefinition.args,
+          returnType: baseDefinition.returnType,
+          language: 'typescript',
+          instructions: `${analysis.instructions ?? ''}\n\nWrite the body of a single function that receives a parameter named \`args\` (an object with the keys above) and \`return\`s the result. Do not include the function signature, imports, or surrounding declarations — only the statements that go inside the function body.`.trim(),
+        },
+        args
+      )
+      definition = {
+        ...baseDefinition,
+        type: 'code' as const,
+        language: 'typescript' as const,
+        instructions: analysis.instructions,
+        code: authored,
+      }
+      break
+    }
+
+    case 'agentic':
+      definition = {
+        ...baseDefinition,
+        type: 'agentic' as const,
+        instructions: analysis.instructions || `Complete the ${readableName} task`,
+        promptTemplate: analysis.promptTemplate,
+        tools: [], // Tools would need to be provided separately
+        maxIterations: 10,
+      }
+      break
+
+    case 'human':
+      definition = {
+        ...baseDefinition,
+        type: 'human' as const,
+        channel: (analysis.channel || 'web') as HumanChannel,
+        instructions:
+          analysis.instructions || `Please review and respond to this ${readableName} request`,
+        promptTemplate: analysis.promptTemplate,
+      }
+      break
+
+    case 'generative':
+    default:
+      definition = {
+        ...baseDefinition,
+        type: 'generative' as const,
+        output: (analysis.output || 'object') as 'string' | 'object' | 'image' | 'video',
+        system: analysis.system,
+        promptTemplate: analysis.promptTemplate || `{{${Object.keys(args)[0] || 'input'}}}`,
+      }
+      break
+  }
+
+  return {
+    type: analysis.type as 'code' | 'generative' | 'agentic' | 'human',
+    reasoning: analysis.reasoning,
+    definition,
+  }
+}
+
+/**
+ * Infer a schema from example arguments
+ */
+function inferArgsSchema(
+  args: Record<string, unknown>
+): Record<string, string | string[] | Record<string, unknown>> {
+  const schema: Record<string, string | string[] | Record<string, unknown>> = {}
+
+  for (const [key, value] of Object.entries(args)) {
+    if (typeof value === 'string') {
+      schema[key] = `The ${key.replace(/([A-Z])/g, ' $1').toLowerCase()}`
+    } else if (typeof value === 'number') {
+      schema[key] = `The ${key.replace(/([A-Z])/g, ' $1').toLowerCase()} (number)`
+    } else if (typeof value === 'boolean') {
+      schema[key] = `Whether ${key.replace(/([A-Z])/g, ' $1').toLowerCase()} (boolean)`
+    } else if (Array.isArray(value)) {
+      if (value.length > 0 && typeof value[0] === 'string') {
+        schema[key] = [`List of ${key.replace(/([A-Z])/g, ' $1').toLowerCase()}`]
+      } else {
+        schema[key] = [`Items for ${key.replace(/([A-Z])/g, ' $1').toLowerCase()}`]
+      }
+    } else if (typeof value === 'object' && value !== null) {
+      schema[key] = inferArgsSchema(value as Record<string, unknown>)
+    } else {
+      schema[key] = `The ${key.replace(/([A-Z])/g, ' $1').toLowerCase()}`
+    }
+  }
+
+  return schema
+}
+
+/**
+ * Auto-define a function based on its name and arguments, or define with explicit definition
+ *
+ * When called with (name, args), uses AI to analyze and determine:
+ * - What type of function it should be (code, generative, agentic, human)
+ * - What it should return
+ * - How it should be implemented
+ *
+ * When called with a FunctionDefinition, creates the function directly.
+ *
+ * @example
+ * ```ts
+ * // Auto-define from name and example args
+ * const planTrip = await define('planTrip', { destination: 'Tokyo', travelers: 2 })
+ *
+ * // Or define explicitly
+ * const summarize = define.generative({
+ *   name: 'summarize',
+ *   args: { text: 'Text to summarize' },
+ *   output: 'string',
+ * })
+ *
+ * // Or with full definition
+ * const fn = defineFunction({
+ *   type: 'generative',
+ *   name: 'translate',
+ *   args: { text: 'Text', lang: 'Target language' },
+ *   output: 'string',
+ * })
+ * ```
+ */
+async function autoDefineImpl(
+  name: string,
+  args: Record<string, unknown>
+): Promise<DefinedFunction> {
+  // Check if already defined
+  const existing = functions.get(name)
+  if (existing) {
+    return existing
+  }
+
+  // Analyze and define the function
+  const { definition } = await analyzeFunction(name, args)
+
+  // Create the defined function
+  const definedFn = createDefinedFunction(definition)
+
+  // Store in registry
+  functions.set(name, definedFn)
+
+  return definedFn
+}
+
+/**
+ * Define functions - auto-define or use typed helpers
+ */
+export const define = Object.assign(autoDefineImpl, {
+  /**
+   * Define a **deterministic** code function (a handler — no LLM at call time).
+   *
+   * Supply a `handler` (canonical) or an inline `code` body. To have a model
+   * *author* code instead, use {@link generateCode} or `define.generative`.
+   */
+  code: <TOutput, TInput>(
+    definition: Omit<CodeFunctionDefinition<TOutput, TInput>, 'type'>
+  ): DefinedFunction<TOutput, TInput> => {
+    const fn = defineFunction({ type: 'code', ...definition } as CodeFunctionDefinition<
+      TOutput,
+      TInput
+    >)
+    functions.set(definition.name, fn as DefinedFunction)
+    return fn
+  },
+
+  /**
+   * Define a generative function
+   */
+  generative: <TOutput, TInput>(
+    definition: Omit<GenerativeFunctionDefinition<TOutput, TInput>, 'type'>
+  ): DefinedFunction<TOutput, TInput> => {
+    const fn = defineFunction({ type: 'generative', ...definition } as GenerativeFunctionDefinition<
+      TOutput,
+      TInput
+    >)
+    functions.set(definition.name, fn as DefinedFunction)
+    return fn
+  },
+
+  /**
+   * Define an agentic function
+   */
+  agentic: <TOutput, TInput>(
+    definition: Omit<AgenticFunctionDefinition<TOutput, TInput>, 'type'>
+  ): DefinedFunction<TOutput, TInput> => {
+    const fn = defineFunction({ type: 'agentic', ...definition } as AgenticFunctionDefinition<
+      TOutput,
+      TInput
+    >)
+    functions.set(definition.name, fn as DefinedFunction)
+    return fn
+  },
+
+  /**
+   * Define a human-in-the-loop function
+   */
+  human: <TOutput, TInput>(
+    definition: Omit<HumanFunctionDefinition<TOutput, TInput>, 'type'>
+  ): DefinedFunction<TOutput, TInput> => {
+    const fn = defineFunction({ type: 'human', ...definition } as HumanFunctionDefinition<
+      TOutput,
+      TInput
+    >)
+    functions.set(definition.name, fn as DefinedFunction)
+    return fn
+  },
+})
+
+// ============================================================================
+// AI Proxy - Smart AI Client with Auto-Definition
+// ============================================================================
+
+/** Known built-in method names that should not be auto-defined */
+const BUILTIN_METHODS = new Set([
+  'do',
+  'is',
+  'code',
+  'decide',
+  'diagram',
+  'generate',
+  'image',
+  'video',
+  'write',
+  'list',
+  'lists',
+  'functions',
+  'define',
+  'defineFunction',
+  'then',
+  'catch',
+  'finally',
+])
+
+/**
+ * Type for the AI proxy with auto-define capability
+ */
+export interface AIProxy {
+  /** Function registry */
+  functions: FunctionRegistry
+  /** Define functions */
+  define: typeof define
+  /** Define a function with full definition */
+  defineFunction: typeof defineFunction
+  /** Dynamic function calls */
+  [key: string]: unknown
+}
+
+/**
+ * Create a smart AI client that auto-defines functions on first call
+ *
+ * @example
+ * ```ts
+ * const ai = createSmartAI()
+ *
+ * // First call - auto-defines the function
+ * const trip = await ai.planTrip({
+ *   destination: 'Tokyo',
+ *   dates: { start: '2024-03-01', end: '2024-03-10' },
+ *   travelers: 2,
+ * })
+ *
+ * // Second call - uses cached definition (in-memory)
+ * const trip2 = await ai.planTrip({
+ *   destination: 'Paris',
+ *   dates: { start: '2024-06-01', end: '2024-06-07' },
+ *   travelers: 4,
+ * })
+ *
+ * // Access registry and define
+ * console.log(ai.functions.list()) // ['planTrip']
+ * ai.define.generative({ name: 'summarize', ... })
+ * ```
+ */
+export function createSmartAI(): AIProxy {
+  const base = {
+    functions,
+    define,
+    defineFunction,
+  }
+
+  return new Proxy(base as AIProxy, {
+    get(target, prop: string) {
+      // Return built-in properties
+      if (prop in target) {
+        return (target as Record<string, unknown>)[prop]
+      }
+
+      // Skip internal properties
+      if (typeof prop === 'symbol' || prop.startsWith('_') || BUILTIN_METHODS.has(prop)) {
+        return undefined
+      }
+
+      // Return a function that auto-defines and calls
+      return async (args: Record<string, unknown> = {}) => {
+        // Check if function is already defined
+        let fn = functions.get(prop)
+
+        if (!fn) {
+          // Auto-define the function
+          fn = await define(prop, args)
+        }
+
+        // Call the function
+        return fn.call(args)
+      }
+    },
+  })
+}
+
+/**
+ * Default AI proxy instance with auto-define capability.
+ *
+ * This is the smart proxy `aiProxy` (re-exported from index.ts as `aiProxy`).
+ * It is intentionally distinct from the `ai` template-tag primitive above —
+ * see `ai` (line ~354) for the template function used like `ai\`...\``.
+ *
+ * @example
+ * ```ts
+ * import { aiProxy } from 'ai-functions'
+ *
+ * // Auto-define and call
+ * const result = await aiProxy.summarize({ text: 'Long article...' })
+ *
+ * // Access functions registry
+ * aiProxy.functions.list()
+ *
+ * // Define explicitly
+ * aiProxy.define.generative({ name: 'translate', ... })
+ * ```
+ */
+export const aiProxy: AIProxy = createSmartAI()