ai-functions 0.3.0 → 0.4.0

package/dist/ai.d.ts

@@ -0,0 +1,285 @@
+/**
+ * AI() and ai() - Core AI function constructors
+ *
+ * These provide the main entry points for AI-powered functions,
+ * with full RPC promise pipelining support via rpc.do.
+ */
+type RpcPromise<T> = Promise<T>;
+/**
+ * Base class for RPC service targets
+ * This is a placeholder for services that want to expose methods over RPC
+ */
+export declare abstract class RpcTarget {
+}
+/**
+ * Options for RPC session (connection to remote AI service)
+ */
+export interface RPCSessionOptions {
+    /** WebSocket URL for RPC connection */
+    wsUrl?: string;
+    /** HTTP URL for RPC fallback */
+    httpUrl?: string;
+    /** Authentication token */
+    token?: string;
+}
+import type { SimpleSchema } from './schema.js';
+import type { LanguageModel } from 'ai';
+import type { AIClient, AIFunctionDefinition, AIGenerateOptions, AIGenerateResult, JSONSchema, ImageOptions, ImageResult, VideoOptions, VideoResult, WriteOptions, ListResult, ListsResult, FunctionDefinition, DefinedFunction, CodeFunctionDefinition, GenerativeFunctionDefinition, AgenticFunctionDefinition, HumanFunctionDefinition, FunctionRegistry } from './types.js';
+/**
+ * Options for creating an AI RPC client instance
+ */
+export interface AIClientOptions extends RPCSessionOptions {
+    /** Default model to use */
+    model?: string;
+    /** Default temperature */
+    temperature?: number;
+    /** Default max tokens */
+    maxTokens?: number;
+    /** Custom functions available to the AI */
+    functions?: AIFunctionDefinition[];
+}
+/**
+ * Options for AI schema functions (subset of generateObject options)
+ */
+export interface AISchemaOptions {
+    /** Model to use (string alias or LanguageModel) */
+    model?: string | LanguageModel;
+    /** System prompt */
+    system?: string;
+    /** Generation mode */
+    mode?: 'auto' | 'json' | 'tool';
+    /** Temperature (0-2) */
+    temperature?: number;
+    /** Top P sampling */
+    topP?: number;
+    /** Top K sampling */
+    topK?: number;
+    /** Presence penalty */
+    presencePenalty?: number;
+    /** Frequency penalty */
+    frequencyPenalty?: number;
+    /** Max tokens to generate */
+    maxTokens?: number;
+    /** Max retries on failure */
+    maxRetries?: number;
+    /** Abort signal */
+    abortSignal?: AbortSignal;
+    /** Custom headers */
+    headers?: Record<string, string>;
+}
+/**
+ * Schema-based functions
+ */
+type SchemaFunctions<T extends Record<string, SimpleSchema>> = {
+    [K in keyof T]: (prompt?: string, options?: AISchemaOptions) => Promise<InferSimpleSchemaResult<T[K]>>;
+};
+/**
+ * Create AI functions from schemas
+ *
+ * @example
+ * ```ts
+ * const ai = AI({
+ *   storyBrand: {
+ *     hero: 'Who is the customer?',
+ *     problem: {
+ *       internal: 'What internal problem do they face?',
+ *       external: 'What external challenge exists?',
+ *       philosophical: 'Why is this wrong?',
+ *     },
+ *     guide: 'Who helps them? (the brand)',
+ *     plan: ['What are the steps to success?'],
+ *     callToAction: 'What should they do?',
+ *     success: 'What does success look like?',
+ *     failure: 'What happens if they fail?',
+ *   },
+ *   recipe: {
+ *     name: 'Recipe name',
+ *     type: 'food | drink | dessert',
+ *     servings: 'How many servings? (number)',
+ *     ingredients: ['List all ingredients'],
+ *     steps: ['Cooking steps in order'],
+ *   },
+ * })
+ *
+ * // Call the generated functions
+ * const brand = await ai.storyBrand('Acme Corp sells widgets')
+ * const dinner = await ai.recipe('Italian pasta for 4 people')
+ * ```
+ */
+export declare function AI<T extends Record<string, SimpleSchema>>(schemas: T, defaultOptions?: AISchemaOptions): SchemaFunctions<T>;
+/**
+ * Create an AI RPC client instance
+ *
+ * @example
+ * ```ts
+ * // Connect to remote AI service
+ * const ai = AI({ wsUrl: 'wss://ai.example.com/rpc' })
+ *
+ * // Use promise pipelining - single round trip!
+ * const result = ai.generate({ prompt: 'Hello' })
+ * const upper = result.text.map(t => t.toUpperCase())
+ * console.log(await upper)
+ *
+ * // Dynamic function calling
+ * const summary = await ai.summarize({ text: longText })
+ * ```
+ */
+export declare function AI(options: AIClientOptions): AIClient & Record<string, (...args: unknown[]) => RpcPromise<unknown>>;
+/**
+ * Infer result type from simple schema
+ */
+type InferSimpleSchemaResult<T> = T extends string ? string : T extends [string] ? string[] : T extends {
+    [K: string]: SimpleSchema;
+} ? {
+    [K in keyof T]: InferSimpleSchemaResult<T[K]>;
+} : unknown;
+/**
+ * Helper to create a function that supports both regular calls and tagged template literals
+ * @example
+ * const fn = withTemplate((prompt) => doSomething(prompt))
+ * fn('hello')      // regular call
+ * fn`hello ${name}` // tagged template literal
+ */
+export declare function withTemplate<TArgs extends unknown[], TReturn>(fn: (prompt: string, ...args: TArgs) => TReturn): ((prompt: string, ...args: TArgs) => TReturn) & ((strings: TemplateStringsArray, ...values: unknown[]) => TReturn);
+/**
+ * Configure the default AI client
+ */
+export declare function configureAI(options: AIClientOptions): void;
+/**
+ * Base class for implementing AI services
+ *
+ * Extend this class to create your own AI service implementation.
+ *
+ * @example
+ * ```ts
+ * class MyAIService extends AIServiceTarget {
+ *   async generate(options: AIGenerateOptions): Promise<AIGenerateResult> {
+ *     // Your implementation
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class AIServiceTarget extends RpcTarget implements AIClient {
+    abstract generate(options: AIGenerateOptions): RpcPromise<AIGenerateResult>;
+    abstract do(action: string, context?: unknown): RpcPromise<unknown>;
+    abstract is(value: unknown, type: string | JSONSchema): RpcPromise<boolean>;
+    abstract code(prompt: string, language?: string): RpcPromise<string>;
+    abstract decide<T extends string>(options: T[], context?: string): RpcPromise<T>;
+    abstract diagram(description: string, format?: 'mermaid' | 'svg' | 'ascii'): RpcPromise<string>;
+    abstract image(prompt: string, options?: ImageOptions): RpcPromise<ImageResult>;
+    abstract video(prompt: string, options?: VideoOptions): RpcPromise<VideoResult>;
+    abstract write(prompt: string, options?: WriteOptions): RpcPromise<string>;
+    abstract list(prompt: string): RpcPromise<ListResult>;
+    abstract lists(prompt: string): RpcPromise<ListsResult>;
+}
+/**
+ * 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<TArgs, TReturn>(definition: FunctionDefinition<TArgs, TReturn>): DefinedFunction<TArgs, TReturn>;
+/**
+ * Global function registry
+ *
+ * Note: This is in-memory only. For persistence, use mdxai or mdxdb packages.
+ */
+export declare const functions: FunctionRegistry;
+/**
+ * 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',
+ * })
+ * ```
+ */
+declare function autoDefineImpl(name: string, args: Record<string, unknown>): Promise<DefinedFunction>;
+/**
+ * Define functions - auto-define or use typed helpers
+ */
+export declare const define: typeof autoDefineImpl & {
+    /**
+     * Define a code generation function
+     */
+    code: <TArgs, TReturn>(definition: Omit<CodeFunctionDefinition<TArgs, TReturn>, "type">) => DefinedFunction<TArgs, TReturn>;
+    /**
+     * Define a generative function
+     */
+    generative: <TArgs, TReturn>(definition: Omit<GenerativeFunctionDefinition<TArgs, TReturn>, "type">) => DefinedFunction<TArgs, TReturn>;
+    /**
+     * Define an agentic function
+     */
+    agentic: <TArgs, TReturn>(definition: Omit<AgenticFunctionDefinition<TArgs, TReturn>, "type">) => DefinedFunction<TArgs, TReturn>;
+    /**
+     * Define a human-in-the-loop function
+     */
+    human: <TArgs, TReturn>(definition: Omit<HumanFunctionDefinition<TArgs, TReturn>, "type">) => DefinedFunction<TArgs, TReturn>;
+};
+/**
+ * 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;
+}
+/**
+ * Default AI instance with auto-define capability
+ *
+ * @example
+ * ```ts
+ * import { ai } from 'ai-functions'
+ *
+ * // Auto-define and call
+ * const result = await ai.summarize({ text: 'Long article...' })
+ *
+ * // Access functions registry
+ * ai.functions.list()
+ *
+ * // Define explicitly
+ * ai.define.generative({ name: 'translate', ... })
+ * ```
+ */
+export declare const ai: AIProxy;
+export {};
+//# sourceMappingURL=ai.d.ts.map

package/dist/ai.d.ts.map

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