@omnicross/core 0.1.1 → 0.1.2

package/dist/usage/pricing-engine.cjs

@@ -0,0 +1,6 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkYMFAJFQTcjs = require('../chunk-YMFAJFQT.cjs');
+
+
+exports.PricingEngine = _chunkYMFAJFQTcjs.PricingEngine;

package/dist/usage/pricing-engine.d.cts

@@ -0,0 +1,83 @@
+import { PricingEntry, PricingEntryInput, PricingFetchResult, PricingConflictDecision, PricingResolution } from '@omnicross/contracts/pricing-types';
+import { UsageTokens } from '@omnicross/contracts/usage-types';
+import { L as Logger } from '../logger-4GvQNzhE.cjs';
+import { PricingStore } from '../ports/pricing-store.cjs';
+
+/**
+ * PricingEngine — manages model pricing and computes per-event cost.
+ *
+ * Persistence goes through the injected `PricingStore` port. Sources of
+ * pricing rows:
+ *  - 'builtin'  — bundled fallback prices, seeded by the host
+ *  - 'litellm'  — refreshed on user demand from LiteLLM's public JSON
+ *  - 'user'     — hand-edited; protected from auto-overwrite
+ *
+ * @module usage/pricing-engine
+ */
+
+/** Output of `calculateCost`. */
+interface CostCalculation {
+    costUsd: number;
+    /**
+     * Difference between hypothetical-no-cache cost (charging cacheReadTokens at
+     * the full input price) and the actual cost (charging at the cache_read price).
+     * Always ≥ 0.
+     */
+    costSavedByCacheUsd: number;
+}
+/** Optional knobs (mostly for tests). */
+interface PricingEngineOptions {
+    /** Override the pricing-source JSON URL — useful for testing. */
+    sourceUrl?: string;
+    /** Override `fetch` — useful for testing. */
+    fetchImpl?: typeof fetch;
+}
+declare class PricingEngine {
+    private store;
+    private logger;
+    private options;
+    private cache;
+    /**
+     * Secondary index keyed by modelId alone. Used as a fallback when no exact
+     * (providerId, modelId) match exists — usage may be recorded under a
+     * runtime provider alias while pricing rows use the canonical provider id,
+     * so matching by model name lets the price still resolve. First
+     * non-wildcard entry per model wins.
+     */
+    private cacheByModel;
+    private cacheLoaded;
+    constructor(store: PricingStore, logger: Logger, options?: PricingEngineOptions);
+    /** Lazy-load and cache the full pricing table. */
+    private ensureCache;
+    /** Force a cache refresh — call after any write. */
+    invalidateCache(): Promise<void>;
+    getAll(): Promise<PricingEntry[]>;
+    /**
+     * Look up a price for (provider, model). Resolution order:
+     *   1. exact (providerId, modelId)
+     *   2. wildcard provider ('*', modelId)
+     *   3. model name alone (any provider) — tolerates a runtime-alias vs
+     *      canonical provider-id mismatch for the same model.
+     */
+    getEntry(providerId: string, modelId: string): Promise<PricingEntry | null>;
+    /**
+     * Compute the cost (and cache savings) for a single response.
+     *
+     * Cost formula (USD):
+     *   cost = (input  * inputPrice
+     *         + output * outputPrice
+     *         + cacheRead  * (cacheReadPrice  ?? inputPrice)
+     *         + cacheWrite * (cacheWritePrice ?? inputPrice)
+     *        ) / 1e6
+     *
+     * Cache savings:
+     *   savings = cacheRead * (inputPrice - cacheReadPrice) / 1e6
+     *           — clamped at 0 if cacheReadPrice is null or ≥ inputPrice.
+     */
+    calculateCost(providerId: string, modelId: string, usage: UsageTokens): Promise<CostCalculation>;
+    upsertManual(input: PricingEntryInput): Promise<PricingEntry>;
+    fetchLatestFromSource(): Promise<PricingFetchResult>;
+    resolveConflicts(decisions: PricingConflictDecision[], pendingIncoming: Map<string, PricingEntryInput>): Promise<PricingResolution>;
+}
+
+export { type CostCalculation, PricingEngine, type PricingEngineOptions };

package/dist/usage/pricing-engine.d.ts

@@ -0,0 +1,83 @@
+import { PricingEntry, PricingEntryInput, PricingFetchResult, PricingConflictDecision, PricingResolution } from '@omnicross/contracts/pricing-types';
+import { UsageTokens } from '@omnicross/contracts/usage-types';
+import { L as Logger } from '../logger-4GvQNzhE.js';
+import { PricingStore } from '../ports/pricing-store.js';
+
+/**
+ * PricingEngine — manages model pricing and computes per-event cost.
+ *
+ * Persistence goes through the injected `PricingStore` port. Sources of
+ * pricing rows:
+ *  - 'builtin'  — bundled fallback prices, seeded by the host
+ *  - 'litellm'  — refreshed on user demand from LiteLLM's public JSON
+ *  - 'user'     — hand-edited; protected from auto-overwrite
+ *
+ * @module usage/pricing-engine
+ */
+
+/** Output of `calculateCost`. */
+interface CostCalculation {
+    costUsd: number;
+    /**
+     * Difference between hypothetical-no-cache cost (charging cacheReadTokens at
+     * the full input price) and the actual cost (charging at the cache_read price).
+     * Always ≥ 0.
+     */
+    costSavedByCacheUsd: number;
+}
+/** Optional knobs (mostly for tests). */
+interface PricingEngineOptions {
+    /** Override the pricing-source JSON URL — useful for testing. */
+    sourceUrl?: string;
+    /** Override `fetch` — useful for testing. */
+    fetchImpl?: typeof fetch;
+}
+declare class PricingEngine {
+    private store;
+    private logger;
+    private options;
+    private cache;
+    /**
+     * Secondary index keyed by modelId alone. Used as a fallback when no exact
+     * (providerId, modelId) match exists — usage may be recorded under a
+     * runtime provider alias while pricing rows use the canonical provider id,
+     * so matching by model name lets the price still resolve. First
+     * non-wildcard entry per model wins.
+     */
+    private cacheByModel;
+    private cacheLoaded;
+    constructor(store: PricingStore, logger: Logger, options?: PricingEngineOptions);
+    /** Lazy-load and cache the full pricing table. */
+    private ensureCache;
+    /** Force a cache refresh — call after any write. */
+    invalidateCache(): Promise<void>;
+    getAll(): Promise<PricingEntry[]>;
+    /**
+     * Look up a price for (provider, model). Resolution order:
+     *   1. exact (providerId, modelId)
+     *   2. wildcard provider ('*', modelId)
+     *   3. model name alone (any provider) — tolerates a runtime-alias vs
+     *      canonical provider-id mismatch for the same model.
+     */
+    getEntry(providerId: string, modelId: string): Promise<PricingEntry | null>;
+    /**
+     * Compute the cost (and cache savings) for a single response.
+     *
+     * Cost formula (USD):
+     *   cost = (input  * inputPrice
+     *         + output * outputPrice
+     *         + cacheRead  * (cacheReadPrice  ?? inputPrice)
+     *         + cacheWrite * (cacheWritePrice ?? inputPrice)
+     *        ) / 1e6
+     *
+     * Cache savings:
+     *   savings = cacheRead * (inputPrice - cacheReadPrice) / 1e6
+     *           — clamped at 0 if cacheReadPrice is null or ≥ inputPrice.
+     */
+    calculateCost(providerId: string, modelId: string, usage: UsageTokens): Promise<CostCalculation>;
+    upsertManual(input: PricingEntryInput): Promise<PricingEntry>;
+    fetchLatestFromSource(): Promise<PricingFetchResult>;
+    resolveConflicts(decisions: PricingConflictDecision[], pendingIncoming: Map<string, PricingEntryInput>): Promise<PricingResolution>;
+}
+
+export { type CostCalculation, PricingEngine, type PricingEngineOptions };

package/dist/usage/pricing-engine.js

@@ -0,0 +1,6 @@
+import {
+  PricingEngine
+} from "../chunk-ZLX3KGXX.js";
+export {
+  PricingEngine
+};

package/dist/usage/usage-recorder.cjs

@@ -0,0 +1,6 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkXBSYYZIYcjs = require('../chunk-XBSYYZIY.cjs');
+
+
+exports.UsageRecorder = _chunkXBSYYZIYcjs.UsageRecorder;

package/dist/usage/usage-recorder.d.cts

@@ -0,0 +1,73 @@
+import { PricingEngine } from './pricing-engine.cjs';
+import { UsageDateRange, UsageTotals, ModelUsageRow, ApiKeyUsageRow, MessageUsageRow, SessionCacheStats } from '@omnicross/contracts/usage-stats-types';
+import { UsageEngineOrigin, UsageTokens } from '@omnicross/contracts/usage-types';
+import { L as Logger } from '../logger-4GvQNzhE.cjs';
+import { UsageEventStore } from '../ports/usage-event-store.cjs';
+import '@omnicross/contracts/pricing-types';
+import '../ports/pricing-store.cjs';
+
+/**
+ * UsageRecorder — funnels every captured LLM-request event through cost
+ * calculation and persists it via the injected `UsageEventStore`.
+ *
+ * Capture taps call `record()` synchronously with the parsed usage data. The
+ * store insert is enqueued via an injectable deferral function (default: a
+ * zero-delay timer; Node hosts may inject `setImmediate`) so the response path
+ * is never blocked on disk I/O.
+ *
+ * @module usage/usage-recorder
+ */
+
+/** Subset of fields the caller MUST provide. Recorder fills cost (store fills ts). */
+interface UsageRecordInput {
+    messageId?: string | null;
+    parentMessageId?: string | null;
+    sessionId?: string | null;
+    providerId: string;
+    model: string;
+    apiKeyId?: string | null;
+    engineOrigin: UsageEngineOrigin;
+    usage: UsageTokens;
+    /** Optional raw provider usage block — kept verbatim for forensics. */
+    rawUsage?: unknown;
+    /** Host run-correlation id. Optional / additive. */
+    runId?: string | null;
+    /** Host event-correlation id for this call. Optional / additive. */
+    eventId?: string | null;
+}
+/** Optional knobs (mostly for hosts/tests). */
+interface UsageRecorderOptions {
+    /**
+     * Deferral function used by `record()` to schedule the async persist off
+     * the caller's path. Defaults to a zero-delay timer; Node hosts may inject
+     * `setImmediate` to preserve their exact scheduling.
+     */
+    defer?: (fn: () => void) => void;
+}
+declare class UsageRecorder {
+    private store;
+    private pricing;
+    private logger;
+    private defer;
+    constructor(store: UsageEventStore, pricing: PricingEngine, logger: Logger, options?: UsageRecorderOptions);
+    /**
+     * Record one LLM request. Returns immediately — the actual store insert is
+     * deferred so the caller's response path is unblocked.
+     *
+     * Errors during the insert are logged but never thrown.
+     */
+    record(input: UsageRecordInput): void;
+    /**
+     * Same as `record()` but awaitable — preferred in tests so they can assert
+     * after the row exists.
+     */
+    recordAsync(input: UsageRecordInput): Promise<string | null>;
+    getTotals(range: UsageDateRange): Promise<UsageTotals>;
+    getByModel(range: UsageDateRange): Promise<ModelUsageRow[]>;
+    getByApiKey(range: UsageDateRange): Promise<ApiKeyUsageRow[]>;
+    getMessagesForSession(sessionId: string): Promise<MessageUsageRow[]>;
+    /** Cumulative cache hit/miss stats for one session. */
+    getSessionCacheStats(sessionId: string): Promise<SessionCacheStats>;
+}
+
+export { type UsageRecordInput, UsageRecorder, type UsageRecorderOptions };

package/dist/usage/usage-recorder.d.ts

@@ -0,0 +1,73 @@
+import { PricingEngine } from './pricing-engine.js';
+import { UsageDateRange, UsageTotals, ModelUsageRow, ApiKeyUsageRow, MessageUsageRow, SessionCacheStats } from '@omnicross/contracts/usage-stats-types';
+import { UsageEngineOrigin, UsageTokens } from '@omnicross/contracts/usage-types';
+import { L as Logger } from '../logger-4GvQNzhE.js';
+import { UsageEventStore } from '../ports/usage-event-store.js';
+import '@omnicross/contracts/pricing-types';
+import '../ports/pricing-store.js';
+
+/**
+ * UsageRecorder — funnels every captured LLM-request event through cost
+ * calculation and persists it via the injected `UsageEventStore`.
+ *
+ * Capture taps call `record()` synchronously with the parsed usage data. The
+ * store insert is enqueued via an injectable deferral function (default: a
+ * zero-delay timer; Node hosts may inject `setImmediate`) so the response path
+ * is never blocked on disk I/O.
+ *
+ * @module usage/usage-recorder
+ */
+
+/** Subset of fields the caller MUST provide. Recorder fills cost (store fills ts). */
+interface UsageRecordInput {
+    messageId?: string | null;
+    parentMessageId?: string | null;
+    sessionId?: string | null;
+    providerId: string;
+    model: string;
+    apiKeyId?: string | null;
+    engineOrigin: UsageEngineOrigin;
+    usage: UsageTokens;
+    /** Optional raw provider usage block — kept verbatim for forensics. */
+    rawUsage?: unknown;
+    /** Host run-correlation id. Optional / additive. */
+    runId?: string | null;
+    /** Host event-correlation id for this call. Optional / additive. */
+    eventId?: string | null;
+}
+/** Optional knobs (mostly for hosts/tests). */
+interface UsageRecorderOptions {
+    /**
+     * Deferral function used by `record()` to schedule the async persist off
+     * the caller's path. Defaults to a zero-delay timer; Node hosts may inject
+     * `setImmediate` to preserve their exact scheduling.
+     */
+    defer?: (fn: () => void) => void;
+}
+declare class UsageRecorder {
+    private store;
+    private pricing;
+    private logger;
+    private defer;
+    constructor(store: UsageEventStore, pricing: PricingEngine, logger: Logger, options?: UsageRecorderOptions);
+    /**
+     * Record one LLM request. Returns immediately — the actual store insert is
+     * deferred so the caller's response path is unblocked.
+     *
+     * Errors during the insert are logged but never thrown.
+     */
+    record(input: UsageRecordInput): void;
+    /**
+     * Same as `record()` but awaitable — preferred in tests so they can assert
+     * after the row exists.
+     */
+    recordAsync(input: UsageRecordInput): Promise<string | null>;
+    getTotals(range: UsageDateRange): Promise<UsageTotals>;
+    getByModel(range: UsageDateRange): Promise<ModelUsageRow[]>;
+    getByApiKey(range: UsageDateRange): Promise<ApiKeyUsageRow[]>;
+    getMessagesForSession(sessionId: string): Promise<MessageUsageRow[]>;
+    /** Cumulative cache hit/miss stats for one session. */
+    getSessionCacheStats(sessionId: string): Promise<SessionCacheStats>;
+}
+
+export { type UsageRecordInput, UsageRecorder, type UsageRecorderOptions };

package/dist/usage/usage-recorder.js

@@ -0,0 +1,6 @@
+import {
+  UsageRecorder
+} from "../chunk-MNYKI4CI.js";
+export {
+  UsageRecorder
+};

package/dist/usage.cjs

@@ -0,0 +1,11 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});require('./chunk-EYZYXJTJ.cjs');
+
+
+var _chunkYMFAJFQTcjs = require('./chunk-YMFAJFQT.cjs');
+
+
+var _chunkXBSYYZIYcjs = require('./chunk-XBSYYZIY.cjs');
+
+
+
+exports.PricingEngine = _chunkYMFAJFQTcjs.PricingEngine; exports.UsageRecorder = _chunkXBSYYZIYcjs.UsageRecorder;

package/dist/usage.d.cts

@@ -0,0 +1,8 @@
+export { CostCalculation, PricingEngine, PricingEngineOptions } from './usage/pricing-engine.cjs';
+export { UsageRecordInput, UsageRecorder, UsageRecorderOptions } from './usage/usage-recorder.cjs';
+import '@omnicross/contracts/pricing-types';
+import '@omnicross/contracts/usage-types';
+import './logger-4GvQNzhE.cjs';
+import './ports/pricing-store.cjs';
+import '@omnicross/contracts/usage-stats-types';
+import './ports/usage-event-store.cjs';

package/dist/usage.d.ts

@@ -0,0 +1,8 @@
+export { CostCalculation, PricingEngine, PricingEngineOptions } from './usage/pricing-engine.js';
+export { UsageRecordInput, UsageRecorder, UsageRecorderOptions } from './usage/usage-recorder.js';
+import '@omnicross/contracts/pricing-types';
+import '@omnicross/contracts/usage-types';
+import './logger-4GvQNzhE.js';
+import './ports/pricing-store.js';
+import '@omnicross/contracts/usage-stats-types';
+import './ports/usage-event-store.js';

package/dist/usage.js

@@ -0,0 +1,11 @@
+import "./chunk-7VU7V2E4.js";
+import {
+  PricingEngine
+} from "./chunk-ZLX3KGXX.js";
+import {
+  UsageRecorder
+} from "./chunk-MNYKI4CI.js";
+export {
+  PricingEngine,
+  UsageRecorder
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnicross/core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Omnicross LLM serving core — provider dispatch, completion pipeline, transformers, and the provider proxy.",
   "license": "MIT",
   "author": "Sayo (https://github.com/Dumoedss)",

package/dist/ApiKeyPoolService-BmMkau07.d.cts

@@ -1,170 +0,0 @@
-import { ApiKeyEntry } from '@omnicross/contracts/llm-config';
-
-/**
- * `Logger` — core-owned port for the structured logger the serving core uses.
- *
- * The serving core MUST depend on THIS interface, never on the concrete host
- * `LoggerService` class as a type. The host (`LoggerService`) already exposes a
- * superset of this surface, so it is passed directly with NO adapter.
- *
- * `error` uses the WIDEST signature `(message, error?, meta?)` so every core
- * call site — `error(msg)`, `error(msg, errInstance)`, `error(msg, err, meta)` —
- * stays assignable (design Q2). `info`/`warn`/`debug` take an optional `meta`
- * bag matching the host's `Record<string, unknown> | Error | object`.
- *
- * @module ports/logger
- */
-interface Logger {
-    info(message: string, meta?: Record<string, unknown> | Error | object): void;
-    warn(message: string, meta?: Record<string, unknown> | Error | object): void;
-    error(message: string, error?: unknown, meta?: Record<string, unknown> | object): void;
-    debug(message: string, meta?: Record<string, unknown> | Error | object): void;
-}
-
-/**
- * ApiKeyPoolService - Multi-API-key load balancing with session affinity
- *
- * Manages a pool of API keys per provider, selecting keys via weighted
- * round-robin and maintaining session-level key affinity to preserve
- * prompt cache across requests within the same session.
- */
-
-/** Live health snapshot for a single key currently in cooldown. */
-interface KeyHealthEntry {
-    /** Epoch-ms when the cooldown expires */
-    until: number;
-    /** Number of consecutive errors */
-    errors: number;
-    /** HTTP status that triggered the most recent cooldown */
-    lastStatus: number | null;
-}
-/** Provider-scoped map of keyId → live cooldown health (cooling keys only). */
-type KeyHealthMap = Record<string, KeyHealthEntry>;
-/** Function type for loading API keys from the database */
-type ApiKeysLoader = (providerId: string) => Promise<ApiKeyEntry[]>;
-/** Function type for disabling a key in the database (on auth failure) */
-type ApiKeyDisabler = (keyId: string) => Promise<boolean>;
-/**
- * Function type for auto-disabling a key in the database on auth failure,
- * persisting the offending status + timestamp so the client UI can surface
- * a per-key health indicator. Preferred over {@link ApiKeyDisabler} when set.
- */
-type ApiKeyAutoDisabler = (keyId: string, status: number, at: number) => Promise<void>;
-/** Function type for resolving environment variable references in API keys */
-type ApiKeyResolver = (rawKey: string) => string;
-declare class ApiKeyPoolService {
-    private loadKeys;
-    private resolveKey;
-    private logger;
-    private disableKey?;
-    private markAutoDisabled?;
-    /** Session 鈫?key binding (session affinity) */
-    private sessionBindings;
-    /** Provider 鈫?round-robin index */
-    private rrIndex;
-    /** Provider 鈫?cached key list */
-    private keyCache;
-    /** Key ID 鈫?cooldown state */
-    private cooldowns;
-    /** Cleanup interval handle */
-    private cleanupTimer;
-    private readonly DEFAULT_COOLDOWN_MS;
-    private readonly MAX_COOLDOWN_MS;
-    private readonly COOLDOWN_MULTIPLIER;
-    constructor(loadKeys: ApiKeysLoader, resolveKey: ApiKeyResolver, logger: Logger, disableKey?: ApiKeyDisabler | undefined, markAutoDisabled?: ApiKeyAutoDisabler | undefined);
-    /**
-     * Get the API key for a session. Implements session affinity.
-     *
-     * First call for a session binds it to a key via weighted round-robin.
-     * Subsequent calls return the same key (preserves prompt cache).
-     *
-     * @returns Resolved API key string, or empty string if no keys available
-     */
-    /**
-     * Read which key id is currently bound to the given session, if any.
-     * Returns null when the session has not yet been bound (first call hasn't
-     * happened) or when the binding is for a different provider.
-     *
-     * Used by the usage-recorder attribution path: after `getKeyForSession`
-     * completes the caller looks up the keyId so the recorded usage
-     * row can attribute spend to a specific pool key.
-     */
-    getKeyIdForSession(providerId: string, sessionId: string): string | null;
-    getKeyForSession(providerId: string, sessionId: string): Promise<string>;
-    /**
-     * Get a key without session affinity (for one-shot calls like testConnection).
-     *
-     * @returns Resolved API key string, or empty string if no keys available
-     */
-    getKey(providerId: string): Promise<string>;
-    /**
-     * Report an error for the current session's key.
-     *
-     * - 429/529 (rate limit / overload): puts key in cooldown with exponential backoff
-     * - 401/403 (auth failure): permanently disables the key in the database
-     *
-     * In both cases, re-binds the session to a different key if available.
-     *
-     * @param statusCode HTTP status code
-     * @returns New resolved API key if re-binding succeeded, null if no keys available
-     */
-    reportError(providerId: string, sessionId: string, statusCode: number): Promise<string | null>;
-    /**
-     * Report a successful request — resets cooldown counter for the session's key.
-     */
-    reportSuccess(sessionId: string): void;
-    /**
-     * Release session binding (call when session ends or is deleted).
-     */
-    releaseSession(sessionId: string): void;
-    /**
-     * Invalidate the key cache. Call after CRUD operations on API keys.
-     */
-    invalidateCache(providerId?: string): void;
-    /**
-     * Check if a provider has any keys in the pool.
-     */
-    hasKeys(providerId: string): Promise<boolean>;
-    /**
-     * Get the live (in-memory) rate-limit cooldown health for a provider's keys.
-     *
-     * Returns ONLY keys that are currently cooling down (cooldown `until` is in
-     * the future). A key absent from the returned map is not cooling. This is a
-     * pure read of the in-memory cooldown map — auth-failure auto-disable state
-     * is persisted on the key row itself (getApiKeys) and is NOT included here.
-     */
-    getKeyHealth(providerId: string): Promise<KeyHealthMap>;
-    /**
-     * Dispose of the service (stop cleanup timer).
-     */
-    dispose(): void;
-    /**
-     * Handle auth failure (401/403): disable the key in DB permanently.
-     */
-    private handleAuthFailure;
-    /**
-     * Apply cooldown with exponential backoff for rate-limit errors (429/529).
-     */
-    private applyCooldown;
-    /**
-     * Get all keys for a provider (with caching).
-     */
-    private getAllKeys;
-    /**
-     * Get available keys: enabled AND not in cooldown.
-     */
-    private getAvailableKeys;
-    /**
-     * Weighted round-robin selection.
-     *
-     * Each key's weight determines how many "slots" it occupies in the rotation.
-     * The round-robin index advances by 1 on each call per provider.
-     */
-    private selectWeightedRoundRobin;
-    /**
-     * Clean up expired cooldowns.
-     */
-    private cleanupExpiredCooldowns;
-}
-
-export { ApiKeyPoolService as A, type KeyHealthEntry as K, type Logger as L, type ApiKeyAutoDisabler as a, type ApiKeyDisabler as b, type ApiKeyResolver as c, type ApiKeysLoader as d, type KeyHealthMap as e };