pi-nebius 0.3.0

package/src/model-settings.ts

@@ -0,0 +1,129 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { isRecord, type NebiusModel } from "./models.ts";
+
+export const efforts = ["none", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export interface ModelSettings {
+  temperature?: number;
+  reasoningEffort?: (typeof efforts)[number];
+  maxTokens?: number;
+  contextWindow?: number;
+  reasoning?: boolean;
+}
+export type ModelSettingsMap = Record<string, ModelSettings>;
+export const settingsPath = (agentDir: string) =>
+  join(agentDir, "pi-nebius", "model-settings.json");
+
+export function validateSettings(value: unknown): ModelSettings {
+  if (!isRecord(value)) throw new Error("Model settings must be an object.");
+  const allowed = ["temperature", "reasoningEffort", "maxTokens", "contextWindow", "reasoning"];
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) throw new Error(`Unknown model setting: ${key}`);
+    const v = value[key];
+    if (key === "temperature" && (typeof v !== "number" || !Number.isFinite(v) || v < 0 || v > 2))
+      throw new Error("Temperature must be between 0 and 2.");
+    if (
+      (key === "maxTokens" || key === "contextWindow") &&
+      (typeof v !== "number" || !Number.isSafeInteger(v) || v <= 0)
+    )
+      throw new Error(`${key} must be a positive integer.`);
+    if (key === "reasoningEffort" && !efforts.includes(v as (typeof efforts)[number]))
+      throw new Error("Invalid reasoning effort.");
+    if (key === "reasoning" && typeof v !== "boolean")
+      throw new Error("Reasoning must be a boolean.");
+  }
+  if (
+    typeof value.maxTokens === "number" &&
+    typeof value.contextWindow === "number" &&
+    value.maxTokens > value.contextWindow
+  )
+    throw new Error("Maximum output tokens cannot exceed the context window.");
+  return { ...value } as ModelSettings;
+}
+
+export async function loadSettings(path: string): Promise<ModelSettingsMap> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw error;
+  }
+  const value: unknown = JSON.parse(text);
+  if (!isRecord(value) || value.version !== 1 || !isRecord(value.models))
+    throw new Error("Invalid Nebius model settings file.");
+  return Object.fromEntries(
+    Object.entries(value.models).map(([id, settings]) => [id, validateSettings(settings)]),
+  );
+}
+
+export async function saveModelSettings(
+  path: string,
+  id: string,
+  settings: ModelSettings,
+): Promise<ModelSettingsMap> {
+  // Re-read before each edit so unrelated changes from another Pi session are retained.
+  const models = await loadSettings(path);
+  const next = validateSettings(settings);
+  const entries = Object.entries(models).filter(([key]) => key !== id);
+  if (Object.keys(next).length) entries.push([id, next]);
+  const updated = Object.fromEntries(entries);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify({ version: 1, models: updated }, null, 2)}\n`, {
+      mode: 0o600,
+      flag: "wx",
+    });
+    await rename(temporary, path);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+  return updated;
+}
+
+export function applyModelSettings(model: NebiusModel, settings: ModelSettings = {}): NebiusModel {
+  const contextWindow = settings.contextWindow ?? model.contextWindow;
+  return {
+    ...model,
+    contextWindow,
+    maxTokens: Math.min(settings.maxTokens ?? model.maxTokens, contextWindow),
+    reasoning: settings.reasoning ?? model.reasoning,
+  };
+}
+
+/** Apply only supported request overrides; never store prompts or messages. */
+export function applyRequestSettings(
+  payload: unknown,
+  model: NebiusModel,
+  settings: ModelSettings = {},
+): unknown {
+  if (!isRecord(payload)) return payload;
+  const result = { ...payload };
+  if (
+    settings.temperature !== undefined &&
+    model.nebiusSupportedParameters?.includes("temperature")
+  )
+    result.temperature = settings.temperature;
+  if (
+    settings.reasoningEffort !== undefined &&
+    model.reasoning &&
+    model.compat?.supportsReasoningEffort
+  )
+    result.reasoning_effort = settings.reasoningEffort;
+  if (settings.maxTokens !== undefined) {
+    delete result.max_completion_tokens;
+    result.max_tokens = Math.min(settings.maxTokens, model.contextWindow);
+  }
+  return result;
+}
+
+export function requestSettings(payload: unknown): Record<string, unknown> {
+  if (!isRecord(payload)) return {};
+  return Object.fromEntries(
+    ["temperature", "reasoning_effort", "max_tokens", "max_completion_tokens", "top_p"]
+      .filter((key) => payload[key] !== undefined)
+      .map((key) => [key, payload[key]]),
+  );
+}

package/src/models.ts

@@ -0,0 +1,73 @@
+import type { Model } from "@earendil-works/pi-ai";
+
+export const BASE_URL = "https://api.tokenfactory.nebius.com/v1";
+export type NebiusModel = Model<"openai-completions"> & { nebiusSupportedParameters?: string[] };
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Only retain fields we understand: no credentials or arbitrary server data reach the cache. */
+export function parseModels(payload: unknown): NebiusModel[] {
+  if (!isRecord(payload) || payload.object !== "list" || !Array.isArray(payload.data)) {
+    throw new Error("Malformed Token Factory model list: expected { object: 'list', data: [...] }");
+  }
+  const models = new Map<string, NebiusModel>();
+  for (const entry of payload.data) {
+    if (
+      !isRecord(entry) ||
+      typeof entry.id !== "string" ||
+      !entry.id.trim() ||
+      entry.id.length > 512 ||
+      [...entry.id].some(
+        (char) => /\s/.test(char) || char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127,
+      )
+    ) {
+      throw new Error("Malformed Token Factory model list: invalid model identifier");
+    }
+    if (entry.status != null && entry.status !== "active") continue;
+    const modality = isRecord(entry.architecture) ? entry.architecture.modality : undefined;
+    // Nebius also serves embeddings and image generation. Only expose text-output models.
+    if (typeof modality === "string" && !/->text$/.test(modality)) continue;
+    const parameters = Array.isArray(entry.supported_sampling_parameters)
+      ? entry.supported_sampling_parameters
+      : [];
+    const features = Array.isArray(entry.supported_features) ? entry.supported_features : [];
+    const effort = parameters.includes("reasoning_effort");
+    const contextWindow = positiveInteger(entry.context_length) ?? 32768;
+    models.set(entry.id, {
+      id: entry.id,
+      name: typeof entry.name === "string" && entry.name.trim() ? entry.name : entry.id,
+      provider: "nebius",
+      api: "openai-completions",
+      baseUrl: BASE_URL,
+      reasoning: effort || features.includes("reasoning"),
+      input:
+        typeof modality === "string" && modality.split("->")[0]?.includes("image")
+          ? ["text", "image"]
+          : ["text"],
+      nebiusSupportedParameters: parameters.filter(
+        (value): value is string => typeof value === "string",
+      ),
+      contextWindow,
+      // No documented output-token limit.
+      maxTokens: Math.min(4096, Math.max(1, Math.floor(contextWindow / 4))),
+      // Required by Pi's Model type; unused by our benchmark.
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      compat: {
+        supportsStore: false,
+        supportsDeveloperRole: false,
+        supportsStrictMode: false,
+        supportsOpenAIGrammarTools: false,
+        supportsReasoningEffort: effort,
+        supportsUsageInStreaming: true,
+        maxTokensField: "max_tokens",
+      },
+    });
+  }
+  return [...models.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function positiveInteger(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}

package/src/provider.ts

@@ -0,0 +1,63 @@
+import { createProvider, type ProviderStreams } from "@earendil-works/pi-ai";
+import { openAICompletionsApi } from "@earendil-works/pi-ai/compat";
+import { withErrorDetails } from "./errors.ts";
+import { applyRequestSettings, type ModelSettingsMap } from "./model-settings.ts";
+import { BASE_URL, type NebiusModel } from "./models.ts";
+
+export function nebiusProvider(
+  models: NebiusModel[],
+  settings: ModelSettingsMap = {},
+  onRequest?: (payload: unknown) => void,
+) {
+  const adapter = openAICompletionsApi();
+  const api: ProviderStreams = {
+    stream: (model, context, options) =>
+      adapter.stream(model, context, {
+        ...options,
+        onPayload: async (payload, selected) => {
+          const previous = await options?.onPayload?.(payload, selected);
+          const adjusted = applyRequestSettings(
+            previous ?? payload,
+            model as NebiusModel,
+            settings[model.id],
+          );
+          onRequest?.(adjusted);
+          return adjusted;
+        },
+        fetch: withErrorDetails(options?.fetch ?? globalThis.fetch),
+      }),
+    streamSimple: (model, context, options) =>
+      adapter.streamSimple(model, context, {
+        ...options,
+        onPayload: async (payload, selected) => {
+          const previous = await options?.onPayload?.(payload, selected);
+          const adjusted = applyRequestSettings(
+            previous ?? payload,
+            model as NebiusModel,
+            settings[model.id],
+          );
+          onRequest?.(adjusted);
+          return adjusted;
+        },
+        fetch: withErrorDetails(options?.fetch ?? globalThis.fetch),
+      }),
+  };
+  return createProvider({
+    id: "nebius",
+    name: "Nebius Token Factory",
+    baseUrl: BASE_URL,
+    models,
+    api,
+    auth: {
+      apiKey: {
+        name: "NEBIUS_API_KEY",
+        // Ambient-only auth: no login flow and no credential persistence.
+        async resolve({ ctx, signal }) {
+          signal.throwIfAborted();
+          const key = (await ctx.env("NEBIUS_API_KEY"))?.trim();
+          return key ? { auth: { apiKey: key }, source: "NEBIUS_API_KEY" } : undefined;
+        },
+      },
+    },
+  });
+}