@zenera/neo 1.1.0

package/dist/models/factory.js

@@ -0,0 +1,533 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { GeminiEmbedder } from "../embeddings/gemini.js";
+import { OpenAIEmbedder } from "../embeddings/openai.js";
+import { OpenRouterEmbedder } from "../embeddings/openrouter.js";
+import { AnthropicModel } from "./anthropic.js";
+import { GeminiModel } from "./gemini.js";
+import { OpenAIModel } from "./openai-chat.js";
+import { OpenAIResponsesModel } from "./openai-responses.js";
+import { OpenRouterModel } from "./openrouter.js";
+// ---------------------------------------------------------------------------
+// The vendor SDKs
+//
+// All four are *optional peer dependencies*: an application installs the one
+// vendor it talks to and pays for nothing else — which matters most for
+// `@google/genai`, whose own tree carries google-auth-library and protobufjs.
+//
+// That only holds if importing this library does not reach for all four, so
+// nothing above is a value import: the SDKs are pulled in here, when a client
+// of that protocol is first built, and never at module scope.
+//
+// `createRequire` rather than `await import()` because it is synchronous, and
+// so `createModel()` and `ModelRegistry.client()` keep handing back a usable
+// object instead of a promise — which is also what keeps a bad credential
+// throwing at the call that named it rather than at some later request. Three
+// of the four publish a CommonJS build; `@openrouter/sdk` is ESM-only, which
+// `require` has loaded since Node 22 for module graphs without a top-level
+// await, and this library already requires Node 24.
+// ---------------------------------------------------------------------------
+const requirePeer = createRequire(import.meta.url);
+/**
+ * An uninstalled optional peer is a setup mistake, not a bug, so it is reported
+ * as the one-line fix rather than as a resolution failure from inside Node.
+ */
+function sdk(pkg, kind) {
+    try {
+        return requirePeer(pkg);
+    }
+    catch (cause) {
+        if (cause.code !== 'MODULE_NOT_FOUND') {
+            throw cause;
+        }
+        throw new Error(`provider kind "${kind}" needs ${pkg}, which is not installed — run: npm i ${pkg}`, { cause });
+    }
+}
+/**
+ * Only two of these need no adapter of their own.
+ *
+ * `openai-compatible` is the shim kind — vLLM, a self-hosted gateway — and the
+ * OpenAI client is exactly right for it. Everything else gets its vendor's own
+ * SDK, because the compatibility endpoints each vendor publishes are porting
+ * aids: Google's drops thinking budgets, thought signatures and cached-content
+ * accounting, Anthropic's drops cache accounting and extended thinking. Those
+ * are the things this runtime is built around, so paying for two more
+ * dependencies is the cheaper trade.
+ *
+ * `openrouter` used to be that shim with the two constants filled in, which
+ * cost nothing until the parts of OpenRouter worth having turned out to be the
+ * parts chat completions cannot say: which upstream provider serves a request,
+ * what to fall back to when it cannot, and what the call actually cost. Its
+ * own SDK carries those as first-class fields, so it now gets an adapter like
+ * every other vendor. `openai-compatible` against the same base url is still
+ * there for anyone who wants the older, laxer client back.
+ *
+ * `google` and `vertex` differ only in how the client authenticates and which
+ * backend it addresses; both speak the same API through the same adapter.
+ */
+const KINDS = {
+    openai: {
+        protocol: 'openai',
+        apiKeyEnv: 'OPENAI_API_KEY',
+        baseURLEnv: 'OPENAI_BASE_URL',
+        apis: ['chat', 'responses'],
+    },
+    google: {
+        protocol: 'gemini',
+        apiKeyEnv: 'GEMINI_API_KEY',
+        baseURLEnv: 'GEMINI_BASE_URL',
+        apis: [],
+    },
+    vertex: {
+        // Vertex authenticates with Application Default Credentials, which the
+        // GenAI SDK resolves itself — so unlike every other kind this one
+        // usually has no key at all. `VERTEX_API_KEY` covers express mode.
+        protocol: 'gemini',
+        apiKeyEnv: 'VERTEX_API_KEY',
+        baseURLEnv: 'VERTEX_BASE_URL',
+        apis: [],
+        keyOptional: true,
+    },
+    anthropic: {
+        protocol: 'anthropic',
+        apiKeyEnv: 'ANTHROPIC_API_KEY',
+        baseURLEnv: 'ANTHROPIC_BASE_URL',
+        apis: [],
+    },
+    openrouter: {
+        protocol: 'openrouter',
+        apiKeyEnv: 'OPENROUTER_API_KEY',
+        baseURLEnv: 'OPENROUTER_BASE_URL',
+        baseURL: 'https://openrouter.ai/api/v1',
+        apis: [],
+    },
+    'openai-compatible': {
+        protocol: 'openai',
+        apiKeyEnv: 'OPENAI_API_KEY',
+        baseURLEnv: 'OPENAI_BASE_URL',
+        apis: ['chat', 'responses'],
+    },
+};
+export const providerKinds = Object.keys(KINDS);
+export function isProviderKind(name) {
+    return Object.hasOwn(KINDS, name);
+}
+// ---------------------------------------------------------------------------
+// Environment references
+// ---------------------------------------------------------------------------
+// `${VAR}` and `${VAR:-fallback}`. Chosen over a bare `env.VAR` token because a
+// literal secret never contains `${`, so there is no rule to remember about
+// which strings are magic — and because it composes inside a longer value,
+// which a whole-value token cannot: `https://${GATEWAY}/v1`.
+const ENV_REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
+/**
+ * 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 function expandEnv(value, where) {
+    return value.replace(ENV_REF, (_match, name, fallback) => {
+        const found = fromEnv(name);
+        if (found !== undefined) {
+            return found;
+        }
+        if (fallback !== undefined) {
+            return fallback;
+        }
+        throw new Error(`${where}: \${${name}} is not set`);
+    });
+}
+function fromEnv(name) {
+    const value = process.env[name];
+    return value?.trim() ? value : undefined;
+}
+function expand(value, where) {
+    return value === undefined ? undefined : expandEnv(value, where);
+}
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+/**
+ * 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 class ModelRegistry {
+    #providers = new Map();
+    #clients = new Map();
+    #default = 'openai';
+    /** Declares (or replaces) a provider. Nothing is contacted until it is used. */
+    provider(name, spec = {}) {
+        if (spec.kind !== undefined && !isProviderKind(spec.kind)) {
+            throw new TypeError(`provider "${name}": unknown kind "${spec.kind}" ` +
+                `(known: ${providerKinds.join(', ')})`);
+        }
+        this.#providers.set(name, spec);
+        // Re-declaring after a client was handed out would otherwise leave the
+        // old credentials in service for the rest of the process.
+        this.#clients.delete(name);
+        return this;
+    }
+    /** Names the provider a bare model id belongs to. */
+    setDefault(name) {
+        if (!this.has(name)) {
+            throw new Error(`default provider "${name}" is not declared (known: ${this.names().join(', ')})`);
+        }
+        this.#default = name;
+        return this;
+    }
+    get defaultProvider() {
+        return this.#default;
+    }
+    /** Declared here, or a built-in kind usable with no declaration at all. */
+    has(name) {
+        return this.#providers.has(name) || isProviderKind(name);
+    }
+    names() {
+        return [...new Set([...this.#providers.keys(), ...providerKinds])];
+    }
+    /** The shared client for a provider, built on first use. */
+    client(name) {
+        const existing = this.#clients.get(name);
+        if (existing) {
+            return existing;
+        }
+        const spec = this.#spec(name);
+        const built = spec.client ?? buildClient(name, this.kindOf(name), spec, spec);
+        this.#clients.set(name, built);
+        return built;
+    }
+    /** Turns a shorthand or a spec into a `Model`. */
+    model(ref) {
+        const spec = typeof ref === 'string' ? this.parse(ref) : ref;
+        const name = spec.provider ?? this.#default;
+        const provider = this.#spec(name);
+        const kind = this.kindOf(name);
+        const defaults = KINDS[kind];
+        // Inline credentials opt out of the shared client: they describe a
+        // different connection, and handing back the memoized one would
+        // silently ignore them.
+        const client = spec.client ??
+            (hasCredentials(spec) ? buildClient(name, kind, spec, provider) : this.client(name));
+        // Every protocol but OpenAI's has exactly one API, so naming one is a
+        // mistake worth reporting rather than a field to ignore.
+        if (defaults.protocol !== 'openai') {
+            if (spec.api) {
+                throw new TypeError(`provider "${name}" (${kind}) has one api, so "${spec.api}" means nothing here`);
+            }
+            switch (defaults.protocol) {
+                case 'anthropic':
+                    return new AnthropicModel(spec.model, client, spec);
+                case 'gemini':
+                    return new GeminiModel(spec.model, client, spec);
+                case 'openrouter':
+                    return new OpenRouterModel(spec.model, client, spec);
+            }
+        }
+        const api = spec.api ?? defaults.apis[0];
+        if (!defaults.apis.includes(api)) {
+            throw new TypeError(`provider "${name}" (${kind}) does not speak the "${api}" api ` +
+                `(supported: ${defaults.apis.join(', ')})`);
+        }
+        return api === 'responses'
+            ? new OpenAIResponsesModel(spec.model, client, spec)
+            : new OpenAIModel(spec.model, client, spec);
+    }
+    /**
+     * 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) {
+        const spec = typeof ref === 'string' ? this.#parseEmbedding(ref) : ref;
+        const name = spec.provider ?? this.#default;
+        const provider = this.#spec(name);
+        const kind = this.kindOf(name);
+        const client = spec.client ??
+            (hasCredentials(spec) ? buildClient(name, kind, spec, provider) : this.client(name));
+        switch (KINDS[kind].protocol) {
+            case 'openai':
+                return new OpenAIEmbedder(spec.model, client, spec);
+            case 'gemini':
+                return new GeminiEmbedder(spec.model, client, spec);
+            case 'openrouter':
+                return new OpenRouterEmbedder(spec.model, client, spec);
+            case 'anthropic':
+                // Not an omission to be filled in later: Anthropic publishes no
+                // embeddings API at all, and points at third parties instead.
+                throw new TypeError(`provider "${name}" (${kind}) has no embeddings api — ` +
+                    `declare a provider of another kind for \`embeddings:\``);
+        }
+    }
+    /**
+     * 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) {
+        const spec = typeof ref === 'string' ? this.parse(ref) : ref;
+        const name = spec.provider ?? this.#default;
+        const provider = this.#spec(name);
+        const kind = this.kindOf(name);
+        const defaults = KINDS[kind];
+        const creds = hasCredentials(spec) ? spec : provider;
+        const apiKeyEnv = creds.apiKeyEnv ?? defaults.apiKeyEnv;
+        // An unset `${VAR}` is precisely the absent credential being asked
+        // about, so it answers the question rather than interrupting it.
+        let apiKey;
+        try {
+            apiKey = expand(creds.apiKey, `provider "${name}": apiKey`) ?? fromEnv(apiKeyEnv);
+        }
+        catch {
+            apiKey = undefined;
+        }
+        return {
+            provider: name,
+            kind,
+            apiKeyEnv,
+            satisfied: Boolean(apiKey ??
+                provider.token ??
+                (spec.client || provider.client) ??
+                defaults.keyOptional),
+            keyOptional: Boolean(defaults.keyOptional),
+        };
+    }
+    /** `[provider[/api]:]model` → spec. Exposed so a caller can validate a ref. */
+    parse(ref) {
+        // Only the first colon separates the prefix: model ids may contain colons.
+        const colon = ref.indexOf(':');
+        if (colon < 0) {
+            return { model: ref };
+        }
+        const [provider, api] = ref.slice(0, colon).split('/');
+        const model = ref.slice(colon + 1);
+        if (!model) {
+            throw new TypeError(`missing model id in "${ref}"`);
+        }
+        if (!provider || !this.has(provider)) {
+            throw new TypeError(`unknown provider "${provider}" in "${ref}" ` +
+                `(known: ${this.names().join(', ')}; a model id that itself contains a ` +
+                `colon must name its provider, e.g. "openai:${ref}")`);
+        }
+        if (api !== undefined && api !== 'chat' && api !== 'responses') {
+            throw new TypeError(`unknown api "${api}" in "${ref}" (expected chat or responses)`);
+        }
+        return { provider, api, model };
+    }
+    #parseEmbedding(ref) {
+        const { provider, api, model } = this.parse(ref);
+        if (api) {
+            throw new TypeError(`"${ref}": embeddings have one api, so "${api}" means nothing here`);
+        }
+        return { provider, model };
+    }
+    #spec(name) {
+        const declared = this.#providers.get(name);
+        if (declared) {
+            return declared;
+        }
+        if (isProviderKind(name)) {
+            return { kind: name };
+        }
+        throw new Error(`unknown provider "${name}" (known: ${this.names().join(', ')}; ` +
+            `declare it under \`providers:\` or in ProjectOptions.providers)`);
+    }
+    /** A declared kind wins; otherwise a built-in name is its own kind. */
+    kindOf(name) {
+        const declared = this.#providers.get(name)?.kind;
+        return declared ?? (isProviderKind(name) ? name : 'openai');
+    }
+}
+/**
+ * Credential resolution, in one place so a `${VAR}` reference behaves the same
+ * whether it came from yaml or from application code. `creds` may be a model
+ * spec overriding the connection; `opts` always carries the provider's
+ * transport settings, which an override does not get to reinvent.
+ */
+function buildClient(name, kind, creds, opts) {
+    const where = `provider "${name}"`;
+    const defaults = KINDS[kind];
+    // A token callback replaces the key rather than supplementing it: the
+    // header is rewritten per request, so whatever the SDK was constructed with
+    // never reaches the wire.
+    const apiKeyEnv = creds.apiKeyEnv ?? defaults.apiKeyEnv;
+    const apiKey = expand(creds.apiKey, `${where}: apiKey`) ?? fromEnv(apiKeyEnv);
+    if (!apiKey && !opts.token && !defaults.keyOptional) {
+        throw new Error(`${where}: no api key — set \`apiKey\`, or set ${apiKeyEnv}`);
+    }
+    // An absent base url means "vendor default", so it may stay undefined.
+    const baseURL = expand(creds.baseURL, `${where}: baseURL`) ??
+        fromEnv(creds.baseURLEnv ?? defaults.baseURLEnv) ??
+        defaults.baseURL;
+    const headers = expandHeaders(opts.headers, where);
+    if (defaults.protocol === 'gemini') {
+        return buildGenAI(kind, apiKey, baseURL, headers, opts, where);
+    }
+    if (defaults.protocol === 'openrouter') {
+        return buildOpenRouter(kind, apiKey, baseURL, headers, opts);
+    }
+    const common = {
+        apiKey: apiKey ?? OAUTH_PLACEHOLDER,
+        baseURL,
+        defaultHeaders: headers,
+        timeout: opts.timeoutMs,
+        maxRetries: opts.maxRetries,
+        ...(opts.token ? { fetch: bearerFetch(opts.token) } : {}),
+    };
+    if (defaults.protocol === 'anthropic') {
+        const { Anthropic } = sdk('@anthropic-ai/sdk', kind);
+        return new Anthropic(common);
+    }
+    const { OpenAI } = sdk('openai', kind);
+    return new OpenAI(common);
+}
+/**
+ * OpenRouter's client takes its base url as `serverURL` and its retry policy as
+ * a strategy object rather than a count, so the shared `common` shape does not
+ * fit — but the two things that usually need a custom `fetch` are cheaper here.
+ *
+ * A `token` callback goes straight in as `apiKey`, which this SDK accepts in
+ * callable form and re-invokes per request; there is nothing to intercept.
+ * Default headers have no constructor slot at all, so they are added by a
+ * `beforeRequest` hook — the same seam the SDK uses for tracing headers.
+ */
+function buildOpenRouter(kind, apiKey, baseURL, headers, opts) {
+    const { OpenRouter, HTTPClient } = sdk('@openrouter/sdk', kind);
+    let httpClient;
+    if (headers) {
+        httpClient = new HTTPClient();
+        httpClient.addHook('beforeRequest', (req) => {
+            for (const [key, value] of Object.entries(headers)) {
+                req.headers.set(key, value);
+            }
+            return req;
+        });
+    }
+    const { token } = opts;
+    return new OpenRouter({
+        apiKey: token ? async () => token() : apiKey,
+        serverURL: baseURL,
+        timeoutMs: opts.timeoutMs,
+        // A count of zero is the one value that has to change shape: this SDK
+        // says "do not retry" with a strategy, not with a number.
+        retryConfig: opts.maxRetries === 0 ? { strategy: 'none' } : undefined,
+        httpClient,
+    });
+}
+/**
+ * The GenAI client is configured by *backend* rather than by url: `vertexai`
+ * selects the Gemini Enterprise endpoint and the SDK derives the address from
+ * the project and region, so there is no base url to assemble here.
+ *
+ * Authentication differs the same way. The Gemini API takes a key; Vertex
+ * normally takes none, because the SDK resolves Application Default
+ * Credentials — a service account, a workload identity, `gcloud auth
+ * application-default login` — and refreshes them itself. That is why `vertex`
+ * is `keyOptional`, and why it needs none of the bearer-token machinery the
+ * OpenAI protocol uses for the same job.
+ */
+function buildGenAI(kind, apiKey, baseURL, headers, opts, where) {
+    const { GoogleGenAI } = sdk('@google/genai', kind);
+    const httpOptions = { baseUrl: baseURL, headers, timeout: opts.timeoutMs };
+    if (kind !== 'vertex') {
+        return new GoogleGenAI({ apiKey, httpOptions });
+    }
+    const project = expand(opts.project, `${where}: project`) ??
+        fromEnv('GOOGLE_CLOUD_PROJECT') ??
+        projectFromKeyFile();
+    if (!project && !apiKey) {
+        throw new Error(`${where}: vertex needs \`project\`, or GOOGLE_CLOUD_PROJECT ` +
+            `(or \`apiKey\` for express mode)`);
+    }
+    return new GoogleGenAI({
+        vertexai: true,
+        apiKey,
+        project,
+        location: expand(opts.location, `${where}: location`) ??
+            fromEnv('GOOGLE_CLOUD_LOCATION') ??
+            'global',
+        httpOptions,
+    });
+}
+/**
+ * `project_id` out of a service-account key file, when one is named.
+ *
+ * The GenAI SDK resolves Application Default Credentials itself but takes the
+ * project only from its constructor or `GOOGLE_CLOUD_PROJECT` — so a key file
+ * that already states which project it belongs to still has to have that
+ * repeated in the environment. Reading it here removes the second variable for
+ * the common case.
+ *
+ * Only that one route carries a project id: credentials from `gcloud auth
+ * application-default login` do not, and a metadata server answers a different
+ * endpoint entirely. Both still need the project named, which is why a
+ * failure to read anything here is not an error — the caller's own check is.
+ */
+function projectFromKeyFile() {
+    const path = fromEnv('GOOGLE_APPLICATION_CREDENTIALS');
+    if (!path) {
+        return undefined;
+    }
+    try {
+        const key = JSON.parse(readFileSync(path, 'utf8'));
+        const id = key.project_id;
+        return typeof id === 'string' && id.trim() ? id : undefined;
+    }
+    catch {
+        // An unreadable or malformed file is the SDK's to report, at the point
+        // where it tries to authenticate with it and can say so precisely.
+        return undefined;
+    }
+}
+// Both SDKs refuse to construct without a key. When a token callback owns the
+// Authorization header this value is never sent, so it only has to be non-empty.
+const OAUTH_PLACEHOLDER = 'oauth';
+/**
+ * Rewrites `Authorization` on every request from a callback, so a credential
+ * that expires — an Azure AD token, a gateway's short-lived grant — is
+ * refreshed without the client, and its connection pool, being rebuilt. Vertex
+ * has no need of it: its SDK does the same job from ambient credentials.
+ */
+function bearerFetch(token) {
+    return async (input, init) => {
+        const headers = new Headers(init?.headers);
+        headers.set('Authorization', `Bearer ${await token()}`);
+        return fetch(input, { ...init, headers });
+    };
+}
+function expandHeaders(headers, where) {
+    if (!headers) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(headers).map(([k, v]) => [k, expandEnv(v, `${where}: headers.${k}`)]));
+}
+function hasCredentials(spec) {
+    return Boolean(spec.apiKey || spec.apiKeyEnv || spec.baseURL || spec.baseURLEnv);
+}
+// ---------------------------------------------------------------------------
+// Default registry
+// ---------------------------------------------------------------------------
+/**
+ * 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 const defaultModels = new 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 function createModel(ref, registry = defaultModels) {
+    return registry.model(ref);
+}
+/** `createModel`'s counterpart for vectors, over the same registry and clients. */
+export function createEmbedder(ref, registry = defaultModels) {
+    return registry.embedder(ref);
+}
+//# sourceMappingURL=factory.js.map

package/dist/models/gemini.d.ts

@@ -0,0 +1,45 @@
+import type { GoogleGenAI } from '@google/genai';
+import type { StreamDelta } from '../events.ts';
+import type { Model, ModelRequest, ModelResponse } from '../model.ts';
+/** The coarse dial Gemini 3 takes in place of a token budget. */
+export type GeminiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
+/**
+ * Provider-specific knobs.
+ *
+ * Thinking is configured two different ways depending on the generation, and
+ * both are exposed rather than unified: 2.5 takes a token `thinkingBudget`,
+ * 3 takes a coarse `thinkingLevel`, and passing the wrong one is an API error
+ * rather than something this adapter can paper over.
+ */
+export interface GeminiModelOptions {
+    /** hard cap on output tokens; the model's own default applies when unset */
+    maxTokens?: number;
+    /** 2.5-era budget, in tokens: `0` disables thinking, `-1` lets the model decide */
+    thinkingBudget?: number;
+    /** 3-era dial; mutually exclusive with `thinkingBudget` */
+    thinkingLevel?: GeminiThinkingLevel;
+    /**
+     * Ask for thought *summaries* — the only reasoning text the API exposes.
+     * On by default: the runtime has a `thinking` channel and the tokens are
+     * billed whether or not the summary is returned.
+     */
+    includeThoughts?: boolean;
+}
+/**
+ * The `Model` contract over `generateContent`.
+ *
+ * Google publishes an OpenAI-compatible endpoint, and reaching Gemini through
+ * it costs nothing but a base url. What it costs *afterwards* is everything
+ * this file exists for: thinking budgets and thought summaries, thought
+ * signatures (without which Gemini 3 function calling is rejected outright),
+ * cached-content accounting, and the block reasons that come back when a safety
+ * filter fires. None of those have an OpenAI field to be carried in.
+ */
+export declare class GeminiModel implements Model {
+    #private;
+    readonly id: string;
+    constructor(id: string, client: GoogleGenAI, options?: GeminiModelOptions);
+    generate(req: ModelRequest): Promise<ModelResponse>;
+    stream(req: ModelRequest, onDelta: (d: StreamDelta) => void): Promise<ModelResponse>;
+}
+//# sourceMappingURL=gemini.d.ts.map