@nebutra/agents 1.0.0

package/src/__tests__/public-api.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Public API contract for @nebutra/agents.
+ *
+ * Guards the surface area that was consolidated from `@nebutra/ai-sdk`
+ * (generateText / streamText / embed / embedMany / configure / models / createModel)
+ * plus the pre-existing agent orchestration primitives. Any deletion or
+ * rename to these exports is a breaking change.
+ */
+
+import { describe, expect, it } from "vitest";
+import * as agents from "../index";
+
+describe("@nebutra/agents public API contract", () => {
+  // ─── Agent orchestration primitives ──────────────────────────────────────
+  it("exports BaseAgent class", () => {
+    expect(agents.BaseAgent).toBeDefined();
+    expect(typeof agents.BaseAgent).toBe("function");
+  });
+
+  it("exports AgentOrchestrator class", () => {
+    expect(agents.AgentOrchestrator).toBeDefined();
+    expect(typeof agents.AgentOrchestrator).toBe("function");
+  });
+
+  it("exports AgentRouter class", () => {
+    expect(agents.AgentRouter).toBeDefined();
+    expect(typeof agents.AgentRouter).toBe("function");
+  });
+
+  // ─── Memory functions ────────────────────────────────────────────────────
+  it("exports memory functions", () => {
+    expect(typeof agents.clearMemory).toBe("function");
+    expect(typeof agents.getMemory).toBe("function");
+    expect(typeof agents.saveMemory).toBe("function");
+  });
+
+  // ─── Tenant / context ────────────────────────────────────────────────────
+  it("exports tenant utilities", () => {
+    expect(typeof agents.checkAgentQuota).toBe("function");
+    expect(typeof agents.createAgentContext).toBe("function");
+  });
+
+  // ─── Tools ───────────────────────────────────────────────────────────────
+  it("exports built-in tools", () => {
+    expect(agents.BUILT_IN_TOOLS).toBeDefined();
+    expect(agents.databaseQueryTool).toBeDefined();
+    expect(agents.knowledgeBaseTool).toBeDefined();
+    expect(agents.webSearchTool).toBeDefined();
+  });
+
+  // ─── Vercel AI SDK helpers (absorbed from @nebutra/ai-sdk) ───────────────
+  it("exports configure() and getConfig()", () => {
+    expect(typeof agents.configure).toBe("function");
+    expect(typeof agents.getConfig).toBe("function");
+  });
+
+  it("exports generateText() and streamText()", () => {
+    expect(typeof agents.generateText).toBe("function");
+    expect(typeof agents.streamText).toBe("function");
+  });
+
+  it("exports embed() and embedMany()", () => {
+    expect(typeof agents.embed).toBe("function");
+    expect(typeof agents.embedMany).toBe("function");
+  });
+
+  it("exports createModel() and createEmbeddingModel()", () => {
+    expect(typeof agents.createModel).toBe("function");
+    expect(typeof agents.createEmbeddingModel).toBe("function");
+  });
+
+  it("exports models preset map with expected keys", () => {
+    expect(agents.models).toBeDefined();
+    expect(agents.models.flagship).toBeTypeOf("string");
+    expect(agents.models.fast).toBeTypeOf("string");
+    expect(agents.models.embedding).toBeTypeOf("string");
+  });
+
+  it("exports resolveModel() and returns presets correctly", () => {
+    expect(typeof agents.resolveModel).toBe("function");
+    expect(agents.resolveModel("flagship")).toBe(agents.models.flagship);
+    expect(agents.resolveModel("custom/passthrough")).toBe("custom/passthrough");
+  });
+
+  it("configure() accepts a provider selection and getConfig() reflects it", () => {
+    agents.configure({ provider: "openai", defaultModel: "gpt-4o" });
+    const cfg = agents.getConfig();
+    expect(cfg.provider).toBe("openai");
+    expect(cfg.defaultModel).toBe("gpt-4o");
+  });
+
+  it("NebutraAIConfigSchema validates input config", () => {
+    expect(agents.NebutraAIConfigSchema).toBeDefined();
+    const parsed = agents.NebutraAIConfigSchema.parse({});
+    expect(parsed.provider).toBe("openrouter"); // default
+    expect(parsed.defaultModel).toBeTypeOf("string");
+  });
+
+  it("AgentOrchestrator can be instantiated with empty agents", () => {
+    const orch = new agents.AgentOrchestrator({ agents: [] });
+    expect(orch).toBeInstanceOf(agents.AgentOrchestrator);
+  });
+
+  it("BaseAgent can be instantiated with an AgentConfig", () => {
+    const agent = new agents.BaseAgent({
+      id: "test",
+      name: "Test Agent",
+      description: "Contract test",
+      model: "openai/gpt-4",
+      instructions: "You are a test agent.",
+    });
+    expect(agent.config.id).toBe("test");
+  });
+});

package/src/agent.ts

@@ -0,0 +1,117 @@
+/**
+ * BaseAgent — abstract agent with memory, usage tracking, and tenant scoping.
+ *
+ * Concrete agents (VercelAIAgent, LangChainAgent, etc.) extend this class
+ * and implement the `execute()` method for their specific SDK.
+ */
+
+import { logger } from "@nebutra/logger";
+import { getMemory, saveMemory } from "./memory";
+import type {
+  AgentConfig,
+  AgentContext,
+  AgentMessage,
+  AgentResponse,
+  AgentUsageEvent,
+} from "./types";
+
+export class BaseAgent {
+  public readonly config: AgentConfig;
+
+  constructor(config: AgentConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Run the agent with full lifecycle:
+   * 1. Load long-term memory (if configured)
+   * 2. Trim to short-term window
+   * 3. Delegate to provider-specific `execute()`
+   * 4. Track usage for billing
+   * 5. Persist new messages to memory
+   */
+  async run(messages: readonly AgentMessage[], context: AgentContext): Promise<AgentResponse> {
+    const startTime = Date.now();
+
+    // Load long-term memory when enabled
+    const memory = this.config.memory?.longTerm?.enabled
+      ? await getMemory(context.tenantId, context.conversationId)
+      : [];
+
+    // Merge and trim to short-term window
+    const maxMessages = this.config.memory?.shortTerm?.maxMessages ?? 50;
+    const allMessages = [...memory, ...messages].slice(-maxMessages);
+
+    // Provider-specific execution
+    const response = await this.execute(allMessages, context);
+
+    const durationMs = Date.now() - startTime;
+
+    // Build usage event for billing / metering
+    const usage: AgentUsageEvent = {
+      tenantId: context.tenantId,
+      userId: context.userId,
+      agentId: this.config.id,
+      model: this.config.model,
+      promptTokens: response.usage.promptTokens,
+      completionTokens: response.usage.completionTokens,
+      totalTokens: response.usage.totalTokens,
+      durationMs,
+      timestamp: new Date(),
+    };
+
+    logger.info("Agent execution completed", {
+      agentId: this.config.id,
+      tenantId: context.tenantId,
+      tokens: usage.totalTokens,
+      durationMs,
+    });
+
+    // Persist to long-term memory
+    if (this.config.memory?.longTerm?.enabled) {
+      await saveMemory(context.tenantId, context.conversationId, response.messages);
+    }
+
+    // Await usage emission so billing deduction is tracked before returning
+    await this.emitUsage(usage);
+
+    return response;
+  }
+
+  /**
+   * Provider-specific execution. Subclasses MUST override this.
+   */
+  protected async execute(
+    _messages: readonly AgentMessage[],
+    _context: AgentContext,
+  ): Promise<AgentResponse> {
+    throw new Error("execute() must be implemented by provider adapter");
+  }
+
+  /**
+   * Emit a usage event for downstream billing / metering.
+   */
+  private async emitUsage(event: AgentUsageEvent): Promise<void> {
+    try {
+      const { deductCredits } = await import("@nebutra/billing/credits");
+
+      // Basic credit consumption: 1 credit per 10k total tokens
+      const totalTokens = event.totalTokens || 0;
+      if (totalTokens === 0) return;
+
+      const creditCost = Math.max(1, Math.ceil(totalTokens / 10000));
+
+      await deductCredits({
+        organizationId: event.tenantId,
+        amount: creditCost,
+        description: `Agent execution: ${event.model}`,
+      });
+    } catch (err) {
+      logger.error("Failed to emit usage or deduct credits for agent execution", {
+        tenantId: event.tenantId,
+        agentId: event.agentId,
+        error: err,
+      });
+    }
+  }
+}

package/src/context.ts

@@ -0,0 +1,99 @@
+/**
+ * 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/env.ts

@@ -0,0 +1,79 @@
+/**
+ * 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.
+ */
+
+import { z } from "zod";
+
+/** Comma-separated provider chain. Order = priority. */
+const FallbackProviderName = z.enum(["openrouter", "anthropic", "openai"]);
+export type FallbackProviderName = z.infer<typeof FallbackProviderName>;
+
+const FallbackChain = z
+  .string()
+  .transform((raw) =>
+    raw
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+  )
+  .pipe(z.array(FallbackProviderName).min(1));
+
+export const AgentsEnvSchema = z.object({
+  // ── Anthropic (direct) ─────────────────────────────────────────────────
+  ANTHROPIC_API_KEY: z.string().optional(),
+
+  // ── Langfuse (LLM tracing — optional) ─────────────────────────────────
+  LANGFUSE_PUBLIC_KEY: z.string().optional(),
+  LANGFUSE_SECRET_KEY: z.string().optional(),
+  LANGFUSE_HOST: z.string().url().default("https://cloud.langfuse.com"),
+
+  // ── Multi-provider fallback chain ─────────────────────────────────────
+  /**
+   * Comma-separated chain of providers tried in order on retryable failures.
+   * Default: "openrouter,anthropic,openai" — OpenRouter first (multi-model),
+   * then direct Anthropic (prompt caching), then direct OpenAI as last resort.
+   */
+  LLM_FALLBACK_CHAIN: FallbackChain.default((): FallbackProviderName[] => [
+    "openrouter",
+    "anthropic",
+    "openai",
+  ]),
+
+  /**
+   * Comma-separated chain of providers tried for EMBEDDINGS, in order.
+   * Default: "openrouter,openai" — Anthropic does not currently expose
+   * embedding models, so it is excluded by default. If unset, falls back
+   * to LLM_FALLBACK_CHAIN with embedding-incompatible providers filtered out.
+   */
+  LLM_EMBEDDING_FALLBACK_CHAIN: FallbackChain.default((): FallbackProviderName[] => [
+    "openrouter",
+    "openai",
+  ]),
+});
+
+export type AgentsEnv = z.infer<typeof AgentsEnvSchema>;
+
+/** Lazy parsed env — re-read once on first call. */
+let _cached: AgentsEnv | undefined;
+
+/** Returns the validated env (cached). Safe to call from any runtime. */
+export function getAgentsEnv(): AgentsEnv {
+  if (_cached) return _cached;
+  _cached = AgentsEnvSchema.parse(globalThis.process?.env ?? {});
+  return _cached;
+}
+
+/** Test helper — clears cache so updated process.env is picked up. */
+export function _resetAgentsEnvCache(): void {
+  _cached = undefined;
+}
+
+/** True iff Langfuse credentials are present. */
+export function isLangfuseConfigured(): boolean {
+  const env = getAgentsEnv();
+  return Boolean(env.LANGFUSE_PUBLIC_KEY && env.LANGFUSE_SECRET_KEY);
+}