@nebutra/agents 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,476 @@
+import { B as BaseAgent } from './agent-CahnMASx.js';
+import { z } from 'zod';
+import { EmbeddingModel, LanguageModel } from 'ai';
+export { GenerateTextResult, ModelMessage, StreamTextResult } from 'ai';
+import { A as AgentMessage, O as OrchestratorConfig, a as AgentContext, b as AgentResponse, P as PipelineStep, R as RouterConfig, c as AgentConfig } from './types-NtgB3pch.js';
+export { d as AgentTool, e as AgentUsageEvent, M as MemoryConfig, T as TokenUsage, f as ToolCallResult } from './types-NtgB3pch.js';
+export { EmbedOptions, GenerateOptions, configure, embed, embedMany, generateText, getConfig, streamText } from './sdk/index.js';
+export { BUILT_IN_TOOLS, databaseQueryTool, knowledgeBaseTool, webSearchTool } from './tools.js';
+export { ModelPreset, models, resolveModel } from './sdk/models.js';
+export { NebutraAIConfig, NebutraAIConfigSchema, ProviderType, ResolvedNebutraAIConfig } from './sdk/config.js';
+export { createEmbeddingModel, createModel } from './sdk/provider.js';
+
+/**
+ * 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" });
+ * ```
+ */
+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;
+}
+/**
+ * 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.
+ */
+declare function renderUserContextBlock(context: UserContext | null | undefined): string | 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)
+ */
+declare function buildPersonalizedSystemPrompt(basePrompt: string, context: UserContext | null | undefined): string;
+
+/**
+ * Environment validation for `@nebutra/agents`.
+ *
+ * All variables are OPTIONAL — the package must work with zero new env config.
+ * Provider keys (OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
+ * are validated lazily by the provider resolver, not here.
+ */
+
+/** Comma-separated provider chain. Order = priority. */
+declare const FallbackProviderName: z.ZodEnum<{
+    openrouter: "openrouter";
+    anthropic: "anthropic";
+    openai: "openai";
+}>;
+type FallbackProviderName = z.infer<typeof FallbackProviderName>;
+declare const AgentsEnvSchema: z.ZodObject<{
+    ANTHROPIC_API_KEY: z.ZodOptional<z.ZodString>;
+    LANGFUSE_PUBLIC_KEY: z.ZodOptional<z.ZodString>;
+    LANGFUSE_SECRET_KEY: z.ZodOptional<z.ZodString>;
+    LANGFUSE_HOST: z.ZodDefault<z.ZodString>;
+    LLM_FALLBACK_CHAIN: z.ZodDefault<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, z.ZodArray<z.ZodEnum<{
+        openrouter: "openrouter";
+        anthropic: "anthropic";
+        openai: "openai";
+    }>>>>;
+    LLM_EMBEDDING_FALLBACK_CHAIN: z.ZodDefault<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, z.ZodArray<z.ZodEnum<{
+        openrouter: "openrouter";
+        anthropic: "anthropic";
+        openai: "openai";
+    }>>>>;
+}, z.core.$strip>;
+type AgentsEnv = z.infer<typeof AgentsEnvSchema>;
+/** Returns the validated env (cached). Safe to call from any runtime. */
+declare function getAgentsEnv(): AgentsEnv;
+/** True iff Langfuse credentials are present. */
+declare function isLangfuseConfigured(): boolean;
+
+/**
+ * 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
+ */
+
+/**
+ * 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).
+ */
+declare function filterAvailableProviders(chain: readonly FallbackProviderName[]): readonly FallbackProviderName[];
+declare function isRetryableError(error: unknown): boolean;
+interface FallbackResult<T> {
+    result: T;
+    provider: FallbackProviderName;
+    attempts: number;
+}
+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.
+ */
+declare function runWithFallback<T>(invoke: (model: LanguageModel) => Promise<T>, options?: CreateFallbackModelOptions): Promise<FallbackResult<T>>;
+/**
+ * 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.
+ */
+declare function withAnthropicCacheControl(): {
+    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.
+ */
+declare function buildSystemWithCache(systemPrompt: string): {
+    role: "system";
+    content: string;
+    providerOptions: ReturnType<typeof withAnthropicCacheControl>;
+};
+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.
+ */
+declare function runEmbedWithFallback<T>(invoke: (model: EmbeddingModel) => Promise<T>, options?: EmbeddingFallbackOptions): Promise<FallbackResult<T>>;
+
+/**
+ * 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. */
+type GenerationModality = "image" | "video";
+/** Tenant-scoped attribution for a generation call (mirrors AgentContext). */
+interface GenerationContext {
+    readonly tenantId: string;
+    readonly userId: string;
+    /** Optional logical grouping (e.g. a canvas / conversation id). */
+    readonly conversationId?: string;
+}
+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[];
+}
+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;
+}
+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.
+ */
+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>;
+}
+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[];
+}
+
+/**
+ * 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.
+ */
+
+declare const mockGenerationProvider: GenerationProvider;
+
+/**
+ * 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`.
+ */
+
+declare function registerGenerationProvider(provider: GenerationProvider): void;
+/** Test helper — restores the registry to just the mock provider. */
+declare function _resetGenerationRegistry(): void;
+/** Provider names available for a modality, in resolved priority order. */
+declare function listGenerationProviders(modality: GenerationModality, options?: GenerationCallOptions): string[];
+/**
+ * Generate an image. Always resolves (falls back to the deterministic mock).
+ */
+declare function generateImage(req: ImageGenerationRequest, ctx: GenerationContext, options?: GenerationCallOptions): Promise<GenerationResult>;
+/**
+ * Generate a video (or, in mock mode, a deterministic poster frame).
+ */
+declare function generateVideo(req: VideoGenerationRequest, ctx: GenerationContext, options?: GenerationCallOptions): Promise<GenerationResult>;
+
+/**
+ * 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.
+ */
+
+/**
+ * Load conversation history from Redis.
+ * Returns an empty array when Redis is unavailable.
+ */
+declare function getMemory(tenantId: string, conversationId: string): Promise<AgentMessage[]>;
+/**
+ * Persist messages to Redis with TTL.
+ * Silently skips when Redis is unavailable.
+ */
+declare function saveMemory(tenantId: string, conversationId: string, messages: readonly AgentMessage[]): Promise<void>;
+/**
+ * Clear conversation memory for a tenant/conversation pair.
+ */
+declare function clearMemory(tenantId: string, conversationId: string): Promise<void>;
+
+/**
+ * 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).
+ */
+type LangfuseClient = {
+    trace: (input: unknown) => unknown;
+    flushAsync: () => Promise<void>;
+    shutdownAsync: () => Promise<void>;
+};
+/**
+ * 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.
+ */
+declare function initLangfuse(): Promise<LangfuseClient | null>;
+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.
+ */
+declare function buildTelemetryConfig(args: {
+    functionId: string;
+    metadata?: TelemetryMetadata;
+}): {
+    isEnabled: boolean;
+    functionId?: string;
+    metadata?: Record<string, unknown>;
+};
+/** Flush pending telemetry before process exit. Safe to call when disabled. */
+declare function flushTelemetry(): Promise<void>;
+
+/**
+ * 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
+ */
+
+declare class AgentOrchestrator {
+    private readonly agents;
+    private readonly router;
+    private readonly defaultAgentId;
+    constructor(config: OrchestratorConfig);
+    /**
+     * Register a pre-built agent instance (e.g. VercelAIAgent).
+     * Overwrites any agent with the same ID.
+     */
+    registerAgent(agent: BaseAgent): void;
+    /**
+     * Get a registered agent by ID.
+     */
+    getAgent(agentId: string): BaseAgent | undefined;
+    /**
+     * Route a message to the best agent and execute.
+     */
+    chat(message: string, context: AgentContext): Promise<AgentResponse>;
+    /**
+     * Execute a multi-agent pipeline where each step's output feeds the next.
+     * @experimental — API may change. Use `chat()` for production workloads.
+     */
+    pipeline(steps: readonly PipelineStep[], input: string, context: AgentContext): Promise<AgentResponse>;
+    /**
+     * 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.
+     */
+    broadcast(message: string, context: AgentContext): Promise<readonly AgentResponse[]>;
+    /**
+     * Check tenant quota before execution.
+     */
+    private assertQuota;
+}
+
+/**
+ * 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
+ */
+
+declare class AgentRouter {
+    private readonly config;
+    constructor(config: RouterConfig);
+    /**
+     * Route a message to the best-matching agent.
+     * Returns the agent ID.
+     */
+    route(message: string, agents: readonly AgentConfig[], context: AgentContext, defaultAgentId?: string): Promise<string>;
+    /**
+     * Keyword-based routing: score each agent by how many words from
+     * its name + description appear in the user message.
+     */
+    private routeByKeyword;
+    /**
+     * 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 routeByLLM;
+    /**
+     * Custom routing via user-supplied function.
+     */
+    private routeByCustom;
+}
+
+/**
+ * Tenant-scoped agent execution context.
+ *
+ * Ensures every agent operation carries tenantId for RLS,
+ * billing, and audit trail purposes.
+ */
+
+/**
+ * Create a fully-populated AgentContext.
+ * Generates a random conversationId when none is provided.
+ */
+declare function createAgentContext(tenantId: string, userId: string, conversationId?: string, metadata?: Record<string, unknown>): AgentContext;
+/**
+ * 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.
+ */
+declare function checkAgentQuota(tenantId: string): Promise<{
+    allowed: boolean;
+    remaining: number;
+}>;
+
+export { AgentConfig, AgentContext, AgentMessage, AgentOrchestrator, AgentResponse, AgentRouter, type AgentsEnv, AgentsEnvSchema, BaseAgent, type CreateFallbackModelOptions, type EmbeddingFallbackOptions, FallbackProviderName, type FallbackResult, type GenerationCallOptions, type GenerationContext, type GenerationModality, type GenerationProvider, type GenerationResult, type ImageGenerationRequest, OrchestratorConfig, PipelineStep, RouterConfig, type TelemetryMetadata, type UserContext, type VideoGenerationRequest, _resetGenerationRegistry, buildPersonalizedSystemPrompt, buildSystemWithCache, buildTelemetryConfig, checkAgentQuota, clearMemory, createAgentContext, filterAvailableProviders, flushTelemetry, generateImage, generateVideo, getAgentsEnv, getMemory, initLangfuse, isLangfuseConfigured, isRetryableError, listGenerationProviders, mockGenerationProvider, registerGenerationProvider, renderUserContextBlock, runEmbedWithFallback, runWithFallback, saveMemory, withAnthropicCacheControl };