@ubean/ai 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soybean
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/core-B-pZdSgG.js

@@ -0,0 +1,239 @@
+import { safeParse } from "valibot";
+import { toJsonSchema } from "@valibot/to-json-schema";
+//#region src/core.ts
+const registeredProviders = /* @__PURE__ */ new Map();
+let defaultProviderId;
+/** Register a provider (idempotent by id). */
+function defineProvider(definition) {
+	if (definition.id && !definition.id.includes("/")) registeredProviders.set(definition.id, definition);
+}
+/** Configure the fallback provider used when a model string has no provider segment. */
+function configureAI(options) {
+	if (options.defaultProvider) defaultProviderId = options.defaultProvider;
+}
+/**
+* Resolve a `provider/model` string to `{ provider, modelId }`.
+* Falls back to the configured default provider, then to an env-driven
+* OpenAI-compatible provider (mirrors devtools' DeepSeek defaults).
+*/
+function resolveModel(model) {
+	const slash = model.indexOf("/");
+	const providerId = slash === -1 ? void 0 : model.slice(0, slash);
+	const modelId = slash === -1 ? model : model.slice(slash + 1);
+	let provider = providerId ? registeredProviders.get(providerId) : void 0;
+	if (!provider && defaultProviderId) provider = registeredProviders.get(defaultProviderId);
+	if (!provider) provider = envProvider();
+	if (!provider) throw new Error(`[@ubean/ai] No provider resolved for "${model}". Define a provider via defineProvider() or configure a default with configureAI().`);
+	return {
+		provider,
+		modelId
+	};
+}
+function envProvider() {
+	const apiKey = process.env.DEEPSEEK_API_KEY || process.env.UBEAN_AI_API_KEY || process.env.OPENAI_API_KEY;
+	const baseURL = process.env.UBEAN_AI_API_BASE || "https://api.deepseek.com/v1";
+	if (!apiKey) return void 0;
+	return {
+		id: "env",
+		kind: "openai-compatible",
+		baseURL,
+		apiKey
+	};
+}
+/** Declare a typed ubean tool. Returns the tool unchanged (type-safe identity). */
+function defineAgentTool(tool) {
+	return tool;
+}
+async function loadAiSdk() {
+	try {
+		const [aiMod, compatMod] = await Promise.all([import("ai"), import("@ai-sdk/openai-compatible")]);
+		return {
+			ai: aiMod,
+			createOpenAICompatible: compatMod.createOpenAICompatible
+		};
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(`[@ubean/ai] The AI SDK packages are not installed. Install them with: pnpm add ai @ai-sdk/openai-compatible (or npm/yarn/bun equivalent). Original error: ${msg}`, { cause: err });
+	}
+}
+function buildSystemPrompt(config) {
+	let system = config.system ?? "";
+	if (config.context && Object.keys(config.context).length > 0) {
+		const ctx = JSON.stringify(config.context, null, 2);
+		system += `\n\n<context>\n${ctx}\n</context>`;
+	}
+	return system;
+}
+/**
+* Build a declarative agent. The loop is delegated to the AI SDK's
+* `streamText`/`generateText` (with `stopWhen: stepCountIs(maxSteps)`); this
+* only returns the ubean-idiomatic surface (`run`/`stream`/`asHandler`).
+*/
+function defineAgent(config) {
+	const system = buildSystemPrompt(config);
+	async function createModel() {
+		const { ai, createOpenAICompatible } = await loadAiSdk();
+		const { provider, modelId } = resolveModel(config.model);
+		return {
+			ai,
+			model: createOpenAICompatible({
+				baseURL: provider.baseURL,
+				name: provider.id,
+				apiKey: provider.apiKey,
+				headers: provider.headers
+			}).chatModel(modelId),
+			provider
+		};
+	}
+	async function buildTools(input) {
+		const { ai } = await loadAiSdk();
+		const tools = {};
+		for (const [name, tool] of Object.entries(config.tools ?? {})) {
+			const toolName = tool.name || name;
+			const inputSchema = ai.jsonSchema(toJsonSchema(tool.input), { validate: (value) => {
+				const result = safeParse(tool.input, value);
+				if (result.success) return {
+					success: true,
+					value: result.output
+				};
+				return {
+					success: false,
+					error: new Error(result.issues.map((i) => i.message).join("; "))
+				};
+			} });
+			tools[toolName] = ai.tool({
+				description: tool.description,
+				inputSchema,
+				execute: async (args, ctx) => {
+					const toolCtx = {
+						runId: input.meta?.runId ?? "run",
+						meta: input.meta,
+						signal: ctx.abortSignal
+					};
+					try {
+						return await tool.execute(args, toolCtx);
+					} catch (err) {
+						throw err instanceof Error ? err : new Error(String(err));
+					}
+				}
+			});
+		}
+		return tools;
+	}
+	function toCoreMessages(input) {
+		if (input.messages) return input.messages;
+		return input.prompt ? [{
+			role: "user",
+			content: input.prompt
+		}] : [];
+	}
+	async function run(input) {
+		const { ai, model } = await createModel();
+		const tools = await buildTools(input);
+		const messages = toCoreMessages(input);
+		const result = await ai.generateText({
+			model,
+			system,
+			messages,
+			tools,
+			stopWhen: ai.stepCountIs(config.maxSteps ?? 5),
+			maxOutputTokens: config.maxTokens,
+			temperature: config.temperature,
+			headers: config.headers
+		});
+		const toolResults = (result.toolResults ?? []).map((tr) => ({
+			toolName: tr.toolName,
+			toolCallId: tr.toolCallId,
+			result: tr.output
+		}));
+		return {
+			text: result.text,
+			output: result.output,
+			toolResults,
+			usage: result.usage ? {
+				inputTokens: result.usage.inputTokens ?? 0,
+				outputTokens: result.usage.outputTokens ?? 0,
+				totalTokens: (result.usage.inputTokens ?? 0) + (result.usage.outputTokens ?? 0)
+			} : void 0
+		};
+	}
+	async function* stream(input) {
+		const { ai, model } = await createModel();
+		const tools = await buildTools(input);
+		const messages = toCoreMessages(input);
+		const result = ai.streamText({
+			model,
+			system,
+			messages,
+			tools,
+			stopWhen: ai.stepCountIs(config.maxSteps ?? 5),
+			maxOutputTokens: config.maxTokens,
+			temperature: config.temperature,
+			headers: config.headers
+		});
+		for await (const part of result.fullStream) switch (part.type) {
+			case "text-delta":
+				yield {
+					type: "text-delta",
+					text: part.text
+				};
+				break;
+			case "tool-call":
+				yield {
+					type: "tool-call",
+					toolCallId: part.toolCallId,
+					toolName: part.toolName,
+					input: part.input
+				};
+				break;
+			case "tool-result":
+				yield {
+					type: "tool-result",
+					toolCallId: part.toolCallId,
+					toolName: part.toolName,
+					result: part.output
+				};
+				break;
+			case "error":
+				yield {
+					type: "error",
+					error: part.error instanceof Error ? part.error.message : String(part.error)
+				};
+				return;
+			case "finish": {
+				const finish = part;
+				yield {
+					type: "done",
+					usage: finish.usage ? {
+						inputTokens: finish.usage.inputTokens ?? 0,
+						outputTokens: finish.usage.outputTokens ?? 0,
+						totalTokens: (finish.usage.inputTokens ?? 0) + (finish.usage.outputTokens ?? 0)
+					} : void 0
+				};
+				return;
+			}
+		}
+	}
+	/**
+	* Convert this agent into a Hono handler. Reads the request body as
+	* `AgentInput` and streams the result as SSE (`data: <json>\n\n`), directly
+	* compatible with `useChat`'s SSE parser.
+	*/
+	function asHandler() {
+		return async (c) => {
+			const input = await c.req.json().catch(() => ({}));
+			const { streamSSE } = await import("hono/streaming");
+			return streamSSE(c, async (sse) => {
+				for await (const chunk of stream(input)) await sse.writeSSE({ data: JSON.stringify(chunk) });
+			});
+		};
+	}
+	return {
+		config,
+		run,
+		stream,
+		asHandler
+	};
+}
+//#endregion
+export { resolveModel as a, defineProvider as i, defineAgent as n, defineAgentTool as r, configureAI as t };

package/dist/gateway.d.ts

@@ -0,0 +1,52 @@
+import { m as ProviderDefinition } from "./types-B5I0sGbf.js";
+//#region src/gateway.d.ts
+/**
+ * DeepSeek (https://www.deepseek.com/).
+ * Default base URL is `https://api.deepseek.com/v1`.
+ * Requires `DEEPSEEK_API_KEY` (or `UBEAN_AI_API_KEY`) env variable or manual `apiKey`.
+ */
+declare const deepseek: ProviderDefinition;
+/**
+ * OpenRouter (https://openrouter.ai/).
+ * Base URL `https://openrouter.ai/api/v1`.
+ * Requires `OPENROUTER_API_KEY`.
+ */
+declare const openrouter: ProviderDefinition;
+/**
+ * OmniRoute (https://github.com/diegosouzapw/OmniRoute) — the Free AI Gateway.
+ * This assumes you are running OmniRoute locally or have deployed it.
+ * Default base URL is the default local endpoint `http://localhost:8080/v1`.
+ * If you are running OmniRoute elsewhere, override `baseURL` when registering.
+ */
+declare const omniRoute: ProviderDefinition;
+/**
+ * OpenAI (https://platform.openai.com/).
+ * Base URL `https://api.openai.com/v1`.
+ * Requires `OPENAI_API_KEY`.
+ *
+ * Note: you can also use this provider via `@ai-sdk/openai` directly; this
+ * definition is for when you are routing OpenAI through a proxy/gateway.
+ */
+declare const openai: ProviderDefinition;
+/**
+ * Anthropic via OpenAI-compatible endpoint.
+ * Anthropic's native endpoint is not OpenAI-compatible out of the box, but
+ * many gateways (including OmniRoute) expose it as such.
+ */
+declare const anthropic: ProviderDefinition;
+/**
+ * Google Gemini via OpenAI-compatible endpoint.
+ * Gemini's native endpoint is not OpenAI-compatible out of the box; this
+ * definition is for when you are using a gateway that exposes it as such.
+ */
+declare const google: ProviderDefinition;
+/**
+ * Groq (https://groq.com/).
+ * OpenAI-compatible endpoint out of the box.
+ * Requires `GROQ_API_KEY`.
+ */
+declare const groq: ProviderDefinition;
+/** All built-in gateway providers exported from this module. */
+declare const allGatewayProviders: ProviderDefinition[];
+//#endregion
+export { type ProviderDefinition, allGatewayProviders, anthropic, deepseek, google, groq, omniRoute, openai, openrouter };

package/dist/gateway.js

@@ -0,0 +1,87 @@
+//#region src/gateway.ts
+/**
+* DeepSeek (https://www.deepseek.com/).
+* Default base URL is `https://api.deepseek.com/v1`.
+* Requires `DEEPSEEK_API_KEY` (or `UBEAN_AI_API_KEY`) env variable or manual `apiKey`.
+*/
+const deepseek = {
+	id: "deepseek",
+	kind: "openai-compatible",
+	baseURL: "https://api.deepseek.com/v1"
+};
+/**
+* OpenRouter (https://openrouter.ai/).
+* Base URL `https://openrouter.ai/api/v1`.
+* Requires `OPENROUTER_API_KEY`.
+*/
+const openrouter = {
+	id: "openrouter",
+	kind: "openai-compatible",
+	baseURL: "https://openrouter.ai/api/v1"
+};
+/**
+* OmniRoute (https://github.com/diegosouzapw/OmniRoute) — the Free AI Gateway.
+* This assumes you are running OmniRoute locally or have deployed it.
+* Default base URL is the default local endpoint `http://localhost:8080/v1`.
+* If you are running OmniRoute elsewhere, override `baseURL` when registering.
+*/
+const omniRoute = {
+	id: "omniroute",
+	kind: "openai-compatible",
+	baseURL: "http://localhost:8080/v1"
+};
+/**
+* OpenAI (https://platform.openai.com/).
+* Base URL `https://api.openai.com/v1`.
+* Requires `OPENAI_API_KEY`.
+*
+* Note: you can also use this provider via `@ai-sdk/openai` directly; this
+* definition is for when you are routing OpenAI through a proxy/gateway.
+*/
+const openai = {
+	id: "openai",
+	kind: "openai-compatible",
+	baseURL: "https://api.openai.com/v1"
+};
+/**
+* Anthropic via OpenAI-compatible endpoint.
+* Anthropic's native endpoint is not OpenAI-compatible out of the box, but
+* many gateways (including OmniRoute) expose it as such.
+*/
+const anthropic = {
+	id: "anthropic",
+	kind: "openai-compatible",
+	baseURL: "https://api.anthropic.com/v1"
+};
+/**
+* Google Gemini via OpenAI-compatible endpoint.
+* Gemini's native endpoint is not OpenAI-compatible out of the box; this
+* definition is for when you are using a gateway that exposes it as such.
+*/
+const google = {
+	id: "google",
+	kind: "openai-compatible",
+	baseURL: "https://generativelanguage.googleapis.com/v1beta/openai"
+};
+/**
+* Groq (https://groq.com/).
+* OpenAI-compatible endpoint out of the box.
+* Requires `GROQ_API_KEY`.
+*/
+const groq = {
+	id: "groq",
+	kind: "openai-compatible",
+	baseURL: "https://api.groq.com/openai/v1"
+};
+/** All built-in gateway providers exported from this module. */
+const allGatewayProviders = [
+	deepseek,
+	openrouter,
+	omniRoute,
+	openai,
+	anthropic,
+	google,
+	groq
+];
+//#endregion
+export { allGatewayProviders, anthropic, deepseek, google, groq, omniRoute, openai, openrouter };

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { _ as UbeanAIProviderOptions, a as AgentStreamChunk, c as AgentToolContext, d as AgentUsage, f as AgentUserMessage, g as ResolvedModel, h as ProviderKind, i as AgentRunResult, l as AgentToolResult, m as ProviderDefinition, n as AgentConfig, o as AgentTool, p as ModelString, r as AgentInput, s as AgentToolCall, t as AgentAssistantMessage, u as AgentToolSet, v as UbeanAgent } from "./types-B5I0sGbf.js";
+import * as v from "valibot";
+//#region src/core.d.ts
+/** Register a provider (idempotent by id). */
+declare function defineProvider(definition: ProviderDefinition): void;
+/** Configure the fallback provider used when a model string has no provider segment. */
+declare function configureAI(options: {
+  defaultProvider?: string;
+}): void;
+/**
+ * Resolve a `provider/model` string to `{ provider, modelId }`.
+ * Falls back to the configured default provider, then to an env-driven
+ * OpenAI-compatible provider (mirrors devtools' DeepSeek defaults).
+ */
+declare function resolveModel(model: string): ResolvedModel;
+/** Declare a typed ubean tool. Returns the tool unchanged (type-safe identity). */
+declare function defineAgentTool<T extends AgentTool['input']>(tool: AgentTool<T>): AgentTool<T>;
+/**
+ * Build a declarative agent. The loop is delegated to the AI SDK's
+ * `streamText`/`generateText` (with `stopWhen: stepCountIs(maxSteps)`); this
+ * only returns the ubean-idiomatic surface (`run`/`stream`/`asHandler`).
+ */
+declare function defineAgent<T = unknown>(config: AgentConfig): UbeanAgent<T>;
+//#endregion
+export { type AgentAssistantMessage, type AgentConfig, type AgentInput, type AgentRunResult, type AgentStreamChunk, type AgentTool, type AgentToolCall, type AgentToolContext, type AgentToolResult, type AgentToolSet, type AgentUsage, type AgentUserMessage, type ModelString, type ProviderDefinition, type ProviderKind, type ResolvedModel, type UbeanAIProviderOptions, type UbeanAgent, configureAI, defineAgent, defineAgentTool, defineProvider, resolveModel, v };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { a as resolveModel, i as defineProvider, n as defineAgent, r as defineAgentTool, t as configureAI } from "./core-B-pZdSgG.js";
+import * as v from "valibot";
+export { configureAI, defineAgent, defineAgentTool, defineProvider, resolveModel, v };

package/dist/runtime/vue.d.ts

@@ -0,0 +1,74 @@
+import { a as AgentStreamChunk, i as AgentRunResult, l as AgentToolResult, r as AgentInput, s as AgentToolCall, v as UbeanAgent } from "../types-B5I0sGbf.js";
+import { ComputedRef, Ref } from "vue";
+//#region src/runtime/vue.d.ts
+/** A single chat message managed by `useChat`. */
+interface ChatMessage {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  /** Tool calls emitted during this assistant turn. */
+  toolCalls?: AgentToolCall[];
+  /** Tool results collected during this assistant turn. */
+  toolResults?: AgentToolResult[];
+  createdAt?: number;
+}
+type ChatStatus = 'ready' | 'streaming' | 'error';
+interface UseChatOptions {
+  /** SSE endpoint. Defaults to a relative `./chat` route if not provided. */
+  url?: string;
+  /** Initial conversation history. */
+  initialMessages?: ChatMessage[];
+  /** Extra fields merged into the request body (e.g. `meta`). */
+  body?: Record<string, unknown>;
+  /** Custom fetch implementation (for wire mocking / tests). */
+  fetch?: typeof fetch;
+}
+/** Set the provider config used by `useAIProvider` (called by the Vite plugin). */
+declare function setAIProviderConfig(config: {
+  defaultProvider?: string;
+  defaultModel?: string;
+}): void;
+interface UseChatReturn {
+  /** Reactive message list. */
+  messages: Ref<ChatMessage[]>;
+  /** 'ready' | 'streaming' | 'error'. */
+  status: Ref<ChatStatus>;
+  /** Last error, if any. */
+  error: Ref<Error | null>;
+  /** Text input bound to the chat box. */
+  input: Ref<string>;
+  /** Raw stream chunks of the latest turn. */
+  data: Ref<AgentStreamChunk[]>;
+  /** Set the input text programmatically. */
+  setInput: (value: string) => void;
+  /** Send a message (uses `input` if `content` omitted). */
+  sendMessage: (content?: string) => Promise<void>;
+  /** Abort the in-flight stream. */
+  abort: () => void;
+  /** Re-send the last user message. */
+  reload: () => Promise<void>;
+  /** Whether the chat is currently streaming. */
+  isStreaming: ComputedRef<boolean>;
+}
+/**
+ * SSR-safe chat composable. Maintains reactive message state and streams
+ * `AgentStreamChunk` SSE frames from the `asHandler()` endpoint.
+ */
+declare function useChat(options?: UseChatOptions): UseChatReturn;
+interface UseAgentReturn<T = unknown> {
+  isStreaming: Ref<boolean>;
+  error: Ref<Error | null>;
+  result: Ref<AgentRunResult<T> | null>;
+  chunks: Ref<AgentStreamChunk[]>;
+  run: (input: AgentInput) => Promise<void>;
+  stream: (input: AgentInput) => Promise<void>;
+}
+/** Drive a `UbeanAgent` directly from a component with reactive state. */
+declare function useAgent<T = unknown>(agent: UbeanAgent<T>): UseAgentReturn<T>;
+/** Read the current fallback provider/model config (set by the Vite plugin). */
+declare function useAIProvider(): {
+  defaultProvider?: string;
+  defaultModel?: string;
+};
+//#endregion
+export { type AgentInput, type AgentRunResult, type AgentStreamChunk, type AgentToolCall, type AgentToolResult, ChatMessage, ChatStatus, type UbeanAgent, UseAgentReturn, UseChatOptions, UseChatReturn, setAIProviderConfig, useAIProvider, useAgent, useChat };

package/dist/runtime/vue.js

@@ -0,0 +1,213 @@
+import { computed, ref, shallowRef } from "vue";
+//#region src/runtime/vue.ts
+/**
+* `@ubean/ai/runtime/vue` — Vue runtime composables.
+*
+* Self-built, SSR-safe thin layer over the `@ubean/ai` kernel. It does NOT
+* depend on `@ai-sdk/vue`; it talks directly to the SSE protocol emitted by
+* `UbeanAgent.asHandler()` (chunks of `AgentStreamChunk`).
+*
+* Rendering is intentionally out of scope (decision C): this module only
+* produces message state; users pick their own markdown/code renderer.
+*/
+/** Parse a raw SSE byte stream into a JSON `AgentStreamChunk` generator. */
+async function* parseSseStream(stream, onChunk) {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		buffer += decoder.decode(value, { stream: true });
+		let sepIndex;
+		while ((sepIndex = buffer.indexOf("\n\n")) !== -1) {
+			const rawEvent = buffer.slice(0, sepIndex);
+			buffer = buffer.slice(sepIndex + 2);
+			const event = parseSseEvent(rawEvent);
+			if (!event.data) continue;
+			let chunk;
+			try {
+				chunk = JSON.parse(event.data);
+			} catch {
+				continue;
+			}
+			onChunk(chunk);
+			yield chunk;
+		}
+	}
+}
+function parseSseEvent(raw) {
+	let data = "";
+	for (const line of raw.split(/\r?\n/)) if (line.startsWith("data:")) data += line.slice(5).trimStart();
+	return { data };
+}
+function nextId() {
+	return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+let providerConfig = {};
+/** Set the provider config used by `useAIProvider` (called by the Vite plugin). */
+function setAIProviderConfig(config) {
+	providerConfig = config;
+}
+/**
+* SSR-safe chat composable. Maintains reactive message state and streams
+* `AgentStreamChunk` SSE frames from the `asHandler()` endpoint.
+*/
+function useChat(options = {}) {
+	const messages = ref(options.initialMessages ?? []);
+	const status = ref("ready");
+	const error = ref(null);
+	const input = ref("");
+	const data = ref([]);
+	let controller = null;
+	let lastUserPrompt = null;
+	const isStreaming = computed(() => status.value === "streaming");
+	const url = options.url ?? "./chat";
+	const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
+	function setInput(value) {
+		input.value = value;
+	}
+	function abort() {
+		controller?.abort();
+	}
+	async function sendMessage(content) {
+		const text = content ?? input.value;
+		if (!text || status.value === "streaming") return;
+		const userMsg = {
+			id: nextId(),
+			role: "user",
+			content: text,
+			createdAt: Date.now()
+		};
+		messages.value = [...messages.value, userMsg];
+		input.value = "";
+		data.value = [];
+		lastUserPrompt = text;
+		const body = {
+			...options.body,
+			messages: messages.value.map(({ role, content: c }) => ({
+				role,
+				content: c
+			}))
+		};
+		if (!fetchImpl) {
+			status.value = "error";
+			error.value = /* @__PURE__ */ new Error("fetch is not available (SSR?) — useChat should only run on the client");
+			return;
+		}
+		controller = new AbortController();
+		status.value = "streaming";
+		error.value = null;
+		let assistantId = nextId();
+		const assistantMsg = {
+			id: assistantId,
+			role: "assistant",
+			content: "",
+			createdAt: Date.now()
+		};
+		messages.value = [...messages.value, assistantMsg];
+		try {
+			const res = await fetchImpl(url, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(body),
+				signal: controller.signal
+			});
+			if (!res.ok || !res.body) throw new Error(`Chat request failed with status ${res.status}`);
+			const applyChunk = (chunk) => {
+				data.value.push(chunk);
+				const idx = messages.value.findIndex((m) => m.id === assistantId);
+				if (idx === -1) return;
+				const current = messages.value[idx];
+				if (chunk.type === "text-delta") current.content += chunk.text;
+				else if (chunk.type === "tool-call") current.toolCalls = [...current.toolCalls ?? [], {
+					toolCallId: chunk.toolCallId,
+					toolName: chunk.toolName,
+					input: chunk.input
+				}];
+				else if (chunk.type === "tool-result") current.toolResults = [...current.toolResults ?? [], {
+					toolName: chunk.toolName,
+					toolCallId: chunk.toolCallId,
+					result: chunk.result,
+					error: chunk.error
+				}];
+				messages.value = [...messages.value];
+			};
+			for await (const _chunk of parseSseStream(res.body, applyChunk));
+			status.value = "ready";
+		} catch (err) {
+			if (controller.signal.aborted) {
+				status.value = "ready";
+				return;
+			}
+			status.value = "error";
+			error.value = err instanceof Error ? err : new Error(String(err));
+		} finally {
+			controller = null;
+		}
+	}
+	async function reload() {
+		if (!lastUserPrompt || status.value === "streaming") return;
+		const last = messages.value[messages.value.length - 1];
+		if (last && last.role === "assistant" && !last.content && !last.toolCalls?.length && !last.toolResults?.length) messages.value = messages.value.slice(0, -1);
+		await sendMessage(lastUserPrompt);
+	}
+	return {
+		messages,
+		status,
+		error,
+		input,
+		data,
+		setInput,
+		sendMessage,
+		abort,
+		reload,
+		isStreaming
+	};
+}
+/** Drive a `UbeanAgent` directly from a component with reactive state. */
+function useAgent(agent) {
+	const isStreaming = ref(false);
+	const error = ref(null);
+	const result = shallowRef(null);
+	const chunks = ref([]);
+	async function run(input) {
+		isStreaming.value = true;
+		error.value = null;
+		chunks.value = [];
+		try {
+			result.value = await agent.run(input);
+		} catch (err) {
+			error.value = err instanceof Error ? err : new Error(String(err));
+		} finally {
+			isStreaming.value = false;
+		}
+	}
+	async function stream(input) {
+		isStreaming.value = true;
+		error.value = null;
+		result.value = null;
+		chunks.value = [];
+		try {
+			for await (const chunk of agent.stream(input)) chunks.value.push(chunk);
+		} catch (err) {
+			error.value = err instanceof Error ? err : new Error(String(err));
+		} finally {
+			isStreaming.value = false;
+		}
+	}
+	return {
+		isStreaming,
+		error,
+		result,
+		chunks,
+		run,
+		stream
+	};
+}
+/** Read the current fallback provider/model config (set by the Vite plugin). */
+function useAIProvider() {
+	return providerConfig;
+}
+//#endregion
+export { setAIProviderConfig, useAIProvider, useAgent, useChat };

package/dist/types-B5I0sGbf.d.ts

@@ -0,0 +1,195 @@
+import { GenericSchema, InferOutput } from "valibot";
+import { Handler } from "hono";
+//#region src/types.d.ts
+/**
+ * @ubean/ai type definitions.
+ *
+ * Kernel design (B2): a thin, declarative orchestration layer over the Vercel
+ * AI SDK (`ai` / `@ai-sdk/openai-compatible`). The agent loop, tool-calling
+ * protocol and streaming are delegated to the AI SDK; this package only adds
+ * a ubean-idiomatic configuration surface, provider resolution and a Vue
+ * runtime. It does NOT re-implement an agent loop or a gateway.
+ */
+/**
+ * A model reference in the form `"provider/model"`, e.g. `"deepseek/deepseek-chat"`,
+ * `"openai/gpt-5.4"`, `"openrouter/anthropic/claude-3.5-sonnet"`.
+ *
+ * The provider segment is resolved against the provider registry (see
+ * `resolveProvider`). The special provider `"openai-compatible"` (or any
+ * provider resolved through the gateway/baseURL mechanism) maps to
+ * `@ai-sdk/openai-compatible`.
+ */
+type ModelString = string;
+/** Provider kind used to pick the underlying AI SDK provider factory. */
+type ProviderKind = 'openai-compatible' | 'openai' | 'anthropic' | 'google' | 'custom';
+/** A registered provider that `@ubean/ai` can resolve `provider/model` strings against. */
+interface ProviderDefinition {
+  /** Provider identifier used in the `provider/model` string. */
+  id: string;
+  /** Provider kind — currently only `openai-compatible` is bundled. */
+  kind: ProviderKind;
+  /** Base URL for the OpenAI-compatible API. */
+  baseURL: string;
+  /** API key. Prefer injecting via runtime config / env rather than hardcoding. */
+  apiKey?: string;
+  /** Optional extra headers forwarded to the provider. */
+  headers?: Record<string, string>;
+  /** Optional per-provider model alias map (alias → canonical model id). */
+  modelAliases?: Record<string, string>;
+}
+/** The result of resolving a `provider/model` string. */
+interface ResolvedModel {
+  /** The provider definition that handled the model string. */
+  provider: ProviderDefinition;
+  /** The model id to pass to the provider factory. */
+  modelId: string;
+}
+/** Context passed to a tool's `execute`. Carries per-run request metadata. */
+interface AgentToolContext {
+  /** A stable id for the current agent run. */
+  runId: string;
+  /** Free-form metadata injected by the caller (e.g. an authenticated user). */
+  meta?: Record<string, unknown>;
+  /** Abort signal to cancel the run. */
+  signal?: AbortSignal;
+}
+/**
+ * A declarative ubean tool. `execute` may use ubean server helpers
+ * (defineHandler, fetch, storage, ...) and must return a JSON-serializable value.
+ */
+interface AgentTool<TInput extends GenericSchema = GenericSchema> {
+  /** Unique tool name sent to the model (lowercase, safe identifier). */
+  name: string;
+  /** Description used by the model for tool selection. */
+  description: string;
+  /** Valibot schema describing the tool's arguments. */
+  input: TInput;
+  /** Executes the tool; `args` is the parsed input. */
+  execute: (args: InferOutput<TInput>, ctx: AgentToolContext) => unknown | Promise<unknown>;
+}
+/** A map of named tools. */
+type AgentToolSet = Record<string, AgentTool<any>>;
+interface AgentConfig {
+  /** `provider/model` string resolved through the provider registry. */
+  model: ModelString;
+  /** System prompt. */
+  system?: string;
+  /** Static context injected into the system prompt (serialized as JSON snippet). */
+  context?: Record<string, unknown>;
+  /** Named tools available to the agent. */
+  tools?: AgentToolSet;
+  /** Max tool-calling steps before the loop stops (default 5). */
+  maxSteps?: number;
+  /** Sampling temperature (default provider-dependent). */
+  temperature?: number;
+  /** Max output tokens. */
+  maxTokens?: number;
+  /** Extra headers forwarded to the provider. */
+  headers?: Record<string, string>;
+  /** Optional provider override (takes precedence over `model`'s provider). */
+  provider?: ProviderDefinition;
+}
+/** Input to a single agent run. Either a raw prompt or a message list. */
+interface AgentInput {
+  /** Single user prompt. */
+  prompt?: string;
+  /** Full message history (prefer when resuming a conversation). */
+  messages?: Array<AgentUserMessage | AgentAssistantMessage>;
+  /** Per-run metadata exposed to tools via `AgentToolContext.meta`. */
+  meta?: Record<string, unknown>;
+}
+/** User message shape accepted by the kernel. */
+interface AgentUserMessage {
+  role: 'user';
+  content: string;
+}
+/** Assistant message shape accepted by the kernel. */
+interface AgentAssistantMessage {
+  role: 'assistant';
+  content: string;
+}
+/** Token usage for a run. */
+interface AgentUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+}
+/** A tool call emitted by the model during a run. */
+interface AgentToolCall {
+  toolCallId: string;
+  toolName: string;
+  /** The arguments the model provided for the call. */
+  input: Record<string, unknown>;
+}
+/** Result of a completed tool call. */
+interface AgentToolResult {
+  toolName: string;
+  toolCallId: string;
+  /** Returned value (may be undefined). */
+  result?: unknown;
+  /** Present when the tool threw. */
+  error?: string;
+}
+/** Result of a non-streaming `run()`. */
+interface AgentRunResult<T = unknown> {
+  /** Final assistant text. */
+  text: string;
+  /** Structured output when the agent is configured with an output schema. */
+  output?: T;
+  /** Every tool call executed during the run. */
+  toolResults: AgentToolResult[];
+  /** Token usage. */
+  usage?: AgentUsage;
+}
+/** Discriminated streaming chunk emitted by `stream()`. */
+type AgentStreamChunk = {
+  type: 'text-delta';
+  text: string;
+} | {
+  type: 'tool-call';
+  toolCallId: string;
+  toolName: string;
+  input: Record<string, unknown>;
+} | {
+  type: 'tool-result';
+  toolCallId: string;
+  toolName: string;
+  result?: unknown;
+  error?: string;
+} | {
+  type: 'error';
+  error: string;
+} | {
+  type: 'done';
+  usage?: AgentUsage;
+};
+/**
+ * The concrete agent returned by `defineAgent`. All orchestration is delegated
+ * to the AI SDK (`ToolLoopAgent` / `streamText`); this object only exposes the
+ * ubean-idiomatic surface.
+ */
+interface UbeanAgent<T = unknown> {
+  /** The normalized config this agent was built from. */
+  readonly config: AgentConfig;
+  /** Run once and await the full result. */
+  run(input: AgentInput): Promise<AgentRunResult<T>>;
+  /** Stream the run as an async iterable of chunks. */
+  stream(input: AgentInput): AsyncIterable<AgentStreamChunk>;
+  /**
+   * Convert this agent into a Hono handler for an API route. Reads the request
+   * body as `AgentInput`, streams the response as SSE. Compatible with
+   * `defineHandler` / `defineHandlerMeta` conventions.
+   */
+  asHandler(): Handler;
+}
+/** Options for `useUbeanAI` / plugin configuration. */
+interface UbeanAIProviderOptions {
+  /** Providers to register. */
+  providers?: ProviderDefinition[];
+  /** Default provider id used when the model string has no provider segment. */
+  defaultProvider?: string;
+  /** Default model id used when neither the model string nor defaultProvider resolve. */
+  defaultModel?: string;
+}
+//#endregion
+export { UbeanAIProviderOptions as _, AgentStreamChunk as a, AgentToolContext as c, AgentUsage as d, AgentUserMessage as f, ResolvedModel as g, ProviderKind as h, AgentRunResult as i, AgentToolResult as l, ProviderDefinition as m, AgentConfig as n, AgentTool as o, ModelString as p, AgentInput as r, AgentToolCall as s, AgentAssistantMessage as t, AgentToolSet as u, UbeanAgent as v };

package/dist/vite.d.ts

@@ -0,0 +1,18 @@
+import { m as ProviderDefinition } from "./types-B5I0sGbf.js";
+import { Plugin } from "vite";
+//#region src/vite.d.ts
+interface UbeanAiOptions {
+  /** Master switch. Disabled plugin returns a noop. */
+  enabled?: boolean;
+  /** Provider presets to register on the server kernel. */
+  providers?: ProviderDefinition[];
+  /** Default provider id used when a model string has no provider segment. */
+  defaultProvider?: string;
+  /** Auto-import the runtime composables (default true). */
+  autoImport?: boolean;
+}
+/** Type-safe helper for defining AI options (pass-through). */
+declare function defineAiConfig(options: UbeanAiOptions): UbeanAiOptions;
+declare function ubeanAiPlugin(userOptions?: UbeanAiOptions): Plugin;
+//#endregion
+export { UbeanAiOptions, ubeanAiPlugin as default, ubeanAiPlugin, defineAiConfig };

package/dist/vite.js

@@ -0,0 +1,58 @@
+import { i as defineProvider } from "./core-B-pZdSgG.js";
+import { registerComponentResolver } from "@ubean/build";
+//#region src/vite.ts
+/** Composable API names auto-importable from `@ubean/ai/runtime/vue`. */
+const RUNTIME_COMPOSABLES = [
+	"useChat",
+	"useAgent",
+	"useAIProvider"
+];
+/** Type-safe helper for defining AI options (pass-through). */
+function defineAiConfig(options) {
+	return options;
+}
+const VIRTUAL_RUNTIME_ID = "virtual:ubean-ai/runtime";
+const RESOLVED_VIRTUAL_RUNTIME_ID = `\0${VIRTUAL_RUNTIME_ID}`;
+function ubeanAiPlugin(userOptions = {}) {
+	const options = userOptions;
+	if (options.enabled === false) return {
+		name: "ubean:ai:noop",
+		enforce: "post"
+	};
+	const autoImportEnabled = options.autoImport !== false;
+	for (const provider of options.providers ?? []) defineProvider(provider);
+	if (autoImportEnabled) registerComponentResolver((name) => {
+		if (RUNTIME_COMPOSABLES.includes(name)) return {
+			name,
+			from: "@ubean/ai/runtime/vue"
+		};
+	});
+	return {
+		name: "ubean:ai",
+		enforce: "pre",
+		resolveId(id) {
+			if (id === VIRTUAL_RUNTIME_ID) return RESOLVED_VIRTUAL_RUNTIME_ID;
+			return null;
+		},
+		load(id) {
+			if (id === RESOLVED_VIRTUAL_RUNTIME_ID) return generateRuntimeVirtualModule(options);
+			return null;
+		},
+		config() {
+			return { optimizeDeps: { include: ["@ubean/ai/runtime/vue"] } };
+		}
+	};
+}
+/** Generate the client virtual module that injects config and re-exports the runtime. */
+function generateRuntimeVirtualModule(options) {
+	const defaultProvider = options.defaultProvider ?? "";
+	return `
+import { useChat, useAgent, useAIProvider, setAIProviderConfig } from '@ubean/ai/runtime/vue';
+
+${defaultProvider ? `setAIProviderConfig({ defaultProvider: ${JSON.stringify(defaultProvider)} });` : ""}
+
+export { useChat, useAgent, useAIProvider, setAIProviderConfig };
+`;
+}
+//#endregion
+export { ubeanAiPlugin as default, ubeanAiPlugin, defineAiConfig };

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@ubean/ai",
+  "version": "0.2.0",
+  "description": "AI large-model integration for the ubean framework: defineAgent + defineAgentTool + Vue runtime (thin orchestration over the Vercel AI SDK)",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    },
+    "./runtime/vue": {
+      "types": "./dist/runtime/vue.d.ts",
+      "import": "./dist/runtime/vue.js"
+    },
+    "./gateway": {
+      "types": "./dist/gateway.d.ts",
+      "import": "./dist/gateway.js"
+    }
+  },
+  "dependencies": {
+    "@valibot/to-json-schema": "^1.7.1",
+    "valibot": "^1.4.2",
+    "@ubean/build": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "hono": "4.13.2",
+    "typescript": "7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.9",
+    "vite-plus": "0.2.9",
+    "vue": "^3.5.41"
+  },
+  "peerDependencies": {
+    "@ai-sdk/openai-compatible": "^1.0.0 || ^2.0.0 || ^3.0.0",
+    "ai": "^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0",
+    "hono": "^4.0.0",
+    "vite": "^5.0.0 || ^6.0.0",
+    "vue": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "@ai-sdk/openai-compatible": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "typecheck": "tsc --noEmit --skipLibCheck"
+  }
+}