@sahan-sac/ai-core 0.1.0

package/dist/providers.js

@@ -0,0 +1,436 @@
+// src/providers.ts
+import "server-only";
+import { createOpenAI } from "@ai-sdk/openai";
+import { generateText } from "ai";
+
+// src/log.ts
+var consoleAiLogger = {
+  warn(message, meta) {
+    console.warn(JSON.stringify({ level: "warn", message, ...meta }));
+  }
+};
+
+// src/models.ts
+var DEFAULT_TEXT_MODELS = {
+  // Long structured JSON: a full flash model, not lite.
+  blog: {
+    gemini: "gemini-2.5-flash",
+    openrouter: "nvidia/nemotron-3-super-120b-a12b:free",
+    nvidia: "nvidia/nemotron-3-super-120b-a12b",
+    vertex: "gemini-2.5-flash"
+  },
+  // Short, latency-sensitive replies: the fastest free model first.
+  chat: {
+    gemini: "gemini-3.1-flash-lite",
+    openrouter: "nvidia/nemotron-3-super-120b-a12b:free",
+    nvidia: "nvidia/nemotron-3-super-120b-a12b",
+    vertex: "gemini-2.5-flash"
+  }
+};
+var pick = (...values) => values.find((value) => value && value.trim()).trim();
+function textModels(env, purpose) {
+  const defaults = DEFAULT_TEXT_MODELS[purpose];
+  const own = purpose === "blog" ? { gemini: env.BLOG_GEMINI_MODEL, openrouter: env.BLOG_OPENROUTER_MODEL, nvidia: env.BLOG_NVIDIA_MODEL, vertex: env.BLOG_VERTEX_MODEL } : { gemini: env.CHAT_GEMINI_MODEL, openrouter: env.CHAT_OPENROUTER_MODEL, nvidia: env.CHAT_NVIDIA_MODEL, vertex: env.CHAT_VERTEX_MODEL };
+  return {
+    gemini: pick(own.gemini, env.GEMINI_MODEL, defaults.gemini),
+    openrouter: pick(own.openrouter, env.OPENROUTER_MODEL, defaults.openrouter),
+    nvidia: pick(own.nvidia, env.NVIDIA_MODEL, defaults.nvidia),
+    vertex: pick(own.vertex, env.VERTEX_MODEL, defaults.vertex)
+  };
+}
+var paidAllowed = (env) => env.AI_ALLOW_PAID === true;
+function vertexConfigured(env) {
+  return Boolean(env.GOOGLE_CLIENT_EMAIL && env.GOOGLE_PRIVATE_KEY && env.GOOGLE_CLOUD_PROJECT);
+}
+function thinkingConfigFor(model, maxOutputTokens) {
+  const long = maxOutputTokens >= 2e3;
+  if (/^gemini-[3-9]/.test(model)) {
+    return { thinkingLevel: long ? "low" : /flash/.test(model) ? "minimal" : "low" };
+  }
+  return { thinkingBudget: long ? Math.min(800, Math.floor(maxOutputTokens / 5)) : 0 };
+}
+
+// src/vertex.ts
+import "server-only";
+var cachedToken = null;
+function base64UrlEncode(input) {
+  return Buffer.from(input).toString("base64url");
+}
+async function getVertexAccessToken(account, fetchImpl = fetch) {
+  const now = Date.now();
+  if (cachedToken && cachedToken.expiresAt - 6e4 > now) return cachedToken.accessToken;
+  const { createSign } = await import("crypto");
+  const issuedAt = Math.floor(now / 1e3);
+  const expiresIn = 3600;
+  const header = base64UrlEncode(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const claims = base64UrlEncode(
+    JSON.stringify({
+      iss: account.clientEmail,
+      scope: "https://www.googleapis.com/auth/cloud-platform",
+      aud: account.tokenUri,
+      iat: issuedAt,
+      exp: issuedAt + expiresIn
+    })
+  );
+  const signingInput = `${header}.${claims}`;
+  const signature = createSign("RSA-SHA256").update(signingInput).sign(account.privateKey);
+  const jwt = `${signingInput}.${base64UrlEncode(signature)}`;
+  const response = await fetchImpl(account.tokenUri, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+      assertion: jwt
+    })
+  });
+  if (!response.ok) {
+    throw new Error(`Vertex token exchange failed: HTTP ${response.status}`);
+  }
+  const data = await response.json();
+  cachedToken = { accessToken: data.access_token, expiresAt: now + data.expires_in * 1e3 };
+  return data.access_token;
+}
+
+// src/providers.ts
+function jsonConfig(jsonMode) {
+  if (!jsonMode) return {};
+  return typeof jsonMode === "object" ? { responseMimeType: "application/json", responseSchema: jsonMode.schema } : { responseMimeType: "application/json" };
+}
+var AI_TIMEOUT_MS = 25e3;
+var AI_COOLDOWN_MS = 6e4;
+async function attempt(provider, prompt, maxTokens, ms, cancel, jsonMode) {
+  const controller = new AbortController();
+  const onCancel = () => controller.abort();
+  cancel.addEventListener("abort", onCancel, { once: true });
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve({ ok: false, errorClass: "timeout", retryable: true });
+    }, ms);
+  });
+  try {
+    return await Promise.race([provider.generate(prompt, { maxTokens, signal: controller.signal, jsonMode }), timeout]);
+  } catch {
+    return { ok: false, errorClass: "transport", retryable: true };
+  } finally {
+    clearTimeout(timer);
+    cancel.removeEventListener("abort", onCancel);
+  }
+}
+var createAiHealth = () => ({ cooldownUntil: /* @__PURE__ */ new Map(), latencyMs: /* @__PURE__ */ new Map() });
+var sharedAiHealth = globalThis.sahanAiHealth ??= createAiHealth();
+function cooldownFor(outcome) {
+  if (outcome.ok) return 0;
+  if (outcome.errorClass === "timeout" || outcome.status === 429) return AI_COOLDOWN_MS;
+  if (outcome.status === 401 || outcome.status === 403 || outcome.status === 404) return AI_COOLDOWN_MS * 10;
+  return 0;
+}
+var HEDGE = /* @__PURE__ */ Symbol("hedge");
+function createAiService(deps) {
+  const timeoutMs = deps.timeoutMs ?? AI_TIMEOUT_MS;
+  const now = deps.now ?? Date.now;
+  const health = deps.health ?? createAiHealth();
+  const logger = deps.logger ?? consoleAiLogger;
+  function rank(at) {
+    const cooling = (p) => Number((health.cooldownUntil.get(p.name) ?? 0) > at);
+    const speed = (p) => health.latencyMs.get(p.name) ?? Number.POSITIVE_INFINITY;
+    const costly = (p) => Number(Boolean(p.lastResort));
+    return [...deps.providers].sort((a, b) => costly(a) - costly(b) || cooling(a) - cooling(b) || speed(a) - speed(b));
+  }
+  async function generate(prompt, options) {
+    if (deps.providers.length === 0) {
+      return { ok: false, provider: null, errorClass: "no_provider", attempts: [] };
+    }
+    const startedAll = now();
+    const ordered = rank(startedAll);
+    const attempts = [];
+    const cancelLosers = new AbortController();
+    const running = /* @__PURE__ */ new Set();
+    let next = 0;
+    let stopped = false;
+    let result = null;
+    let rejected;
+    const launch = () => {
+      if (result || stopped || next >= ordered.length) return false;
+      const remaining = deps.deadlineMs === void 0 ? timeoutMs : deps.deadlineMs - (now() - startedAll);
+      if (remaining <= 250) return false;
+      const provider = ordered[next++];
+      options?.onAttempt?.({ provider: provider.name, stage: "start" });
+      const started = now();
+      const run = attempt(provider, prompt, options?.maxTokens, Math.min(timeoutMs, remaining), cancelLosers.signal, options?.jsonMode).then((raw) => {
+        if (result) return;
+        const ms = now() - started;
+        let outcome = raw;
+        if (outcome.ok && options?.accept) {
+          const reason = options.accept(outcome.text);
+          if (reason) {
+            rejected = { provider: provider.name, text: outcome.text, reason };
+            outcome = { ok: false, errorClass: "invalid_output", retryable: true };
+          }
+        }
+        if (outcome.ok) {
+          health.cooldownUntil.delete(provider.name);
+          const previous = health.latencyMs.get(provider.name);
+          health.latencyMs.set(provider.name, previous === void 0 ? ms : Math.round(previous * 0.7 + ms * 0.3));
+          attempts.push({ provider: provider.name, ok: true, ms });
+          result = { ok: true, provider: provider.name, text: outcome.text, attempts };
+          options?.onAttempt?.({ provider: provider.name, stage: "success" });
+          cancelLosers.abort();
+          return;
+        }
+        attempts.push({ provider: provider.name, ok: false, errorClass: outcome.errorClass, ms });
+        const fallbackTo = next < ordered.length ? ordered[next].name : void 0;
+        options?.onAttempt?.({
+          provider: provider.name,
+          stage: fallbackTo ? "fallback" : "failure",
+          errorClass: outcome.errorClass,
+          fallbackTo
+        });
+        const cooldown = cooldownFor(outcome);
+        if (cooldown) health.cooldownUntil.set(provider.name, now() + cooldown);
+        logger.warn("ai provider failed", {
+          provider: provider.name,
+          errorClass: outcome.errorClass,
+          ms,
+          ...outcome.errorClass === "invalid_output" && rejected ? { reason: rejected.reason.slice(0, 160) } : {}
+        });
+        if (!outcome.retryable) stopped = true;
+      });
+      const tracked = run.finally(() => running.delete(tracked));
+      running.add(tracked);
+      return true;
+    };
+    while (!result) {
+      if (running.size === 0 && !launch()) break;
+      let timer;
+      const racers = [...running];
+      if (deps.hedgeAfterMs !== void 0 && next < ordered.length) {
+        racers.push(new Promise((resolve) => timer = setTimeout(() => resolve(HEDGE), deps.hedgeAfterMs)));
+      }
+      const first = await Promise.race(racers);
+      clearTimeout(timer);
+      if (first === HEDGE) launch();
+    }
+    return result ?? { ok: false, provider: null, errorClass: attempts[attempts.length - 1]?.errorClass ?? "deadline", attempts, rejected };
+  }
+  return { generate };
+}
+function httpOutcome(status) {
+  return { ok: false, errorClass: `http_${status}`, retryable: true, status };
+}
+var FREE_SUFFIX = ":free";
+function openRouterProvider(config) {
+  const model = config.model || DEFAULT_TEXT_MODELS.blog.openrouter;
+  const client = createOpenAI({
+    apiKey: config.apiKey,
+    baseURL: config.baseUrl || "https://openrouter.ai/api/v1",
+    fetch: config.fetch
+  });
+  return {
+    name: config.name ?? "openrouter",
+    async generate(prompt, options) {
+      if (!config.allowPaidModels && !model.endsWith(FREE_SUFFIX)) {
+        return { ok: false, errorClass: "paid_model_blocked", retryable: true };
+      }
+      return sdkGenerate(client.chat(model), prompt, options);
+    }
+  };
+}
+async function sdkGenerate(model, prompt, options) {
+  try {
+    const result = await generateText({
+      model,
+      system: prompt.system,
+      prompt: prompt.user,
+      maxOutputTokens: options?.maxTokens ?? 1200,
+      maxRetries: 0,
+      abortSignal: options?.signal
+    });
+    if (!result.text) return { ok: false, errorClass: "empty_response", retryable: true };
+    if (result.finishReason === "length") return { ok: false, errorClass: "truncated", retryable: true };
+    return { ok: true, text: result.text };
+  } catch (error) {
+    const status = error?.statusCode ?? error?.status;
+    if (status) return httpOutcome(status);
+    return { ok: false, errorClass: options?.signal?.aborted ? "timeout" : "provider_error", retryable: true };
+  }
+}
+function nvidiaProvider(config) {
+  const model = config.model || DEFAULT_TEXT_MODELS.blog.nvidia;
+  const client = createOpenAI({
+    apiKey: config.apiKey,
+    baseURL: "https://integrate.api.nvidia.com/v1",
+    fetch: config.fetch
+  });
+  return {
+    name: "nvidia",
+    generate: (prompt, options) => sdkGenerate(client.chat(model), prompt, options)
+  };
+}
+function geminiOutcome(data) {
+  const candidate = data.candidates?.[0];
+  const text = candidate?.content?.parts?.filter((part) => !part.thought).map((part) => part.text ?? "").join("") ?? "";
+  if (candidate?.finishReason === "MAX_TOKENS") return { ok: false, errorClass: "truncated", retryable: true };
+  if (!text) return { ok: false, errorClass: "empty_response", retryable: true };
+  return { ok: true, text };
+}
+function geminiProvider(config) {
+  const model = config.model || DEFAULT_TEXT_MODELS.blog.gemini;
+  const fetchImpl = config.fetchImpl ?? fetch;
+  return {
+    name: "gemini",
+    async generate(prompt, options) {
+      try {
+        const maxOutputTokens = options?.maxTokens ?? 2400;
+        const generationConfig = {
+          maxOutputTokens,
+          thinkingConfig: thinkingConfigFor(model, maxOutputTokens),
+          ...jsonConfig(options?.jsonMode)
+        };
+        let response = await fetchImpl(
+          `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`,
+          {
+            method: "POST",
+            // Header, not ?key=: query strings end up in proxy and access logs.
+            headers: { "content-type": "application/json", "x-goog-api-key": config.apiKey },
+            signal: options?.signal,
+            body: JSON.stringify({
+              systemInstruction: { parts: [{ text: prompt.system }] },
+              contents: [{ role: "user", parts: [{ text: prompt.user }] }],
+              generationConfig
+            })
+          }
+        );
+        if (response.status === 503 && !options?.signal?.aborted) {
+          await new Promise((r) => setTimeout(r, 500));
+          if (!options?.signal?.aborted) {
+            response = await fetchImpl(
+              `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`,
+              {
+                method: "POST",
+                headers: { "content-type": "application/json", "x-goog-api-key": config.apiKey },
+                signal: options?.signal,
+                body: JSON.stringify({
+                  systemInstruction: { parts: [{ text: prompt.system }] },
+                  contents: [{ role: "user", parts: [{ text: prompt.user }] }],
+                  generationConfig
+                })
+              }
+            );
+          }
+        }
+        if (!response.ok) return httpOutcome(response.status);
+        return geminiOutcome(await response.json());
+      } catch {
+        return { ok: false, errorClass: options?.signal?.aborted ? "timeout" : "transport", retryable: true };
+      }
+    }
+  };
+}
+function vertexProvider(config) {
+  const model = config.model || DEFAULT_TEXT_MODELS.blog.vertex;
+  const location = config.location ?? (/^gemini-[3-9]/.test(model) ? "global" : "us-central1");
+  const host = location === "global" ? "aiplatform.googleapis.com" : `${location}-aiplatform.googleapis.com`;
+  const fetchImpl = config.fetchImpl ?? fetch;
+  return {
+    name: "vertex",
+    lastResort: true,
+    async generate(prompt, options) {
+      try {
+        const accessToken = await getVertexAccessToken(
+          { clientEmail: config.clientEmail, privateKey: config.privateKey, tokenUri: config.tokenUri },
+          fetchImpl
+        );
+        const response = await fetchImpl(
+          `https://${host}/v1/projects/${config.project}/locations/${location}/publishers/google/models/${model}:generateContent`,
+          {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${accessToken}` },
+            signal: options?.signal,
+            body: JSON.stringify({
+              systemInstruction: { parts: [{ text: prompt.system }] },
+              contents: [{ role: "user", parts: [{ text: prompt.user }] }],
+              generationConfig: {
+                maxOutputTokens: options?.maxTokens ?? 1800,
+                thinkingConfig: thinkingConfigFor(model, options?.maxTokens ?? 1800),
+                ...jsonConfig(options?.jsonMode)
+              }
+            })
+          }
+        );
+        if (!response.ok) return httpOutcome(response.status);
+        return geminiOutcome(await response.json());
+      } catch {
+        return { ok: false, errorClass: "transport", retryable: true };
+      }
+    }
+  };
+}
+function realProviders(env, purpose, fetchImpl) {
+  const providers = [];
+  const models = textModels(env, purpose);
+  if (env.GEMINI_API_KEY) {
+    providers.push(geminiProvider({ apiKey: env.GEMINI_API_KEY, model: models.gemini, fetchImpl }));
+  }
+  const openRouterModel = models.openrouter;
+  if (env.OPENROUTER_API_KEY) {
+    providers.push(
+      openRouterProvider({
+        apiKey: env.OPENROUTER_API_KEY,
+        model: openRouterModel,
+        baseUrl: env.OPENROUTER_BASE_URL,
+        allowPaidModels: env.OPENROUTER_ALLOW_PAID_MODELS,
+        fetch: fetchImpl
+      })
+    );
+  }
+  if (env.OPENROUTER_API_KEY_2) {
+    providers.push(
+      openRouterProvider({
+        apiKey: env.OPENROUTER_API_KEY_2,
+        model: openRouterModel,
+        baseUrl: env.OPENROUTER_BASE_URL,
+        allowPaidModels: env.OPENROUTER_ALLOW_PAID_MODELS,
+        fetch: fetchImpl,
+        name: "openrouter-2"
+      })
+    );
+  }
+  if (env.NVIDIA_API_KEY) {
+    providers.push(
+      nvidiaProvider({
+        apiKey: env.NVIDIA_API_KEY,
+        model: models.nvidia,
+        fetch: fetchImpl
+      })
+    );
+  }
+  if (paidAllowed(env) && vertexConfigured(env)) {
+    providers.push(
+      vertexProvider({
+        clientEmail: env.GOOGLE_CLIENT_EMAIL,
+        privateKey: env.GOOGLE_PRIVATE_KEY,
+        tokenUri: env.GOOGLE_TOKEN_URI,
+        project: env.GOOGLE_CLOUD_PROJECT,
+        model: models.vertex,
+        fetchImpl
+      })
+    );
+  }
+  return providers;
+}
+export {
+  AI_COOLDOWN_MS,
+  AI_TIMEOUT_MS,
+  HEDGE,
+  createAiHealth,
+  createAiService,
+  geminiOutcome,
+  geminiProvider,
+  nvidiaProvider,
+  openRouterProvider,
+  realProviders,
+  sharedAiHealth,
+  vertexProvider
+};

package/dist/vertex.d.ts

@@ -0,0 +1,11 @@
+interface VertexServiceAccount {
+    clientEmail: string;
+    privateKey: string;
+    tokenUri: string;
+}
+/** Signs a Google OAuth2 service-account JWT and exchanges it for an access token. */
+declare function getVertexAccessToken(account: VertexServiceAccount, fetchImpl?: typeof fetch): Promise<string>;
+/** Test helper: forget the cached token. */
+declare function resetVertexTokenCache(): void;
+
+export { type VertexServiceAccount, getVertexAccessToken, resetVertexTokenCache };

package/dist/vertex.js

@@ -0,0 +1,47 @@
+// src/vertex.ts
+import "server-only";
+var cachedToken = null;
+function base64UrlEncode(input) {
+  return Buffer.from(input).toString("base64url");
+}
+async function getVertexAccessToken(account, fetchImpl = fetch) {
+  const now = Date.now();
+  if (cachedToken && cachedToken.expiresAt - 6e4 > now) return cachedToken.accessToken;
+  const { createSign } = await import("crypto");
+  const issuedAt = Math.floor(now / 1e3);
+  const expiresIn = 3600;
+  const header = base64UrlEncode(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const claims = base64UrlEncode(
+    JSON.stringify({
+      iss: account.clientEmail,
+      scope: "https://www.googleapis.com/auth/cloud-platform",
+      aud: account.tokenUri,
+      iat: issuedAt,
+      exp: issuedAt + expiresIn
+    })
+  );
+  const signingInput = `${header}.${claims}`;
+  const signature = createSign("RSA-SHA256").update(signingInput).sign(account.privateKey);
+  const jwt = `${signingInput}.${base64UrlEncode(signature)}`;
+  const response = await fetchImpl(account.tokenUri, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+      assertion: jwt
+    })
+  });
+  if (!response.ok) {
+    throw new Error(`Vertex token exchange failed: HTTP ${response.status}`);
+  }
+  const data = await response.json();
+  cachedToken = { accessToken: data.access_token, expiresAt: now + data.expires_in * 1e3 };
+  return data.access_token;
+}
+function resetVertexTokenCache() {
+  cachedToken = null;
+}
+export {
+  getVertexAccessToken,
+  resetVertexTokenCache
+};

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@sahan-sac/ai-core",
+  "version": "0.1.0",
+  "description": "Free-by-default AI provider chain (Gemini, OpenRouter, NVIDIA, Vertex) with hedging, cooldowns and deadlines, env-driven model resolution, image generation and prompt-injection guards. Shared by @sahan-sac/blog-kit and @sahan-sac/chat-kit.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ks-official-Sahan/Sahan.git",
+    "directory": "packages/ai-core"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "gemini",
+    "openrouter",
+    "nvidia",
+    "vertex",
+    "flux"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./env": {
+      "types": "./dist/env.d.ts",
+      "import": "./dist/env.js"
+    },
+    "./models": {
+      "types": "./dist/models.d.ts",
+      "import": "./dist/models.js"
+    },
+    "./providers": {
+      "types": "./dist/providers.d.ts",
+      "import": "./dist/providers.js"
+    },
+    "./vertex": {
+      "types": "./dist/vertex.d.ts",
+      "import": "./dist/vertex.js"
+    },
+    "./image": {
+      "types": "./dist/image.d.ts",
+      "import": "./dist/image.js"
+    },
+    "./guard": {
+      "types": "./dist/guard.d.ts",
+      "import": "./dist/guard.js"
+    },
+    "./availability": {
+      "types": "./dist/availability.d.ts",
+      "import": "./dist/availability.js"
+    },
+    "./log": {
+      "types": "./dist/log.d.ts",
+      "import": "./dist/log.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "dependencies": {
+    "@ai-sdk/openai": "^4.0.71",
+    "ai": "^7.0.107",
+    "server-only": "^0.0.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsup": "^8.3.5",
+    "tsx": "^4.23.15",
+    "typescript": "^5.6.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.build.json",
+    "test": "node --conditions=react-server --import tsx --test \"src/**/*.test.ts\""
+  }
+}