@nebutra/agents 1.0.0

package/src/sdk/index.ts

@@ -0,0 +1,214 @@
+/**
+ * Top-level Vercel AI SDK helpers — absorbed from the former
+ * `@nebutra/ai-sdk` package during the AI consolidation.
+ *
+ * Public API (unchanged):
+ *   configure(), getConfig()
+ *   generateText(), streamText()
+ *   embed(), embedMany()
+ *   createModel(), createEmbeddingModel()
+ *   models, resolveModel()
+ */
+
+import {
+  embed as _embed,
+  embedMany as _embedMany,
+  generateText as _generateText,
+  streamText as _streamText,
+  type GenerateTextResult,
+  type JSONValue,
+  type ModelMessage,
+  type StreamTextResult,
+} from "ai";
+import { runEmbedWithFallback } from "../fallback";
+import {
+  type NebutraAIConfig,
+  NebutraAIConfigSchema,
+  type ResolvedNebutraAIConfig,
+} from "./config";
+import { createModel } from "./provider";
+
+// ---------------------------------------------------------------------------
+// Singleton config — call `configure()` once at app startup
+// ---------------------------------------------------------------------------
+
+let _resolved: ResolvedNebutraAIConfig = NebutraAIConfigSchema.parse({});
+
+/**
+ * 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
+ * ```
+ */
+export function configure(config: NebutraAIConfig = {}): void {
+  _resolved = NebutraAIConfigSchema.parse(config);
+}
+
+/** Returns the current resolved config (read-only). */
+export function getConfig(): Readonly<ResolvedNebutraAIConfig> {
+  return _resolved;
+}
+
+// ---------------------------------------------------------------------------
+// Core generation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ */
+export 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;
+  };
+}
+
+export 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}.
+ */
+export 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.
+ */
+export async function generateText(
+  messages: ModelMessage[],
+  options: GenerateOptions = {},
+): Promise<GenerateTextResult<Record<string, never>, never>> {
+  const model = createModel(options.model ?? _resolved.defaultModel, _resolved);
+
+  return await _generateText({
+    model,
+    messages,
+    ...(options.system ? { system: options.system } : {}),
+    temperature: options.temperature ?? _resolved.temperature,
+    ...(options.maxTokens ? { maxTokens: options.maxTokens } : {}),
+    ...(options.providerOptions
+      ? { providerOptions: { openrouter: options.providerOptions } }
+      : {}),
+  });
+}
+
+/**
+ * Stream a text response for real-time UI.
+ */
+export async function streamText(
+  messages: ModelMessage[],
+  options: StreamOptions = {},
+): Promise<StreamTextResult<Record<string, never>, never>> {
+  const model = createModel(options.model ?? _resolved.defaultModel, _resolved);
+  const userOnFinish = options.onFinish;
+
+  return _streamText({
+    model,
+    messages,
+    ...(options.system ? { system: options.system } : {}),
+    temperature: options.temperature ?? _resolved.temperature,
+    ...(options.maxTokens ? { maxTokens: options.maxTokens } : {}),
+    ...(options.providerOptions
+      ? { providerOptions: { openrouter: options.providerOptions } }
+      : {}),
+    ...(userOnFinish
+      ? {
+          onFinish: ({ text, finishReason, totalUsage }) => {
+            const event: StreamFinishEvent = {
+              text,
+              finishReason: String(finishReason),
+              usage: {
+                inputTokens: totalUsage?.inputTokens,
+                outputTokens: totalUsage?.outputTokens,
+                totalTokens: totalUsage?.totalTokens,
+              },
+            };
+            return userOnFinish(event);
+          },
+        }
+      : {}),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Embeddings
+// ---------------------------------------------------------------------------
+
+export 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`.
+ */
+export async function embed(value: string, options: EmbedOptions = {}) {
+  const { result } = await runEmbedWithFallback(async (model) => _embed({ model, value }), {
+    model: options.model ?? "embedding",
+  });
+  return result;
+}
+
+/**
+ * Generate embedding vectors for multiple values in a single request.
+ *
+ * Uses `runEmbedWithFallback()` for provider rotation on retryable errors.
+ */
+export async function embedMany(values: string[], options: EmbedOptions = {}) {
+  const { result } = await runEmbedWithFallback(async (model) => _embedMany({ model, values }), {
+    model: options.model ?? "embedding",
+  });
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+
+export type { GenerateTextResult, ModelMessage, StreamTextResult } from "ai";
+export {
+  type NebutraAIConfig,
+  NebutraAIConfigSchema,
+  type ProviderType,
+  type ResolvedNebutraAIConfig,
+} from "./config";
+export type { ModelPreset } from "./models";
+export { models, resolveModel } from "./models";
+export { createEmbeddingModel, createModel } from "./provider";

package/src/sdk/models.ts

@@ -0,0 +1,57 @@
+/**
+ * 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").
+ */
+export const models = {
+  /** High-quality reasoning — default for complex tasks */
+  flagship: "anthropic/claude-sonnet-4",
+
+  /** Deep reasoning for architecture and research */
+  reasoning: "anthropic/claude-opus-4",
+
+  /** Fast + cheap — chat, summaries, classification */
+  fast: "anthropic/claude-haiku-4",
+
+  /** OpenAI flagship */
+  "openai-flagship": "openai/gpt-5.4",
+
+  /** Google flagship */
+  "google-flagship": "google/gemini-2.5-pro",
+
+  /** Google fast */
+  "google-fast": "google/gemini-2.5-flash",
+
+  /** Embedding model */
+  embedding: "openai/text-embedding-3-small",
+
+  /** Embedding model (high-dimensional) */
+  "embedding-large": "openai/text-embedding-3-large",
+
+  // --- SiliconFlow presets (use with provider: "siliconflow") ---
+
+  /** SiliconFlow — Qwen 2.5 72B (flagship open-source) */
+  "sf-qwen": "Qwen/Qwen2.5-72B-Instruct",
+
+  /** SiliconFlow — DeepSeek R1 reasoning (via SiliconFlow Pro) */
+  "sf-deepseek-r1": "Pro/deepseek-ai/DeepSeek-R1",
+
+  /** SiliconFlow — DeepSeek V3 (fast, capable) */
+  "sf-deepseek-v3": "deepseek-ai/DeepSeek-V3",
+} as const;
+
+export 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).
+ */
+export function resolveModel(modelOrPreset: string): string {
+  if (modelOrPreset in models) {
+    return models[modelOrPreset as ModelPreset];
+  }
+  return modelOrPreset;
+}

package/src/sdk/provider.ts

@@ -0,0 +1,80 @@
+import { createOpenAI } from "@ai-sdk/openai";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import type { EmbeddingModel, LanguageModel } from "ai";
+import { type ResolvedNebutraAIConfig, resolveApiKey } from "./config";
+import { resolveModel } from "./models";
+
+/**
+ * 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)
+ */
+export function createModel(modelOrPreset: string, config: ResolvedNebutraAIConfig): LanguageModel {
+  const modelId = resolveModel(modelOrPreset);
+  const apiKey = resolveApiKey(config);
+
+  switch (config.provider) {
+    case "openrouter": {
+      const provider = createOpenRouter({
+        apiKey,
+        ...(config.headers ? { headers: config.headers } : {}),
+        ...(config.extraBody ? { extraBody: config.extraBody } : {}),
+      });
+      return provider.chat(modelId);
+    }
+
+    case "openai": {
+      const provider = createOpenAI({ apiKey });
+      return provider(modelId);
+    }
+
+    case "siliconflow": {
+      // SiliconFlow: OpenAI-compatible API with China-optimized infra
+      // Models use "Vendor/Model" format, e.g. "Qwen/Qwen2.5-72B-Instruct"
+      const provider = createOpenAI({
+        apiKey,
+        baseURL: "https://api.siliconflow.cn/v1",
+      });
+      return provider(modelId);
+    }
+
+    case "gateway": {
+      // Vercel AI Gateway: use @ai-sdk/openai with gateway baseURL
+      // OIDC token is passed as apiKey, routed through Vercel's proxy
+      const provider = createOpenAI({
+        apiKey,
+        baseURL: "https://ai-gateway.vercel.sh/v1",
+      });
+      return provider(modelId);
+    }
+  }
+}
+
+/**
+ * Creates an embedding model instance for vector operations.
+ * Only supported with OpenRouter provider.
+ */
+export function createEmbeddingModel(
+  modelOrPreset: string,
+  config: ResolvedNebutraAIConfig,
+): EmbeddingModel {
+  const modelId = resolveModel(modelOrPreset);
+  const apiKey = resolveApiKey(config);
+
+  if (config.provider !== "openrouter") {
+    throw new Error(
+      `[@nebutra/agents] Embedding models are currently only supported with the "openrouter" provider.`,
+    );
+  }
+
+  const provider = createOpenRouter({
+    apiKey,
+    ...(config.headers ? { headers: config.headers } : {}),
+  });
+
+  return provider.textEmbeddingModel(modelId);
+}

package/src/tenant.ts

@@ -0,0 +1,52 @@
+/**
+ * Tenant-scoped agent execution context.
+ *
+ * Ensures every agent operation carries tenantId for RLS,
+ * billing, and audit trail purposes.
+ */
+
+import type { AgentContext } from "./types";
+
+/**
+ * Create a fully-populated AgentContext.
+ * Generates a random conversationId when none is provided.
+ */
+export function createAgentContext(
+  tenantId: string,
+  userId: string,
+  conversationId?: string,
+  metadata?: Record<string, unknown>,
+): AgentContext {
+  return {
+    tenantId,
+    userId,
+    conversationId: conversationId ?? crypto.randomUUID(),
+    ...(metadata !== undefined ? { metadata } : {}),
+  };
+}
+
+/**
+ * Validate that a tenant has remaining quota for agent execution.
+ *
+ * Returns `{ allowed: true, remaining: -1 }` (unlimited) by default.
+ * Integrate with @nebutra/billing entitlements for production usage.
+ */
+export async function checkAgentQuota(
+  tenantId: string,
+): Promise<{ allowed: boolean; remaining: number }> {
+  try {
+    const { getCreditBalance } = await import("@nebutra/billing/credits");
+    const balance = await getCreditBalance(tenantId);
+
+    // Simple quota check: tenant must have positive credits
+    // In production, we might check plan-specific monthly limits beforehand
+    if (balance.balance > 0) {
+      return { allowed: true, remaining: balance.balance };
+    }
+
+    return { allowed: false, remaining: 0 };
+  } catch (_err) {
+    // Failsafe open if billing is unconfigured
+    return { allowed: true, remaining: -1 };
+  }
+}

package/src/tools.ts

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+
+import type { AgentTool } from "./types";
+
+/** Search the web for current information. */
+export const webSearchTool: AgentTool = {
+  name: "web_search",
+  description: "Search the web for current information",
+  inputSchema: {
+    type: "object",
+    properties: { query: { type: "string" } },
+    required: ["query"],
+  },
+  execute: async (_input, _context) => {
+    return {
+      results: [],
+      note: "Configure TAVILY_API_KEY or SERPER_API_KEY for live search",
+    };
+  },
+};
+
+/** Query the tenant's database (tenant-scoped via RLS). */
+export const databaseQueryTool: AgentTool = {
+  name: "database_query",
+  description: "Query the tenant's database",
+  inputSchema: {
+    type: "object",
+    properties: { query: { type: "string" } },
+    required: ["query"],
+  },
+  execute: async (_input, context) => {
+    return {
+      note: `Query would execute in tenant ${context.tenantId} scope`,
+    };
+  },
+};
+
+/** RAG-style knowledge base retrieval. */
+export const knowledgeBaseTool: AgentTool = {
+  name: "knowledge_base",
+  description: "Search the organization's knowledge base for relevant documents",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: { type: "string" },
+      limit: { type: "number" },
+    },
+  },
+  execute: async (_input, _context) => {
+    return { documents: [], note: "Configure vector store for RAG" };
+  },
+};
+
+/** All pre-built tools. */
+export const BUILT_IN_TOOLS: readonly AgentTool[] = [
+  webSearchTool,
+  databaseQueryTool,
+  knowledgeBaseTool,
+];

package/src/types.ts

@@ -0,0 +1,114 @@
+/**
+ * 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.
+ */
+
+// ─── Agent Configuration ──────────────────────────────────────────────────────
+
+export 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;
+}
+
+// ─── Tools ────────────────────────────────────────────────────────────────────
+
+export interface AgentTool {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: Record<string, unknown>;
+  readonly execute: (input: unknown, context: AgentContext) => Promise<unknown>;
+}
+
+// ─── Execution Context ────────────────────────────────────────────────────────
+
+export interface AgentContext {
+  readonly tenantId: string;
+  readonly userId: string;
+  readonly conversationId: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+// ─── Messages ─────────────────────────────────────────────────────────────────
+
+export interface AgentMessage {
+  readonly role: "user" | "assistant" | "system" | "tool";
+  readonly content: string;
+  readonly toolCalls?: readonly ToolCallResult[];
+  readonly timestamp: Date;
+}
+
+export interface ToolCallResult {
+  readonly toolName: string;
+  readonly args: unknown;
+  readonly result: unknown;
+}
+
+// ─── Response ─────────────────────────────────────────────────────────────────
+
+export interface AgentResponse {
+  readonly messages: readonly AgentMessage[];
+  readonly usage: TokenUsage;
+  readonly finishReason: string;
+  readonly agentId: string;
+}
+
+export interface TokenUsage {
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly totalTokens: number;
+}
+
+// ─── Memory ───────────────────────────────────────────────────────────────────
+
+export interface MemoryConfig {
+  readonly shortTerm?: { readonly maxMessages: number };
+  readonly longTerm?: { readonly enabled: boolean };
+}
+
+// ─── Orchestrator ─────────────────────────────────────────────────────────────
+
+export interface OrchestratorConfig {
+  readonly agents: readonly AgentConfig[];
+  readonly router?: RouterConfig;
+  readonly defaultAgentId?: string;
+}
+
+export interface RouterConfig {
+  readonly strategy: "keyword" | "llm" | "custom";
+  readonly customRouter?: (message: string, context: AgentContext) => Promise<string>;
+}
+
+export interface PipelineStep {
+  readonly agentId: string;
+  readonly transformInput?: (prevOutput: string) => string;
+}
+
+// ─── Usage / Billing ──────────────────────────────────────────────────────────
+
+export 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;
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "esnext",
+    "types": ["node"],
+    "incremental": false
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: [
+    "src/index.ts",
+    "src/tools.ts",
+    "src/providers/vercel-ai.ts",
+    "src/providers/langchain.ts",
+    "src/sdk/index.ts",
+    "src/sdk/config.ts",
+    "src/sdk/models.ts",
+    "src/sdk/provider.ts",
+  ],
+  format: ["esm"],
+  dts: true,
+  clean: true,
+  target: "node20",
+  outDir: "dist",
+  splitting: true,
+  external: ["ai", "@nebutra/logger", "@nebutra/cache", "@nebutra/billing"],
+});