@gullabs/google 0.7.0 → 0.8.1

package/dist/index.d.cts

@@ -1,4 +1,44 @@
-import { AuthMaterial, ProviderAdapter, LlmError, Logger } from '@gullabs/core';
+import { AuthMaterial, ProviderAdapter, ProviderPlugin, ModelRegistry, ModelDescriptor, PricingSource, ModelRates, LlmError, Logger, Message } from '@gullabs/core';
+import { Content } from '@google/genai';
+
+/**
+ * Google-specific provider options for `@gullabs/google`.
+ *
+ * Importing anything from this module (including this type-only re-export)
+ * pulls in the `declare module '@gullabs/core'` augmentation below, which
+ * adds the `google` key to `ProviderOptionsMap`. `packages/google/src/index.ts`
+ * re-exports these types unconditionally so the augmentation always loads
+ * when anything is imported from `@gullabs/google`.
+ *
+ * @module
+ */
+type GoogleSafetySetting = {
+    category: string;
+    threshold: string;
+};
+type GoogleSearchTool = {
+    googleSearch: Record<string, never>;
+};
+type GoogleProviderOptions = {
+    /** Google cached content resource name. */
+    cachedContent?: string;
+    /** Allowlisted Google safety settings. */
+    safetySettings?: GoogleSafetySetting[];
+    /** Exact Google tool declarations admitted by the selected model schema. */
+    tools?: GoogleSearchTool[];
+    /** Allowlisted Google transport options. */
+    httpOptions?: {
+        /** Per-request Google transport timeout in milliseconds. */
+        timeout?: number;
+    };
+    /** Allow provider fallback from flex when flex was explicitly selected. */
+    flexFallback?: boolean;
+};
+declare module '@gullabs/core' {
+    interface ProviderOptionsMap {
+        google?: GoogleProviderOptions;
+    }
+}
 
 /**
  * Structural GeminiClientLike interface + buildGoogleClient factory.
@@ -241,16 +281,45 @@ interface GeminiGenerateParams {
     contents: GeminiContent[];
     config?: GeminiGenerateConfig;
 }
+/**
+ * Parameters for models.countTokens.
+ * Real type: CountTokensParameters.
+ */
+interface GeminiCountTokensParams {
+    model: string;
+    contents: GeminiContent[];
+    config?: {
+        systemInstruction?: {
+            parts: GeminiContentPart[];
+        };
+        /**
+         * Real field: CountTokensConfig.abortSignal. countTokens has no
+         * tier-timeout dance (no flex/standard default ceilings) — `ctx.signal`
+         * is forwarded here directly, unlike `run()`'s combined timer signal.
+         */
+        abortSignal?: AbortSignal;
+    };
+}
+/**
+ * Response shape for models.countTokens.
+ * Real type: CountTokensResponse.
+ */
+interface GeminiCountTokensResponseShape {
+    totalTokens?: number;
+    cachedContentTokenCount?: number;
+}
 /**
  * Structural interface for the @google/genai client surface the adapter uses.
  *
  * Satisfied by:
  * - The real GoogleGenAI client (via buildGoogleClient wrapper).
- * - FakeGeminiClient from @gullabs/testing (its generateContent accepts unknown).
+ * - FakeGeminiClient from @gullabs/testing (its generateContent/countTokens
+ *   accept unknown).
  */
 interface GeminiClientLike {
     models: {
         generateContent(params: GeminiGenerateParams): Promise<GeminiResponseShape>;
+        countTokens(params: GeminiCountTokensParams): Promise<GeminiCountTokensResponseShape>;
     };
 }
 /**
@@ -296,6 +365,151 @@ interface GeminiAdapterOptions {
  */
 declare function geminiAdapter(opts?: GeminiAdapterOptions): ProviderAdapter;
 
+/**
+ * `googleProvider` — {@link ProviderPlugin} factory for @gullabs/google.
+ *
+ * Bundles the Gemini adapter, the built-in Gemini + Gemma model descriptors,
+ * and the Gemini pricing source into a single plugin for
+ * {@link composeProviders}.
+ *
+ * @module
+ */
+
+/**
+ * Create a {@link ProviderPlugin} for the Gemini provider.
+ *
+ * @param opts - Forwarded to {@link geminiAdapter}.
+ * @returns A plugin bundling the Gemini adapter, Gemini + Gemma model
+ *   descriptors, and the built-in Gemini pricing source.
+ *
+ * @example
+ * ```ts
+ * import { createClient, composeProviders } from '@gullabs/core'
+ * import { googleProvider } from '@gullabs/google'
+ *
+ * const client = createClient({
+ *   ...composeProviders([googleProvider()]),
+ * })
+ * ```
+ */
+declare function googleProvider(opts?: GeminiAdapterOptions): ProviderPlugin;
+
+/**
+ * Model descriptor registry for @gullabs/google.
+ *
+ * Centralises Gemini/Gemma model knowledge: reasoning-effort vocabularies,
+ * capability flags, and the built-in descriptor arrays. `@gullabs/core` owns
+ * only the generic registry machinery (`ModelDescriptor`, `ModelRegistry`,
+ * `createModelRegistry`) — this module supplies the Gemini-specific data.
+ *
+ * @module
+ */
+
+declare const geminiModelDescriptors: ModelDescriptor[];
+declare const gemmaModelDescriptors: ModelDescriptor[];
+/**
+ * Pre-built registry of all built-in Gemini + Gemma descriptors.
+ *
+ * Most callers should prefer {@link googleProvider} (which bundles this same
+ * descriptor set via `composeProviders`); this export remains for callers
+ * that need a bare `ModelRegistry` without going through the plugin seam.
+ */
+declare const defaultGeminiRegistry: ModelRegistry;
+
+/**
+ * Gemini pricing source for @gullabs/google.
+ *
+ * Provides `geminiPricingSource` — a factory returning a `PricingSource` port
+ * implementation backed by the frozen Gemini pricing snapshot ({@link
+ * GEMINI_PRICING}). Walks the rates table (exact-then-longest-prefix match)
+ * and delegates the actual arithmetic to `@gullabs/core`'s `computeCost`,
+ * supplying this package's rates table + tier-factor map as explicit
+ * parameters — core itself carries zero Gemini pricing knowledge.
+ *
+ * @module
+ */
+
+/**
+ * Factory that returns the **google-scoped** {@link PricingSource} port
+ * implementation backed by the built-in Gemini pricing snapshot.
+ *
+ * `PricingSource` is provider-scoped by contract — this source only knows
+ * bare Gemini/Gemma model keys. Compose it into `ClientConfig.pricingSources`
+ * under the `'google'` key (or bundle it via {@link googleProvider}); do not
+ * use it for other providers.
+ *
+ * The returned object is stateless and can be shared across calls.
+ *
+ * @example
+ * ```ts
+ * import { geminiPricingSource } from '@gullabs/google'
+ *
+ * const pricing = geminiPricingSource()
+ * const cost = pricing.price('gemini-2.5-pro', usage, 'flex')
+ * ```
+ */
+declare function geminiPricingSource(): PricingSource;
+
+/**
+ * Gemini pricing snapshot for @gullabs/google.
+ *
+ * All rates are in **micro-USD per million tokens** (µUSD/M).
+ * To get the cost for N tokens: `cost_µUSD = N * ratePerM / 1_000_000`.
+ *
+ * **Service tiers.** Rates below are STANDARD-tier. Google's **Batch** tier is a
+ * flat 50% discount on standard, and **Flex** matches Batch pricing. The cost
+ * engine applies the {@link TIER_FACTOR} multiplier — this snapshot stores
+ * standard rates only.
+ *
+ * **Long-context tier.** Gemini Pro models charge a premium when the GROSS input
+ * token count exceeds 200,000. Selected by `inputTokens` (incl. cached), not by
+ * billable input.
+ *
+ * **Thinking tokens.** Already inside `outputTokens` (GROSS convention) and
+ * billed at the standard output rate — no separate thinking lane.
+ *
+ * **Modality caveat (v1 = text).** Gemini 2.5 Flash / Flash-Lite charge a higher
+ * INPUT rate for audio tokens than for text/image/video. v1 is text-only and uses
+ * the text/img/vid input rate. Per-modality input pricing is a deferred seam
+ * (see DESIGN.md) — revisit when audio input is supported.
+ *
+ * Verified against https://ai.google.dev/gemini-api/docs/pricing on 2026-06-28.
+ *
+ * @module
+ */
+
+/**
+ * Identifies this pricing snapshot — bump the date when rates change.
+ *
+ * This is a snapshot date tied to Gemini's own pricing page, not a generic
+ * core concept — it lives here (not `@gullabs/core`) alongside the rates it
+ * dates.
+ */
+declare const pricingVersion: "gemini-2026-06-28";
+/**
+ * Service-tier price multipliers. Batch and Flex are a flat 50% of standard
+ * (per Google's pricing page: "Batch API — 50% cost reduction"; Flex matches Batch).
+ *
+ * `serviceTier` is an opaque, provider-defined string end-to-end — this map is
+ * the *only* place a tier name is resolved to a multiplier. A tier key not
+ * present here is never coerced to `standard`: `computeCost` (`@gullabs/core`)
+ * treats that as an unpriced call (reject-don't-map), not a mapping to this
+ * table's default. `undefined` (no tier requested) is the one case that
+ * legitimately defaults to `standard` — that is documented default behavior,
+ * not a guess.
+ */
+declare const TIER_FACTOR: Readonly<Record<string, number>>;
+/**
+ * Frozen Gemini pricing snapshot (STANDARD tier; per-1M in µUSD).
+ *
+ * Keys are model-string prefixes / exact identifiers used in routing. The cost
+ * engine matches exact first, then longest-prefix (see `lookupRates` in
+ * `cost.ts`).
+ *
+ * Source: https://ai.google.dev/gemini-api/docs/pricing (2026-06-28).
+ */
+declare const GEMINI_PRICING: Readonly<Record<string, ModelRates>>;
+
 declare function isGeminiCapacityError(err: LlmError): boolean;
 
 /**
@@ -456,8 +670,8 @@ interface GeminiCachesClientLike {
     create(params: {
         model: string;
         config: {
-            contents?: unknown;
-            systemInstruction?: unknown;
+            contents?: Content[];
+            systemInstruction?: Content | string;
             ttl?: string;
             displayName?: string;
         };
@@ -500,6 +714,35 @@ interface GoogleCacheStoreOptions {
     logger?: Logger;
     /** Injectable clock for deterministic tests.  Default: `Date.now`. */
     now?: () => number;
+    /**
+     * Opt-in pre-flight token-count gate applied before every cache create
+     * (both `create()` directly and the `getOrCreate()` path it delegates to,
+     * including the coalesced path — enforced once, inside `create()`, so
+     * there is no separate "in-flight" gap to close).
+     */
+    preflight?: {
+        /** Minimum token count required before a cache create is allowed to proceed. */
+        minTokens: number;
+        /**
+         * Counts tokens for the exact token-bearing payload of the impending
+         * create — `model` + `contents` + `systemInstruction` only. `ttl` and
+         * `displayName` are excluded: they carry no tokens and are irrelevant to
+         * the pre-flight check.
+         *
+         * This callback receives genai-native `Content[]`/`Content|string` — it
+         * does NOT receive the library's `Message[]` shape and there is no
+         * automatic conversion between the two (explicit seam, by design). Hosts
+         * using genai-native content directly can wire this to a raw
+         * `client.models.countTokens` call; hosts building from the library's
+         * `Message[]` should call `@gullabs/core`'s `client.countTokens` rather
+         * than expecting this callback to convert for them.
+         */
+        countTokens: (payload: {
+            model: string;
+            contents?: Content[];
+            systemInstruction?: Content | string;
+        }) => Promise<number>;
+    };
 }
 /**
  * Process-scoped helper for the Gemini Context Cache API.
@@ -526,6 +769,7 @@ declare class GoogleCacheStore {
     private readonly onDeleteError;
     private readonly logger;
     private readonly now;
+    private readonly preflight;
     /** Memoised client promise — built at most once per store instance. */
     private clientPromise;
     /** In-process cache of live handles, keyed by `${model}:${stableKey}`. */
@@ -545,8 +789,8 @@ declare class GoogleCacheStore {
     create(input: {
         model: string;
         ttlSeconds: number;
-        contents?: unknown;
-        systemInstruction?: unknown;
+        contents?: Content[];
+        systemInstruction?: Content | string;
         displayName?: string;
     }): Promise<GoogleCacheHandle>;
     /**
@@ -560,8 +804,8 @@ declare class GoogleCacheStore {
      */
     getOrCreate(key: CacheKey, factory: () => Promise<{
         ttlSeconds: number;
-        contents?: unknown;
-        systemInstruction?: unknown;
+        contents?: Content[];
+        systemInstruction?: Content | string;
     }>): Promise<GoogleCacheHandle>;
     /**
      * Extend the cache TTL if it will expire within `thresholdSeconds`.
@@ -612,4 +856,85 @@ interface Citation {
  */
 declare function normalizeGroundingCitations(groundingMetadata: unknown): Citation[];
 
-export { type CacheKey, type Citation, FLEX_DEFAULT_TIMEOUT_MS, type GeminiAdapterOptions, type GeminiCachesClientLike, type GeminiClientLike, type GeminiFilesClientLike, type GoogleCacheHandle, GoogleCacheStore, type GoogleCacheStoreOptions, type GoogleFileHandle, GoogleFileStore, type GoogleFileStoreOptions, STANDARD_DEFAULT_TIMEOUT_MS, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, geminiAdapter, isGeminiCapacityError, normalizeGroundingCitations, requireApiKey };
+/**
+ * geminiContentToMessages — migration utility: `@google/genai` `Content[]` →
+ * any-llm's normalized `Message[]`.
+ *
+ * For consumers moving hand-authored `@google/genai` prompts onto this
+ * library. Uses `@google/genai` TYPES ONLY (no runtime SDK dependency — the
+ * package is a peer dep, imported here with `import type`).
+ *
+ * Reject-don't-map: every genai `Content`/`Part` shape this utility cannot
+ * losslessly represent in any-llm's normalized types throws a typed
+ * `LlmError('bad_request')` naming the offending field or kind. Nothing is
+ * ever silently dropped — that silent-loss failure mode is exactly what this
+ * utility exists to eliminate for migrating callers.
+ *
+ * Validation is an exhaustive own-key scan: the set of defined keys on each
+ * `Part` must be EXACTLY one of the recognized combinations (`['text']`,
+ * `['inlineData']`, `['inlineData', 'mediaResolution']`, `['fileData']`,
+ * `['fileData', 'mediaResolution']`). Any other key — including unknown
+ * future SDK fields — or any combination outside that set throws. Keys whose
+ * value is `undefined` are treated as absent (genai types are all-optional;
+ * only defined values count).
+ *
+ * @module
+ */
+
+/**
+ * Input accepted by {@link geminiContentToMessages}.
+ */
+interface GeminiContentToMessagesInput {
+    /** Raw `@google/genai` conversation history to convert. */
+    contents: Content[];
+    /**
+     * Raw `@google/genai` system instruction — either the SDK's shorthand
+     * plain string, or a full `Content` (only text parts supported; any
+     * non-text part throws).
+     */
+    systemInstruction?: Content | string;
+}
+/**
+ * Output produced by {@link geminiContentToMessages}.
+ */
+interface GeminiContentToMessagesResult {
+    /** Concatenated system text, present only when `systemInstruction` was given. */
+    system?: string;
+    /** Normalized any-llm messages, one per input `Content`. */
+    messages: Message[];
+}
+/**
+ * Convert `@google/genai` `Content[]` / `Part[]` into any-llm's normalized
+ * `{ system?, messages }` shape.
+ *
+ * A migration utility for callers moving hand-authored `@google/genai`
+ * prompts onto any-llm. Exhaustive and reject-don't-map: any genai shape
+ * that cannot be losslessly represented in any-llm's normalized types
+ * throws `LlmError('bad_request')` naming the offending kind/field instead
+ * of silently dropping it.
+ *
+ * `system` is derived ONLY from the explicit `systemInstruction` input —
+ * never inferred from `contents`.
+ *
+ * @example
+ * ```ts
+ * // Before: hand-rolled @google/genai prompt
+ * const contents: Content[] = [
+ *   { role: 'user', parts: [{ text: 'Describe this image.' }, { inlineData: { mimeType: 'image/png', data } }] },
+ *   { role: 'model', parts: [{ text: 'A red bicycle leaning against a brick wall.' }] },
+ * ]
+ *
+ * // After: migrate onto any-llm's normalized shape in one call
+ * import { geminiContentToMessages } from '@gullabs/google'
+ *
+ * const { system, messages } = geminiContentToMessages({
+ *   contents,
+ *   systemInstruction: 'You are a concise visual describer.',
+ * })
+ *
+ * const result = await client.generate({ provider: 'google', model: 'gemini-2.5-pro', system, messages }, { auth })
+ * ```
+ */
+declare function geminiContentToMessages(input: GeminiContentToMessagesInput): GeminiContentToMessagesResult;
+
+export { type CacheKey, type Citation, FLEX_DEFAULT_TIMEOUT_MS, GEMINI_PRICING, type GeminiAdapterOptions, type GeminiCachesClientLike, type GeminiClientLike, type GeminiContentToMessagesInput, type GeminiContentToMessagesResult, type GeminiCountTokensParams, type GeminiCountTokensResponseShape, type GeminiFilesClientLike, type GoogleCacheHandle, GoogleCacheStore, type GoogleCacheStoreOptions, type GoogleFileHandle, GoogleFileStore, type GoogleFileStoreOptions, type GoogleProviderOptions, type GoogleSafetySetting, type GoogleSearchTool, STANDARD_DEFAULT_TIMEOUT_MS, TIER_FACTOR, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, defaultGeminiRegistry, geminiAdapter, geminiContentToMessages, geminiModelDescriptors, geminiPricingSource, gemmaModelDescriptors, googleProvider, isGeminiCapacityError, normalizeGroundingCitations, pricingVersion, requireApiKey };