@namzu/zen 2.3.0 → 2.5.0

package/dist/catalogue/derive.d.ts

@@ -0,0 +1,203 @@
+/**
+ * The derivation rules that turn Zen's and Go's upstream documents into a
+ * model roster.
+ *
+ * Pure: no network, no file system, no logger. `fetch.ts` reads the sources and
+ * `catalogue.ts` assembles a catalogue from them; the maintainer's generator
+ * (`scripts/generate-zen-models.mjs`) imports these same functions to render
+ * the bundled snapshot in `models.ts`, so the runtime refresh and the snapshot
+ * can never parse the same page two different ways.
+ *
+ * ## Where each field comes from
+ *
+ * Routes come from the service's own documentation page, as the pair
+ * (endpoint, AI SDK package) that page states per model. Both halves are read
+ * and required to agree, because a page that changed shape must stop the run
+ * rather than have one half guessed: the wire a model is served on is a routing
+ * fact, and the wrong one is a request to the wrong endpoint rather than a
+ * clean failure. A row may state its endpoint and no package, with the `-` the
+ * page's own tables use for a cell that has no value: that row is read and
+ * recorded with no wire, and `deriveService` reports it as a model it will not
+ * carry. Losing a column, or carrying a marker that is not `-`, is the page
+ * moving and stops the run.
+ *
+ * Prices come from the same page's per-1M-token table, at the base tier: the
+ * unqualified row when a model has one, the "(Off-Peak)" row for the Go
+ * DeepSeek entries that publish both, and the "(≤ n tokens)" row when a model
+ * is only published as a tier pair. A model with no price row at all must
+ * appear in that page's free-model list and is then zero — "no row" is never
+ * quietly read as free.
+ *
+ * Limits, modalities, tool support and effort levels come from the matching
+ * provider entry in models.dev. Its `npm` is deliberately NOT used as a route,
+ * in either place models.dev states one: the provider-level field names a
+ * single Chat-Completions package for both services, which would send the Go
+ * Qwen rows — documented on `/messages` — to `/chat/completions`, and the
+ * per-model `provider.npm` is stated for fewer than half the documented
+ * models, so it cannot route the rest.
+ *
+ * The two services' own `/models` answers carry `id`, `object`, `created` and
+ * `owned_by` and nothing else: they say a model EXISTS and nothing about how to
+ * call it. An id served there and documented nowhere cannot be carried, only
+ * reported.
+ */
+import type { ModelInputModality, ReasoningEffort } from '@namzu/sdk';
+import type { ZenProtocol, ZenService } from '../models.js';
+/**
+ * A source that could not be read, or no longer has the shape these rules
+ * parse. Never a curation decision: nothing a caller does to the catalogue
+ * clears it, and a refresh that meets one must keep whatever it had before.
+ */
+export declare class ZenCatalogueSourceError extends Error {
+    readonly name = "ZenCatalogueSourceError";
+}
+/** Whether `name` is safe to print as it is: no control, format or separator character. */
+export declare function isDisplayableName(name: string): boolean;
+/** A service, its documentation page, and the models.dev provider holding its limits. */
+export declare const ZEN_SERVICES: readonly {
+    readonly service: ZenService;
+    readonly page: string;
+    readonly provider: string;
+}[];
+/**
+ * Every (AI SDK package, endpoint) pair a page may state, and the protocol
+ * each is. `kind` says how the endpoint names the model: the first three put
+ * it in the body of a fixed path, Google puts it in the path itself.
+ */
+export declare const ROUTES: readonly {
+    readonly npm: string;
+    readonly path: string;
+    readonly protocol: ZenProtocol;
+    readonly kind: 'path' | 'model';
+}[];
+/** The SDK's input modalities, and the models.dev names that map onto them. */
+export declare const MODALITIES: Readonly<Record<string, ModelInputModality>>;
+/** The service each base host serves, by the path prefix its endpoints carry. */
+export declare const SERVICE_PREFIX: Readonly<Record<ZenService, string>>;
+/** One route-table row. `npm` is undefined when the page states no wire. */
+export interface ZenRouteRow {
+    readonly name: string;
+    readonly id: string;
+    readonly endpoint: string;
+    readonly npm: string | undefined;
+}
+/** One price-table row, in USD per million tokens. */
+export interface ZenPriceRow {
+    readonly name: string;
+    readonly input: number;
+    readonly output: number;
+}
+/** A documentation page, split into the three tables the rules read. */
+export interface ZenParsedPage {
+    readonly routes: readonly ZenRouteRow[];
+    readonly prices: readonly ZenPriceRow[];
+    readonly freeNames: readonly string[];
+}
+/**
+ * One `/models` answer, as the set of ids it says the service serves.
+ *
+ * The shape is asserted rather than assumed, and an answer with no ids in it is
+ * refused: a service that returns nothing is a source that moved, and reading
+ * it as "nothing is served" would turn an outage into an empty roster.
+ */
+export declare function parseServed(service: string, text: string): Set<string>;
+/**
+ * Whether a line looks like a row of the route table.
+ *
+ * The account has to CLOSE, not merely to be attempted: a line shaped like a
+ * route row that the route pattern did not capture is a page these rules no
+ * longer read correctly, and dropping it silently is the defect the whole
+ * arrangement exists to remove. Two shapes count, both measured against the
+ * live pages:
+ *
+ *  - two or more backticked cells, which is a row carrying both its endpoint
+ *    and its package;
+ *  - three or more cells with at least one backticked cell, which is a row that
+ *    kept a value and lost a column: an empty package cell leaves four cells,
+ *    and a row whose package COLUMN is gone leaves three.
+ *
+ * The backtick guard keeps the wider rule off table separators
+ * (`| --- | --- | --- | --- |` carries no code span), and a prose row that
+ * quotes a code span has two cells.
+ */
+export declare function isRouteRowShaped(line: string): boolean;
+/** A documentation page, split into the three tables the rules read. */
+export declare function parsePage(text: string, { page, service }: {
+    readonly page: string;
+    readonly service: string;
+}): ZenParsedPage;
+/**
+ * A price cell, or undefined when the cell is not a price.
+ *
+ * Go states its free models' rate as the word "Free" rather than as `$0.00`,
+ * which is a statement about the price and not a missing one, so it is read as
+ * zero.
+ */
+export declare function priceCell(cell: string): number | undefined;
+/** Model names are matched across tables by their letters, digits and dots. */
+export declare function nameKey(name: string): string;
+/**
+ * The base-tier price row for a model: the unqualified row, the "(≤ …)" row of
+ * a tier pair, or the "(Off-Peak)" row of a peak/off-peak pair.
+ */
+export declare function priceRowFor(rows: readonly ZenPriceRow[], name: string): ZenPriceRow | undefined;
+/**
+ * The protocol a (package, endpoint) pair is, refusing anything unrecognised.
+ *
+ * The pair is checked against the URL's own parts rather than by substring: a
+ * cell reading `https://evil.example/messages` contains the path a Messages
+ * route has, and a routing decision that accepts it is a routing decision made
+ * on the wrong string. Host, service prefix, path and package must all agree.
+ */
+export declare function protocolFor({ id, endpoint, npm }: Pick<ZenRouteRow, 'id' | 'endpoint' | 'npm'>, service: string): ZenProtocol;
+/** A models.dev provider entry: its models, keyed by id. */
+export interface ModelsDevProvider {
+    readonly models: Readonly<Record<string, unknown>>;
+}
+/** One model a service's derivation carries, before it becomes a `ZenModel`. */
+export interface DerivedZenModel {
+    readonly id: string;
+    readonly name: string;
+    readonly protocol: ZenProtocol;
+    readonly contextWindow: number;
+    readonly maxOutputTokens: number;
+    readonly inputModalities: ModelInputModality[];
+    readonly inputPrice: number;
+    readonly outputPrice: number;
+    readonly supportsToolUse: boolean;
+    readonly effortLevels: ReasoningEffort[];
+    readonly supportsAnonymousAccess: boolean;
+}
+/** Everything one service's derivation produced, carried and not. */
+export interface DerivedZenService {
+    readonly models: DerivedZenModel[];
+    /** `[service/id, why]`: documented models it did not carry and nothing omits. */
+    readonly undecided: [string, string][];
+    /** Omitted ids upstream neither documents nor serves any more. */
+    readonly stale: string[];
+    /** Price rows no route row names. */
+    readonly orphanPrices: string[];
+    /** Ids the service serves that its page does not document and nothing omits. */
+    readonly servedUncurried: string[];
+}
+/** Omission decisions, as the review file's record or as a set of `service/id` keys. */
+export type ZenOmissions = Readonly<Record<string, string>> | ReadonlySet<string>;
+/**
+ * One service's carried models, plus everything either source names and the
+ * catalogue does not carry.
+ *
+ * `served` is the set of ids the service's own `/models` answer carries, and it
+ * is required rather than defaulted: a caller that forgot it would turn the
+ * served dimension off silently.
+ */
+export declare function derive(service: string, parsed: ZenParsedPage, providerKey: string, provider: ModelsDevProvider, omissions: ZenOmissions, served: ReadonlySet<string>): DerivedZenService;
+/**
+ * Refuse a roster that collapsed.
+ *
+ * A roster that came out empty, or that lost a fifth of what the baseline
+ * carries, is a source that moved far more often than a decision anybody made,
+ * and both look identical to a successful run from the inside.
+ */
+export declare const ROSTER_FLOOR = 0.8;
+export declare function checkRosterFloor(built: Readonly<Record<ZenService, readonly unknown[]>>, committed: Readonly<Record<ZenService, readonly unknown[]>>): void;
+//# sourceMappingURL=derive.d.ts.map

package/dist/catalogue/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../src/catalogue/derive.ts"],"names":[],"mappings":"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"}