@nebutra/agents 1.1.1 → 2.0.0

package/src/router.ts

@@ -1,158 +0,0 @@
-/**
- * AgentRouter — routes incoming messages to the appropriate agent.
- *
- * Strategies:
- *   - keyword: fast, pattern-based matching against agent descriptions
- *   - llm: uses a small model to classify intent (requires AI SDK)
- *   - custom: user-supplied routing function
- */
-
-import { logger } from "@nebutra/logger";
-import type { AgentConfig, AgentContext, RouterConfig } from "./types";
-
-export class AgentRouter {
-  private readonly config: RouterConfig;
-
-  constructor(config: RouterConfig) {
-    this.config = config;
-  }
-
-  /**
-   * Route a message to the best-matching agent.
-   * Returns the agent ID.
-   */
-  async route(
-    message: string,
-    agents: readonly AgentConfig[],
-    context: AgentContext,
-    defaultAgentId?: string,
-  ): Promise<string> {
-    if (agents.length === 0) {
-      throw new Error("No agents configured in the orchestrator");
-    }
-
-    const fallback = defaultAgentId ?? agents[0]?.id;
-    if (!fallback) {
-      throw new Error("No agents configured in the orchestrator");
-    }
-    switch (this.config.strategy) {
-      case "keyword":
-        return this.routeByKeyword(message, agents, defaultAgentId) ?? fallback;
-      case "llm":
-        return (await this.routeByLLM(message, agents, defaultAgentId)) ?? fallback;
-      case "custom":
-        return this.routeByCustom(message, context, defaultAgentId);
-      default: {
-        const _exhaustive: never = this.config.strategy;
-        throw new Error(`Unknown routing strategy: ${String(_exhaustive)}`);
-      }
-    }
-  }
-
-  /**
-   * Keyword-based routing: score each agent by how many words from
-   * its name + description appear in the user message.
-   */
-  private routeByKeyword(
-    message: string,
-    agents: readonly AgentConfig[],
-    defaultAgentId?: string,
-  ): string | undefined {
-    const messageLower = message.toLowerCase();
-    let bestId = defaultAgentId ?? agents[0]?.id;
-    let bestScore = 0;
-
-    for (const agent of agents) {
-      const keywords = `${agent.name} ${agent.description}`.toLowerCase().split(/\s+/);
-
-      let score = 0;
-      for (const keyword of keywords) {
-        if (keyword.length > 2 && messageLower.includes(keyword)) {
-          score += 1;
-        }
-      }
-
-      if (score > bestScore) {
-        bestScore = score;
-        bestId = agent.id;
-      }
-    }
-
-    logger.info("Router: keyword match", {
-      selectedAgentId: bestId,
-      score: bestScore,
-    });
-    return bestId;
-  }
-
-  /**
-   * LLM-based routing: uses a small model to classify the user's intent
-   * and select the best agent. Falls back to keyword if AI SDK unavailable.
-   */
-  private async routeByLLM(
-    message: string,
-    agents: readonly AgentConfig[],
-    defaultAgentId?: string,
-  ): Promise<string | undefined> {
-    try {
-      const { generateText } = await import("ai");
-
-      const agentList = agents.map((a) => `- ${a.id}: ${a.description}`).join("\n");
-
-      const result = await generateText({
-        model: agents[0]?.model as unknown as Parameters<typeof generateText>[0]["model"],
-        system: [
-          "You are a routing classifier. Given a user message and a list of agents,",
-          "respond with ONLY the agent ID that best matches the user's intent.",
-          "If no agent is a good match, respond with the default agent ID.",
-          "",
-          `Available agents:\n${agentList}`,
-          "",
-          defaultAgentId ? `Default agent: ${defaultAgentId}` : "",
-        ].join("\n"),
-        messages: [{ role: "user" as const, content: message }],
-      });
-
-      const selectedId = result.text.trim();
-      const validAgent = agents.find((a) => a.id === selectedId);
-
-      if (validAgent) {
-        logger.info("Router: LLM classification", {
-          selectedAgentId: validAgent.id,
-        });
-        return validAgent.id;
-      }
-
-      // LLM returned an invalid ID — fall back
-      return defaultAgentId ?? agents[0]?.id;
-    } catch (error) {
-      logger.warn("Router: LLM routing failed, falling back to keyword", {
-        error,
-      });
-      return this.routeByKeyword(message, agents, defaultAgentId);
-    }
-  }
-
-  /**
-   * Custom routing via user-supplied function.
-   */
-  private async routeByCustom(
-    message: string,
-    context: AgentContext,
-    defaultAgentId?: string,
-  ): Promise<string> {
-    if (!this.config.customRouter) {
-      throw new Error(
-        'RouterConfig strategy is "custom" but no customRouter function was provided',
-      );
-    }
-
-    try {
-      return await this.config.customRouter(message, context);
-    } catch (error) {
-      logger.warn("Router: custom router failed", { error });
-      if (defaultAgentId) return defaultAgentId;
-      throw error;
-    }
-  }
-}

package/src/sdk/config.ts

@@ -1,73 +0,0 @@
-/**
- * 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.
- */
-
-import { z } from "zod";
-
-/**
- * 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)
- */
-export const ProviderType = z.enum(["openrouter", "openai", "siliconflow", "gateway"]);
-export type ProviderType = z.infer<typeof ProviderType>;
-
-export const NebutraAIConfigSchema = z.object({
-  /** Which provider backend to use. Defaults to "openrouter". */
-  provider: ProviderType.default("openrouter"),
-
-  /** API key override. Falls back to env vars per provider. */
-  apiKey: z.string().optional(),
-
-  /** Default model identifier. Provider-specific format. */
-  defaultModel: z.string().default("anthropic/claude-sonnet-4"),
-
-  /** Default temperature for generations. */
-  temperature: z.number().min(0).max(2).default(0.7),
-
-  /** Default max tokens for output. */
-  maxTokens: z.number().int().positive().optional(),
-
-  /** Extra headers merged into every request (e.g. HTTP-Referer for OpenRouter). */
-  headers: z.record(z.string(), z.string()).optional(),
-
-  /** Extra body fields merged into every request. */
-  extraBody: z.record(z.string(), z.unknown()).optional(),
-});
-
-export type NebutraAIConfig = z.input<typeof NebutraAIConfigSchema>;
-export type ResolvedNebutraAIConfig = z.output<typeof NebutraAIConfigSchema>;
-
-/**
- * Resolves the API key from explicit config or environment variables.
- */
-export function resolveApiKey(config: ResolvedNebutraAIConfig): string {
-  if (config.apiKey) return config.apiKey;
-
-  const envMap: Record<ProviderType, string> = {
-    openrouter: "OPENROUTER_API_KEY",
-    openai: "OPENAI_API_KEY",
-    siliconflow: "SILICONFLOW_API_KEY",
-    gateway: "VERCEL_OIDC_TOKEN",
-  };
-
-  const envVar = envMap[config.provider];
-
-  const value = globalThis.process?.env?.[envVar];
-
-  if (!value) {
-    throw new Error(
-      `[@nebutra/agents] Missing API key. Set "${envVar}" in environment or pass "apiKey" in config.`,
-    );
-  }
-
-  return value;
-}

package/src/sdk/index.ts

@@ -1,214 +0,0 @@
-/**
- * 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

@@ -1,57 +0,0 @@
-/**
- * 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

@@ -1,80 +0,0 @@
-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

@@ -1,52 +0,0 @@
-/**
- * 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

@@ -1,65 +0,0 @@
-/**
- * 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,
-];