@almadar/llm 2.50.0 → 2.52.0

package/src/client.ts

@@ -22,7 +22,7 @@ import {
   getGlobalRateLimiter,
   type RateLimiterOptions,
 } from './rate-limiter.js';
-import { TokenTracker, getGlobalTokenTracker } from './token-tracker.js';
+import { TokenTracker, getGlobalTokenTracker, estimateCostUSD } from './token-tracker.js';
 import { parseJsonResponse } from './json-parser.js';
 import {
   parseChatCompletionResponse,
@@ -203,6 +203,15 @@ export interface LLMUsage {
    *  `prompt_tokens_details.cached_tokens`, deepseek-native
    *  `prompt_cache_hit_tokens`). Absent when the provider reports neither. */
   cachedPromptTokens?: number;
+  /**
+   * USD cost of this one call. OpenRouter's authoritative `usage.cost`
+   * (real, routing+cache-adjusted charge) when the provider is
+   * `openrouter`; otherwise `estimateCostUSD` priced from the same
+   * OpenRouter-fetched table `TokenTracker` uses for the whole-run total.
+   * Absent — never `0` — when neither is available (pricing fetch
+   * pending, or the model isn't in OpenRouter's catalog).
+   */
+  costUSD?: number;
 }
 
 export type LLMFinishReason =
@@ -1329,11 +1338,23 @@ export class LLMClient {
           };
           const cachedTokens =
             rawUsage.prompt_tokens_details?.cached_tokens ?? rawUsage.prompt_cache_hit_tokens;
+          // Prefer OpenRouter's authoritative charge; otherwise price the
+          // tokens from the same pricing table the tracker uses (absent,
+          // never 0, when the model has no known pricing row yet).
+          const costUSD =
+            typeof rawUsage.cost === 'number'
+              ? rawUsage.cost
+              : estimateCostUSD(this.modelName, {
+                  promptTokens: parsed.usage.prompt_tokens,
+                  completionTokens: parsed.usage.completion_tokens,
+                  cachedPromptTokens: cachedTokens ?? 0,
+                });
           usage = {
             promptTokens: parsed.usage.prompt_tokens,
             completionTokens: parsed.usage.completion_tokens,
             totalTokens: parsed.usage.total_tokens,
             ...(cachedTokens !== undefined ? { cachedPromptTokens: cachedTokens } : {}),
+            ...(costUSD !== undefined ? { costUSD } : {}),
           };
           if (this.tokenTracker) {
             this.tokenTracker.addUsage(usage.promptTokens, usage.completionTokens, {

package/src/image-client.ts

@@ -41,13 +41,15 @@ export const LOCAL_IMAGE_MODELS = {
   Z_IMAGE_TURBO: 'z-image-turbo',
   FLUX_SCHNELL: 'flux-schnell',
   FLUX_DEV: 'flux-dev',
+  FLUX_KONTEXT: 'flux-kontext',
+  FLUX2_KLEIN: 'flux2-klein',
 } as const;
 
 export const LOCAL_IMAGE_DEFAULTS = {
   /** Z-Image-Turbo is the default: public on Hugging Face, no token required (FLUX is gated). */
-  sheet: LOCAL_IMAGE_MODELS.Z_IMAGE_TURBO,
-  preview: LOCAL_IMAGE_MODELS.Z_IMAGE_TURBO,
-} as const;
+  sheet: process.env.LOCAL_IMAGE_SHEET_MODEL ?? LOCAL_IMAGE_MODELS.Z_IMAGE_TURBO,
+  preview: process.env.LOCAL_IMAGE_PREVIEW_MODEL ?? LOCAL_IMAGE_MODELS.Z_IMAGE_TURBO,
+};
 
 export interface ImageClientOptions {
   provider?: ImageProvider;
@@ -72,6 +74,10 @@ export interface ImageGenerateOptions {
   quality?: 'auto' | 'low' | 'medium' | 'high';
   background?: 'auto' | 'transparent' | 'opaque';
   seed?: number;
+  /** Diffusion step count (local shim; 1–100). */
+  steps?: number;
+  /** img2img denoise strength 0–1 (local shim `image_strength`), used with `references`. */
+  strength?: number;
   references?: ReadonlyArray<ImageReference>;
   provider?: { order?: string[]; only?: string[]; allowFallbacks?: boolean };
 }
@@ -121,6 +127,8 @@ const API_KEY_ENV_VARS: Record<ImageProvider, string> = {
 const IMAGE_CHECKED_PARAM_NAMES = {
   background: 'background',
   seed: 'seed',
+  steps: 'steps',
+  strength: 'image_strength',
   references: 'input_references',
 } as const;
 
@@ -218,7 +226,11 @@ export class ImageClient {
 
     // The local shim serves no `.../endpoints` metadata; declare what it honors.
     if (this.provider === 'local') {
-      const local: ImageModelCapabilities = { model, supportedParameters: new Set(['seed', IMAGE_CHECKED_PARAM_NAMES.references]), raw: {} };
+      const local: ImageModelCapabilities = {
+        model,
+        supportedParameters: new Set(['seed', IMAGE_CHECKED_PARAM_NAMES.steps, IMAGE_CHECKED_PARAM_NAMES.strength, IMAGE_CHECKED_PARAM_NAMES.references]),
+        raw: {},
+      };
       this.capabilitiesCache.set(model, local);
       return local;
     }
@@ -259,6 +271,14 @@ export class ImageClient {
       delete filtered.seed;
       dropped.push(IMAGE_CHECKED_PARAM_NAMES.seed);
     }
+    if (filtered.steps !== undefined && !caps.supportedParameters.has(IMAGE_CHECKED_PARAM_NAMES.steps)) {
+      delete filtered.steps;
+      dropped.push(IMAGE_CHECKED_PARAM_NAMES.steps);
+    }
+    if (filtered.strength !== undefined && !caps.supportedParameters.has(IMAGE_CHECKED_PARAM_NAMES.strength)) {
+      delete filtered.strength;
+      dropped.push(IMAGE_CHECKED_PARAM_NAMES.strength);
+    }
     if (
       filtered.references !== undefined &&
       filtered.references.length > 0 &&
@@ -289,6 +309,7 @@ export class ImageClient {
     if (opts.quality !== undefined) requestBody.quality = opts.quality;
     if (opts.background !== undefined) requestBody.background = opts.background;
     if (opts.seed !== undefined) requestBody.seed = opts.seed;
+    if (opts.steps !== undefined) requestBody.steps = opts.steps;
     if (opts.references !== undefined && opts.references.length > 0) {
       requestBody.input_references = opts.references.map((r) => ({ type: 'image_url', image_url: { url: r.url } }));
     }
@@ -318,6 +339,8 @@ export class ImageClient {
     if (opts.n !== undefined) requestBody.n = opts.n;
     if (opts.size !== undefined) requestBody.size = opts.size;
     if (opts.seed !== undefined) requestBody.seed = opts.seed;
+    if (opts.steps !== undefined) requestBody.steps = opts.steps;
+    if (opts.strength !== undefined) requestBody.image_strength = opts.strength;
     if (opts.references !== undefined && opts.references.length > 0) {
       requestBody.input_references = opts.references.map((r) => ({ type: 'image_url', image_url: { url: r.url } }));
     }

package/src/index.ts

@@ -59,7 +59,9 @@ export {
   TokenTracker,
   getGlobalTokenTracker,
   resetGlobalTokenTracker,
+  estimateCostUSD,
   type TokenUsage,
+  type EstimateCostTokens,
 } from './token-tracker.js';
 
 export {
@@ -158,4 +160,27 @@ export {
   type RankedEdit,
   type RankEditsResult,
   type MasarHealthResult,
+  JevProvider,
+  JevError,
+  getJevProvider,
+  resetJevProvider,
+  isJevAvailable,
+  JEV_MODELS,
+  JEV_DECISIONS_URL,
+  type JevModelId,
+  type JevJsonValue,
+  type JevState,
+  type JevNoulQuestion,
+  type JevChoiceQuestion,
+  type JevScoreQuestion,
+  type JevQuestion,
+  type JevNoulAnswer,
+  type JevChoiceAnswer,
+  type JevScoreAnswer,
+  type JevAnswer,
+  type JevDecideRequest,
+  type JevUsage,
+  type JevDecideResult,
+  type JevProviderOptions,
+  type JevHealthResult,
 } from './providers/index.js';

package/src/providers/index.ts

@@ -22,3 +22,29 @@ export {
   type RankEditsResult,
   type MasarHealthResult,
 } from './masar.js';
+
+export {
+  JevProvider,
+  JevError,
+  getJevProvider,
+  resetJevProvider,
+  isJevAvailable,
+  JEV_MODELS,
+  JEV_DECISIONS_URL,
+  type JevModelId,
+  type JevJsonValue,
+  type JevState,
+  type JevNoulQuestion,
+  type JevChoiceQuestion,
+  type JevScoreQuestion,
+  type JevQuestion,
+  type JevNoulAnswer,
+  type JevChoiceAnswer,
+  type JevScoreAnswer,
+  type JevAnswer,
+  type JevDecideRequest,
+  type JevUsage,
+  type JevDecideResult,
+  type JevProviderOptions,
+  type JevHealthResult,
+} from './jev.js';

package/src/providers/jev.ts

@@ -0,0 +1,456 @@
+/**
+ * Jev Provider
+ *
+ * Thin HTTP client for TypeSafe's "System One" decision model on OpenRouter.
+ * Not a chat model — `POST /api/alpha/decisions`, one or more `noul` / `choice`
+ * / `score` questions batched into a single round-trip. No temperature/top_p/
+ * max_tokens, no streaming, no system prompt.
+ *
+ * See docs/Almadar_Rabit.md § "Jev decision provider" for the verified contract.
+ *
+ * @packageDocumentation
+ */
+
+import { getGlobalTokenTracker } from '../token-tracker.js';
+
+// ============================================================================
+// Models
+// ============================================================================
+
+export const JEV_MODELS = {
+  JEV_1_13: 'typesafe/jev-1.13',
+  JEV_LATEST: '~typesafe/jev-latest',
+} as const;
+
+export type JevModelId = (typeof JEV_MODELS)[keyof typeof JEV_MODELS];
+
+export const JEV_DECISIONS_URL = 'https://openrouter.ai/api/alpha/decisions';
+
+const JEV_MODELS_BASE_URL = 'https://openrouter.ai/api/v1/models';
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+// ============================================================================
+// JSON value (recursive, not Record<string, unknown> — repo lint bans that)
+// ============================================================================
+
+export type JevJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JevJsonValue[]
+  | { [key: string]: JevJsonValue };
+
+export type JevState = string | Record<string, JevJsonValue>;
+
+// ============================================================================
+// Questions
+// ============================================================================
+
+export interface JevNoulQuestion {
+  type: 'noul';
+  /** Must pose the yes/no question directly (docs.typesafe.ai/api, e.g. "Does this convey urgency?") — the noul answer is P(yes) TO THIS TEXT, never a policy paragraph. */
+  instructions: string;
+  /** Optional descriptions of what a yes and a no mean (docs-verified request shape); passed through verbatim to `/api/alpha/decisions`. */
+  criteria?: { true: string; false: string };
+}
+
+export interface JevChoiceQuestion {
+  type: 'choice';
+  instructions: string;
+  criteria: Record<string, string>;
+}
+
+export interface JevScoreQuestion {
+  type: 'score';
+  instructions: string;
+  /** Ordered level descriptions, 2–10 entries (verified docs.typesafe.ai/api). */
+  criteria: string[];
+}
+
+export type JevQuestion = JevNoulQuestion | JevChoiceQuestion | JevScoreQuestion;
+
+// ============================================================================
+// Answers
+// ============================================================================
+
+export interface JevNoulAnswer {
+  type: 'noul';
+  noul: number;
+}
+
+export interface JevChoiceAnswer {
+  type: 'choice';
+  choice: string;
+  probabilities: Record<string, number>;
+  confidence: number;
+}
+
+export interface JevScoreAnswer {
+  type: 'score';
+  score: number;
+  legend: Record<string, string>;
+  probabilities: Record<string, number>;
+  confidence: number;
+}
+
+export type JevAnswer = JevNoulAnswer | JevChoiceAnswer | JevScoreAnswer;
+
+// ============================================================================
+// Request / Result
+// ============================================================================
+
+export interface JevDecideRequest<Q extends Record<string, JevQuestion>> {
+  state: JevState;
+  questions: Q;
+  model?: JevModelId;
+}
+
+export interface JevUsage {
+  inputTokens: number;
+  outputTokens: number;
+  costUSD: number;
+}
+
+// The extends-check must run on JevAnswerFor's OWN naked type parameter, not
+// inline on the indexed access `Q[K]` — a conditional keyed off an indexed
+// access type isn't distributive, so a wide Q (e.g. Record<string,
+// JevQuestion>) would collapse every key to the final `never`/last branch
+// instead of distributing per union member.
+type JevAnswerFor<TQ extends JevQuestion> = TQ extends JevNoulQuestion
+  ? JevNoulAnswer
+  : TQ extends JevChoiceQuestion
+    ? JevChoiceAnswer
+    : TQ extends JevScoreQuestion
+      ? JevScoreAnswer
+      : never;
+
+type JevAnswersOf<Q extends Record<string, JevQuestion>> = {
+  [K in keyof Q]: JevAnswerFor<Q[K]>;
+};
+
+export interface JevDecideResult<Q extends Record<string, JevQuestion>> {
+  answers: JevAnswersOf<Q>;
+  model: string;
+  id: string;
+  provider: string;
+  usage: JevUsage;
+  durationMs: number;
+}
+
+export interface JevProviderOptions {
+  apiKey?: string;
+  model?: JevModelId;
+  baseUrl?: string;
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+}
+
+export interface JevHealthResult {
+  ok: boolean;
+  model: string;
+  endpoints: number;
+}
+
+// ============================================================================
+// Error
+// ============================================================================
+
+export class JevError extends Error {
+  constructor(
+    message: string,
+    public readonly status?: number,
+    public readonly body?: string,
+  ) {
+    super(message);
+    this.name = 'JevError';
+  }
+}
+
+// ============================================================================
+// Runtime validation — parse untrusted JSON into narrow local types via
+// explicit checks, never `as any` / `as unknown as X`.
+// ============================================================================
+
+function isRecord(value: unknown): value is { [key: string]: unknown } {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isNumberRecord(value: unknown): value is Record<string, number> {
+  return isRecord(value) && Object.values(value).every((v) => typeof v === 'number');
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return isRecord(value) && Object.values(value).every((v) => typeof v === 'string');
+}
+
+function isNoulAnswer(value: unknown): value is JevNoulAnswer {
+  return isRecord(value) && value.type === 'noul' && typeof value.noul === 'number';
+}
+
+function isChoiceAnswer(value: unknown): value is JevChoiceAnswer {
+  return (
+    isRecord(value) &&
+    value.type === 'choice' &&
+    typeof value.choice === 'string' &&
+    typeof value.confidence === 'number' &&
+    isNumberRecord(value.probabilities)
+  );
+}
+
+function isScoreAnswer(value: unknown): value is JevScoreAnswer {
+  return (
+    isRecord(value) &&
+    value.type === 'score' &&
+    typeof value.score === 'number' &&
+    typeof value.confidence === 'number' &&
+    isStringRecord(value.legend) &&
+    isNumberRecord(value.probabilities)
+  );
+}
+
+function isJevAnswer(value: unknown): value is JevAnswer {
+  return isNoulAnswer(value) || isChoiceAnswer(value) || isScoreAnswer(value);
+}
+
+interface JevWireBody {
+  model: string;
+  id: string;
+  provider: string;
+  answers: Record<string, JevAnswer>;
+  usage: { inputTokens: number; outputTokens: number; cost: number };
+}
+
+function parseWireBody(value: unknown, status: number, rawBody: string): JevWireBody {
+  if (!isRecord(value)) {
+    throw new JevError('Jev decide: response body is not a JSON object', status, rawBody);
+  }
+  const { model, id, provider, answers, usage } = value;
+  if (typeof model !== 'string') {
+    throw new JevError('Jev decide: response is missing string "model"', status, rawBody);
+  }
+  if (typeof id !== 'string') {
+    throw new JevError('Jev decide: response is missing string "id"', status, rawBody);
+  }
+  if (typeof provider !== 'string') {
+    throw new JevError('Jev decide: response is missing string "provider"', status, rawBody);
+  }
+  if (!isRecord(answers)) {
+    throw new JevError('Jev decide: response is missing an "answers" object', status, rawBody);
+  }
+  if (!isRecord(usage)) {
+    throw new JevError('Jev decide: response is missing a "usage" object', status, rawBody);
+  }
+  const { input_tokens: inputTokens, output_tokens: outputTokens, cost } = usage;
+  if (typeof inputTokens !== 'number' || typeof outputTokens !== 'number' || typeof cost !== 'number') {
+    throw new JevError('Jev decide: "usage" is missing input_tokens/output_tokens/cost', status, rawBody);
+  }
+
+  const parsedAnswers: Record<string, JevAnswer> = {};
+  for (const [key, answer] of Object.entries(answers)) {
+    if (!isJevAnswer(answer)) {
+      throw new JevError(`Jev decide: answer "${key}" has an invalid or unrecognized shape`, status, rawBody);
+    }
+    parsedAnswers[key] = answer;
+  }
+
+  return { model, id, provider, answers: parsedAnswers, usage: { inputTokens, outputTokens, cost } };
+}
+
+// ============================================================================
+// Provider
+// ============================================================================
+
+export class JevProvider {
+  private readonly apiKeyOverride: string | undefined;
+  private readonly defaultModel: JevModelId;
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options?: JevProviderOptions) {
+    this.apiKeyOverride = options?.apiKey;
+    this.defaultModel = options?.model ?? JEV_MODELS.JEV_1_13;
+    this.baseUrl = options?.baseUrl ?? JEV_DECISIONS_URL;
+    this.timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.fetchImpl = options?.fetchImpl ?? fetch;
+  }
+
+  /**
+   * Answer one or more `noul` / `choice` / `score` questions about `state`
+   * in a single round-trip.
+   *
+   * POST /api/alpha/decisions
+   */
+  async decide<Q extends Record<string, JevQuestion>>(
+    req: JevDecideRequest<Q>,
+  ): Promise<JevDecideResult<Q>> {
+    const apiKey = this.resolveApiKey();
+    const model = req.model ?? this.defaultModel;
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    const startedAt = Date.now();
+
+    let response: Response;
+    try {
+      response = await this.fetchImpl(this.baseUrl, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ model, state: req.state, questions: req.questions }),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      clearTimeout(timer);
+      if (error instanceof DOMException && error.name === 'AbortError') {
+        throw new JevError(`Jev decide timed out after ${this.timeoutMs}ms`);
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      throw new JevError(`Jev decide request failed: ${message}`);
+    }
+    clearTimeout(timer);
+
+    const rawBody = await response.text();
+    const durationMs = Date.now() - startedAt;
+
+    if (!response.ok) {
+      throw new JevError(`Jev decide failed with status ${response.status}`, response.status, rawBody);
+    }
+
+    let parsedJson: unknown;
+    try {
+      parsedJson = JSON.parse(rawBody);
+    } catch {
+      throw new JevError('Jev decide: response body is not valid JSON', response.status, rawBody);
+    }
+
+    const wire = parseWireBody(parsedJson, response.status, rawBody);
+
+    const answers: Record<string, JevAnswer> = {};
+    for (const key of Object.keys(req.questions)) {
+      const question = req.questions[key];
+      const answer = wire.answers[key];
+      if (!answer) {
+        throw new JevError(`Jev decide: missing answer for question "${key}"`, response.status, rawBody);
+      }
+      if (answer.type !== question.type) {
+        throw new JevError(
+          `Jev decide: answer "${key}" has type "${answer.type}", expected "${question.type}"`,
+          response.status,
+          rawBody,
+        );
+      }
+      if (answer.type === 'choice' && question.type === 'choice' && !(answer.choice in question.criteria)) {
+        throw new JevError(
+          `Jev decide: answer "${key}" chose "${answer.choice}", which is not one of the declared criteria`,
+          response.status,
+          rawBody,
+        );
+      }
+      answers[key] = answer;
+    }
+
+    getGlobalTokenTracker(model).addUsage(wire.usage.inputTokens, wire.usage.outputTokens, {
+      provider: 'jev',
+      durationMs,
+      // Jev is absent from OpenRouter's /api/v1/models catalog, so cost must
+      // come from the decisions endpoint's own authoritative usage.cost.
+      costUSD: wire.usage.cost,
+    });
+
+    return {
+      // Unavoidable: Object.keys(req.questions) erases each key to plain
+      // `string`, so TS can't prove a loop-built object satisfies the
+      // generic mapped type JevAnswersOf<Q> per key — this one assertion
+      // follows the per-key runtime validation (present, type, criteria) above.
+      answers: answers as JevAnswersOf<Q>,
+      model: wire.model,
+      id: wire.id,
+      provider: wire.provider,
+      usage: {
+        inputTokens: wire.usage.inputTokens,
+        outputTokens: wire.usage.outputTokens,
+        costUSD: wire.usage.cost,
+      },
+      durationMs,
+    };
+  }
+
+  /**
+   * Check the model is servable. `~typesafe/jev-latest` legitimately reports
+   * `endpoints: []` yet still works as a `model` value, so `ok` tracks HTTP
+   * 200 only — an empty endpoint list is never treated as "down".
+   *
+   * GET /api/v1/models/<model>/endpoints
+   */
+  async health(): Promise<JevHealthResult> {
+    const apiKey = this.resolveApiKey();
+    const model = this.defaultModel;
+    const url = `${JEV_MODELS_BASE_URL}/${model}/endpoints`;
+
+    let response: Response;
+    try {
+      response = await this.fetchImpl(url, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+      });
+    } catch {
+      return { ok: false, model, endpoints: 0 };
+    }
+    if (!response.ok) {
+      return { ok: false, model, endpoints: 0 };
+    }
+
+    let endpoints = 0;
+    try {
+      const parsed: unknown = JSON.parse(await response.text());
+      if (isRecord(parsed) && isRecord(parsed.data) && Array.isArray(parsed.data.endpoints)) {
+        endpoints = parsed.data.endpoints.length;
+      }
+    } catch {
+      // Non-JSON body: still HTTP 200, so `ok` stays true with endpoints 0.
+    }
+    return { ok: true, model, endpoints };
+  }
+
+  private resolveApiKey(): string {
+    const apiKey = this.apiKeyOverride ?? process.env.OPENROUTER_API_KEY ?? process.env.OPEN_ROUTER_API_KEY;
+    if (!apiKey) {
+      throw new JevError(
+        'Jev: no API key. Set OPENROUTER_API_KEY (or OPEN_ROUTER_API_KEY) in the environment, or pass { apiKey } to JevProvider.',
+      );
+    }
+    return apiKey;
+  }
+}
+
+// ============================================================================
+// Singleton
+// ============================================================================
+
+let sharedInstance: JevProvider | null = null;
+
+/**
+ * Get the singleton Jev provider instance.
+ *
+ * Creates the instance on first call, returns cached instance thereafter.
+ *
+ * @param {JevProviderOptions} [options] - Provider configuration options
+ * @returns {JevProvider} The Jev provider instance
+ */
+export function getJevProvider(options?: JevProviderOptions): JevProvider {
+  if (!sharedInstance) {
+    sharedInstance = new JevProvider(options);
+  }
+  return sharedInstance;
+}
+
+export function resetJevProvider(): void {
+  sharedInstance = null;
+}
+
+export function isJevAvailable(): boolean {
+  return Boolean(process.env.OPENROUTER_API_KEY ?? process.env.OPEN_ROUTER_API_KEY);
+}