@danypops/jittor 0.16.3 → 0.18.0

package/src/observability/usage-import.ts

@@ -0,0 +1,122 @@
+export interface HistoricalUsageRecord {
+	identity: string;
+	observedAt: number;
+	provider: string;
+	model: string;
+	thinking: string | null;
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	costUsd: number;
+}
+
+export interface HistoricalUsageScan {
+	records: HistoricalUsageRecord[];
+	filesScanned: number;
+	entriesScanned: number;
+	bytesScanned: number;
+	malformedEntries: number;
+	truncated: boolean;
+	canceled: boolean;
+	cursor: string | null;
+}
+
+export interface HistoricalUsageSource {
+	scan(canceled: () => boolean): Promise<HistoricalUsageScan>;
+}
+
+export interface UsageImportResult {
+	dryRun: boolean;
+	discovered: number;
+	imported: number;
+	duplicates: number;
+	filesScanned: number;
+	entriesScanned: number;
+	bytesScanned: number;
+	malformedEntries: number;
+	truncated: boolean;
+	canceled: boolean;
+	cursor: string | null;
+	completedAt: number;
+}
+
+export interface UsageImportStatus {
+	running: boolean;
+	cancelRequested: boolean;
+	lastResult: UsageImportResult | null;
+}
+
+export interface UsageImportStore {
+	import(records: HistoricalUsageRecord[]): { imported: number; duplicates: number };
+	preview(records: HistoricalUsageRecord[]): { duplicates: number };
+	status(): UsageImportStatus;
+	saveStatus(status: UsageImportStatus): void;
+}
+
+export interface UsageImportController {
+	run(input?: { dryRun?: boolean }): Promise<UsageImportResult>;
+	status(): UsageImportStatus;
+	cancel(): UsageImportStatus;
+}
+
+export class HistoricalUsageImporter implements UsageImportController {
+	private cancelRequested = false;
+	private active = 0;
+
+	constructor(
+		private readonly source: HistoricalUsageSource,
+		private readonly store: UsageImportStore,
+		private readonly clock: () => number = Date.now,
+	) {}
+
+	async run(input: { dryRun?: boolean } = {}): Promise<UsageImportResult> {
+		this.cancelRequested = false;
+		this.active += 1;
+		this.persistStatus();
+		try {
+			const scan = await this.source.scan(() => this.cancelRequested);
+			const dryRun = input.dryRun === true;
+			const outcome = dryRun ? { imported: 0, duplicates: this.store.preview(scan.records).duplicates } : this.store.import(scan.records);
+			const result: UsageImportResult = {
+				dryRun,
+				discovered: scan.records.length,
+				...outcome,
+				filesScanned: scan.filesScanned,
+				entriesScanned: scan.entriesScanned,
+				bytesScanned: scan.bytesScanned,
+				malformedEntries: scan.malformedEntries,
+				truncated: scan.truncated,
+				canceled: scan.canceled,
+				cursor: scan.cursor,
+				completedAt: this.clock(),
+			};
+			this.active -= 1;
+			this.store.saveStatus({ running: this.active > 0, cancelRequested: this.cancelRequested, lastResult: result });
+			return result;
+		} catch (error) {
+			this.active -= 1;
+			this.persistStatus();
+			throw error;
+		}
+	}
+
+	status(): UsageImportStatus {
+		const persisted = this.store.status();
+		return { ...persisted, running: this.active > 0, cancelRequested: this.cancelRequested };
+	}
+
+	cancel(): UsageImportStatus {
+		this.cancelRequested = true;
+		this.persistStatus();
+		return this.status();
+	}
+
+	private persistStatus(): void {
+		this.store.saveStatus({
+			running: this.active > 0,
+			cancelRequested: this.cancelRequested,
+			lastResult: this.store.status().lastResult,
+		});
+	}
+}

package/src/openai/token-counter.ts

@@ -0,0 +1,63 @@
+import { normalizeModelIdentity } from "../observability/model-identity.ts";
+import type { TextTokenCounter, TextTokenCountInput, TokenMeasurement } from "../observability/token-measurement.ts";
+
+type OpenAiEncoding = "cl100k_base" | "o200k_base" | "o200k_harmony";
+type EncodeText = (text: string) => ArrayLike<number>;
+
+function openAiModelId(provider: string | undefined, model: string | undefined): string | null {
+	if (provider === undefined || model === undefined) return null;
+	const normalizedProvider = provider.toLowerCase();
+	const normalizedModel = model.toLowerCase();
+	if (["openai", "openai-codex", "azure-openai"].includes(normalizedProvider)) return normalizedModel;
+	if (normalizedProvider === "openrouter" && normalizedModel.startsWith("openai/")) return normalizedModel.slice("openai/".length);
+	return null;
+}
+
+/** Deliberately conservative: an unknown future model falls back instead of guessing an encoding and claiming exact text tokenization. */
+function encodingForOpenAiModel(model: string): OpenAiEncoding | null {
+	if (model.startsWith("gpt-oss-")) return "o200k_harmony";
+	if (/^(?:gpt-5|gpt-4\.1|gpt-4o|chatgpt-4o|o[134](?:-|$))/.test(model)) return "o200k_base";
+	if (/^(?:gpt-4(?:-|$)|gpt-3\.5(?:-|$)|text-embedding-(?:3|ada-002))/.test(model)) return "cl100k_base";
+	return null;
+}
+
+/**
+ * Exact BPE count for the supplied text only. It intentionally does not encode a provider request
+ * envelope, tools, images, cache controls, or chat template, so its provenance is never presented
+ * as exact request usage.
+ */
+export class OpenAiTextTokenCounter implements TextTokenCounter {
+	constructor(
+		private readonly encoding: OpenAiEncoding,
+		private readonly encode: EncodeText,
+	) {}
+
+	countText(input: TextTokenCountInput): TokenMeasurement | null {
+		const modelId = openAiModelId(input.provider, input.model);
+		if (!modelId || encodingForOpenAiModel(modelId) !== this.encoding) return null;
+		const identity = normalizeModelIdentity(input.provider!, input.model!);
+		return {
+			tokens: this.encode(input.text).length,
+			scope: input.scope,
+			provenance: "tokenizer-exact-text",
+			method: `gpt-tokenizer:${this.encoding}`,
+			provider: identity.provider,
+			model: identity.model,
+		};
+	}
+}
+
+/** Loads only the one BPE table required by the requested model, and returns null rather than guessing for an unknown mapping. */
+export async function loadOpenAiTextTokenCounter(provider: string, model: string): Promise<OpenAiTextTokenCounter | null> {
+	const modelId = openAiModelId(provider, model);
+	if (!modelId) return null;
+	const encoding = encodingForOpenAiModel(modelId);
+	if (!encoding) return null;
+	const module =
+		encoding === "o200k_base"
+			? await import("gpt-tokenizer/encoding/o200k_base")
+			: encoding === "o200k_harmony"
+				? await import("gpt-tokenizer/encoding/o200k_harmony")
+				: await import("gpt-tokenizer/encoding/cl100k_base");
+	return new OpenAiTextTokenCounter(encoding, module.encode);
+}

package/src/{adapters/openrouter-benchmark-source.ts → openrouter/benchmark-source.ts}

@@ -9,9 +9,9 @@ import {
 	type BenchmarkSourceSnapshot,
 	normalizeModelIdentity,
 	validateBenchmarkObservation,
-} from "../domain/benchmark.ts";
-import type { BenchmarkSource } from "../ports/benchmark-source.ts";
-import { contractRecord, type OpenRouterModel, parseOpenRouterModels } from "../providers/openrouter-contracts.ts";
+} from "../optimization/model-selection/benchmark.ts";
+import type { BenchmarkSource } from "../optimization/model-selection/source.ts";
+import { contractRecord, type OpenRouterModel, parseOpenRouterModels } from "./contracts.ts";
 
 const OPENROUTER_MODELS_BASE_URL = "https://openrouter.ai/api/v1/models";
 const OPENROUTER_MODELS_URL = `${OPENROUTER_MODELS_BASE_URL}?limit=${BENCHMARK_MAX_MODELS_PER_SOURCE}`;

package/src/{providers/openrouter-contracts.ts → openrouter/contracts.ts}

@@ -1,4 +1,4 @@
-import type { MetricObservation } from "../domain/metric.ts";
+import type { MetricObservation } from "../observability/metric.ts";
 
 export interface OpenRouterUsage {
 	promptTokens: number;

package/src/{adapters/openrouter-design-arena-source.ts → openrouter/design-arena-source.ts}

@@ -4,10 +4,10 @@ import {
 	type BenchmarkSourceSnapshot,
 	normalizeModelIdentity,
 	validateBenchmarkObservation,
-} from "../domain/benchmark.ts";
-import type { BenchmarkSource } from "../ports/benchmark-source.ts";
-import { contractRecord } from "../providers/openrouter-contracts.ts";
-import type { OpenRouterBenchmarkTransport } from "./openrouter-benchmark-source.ts";
+} from "../optimization/model-selection/benchmark.ts";
+import type { BenchmarkSource } from "../optimization/model-selection/source.ts";
+import type { OpenRouterBenchmarkTransport } from "./benchmark-source.ts";
+import { contractRecord } from "./contracts.ts";
 
 const SOURCE_ID = "openrouter-design-arena";
 const BASE_URL = `https://openrouter.ai/api/v1/benchmarks?source=design-arena&max_results=${BENCHMARK_MAX_MODELS_PER_SOURCE}`;

package/src/openrouter/source.ts

@@ -0,0 +1,20 @@
+import type { TelemetryBatch, TelemetrySource } from "../observability/telemetry-source.ts";
+import { OpenRouterTelemetryAdapter, type OpenRouterTransport } from "./telemetry.ts";
+
+export class OpenRouterTelemetrySource implements TelemetrySource {
+	readonly id = "openrouter";
+	readonly provider = "openrouter";
+	readonly required = false;
+
+	constructor(
+		private readonly apiKey: string,
+		private readonly transport: OpenRouterTransport = fetch,
+		private readonly clock: () => number = Date.now,
+	) {}
+
+	async poll(): Promise<TelemetryBatch> {
+		const observedAt = this.clock();
+		const snapshot = await new OpenRouterTelemetryAdapter(this.apiKey, this.transport).readKey(observedAt);
+		return { observedAt, metrics: snapshot.metrics, windows: [] };
+	}
+}

package/src/{providers/openrouter.ts → openrouter/telemetry.ts}

@@ -7,7 +7,7 @@ import {
 	parseOpenRouterGeneration,
 	parseOpenRouterKey,
 	parseOpenRouterModels,
-} from "./openrouter-contracts.ts";
+} from "./contracts.ts";
 
 export {
 	type OpenRouterAnalyticsResult,
@@ -18,7 +18,7 @@ export {
 	type OpenRouterUsageContext,
 	openRouterUsageMetrics,
 	parseOpenRouterUsage,
-} from "./openrouter-contracts.ts";
+} from "./contracts.ts";
 
 const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
 export type OpenRouterTransport = (request: Request) => Promise<Response>;

package/src/{domain → optimization/model-selection}/benchmark.ts

@@ -5,21 +5,17 @@ import {
 	BENCHMARK_MAX_QUERY_LIMIT,
 	BENCHMARK_MAX_TEXT_CHARACTERS,
 	BENCHMARK_REFRESH_INTERVAL_MS,
-} from "../constants.ts";
-import type { BenchmarkController } from "../ports/benchmark-controller.ts";
-import type { BenchmarkSource as BenchmarkSourcePort } from "../ports/benchmark-source.ts";
-import type { BenchmarkStore } from "../ports/benchmark-store.ts";
-import { METRIC_UNITS, type MetricUnit } from "./metric.ts";
+} from "../../constants.ts";
+import { METRIC_UNITS, type MetricUnit } from "../../observability/metric.ts";
+import { type ModelIdentity, normalizeModelIdentity } from "../../observability/model-identity.ts";
+import type { BenchmarkController } from "./controller.ts";
+import type { BenchmarkSource as BenchmarkSourcePort } from "./source.ts";
+import type { BenchmarkStore } from "./store.ts";
 
-export type BenchmarkSourceType = "creator" | "marketplace" | "independent" | "operational" | "preference" | "local";
+export type { ModelIdentity };
+export { normalizeModelIdentity };
 
-export interface ModelIdentity {
-	provider: string;
-	model: string;
-	version: string | null;
-	canonical: string;
-	aliases: string[];
-}
+export type BenchmarkSourceType = "creator" | "marketplace" | "independent" | "operational" | "preference" | "local";
 
 export interface BenchmarkProvenance {
 	sourceId: string;
@@ -89,7 +85,6 @@ export interface BenchmarkCatalogOptions {
 
 export type BenchmarkSource = BenchmarkSourcePort;
 
-const VERSION_SUFFIX = /-(\d{4}-\d{2}-\d{2})$/;
 const SOURCE_TYPES = new Set<BenchmarkSourceType>(["creator", "marketplace", "independent", "operational", "preference", "local"]);
 
 function boundedText(value: unknown, name: string, maximum = BENCHMARK_MAX_TEXT_CHARACTERS): string {
@@ -107,19 +102,6 @@ function identityPart(value: string, name: string, allowPath = false): string {
 	return normalized;
 }
 
-export function normalizeModelIdentity(provider: string, model: string, aliases: string[] = []): ModelIdentity {
-	const normalizedProvider = identityPart(provider, "provider");
-	const normalizedModel = identityPart(model, "model", true);
-	const version = VERSION_SUFFIX.exec(normalizedModel)?.[1] ?? null;
-	const canonical = `${normalizedProvider}/${normalizedModel}`;
-	const normalizedAliases = [
-		...new Set(aliases.map((alias) => boundedText(alias, "alias", BENCHMARK_IDENTITY_MAX_CHARACTERS).toLowerCase())),
-	]
-		.filter((alias) => alias !== canonical)
-		.sort();
-	return { provider: normalizedProvider, model: normalizedModel, version, canonical, aliases: normalizedAliases };
-}
-
 function validateIdentity(value: unknown): ModelIdentity {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("model identity is required");
 	const input = value as Record<string, unknown>;

package/src/optimization/model-selection/catalog-store.ts

@@ -0,0 +1,97 @@
+import { MODEL_CATALOG_MAX_ENTRIES, MODEL_CATALOG_STORE_QUERY_LIMIT } from "../../constants.ts";
+import type { MetricObservation } from "../../observability/metric.ts";
+import type { MetricStore } from "../../observability/store.ts";
+import type { ModelCatalogEntry, ModelCatalogSnapshot, ModelCatalogStore } from "./catalog.ts";
+
+const SOURCE = "catalog:models.dev";
+const SNAPSHOT_SCOPE = "snapshot";
+const COMPLETE_METRIC = "snapshot-complete";
+const ENTRY_METRIC = "model";
+const BATCH_SIZE = 100;
+
+function validEntry(value: unknown): value is ModelCatalogEntry {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const entry = value as Partial<ModelCatalogEntry>;
+	return (
+		typeof entry.provider === "string" &&
+		typeof entry.model === "string" &&
+		typeof entry.canonical === "string" &&
+		Array.isArray(entry.aliases) &&
+		typeof entry.name === "string" &&
+		typeof entry.limits?.context === "number" &&
+		typeof entry.limits?.output === "number" &&
+		typeof entry.fieldAuthority === "object" &&
+		entry.fieldAuthority !== null
+	);
+}
+
+function entryObservation(snapshot: ModelCatalogSnapshot, entry: ModelCatalogEntry): MetricObservation {
+	return {
+		source: SOURCE,
+		scope: entry.canonical,
+		metric: ENTRY_METRIC,
+		value: 1,
+		unit: "count",
+		observedAt: snapshot.provenance.retrievedAt,
+		attributes: { snapshotId: snapshot.snapshotId, entry },
+	};
+}
+
+/** Complete-marker snapshot store: failed/partial writes remain invisible because the marker lands last. */
+export class MetricModelCatalogStore implements ModelCatalogStore {
+	constructor(private readonly metrics: MetricStore) {}
+
+	publish(snapshot: ModelCatalogSnapshot): ModelCatalogSnapshot {
+		if (snapshot.entries.length === 0 || snapshot.entries.length > MODEL_CATALOG_MAX_ENTRIES)
+			throw new Error("model catalog snapshot exceeds the entry limit");
+		const existing = this.latest();
+		if (existing?.snapshotId === snapshot.snapshotId) return existing;
+		const rows = snapshot.entries.map((entry) => entryObservation(snapshot, entry));
+		for (let offset = 0; offset < rows.length; offset += BATCH_SIZE) this.metrics.recordBatch(rows.slice(offset, offset + BATCH_SIZE));
+		this.metrics.record({
+			source: SOURCE,
+			scope: SNAPSHOT_SCOPE,
+			metric: COMPLETE_METRIC,
+			value: rows.length,
+			unit: "count",
+			observedAt: snapshot.provenance.retrievedAt,
+			attributes: {
+				snapshotId: snapshot.snapshotId,
+				provenance: snapshot.provenance,
+			},
+		});
+		return structuredClone(snapshot);
+	}
+
+	latest(): ModelCatalogSnapshot | null {
+		const marker = this.metrics.query({ source: SOURCE, scope: SNAPSHOT_SCOPE, metric: COMPLETE_METRIC, order: "desc", limit: 1 })[0];
+		if (!marker || typeof marker.value !== "number" || !Number.isSafeInteger(marker.value) || marker.value < 1) return null;
+		const snapshotId = marker.attributes.snapshotId;
+		const provenance = marker.attributes.provenance;
+		if (typeof snapshotId !== "string" || typeof provenance !== "object" || provenance === null || Array.isArray(provenance)) return null;
+		const rows = this.metrics.query({ source: SOURCE, until: marker.observedAt, order: "desc", limit: MODEL_CATALOG_STORE_QUERY_LIMIT });
+		const markerIndex = rows.findIndex((row) => row.id === marker.id);
+		if (markerIndex < 0) return null;
+		const entries = rows
+			.slice(markerIndex + 1)
+			.filter((row) => row.metric === ENTRY_METRIC && row.attributes.snapshotId === snapshotId)
+			.slice(0, marker.value)
+			.map((row) => row.attributes.entry);
+		if (entries.length !== marker.value || !entries.every(validEntry)) return null;
+		const p = provenance as Record<string, unknown>;
+		if (
+			p.sourceId !== "models.dev" ||
+			typeof p.sourceUrl !== "string" ||
+			typeof p.revision !== "string" ||
+			typeof p.retrievedAt !== "number" ||
+			typeof p.freshUntil !== "number" ||
+			p.license !== "MIT"
+		)
+			return null;
+		return {
+			snapshotId,
+			provenance: p as unknown as ModelCatalogSnapshot["provenance"],
+			entries: (entries as ModelCatalogEntry[]).reverse().map((entry) => structuredClone(entry)),
+		};
+	}
+}