@nebutra/agents 1.1.0 → 1.1.2

package/src/providers/langchain.ts

@@ -1,28 +0,0 @@
-/**
- * LangChain.js agent adapter — stub.
- *
- * This module intentionally throws at construction time to guide
- * developers through the required dependency installation.
- *
- * Once the packages are installed, implement the `execute()` method
- * using LangChain's AgentExecutor or the newer LangGraph approach.
- */
-
-import { BaseAgent } from "../agent";
-import type { AgentConfig } from "../types";
-
-export class LangChainAgent extends BaseAgent {
-  constructor(config: AgentConfig) {
-    super(config);
-    throw new Error(
-      [
-        "LangChain agent requires additional packages. Install:",
-        "",
-        "  pnpm add langchain @langchain/core @langchain/openai",
-        "",
-        "Then implement the execute() method in this file using",
-        "LangChain's AgentExecutor or LangGraph.",
-      ].join("\n"),
-    );
-  }
-}

package/src/providers/vercel-ai.ts

@@ -1,114 +0,0 @@
-/**
- * Vercel AI SDK agent adapter.
- *
- * Uses `streamText` from the `ai` package with tool-loop support.
- * The `ai` peer dependency is dynamically imported so the package
- * doesn't fail at require-time when the SDK is absent.
- */
-
-import { BaseAgent } from "../agent";
-import { runWithFallback, withAnthropicCacheControl } from "../fallback";
-import { buildTelemetryConfig } from "../observability";
-import type { AgentContext, AgentMessage, AgentResponse } from "../types";
-
-export class VercelAIAgent extends BaseAgent {
-  protected override async execute(
-    messages: readonly AgentMessage[],
-    context: AgentContext,
-  ): Promise<AgentResponse> {
-    // Dynamic import — avoids hard dependency on `ai`
-    const { streamText, stepCountIs, dynamicTool } = await import("ai");
-
-    type StreamTextParams = Parameters<typeof streamText>[0];
-
-    // Build AI SDK tool definitions from our AgentTool interface.
-    // We use dynamicTool() because our AgentTool uses a loose JSON Schema
-    // record type rather than a typed Zod schema.
-    const toolSet: StreamTextParams["tools"] = this.config.tools
-      ? Object.fromEntries(
-          this.config.tools.map((t) => [
-            t.name,
-            dynamicTool({
-              description: t.description,
-              inputSchema: t.inputSchema as Parameters<typeof dynamicTool>[0]["inputSchema"],
-              execute: async (args) => t.execute(args, context),
-            }),
-          ]),
-        )
-      : undefined;
-
-    // Build streamText options, conditionally including tools to satisfy
-    // exactOptionalPropertyTypes (tools must not be `undefined`).
-    //
-    // Cost optimization: stable content (system prompt + tool defs) is placed
-    // FIRST and dynamic content (user messages) LAST. This ordering is required
-    // for both Anthropic explicit prompt caching (90% discount via `cacheControl`)
-    // and OpenAI automatic caching (≥1024 token stable prefix). Reordering or
-    // mutating the system prompt invalidates the cache on every call.
-    const telemetry = buildTelemetryConfig({
-      functionId: `agent.${this.config.id}`,
-      metadata: {
-        tenantId: context.tenantId,
-        userId: context.userId,
-        sessionId: context.conversationId,
-        agentId: this.config.id,
-      },
-    });
-
-    const baseOptionsWithoutModel = {
-      system: this.config.instructions,
-      messages: messages.map((m) => ({
-        role: m.role as "user" | "assistant" | "system",
-        content: m.content,
-      })),
-      stopWhen: stepCountIs(this.config.maxSteps ?? 20),
-      // Anthropic prompt cache control on the system message — 90% cost
-      // reduction on cached prefix tokens. No-op for non-Anthropic providers.
-      providerOptions: withAnthropicCacheControl(),
-      experimental_telemetry: telemetry,
-    };
-
-    // Run through the multi-provider fallback chain. The chain is filtered
-    // to providers with API keys present (so single-provider deploys are
-    // backward-compatible — only the configured provider is tried).
-    const { result } = await runWithFallback(
-      async (model) => {
-        const streamOptions = {
-          ...baseOptionsWithoutModel,
-          model,
-          ...(toolSet !== undefined ? { tools: toolSet } : {}),
-        } as StreamTextParams;
-        const r = streamText(streamOptions);
-        // Materialize the result so retryable errors surface inside the
-        // try/catch in runWithFallback() rather than escaping as unhandled
-        // rejections from the lazy stream.
-        const text = await r.text;
-        const usage = await r.usage;
-        return { text, usage };
-      },
-      { model: this.config.model },
-    );
-
-    const { text, usage } = result;
-
-    // AI SDK v6 uses inputTokens/outputTokens on LanguageModelUsage
-    const inputTokens = usage?.inputTokens ?? 0;
-    const outputTokens = usage?.outputTokens ?? 0;
-
-    const responseMessages: AgentMessage[] = [
-      ...messages,
-      { role: "assistant" as const, content: text, timestamp: new Date() },
-    ];
-
-    return {
-      messages: responseMessages,
-      usage: {
-        promptTokens: inputTokens,
-        completionTokens: outputTokens,
-        totalTokens: inputTokens + outputTokens,
-      },
-      finishReason: "stop",
-      agentId: this.config.id,
-    };
-  }
-}

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;
-}