@nebutra/agents 1.1.1 → 1.1.2

package/dist/index.d.ts

@@ -1,14 +1,17 @@
-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';
+import { B as BaseAgent } from './agent-DDGWuUpe.js';
+export { AgentsEnv, AgentsEnvSchema, FallbackProviderName, getAgentsEnv, isLangfuseConfigured } from './env.js';
+export { CreateFallbackModelOptions, EmbeddingFallbackOptions, FallbackResult, buildSystemWithCache, filterAvailableProviders, isRetryableError, runEmbedWithFallback, runWithFallback, withAnthropicCacheControl } from './fallback.js';
+export { GenerationCallOptions, GenerationContext, GenerationModality, GenerationProvider, GenerationResult, ImageGenerationRequest, VideoGenerationRequest, _resetGenerationRegistry, generateImage, generateVideo, listGenerationProviders, mockGenerationProvider, registerGenerationProvider } from './generation/index.js';
+import { A as AgentMessage, O as OrchestratorConfig, a as AgentContext, b as AgentResponse, R as RouterConfig, c as AgentConfig } from './types-BytC-HfQ.js';
+export { d as AgentTool, e as AgentUsageEvent, M as MemoryConfig, T as TokenUsage, f as ToolCallResult } from './types-BytC-HfQ.js';
+export { TelemetryMetadata, buildTelemetryConfig, flushTelemetry, initLangfuse } from './observability.js';
+export { EmbedOptions, GenerateOptions, GenerateStructuredResult, OPENAI_MAX_PROPERTY_NAME_LENGTH, assertSafeOpenAIJsonPayload, configure, embed, embedMany, findOversizedPropertyName, generateStructured, generateText, getConfig, streamText, validateStructured } from './sdk/index.js';
 export { BUILT_IN_TOOLS, databaseQueryTool, knowledgeBaseTool, webSearchTool } from './tools.js';
+export { GenerateTextResult, ModelMessage, StreamTextResult } from 'ai';
 export { ModelPreset, models, resolveModel } from './sdk/models.js';
 export { NebutraAIConfig, NebutraAIConfigSchema, ProviderType, ResolvedNebutraAIConfig } from './sdk/config.js';
 export { createEmbeddingModel, createModel } from './sdk/provider.js';
+import 'zod';
 
 /**
  * User context primitives — Memory-as-context layer for AI conversations.
@@ -52,258 +55,6 @@ declare function renderUserContextBlock(context: UserContext | null | undefined)
  */
 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.
  *
@@ -331,55 +82,14 @@ declare function saveMemory(tenantId: string, conversationId: string, messages:
 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.
+ * AgentOrchestrator — single-agent routing for the gateway's chat surface.
  *
- * 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
+ * Routes a message to the best-matching registered agent and executes it.
+ * Multi-agent fan-out / pipeline orchestration deliberately does NOT live here:
+ * that grammar is owned by @nebutra/agent-runtime (planWaves / runAgentWaves
+ * over a node topology), the single source of truth for wave scheduling. The
+ * previous `broadcast()` / `pipeline()` methods were unwired @experimental
+ * duplicates and were removed to keep one orchestration substrate.
  */
 
 declare class AgentOrchestrator {
@@ -392,28 +102,11 @@ declare class AgentOrchestrator {
      * Overwrites any agent with the same ID.
      */
     registerAgent(agent: BaseAgent): void;
-    /**
-     * Get a registered agent by ID.
-     */
+    /** Get a registered agent by ID. */
     getAgent(agentId: string): BaseAgent | undefined;
-    /**
-     * Route a message to the best agent and execute.
-     */
+    /** 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.
-     */
+    /** Check tenant quota before execution. */
     private assertQuota;
 }
 
@@ -473,4 +166,4 @@ declare function checkAgentQuota(tenantId: string): Promise<{
     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 };
+export { AgentConfig, AgentContext, AgentMessage, AgentOrchestrator, AgentResponse, AgentRouter, BaseAgent, OrchestratorConfig, RouterConfig, type UserContext, buildPersonalizedSystemPrompt, checkAgentQuota, clearMemory, createAgentContext, getMemory, renderUserContextBlock, saveMemory };