@zenera/neo 1.1.0

package/dist/models/factory.d.ts

@@ -0,0 +1,202 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import type { GoogleGenAI } from '@google/genai';
+import type { OpenRouter } from '@openrouter/sdk';
+import type OpenAI from 'openai';
+import type { Embedder } from '../embedding.ts';
+import { type GeminiEmbedderOptions } from '../embeddings/gemini.ts';
+import { type OpenAIEmbedderOptions } from '../embeddings/openai.ts';
+import { type OpenRouterEmbedderOptions } from '../embeddings/openrouter.ts';
+import type { Model } from '../model.ts';
+import { type AnthropicModelOptions } from './anthropic.ts';
+import { type GeminiModelOptions } from './gemini.ts';
+import { type OpenAIResponsesModelOptions } from './openai-responses.ts';
+import { type OpenRouterModelOptions } from './openrouter.ts';
+/**
+ * A *provider* is a connection; a *model* is a request shape. They used to be
+ * one type, which made "two OpenAI keys" mean repeating credentials on every
+ * model that used the second one — and gave every agent its own HTTP client,
+ * with its own connection pool and its own retry budget.
+ *
+ * Separated, credentials are declared once under a name, the client behind that
+ * name is built once and shared, and a model spec becomes vendor-neutral: a
+ * provider, an id, and knobs.
+ */
+export type ProviderKind = 'openai' | 'google' | 'vertex' | 'anthropic' | 'openrouter' | 'openai-compatible';
+export type OpenAIApi = 'chat' | 'responses';
+/** The vendor client behind a provider name. */
+export type ProviderClient = OpenAI | Anthropic | GoogleGenAI | OpenRouter;
+/**
+ * How to reach a provider. Every field has an env fallback so a spec can stay
+ * declarative (and secret-free) in application code.
+ */
+export interface Credentials {
+    /** literal key, or a `${VAR}` reference — wins over any env lookup */
+    apiKey?: string;
+    /** env var holding the key; defaults to the kind's conventional name */
+    apiKeyEnv?: string;
+    /** literal base url, or a `${VAR}` reference, for gateways and compatible endpoints */
+    baseURL?: string;
+    /** env var holding the base url; defaults to the kind's conventional name */
+    baseURLEnv?: string;
+}
+/** A named connection to a vendor. One client is built per registered name. */
+export interface ProviderSpec extends Credentials {
+    /** which vendor this speaks; defaults to `openai` */
+    kind?: ProviderKind;
+    /**
+     * vertex only: GCP project id. Falls back to `GOOGLE_CLOUD_PROJECT`, then
+     * to the `project_id` inside the service-account key file named by
+     * `GOOGLE_APPLICATION_CREDENTIALS`.
+     */
+    project?: string;
+    /** vertex only: a region, or `global` (env: `GOOGLE_CLOUD_LOCATION`, default `global`) */
+    location?: string;
+    /**
+     * Returns a bearer token, once per request, so a short-lived credential can
+     * be refreshed without rebuilding the client. Azure AD and gateways that
+     * mint their own grants are the cases; Vertex is not, because the GenAI SDK
+     * already resolves and refreshes Application Default Credentials. Code
+     * only: a function is not something yaml can hold.
+     */
+    token?: () => string | Promise<string>;
+    /** sent on every request — gateway routing, attribution, api versions */
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    maxRetries?: number;
+    /**
+     * Pre-built client — bypasses credential resolution entirely. The seam for
+     * auth no configuration can express: Vertex service accounts, Bedrock
+     * signing, or a stub in tests.
+     */
+    client?: ProviderClient;
+}
+/**
+ * What to ask for, and of whom. Vendor differences live in the *provider*, so
+ * there is nothing here to discriminate on: the option interfaces are unioned
+ * and the knobs that do not apply to the chosen vendor are ignored.
+ *
+ * `Credentials` are still accepted inline, for a one-off model that does not
+ * warrant a declared provider. Using them opts out of the shared client.
+ */
+export interface ModelSpec extends Credentials, OpenAIResponsesModelOptions, AnthropicModelOptions, GeminiModelOptions, OpenRouterModelOptions {
+    /**
+     * Registered provider name. The built-in providers are named after their
+     * kind, so `provider: 'google'` works with nothing declared. Defaults to
+     * the registry's default provider.
+     */
+    provider?: string;
+    /** which API to speak; defaults to the vendor's usual one */
+    api?: OpenAIApi;
+    model: string;
+    /** pre-built client — bypasses provider resolution entirely */
+    client?: ProviderClient;
+}
+/**
+ * Shorthand: `[provider[/api]:]model`, e.g. `gpt-4o`, `openai:gpt-4o`,
+ * `openai/responses:o3`, `gemini-eu:gemini-2.5-pro`.
+ *
+ * Only the *first* colon separates, so a fine-tuned id keeps its own — it just
+ * has to name its provider: `openai:ft:gpt-4o:acme::a1b2`. Anything the
+ * shorthand cannot express (keys, base urls, reasoning knobs) needs the object
+ * form.
+ */
+export type ModelRef = ModelSpec | string;
+/**
+ * The same idea one layer down: which vectoriser, and of whom.
+ *
+ * A separate type from `ModelSpec` rather than a flag on it, because the two
+ * share only their connection. There is no `api` field — `/v1/responses` has no
+ * embeddings endpoint, so naming one would be meaningless on every protocol,
+ * not just the three that already have a single API.
+ */
+export interface EmbeddingSpec extends Credentials, OpenAIEmbedderOptions, GeminiEmbedderOptions, OpenRouterEmbedderOptions {
+    /** registered provider name; defaults to the registry's default provider */
+    provider?: string;
+    model: string;
+    /** pre-built client — bypasses provider resolution entirely */
+    client?: ProviderClient;
+}
+/** Shorthand: `[provider:]model`, e.g. `text-embedding-3-small`, `google:gemini-embedding-001`. */
+export type EmbeddingRef = EmbeddingSpec | string;
+/**
+ * What a ref *would* connect with. `model()` answers the same question by
+ * building a client — which needs the very credential a caller wanting to
+ * report on credentials does not have. This resolves the same precedence rules
+ * and stops there, so a CLI can say which model is unreachable before anything
+ * throws three frames deeper.
+ */
+export interface ModelRequirement {
+    /** the provider name the ref resolves to, declared or built-in */
+    provider: string;
+    kind: ProviderKind;
+    /** env var consulted when the spec carries no `apiKey` of its own */
+    apiKeyEnv: string;
+    /** a client could be built as things stand */
+    satisfied: boolean;
+    /** the SDK authenticates without a key, so `satisfied` says little */
+    keyOptional: boolean;
+}
+export declare const providerKinds: ProviderKind[];
+export declare function isProviderKind(name: string): name is ProviderKind;
+/**
+ * Substitutes `${VAR}` references. An unset variable with no fallback is an
+ * error naming both the variable and where it was written, because the
+ * alternative is an empty api key and a 401 three layers away.
+ */
+export declare function expandEnv(value: string, where: string): string;
+/**
+ * Named providers, and the clients behind them.
+ *
+ * The clients are why this is an object rather than a function: one `OpenAI`
+ * per provider name, built on first use and shared by every model and every
+ * agent that names it. A registry is also the seam a host uses to point a name
+ * at different credentials, or at a stub — neither of which should mean
+ * touching a `switch`.
+ */
+export declare class ModelRegistry {
+    #private;
+    /** Declares (or replaces) a provider. Nothing is contacted until it is used. */
+    provider(name: string, spec?: ProviderSpec): this;
+    /** Names the provider a bare model id belongs to. */
+    setDefault(name: string): this;
+    get defaultProvider(): string;
+    /** Declared here, or a built-in kind usable with no declaration at all. */
+    has(name: string): boolean;
+    names(): string[];
+    /** The shared client for a provider, built on first use. */
+    client(name: string): ProviderClient;
+    /** Turns a shorthand or a spec into a `Model`. */
+    model(ref: ModelRef): Model;
+    /**
+     * Turns a shorthand or a spec into an `Embedder`, over the same providers
+     * and the same shared clients as `model()` — an `openai` key declared once
+     * generates and embeds without being mentioned twice.
+     */
+    embedder(ref: EmbeddingRef): Embedder;
+    /**
+     * What a ref needs to reach its vendor, resolved but not contacted. An
+     * unknown provider still throws: that is a broken config, not a missing
+     * credential, and the two want different words.
+     */
+    requirement(ref: ModelRef | EmbeddingRef): ModelRequirement;
+    /** `[provider[/api]:]model` → spec. Exposed so a caller can validate a ref. */
+    parse(ref: string): ModelSpec;
+    /** A declared kind wins; otherwise a built-in name is its own kind. */
+    kindOf(name: string): ProviderKind;
+}
+/**
+ * The registry behind the bare `createModel`. An application that never
+ * declares a provider still gets shared clients through it, because the
+ * built-in names (`openai`, `google`, …) resolve without declaration.
+ */
+export declare const defaultModels: ModelRegistry;
+/**
+ * One entry point for every provider. Accepts a shorthand string or a full
+ * spec, so `createModel('openai/responses:o3')` and
+ * `createModel({ model: 'o3', api: 'responses', apiKeyEnv: 'MY_KEY' })` are
+ * both valid.
+ */
+export declare function createModel(ref: ModelRef, registry?: ModelRegistry): Model;
+/** `createModel`'s counterpart for vectors, over the same registry and clients. */
+export declare function createEmbedder(ref: EmbeddingRef, registry?: ModelRegistry): Embedder;
+//# sourceMappingURL=factory.d.ts.map