@nebutra/agents 1.0.0 → 1.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,40 @@
+
+> @nebutra/agents@1.1.0 build /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/agents
+> tsup
+
+CLI Building entry: src/index.ts, src/tools.ts, src/providers/langchain.ts, src/providers/vercel-ai.ts, src/sdk/config.ts, src/sdk/index.ts, src/sdk/models.ts, src/sdk/provider.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Using tsup config: /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/agents/tsup.config.ts
+CLI Target: node20
+CLI Cleaning output folder
+ESM Build start
+ESM dist/index.js               16.08 KB
+ESM dist/providers/langchain.js 536.00 B
+ESM dist/sdk/config.js          166.00 B
+ESM dist/tools.js               203.00 B
+ESM dist/chunk-UVL2UVVM.js      1.26 KB
+ESM dist/providers/vercel-ai.js 2.43 KB
+ESM dist/chunk-B7XWL35G.js      1.51 KB
+ESM dist/chunk-RDOFKRI6.js      4.71 KB
+ESM dist/sdk/index.js           534.00 B
+ESM dist/chunk-5LX742GP.js      7.78 KB
+ESM dist/chunk-NPQECBXL.js      2.37 KB
+ESM dist/sdk/models.js          102.00 B
+ESM dist/chunk-RLWM437Q.js      1.63 KB
+ESM dist/chunk-NVPE5EDI.js      1.49 KB
+ESM dist/chunk-5JZJ5KMC.js      1.22 KB
+ESM dist/sdk/provider.js        190.00 B
+ESM ⚡️ Build success in 33ms
+DTS Build start
+DTS ⚡️ Build success in 5153ms
+DTS dist/index.d.ts               19.71 KB
+DTS dist/tools.d.ts               724.00 B
+DTS dist/providers/langchain.d.ts 546.00 B
+DTS dist/providers/vercel-ai.d.ts 569.00 B
+DTS dist/sdk/index.d.ts           3.88 KB
+DTS dist/sdk/models.d.ts          1.73 KB
+DTS dist/sdk/provider.d.ts        882.00 B
+DTS dist/sdk/config.d.ts          1.80 KB
+DTS dist/agent-CahnMASx.d.ts      1.10 KB
+DTS dist/types-NtgB3pch.d.ts      3.02 KB

package/.turbo/turbo-test.log

@@ -0,0 +1,18 @@
+
+> @nebutra/agents@1.1.0 test /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/agents
+> vitest run
+
+
+ RUN  v4.1.4 /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/agents
+
+ ✓ src/__tests__/fallback-wiring.test.ts (9 tests) 253ms
+ ✓ src/__tests__/cost-observability.test.ts (18 tests) 655ms
+     ✓ falls through retryable errors and returns the next provider's result  537ms
+ ✓ src/__tests__/public-api.test.ts (16 tests) 59ms
+ ✓ src/__tests__/generation.test.ts (7 tests) 43ms
+
+ Test Files  4 passed (4)
+      Tests  50 passed (50)
+   Start at  16:51:18
+   Duration  4.50s (transform 2.59s, setup 0ms, import 6.35s, tests 1.01s, environment 1ms)
+

package/.turbo/turbo-typecheck.log

@@ -0,0 +1,4 @@
+
+> @nebutra/agents@1.1.0 typecheck /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/agents
+> tsc --noEmit
+

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# @nebutra/agents
+
+## 1.1.0
+
+### Minor Changes
+
+- [`092a1ce`](https://github.com/Nebutra/Nebutra-Sailor/commit/092a1ce810965e2d81767642e4bad05b80df81f4) Thanks [@TsekaLuk](https://github.com/TsekaLuk)! - Add the Atelier agentic creative-canvas capability.
+
+  - `@nebutra/agents`: new image/video **generation modality**
+    (`@nebutra/agents/generation`) on the same env-key-gated provider layer as
+    the LLM fallback chain, with a deterministic always-available mock provider.
+  - `@nebutra/atelier-canvas`: new package — server-authoritative non-overlap
+    placement, persist-then-broadcast consistency, per-`(tenant,canvas)`
+    serialization, tenant-scoped store (in-memory + Prisma adapter). The
+    `./agent` subpath adds the creative-direction prompt strategy + generation
+    tool + `AgentConfig` factory (optional `@nebutra/agents` peer).
+  - `@nebutra/feature-flags`: new `FLAGS.ATELIER_CANVAS` (off by default).
+
+  Additive `AtelierCanvas` Prisma model. A flag-gated `/atelier` demo route in
+  `apps/web` exercises the loop end-to-end with the mock provider (no AI key
+  required).
+
+### Patch Changes
+
+- Updated dependencies [[`5d3d7e6`](https://github.com/Nebutra/Nebutra-Sailor/commit/5d3d7e6c59cae5aa242bb988b75a9888cfd0db39)]:
+  - @nebutra/billing@0.1.1

package/dist/agent-CahnMASx.d.ts

@@ -0,0 +1,32 @@
+import { c as AgentConfig, A as AgentMessage, a as AgentContext, b as AgentResponse } from './types-NtgB3pch.js';
+
+/**
+ * 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.
+ */
+
+declare class BaseAgent {
+    readonly config: AgentConfig;
+    constructor(config: AgentConfig);
+    /**
+     * 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
+     */
+    run(messages: readonly AgentMessage[], context: AgentContext): Promise<AgentResponse>;
+    /**
+     * Provider-specific execution. Subclasses MUST override this.
+     */
+    protected execute(_messages: readonly AgentMessage[], _context: AgentContext): Promise<AgentResponse>;
+    /**
+     * Emit a usage event for downstream billing / metering.
+     */
+    private emitUsage;
+}
+
+export { BaseAgent as B };

package/dist/chunk-5JZJ5KMC.js

@@ -0,0 +1,37 @@
+// src/sdk/models.ts
+var models = {
+  /** High-quality reasoning — default for complex tasks */
+  flagship: "anthropic/claude-sonnet-4",
+  /** Deep reasoning for architecture and research */
+  reasoning: "anthropic/claude-opus-4",
+  /** Fast + cheap — chat, summaries, classification */
+  fast: "anthropic/claude-haiku-4",
+  /** OpenAI flagship */
+  "openai-flagship": "openai/gpt-5.4",
+  /** Google flagship */
+  "google-flagship": "google/gemini-2.5-pro",
+  /** Google fast */
+  "google-fast": "google/gemini-2.5-flash",
+  /** Embedding model */
+  embedding: "openai/text-embedding-3-small",
+  /** Embedding model (high-dimensional) */
+  "embedding-large": "openai/text-embedding-3-large",
+  // --- SiliconFlow presets (use with provider: "siliconflow") ---
+  /** SiliconFlow — Qwen 2.5 72B (flagship open-source) */
+  "sf-qwen": "Qwen/Qwen2.5-72B-Instruct",
+  /** SiliconFlow — DeepSeek R1 reasoning (via SiliconFlow Pro) */
+  "sf-deepseek-r1": "Pro/deepseek-ai/DeepSeek-R1",
+  /** SiliconFlow — DeepSeek V3 (fast, capable) */
+  "sf-deepseek-v3": "deepseek-ai/DeepSeek-V3"
+};
+function resolveModel(modelOrPreset) {
+  if (modelOrPreset in models) {
+    return models[modelOrPreset];
+  }
+  return modelOrPreset;
+}
+
+export {
+  models,
+  resolveModel
+};

package/dist/chunk-5LX742GP.js

@@ -0,0 +1,224 @@
+import {
+  resolveModel
+} from "./chunk-5JZJ5KMC.js";
+
+// src/env.ts
+import { z } from "zod";
+var FallbackProviderName = z.enum(["openrouter", "anthropic", "openai"]);
+var FallbackChain = z.string().transform(
+  (raw) => raw.split(",").map((s) => s.trim()).filter(Boolean)
+).pipe(z.array(FallbackProviderName).min(1));
+var 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(() => [
+    "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(() => [
+    "openrouter",
+    "openai"
+  ])
+});
+var _cached;
+function getAgentsEnv() {
+  if (_cached) return _cached;
+  _cached = AgentsEnvSchema.parse(globalThis.process?.env ?? {});
+  return _cached;
+}
+function isLangfuseConfigured() {
+  const env = getAgentsEnv();
+  return Boolean(env.LANGFUSE_PUBLIC_KEY && env.LANGFUSE_SECRET_KEY);
+}
+
+// src/fallback.ts
+import { logger } from "@nebutra/logger";
+var ENV_KEY_BY_PROVIDER = {
+  openrouter: "OPENROUTER_API_KEY",
+  anthropic: "ANTHROPIC".concat("_API_KEY"),
+  openai: "OPENAI".concat("_API_KEY")
+};
+function hasProviderKey(provider) {
+  const k = ENV_KEY_BY_PROVIDER[provider];
+  return Boolean(globalThis.process?.env?.[k]);
+}
+function filterAvailableProviders(chain) {
+  const filtered = chain.filter(hasProviderKey);
+  return filtered.length > 0 ? filtered : chain;
+}
+async function buildModel(provider, modelOrPreset) {
+  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 }).chat(modelId);
+    }
+    case "anthropic": {
+      const { createAnthropic } = await import("@ai-sdk/anthropic");
+      const anthropicModelId = modelId.startsWith("anthropic/") ? modelId.slice("anthropic/".length) : modelId;
+      return createAnthropic({ apiKey })(anthropicModelId);
+    }
+    case "openai": {
+      const { createOpenAI } = await import("@ai-sdk/openai");
+      const openaiModelId = modelId.startsWith("openai/") ? modelId.slice("openai/".length) : modelId;
+      return createOpenAI({ apiKey })(openaiModelId);
+    }
+  }
+}
+var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504]);
+function isRetryableError(error) {
+  if (!error || typeof error !== "object") return false;
+  const e = error;
+  const status = typeof e.statusCode === "number" ? e.statusCode : typeof e.status === "number" ? e.status : void 0;
+  if (status !== void 0 && 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;
+  }
+  if (e.isRetryable === true) return true;
+  return false;
+}
+async function runWithFallback(invoke, options = {}) {
+  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;
+  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;
+      if (!isRetryableError(error)) {
+        logger.error("LLM call failed (non-retryable)", { provider, error });
+        throw error;
+      }
+      logger.warn("LLM provider failed \u2014 trying next in chain", {
+        provider,
+        nextIndex: attempts,
+        error
+      });
+    }
+  }
+  throw new Error(
+    `All LLM providers in fallback chain [${chain.join(", ")}] failed. Last error: ${String(lastError)}`
+  );
+}
+function withAnthropicCacheControl() {
+  return {
+    anthropic: { cacheControl: { type: "ephemeral" } }
+  };
+}
+function buildSystemWithCache(systemPrompt) {
+  return {
+    role: "system",
+    content: systemPrompt,
+    providerOptions: withAnthropicCacheControl()
+  };
+}
+var EMBEDDING_CAPABLE = /* @__PURE__ */ new Set([
+  "openrouter",
+  "openai"
+]);
+async function buildEmbeddingModel(provider, modelOrPreset) {
+  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");
+    }
+  }
+}
+async function runEmbedWithFallback(invoke, options = {}) {
+  const env = getAgentsEnv();
+  const rawChain = options.chain ?? env.LLM_EMBEDDING_FALLBACK_CHAIN;
+  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 \u2014 set OPENROUTER_API_KEY or OPENAI_API_KEY (Anthropic does not expose embedding models)."
+    );
+  }
+  const model = options.model ?? "embedding";
+  let lastError;
+  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 \u2014 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 {
+  AgentsEnvSchema,
+  getAgentsEnv,
+  isLangfuseConfigured,
+  filterAvailableProviders,
+  isRetryableError,
+  runWithFallback,
+  withAnthropicCacheControl,
+  buildSystemWithCache,
+  runEmbedWithFallback
+};

package/dist/chunk-B7XWL35G.js

@@ -0,0 +1,60 @@
+import {
+  getAgentsEnv,
+  isLangfuseConfigured
+} from "./chunk-5LX742GP.js";
+
+// src/observability.ts
+import { logger } from "@nebutra/logger";
+var _client;
+async function initLangfuse() {
+  if (_client !== void 0) return _client;
+  if (!isLangfuseConfigured()) {
+    _client = null;
+    return null;
+  }
+  try {
+    const env = getAgentsEnv();
+    const { Langfuse } = await import("langfuse");
+    _client = new Langfuse({
+      publicKey: env.LANGFUSE_PUBLIC_KEY,
+      secretKey: env.LANGFUSE_SECRET_KEY,
+      baseUrl: env.LANGFUSE_HOST
+    });
+    logger.info("Langfuse telemetry enabled", { host: env.LANGFUSE_HOST });
+    return _client;
+  } catch (error) {
+    logger.warn("Failed to initialise Langfuse \u2014 telemetry disabled", { error });
+    _client = null;
+    return null;
+  }
+}
+function buildTelemetryConfig(args) {
+  if (!isLangfuseConfigured()) {
+    return { isEnabled: false };
+  }
+  return {
+    isEnabled: true,
+    functionId: args.functionId,
+    metadata: {
+      ...args.metadata ?? {},
+      // Langfuse picks up these conventional keys from metadata
+      ...args.metadata?.tenantId ? { langfuseUserId: args.metadata.tenantId } : {},
+      ...args.metadata?.sessionId ? { langfuseSessionId: args.metadata.sessionId } : {}
+    }
+  };
+}
+async function flushTelemetry() {
+  const client = await initLangfuse();
+  if (!client) return;
+  try {
+    await client.flushAsync();
+  } catch (error) {
+    logger.warn("Langfuse flush failed", { error });
+  }
+}
+
+export {
+  initLangfuse,
+  buildTelemetryConfig,
+  flushTelemetry
+};

package/dist/chunk-NPQECBXL.js

@@ -0,0 +1,82 @@
+import {
+  runEmbedWithFallback
+} from "./chunk-5LX742GP.js";
+import {
+  createModel
+} from "./chunk-RLWM437Q.js";
+import {
+  NebutraAIConfigSchema
+} from "./chunk-NVPE5EDI.js";
+
+// src/sdk/index.ts
+import {
+  embed as _embed,
+  embedMany as _embedMany,
+  generateText as _generateText,
+  streamText as _streamText
+} from "ai";
+var _resolved = NebutraAIConfigSchema.parse({});
+function configure(config = {}) {
+  _resolved = NebutraAIConfigSchema.parse(config);
+}
+function getConfig() {
+  return _resolved;
+}
+async function generateText(messages, options = {}) {
+  const model = createModel(options.model ?? _resolved.defaultModel, _resolved);
+  return await _generateText({
+    model,
+    messages,
+    ...options.system ? { system: options.system } : {},
+    temperature: options.temperature ?? _resolved.temperature,
+    ...options.maxTokens ? { maxTokens: options.maxTokens } : {},
+    ...options.providerOptions ? { providerOptions: { openrouter: options.providerOptions } } : {}
+  });
+}
+async function streamText(messages, options = {}) {
+  const model = createModel(options.model ?? _resolved.defaultModel, _resolved);
+  const userOnFinish = options.onFinish;
+  return _streamText({
+    model,
+    messages,
+    ...options.system ? { system: options.system } : {},
+    temperature: options.temperature ?? _resolved.temperature,
+    ...options.maxTokens ? { maxTokens: options.maxTokens } : {},
+    ...options.providerOptions ? { providerOptions: { openrouter: options.providerOptions } } : {},
+    ...userOnFinish ? {
+      onFinish: ({ text, finishReason, totalUsage }) => {
+        const event = {
+          text,
+          finishReason: String(finishReason),
+          usage: {
+            inputTokens: totalUsage?.inputTokens,
+            outputTokens: totalUsage?.outputTokens,
+            totalTokens: totalUsage?.totalTokens
+          }
+        };
+        return userOnFinish(event);
+      }
+    } : {}
+  });
+}
+async function embed(value, options = {}) {
+  const { result } = await runEmbedWithFallback(async (model) => _embed({ model, value }), {
+    model: options.model ?? "embedding"
+  });
+  return result;
+}
+async function embedMany(values, options = {}) {
+  const { result } = await runEmbedWithFallback(async (model) => _embedMany({ model, values }), {
+    model: options.model ?? "embedding"
+  });
+  return result;
+}
+
+export {
+  configure,
+  getConfig,
+  generateText,
+  streamText,
+  embed,
+  embedMany
+};

package/dist/chunk-NVPE5EDI.js

@@ -0,0 +1,42 @@
+// src/sdk/config.ts
+import { z } from "zod";
+var ProviderType = z.enum(["openrouter", "openai", "siliconflow", "gateway"]);
+var NebutraAIConfigSchema = z.object({
+  /** Which provider backend to use. Defaults to "openrouter". */
+  provider: ProviderType.default("openrouter"),
+  /** API key override. Falls back to env vars per provider. */
+  apiKey: z.string().optional(),
+  /** Default model identifier. Provider-specific format. */
+  defaultModel: z.string().default("anthropic/claude-sonnet-4"),
+  /** Default temperature for generations. */
+  temperature: z.number().min(0).max(2).default(0.7),
+  /** Default max tokens for output. */
+  maxTokens: z.number().int().positive().optional(),
+  /** Extra headers merged into every request (e.g. HTTP-Referer for OpenRouter). */
+  headers: z.record(z.string(), z.string()).optional(),
+  /** Extra body fields merged into every request. */
+  extraBody: z.record(z.string(), z.unknown()).optional()
+});
+function resolveApiKey(config) {
+  if (config.apiKey) return config.apiKey;
+  const envMap = {
+    openrouter: "OPENROUTER_API_KEY",
+    openai: "OPENAI_API_KEY",
+    siliconflow: "SILICONFLOW_API_KEY",
+    gateway: "VERCEL_OIDC_TOKEN"
+  };
+  const envVar = envMap[config.provider];
+  const value = globalThis.process?.env?.[envVar];
+  if (!value) {
+    throw new Error(
+      `[@nebutra/agents] Missing API key. Set "${envVar}" in environment or pass "apiKey" in config.`
+    );
+  }
+  return value;
+}
+
+export {
+  ProviderType,
+  NebutraAIConfigSchema,
+  resolveApiKey
+};