@nebutra/agents 1.0.0 → 1.1.0

package/dist/sdk/config.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+
+/**
+ * Runtime configuration for the Vercel AI SDK-backed helpers
+ * (`generateText`, `streamText`, `embed`, `embedMany`).
+ *
+ * Previously lived in `@nebutra/ai-sdk/config`. Absorbed into
+ * `@nebutra/agents` during the AI package consolidation so there is
+ * a single AI runtime package.
+ */
+
+/**
+ * Supported AI provider backends for the top-level helpers.
+ *
+ * - openrouter:   300+ models, automatic failover, pay-as-you-go (default)
+ * - openai:       Direct OpenAI API access
+ * - siliconflow:  SiliconFlow cloud — Qwen, DeepSeek, etc. (OpenAI-compatible, China-optimized)
+ * - gateway:      Vercel AI Gateway with OIDC auth (for Vercel-deployed apps)
+ */
+declare const ProviderType: z.ZodEnum<{
+    openrouter: "openrouter";
+    openai: "openai";
+    siliconflow: "siliconflow";
+    gateway: "gateway";
+}>;
+type ProviderType = z.infer<typeof ProviderType>;
+declare const NebutraAIConfigSchema: z.ZodObject<{
+    provider: z.ZodDefault<z.ZodEnum<{
+        openrouter: "openrouter";
+        openai: "openai";
+        siliconflow: "siliconflow";
+        gateway: "gateway";
+    }>>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    defaultModel: z.ZodDefault<z.ZodString>;
+    temperature: z.ZodDefault<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    extraBody: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+type NebutraAIConfig = z.input<typeof NebutraAIConfigSchema>;
+type ResolvedNebutraAIConfig = z.output<typeof NebutraAIConfigSchema>;
+/**
+ * Resolves the API key from explicit config or environment variables.
+ */
+declare function resolveApiKey(config: ResolvedNebutraAIConfig): string;
+
+export { type NebutraAIConfig, NebutraAIConfigSchema, ProviderType, type ResolvedNebutraAIConfig, resolveApiKey };

package/dist/sdk/config.js

@@ -0,0 +1,10 @@
+import {
+  NebutraAIConfigSchema,
+  ProviderType,
+  resolveApiKey
+} from "../chunk-NVPE5EDI.js";
+export {
+  NebutraAIConfigSchema,
+  ProviderType,
+  resolveApiKey
+};

package/dist/sdk/index.d.ts

@@ -0,0 +1,94 @@
+import * as ai from 'ai';
+import { JSONValue, ModelMessage, GenerateTextResult, StreamTextResult } from 'ai';
+export { GenerateTextResult, ModelMessage, StreamTextResult } from 'ai';
+import { NebutraAIConfig, ResolvedNebutraAIConfig } from './config.js';
+export { NebutraAIConfigSchema, ProviderType } from './config.js';
+export { ModelPreset, models, resolveModel } from './models.js';
+export { createEmbeddingModel, createModel } from './provider.js';
+import 'zod';
+
+/**
+ * Initialise the global Nebutra AI configuration.
+ * Call once in your app entry point (e.g. instrumentation.ts or layout.tsx).
+ *
+ * @example
+ * ```ts
+ * import { configure } from "@nebutra/agents";
+ *
+ * configure({ provider: "openrouter" });
+ * // → reads OPENROUTER_API_KEY from env automatically
+ * ```
+ */
+declare function configure(config?: NebutraAIConfig): void;
+/** Returns the current resolved config (read-only). */
+declare function getConfig(): Readonly<ResolvedNebutraAIConfig>;
+/**
+ * Stream-completion event passed to {@link StreamOptions.onFinish}.
+ * Mirrors the AI SDK's `streamText.onFinish` event shape but is decoupled
+ * from the SDK internals so consumers don't break on SDK version bumps.
+ */
+interface StreamFinishEvent {
+    /** Final accumulated text of the model's response. */
+    text: string;
+    /** Reason the stream terminated (e.g. "stop", "length", "tool-calls"). */
+    finishReason: string;
+    /** Token usage for the request (best-effort; provider-dependent). */
+    usage: {
+        inputTokens: number | undefined;
+        outputTokens: number | undefined;
+        totalTokens: number | undefined;
+    };
+}
+interface GenerateOptions {
+    /** Model ID or preset alias (e.g. "flagship", "fast", "anthropic/claude-sonnet-4"). */
+    model?: string;
+    /** System prompt prepended to the conversation. */
+    system?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** OpenRouter-specific provider options (reasoning, cacheControl, etc.). */
+    providerOptions?: Record<string, JSONValue | undefined>;
+}
+/**
+ * Options accepted by {@link streamText}. Adds the durable `onFinish` hook on
+ * top of {@link GenerateOptions}.
+ */
+interface StreamOptions extends GenerateOptions {
+    /**
+     * Invoked once the model has finished streaming, regardless of whether the
+     * client kept the response connection open. Use this for server-side
+     * persistence (e.g. saving chat sessions to a database) — it is the durable
+     * hook for write-once side-effects.
+     *
+     * Errors thrown inside the callback are caught by the AI SDK and logged;
+     * they do not surface to the streaming client.
+     */
+    onFinish?: (event: StreamFinishEvent) => void | Promise<void>;
+}
+/**
+ * Generate a complete text response.
+ */
+declare function generateText(messages: ModelMessage[], options?: GenerateOptions): Promise<GenerateTextResult<Record<string, never>, never>>;
+/**
+ * Stream a text response for real-time UI.
+ */
+declare function streamText(messages: ModelMessage[], options?: StreamOptions): Promise<StreamTextResult<Record<string, never>, never>>;
+interface EmbedOptions {
+    /** Embedding model ID or preset alias. Defaults to "embedding". */
+    model?: string;
+}
+/**
+ * Generate an embedding vector for a single value.
+ *
+ * Uses `runEmbedWithFallback()` so retryable failures (429 / 5xx / network)
+ * automatically rotate to the next provider in `LLM_EMBEDDING_FALLBACK_CHAIN`.
+ */
+declare function embed(value: string, options?: EmbedOptions): Promise<ai.EmbedResult>;
+/**
+ * Generate embedding vectors for multiple values in a single request.
+ *
+ * Uses `runEmbedWithFallback()` for provider rotation on retryable errors.
+ */
+declare function embedMany(values: string[], options?: EmbedOptions): Promise<ai.EmbedManyResult>;
+
+export { type EmbedOptions, type GenerateOptions, NebutraAIConfig, ResolvedNebutraAIConfig, type StreamFinishEvent, type StreamOptions, configure, embed, embedMany, generateText, getConfig, streamText };

package/dist/sdk/index.js

@@ -0,0 +1,33 @@
+import {
+  configure,
+  embed,
+  embedMany,
+  generateText,
+  getConfig,
+  streamText
+} from "../chunk-NPQECBXL.js";
+import "../chunk-5LX742GP.js";
+import {
+  createEmbeddingModel,
+  createModel
+} from "../chunk-RLWM437Q.js";
+import {
+  NebutraAIConfigSchema
+} from "../chunk-NVPE5EDI.js";
+import {
+  models,
+  resolveModel
+} from "../chunk-5JZJ5KMC.js";
+export {
+  NebutraAIConfigSchema,
+  configure,
+  createEmbeddingModel,
+  createModel,
+  embed,
+  embedMany,
+  generateText,
+  getConfig,
+  models,
+  resolveModel,
+  streamText
+};

package/dist/sdk/models.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Model presets for common Nebutra use cases.
+ *
+ * All IDs use "vendor/model" format (OpenRouter / SiliconFlow).
+ * When using direct OpenAI provider, only OpenAI models are valid.
+ * When using Vercel AI Gateway, use "provider/model" format.
+ * When using SiliconFlow, use "Vendor/Model" format (e.g. "Qwen/Qwen2.5-72B-Instruct").
+ */
+declare const models: {
+    /** High-quality reasoning — default for complex tasks */
+    readonly flagship: "anthropic/claude-sonnet-4";
+    /** Deep reasoning for architecture and research */
+    readonly reasoning: "anthropic/claude-opus-4";
+    /** Fast + cheap — chat, summaries, classification */
+    readonly fast: "anthropic/claude-haiku-4";
+    /** OpenAI flagship */
+    readonly "openai-flagship": "openai/gpt-5.4";
+    /** Google flagship */
+    readonly "google-flagship": "google/gemini-2.5-pro";
+    /** Google fast */
+    readonly "google-fast": "google/gemini-2.5-flash";
+    /** Embedding model */
+    readonly embedding: "openai/text-embedding-3-small";
+    /** Embedding model (high-dimensional) */
+    readonly "embedding-large": "openai/text-embedding-3-large";
+    /** SiliconFlow — Qwen 2.5 72B (flagship open-source) */
+    readonly "sf-qwen": "Qwen/Qwen2.5-72B-Instruct";
+    /** SiliconFlow — DeepSeek R1 reasoning (via SiliconFlow Pro) */
+    readonly "sf-deepseek-r1": "Pro/deepseek-ai/DeepSeek-R1";
+    /** SiliconFlow — DeepSeek V3 (fast, capable) */
+    readonly "sf-deepseek-v3": "deepseek-ai/DeepSeek-V3";
+};
+type ModelPreset = keyof typeof models;
+/**
+ * Resolves a model preset alias to its full model ID.
+ * If the input is not a preset key, returns it as-is (passthrough).
+ */
+declare function resolveModel(modelOrPreset: string): string;
+
+export { type ModelPreset, models, resolveModel };

package/dist/sdk/models.js

@@ -0,0 +1,8 @@
+import {
+  models,
+  resolveModel
+} from "../chunk-5JZJ5KMC.js";
+export {
+  models,
+  resolveModel
+};

package/dist/sdk/provider.d.ts

@@ -0,0 +1,21 @@
+import { EmbeddingModel, LanguageModel } from 'ai';
+import { ResolvedNebutraAIConfig } from './config.js';
+import 'zod';
+
+/**
+ * Creates a language model instance based on the resolved config.
+ *
+ * Provider routing:
+ * - "openrouter"   → @openrouter/ai-sdk-provider (300+ models, failover)
+ * - "openai"       → @ai-sdk/openai (direct OpenAI API)
+ * - "siliconflow"  → @ai-sdk/openai with SiliconFlow baseURL (OpenAI-compatible)
+ * - "gateway"      → Vercel AI Gateway via plain model string (OIDC auth)
+ */
+declare function createModel(modelOrPreset: string, config: ResolvedNebutraAIConfig): LanguageModel;
+/**
+ * Creates an embedding model instance for vector operations.
+ * Only supported with OpenRouter provider.
+ */
+declare function createEmbeddingModel(modelOrPreset: string, config: ResolvedNebutraAIConfig): EmbeddingModel;
+
+export { createEmbeddingModel, createModel };

package/dist/sdk/provider.js

@@ -0,0 +1,10 @@
+import {
+  createEmbeddingModel,
+  createModel
+} from "../chunk-RLWM437Q.js";
+import "../chunk-NVPE5EDI.js";
+import "../chunk-5JZJ5KMC.js";
+export {
+  createEmbeddingModel,
+  createModel
+};

package/dist/tools.d.ts

@@ -0,0 +1,20 @@
+import { d as AgentTool } from './types-NtgB3pch.js';
+
+/**
+ * Built-in tool registry for agents.
+ *
+ * These are safe, tenant-scoped stubs that demonstrate the tool interface.
+ * Each tool requires configuration (API keys, vector stores, etc.) before
+ * it produces real results.
+ */
+
+/** Search the web for current information. */
+declare const webSearchTool: AgentTool;
+/** Query the tenant's database (tenant-scoped via RLS). */
+declare const databaseQueryTool: AgentTool;
+/** RAG-style knowledge base retrieval. */
+declare const knowledgeBaseTool: AgentTool;
+/** All pre-built tools. */
+declare const BUILT_IN_TOOLS: readonly AgentTool[];
+
+export { BUILT_IN_TOOLS, databaseQueryTool, knowledgeBaseTool, webSearchTool };

package/dist/tools.js

@@ -0,0 +1,12 @@
+import {
+  BUILT_IN_TOOLS,
+  databaseQueryTool,
+  knowledgeBaseTool,
+  webSearchTool
+} from "./chunk-UVL2UVVM.js";
+export {
+  BUILT_IN_TOOLS,
+  databaseQueryTool,
+  knowledgeBaseTool,
+  webSearchTool
+};

package/dist/types-NtgB3pch.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Core types for the multi-agent orchestration engine.
+ *
+ * All tenant-scoped operations require an AgentContext carrying `tenantId`.
+ * Usage tracking is emitted on every execution for downstream billing.
+ */
+interface AgentConfig {
+    /** Unique identifier for this agent */
+    readonly id: string;
+    /** Human-readable name */
+    readonly name: string;
+    /** What this agent does (used by the router for intent matching) */
+    readonly description: string;
+    /** Model identifier, e.g. "openai/gpt-5.4" or "anthropic/claude-sonnet-4.6" */
+    readonly model: string;
+    /** System prompt / instructions */
+    readonly instructions: string;
+    /** Tools this agent can invoke */
+    readonly tools?: readonly AgentTool[];
+    /** Maximum tool-loop iterations (default 20) */
+    readonly maxSteps?: number;
+    /** Memory configuration */
+    readonly memory?: MemoryConfig;
+}
+interface AgentTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    readonly execute: (input: unknown, context: AgentContext) => Promise<unknown>;
+}
+interface AgentContext {
+    readonly tenantId: string;
+    readonly userId: string;
+    readonly conversationId: string;
+    readonly metadata?: Record<string, unknown>;
+}
+interface AgentMessage {
+    readonly role: "user" | "assistant" | "system" | "tool";
+    readonly content: string;
+    readonly toolCalls?: readonly ToolCallResult[];
+    readonly timestamp: Date;
+}
+interface ToolCallResult {
+    readonly toolName: string;
+    readonly args: unknown;
+    readonly result: unknown;
+}
+interface AgentResponse {
+    readonly messages: readonly AgentMessage[];
+    readonly usage: TokenUsage;
+    readonly finishReason: string;
+    readonly agentId: string;
+}
+interface TokenUsage {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly totalTokens: number;
+}
+interface MemoryConfig {
+    readonly shortTerm?: {
+        readonly maxMessages: number;
+    };
+    readonly longTerm?: {
+        readonly enabled: boolean;
+    };
+}
+interface OrchestratorConfig {
+    readonly agents: readonly AgentConfig[];
+    readonly router?: RouterConfig;
+    readonly defaultAgentId?: string;
+}
+interface RouterConfig {
+    readonly strategy: "keyword" | "llm" | "custom";
+    readonly customRouter?: (message: string, context: AgentContext) => Promise<string>;
+}
+interface PipelineStep {
+    readonly agentId: string;
+    readonly transformInput?: (prevOutput: string) => string;
+}
+interface AgentUsageEvent {
+    readonly tenantId: string;
+    readonly userId: string;
+    readonly agentId: string;
+    readonly model: string;
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly totalTokens: number;
+    readonly durationMs: number;
+    readonly timestamp: Date;
+}
+
+export type { AgentMessage as A, MemoryConfig as M, OrchestratorConfig as O, PipelineStep as P, RouterConfig as R, TokenUsage as T, AgentContext as a, AgentResponse as b, AgentConfig as c, AgentTool as d, AgentUsageEvent as e, ToolCallResult as f };

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@nebutra/agents",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Nebutra AI runtime: multi-agent orchestration + Vercel AI SDK helpers (absorbed @nebutra/ai-sdk in 1.0.0)",
   "private": false,
-  "license": "AGPL-3.0",
+  "license": "MIT",
   "type": "module",
   "nebutra": {
     "featureId": "agents",
@@ -17,6 +17,7 @@
     "./tools": "./src/tools.ts",
     "./providers/vercel-ai": "./src/providers/vercel-ai.ts",
     "./providers/langchain": "./src/providers/langchain.ts",
+    "./generation": "./src/generation/index.ts",
     "./sdk": "./src/sdk/index.ts",
     "./sdk/config": "./src/sdk/config.ts",
     "./sdk/models": "./src/sdk/models.ts",
@@ -32,7 +33,7 @@
     "langfuse": "^3.38.20",
     "langfuse-vercel": "^3.38.20",
     "zod": "^4.3.6",
-    "@nebutra/billing": "0.1.0",
+    "@nebutra/billing": "0.1.1",
     "@nebutra/cache": "0.0.1",
     "@nebutra/logger": "0.1.0"
   },

package/src/__tests__/generation.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Image / video generation modality.
+ *
+ * Verifies the env-key-gated provider chain mirrors the LLM fallback design:
+ * deterministic mock terminal, additive real-provider priority, retryable
+ * rotation, and tenant-scoped attribution.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  _resetGenerationRegistry,
+  type GenerationContext,
+  type GenerationProvider,
+  generateImage,
+  generateVideo,
+  listGenerationProviders,
+  registerGenerationProvider,
+} from "../generation/index";
+
+const ctx: GenerationContext = {
+  tenantId: "org_test",
+  userId: "user_test",
+  conversationId: "canvas_1",
+};
+
+beforeEach(() => {
+  _resetGenerationRegistry();
+  delete process.env.GENERATION_FALLBACK_CHAIN;
+});
+afterEach(() => {
+  _resetGenerationRegistry();
+});
+
+describe("mock provider (terminal)", () => {
+  it("is always available with no secret", () => {
+    expect(listGenerationProviders("image")).toEqual(["mock"]);
+    expect(listGenerationProviders("video")).toEqual(["mock"]);
+  });
+
+  it("produces a deterministic data URI for identical input", async () => {
+    const a = await generateImage({ prompt: "a blue fox", width: 512, height: 512 }, ctx);
+    const b = await generateImage({ prompt: "a blue fox", width: 512, height: 512 }, ctx);
+    expect(a.url).toBe(b.url);
+    expect(a.url.startsWith("data:image/svg+xml;base64,")).toBe(true);
+    expect(a.width).toBe(512);
+    expect(a.providerName).toBe("mock");
+    expect(a.usage.units).toBe(1);
+  });
+
+  it("varies output by prompt", async () => {
+    const a = await generateImage({ prompt: "sunset" }, ctx);
+    const b = await generateImage({ prompt: "moonrise" }, ctx);
+    expect(a.url).not.toBe(b.url);
+  });
+
+  it("returns a poster frame + second-based units for video", async () => {
+    const v = await generateVideo({ prompt: "waves", durationSeconds: 8 }, ctx);
+    expect(v.modality).toBe("video");
+    expect(v.usage.units).toBe(8);
+  });
+});
+
+describe("env-key gating + priority", () => {
+  const realProvider: GenerationProvider = {
+    name: "fake-real",
+    envKey: "FAKE_REAL_API_KEY",
+    capabilities: ["image"],
+    async generateImage(req) {
+      return {
+        modality: "image",
+        mimeType: "image/png",
+        url: "https://example.test/real.png",
+        width: req.width ?? 1024,
+        height: req.height ?? 1024,
+        providerName: "fake-real",
+        model: "fake-real-1",
+        usage: { units: 1 },
+      };
+    },
+  };
+
+  it("hides a provider whose env key is absent", () => {
+    registerGenerationProvider(realProvider);
+    delete process.env.FAKE_REAL_API_KEY;
+    expect(listGenerationProviders("image")).toEqual(["mock"]);
+  });
+
+  it("prefers the real provider when its key is present", async () => {
+    registerGenerationProvider(realProvider);
+    process.env.FAKE_REAL_API_KEY = "x";
+    expect(listGenerationProviders("image")).toEqual(["fake-real", "mock"]);
+    const r = await generateImage({ prompt: "hi" }, ctx);
+    expect(r.providerName).toBe("fake-real");
+    delete process.env.FAKE_REAL_API_KEY;
+  });
+});
+
+describe("retryable rotation", () => {
+  it("rotates to mock when a real provider throws a retryable error", async () => {
+    registerGenerationProvider({
+      name: "flaky",
+      envKey: null,
+      capabilities: ["image"],
+      async generateImage() {
+        throw new Error("429 Too Many Requests");
+      },
+    });
+    const r = await generateImage({ prompt: "resilient" }, ctx);
+    expect(r.providerName).toBe("mock");
+  });
+});