@nebutra/agents 1.1.0 → 1.1.2

package/src/generation/mock-provider.ts

@@ -1,123 +0,0 @@
-/**
- * Deterministic mock generation provider.
- *
- * Always available (`envKey: null`) so CI and flag-gated demos never need a
- * paid secret. Output is a stable, content-addressed SVG `data:` URI: the same
- * prompt + size always yields byte-identical bytes, which makes canvas
- * placement and websocket-sync tests deterministic.
- *
- * Wiring a real provider (Replicate / OpenAI images / Volces) later is purely
- * additive — register it with a non-null `envKey` and it takes priority over
- * `mock` in the fallback chain whenever its key is present.
- */
-
-import type {
-  GenerationContext,
-  GenerationProvider,
-  GenerationResult,
-  ImageGenerationRequest,
-  VideoGenerationRequest,
-} from "./types";
-
-/** FNV-1a — small, stable, no deps. Used to derive a deterministic hue. */
-function hash(input: string): number {
-  let h = 0x811c9dc5;
-  for (let i = 0; i < input.length; i++) {
-    h ^= input.charCodeAt(i);
-    h = Math.imul(h, 0x01000193);
-  }
-  return h >>> 0;
-}
-
-function escapeXml(s: string): string {
-  return s
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}
-
-function svgDataUri(label: string, prompt: string, w: number, h: number): string {
-  const hue = hash(prompt) % 360;
-  const hue2 = (hue + 40) % 360;
-  // Wrap the prompt to ~32 chars/line, max 4 lines, so the placeholder
-  // visibly carries its prompt (useful when eyeballing a canvas demo).
-  const words = prompt.split(/\s+/);
-  const lines: string[] = [];
-  let cur = "";
-  for (const word of words) {
-    if ((cur + " " + word).trim().length > 32) {
-      lines.push(cur.trim());
-      cur = word;
-    } else {
-      cur = `${cur} ${word}`;
-    }
-    if (lines.length === 4) break;
-  }
-  if (cur && lines.length < 4) lines.push(cur.trim());
-
-  const tspans = lines
-    .map((ln, i) => `<tspan x="50%" dy="${i === 0 ? 0 : 26}">${escapeXml(ln)}</tspan>`)
-    .join("");
-
-  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">
-<defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
-<stop offset="0" stop-color="hsl(${hue} 70% 55%)"/>
-<stop offset="1" stop-color="hsl(${hue2} 70% 45%)"/>
-</linearGradient></defs>
-<rect width="${w}" height="${h}" fill="url(#g)"/>
-<text x="50%" y="14%" fill="rgba(255,255,255,.7)" font-family="sans-serif" font-size="20" text-anchor="middle">${escapeXml(label)}</text>
-<text x="50%" y="46%" fill="#fff" font-family="sans-serif" font-size="22" font-weight="600" text-anchor="middle">${tspans}</text>
-</svg>`;
-
-  // base64 keeps the URI well-formed regardless of prompt characters.
-  const b64 =
-    typeof btoa === "function"
-      ? btoa(unescape(encodeURIComponent(svg)))
-      : Buffer.from(svg, "utf8").toString("base64");
-  return `data:image/svg+xml;base64,${b64}`;
-}
-
-export const mockGenerationProvider: GenerationProvider = {
-  name: "mock",
-  envKey: null,
-  capabilities: ["image", "video"],
-
-  async generateImage(
-    req: ImageGenerationRequest,
-    _ctx: GenerationContext,
-  ): Promise<GenerationResult> {
-    const width = req.width ?? 1024;
-    const height = req.height ?? 1024;
-    return {
-      modality: "image",
-      mimeType: "image/svg+xml",
-      url: svgDataUri("mock · image", req.prompt, width, height),
-      width,
-      height,
-      providerName: "mock",
-      model: req.model ?? "mock-image-1",
-      usage: { units: 1 },
-    };
-  },
-
-  async generateVideo(
-    req: VideoGenerationRequest,
-    _ctx: GenerationContext,
-  ): Promise<GenerationResult> {
-    const width = req.width ?? 1280;
-    const height = req.height ?? 720;
-    const seconds = req.durationSeconds ?? 5;
-    // No real codec in mock mode — return a poster frame the canvas can embed.
-    return {
-      modality: "video",
-      mimeType: "image/svg+xml",
-      url: svgDataUri(`mock · video · ${seconds}s`, req.prompt, width, height),
-      width,
-      height,
-      providerName: "mock",
-      model: req.model ?? "mock-video-1",
-      usage: { units: seconds },
-    };
-  },
-};

package/src/generation/types.ts

@@ -1,87 +0,0 @@
-/**
- * Image / video generation modality for `@nebutra/agents`.
- *
- * The text + embedding modalities wrap the Vercel AI SDK. Image / video
- * generation is a *new modality on the same provider layer*: providers are
- * env-key gated exactly like the LLM fallback chain (see `fallback.ts`), so
- * single-provider — or zero-provider (mock) — deploys just work.
- *
- * Generation is tenant-scoped: every call carries a {@link GenerationContext}
- * so downstream metering / audit can attribute units to an organization.
- */
-
-/** What a provider can produce. */
-export type GenerationModality = "image" | "video";
-
-/** Tenant-scoped attribution for a generation call (mirrors AgentContext). */
-export interface GenerationContext {
-  readonly tenantId: string;
-  readonly userId: string;
-  /** Optional logical grouping (e.g. a canvas / conversation id). */
-  readonly conversationId?: string;
-}
-
-export interface ImageGenerationRequest {
-  readonly prompt: string;
-  /** Pixel width — defaults to 1024. */
-  readonly width?: number;
-  /** Pixel height — defaults to 1024. */
-  readonly height?: number;
-  /** Optional model id / preset; provider-specific passthrough. */
-  readonly model?: string;
-  /** Reference images (data: URI or URL) for edit / variation flows. */
-  readonly inputImages?: readonly string[];
-}
-
-export interface VideoGenerationRequest {
-  readonly prompt: string;
-  /** Clip length in seconds — defaults to 5. */
-  readonly durationSeconds?: number;
-  readonly width?: number;
-  readonly height?: number;
-  readonly model?: string;
-  /** Optional first-frame image (data: URI or URL). */
-  readonly inputImage?: string;
-}
-
-export interface GenerationResult {
-  readonly modality: GenerationModality;
-  /** e.g. "image/svg+xml", "image/png", "video/mp4". */
-  readonly mimeType: string;
-  /** `data:` URI (mock / inline) or a remote URL the caller can fetch. */
-  readonly url: string;
-  readonly width: number;
-  readonly height: number;
-  /** Provider that actually produced the asset. */
-  readonly providerName: string;
-  /** Model id reported by the provider. */
-  readonly model: string;
-  /**
-   * Best-effort billable units for `@nebutra/metering` (e.g. 1 image,
-   * N seconds of video). Callers decide the meter mapping.
-   */
-  readonly usage: { readonly units: number };
-}
-
-/**
- * A generation backend. `envKey` mirrors the LLM provider gating: when the
- * variable is absent the provider is filtered out of the chain. `null` means
- * "always available" — reserved for the deterministic mock provider so CI and
- * flag-gated demos never need a paid secret.
- */
-export interface GenerationProvider {
-  readonly name: string;
-  readonly envKey: string | null;
-  readonly capabilities: readonly GenerationModality[];
-  generateImage?(req: ImageGenerationRequest, ctx: GenerationContext): Promise<GenerationResult>;
-  generateVideo?(req: VideoGenerationRequest, ctx: GenerationContext): Promise<GenerationResult>;
-}
-
-export interface GenerationCallOptions {
-  /**
-   * Ordered provider-name preference. Unknown / unavailable names are skipped.
-   * Defaults to `GENERATION_FALLBACK_CHAIN` env (comma-separated) then registry
-   * order, always ending at `mock` so a result is guaranteed.
-   */
-  readonly chain?: readonly string[];
-}

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