@nebutra/agents 1.1.1 → 1.1.2

package/src/index.ts

@@ -1,104 +0,0 @@
-// ─── Core ─────────────────────────────────────────────────────────────────────
-export { BaseAgent } from "./agent";
-// ─── User context (personalization) ───────────────────────────────────────────
-export {
-  buildPersonalizedSystemPrompt,
-  renderUserContextBlock,
-  type UserContext,
-} from "./context";
-// ─── Env / Observability / Fallback ─────────────────────────────────────────
-export {
-  type AgentsEnv,
-  AgentsEnvSchema,
-  type FallbackProviderName,
-  getAgentsEnv,
-  isLangfuseConfigured,
-} from "./env";
-export {
-  buildSystemWithCache,
-  type CreateFallbackModelOptions,
-  type EmbeddingFallbackOptions,
-  type FallbackResult,
-  filterAvailableProviders,
-  isRetryableError,
-  runEmbedWithFallback,
-  runWithFallback,
-  withAnthropicCacheControl,
-} from "./fallback";
-// ─── Generation (image / video modality) ─────────────────────────────────────
-// New modality on the same env-key-gated provider layer as the LLM fallback
-// chain. `mock` is always available so CI / flag-gated demos need no secret.
-export {
-  _resetGenerationRegistry,
-  type GenerationCallOptions,
-  type GenerationContext,
-  type GenerationModality,
-  type GenerationProvider,
-  type GenerationResult,
-  generateImage,
-  generateVideo,
-  type ImageGenerationRequest,
-  listGenerationProviders,
-  mockGenerationProvider,
-  registerGenerationProvider,
-  type VideoGenerationRequest,
-} from "./generation/index";
-// ─── Memory ───────────────────────────────────────────────────────────────────
-export { clearMemory, getMemory, saveMemory } from "./memory";
-export {
-  buildTelemetryConfig,
-  flushTelemetry,
-  initLangfuse,
-  type TelemetryMetadata,
-} from "./observability";
-export { AgentOrchestrator } from "./orchestrator";
-export { AgentRouter } from "./router";
-// ─── Vercel AI SDK helpers (absorbed from @nebutra/ai-sdk) ───────────────────
-// Top-level generation, streaming and embedding helpers that wrap the Vercel
-// AI SDK (`ai` package) with a single configure()-driven provider resolver.
-export {
-  configure,
-  createEmbeddingModel,
-  createModel,
-  type EmbedOptions,
-  embed,
-  embedMany,
-  type GenerateOptions,
-  type GenerateTextResult,
-  generateText,
-  getConfig,
-  type ModelMessage,
-  type ModelPreset,
-  models,
-  type NebutraAIConfig,
-  NebutraAIConfigSchema,
-  type ProviderType,
-  type ResolvedNebutraAIConfig,
-  resolveModel,
-  type StreamTextResult,
-  streamText,
-} from "./sdk/index";
-// ─── Tenant ───────────────────────────────────────────────────────────────────
-export { checkAgentQuota, createAgentContext } from "./tenant";
-// ─── Tools ────────────────────────────────────────────────────────────────────
-export {
-  BUILT_IN_TOOLS,
-  databaseQueryTool,
-  knowledgeBaseTool,
-  webSearchTool,
-} from "./tools";
-// ─── Types ────────────────────────────────────────────────────────────────────
-export type {
-  AgentConfig,
-  AgentContext,
-  AgentMessage,
-  AgentResponse,
-  AgentTool,
-  AgentUsageEvent,
-  MemoryConfig,
-  OrchestratorConfig,
-  PipelineStep,
-  RouterConfig,
-  TokenUsage,
-  ToolCallResult,
-} from "./types";

package/src/memory.ts

@@ -1,126 +0,0 @@
-/**
- * Agent memory — Redis-backed per-tenant conversation persistence.
- *
- * Key format: `agent:memory:{tenantId}:{conversationId}`
- * TTL: 7 days (configurable via AGENT_MEMORY_TTL_SECONDS env var).
- *
- * Graceful degradation: if Redis is unavailable, functions return
- * empty arrays / silently skip writes so agents still work in
- * in-memory-only mode.
- */
-
-import { logger } from "@nebutra/logger";
-import type { AgentMessage } from "./types";
-
-const DEFAULT_TTL_SECONDS = 7 * 24 * 60 * 60; // 7 days
-
-function getTtl(): number {
-  const envTtl = process.env.AGENT_MEMORY_TTL_SECONDS;
-  if (envTtl) {
-    const parsed = Number.parseInt(envTtl, 10);
-    if (!Number.isNaN(parsed) && parsed > 0) {
-      return parsed;
-    }
-  }
-  return DEFAULT_TTL_SECONDS;
-}
-
-function memoryKey(tenantId: string, conversationId: string): string {
-  return `agent:memory:${tenantId}:${conversationId}`;
-}
-
-/**
- * Lazily resolve Redis. Returns null when Redis is not configured
- * so callers can gracefully degrade.
- */
-async function tryGetRedis() {
-  try {
-    const { getRedis } = await import("@nebutra/cache");
-    return getRedis();
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Load conversation history from Redis.
- * Returns an empty array when Redis is unavailable.
- */
-export async function getMemory(tenantId: string, conversationId: string): Promise<AgentMessage[]> {
-  const redis = await tryGetRedis();
-  if (!redis) return [];
-
-  try {
-    const raw = await redis.get<string>(memoryKey(tenantId, conversationId));
-    if (!raw) return [];
-
-    const parsed: unknown = typeof raw === "string" ? JSON.parse(raw) : raw;
-    if (!Array.isArray(parsed)) return [];
-
-    return parsed.map((m: Record<string, unknown>): AgentMessage => {
-      const toolCalls = m.toolCalls;
-      if (Array.isArray(toolCalls) && toolCalls.length > 0) {
-        return {
-          role: m.role as AgentMessage["role"],
-          content: String(m.content ?? ""),
-          toolCalls: toolCalls as unknown as NonNullable<AgentMessage["toolCalls"]>,
-          timestamp: new Date(String(m.timestamp)),
-        };
-      }
-      return {
-        role: m.role as AgentMessage["role"],
-        content: String(m.content ?? ""),
-        timestamp: new Date(String(m.timestamp)),
-      };
-    });
-  } catch (error) {
-    logger.warn("Failed to load agent memory, falling back to empty", {
-      tenantId,
-      conversationId,
-      error,
-    });
-    return [];
-  }
-}
-
-/**
- * Persist messages to Redis with TTL.
- * Silently skips when Redis is unavailable.
- */
-export async function saveMemory(
-  tenantId: string,
-  conversationId: string,
-  messages: readonly AgentMessage[],
-): Promise<void> {
-  const redis = await tryGetRedis();
-  if (!redis) return;
-
-  try {
-    const key = memoryKey(tenantId, conversationId);
-    await redis.set(key, JSON.stringify(messages), { ex: getTtl() });
-  } catch (error) {
-    logger.warn("Failed to save agent memory", {
-      tenantId,
-      conversationId,
-      error,
-    });
-  }
-}
-
-/**
- * Clear conversation memory for a tenant/conversation pair.
- */
-export async function clearMemory(tenantId: string, conversationId: string): Promise<void> {
-  const redis = await tryGetRedis();
-  if (!redis) return;
-
-  try {
-    await redis.del(memoryKey(tenantId, conversationId));
-  } catch (error) {
-    logger.warn("Failed to clear agent memory", {
-      tenantId,
-      conversationId,
-      error,
-    });
-  }
-}

package/src/observability.ts

@@ -1,102 +0,0 @@
-/**
- * LLM observability via Langfuse.
- *
- * - No-op when env vars are missing — the package works with zero config.
- * - Exposes `experimental_telemetry` settings ready to plug into Vercel AI SDK.
- * - Use `LangfuseExporter` from `langfuse-vercel` in your OTEL NodeSDK setup
- *   for full trace export (see README).
- */
-
-import { logger } from "@nebutra/logger";
-import { getAgentsEnv, isLangfuseConfigured } from "./env";
-
-// `Langfuse` client is dynamically imported so the package starts up
-// without telemetry deps when they are not used.
-type LangfuseClient = {
-  trace: (input: unknown) => unknown;
-  flushAsync: () => Promise<void>;
-  shutdownAsync: () => Promise<void>;
-};
-
-let _client: LangfuseClient | null | undefined;
-
-/**
- * Returns a configured `Langfuse` client, or `null` when env is missing.
- *
- * Telemetry is OPTIONAL. If LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY are
- * not set, this returns null (no error). Callers must handle the null case.
- */
-export async function initLangfuse(): Promise<LangfuseClient | null> {
-  if (_client !== undefined) return _client;
-
-  if (!isLangfuseConfigured()) {
-    _client = null;
-    return null;
-  }
-
-  try {
-    const env = getAgentsEnv();
-    const { Langfuse } = await import("langfuse");
-    _client = new Langfuse({
-      publicKey: env.LANGFUSE_PUBLIC_KEY!,
-      secretKey: env.LANGFUSE_SECRET_KEY!,
-      baseUrl: env.LANGFUSE_HOST,
-    }) as unknown as LangfuseClient;
-    logger.info("Langfuse telemetry enabled", { host: env.LANGFUSE_HOST });
-    return _client;
-  } catch (error) {
-    logger.warn("Failed to initialise Langfuse — telemetry disabled", { error });
-    _client = null;
-    return null;
-  }
-}
-
-/** Test helper — clears cached client so subsequent init() re-reads env. */
-export function _resetLangfuseCache(): void {
-  _client = undefined;
-}
-
-export interface TelemetryMetadata {
-  tenantId?: string | undefined;
-  userId?: string | undefined;
-  sessionId?: string | undefined;
-  agentId?: string | undefined;
-  [key: string]: unknown;
-}
-
-/**
- * Build the `experimental_telemetry` option for AI SDK calls.
- * Returns `{ isEnabled: false }` (a safe no-op) when Langfuse is not configured,
- * which avoids any OTEL span creation cost.
- */
-export function buildTelemetryConfig(args: { functionId: string; metadata?: TelemetryMetadata }): {
-  isEnabled: boolean;
-  functionId?: string;
-  metadata?: Record<string, unknown>;
-} {
-  if (!isLangfuseConfigured()) {
-    return { isEnabled: false };
-  }
-
-  return {
-    isEnabled: true,
-    functionId: args.functionId,
-    metadata: {
-      ...(args.metadata ?? {}),
-      // Langfuse picks up these conventional keys from metadata
-      ...(args.metadata?.tenantId ? { langfuseUserId: args.metadata.tenantId } : {}),
-      ...(args.metadata?.sessionId ? { langfuseSessionId: args.metadata.sessionId } : {}),
-    },
-  };
-}
-
-/** Flush pending telemetry before process exit. Safe to call when disabled. */
-export async function flushTelemetry(): Promise<void> {
-  const client = await initLangfuse();
-  if (!client) return;
-  try {
-    await client.flushAsync();
-  } catch (error) {
-    logger.warn("Langfuse flush failed", { error });
-  }
-}

package/src/orchestrator.ts

@@ -1,147 +0,0 @@
-/**
- * AgentOrchestrator — multi-agent coordination engine.
- *
- * Supports three execution modes:
- *   - chat(): route a single message to the best agent
- *   - pipeline(): chain agents sequentially (output → next input)
- *   - broadcast(): fan-out to all agents and collect results
- */
-
-import { logger } from "@nebutra/logger";
-import { BaseAgent } from "./agent";
-import { AgentRouter } from "./router";
-import { checkAgentQuota } from "./tenant";
-import type {
-  AgentContext,
-  AgentMessage,
-  AgentResponse,
-  OrchestratorConfig,
-  PipelineStep,
-} from "./types";
-
-export class AgentOrchestrator {
-  private readonly agents: Map<string, BaseAgent>;
-  private readonly router: AgentRouter;
-  private readonly defaultAgentId: string | undefined;
-
-  constructor(config: OrchestratorConfig) {
-    this.agents = new Map();
-    this.defaultAgentId = config.defaultAgentId;
-
-    // Register agents — callers provide AgentConfig[], we wrap in BaseAgent
-    // In practice, callers will register concrete subclasses (VercelAIAgent, etc.)
-    for (const agentConfig of config.agents) {
-      this.agents.set(agentConfig.id, new BaseAgent(agentConfig));
-    }
-
-    // Set up router
-    this.router = new AgentRouter(config.router ?? { strategy: "keyword" });
-  }
-
-  /**
-   * Register a pre-built agent instance (e.g. VercelAIAgent).
-   * Overwrites any agent with the same ID.
-   */
-  registerAgent(agent: BaseAgent): void {
-    this.agents.set(agent.config.id, agent);
-  }
-
-  /**
-   * Get a registered agent by ID.
-   */
-  getAgent(agentId: string): BaseAgent | undefined {
-    return this.agents.get(agentId);
-  }
-
-  /**
-   * Route a message to the best agent and execute.
-   */
-  async chat(message: string, context: AgentContext): Promise<AgentResponse> {
-    await this.assertQuota(context.tenantId);
-
-    const agentConfigs = [...this.agents.values()].map((a) => a.config);
-    const agentId = await this.router.route(message, agentConfigs, context, this.defaultAgentId);
-
-    const agent = this.agents.get(agentId);
-    if (!agent) {
-      throw new Error(`Agent "${agentId}" not found in orchestrator`);
-    }
-
-    const messages: AgentMessage[] = [{ role: "user", content: message, timestamp: new Date() }];
-
-    return agent.run(messages, context);
-  }
-
-  /**
-   * Execute a multi-agent pipeline where each step's output feeds the next.
-   * @experimental — API may change. Use `chat()` for production workloads.
-   */
-  async pipeline(
-    steps: readonly PipelineStep[],
-    input: string,
-    context: AgentContext,
-  ): Promise<AgentResponse> {
-    await this.assertQuota(context.tenantId);
-
-    let currentInput = input;
-    let lastResponse: AgentResponse | undefined;
-
-    for (const step of steps) {
-      const agent = this.agents.get(step.agentId);
-      if (!agent) {
-        throw new Error(`Pipeline step references unknown agent "${step.agentId}"`);
-      }
-
-      const transformedInput = step.transformInput
-        ? step.transformInput(currentInput)
-        : currentInput;
-
-      const messages: AgentMessage[] = [
-        { role: "user", content: transformedInput, timestamp: new Date() },
-      ];
-
-      lastResponse = await agent.run(messages, context);
-
-      // Extract the last assistant message as input for the next step
-      const assistantMessages = lastResponse.messages.filter((m) => m.role === "assistant");
-      const lastAssistant = assistantMessages[assistantMessages.length - 1];
-      currentInput = lastAssistant?.content ?? "";
-
-      logger.info("Pipeline step completed", {
-        agentId: step.agentId,
-        tenantId: context.tenantId,
-      });
-    }
-
-    if (!lastResponse) {
-      throw new Error("Pipeline produced no response (empty steps?)");
-    }
-
-    return lastResponse;
-  }
-
-  /**
-   * Broadcast a message to ALL registered agents in parallel.
-   * Returns an array of responses (one per agent).
-   * @experimental — API may change. Use `chat()` for production workloads.
-   */
-  async broadcast(message: string, context: AgentContext): Promise<readonly AgentResponse[]> {
-    await this.assertQuota(context.tenantId);
-
-    const messages: AgentMessage[] = [{ role: "user", content: message, timestamp: new Date() }];
-
-    const promises = [...this.agents.values()].map((agent) => agent.run(messages, context));
-
-    return Promise.all(promises);
-  }
-
-  /**
-   * Check tenant quota before execution.
-   */
-  private async assertQuota(tenantId: string): Promise<void> {
-    const { allowed } = await checkAgentQuota(tenantId);
-    if (!allowed) {
-      throw new Error(`Tenant "${tenantId}" has exceeded agent execution quota`);
-    }
-  }
-}

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