@h-ai/ai 0.1.0-alpha5

package/dist/api/index.d.ts

@@ -0,0 +1,628 @@
+import { z } from 'zod';
+
+/**
+ * @h-ai/ai/api — AI API 端点契约定义
+ *
+ * 所有 ai 模块的 API 端点（path + method + schema），
+ * 客户端和服务端都从此处引用，编译时保证一致性。
+ *
+ * 注意：`chatStream` 使用 SSE 流式协议，客户端应使用
+ * `createAIClient().chatStream()` 而非 `api.call()`。
+ * 此处定义仅用于服务端路由注册和文档生成。
+ *
+ * @module ai-api-contract
+ */
+
+interface EndpointDef<TInput = unknown, TOutput = unknown> {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    path: string;
+    input: z.ZodType<TInput>;
+    output: z.ZodType<TOutput>;
+    requireAuth?: boolean;
+    meta?: {
+        summary?: string;
+        tags?: string[];
+        streaming?: boolean;
+    };
+}
+/**
+ * ai 所有 API 端点
+ *
+ * @example
+ * ```ts
+ * // 客户端（非流式）
+ * import { aiEndpoints } from '@h-ai/ai/api'
+ * const result = await api.call(aiEndpoints.chat, { messages: [...] })
+ *
+ * // 客户端（流式）— 使用专用 AIClient
+ * import { api } from '@h-ai/api-client'
+ * import { createAIClient } from '@h-ai/ai/client'
+ * await api.init({ baseUrl: '/api' })
+ * const client = createAIClient({ api })
+ * for await (const chunk of client.chatStream({ messages })) { ... }
+ *
+ * // 服务端
+ * export const POST = kit.fromContract(aiEndpoints.chat, async (input) => {
+ *   const result = await ai.llm.chat(input)
+ *   return result.success ? result.data : kit.response.internalError(result.error.message)
+ * })
+ * ```
+ */
+declare const aiEndpoints: {
+    /** 聊天完成（非流式） */
+    readonly chat: EndpointDef<{
+        messages: {
+            role: "system" | "user" | "assistant" | "tool";
+            content?: string | ({
+                type: "text";
+                text: string;
+            } | {
+                type: "image_url";
+                image_url: {
+                    url: string;
+                    detail?: "auto" | "low" | "high" | undefined;
+                };
+            })[] | undefined;
+            name?: string | undefined;
+            tool_calls?: {
+                id: string;
+                type: "function";
+                function: {
+                    name: string;
+                    arguments: string;
+                };
+            }[] | undefined;
+            tool_call_id?: string | undefined;
+        }[];
+        model?: string | undefined;
+        temperature?: number | undefined;
+        top_p?: number | undefined;
+        max_tokens?: number | undefined;
+        stream?: boolean | undefined;
+        tools?: {
+            type: "function";
+            function: {
+                name: string;
+                description?: string | undefined;
+                parameters?: {
+                    type: "object";
+                    properties?: Record<string, {
+                        type: string;
+                        description?: string | undefined;
+                        enum?: string[] | undefined;
+                    }> | undefined;
+                    required?: string[] | undefined;
+                } | undefined;
+            };
+        }[] | undefined;
+        tool_choice?: "auto" | "none" | {
+            type: "function";
+            function: {
+                name: string;
+            };
+        } | undefined;
+    }, {
+        id: string;
+        object: "chat.completion";
+        created: number;
+        model: string;
+        choices: {
+            index: number;
+            message: {
+                role: "assistant";
+                content?: string | null | undefined;
+                tool_calls?: {
+                    id: string;
+                    type: "function";
+                    function: {
+                        name: string;
+                        arguments: string;
+                    };
+                }[] | undefined;
+            };
+            finish_reason: "tool_calls" | "stop" | "length" | "content_filter";
+        }[];
+        usage: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+        };
+    }>;
+    /**
+     * 聊天完成（流式 SSE）
+     *
+     * 此端点使用 Server-Sent Events 协议返回流式 chunk。
+     * 客户端应使用 `createAIClient().chatStream()` 而非 `api.call()`。
+     * 定义此契约用于服务端路由注册和 API 文档。
+     */
+    readonly chatStream: EndpointDef<{
+        messages: {
+            role: "system" | "user" | "assistant" | "tool";
+            content?: string | ({
+                type: "text";
+                text: string;
+            } | {
+                type: "image_url";
+                image_url: {
+                    url: string;
+                    detail?: "auto" | "low" | "high" | undefined;
+                };
+            })[] | undefined;
+            name?: string | undefined;
+            tool_calls?: {
+                id: string;
+                type: "function";
+                function: {
+                    name: string;
+                    arguments: string;
+                };
+            }[] | undefined;
+            tool_call_id?: string | undefined;
+        }[];
+        model?: string | undefined;
+        temperature?: number | undefined;
+        top_p?: number | undefined;
+        max_tokens?: number | undefined;
+        stream?: boolean | undefined;
+        tools?: {
+            type: "function";
+            function: {
+                name: string;
+                description?: string | undefined;
+                parameters?: {
+                    type: "object";
+                    properties?: Record<string, {
+                        type: string;
+                        description?: string | undefined;
+                        enum?: string[] | undefined;
+                    }> | undefined;
+                    required?: string[] | undefined;
+                } | undefined;
+            };
+        }[] | undefined;
+        tool_choice?: "auto" | "none" | {
+            type: "function";
+            function: {
+                name: string;
+            };
+        } | undefined;
+    }, unknown>;
+    /** 简单消息（便捷接口，封装单轮对话） */
+    readonly sendMessage: EndpointDef<{
+        message: string;
+        systemPrompt?: string | undefined;
+        model?: string | undefined;
+        temperature?: number | undefined;
+    }, {
+        content: string;
+        model: string;
+        usage?: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+        } | undefined;
+    }>;
+    /** 记忆检索 */
+    readonly memoryRecall: EndpointDef<{
+        query: string;
+        topK?: number | undefined;
+        types?: ("custom" | "fact" | "preference" | "event" | "summary")[] | undefined;
+        minImportance?: number | undefined;
+        objectId?: string | undefined;
+    }, {
+        items: {
+            id: string;
+            content: string;
+            type: "custom" | "fact" | "preference" | "event" | "summary";
+            importance: number;
+            createdAt: number;
+            lastAccessedAt: number;
+            accessCount: number;
+            objectId?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }[];
+    }>;
+    /** 记忆列表（分页） */
+    readonly memoryList: EndpointDef<{
+        types?: ("custom" | "fact" | "preference" | "event" | "summary")[] | undefined;
+        objectId?: string | undefined;
+        offset?: number | undefined;
+        limit?: number | undefined;
+    }, {
+        items: {
+            id: string;
+            content: string;
+            type: "custom" | "fact" | "preference" | "event" | "summary";
+            importance: number;
+            createdAt: number;
+            lastAccessedAt: number;
+            accessCount: number;
+            objectId?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+        }[];
+        total: number;
+    }>;
+    /** 会话列表 */
+    readonly sessionList: EndpointDef<{
+        objectId: string;
+    }, {
+        items: {
+            objectId: string;
+            sessionId: string;
+            createdAt: number;
+            updatedAt: number;
+            metadata?: Record<string, unknown> | undefined;
+        }[];
+    }>;
+    /** 对话历史 */
+    readonly chatHistory: EndpointDef<{
+        objectId: string;
+        sessionId: string;
+        limit?: number | undefined;
+        order?: "asc" | "desc" | undefined;
+    }, {
+        items: {
+            id: string;
+            objectId: string;
+            sessionId: string;
+            request: {
+                model: string;
+                messages: {
+                    role: "system" | "user" | "assistant" | "tool";
+                    content?: string | ({
+                        type: "text";
+                        text: string;
+                    } | {
+                        type: "image_url";
+                        image_url: {
+                            url: string;
+                            detail?: "auto" | "low" | "high" | undefined;
+                        };
+                    })[] | undefined;
+                    name?: string | undefined;
+                    tool_calls?: {
+                        id: string;
+                        type: "function";
+                        function: {
+                            name: string;
+                            arguments: string;
+                        };
+                    }[] | undefined;
+                    tool_call_id?: string | undefined;
+                }[];
+            };
+            response: {
+                content: string;
+                finishReason: string;
+                usage: {
+                    prompt_tokens: number;
+                    completion_tokens: number;
+                    total_tokens: number;
+                };
+                toolCalls?: {
+                    id: string;
+                    type: "function";
+                    function: {
+                        name: string;
+                        arguments: string;
+                    };
+                }[] | undefined;
+            };
+            createdAt: number;
+            duration: number;
+        }[];
+    }>;
+};
+
+/**
+ * @h-ai/ai/api — AI API 契约 Schema
+ *
+ * 入参/出参 Schema，客户端和服务端共享的唯一真相源。
+ * @module ai-api-schemas
+ */
+
+/** 聊天消息 */
+declare const ChatMessageSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        system: "system";
+        user: "user";
+        assistant: "assistant";
+        tool: "tool";
+    }>;
+    content: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"image_url">;
+        image_url: z.ZodObject<{
+            url: z.ZodString;
+            detail: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                low: "low";
+                high: "high";
+            }>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>]>>]>>;
+    name: z.ZodOptional<z.ZodString>;
+    tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    tool_call_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** 聊天完成请求入参 */
+declare const ChatCompletionInputSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    messages: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            system: "system";
+            user: "user";
+            assistant: "assistant";
+            tool: "tool";
+        }>;
+        content: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"image_url">;
+            image_url: z.ZodObject<{
+                url: z.ZodString;
+                detail: z.ZodOptional<z.ZodEnum<{
+                    auto: "auto";
+                    low: "low";
+                    high: "high";
+                }>>;
+            }, z.core.$strip>;
+        }, z.core.$strip>]>>]>>;
+        name: z.ZodOptional<z.ZodString>;
+        tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodLiteral<"function">;
+            function: z.ZodObject<{
+                name: z.ZodString;
+                arguments: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>>>;
+        tool_call_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    top_p: z.ZodOptional<z.ZodNumber>;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    stream: z.ZodOptional<z.ZodBoolean>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            parameters: z.ZodOptional<z.ZodObject<{
+                type: z.ZodLiteral<"object">;
+                properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    type: z.ZodString;
+                    description: z.ZodOptional<z.ZodString>;
+                    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                }, z.core.$strip>>>;
+                required: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    tool_choice: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodLiteral<"none">, z.ZodObject<{
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>;
+/** 聊天完成响应出参 */
+declare const ChatCompletionOutputSchema: z.ZodObject<{
+    id: z.ZodString;
+    object: z.ZodLiteral<"chat.completion">;
+    created: z.ZodNumber;
+    model: z.ZodString;
+    choices: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        message: z.ZodObject<{
+            role: z.ZodLiteral<"assistant">;
+            content: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                type: z.ZodLiteral<"function">;
+                function: z.ZodObject<{
+                    name: z.ZodString;
+                    arguments: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>;
+        finish_reason: z.ZodEnum<{
+            tool_calls: "tool_calls";
+            stop: "stop";
+            length: "length";
+            content_filter: "content_filter";
+        }>;
+    }, z.core.$strip>>;
+    usage: z.ZodObject<{
+        prompt_tokens: z.ZodNumber;
+        completion_tokens: z.ZodNumber;
+        total_tokens: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** 简单消息请求入参（便捷接口） */
+declare const SendMessageInputSchema: z.ZodObject<{
+    message: z.ZodString;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** 简单消息响应出参 */
+declare const SendMessageOutputSchema: z.ZodObject<{
+    content: z.ZodString;
+    model: z.ZodString;
+    usage: z.ZodOptional<z.ZodObject<{
+        prompt_tokens: z.ZodNumber;
+        completion_tokens: z.ZodNumber;
+        total_tokens: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** 记忆检索请求入参 */
+declare const MemoryRecallInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    topK: z.ZodOptional<z.ZodNumber>;
+    types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        custom: "custom";
+        fact: "fact";
+        preference: "preference";
+        event: "event";
+        summary: "summary";
+    }>>>;
+    minImportance: z.ZodOptional<z.ZodNumber>;
+    objectId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** 记忆检索响应出参 */
+declare const MemoryRecallOutputSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        content: z.ZodString;
+        type: z.ZodEnum<{
+            custom: "custom";
+            fact: "fact";
+            preference: "preference";
+            event: "event";
+            summary: "summary";
+        }>;
+        importance: z.ZodNumber;
+        objectId: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        createdAt: z.ZodNumber;
+        lastAccessedAt: z.ZodNumber;
+        accessCount: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** 记忆列表请求入参 */
+declare const MemoryListInputSchema: z.ZodObject<{
+    types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        custom: "custom";
+        fact: "fact";
+        preference: "preference";
+        event: "event";
+        summary: "summary";
+    }>>>;
+    objectId: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** 记忆列表响应出参 */
+declare const MemoryListOutputSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        content: z.ZodString;
+        type: z.ZodEnum<{
+            custom: "custom";
+            fact: "fact";
+            preference: "preference";
+            event: "event";
+            summary: "summary";
+        }>;
+        importance: z.ZodNumber;
+        objectId: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        createdAt: z.ZodNumber;
+        lastAccessedAt: z.ZodNumber;
+        accessCount: z.ZodNumber;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+}, z.core.$strip>;
+/** 会话列表请求入参 */
+declare const SessionListInputSchema: z.ZodObject<{
+    objectId: z.ZodString;
+}, z.core.$strip>;
+/** 会话列表响应出参 */
+declare const SessionListOutputSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        objectId: z.ZodString;
+        sessionId: z.ZodString;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** 对话历史请求入参 */
+declare const ChatHistoryInputSchema: z.ZodObject<{
+    objectId: z.ZodString;
+    sessionId: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+    order: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+}, z.core.$strip>;
+/** 对话历史响应出参 */
+declare const ChatHistoryOutputSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        objectId: z.ZodString;
+        sessionId: z.ZodString;
+        request: z.ZodObject<{
+            model: z.ZodString;
+            messages: z.ZodArray<z.ZodObject<{
+                role: z.ZodEnum<{
+                    system: "system";
+                    user: "user";
+                    assistant: "assistant";
+                    tool: "tool";
+                }>;
+                content: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                    type: z.ZodLiteral<"text">;
+                    text: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    type: z.ZodLiteral<"image_url">;
+                    image_url: z.ZodObject<{
+                        url: z.ZodString;
+                        detail: z.ZodOptional<z.ZodEnum<{
+                            auto: "auto";
+                            low: "low";
+                            high: "high";
+                        }>>;
+                    }, z.core.$strip>;
+                }, z.core.$strip>]>>]>>;
+                name: z.ZodOptional<z.ZodString>;
+                tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    type: z.ZodLiteral<"function">;
+                    function: z.ZodObject<{
+                        name: z.ZodString;
+                        arguments: z.ZodString;
+                    }, z.core.$strip>;
+                }, z.core.$strip>>>;
+                tool_call_id: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        response: z.ZodObject<{
+            content: z.ZodString;
+            toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                type: z.ZodLiteral<"function">;
+                function: z.ZodObject<{
+                    name: z.ZodString;
+                    arguments: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>>>;
+            finishReason: z.ZodString;
+            usage: z.ZodObject<{
+                prompt_tokens: z.ZodNumber;
+                completion_tokens: z.ZodNumber;
+                total_tokens: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+        createdAt: z.ZodNumber;
+        duration: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ChatCompletionInput = z.infer<typeof ChatCompletionInputSchema>;
+type ChatCompletionOutput = z.infer<typeof ChatCompletionOutputSchema>;
+type SendMessageInput = z.infer<typeof SendMessageInputSchema>;
+type SendMessageOutput = z.infer<typeof SendMessageOutputSchema>;
+
+export { type ChatCompletionInput, ChatCompletionInputSchema, type ChatCompletionOutput, ChatCompletionOutputSchema, ChatHistoryInputSchema, ChatHistoryOutputSchema, ChatMessageSchema, MemoryListInputSchema, MemoryListOutputSchema, MemoryRecallInputSchema, MemoryRecallOutputSchema, type SendMessageInput, SendMessageInputSchema, type SendMessageOutput, SendMessageOutputSchema, SessionListInputSchema, SessionListOutputSchema, aiEndpoints };