@nebutra/agents 1.0.0 → 1.1.1

package/dist/index.js

@@ -0,0 +1,533 @@
+import {
+  BUILT_IN_TOOLS,
+  databaseQueryTool,
+  knowledgeBaseTool,
+  webSearchTool
+} from "./chunk-UVL2UVVM.js";
+import {
+  buildTelemetryConfig,
+  flushTelemetry,
+  initLangfuse
+} from "./chunk-B7XWL35G.js";
+import {
+  BaseAgent,
+  clearMemory,
+  getMemory,
+  saveMemory
+} from "./chunk-RDOFKRI6.js";
+import {
+  configure,
+  embed,
+  embedMany,
+  generateText,
+  getConfig,
+  streamText
+} from "./chunk-NPQECBXL.js";
+import {
+  AgentsEnvSchema,
+  buildSystemWithCache,
+  filterAvailableProviders,
+  getAgentsEnv,
+  isLangfuseConfigured,
+  isRetryableError,
+  runEmbedWithFallback,
+  runWithFallback,
+  withAnthropicCacheControl
+} from "./chunk-5LX742GP.js";
+import {
+  createEmbeddingModel,
+  createModel
+} from "./chunk-RLWM437Q.js";
+import {
+  NebutraAIConfigSchema
+} from "./chunk-NVPE5EDI.js";
+import {
+  models,
+  resolveModel
+} from "./chunk-5JZJ5KMC.js";
+
+// src/context.ts
+var MAX_BIO_CHARS = 2e3;
+var MAX_INSTRUCTIONS_CHARS = 3e3;
+var MAX_OCCUPATION_CHARS = 120;
+var MAX_NICKNAME_CHARS = 80;
+function present(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function clamp(value, max) {
+  return value.length > max ? `${value.slice(0, max)}\u2026` : value;
+}
+function renderUserContextBlock(context) {
+  if (!context) return null;
+  const lines = [];
+  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:
+${lines.join("\n")}`;
+  }
+  if (present(context.customInstructions)) {
+    if (block) block += "\n\n";
+    block += `The user's custom instructions (these take precedence over defaults):
+${clamp(
+      context.customInstructions.trim(),
+      MAX_INSTRUCTIONS_CHARS
+    )}`;
+  }
+  return block.length > 0 ? block : null;
+}
+function buildPersonalizedSystemPrompt(basePrompt, context) {
+  const block = renderUserContextBlock(context);
+  if (!block) return basePrompt;
+  return `${block}
+
+---
+
+${basePrompt}`;
+}
+
+// src/generation/index.ts
+import { logger } from "@nebutra/logger";
+
+// src/generation/mock-provider.ts
+function hash(input) {
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function escapeXml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function svgDataUri(label, prompt, w, h) {
+  const hue = hash(prompt) % 360;
+  const hue2 = (hue + 40) % 360;
+  const words = prompt.split(/\s+/);
+  const lines = [];
+  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>`;
+  const b64 = typeof btoa === "function" ? btoa(unescape(encodeURIComponent(svg))) : Buffer.from(svg, "utf8").toString("base64");
+  return `data:image/svg+xml;base64,${b64}`;
+}
+var mockGenerationProvider = {
+  name: "mock",
+  envKey: null,
+  capabilities: ["image", "video"],
+  async generateImage(req, _ctx) {
+    const width = req.width ?? 1024;
+    const height = req.height ?? 1024;
+    return {
+      modality: "image",
+      mimeType: "image/svg+xml",
+      url: svgDataUri("mock \xB7 image", req.prompt, width, height),
+      width,
+      height,
+      providerName: "mock",
+      model: req.model ?? "mock-image-1",
+      usage: { units: 1 }
+    };
+  },
+  async generateVideo(req, _ctx) {
+    const width = req.width ?? 1280;
+    const height = req.height ?? 720;
+    const seconds = req.durationSeconds ?? 5;
+    return {
+      modality: "video",
+      mimeType: "image/svg+xml",
+      url: svgDataUri(`mock \xB7 video \xB7 ${seconds}s`, req.prompt, width, height),
+      width,
+      height,
+      providerName: "mock",
+      model: req.model ?? "mock-video-1",
+      usage: { units: seconds }
+    };
+  }
+};
+
+// src/generation/index.ts
+var log = logger.child({ module: "agents/generation" });
+var _registry = /* @__PURE__ */ new Map();
+function registerGenerationProvider(provider) {
+  _registry.set(provider.name, provider);
+}
+function _resetGenerationRegistry() {
+  _registry.clear();
+  _registry.set(mockGenerationProvider.name, mockGenerationProvider);
+}
+_resetGenerationRegistry();
+function hasEnvKey(provider) {
+  if (provider.envKey === null) return true;
+  return Boolean(globalThis.process?.env?.[provider.envKey]);
+}
+function listGenerationProviders(modality, options = {}) {
+  const envChain = (globalThis.process?.env?.GENERATION_FALLBACK_CHAIN ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  const preferred = options.chain ?? (envChain.length > 0 ? envChain : []);
+  const mockName = mockGenerationProvider.name;
+  const all = [...preferred, ..._registry.keys()];
+  const seen = /* @__PURE__ */ new Set();
+  const resolved = [];
+  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, options, ctx, invoke) {
+  const chain = listGenerationProviders(modality, options);
+  let lastErr;
+  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
+      });
+      if (!retryable && name !== mockGenerationProvider.name) continue;
+      if (!retryable) throw err;
+    }
+  }
+  throw lastErr instanceof Error ? lastErr : new Error("[@nebutra/agents] generation chain exhausted");
+}
+async function generateImage(req, ctx, options = {}) {
+  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);
+  });
+}
+async function generateVideo(req, ctx, options = {}) {
+  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);
+  });
+}
+
+// src/orchestrator.ts
+import { logger as logger3 } from "@nebutra/logger";
+
+// src/router.ts
+import { logger as logger2 } from "@nebutra/logger";
+var AgentRouter = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Route a message to the best-matching agent.
+   * Returns the agent ID.
+   */
+  async route(message, agents, context, defaultAgentId) {
+    if (agents.length === 0) {
+      throw new Error("No agents configured in the orchestrator");
+    }
+    const fallback = defaultAgentId ?? agents[0]?.id;
+    if (!fallback) {
+      throw new Error("No agents configured in the orchestrator");
+    }
+    switch (this.config.strategy) {
+      case "keyword":
+        return this.routeByKeyword(message, agents, defaultAgentId) ?? fallback;
+      case "llm":
+        return await this.routeByLLM(message, agents, defaultAgentId) ?? fallback;
+      case "custom":
+        return this.routeByCustom(message, context, defaultAgentId);
+      default: {
+        const _exhaustive = this.config.strategy;
+        throw new Error(`Unknown routing strategy: ${String(_exhaustive)}`);
+      }
+    }
+  }
+  /**
+   * Keyword-based routing: score each agent by how many words from
+   * its name + description appear in the user message.
+   */
+  routeByKeyword(message, agents, defaultAgentId) {
+    const messageLower = message.toLowerCase();
+    let bestId = defaultAgentId ?? agents[0]?.id;
+    let bestScore = 0;
+    for (const agent of agents) {
+      const keywords = `${agent.name} ${agent.description}`.toLowerCase().split(/\s+/);
+      let score = 0;
+      for (const keyword of keywords) {
+        if (keyword.length > 2 && messageLower.includes(keyword)) {
+          score += 1;
+        }
+      }
+      if (score > bestScore) {
+        bestScore = score;
+        bestId = agent.id;
+      }
+    }
+    logger2.info("Router: keyword match", {
+      selectedAgentId: bestId,
+      score: bestScore
+    });
+    return bestId;
+  }
+  /**
+   * 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.
+   */
+  async routeByLLM(message, agents, defaultAgentId) {
+    try {
+      const { generateText: generateText2 } = await import("ai");
+      const agentList = agents.map((a) => `- ${a.id}: ${a.description}`).join("\n");
+      const result = await generateText2({
+        model: agents[0]?.model,
+        system: [
+          "You are a routing classifier. Given a user message and a list of agents,",
+          "respond with ONLY the agent ID that best matches the user's intent.",
+          "If no agent is a good match, respond with the default agent ID.",
+          "",
+          `Available agents:
+${agentList}`,
+          "",
+          defaultAgentId ? `Default agent: ${defaultAgentId}` : ""
+        ].join("\n"),
+        messages: [{ role: "user", content: message }]
+      });
+      const selectedId = result.text.trim();
+      const validAgent = agents.find((a) => a.id === selectedId);
+      if (validAgent) {
+        logger2.info("Router: LLM classification", {
+          selectedAgentId: validAgent.id
+        });
+        return validAgent.id;
+      }
+      return defaultAgentId ?? agents[0]?.id;
+    } catch (error) {
+      logger2.warn("Router: LLM routing failed, falling back to keyword", {
+        error
+      });
+      return this.routeByKeyword(message, agents, defaultAgentId);
+    }
+  }
+  /**
+   * Custom routing via user-supplied function.
+   */
+  async routeByCustom(message, context, defaultAgentId) {
+    if (!this.config.customRouter) {
+      throw new Error(
+        'RouterConfig strategy is "custom" but no customRouter function was provided'
+      );
+    }
+    try {
+      return await this.config.customRouter(message, context);
+    } catch (error) {
+      logger2.warn("Router: custom router failed", { error });
+      if (defaultAgentId) return defaultAgentId;
+      throw error;
+    }
+  }
+};
+
+// src/tenant.ts
+function createAgentContext(tenantId, userId, conversationId, metadata) {
+  return {
+    tenantId,
+    userId,
+    conversationId: conversationId ?? crypto.randomUUID(),
+    ...metadata !== void 0 ? { metadata } : {}
+  };
+}
+async function checkAgentQuota(tenantId) {
+  try {
+    const { getCreditBalance } = await import("@nebutra/billing/credits");
+    const balance = await getCreditBalance(tenantId);
+    if (balance.balance > 0) {
+      return { allowed: true, remaining: balance.balance };
+    }
+    return { allowed: false, remaining: 0 };
+  } catch (_err) {
+    return { allowed: true, remaining: -1 };
+  }
+}
+
+// src/orchestrator.ts
+var AgentOrchestrator = class {
+  agents;
+  router;
+  defaultAgentId;
+  constructor(config) {
+    this.agents = /* @__PURE__ */ new Map();
+    this.defaultAgentId = config.defaultAgentId;
+    for (const agentConfig of config.agents) {
+      this.agents.set(agentConfig.id, new BaseAgent(agentConfig));
+    }
+    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) {
+    this.agents.set(agent.config.id, agent);
+  }
+  /**
+   * Get a registered agent by ID.
+   */
+  getAgent(agentId) {
+    return this.agents.get(agentId);
+  }
+  /**
+   * Route a message to the best agent and execute.
+   */
+  async chat(message, context) {
+    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 = [{ role: "user", content: message, timestamp: /* @__PURE__ */ 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, input, context) {
+    await this.assertQuota(context.tenantId);
+    let currentInput = input;
+    let lastResponse;
+    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 = [
+        { role: "user", content: transformedInput, timestamp: /* @__PURE__ */ new Date() }
+      ];
+      lastResponse = await agent.run(messages, context);
+      const assistantMessages = lastResponse.messages.filter((m) => m.role === "assistant");
+      const lastAssistant = assistantMessages[assistantMessages.length - 1];
+      currentInput = lastAssistant?.content ?? "";
+      logger3.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, context) {
+    await this.assertQuota(context.tenantId);
+    const messages = [{ role: "user", content: message, timestamp: /* @__PURE__ */ new Date() }];
+    const promises = [...this.agents.values()].map((agent) => agent.run(messages, context));
+    return Promise.all(promises);
+  }
+  /**
+   * Check tenant quota before execution.
+   */
+  async assertQuota(tenantId) {
+    const { allowed } = await checkAgentQuota(tenantId);
+    if (!allowed) {
+      throw new Error(`Tenant "${tenantId}" has exceeded agent execution quota`);
+    }
+  }
+};
+export {
+  AgentOrchestrator,
+  AgentRouter,
+  AgentsEnvSchema,
+  BUILT_IN_TOOLS,
+  BaseAgent,
+  NebutraAIConfigSchema,
+  _resetGenerationRegistry,
+  buildPersonalizedSystemPrompt,
+  buildSystemWithCache,
+  buildTelemetryConfig,
+  checkAgentQuota,
+  clearMemory,
+  configure,
+  createAgentContext,
+  createEmbeddingModel,
+  createModel,
+  databaseQueryTool,
+  embed,
+  embedMany,
+  filterAvailableProviders,
+  flushTelemetry,
+  generateImage,
+  generateText,
+  generateVideo,
+  getAgentsEnv,
+  getConfig,
+  getMemory,
+  initLangfuse,
+  isLangfuseConfigured,
+  isRetryableError,
+  knowledgeBaseTool,
+  listGenerationProviders,
+  mockGenerationProvider,
+  models,
+  registerGenerationProvider,
+  renderUserContextBlock,
+  resolveModel,
+  runEmbedWithFallback,
+  runWithFallback,
+  saveMemory,
+  streamText,
+  webSearchTool,
+  withAnthropicCacheControl
+};

package/dist/providers/langchain.d.ts

@@ -0,0 +1,18 @@
+import { B as BaseAgent } from '../agent-CahnMASx.js';
+import { c as AgentConfig } from '../types-NtgB3pch.js';
+
+/**
+ * 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.
+ */
+
+declare class LangChainAgent extends BaseAgent {
+    constructor(config: AgentConfig);
+}
+
+export { LangChainAgent };

package/dist/providers/langchain.js

@@ -0,0 +1,23 @@
+import {
+  BaseAgent
+} from "../chunk-RDOFKRI6.js";
+
+// src/providers/langchain.ts
+var LangChainAgent = class extends BaseAgent {
+  constructor(config) {
+    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")
+    );
+  }
+};
+export {
+  LangChainAgent
+};

package/dist/providers/vercel-ai.d.ts

@@ -0,0 +1,16 @@
+import { B as BaseAgent } from '../agent-CahnMASx.js';
+import { A as AgentMessage, a as AgentContext, b as AgentResponse } from '../types-NtgB3pch.js';
+
+/**
+ * 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.
+ */
+
+declare class VercelAIAgent extends BaseAgent {
+    protected execute(messages: readonly AgentMessage[], context: AgentContext): Promise<AgentResponse>;
+}
+
+export { VercelAIAgent };

package/dist/providers/vercel-ai.js

@@ -0,0 +1,83 @@
+import {
+  buildTelemetryConfig
+} from "../chunk-B7XWL35G.js";
+import {
+  BaseAgent
+} from "../chunk-RDOFKRI6.js";
+import {
+  runWithFallback,
+  withAnthropicCacheControl
+} from "../chunk-5LX742GP.js";
+import "../chunk-5JZJ5KMC.js";
+
+// src/providers/vercel-ai.ts
+var VercelAIAgent = class extends BaseAgent {
+  async execute(messages, context) {
+    const { streamText, stepCountIs, dynamicTool } = await import("ai");
+    const toolSet = this.config.tools ? Object.fromEntries(
+      this.config.tools.map((t) => [
+        t.name,
+        dynamicTool({
+          description: t.description,
+          inputSchema: t.inputSchema,
+          execute: async (args) => t.execute(args, context)
+        })
+      ])
+    ) : void 0;
+    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,
+        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
+    };
+    const { result } = await runWithFallback(
+      async (model) => {
+        const streamOptions = {
+          ...baseOptionsWithoutModel,
+          model,
+          ...toolSet !== void 0 ? { tools: toolSet } : {}
+        };
+        const r = streamText(streamOptions);
+        const text2 = await r.text;
+        const usage2 = await r.usage;
+        return { text: text2, usage: usage2 };
+      },
+      { model: this.config.model }
+    );
+    const { text, usage } = result;
+    const inputTokens = usage?.inputTokens ?? 0;
+    const outputTokens = usage?.outputTokens ?? 0;
+    const responseMessages = [
+      ...messages,
+      { role: "assistant", content: text, timestamp: /* @__PURE__ */ new Date() }
+    ];
+    return {
+      messages: responseMessages,
+      usage: {
+        promptTokens: inputTokens,
+        completionTokens: outputTokens,
+        totalTokens: inputTokens + outputTokens
+      },
+      finishReason: "stop",
+      agentId: this.config.id
+    };
+  }
+};
+export {
+  VercelAIAgent
+};