@almadar/llm 2.51.0 → 2.53.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/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);
+}

package/src/token-tracker.ts

@@ -169,7 +169,15 @@ function refreshPricingCache(): void {
     });
 }
 
-function getCostForModel(model: string): TokenCost {
+/**
+ * Look up a model's pricing row without a zero-cost fallback — `undefined`
+ * means "no pricing known yet" (OpenRouter fetch pending, or the model
+ * isn't listed), distinct from a model that is genuinely free. Single
+ * lookup path: `getCostForModel` (zero-fallback, for the tracker's own
+ * running totals) and `estimateCostUSD` (pure, callers outside the
+ * tracker) both resolve through this.
+ */
+function getCostForModelIfKnown(model: string): TokenCost | undefined {
   const pricing = getPricing();
   // Try direct match on OpenRouter ID
   const orId = MODEL_ID_MAP[model];
@@ -180,8 +188,64 @@ function getCostForModel(model: string): TokenCost {
   for (const [key, cost] of Object.entries(pricing)) {
     if (key.includes(model) || model.includes(key.split('/')[1] ?? '')) return cost;
   }
+  return undefined;
+}
+
+function getCostForModel(model: string): TokenCost {
   // No pricing available — return zero (OpenRouter fetch pending or model not listed)
-  return { promptCostPer1K: 0, completionCostPer1K: 0 };
+  return getCostForModelIfKnown(model) ?? { promptCostPer1K: 0, completionCostPer1K: 0 };
+}
+
+/** Cache-aware cost formula shared by `TokenTracker.costFor` (instance,
+ *  zero-fallback pricing) and `estimateCostUSD` (pure, `undefined` pricing
+ *  propagates to the caller instead of silently pricing at $0). */
+function priceTokens(
+  costs: TokenCost,
+  promptTokens: number,
+  completionTokens: number,
+  cached: number,
+  written: number,
+): number {
+  const cacheReadRate = costs.cacheReadCostPer1K ?? costs.promptCostPer1K;
+  const cacheWriteRate = costs.cacheWriteCostPer1K ?? costs.promptCostPer1K;
+  const uncached = Math.max(0, promptTokens - cached - written);
+  return (
+    (uncached / 1000) * costs.promptCostPer1K +
+    (cached / 1000) * cacheReadRate +
+    (written / 1000) * cacheWriteRate +
+    (completionTokens / 1000) * costs.completionCostPer1K
+  );
+}
+
+export interface EstimateCostTokens {
+  promptTokens: number;
+  completionTokens: number;
+  /** Subset of `promptTokens` served from the provider's prefix cache. */
+  cachedPromptTokens?: number;
+  /** Subset of `promptTokens` written to cache (Anthropic cache-write). */
+  cacheWriteTokens?: number;
+}
+
+/**
+ * Pure per-call cost estimate from token counts alone, priced from the SAME
+ * OpenRouter-fetched table `TokenTracker` uses for the whole-run total (the
+ * 24h disk cache in `getPricing` — no second pricing source). Callers with
+ * tokens + a model name but no `TokenTracker` instance (e.g. a trace-event
+ * emitter) use this instead of reimplementing the cache-aware math.
+ *
+ * Returns `undefined` when the model has no known pricing row — the
+ * caller's job to render that as "unknown", never as `$0`.
+ */
+export function estimateCostUSD(model: string, tokens: EstimateCostTokens): number | undefined {
+  const costs = getCostForModelIfKnown(model);
+  if (costs === undefined) return undefined;
+  return priceTokens(
+    costs,
+    tokens.promptTokens,
+    tokens.completionTokens,
+    Math.max(0, tokens.cachedPromptTokens ?? 0),
+    Math.max(0, tokens.cacheWriteTokens ?? 0),
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -220,16 +284,7 @@ export class TokenTracker {
 
   /** Cache-aware cost for one (or an aggregate of) call(s), in USD. */
   private costFor(model: string, promptTokens: number, completionTokens: number, cached: number, written: number): number {
-    const costs = getCostForModel(model);
-    const cacheReadRate = costs.cacheReadCostPer1K ?? costs.promptCostPer1K;
-    const cacheWriteRate = costs.cacheWriteCostPer1K ?? costs.promptCostPer1K;
-    const uncached = Math.max(0, promptTokens - cached - written);
-    return (
-      (uncached / 1000) * costs.promptCostPer1K +
-      (cached / 1000) * cacheReadRate +
-      (written / 1000) * cacheWriteRate +
-      (completionTokens / 1000) * costs.completionCostPer1K
-    );
+    return priceTokens(getCostForModel(model), promptTokens, completionTokens, cached, written);
   }
 
   /**