@aeye/ai 0.1.0

package/dist/ai.d.ts

@@ -0,0 +1,204 @@
+/**
+ * AI Class - Main Entry Point
+ *
+ * Instance-based AI library similar to OpenAI's SDK.
+ * Provides type-safe, scoped access to AI capabilities with hooks and context injection.
+ */
+import { Agent, Extend, MessageContentType, Prompt, Tool, ToolCompatible, Tuple } from '@aeye/core';
+import { ChatAPI } from './apis/chat';
+import { EmbedAPI } from './apis/embed';
+import { ImageAPI } from './apis/image';
+import { ModelsAPI } from './apis/models';
+import { SpeechAPI } from './apis/speech';
+import { TranscribeAPI } from './apis/transcribe';
+import { ModelRegistry } from './registry';
+import type { AgentInput, AIBaseMetadata, AIBaseTypes, AIConfig, AIConfigOf, AIContext, AIContextOptional, AIContextRequired, AIContextUser, AIHooks, AIMetadata, AIMetadataRequired, AIMetadataUser, AIProviderNames, AIProviders, AITypesInfer, ComponentFor, ComponentInput, ComponentOutput, Context, LibraryStats, Message, ModelInfo, ModelOverride, PromptInput, Providers, Request, SelectedModelFor, ToolInput, Usage } from './types';
+/**
+ * AI Class
+ *
+ * @template T - AIBaseTypes container with all type information
+ *
+ * @example
+ * ```typescript
+ * const ai = AI.with<AppContext, AppMetadata>()
+ *   .providers({ openai, openrouter })
+ *   .create({
+ *     defaultContext: { baseURL: 'https://api.example.com' },
+ *     providedContext: async (ctx) => ({ db, user }),
+ *     hooks: {
+ *       beforeRequest: async (ctx, request, selected, estimatedTokens, estimatedCost) => {
+ *         // Check budget
+ *       },
+ *       afterRequest: async (ctx, request, response, responseComplete, selected, usage, cost) => {
+ *         // Track usage
+ *       }
+ *     }
+ *   });
+ *
+ * // Use the API
+ * const response = await ai.chat.get([{ role: 'user', content: 'Hi' }]);
+ * ```
+ */
+export declare class AI<T extends AIBaseTypes> {
+    readonly config: AIConfigOf<T>;
+    readonly registry: ModelRegistry<AIProviders<T>>;
+    readonly chat: ChatAPI<T>;
+    readonly image: ImageAPI<T>;
+    readonly speech: SpeechAPI<T>;
+    readonly transcribe: TranscribeAPI<T>;
+    readonly embed: EmbedAPI<T>;
+    readonly models: ModelsAPI<AIProviders<T>>;
+    readonly providers: AIProviders<T>;
+    readonly components: ComponentFor<T>[];
+    hooks: AIHooks<T>;
+    private cumulativeCost;
+    private cumulativeLatency;
+    private cumulativeRequestCount;
+    readonly tokens: Record<MessageContentType, {
+        divisor: number;
+        base64Divisor: number;
+        fallback: number;
+        max?: number;
+    }>;
+    /**
+     * Static builder for creating AI instances with type inference
+     */
+    static with<TContext extends AIContextUser = {}, TMetadata extends AIMetadataUser = {}>(): {
+        providers: <TProviders extends Providers>(providers: TProviders) => {
+            create: <TConfig extends Omit<AIConfig<TContext, TMetadata, TProviders>, "providers">>(config: TConfig) => AI<AITypesInfer<TContext, TMetadata, TProviders, TConfig>>;
+        };
+    };
+    constructor(config: AIConfigOf<T>);
+    /**
+     * Sets the hooks for this AI instance and returns the instance.
+     *
+     * @param hooks - Hooks to set
+     * @returns this
+     */
+    withHooks(hooks: AIHooks<T>): this;
+    /**
+     * Build full context from required context
+     *
+     * Merges defaults → provided → required in that order
+     *
+     * @param requiredCtx - Required context provided by caller
+     * @returns Full AIContext with all fields populated
+     */
+    buildContext(requiredCtx: AIContextRequired<T>): Promise<AIContext<T>>;
+    /**
+     * Build core context with executor and streamer injected from ChatAPI
+     *
+     * This is used by Prompts to get stream/execute functions in the context.
+     *
+     * @param requiredCtx - Required context provided by caller
+     * @returns Full context with stream and execute functions
+     */
+    buildCoreContext(requiredCtx: AIContextRequired<T>): Promise<Context<T>>;
+    /**
+     * Build full metadata from required metadata
+     *
+     * Merges defaults → provided → required in that order
+     *
+     * @param requiredMetadata - Required metadata provided by caller
+     * @returns Full AIMetadata with all fields populated
+     */
+    buildMetadata(requiredMetadata: AIMetadataRequired<T>): Promise<AIMetadata<T>>;
+    /**
+     * Merges multiple metadata objects into one. Some properties may be
+     * merged in a special way depending on their type. The metadata objects
+     * are merged in the order they are provided, with later objects
+     * overriding earlier ones.
+     *
+     * @param metadatas
+     * @returns
+     */
+    mergeMetadata(...metadatas: Array<Partial<AIMetadata<T> | undefined>>): AIMetadata<T>;
+    /**
+     * Select a model based on metadata (used by API classes)
+     * @internal
+     */
+    selectModel(metadata: AIMetadata<T>): SelectedModelFor<T> | undefined;
+    /**
+     * Estimate usage for a message (used by API classes and Prompts)
+     *
+     * @param message - Message to estimate usage for
+     * @returns Usage statistics structured to match ModelPricing
+     */
+    estimateMessageUsage(message: Message): Usage;
+    /**
+     * Estimate usage for a request (used by API classes)
+     * @internal
+     */
+    estimateRequestUsage(request: Request): Usage;
+    /**
+     * Calculate cost for a request (used by API classes)
+     * Matches the structure of Usage to ModelPricing for accurate cost calculation.
+     * @internal
+     */
+    calculateCost(model: ModelInfo<AIProviderNames<T>>, usage: Usage): number;
+    /**
+     * Determines whether a given override matches a model.
+     *
+     * @param model - Model information
+     * @param override - Model override to check
+     * @returns
+     */
+    matchesOverride(model: ModelInfo, override: ModelOverride): boolean;
+    /**
+     * Run a component with AI instance context.
+     *
+     * @param component - Component to run
+     * @param input - Input for the component
+     * @param ctx - Optional context
+     */
+    run<C extends ComponentFor<T>>(component: C, input: ComponentInput<C>, ...[ctx]: AIContextOptional<T>): Promise<ComponentOutput<C>>;
+    /**
+     * Create an enhanced prompt bound to this AI instance.
+     *
+     * @template TName - Name of the prompt.
+     * @template TInput - Input type for the prompt.
+     * @template TOutput - Output type for the prompt.
+     * @template TTools - Tools used by the prompt.
+     * @param options - Prompt configuration options.
+     * @returns - An enhanced prompt instance.
+     */
+    prompt<TName extends string = string, TInput extends object = {}, TOutput extends object | string = string, TTools extends Tuple<ToolCompatible<AIContextRequired<T>, AIMetadataRequired<T>>> = []>(options: Omit<PromptInput<AIContext<T>, AIMetadata<T>, TName, TInput, TOutput, TTools>, 'types'>): Prompt<Partial<Omit<import("./types").AIBaseContext<T>, "ai">> & Omit<import("./types").Relax<T["Context"], T["DefaultContext"] & T["ProvidedContext"]>, keyof import("./types").AIBaseContext<AIBaseTypes>> extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never, AIBaseMetadata<AIProviders<T>> & Omit<import("./types").Relax<T["Metadata"], T["DefaultMetadata"] & T["ProvidedMetadata"]>, keyof import("./types").AIMetadataAny> extends infer T_2 ? { [K_1 in keyof T_2]: T_2[K_1]; } : never, TName, TInput, TOutput, TTools>;
+    /**
+     * Create an enhanced tool bound to this AI instance
+     */
+    tool<TName extends string = string, TParams extends object = {}, TOutput = unknown, TRefs extends Tuple<ComponentFor<T>> = []>(options: Omit<ToolInput<AIContext<T>, AIMetadata<T>, TName, TParams, TOutput, TRefs>, 'types'>): Tool<Partial<Omit<import("./types").AIBaseContext<T>, "ai">> & Omit<import("./types").Relax<T["Context"], T["DefaultContext"] & T["ProvidedContext"]>, keyof import("./types").AIBaseContext<AIBaseTypes>> extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never, AIBaseMetadata<AIProviders<T>> & Omit<import("./types").Relax<T["Metadata"], T["DefaultMetadata"] & T["ProvidedMetadata"]>, keyof import("./types").AIMetadataAny> extends infer T_2 ? { [K_1 in keyof T_2]: T_2[K_1]; } : never, TName, TParams, Promise<TOutput>, TRefs>;
+    /**
+     * Create an enhanced agent bound to this AI instance
+     */
+    agent<TName extends string = string, TInput extends object = {}, TOutput = unknown, TRefs extends Tuple<ComponentFor<T>> = []>(options: Omit<AgentInput<AIContext<T>, AIMetadata<T>, TName, TInput, TOutput, TRefs>, 'types'>): Agent<Partial<Omit<import("./types").AIBaseContext<T>, "ai">> & Omit<import("./types").Relax<T["Context"], T["DefaultContext"] & T["ProvidedContext"]>, keyof import("./types").AIBaseContext<AIBaseTypes>> extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never, AIBaseMetadata<AIProviders<T>> & Omit<import("./types").Relax<T["Metadata"], T["DefaultMetadata"] & T["ProvidedMetadata"]>, keyof import("./types").AIMetadataAny> extends infer T_2 ? { [K_1 in keyof T_2]: T_2[K_1]; } : never, TName, TInput, Promise<TOutput>, TRefs>;
+    /**
+     * Extend this AI instance with additional context type
+     *
+     * Creates a new AI instance that shares the base model registry but can have
+     * its own models, overrides, handlers, and extended context type.
+     *
+     * @example
+     * ```typescript
+     * const chatAI = ai.extend<{ chat: Chat, chatMessage: ChatMessage }>({
+     *   defaultContext: { chat, chatMessage },
+     *   modelOverrides: [...]
+     * });
+     * const chatAgent = chatAI.agent({...});
+     * ```
+     */
+    extend<TExtendedContext extends object = {}, TExtendedMetadata extends object = {}>(config?: Partial<AIConfig<Extend<T['Context'], TExtendedContext>, Extend<T['Metadata'], TExtendedMetadata>, AIProviders<T>>>): AI<AITypesInfer<Extend<T["Context"], TExtendedContext>, Extend<T["Metadata"], TExtendedMetadata>, AIProviders<T>, Partial<AIConfig<Extend<T["Context"], TExtendedContext>, Extend<T["Metadata"], TExtendedMetadata>, AIProviders<T>>>>>;
+    /**
+     * Track a request's cost and latency for statistics.
+     * Called internally by API classes after successful requests.
+     *
+     * @param cost - Cost of the request in dollars
+     * @param latency - Latency of the request in milliseconds
+     * @internal
+     */
+    trackRequest(cost: number, latency: number): void;
+    /**
+     * Get library statistics
+     */
+    stats(): LibraryStats;
+}
+//# 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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"}