@nebutra/agents 1.1.0 → 1.1.2

package/src/context.ts

@@ -1,99 +0,0 @@
-/**
- * User context primitives — Memory-as-context layer for AI conversations.
- *
- * Inspired by Perplexity / ChatGPT "custom instructions" pattern but
- * implemented as pure helpers: this package does **not** read the database
- * (keeps `@nebutra/agents` data-layer-agnostic). The caller fetches the
- * profile and passes the structured object in.
- *
- * Usage pattern from a Next.js route:
- *
- * ```ts
- * const profile = await db.userProfile.findUnique({ where: { userId } });
- * const system = buildPersonalizedSystemPrompt(BASE_PROMPT, profile);
- * const result = await streamText(messages, { system, model: "fast" });
- * ```
- */
-
-export interface UserContext {
-  /** What the assistant should call the user. */
-  nickname?: string | null;
-  /** Job title / role — gives the model audience context. */
-  occupation?: string | null;
-  /** Free-form bio (interests, location, work focus, etc.). */
-  bio?: string | null;
-  /** Verbatim instructions that override default tone/format. */
-  customInstructions?: string | null;
-}
-
-const MAX_BIO_CHARS = 2000;
-const MAX_INSTRUCTIONS_CHARS = 3000;
-const MAX_OCCUPATION_CHARS = 120;
-const MAX_NICKNAME_CHARS = 80;
-
-/**
- * Truthy check that treats empty strings as "no context".
- */
-function present(value: string | null | undefined): value is string {
-  return typeof value === "string" && value.trim().length > 0;
-}
-
-/**
- * Truncate to a hard byte budget — defensive against runaway DB rows.
- */
-function clamp(value: string, max: number): string {
-  return value.length > max ? `${value.slice(0, max)}…` : value;
-}
-
-/**
- * Renders a `UserContext` as a compact block to inject into a system prompt.
- *
- * Output is null when no field is set, so callers can skip the entire
- * "About the user" preamble and avoid wasted tokens.
- */
-export function renderUserContextBlock(context: UserContext | null | undefined): string | null {
-  if (!context) return null;
-
-  const lines: string[] = [];
-
-  if (present(context.nickname)) {
-    lines.push(`- Preferred name: ${clamp(context.nickname.trim(), MAX_NICKNAME_CHARS)}`);
-  }
-  if (present(context.occupation)) {
-    lines.push(`- Role: ${clamp(context.occupation.trim(), MAX_OCCUPATION_CHARS)}`);
-  }
-  if (present(context.bio)) {
-    lines.push(`- About them: ${clamp(context.bio.trim(), MAX_BIO_CHARS)}`);
-  }
-
-  let block = "";
-  if (lines.length > 0) {
-    block += `About the user:\n${lines.join("\n")}`;
-  }
-
-  if (present(context.customInstructions)) {
-    if (block) block += "\n\n";
-    block += `The user's custom instructions (these take precedence over defaults):\n${clamp(
-      context.customInstructions.trim(),
-      MAX_INSTRUCTIONS_CHARS,
-    )}`;
-  }
-
-  return block.length > 0 ? block : null;
-}
-
-/**
- * Builds the final system prompt by prepending a personalization block to the
- * base prompt. Pure — no side effects, safe to call per-request.
- *
- * @param basePrompt - the assistant's role-defining base prompt
- * @param context    - structured user context (null/undefined disables personalization)
- */
-export function buildPersonalizedSystemPrompt(
-  basePrompt: string,
-  context: UserContext | null | undefined,
-): string {
-  const block = renderUserContextBlock(context);
-  if (!block) return basePrompt;
-  return `${block}\n\n---\n\n${basePrompt}`;
-}

package/src/fallback.ts

@@ -1,358 +0,0 @@
-/**
- * Multi-provider fallback chain + prompt-caching helpers.
- *
- * Cost & reliability primitives for production LLM workloads:
- *
- * 1. `createFallbackModel()` — picks a primary model and returns a callable
- *    that retries on retryable errors (429 / 5xx / network) by swapping to
- *    the next provider in `LLM_FALLBACK_CHAIN`.
- *
- * 2. `withCacheControl()` — annotates the system message with Anthropic
- *    `cacheControl: { type: 'ephemeral' }` for a 90% discount on cached
- *    prefix tokens. OpenAI auto-caches when the prefix is stable and ≥1024
- *    tokens — see comment in `generateWithFallback()`.
- *
- * Reference: https://sdk.vercel.ai/docs/ai-sdk-providers/anthropic#cache-control
- */
-
-import { logger } from "@nebutra/logger";
-import type { EmbeddingModel, LanguageModel, ModelMessage } from "ai";
-import { type FallbackProviderName, getAgentsEnv } from "./env";
-import { resolveModel } from "./sdk/models";
-
-// ────────────────────────────────────────────────────────────────────────────
-// Env-key lookup — used to filter the chain to providers that actually have
-// credentials present. This makes single-provider deploys "just work".
-// ────────────────────────────────────────────────────────────────────────────
-
-const ENV_KEY_BY_PROVIDER: Record<FallbackProviderName, string> = {
-  openrouter: "OPENROUTER_API_KEY",
-  anthropic: "ANTHROPIC".concat("_API_KEY"),
-  openai: "OPENAI".concat("_API_KEY"),
-};
-
-function hasProviderKey(provider: FallbackProviderName): boolean {
-  const k = ENV_KEY_BY_PROVIDER[provider];
-  return Boolean(globalThis.process?.env?.[k]);
-}
-
-/**
- * Filter a chain to providers whose API key is present in env.
- * Returns the original chain unchanged if NO providers have keys (so callers
- * still see a meaningful error rather than an empty-chain throw).
- */
-export function filterAvailableProviders(
-  chain: readonly FallbackProviderName[],
-): readonly FallbackProviderName[] {
-  const filtered = chain.filter(hasProviderKey);
-  return filtered.length > 0 ? filtered : chain;
-}
-
-// ────────────────────────────────────────────────────────────────────────────
-// Provider factory — lazy + dynamic to avoid hard dep on @ai-sdk/anthropic
-// during cold paths that don't use it.
-// ────────────────────────────────────────────────────────────────────────────
-
-// Note: this fallback chain INTENTIONALLY uses direct provider API keys
-// (OpenRouter / Anthropic / OpenAI) rather than Vercel AI Gateway OIDC.
-// Rationale: this package runs in many non-Vercel deployments (ECS, Docker,
-// self-hosted Hono) where OIDC isn't available. Apps deployed on Vercel
-// should configure provider="gateway" in NebutraAIConfig (see sdk/config.ts)
-// to route through AI Gateway with OIDC auth.
-
-async function buildModel(
-  provider: FallbackProviderName,
-  modelOrPreset: string,
-): Promise<LanguageModel> {
-  const modelId = resolveModel(modelOrPreset);
-
-  // Apps on Vercel should set provider="gateway" in NebutraAIConfig instead
-  // of using this direct-fallback chain.
-  const envKey = ENV_KEY_BY_PROVIDER[provider];
-  const apiKey = globalThis.process?.env?.[envKey];
-  if (!apiKey) throw new Error(`${envKey} missing`);
-
-  switch (provider) {
-    case "openrouter": {
-      const { createOpenRouter } = await import("@openrouter/ai-sdk-provider");
-      return createOpenRouter({ apiKey }).chat(modelId);
-    }
-    case "anthropic": {
-      const { createAnthropic } = await import("@ai-sdk/anthropic");
-      // Anthropic uses bare model IDs — strip "anthropic/" prefix from presets.
-      const anthropicModelId = modelId.startsWith("anthropic/")
-        ? modelId.slice("anthropic/".length)
-        : modelId;
-      return createAnthropic({ apiKey })(anthropicModelId);
-    }
-    case "openai": {
-      const { createOpenAI } = await import("@ai-sdk/openai");
-      // Strip "openai/" prefix.
-      const openaiModelId = modelId.startsWith("openai/")
-        ? modelId.slice("openai/".length)
-        : modelId;
-      return createOpenAI({ apiKey })(openaiModelId);
-    }
-  }
-}
-
-// ────────────────────────────────────────────────────────────────────────────
-// Retryable error classification
-// ────────────────────────────────────────────────────────────────────────────
-
-const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
-
-export function isRetryableError(error: unknown): boolean {
-  if (!error || typeof error !== "object") return false;
-  const e = error as Record<string, unknown>;
-
-  const status =
-    typeof e.statusCode === "number"
-      ? e.statusCode
-      : typeof e.status === "number"
-        ? e.status
-        : undefined;
-  if (status !== undefined && RETRYABLE_STATUS.has(status)) return true;
-
-  const code = typeof e.code === "string" ? e.code : "";
-  if (
-    code === "ECONNRESET" ||
-    code === "ETIMEDOUT" ||
-    code === "ENOTFOUND" ||
-    code === "EAI_AGAIN"
-  ) {
-    return true;
-  }
-
-  // AI SDK APICallError / network errors expose `.isRetryable`
-  if (e.isRetryable === true) return true;
-
-  return false;
-}
-
-// ────────────────────────────────────────────────────────────────────────────
-// Resolved fallback model — try chain in order
-// ────────────────────────────────────────────────────────────────────────────
-
-export interface FallbackResult<T> {
-  result: T;
-  provider: FallbackProviderName;
-  attempts: number;
-}
-
-export interface CreateFallbackModelOptions {
-  /** Override the default chain from env. */
-  chain?: readonly FallbackProviderName[];
-  /** Model preset / id passed to each provider in the chain. */
-  model?: string;
-  /**
-   * If true (default), filter the chain to providers whose API key is present
-   * in env. Set false to keep the original chain (caller wants to surface
-   * "missing key" errors as fallback steps — useful for tests).
-   */
-  filterAvailable?: boolean;
-}
-
-/**
- * Run an AI SDK call against the configured fallback chain.
- *
- * The caller provides an `invoke(model)` function — usually a closure over
- * `streamText` or `generateText` — and `runWithFallback` walks the chain,
- * trying each provider in order until one succeeds or the chain is exhausted.
- */
-export async function runWithFallback<T>(
-  invoke: (model: LanguageModel) => Promise<T>,
-  options: CreateFallbackModelOptions = {},
-): Promise<FallbackResult<T>> {
-  const env = getAgentsEnv();
-  const rawChain = options.chain ?? env.LLM_FALLBACK_CHAIN;
-  const chain = options.filterAvailable === false ? rawChain : filterAvailableProviders(rawChain);
-  const model = options.model ?? "flagship";
-
-  let lastError: unknown;
-  let attempts = 0;
-
-  for (const provider of chain) {
-    attempts += 1;
-    try {
-      const lm = await buildModel(provider, model);
-      const result = await invoke(lm);
-      if (attempts > 1) {
-        logger.info("LLM fallback succeeded", { provider, attempts });
-      }
-      return { result, provider, attempts };
-    } catch (error) {
-      lastError = error;
-
-      // Non-retryable: surface the original error immediately.
-      if (!isRetryableError(error)) {
-        logger.error("LLM call failed (non-retryable)", { provider, error });
-        throw error;
-      }
-
-      logger.warn("LLM provider failed — trying next in chain", {
-        provider,
-        nextIndex: attempts,
-        error,
-      });
-    }
-  }
-
-  throw new Error(
-    `All LLM providers in fallback chain [${chain.join(", ")}] failed. ` +
-      `Last error: ${String(lastError)}`,
-  );
-}
-
-// ────────────────────────────────────────────────────────────────────────────
-// Prompt-caching helper
-// ────────────────────────────────────────────────────────────────────────────
-
-/**
- * Build `providerOptions` that enable prompt caching across providers.
- *
- * - Anthropic: explicit `cacheControl: { type: 'ephemeral' }` on the system
- *   message — 90% cost reduction on cached prefix tokens.
- * - OpenAI: prompt caching is AUTOMATIC for prompts ≥1024 tokens with a
- *   stable prefix. No flag needed — but callers MUST keep the system prompt
- *   + tools FIRST and dynamic user content LAST, otherwise the cache is
- *   invalidated on every call.
- * - OpenRouter: passes provider options through transparently.
- */
-export function withAnthropicCacheControl(): {
-  anthropic: { cacheControl: { type: "ephemeral" } };
-} {
-  return {
-    anthropic: { cacheControl: { type: "ephemeral" } },
-  };
-}
-
-/**
- * Wraps the system message in a structured cache-control hint.
- * Returns the messages array unchanged if no system text is provided.
- *
- * IMPORTANT: keep stable content (system prompt + tool defs) FIRST,
- * dynamic content (user query) LAST — required for both Anthropic explicit
- * caching AND OpenAI automatic caching to hit.
- */
-export function buildSystemWithCache(systemPrompt: string): {
-  role: "system";
-  content: string;
-  providerOptions: ReturnType<typeof withAnthropicCacheControl>;
-} {
-  return {
-    role: "system",
-    content: systemPrompt,
-    providerOptions: withAnthropicCacheControl(),
-  };
-}
-
-// ────────────────────────────────────────────────────────────────────────────
-// Embedding fallback — separate chain since not every chat provider exposes
-// embeddings (Anthropic notably does not).
-// ────────────────────────────────────────────────────────────────────────────
-
-/** Providers that currently expose embedding models via the AI SDK. */
-const EMBEDDING_CAPABLE: ReadonlySet<FallbackProviderName> = new Set<FallbackProviderName>([
-  "openrouter",
-  "openai",
-]);
-
-async function buildEmbeddingModel(
-  provider: FallbackProviderName,
-  modelOrPreset: string,
-): Promise<EmbeddingModel> {
-  const modelId = resolveModel(modelOrPreset);
-  const envKey = ENV_KEY_BY_PROVIDER[provider];
-  const apiKey = globalThis.process?.env?.[envKey];
-  if (!apiKey) throw new Error(`${envKey} missing`);
-
-  switch (provider) {
-    case "openrouter": {
-      const { createOpenRouter } = await import("@openrouter/ai-sdk-provider");
-      return createOpenRouter({ apiKey }).textEmbeddingModel(modelId);
-    }
-    case "openai": {
-      const { createOpenAI } = await import("@ai-sdk/openai");
-      const openaiModelId = modelId.startsWith("openai/")
-        ? modelId.slice("openai/".length)
-        : modelId;
-      return createOpenAI({ apiKey }).textEmbeddingModel(openaiModelId);
-    }
-    case "anthropic": {
-      throw new Error("Anthropic does not expose embedding models");
-    }
-  }
-}
-
-export interface EmbeddingFallbackOptions {
-  chain?: readonly FallbackProviderName[];
-  model?: string;
-  filterAvailable?: boolean;
-}
-
-/**
- * Run an AI SDK embedding call against the configured embedding fallback chain.
- *
- * The caller provides an `invoke(model)` function — usually a closure over
- * `embed` or `embedMany` from the `ai` package — and this helper walks the
- * embedding-capable chain, trying each provider until one succeeds.
- */
-export async function runEmbedWithFallback<T>(
-  invoke: (model: EmbeddingModel) => Promise<T>,
-  options: EmbeddingFallbackOptions = {},
-): Promise<FallbackResult<T>> {
-  const env = getAgentsEnv();
-  const rawChain = options.chain ?? env.LLM_EMBEDDING_FALLBACK_CHAIN;
-
-  // Filter to providers that (a) expose embeddings and (b) have keys present.
-  const capable = rawChain.filter((p) => EMBEDDING_CAPABLE.has(p));
-  const chain = options.filterAvailable === false ? capable : capable.filter(hasProviderKey);
-
-  if (chain.length === 0) {
-    logger.warn("Embedding fallback chain is empty after filtering", {
-      raw: rawChain,
-      capable,
-    });
-    throw new Error(
-      "No embedding-capable providers available — set OPENROUTER_API_KEY or " +
-        "OPENAI_API_KEY (Anthropic does not expose embedding models).",
-    );
-  }
-
-  const model = options.model ?? "embedding";
-  let lastError: unknown;
-  let attempts = 0;
-
-  for (const provider of chain) {
-    attempts += 1;
-    try {
-      const em = await buildEmbeddingModel(provider, model);
-      const result = await invoke(em);
-      if (attempts > 1) {
-        logger.info("Embedding fallback succeeded", { provider, attempts });
-      }
-      return { result, provider, attempts };
-    } catch (error) {
-      lastError = error;
-
-      if (!isRetryableError(error)) {
-        logger.error("Embedding call failed (non-retryable)", { provider, error });
-        throw error;
-      }
-
-      logger.warn("Embedding provider failed — trying next in chain", {
-        provider,
-        nextIndex: attempts,
-        error,
-      });
-    }
-  }
-
-  throw new Error(
-    `All embedding providers in fallback chain [${chain.join(", ")}] failed. ` +
-      `Last error: ${String(lastError)}`,
-  );
-}
-
-export type { ModelMessage };

package/src/generation/index.ts

@@ -1,157 +0,0 @@
-/**
- * Image / video generation modality — public surface.
- *
- * Mirrors the LLM fallback design (`fallback.ts`): an ordered provider chain,
- * filtered to providers whose `envKey` is present, with `mock` as the
- * guaranteed terminal so a result is always produced. Retryable failures
- * (429 / 5xx / network) rotate to the next provider via `isRetryableError`.
- */
-
-import { logger } from "@nebutra/logger";
-import { isRetryableError } from "../fallback";
-import { mockGenerationProvider } from "./mock-provider";
-import type {
-  GenerationCallOptions,
-  GenerationContext,
-  GenerationModality,
-  GenerationProvider,
-  GenerationResult,
-  ImageGenerationRequest,
-  VideoGenerationRequest,
-} from "./types";
-
-const log = logger.child({ module: "agents/generation" });
-
-// ── Registry ────────────────────────────────────────────────────────────────
-// `mock` is registered last and always available. Real providers register
-// ahead of it (additively) and win whenever their env key is present.
-
-const _registry = new Map<string, GenerationProvider>();
-
-export function registerGenerationProvider(provider: GenerationProvider): void {
-  _registry.set(provider.name, provider);
-}
-
-/** Test helper — restores the registry to just the mock provider. */
-export function _resetGenerationRegistry(): void {
-  _registry.clear();
-  _registry.set(mockGenerationProvider.name, mockGenerationProvider);
-}
-
-_resetGenerationRegistry();
-
-function hasEnvKey(provider: GenerationProvider): boolean {
-  if (provider.envKey === null) return true;
-  return Boolean(globalThis.process?.env?.[provider.envKey]);
-}
-
-/** Provider names available for a modality, in resolved priority order. */
-export function listGenerationProviders(
-  modality: GenerationModality,
-  options: GenerationCallOptions = {},
-): string[] {
-  const envChain = (globalThis.process?.env?.GENERATION_FALLBACK_CHAIN ?? "")
-    .split(",")
-    .map((s) => s.trim())
-    .filter(Boolean);
-  const preferred = options.chain ?? (envChain.length > 0 ? envChain : []);
-
-  // Real providers first (explicit chain wins, then registry order), `mock`
-  // is always demoted to the guaranteed terminal regardless of registry order.
-  const mockName = mockGenerationProvider.name;
-  const all = [...preferred, ..._registry.keys()];
-  const seen = new Set<string>();
-  const resolved: string[] = [];
-  for (const name of all) {
-    if (seen.has(name) || name === mockName) continue;
-    seen.add(name);
-    const provider = _registry.get(name);
-    if (!provider) continue;
-    if (!provider.capabilities.includes(modality)) continue;
-    if (!hasEnvKey(provider)) continue;
-    resolved.push(name);
-  }
-  resolved.push(mockName);
-  return resolved;
-}
-
-async function runChain(
-  modality: GenerationModality,
-  options: GenerationCallOptions,
-  ctx: GenerationContext,
-  invoke: (p: GenerationProvider) => Promise<GenerationResult>,
-): Promise<GenerationResult> {
-  const chain = listGenerationProviders(modality, options);
-  let lastErr: unknown;
-  for (const name of chain) {
-    const provider = _registry.get(name);
-    if (!provider) continue;
-    try {
-      const result = await invoke(provider);
-      log.debug("generation succeeded", {
-        provider: name,
-        modality,
-        tenantId: ctx.tenantId,
-      });
-      return result;
-    } catch (err) {
-      lastErr = err;
-      const retryable = isRetryableError(err);
-      log.warn("generation provider failed", {
-        provider: name,
-        modality,
-        retryable,
-        tenantId: ctx.tenantId,
-      });
-      // Non-retryable from the terminal mock would be a real bug — surface it.
-      if (!retryable && name !== mockGenerationProvider.name) continue;
-      if (!retryable) throw err;
-    }
-  }
-  throw lastErr instanceof Error
-    ? lastErr
-    : new Error("[@nebutra/agents] generation chain exhausted");
-}
-
-/**
- * Generate an image. Always resolves (falls back to the deterministic mock).
- */
-export async function generateImage(
-  req: ImageGenerationRequest,
-  ctx: GenerationContext,
-  options: GenerationCallOptions = {},
-): Promise<GenerationResult> {
-  return runChain("image", options, ctx, (p) => {
-    if (!p.generateImage) {
-      throw new Error(`[@nebutra/agents] provider "${p.name}" lacks image support`);
-    }
-    return p.generateImage(req, ctx);
-  });
-}
-
-/**
- * Generate a video (or, in mock mode, a deterministic poster frame).
- */
-export async function generateVideo(
-  req: VideoGenerationRequest,
-  ctx: GenerationContext,
-  options: GenerationCallOptions = {},
-): Promise<GenerationResult> {
-  return runChain("video", options, ctx, (p) => {
-    if (!p.generateVideo) {
-      throw new Error(`[@nebutra/agents] provider "${p.name}" lacks video support`);
-    }
-    return p.generateVideo(req, ctx);
-  });
-}
-
-export { mockGenerationProvider } from "./mock-provider";
-export type {
-  GenerationCallOptions,
-  GenerationContext,
-  GenerationModality,
-  GenerationProvider,
-  GenerationResult,
-  ImageGenerationRequest,
-  VideoGenerationRequest,
-} from "./types";