@nebutra/agents 1.1.1 → 2.0.0

package/README.md

@@ -41,7 +41,7 @@ integration hook lives here in `providers/langchain.ts` as an extension point.
 ```ts
 import { configure, streamText } from "@nebutra/agents";
 
-configure({ provider: "openrouter", defaultModel: "anthropic/claude-sonnet-4" });
+configure({ provider: "openrouter", defaultModel: "anthropic/claude-sonnet-4.6" });
 
 const result = await streamText(
   [{ role: "user", content: "Explain monorepos" }],
@@ -58,13 +58,13 @@ import { VercelAIAgent } from "@nebutra/agents/providers/vercel-ai";
 
 const orchestrator = new AgentOrchestrator({
   agents: [
-    { id: "assistant", name: "Assistant", description: "Helpful", model: "openai/gpt-4", instructions: "..." },
+    { id: "assistant", name: "Assistant", description: "Helpful", model: "openai/gpt-5.5", instructions: "..." },
   ],
 });
 
 // Swap the BaseAgent for a real VercelAIAgent at runtime:
 orchestrator.registerAgent(
-  new VercelAIAgent({ id: "assistant", name: "Assistant", description: "Helpful", model: "openai/gpt-4", instructions: "..." }),
+  new VercelAIAgent({ id: "assistant", name: "Assistant", description: "Helpful", model: "openai/gpt-5.5", instructions: "..." }),
 );
 
 const ctx = createAgentContext("org_123", "user_456");
@@ -76,3 +76,7 @@ const response = await orchestrator.chat("Hello", ctx);
 
 Every agent operation requires a `tenantId`. Usage events are emitted for
 billing and metering integration (see `@nebutra/billing/credits`).
+
+## License
+
+MIT

package/dist/{agent-CahnMASx.d.ts → agent-DDGWuUpe.d.ts}

@@ -1,4 +1,4 @@
-import { c as AgentConfig, A as AgentMessage, a as AgentContext, b as AgentResponse } from './types-NtgB3pch.js';
+import { c as AgentConfig, A as AgentMessage, a as AgentContext, b as AgentResponse } from './types-BytC-HfQ.js';
 
 /**
  * BaseAgent — abstract agent with memory, usage tracking, and tenant scoping.

package/dist/{chunk-B7XWL35G.js → chunk-7VL333VJ.js}

@@ -1,7 +1,7 @@
 import {
   getAgentsEnv,
   isLangfuseConfigured
-} from "./chunk-5LX742GP.js";
+} from "./chunk-FCXWOXII.js";
 
 // src/observability.ts
 import { logger } from "@nebutra/logger";
@@ -28,6 +28,9 @@ async function initLangfuse() {
     return null;
   }
 }
+function _resetLangfuseCache() {
+  _client = void 0;
+}
 function buildTelemetryConfig(args) {
   if (!isLangfuseConfigured()) {
     return { isEnabled: false };
@@ -55,6 +58,7 @@ async function flushTelemetry() {
 
 export {
   initLangfuse,
+  _resetLangfuseCache,
   buildTelemetryConfig,
   flushTelemetry
 };

package/dist/{chunk-5LX742GP.js → chunk-C4CC5UEF.js}

@@ -1,60 +1,22 @@
 import {
-  resolveModel
-} from "./chunk-5JZJ5KMC.js";
-
-// src/env.ts
-import { z } from "zod";
-var FallbackProviderName = z.enum(["openrouter", "anthropic", "openai"]);
-var FallbackChain = z.string().transform(
-  (raw) => raw.split(",").map((s) => s.trim()).filter(Boolean)
-).pipe(z.array(FallbackProviderName).min(1));
-var AgentsEnvSchema = z.object({
-  // ── Anthropic (direct) ─────────────────────────────────────────────────
-  ANTHROPIC_API_KEY: z.string().optional(),
-  // ── Langfuse (LLM tracing — optional) ─────────────────────────────────
-  LANGFUSE_PUBLIC_KEY: z.string().optional(),
-  LANGFUSE_SECRET_KEY: z.string().optional(),
-  LANGFUSE_HOST: z.string().url().default("https://cloud.langfuse.com"),
-  // ── Multi-provider fallback chain ─────────────────────────────────────
-  /**
-   * Comma-separated chain of providers tried in order on retryable failures.
-   * Default: "openrouter,anthropic,openai" — OpenRouter first (multi-model),
-   * then direct Anthropic (prompt caching), then direct OpenAI as last resort.
-   */
-  LLM_FALLBACK_CHAIN: FallbackChain.default(() => [
-    "openrouter",
-    "anthropic",
-    "openai"
-  ]),
-  /**
-   * Comma-separated chain of providers tried for EMBEDDINGS, in order.
-   * Default: "openrouter,openai" — Anthropic does not currently expose
-   * embedding models, so it is excluded by default. If unset, falls back
-   * to LLM_FALLBACK_CHAIN with embedding-incompatible providers filtered out.
-   */
-  LLM_EMBEDDING_FALLBACK_CHAIN: FallbackChain.default(() => [
-    "openrouter",
-    "openai"
-  ])
-});
-var _cached;
-function getAgentsEnv() {
-  if (_cached) return _cached;
-  _cached = AgentsEnvSchema.parse(globalThis.process?.env ?? {});
-  return _cached;
-}
-function isLangfuseConfigured() {
-  const env = getAgentsEnv();
-  return Boolean(env.LANGFUSE_PUBLIC_KEY && env.LANGFUSE_SECRET_KEY);
-}
+  resolveModel,
+  toAi302ModelId
+} from "./chunk-HVLFZW6E.js";
+import {
+  getAgentsEnv
+} from "./chunk-FCXWOXII.js";
 
 // src/fallback.ts
 import { logger } from "@nebutra/logger";
 var ENV_KEY_BY_PROVIDER = {
   openrouter: "OPENROUTER_API_KEY",
   anthropic: "ANTHROPIC".concat("_API_KEY"),
-  openai: "OPENAI".concat("_API_KEY")
+  openai: "OPENAI".concat("_API_KEY"),
+  ai302: "AI302_API_KEY"
 };
+function ai302BaseUrl() {
+  return globalThis.process?.env?.AI302_BASE_URL ?? "https://api.302.ai/v1";
+}
 function hasProviderKey(provider) {
   const k = ENV_KEY_BY_PROVIDER[provider];
   return Boolean(globalThis.process?.env?.[k]);
@@ -83,6 +45,10 @@ async function buildModel(provider, modelOrPreset) {
       const openaiModelId = modelId.startsWith("openai/") ? modelId.slice("openai/".length) : modelId;
       return createOpenAI({ apiKey })(openaiModelId);
     }
+    case "ai302": {
+      const { createOpenAI } = await import("@ai-sdk/openai");
+      return createOpenAI({ apiKey, baseURL: ai302BaseUrl() })(toAi302ModelId(modelId));
+    }
   }
 }
 var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504]);
@@ -145,7 +111,10 @@ function buildSystemWithCache(systemPrompt) {
 }
 var EMBEDDING_CAPABLE = /* @__PURE__ */ new Set([
   "openrouter",
-  "openai"
+  "openai",
+  // 302.AI serves /v1/embeddings — an unauthenticated POST answers
+  // `Missing 302 Apikey` rather than 404, so the route exists behind auth.
+  "ai302"
 ]);
 async function buildEmbeddingModel(provider, modelOrPreset) {
   const modelId = resolveModel(modelOrPreset);
@@ -162,6 +131,12 @@ async function buildEmbeddingModel(provider, modelOrPreset) {
       const openaiModelId = modelId.startsWith("openai/") ? modelId.slice("openai/".length) : modelId;
       return createOpenAI({ apiKey }).textEmbeddingModel(openaiModelId);
     }
+    case "ai302": {
+      const { createOpenAI } = await import("@ai-sdk/openai");
+      return createOpenAI({ apiKey, baseURL: ai302BaseUrl() }).textEmbeddingModel(
+        toAi302ModelId(modelId)
+      );
+    }
     case "anthropic": {
       throw new Error("Anthropic does not expose embedding models");
     }
@@ -212,9 +187,6 @@ async function runEmbedWithFallback(invoke, options = {}) {
 }
 
 export {
-  AgentsEnvSchema,
-  getAgentsEnv,
-  isLangfuseConfigured,
   filterAvailableProviders,
   isRetryableError,
   runWithFallback,

package/{src/env.ts → dist/chunk-FCXWOXII.js}

@@ -1,79 +1,55 @@
-/**
- * Environment validation for `@nebutra/agents`.
- *
- * All variables are OPTIONAL — the package must work with zero new env config.
- * Provider keys (OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
- * are validated lazily by the provider resolver, not here.
- */
-
+// src/env.ts
 import { z } from "zod";
-
-/** Comma-separated provider chain. Order = priority. */
-const FallbackProviderName = z.enum(["openrouter", "anthropic", "openai"]);
-export type FallbackProviderName = z.infer<typeof FallbackProviderName>;
-
-const FallbackChain = z
-  .string()
-  .transform((raw) =>
-    raw
-      .split(",")
-      .map((s) => s.trim())
-      .filter(Boolean),
-  )
-  .pipe(z.array(FallbackProviderName).min(1));
-
-export const AgentsEnvSchema = z.object({
+var FallbackProviderName = z.enum(["openrouter", "anthropic", "openai", "ai302"]);
+var FallbackChain = z.string().transform(
+  (raw) => raw.split(",").map((s) => s.trim()).filter(Boolean)
+).pipe(z.array(FallbackProviderName).min(1));
+var AgentsEnvSchema = z.object({
   // ── Anthropic (direct) ─────────────────────────────────────────────────
   ANTHROPIC_API_KEY: z.string().optional(),
-
   // ── Langfuse (LLM tracing — optional) ─────────────────────────────────
   LANGFUSE_PUBLIC_KEY: z.string().optional(),
   LANGFUSE_SECRET_KEY: z.string().optional(),
   LANGFUSE_HOST: z.string().url().default("https://cloud.langfuse.com"),
-
   // ── Multi-provider fallback chain ─────────────────────────────────────
   /**
    * Comma-separated chain of providers tried in order on retryable failures.
    * Default: "openrouter,anthropic,openai" — OpenRouter first (multi-model),
    * then direct Anthropic (prompt caching), then direct OpenAI as last resort.
    */
-  LLM_FALLBACK_CHAIN: FallbackChain.default((): FallbackProviderName[] => [
+  LLM_FALLBACK_CHAIN: FallbackChain.default(() => [
     "openrouter",
     "anthropic",
-    "openai",
+    "openai"
   ]),
-
   /**
    * Comma-separated chain of providers tried for EMBEDDINGS, in order.
    * Default: "openrouter,openai" — Anthropic does not currently expose
    * embedding models, so it is excluded by default. If unset, falls back
    * to LLM_FALLBACK_CHAIN with embedding-incompatible providers filtered out.
    */
-  LLM_EMBEDDING_FALLBACK_CHAIN: FallbackChain.default((): FallbackProviderName[] => [
+  LLM_EMBEDDING_FALLBACK_CHAIN: FallbackChain.default(() => [
     "openrouter",
-    "openai",
-  ]),
+    "openai"
+  ])
 });
-
-export type AgentsEnv = z.infer<typeof AgentsEnvSchema>;
-
-/** Lazy parsed env — re-read once on first call. */
-let _cached: AgentsEnv | undefined;
-
-/** Returns the validated env (cached). Safe to call from any runtime. */
-export function getAgentsEnv(): AgentsEnv {
+var _cached;
+function getAgentsEnv() {
   if (_cached) return _cached;
   _cached = AgentsEnvSchema.parse(globalThis.process?.env ?? {});
   return _cached;
 }
-
-/** Test helper — clears cache so updated process.env is picked up. */
-export function _resetAgentsEnvCache(): void {
-  _cached = undefined;
+function _resetAgentsEnvCache() {
+  _cached = void 0;
 }
-
-/** True iff Langfuse credentials are present. */
-export function isLangfuseConfigured(): boolean {
+function isLangfuseConfigured() {
   const env = getAgentsEnv();
   return Boolean(env.LANGFUSE_PUBLIC_KEY && env.LANGFUSE_SECRET_KEY);
 }
+
+export {
+  AgentsEnvSchema,
+  getAgentsEnv,
+  _resetAgentsEnvCache,
+  isLangfuseConfigured
+};

package/dist/chunk-HVLFZW6E.js

@@ -0,0 +1,71 @@
+// src/sdk/frontier-fallback.generated.ts
+var FRONTIER_FALLBACK = {
+  reasoning: "anthropic/claude-opus-5",
+  flagship: "anthropic/claude-sonnet-5",
+  fast: "anthropic/claude-haiku-4.5",
+  "openai-flagship": "openai/gpt-5.6-sol",
+  "google-flagship": "google/gemini-3.1-pro-preview",
+  "google-fast": "google/gemini-3.7-flash"
+};
+var AI302_ALIASES = {
+  fast: "claude-haiku-4-5-20251001"
+};
+var AI302_OPEN_MODELS = {
+  "302-deepseek": "deepseek-v4-pro",
+  "302-deepseek-fast": "deepseek-v4-flash",
+  "302-qwen": "qwen3.8-max",
+  "302-glm": "glm-5.3",
+  "302-kimi": "kimi-k3",
+  "302-minimax": "MiniMax-M3"
+};
+
+// src/sdk/models.ts
+var models = {
+  // ── Generated frontier tiers — edit via `pnpm gen:frontier-models` ──────────
+  ...FRONTIER_FALLBACK,
+  /** Embedding model */
+  embedding: "openai/text-embedding-3-small",
+  /** Embedding model (high-dimensional) */
+  "embedding-large": "openai/text-embedding-3-large",
+  // --- Open-weight families via 302.AI (use with provider: "ai302") ---
+  // Generated with the tiers above. These replaced three SiliconFlow presets
+  // naming Qwen2.5-72B, DeepSeek-R1 and DeepSeek-V3 — every one superseded,
+  // none with a caller anywhere in the repo, and none checkable without a
+  // SiliconFlow key. 302 serves the same families and lists its catalogue,
+  // so these are resolved rather than remembered.
+  ...AI302_OPEN_MODELS,
+  // --- SenseNova Token Plan presets (use with provider: "sensenova") ---
+  // Base URL: https://token.sensenova.cn/v1
+  // Docs: https://github.com/OpenSenseNova/SenseNova6.7/blob/main/API_CN.md
+  /** SenseNova 6.7 Flash-Lite — small multimodal agent (default for i18n CI) */
+  "sn-flash-lite": "sensenova-6.7-flash-lite",
+  /** DeepSeek V4 Flash via SenseNova Token Plan — long context, cheap */
+  "sn-deepseek-flash": "deepseek-v4-flash",
+  /** Alias: prefer flash-lite for bulk translation */
+  "sn-translate": "sensenova-6.7-flash-lite"
+};
+function resolveModel(modelOrPreset) {
+  if (modelOrPreset in models) {
+    return models[modelOrPreset];
+  }
+  return modelOrPreset;
+}
+var AI302_BY_GATEWAY_ID = Object.fromEntries(
+  Object.entries(AI302_ALIASES).map(([tier, id]) => [
+    FRONTIER_FALLBACK[tier],
+    id
+  ])
+);
+function toAi302ModelId(modelOrPreset) {
+  const modelId = resolveModel(modelOrPreset);
+  const alias = AI302_BY_GATEWAY_ID[modelId];
+  if (alias) return alias;
+  const slash = modelId.indexOf("/");
+  return slash === -1 ? modelId : modelId.slice(slash + 1);
+}
+
+export {
+  models,
+  resolveModel,
+  toAi302ModelId
+};

package/dist/chunk-HZQXXUKB.js

@@ -0,0 +1,171 @@
+import {
+  isRetryableError
+} from "./chunk-C4CC5UEF.js";
+
+// src/generation/index.ts
+import { logger } from "@nebutra/logger";
+
+// src/generation/mock-provider.ts
+function hash(input) {
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function escapeXml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function svgDataUri(label, prompt, w, h) {
+  const hue = hash(prompt) % 360;
+  const hue2 = (hue + 40) % 360;
+  const words = prompt.split(/\s+/);
+  const lines = [];
+  let cur = "";
+  for (const word of words) {
+    if ((cur + " " + word).trim().length > 32) {
+      lines.push(cur.trim());
+      cur = word;
+    } else {
+      cur = `${cur} ${word}`;
+    }
+    if (lines.length === 4) break;
+  }
+  if (cur && lines.length < 4) lines.push(cur.trim());
+  const tspans = lines.map((ln, i) => `<tspan x="50%" dy="${i === 0 ? 0 : 26}">${escapeXml(ln)}</tspan>`).join("");
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">
+<defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+<stop offset="0" stop-color="hsl(${hue} 70% 55%)"/>
+<stop offset="1" stop-color="hsl(${hue2} 70% 45%)"/>
+</linearGradient></defs>
+<rect width="${w}" height="${h}" fill="url(#g)"/>
+<text x="50%" y="14%" fill="rgba(255,255,255,.7)" font-family="sans-serif" font-size="20" text-anchor="middle">${escapeXml(label)}</text>
+<text x="50%" y="46%" fill="#fff" font-family="sans-serif" font-size="22" font-weight="600" text-anchor="middle">${tspans}</text>
+</svg>`;
+  const b64 = typeof btoa === "function" ? btoa(unescape(encodeURIComponent(svg))) : Buffer.from(svg, "utf8").toString("base64");
+  return `data:image/svg+xml;base64,${b64}`;
+}
+var mockGenerationProvider = {
+  name: "mock",
+  envKey: null,
+  capabilities: ["image", "video"],
+  async generateImage(req, _ctx) {
+    const width = req.width ?? 1024;
+    const height = req.height ?? 1024;
+    return {
+      modality: "image",
+      mimeType: "image/svg+xml",
+      url: svgDataUri("mock \xB7 image", req.prompt, width, height),
+      width,
+      height,
+      providerName: "mock",
+      model: req.model ?? "mock-image-1",
+      usage: { units: 1 }
+    };
+  },
+  async generateVideo(req, _ctx) {
+    const width = req.width ?? 1280;
+    const height = req.height ?? 720;
+    const seconds = req.durationSeconds ?? 5;
+    return {
+      modality: "video",
+      mimeType: "image/svg+xml",
+      url: svgDataUri(`mock \xB7 video \xB7 ${seconds}s`, req.prompt, width, height),
+      width,
+      height,
+      providerName: "mock",
+      model: req.model ?? "mock-video-1",
+      usage: { units: seconds }
+    };
+  }
+};
+
+// src/generation/index.ts
+var log = logger.child({ module: "agents/generation" });
+var _registry = /* @__PURE__ */ new Map();
+function registerGenerationProvider(provider) {
+  _registry.set(provider.name, provider);
+}
+function _resetGenerationRegistry() {
+  _registry.clear();
+  _registry.set(mockGenerationProvider.name, mockGenerationProvider);
+}
+_resetGenerationRegistry();
+function hasEnvKey(provider) {
+  if (provider.envKey === null) return true;
+  return Boolean(globalThis.process?.env?.[provider.envKey]);
+}
+function listGenerationProviders(modality, options = {}) {
+  const envChain = (globalThis.process?.env?.GENERATION_FALLBACK_CHAIN ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  const preferred = options.chain ?? (envChain.length > 0 ? envChain : []);
+  const mockName = mockGenerationProvider.name;
+  const all = [...preferred, ..._registry.keys()];
+  const seen = /* @__PURE__ */ new Set();
+  const resolved = [];
+  for (const name of all) {
+    if (seen.has(name) || name === mockName) continue;
+    seen.add(name);
+    const provider = _registry.get(name);
+    if (!provider) continue;
+    if (!provider.capabilities.includes(modality)) continue;
+    if (!hasEnvKey(provider)) continue;
+    resolved.push(name);
+  }
+  resolved.push(mockName);
+  return resolved;
+}
+async function runChain(modality, options, ctx, invoke) {
+  const chain = listGenerationProviders(modality, options);
+  let lastErr;
+  for (const name of chain) {
+    const provider = _registry.get(name);
+    if (!provider) continue;
+    try {
+      const result = await invoke(provider);
+      log.debug("generation succeeded", {
+        provider: name,
+        modality,
+        tenantId: ctx.tenantId
+      });
+      return result;
+    } catch (err) {
+      lastErr = err;
+      const retryable = isRetryableError(err);
+      log.warn("generation provider failed", {
+        provider: name,
+        modality,
+        retryable,
+        tenantId: ctx.tenantId
+      });
+      if (!retryable && name !== mockGenerationProvider.name) continue;
+      if (!retryable) throw err;
+    }
+  }
+  throw lastErr instanceof Error ? lastErr : new Error("[@nebutra/agents] generation chain exhausted");
+}
+async function generateImage(req, ctx, options = {}) {
+  return runChain("image", options, ctx, (p) => {
+    if (!p.generateImage) {
+      throw new Error(`[@nebutra/agents] provider "${p.name}" lacks image support`);
+    }
+    return p.generateImage(req, ctx);
+  });
+}
+async function generateVideo(req, ctx, options = {}) {
+  return runChain("video", options, ctx, (p) => {
+    if (!p.generateVideo) {
+      throw new Error(`[@nebutra/agents] provider "${p.name}" lacks video support`);
+    }
+    return p.generateVideo(req, ctx);
+  });
+}
+
+export {
+  mockGenerationProvider,
+  registerGenerationProvider,
+  _resetGenerationRegistry,
+  listGenerationProviders,
+  generateImage,
+  generateVideo
+};

package/dist/{chunk-RLWM437Q.js → chunk-KC6SOI5Z.js}

@@ -1,9 +1,10 @@
 import {
   resolveApiKey
-} from "./chunk-NVPE5EDI.js";
+} from "./chunk-YBCIJKC7.js";
 import {
-  resolveModel
-} from "./chunk-5JZJ5KMC.js";
+  resolveModel,
+  toAi302ModelId
+} from "./chunk-HVLFZW6E.js";
 
 // src/sdk/provider.ts
 import { createOpenAI } from "@ai-sdk/openai";
@@ -27,10 +28,24 @@ function createModel(modelOrPreset, config) {
     case "siliconflow": {
       const provider = createOpenAI({
         apiKey,
-        baseURL: "https://api.siliconflow.cn/v1"
+        baseURL: process.env.SILICONFLOW_BASE_URL ?? "https://api.siliconflow.cn/v1"
       });
       return provider(modelId);
     }
+    case "sensenova": {
+      const provider = createOpenAI({
+        apiKey,
+        baseURL: process.env.SENSENOVA_BASE_URL ?? "https://token.sensenova.cn/v1"
+      });
+      return provider(modelId);
+    }
+    case "ai302": {
+      const provider = createOpenAI({
+        apiKey,
+        baseURL: process.env.AI302_BASE_URL ?? "https://api.302.ai/v1"
+      });
+      return provider(toAi302ModelId(modelId));
+    }
     case "gateway": {
       const provider = createOpenAI({
         apiKey,

package/dist/{chunk-NPQECBXL.js → chunk-S5N743EP.js}

@@ -1,20 +1,69 @@
-import {
-  runEmbedWithFallback
-} from "./chunk-5LX742GP.js";
 import {
   createModel
-} from "./chunk-RLWM437Q.js";
+} from "./chunk-KC6SOI5Z.js";
 import {
   NebutraAIConfigSchema
-} from "./chunk-NVPE5EDI.js";
+} from "./chunk-YBCIJKC7.js";
+import {
+  assertSafeOpenAIJsonPayload
+} from "./chunk-VZPQOXWW.js";
+import {
+  runEmbedWithFallback,
+  runWithFallback
+} from "./chunk-C4CC5UEF.js";
 
 // src/sdk/index.ts
 import {
   embed as _embed,
   embedMany as _embedMany,
-  generateText as _generateText,
+  generateText as _generateText2,
   streamText as _streamText
 } from "ai";
+
+// src/sdk/structured.ts
+import { generateText as _generateText, jsonSchema, tool } from "ai";
+import Ajv from "ajv";
+var ajv = new Ajv({ allErrors: true, strict: false });
+function validateStructured(value, schema) {
+  const validate = ajv.compile(schema);
+  if (!validate(value)) {
+    throw new Error(
+      `structured output failed schema validation: ${ajv.errorsText(validate.errors)}`
+    );
+  }
+}
+async function generateStructured(messages, schema, options = {}) {
+  assertSafeOpenAIJsonPayload("OpenAI structured request messages", messages);
+  assertSafeOpenAIJsonPayload("OpenAI structured output schema", schema);
+  const { result } = await runWithFallback(
+    (model) => _generateText({
+      model,
+      messages,
+      tools: {
+        _output: tool({
+          description: "Return the final result as a structured object matching the schema.",
+          inputSchema: jsonSchema(schema)
+        })
+      },
+      toolChoice: { type: "tool", toolName: "_output" }
+    }),
+    { model: options.model ?? "flagship" }
+  );
+  const call = result.toolCalls?.find((c) => c.toolName === "_output");
+  const output = call?.input ?? null;
+  validateStructured(output, schema);
+  const usage = result.usage;
+  return {
+    output,
+    usage: {
+      inputTokens: usage?.inputTokens ?? 0,
+      outputTokens: usage?.outputTokens ?? 0,
+      reasoningOutputTokens: usage?.reasoningTokens ?? 0
+    }
+  };
+}
+
+// src/sdk/index.ts
 var _resolved = NebutraAIConfigSchema.parse({});
 function configure(config = {}) {
   _resolved = NebutraAIConfigSchema.parse(config);
@@ -23,8 +72,9 @@ function getConfig() {
   return _resolved;
 }
 async function generateText(messages, options = {}) {
+  assertSafeOpenAIJsonPayload("OpenAI request messages", messages);
   const model = createModel(options.model ?? _resolved.defaultModel, _resolved);
-  return await _generateText({
+  return await _generateText2({
     model,
     messages,
     ...options.system ? { system: options.system } : {},
@@ -34,6 +84,7 @@ async function generateText(messages, options = {}) {
   });
 }
 async function streamText(messages, options = {}) {
+  assertSafeOpenAIJsonPayload("OpenAI request messages", messages);
   const model = createModel(options.model ?? _resolved.defaultModel, _resolved);
   const userOnFinish = options.onFinish;
   return _streamText({
@@ -73,6 +124,8 @@ async function embedMany(values, options = {}) {
 }
 
 export {
+  validateStructured,
+  generateStructured,
   configure,
   getConfig,
   generateText,