@intx/inference-discovery-google-genai 0.1.2 → 0.3.0

package/dist/request-body.js

@@ -0,0 +1,337 @@
+import { readFileSync } from "node:fs";
+import { CapabilityNotBuildableError, resolveMediaPath, } from "@intx/inference-discovery/catalog";
+// Text models share the full multimodal text capability surface; only
+// thinking-budget handling differs for models that cannot disable thinking
+// (see minimalThinkingBudget). Image models are output-only.
+export const TEXT_MODELS = new Set([
+    "gemini-2.5-flash",
+    "gemini-2.5-pro",
+    "gemini-3.6-flash",
+    "gemini-3.5-flash",
+    "gemini-3-flash-preview",
+    "gemini-3.1-pro-preview",
+]);
+export const IMAGE_MODELS = new Set([
+    "gemini-2.5-flash-image",
+    "gemini-3.1-flash-image",
+]);
+const TEXT_MODEL_CAPABILITIES = new Set([
+    "plain-text",
+    "plain-text-streaming",
+    "function-calling-multi-turn",
+    "function-calling-multi-turn-streaming",
+    "function-calling-with-thinking",
+    "function-calling-with-thinking-streaming",
+    "vision-input",
+    "vision-input-streaming",
+    "audio-input",
+    "audio-input-streaming",
+    "video-input",
+    "video-input-streaming",
+    "document-input",
+    "document-input-streaming",
+    "code-execution",
+    "code-execution-streaming",
+    "grounding",
+    "grounding-streaming",
+    "files-api-reference",
+    "files-api-reference-streaming",
+    "safety-classification",
+    "safety-classification-streaming",
+    "structured-output",
+    "structured-output-streaming",
+]);
+const IMAGE_MODEL_CAPABILITIES = new Set([
+    "image-output",
+    "image-output-streaming",
+]);
+const EXTENSION_TO_MIME_TYPE = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    gif: "image/gif",
+    webp: "image/webp",
+    wav: "audio/wav",
+    mp3: "audio/mpeg",
+    ogg: "audio/ogg",
+    flac: "audio/flac",
+    mp4: "video/mp4",
+    mov: "video/quicktime",
+    webm: "video/webm",
+    pdf: "application/pdf",
+};
+function classifyModel(model, override) {
+    if (TEXT_MODELS.has(model))
+        return "text";
+    if (IMAGE_MODELS.has(model))
+        return "image";
+    return override ?? "text";
+}
+// True when the model's class is known from set membership, so its request
+// shape is not a guess. A caller (the probe) uses this to tell an operator when
+// it is defaulting an unknown model to the text class rather than classifying a
+// known one — the default is deliberate, but it should never be silent.
+export function isKnownModel(model) {
+    return TEXT_MODELS.has(model) || IMAGE_MODELS.has(model);
+}
+function assertCapabilityBuildable(model, capability, modelClass) {
+    const resolved = classifyModel(model, modelClass);
+    const supported = resolved === "image" ? IMAGE_MODEL_CAPABILITIES : TEXT_MODEL_CAPABILITIES;
+    if (!supported.has(capability)) {
+        throw new CapabilityNotBuildableError(capability, `google-genai: ${resolved}-class model ${model} does not support capability ${capability}`);
+    }
+}
+function extensionFor(path) {
+    const dot = path.lastIndexOf(".");
+    if (dot < 0 || dot === path.length - 1) {
+        throw new Error(`google-genai: cannot infer media MIME type, no extension in path: ${path}`);
+    }
+    return path.slice(dot + 1).toLowerCase();
+}
+function mimeTypeFor(ref) {
+    const ext = extensionFor(ref.path);
+    const mime = EXTENSION_TO_MIME_TYPE[ext];
+    if (mime === undefined) {
+        throw new Error(`google-genai: no MIME type mapping for extension .${ext} (path ${ref.path})`);
+    }
+    return mime;
+}
+function readMediaBase64(ref) {
+    const absolute = resolveMediaPath(ref);
+    const bytes = readFileSync(absolute);
+    return bytes.toString("base64");
+}
+function expectSingleMedia(intent) {
+    if (intent.media === undefined || intent.media.length === 0) {
+        throw new Error("google-genai: media-input capability requires intent.media to be non-empty");
+    }
+    if (intent.media.length !== 1) {
+        throw new Error(`google-genai: media-input capability expects exactly one media reference, got ${String(intent.media.length)}`);
+    }
+    const [media] = intent.media;
+    if (media === undefined) {
+        throw new Error("google-genai: media-input capability: media[0] is unexpectedly undefined");
+    }
+    return media;
+}
+function expectSingleTool(intent) {
+    if (intent.tools === undefined || intent.tools.length === 0) {
+        throw new Error("google-genai: function-calling capability requires intent.tools to be non-empty");
+    }
+    if (intent.tools.length !== 1) {
+        throw new Error(`google-genai: function-calling capability expects exactly one tool declaration, got ${String(intent.tools.length)}`);
+    }
+    const [tool] = intent.tools;
+    if (tool === undefined) {
+        throw new Error("google-genai: function-calling capability: tools[0] is unexpectedly undefined");
+    }
+    return tool;
+}
+function userTextContent(prompt) {
+    return {
+        role: "user",
+        parts: [{ text: prompt }],
+    };
+}
+// Gemini's "dynamic" thinking budget sentinel: the model decides how much to
+// think and no cap is imposed.
+const DYNAMIC_THINKING_BUDGET = -1;
+// gemini-2.5-pro rejects thinkingConfig.thinkingBudget: 0 with HTTP 400
+// "Budget 0 is invalid. This model only works in thinking mode." The budget can
+// only be chosen by model identity, because the API surfaces the constraint
+// solely as a runtime 400 with no build-time signal. Add a model here when its
+// API rejects a zero thinking budget.
+const THINKING_MANDATORY_MODELS = new Set([
+    "gemini-2.5-pro",
+    "gemini-3.6-flash",
+    "gemini-3.1-pro-preview",
+]);
+// The thinking budget to request when a probe wants thinking suppressed: 0
+// (fully off) for models that allow it, or the dynamic budget for models that
+// cannot be set to 0. includeThoughts stays false in both cases, so no thought
+// parts are returned either way.
+function minimalThinkingBudget(model) {
+    return THINKING_MANDATORY_MODELS.has(model) ? DYNAMIC_THINKING_BUDGET : 0;
+}
+function plainTextBody(intent) {
+    return {
+        contents: [userTextContent(intent.prompt)],
+    };
+}
+function plainTextStreamingBody(intent, model) {
+    return {
+        contents: [userTextContent(intent.prompt)],
+        generationConfig: {
+            maxOutputTokens: 400,
+            thinkingConfig: {
+                thinkingBudget: minimalThinkingBudget(model),
+            },
+        },
+    };
+}
+function functionToolFromDecl(decl) {
+    return {
+        functionDeclarations: [
+            {
+                name: decl.name,
+                description: decl.description,
+                parameters: decl.parameters,
+            },
+        ],
+    };
+}
+function functionCallingBody(intent, thinking) {
+    const decl = expectSingleTool(intent);
+    const thinkingConfig = thinking.includeThoughts
+        ? { thinkingBudget: thinking.budget, includeThoughts: true }
+        : { thinkingBudget: thinking.budget };
+    return {
+        contents: [userTextContent(intent.prompt)],
+        tools: [functionToolFromDecl(decl)],
+        toolConfig: {
+            functionCallingConfig: {
+                mode: "ANY",
+                allowedFunctionNames: [decl.name],
+            },
+        },
+        generationConfig: {
+            thinkingConfig,
+        },
+    };
+}
+function inlineMediaBody(intent) {
+    const media = expectSingleMedia(intent);
+    return {
+        contents: [
+            {
+                role: "user",
+                parts: [
+                    { text: intent.prompt },
+                    {
+                        inlineData: {
+                            mimeType: mimeTypeFor(media),
+                            data: readMediaBase64(media),
+                        },
+                    },
+                ],
+            },
+        ],
+    };
+}
+function imageOutputBody(intent) {
+    return {
+        contents: [userTextContent(intent.prompt)],
+        generationConfig: {
+            responseModalities: ["TEXT", "IMAGE"],
+        },
+    };
+}
+function codeExecutionBody(intent) {
+    return {
+        contents: [userTextContent(intent.prompt)],
+        tools: [{ codeExecution: {} }],
+    };
+}
+function groundingBody(intent) {
+    return {
+        contents: [userTextContent(intent.prompt)],
+        tools: [{ googleSearch: {} }],
+    };
+}
+// Shape-identical between streaming and non-streaming variants — only the
+// endpoint differs (handled by buildEndpointURL). The streaming variant
+// deliberately does NOT clamp `thinkingBudget: 0` the way plain-text
+// streaming does: the safety classifier's engagement may depend on
+// whether the model goes through a thinking phase, and the probe's job
+// is to observe natural classifier behavior at default generation
+// settings, not constrained ones.
+function safetyClassificationBody(intent) {
+    return {
+        contents: [userTextContent(intent.prompt)],
+    };
+}
+function structuredOutputBody(intent) {
+    const format = intent.responseFormat;
+    if (format === undefined) {
+        throw new Error("google-genai: structured-output intent has no responseFormat");
+    }
+    const generationConfig = {};
+    switch (format.kind) {
+        case "text":
+            // Free-form text is Gemini's default; emit no responseMimeType.
+            break;
+        case "json":
+            generationConfig.responseMimeType = "application/json";
+            break;
+        case "json-schema":
+            generationConfig.responseMimeType = "application/json";
+            generationConfig.responseSchema = format.schema;
+            break;
+    }
+    const body = {
+        contents: [userTextContent(intent.prompt)],
+    };
+    if (Object.keys(generationConfig).length > 0) {
+        body.generationConfig = generationConfig;
+    }
+    return body;
+}
+export function buildRequestBody(opts) {
+    assertCapabilityBuildable(opts.model, opts.capability, opts.modelClass);
+    switch (opts.capability) {
+        case "plain-text":
+            return plainTextBody(opts.intent);
+        case "plain-text-streaming":
+            return plainTextStreamingBody(opts.intent, opts.model);
+        case "function-calling-multi-turn":
+        case "function-calling-multi-turn-streaming":
+            return functionCallingBody(opts.intent, {
+                budget: minimalThinkingBudget(opts.model),
+                includeThoughts: false,
+            });
+        case "function-calling-with-thinking":
+        case "function-calling-with-thinking-streaming":
+            return functionCallingBody(opts.intent, {
+                budget: 1024,
+                includeThoughts: true,
+            });
+        case "vision-input":
+        case "vision-input-streaming":
+        case "audio-input":
+        case "audio-input-streaming":
+        case "video-input":
+        case "video-input-streaming":
+        case "document-input":
+        case "document-input-streaming":
+            return inlineMediaBody(opts.intent);
+        case "image-output":
+        case "image-output-streaming":
+            return imageOutputBody(opts.intent);
+        case "code-execution":
+        case "code-execution-streaming":
+            return codeExecutionBody(opts.intent);
+        case "grounding":
+        case "grounding-streaming":
+            return groundingBody(opts.intent);
+        case "safety-classification":
+        case "safety-classification-streaming":
+            return safetyClassificationBody(opts.intent);
+        case "structured-output":
+        case "structured-output-streaming":
+            return structuredOutputBody(opts.intent);
+        case "files-api-reference":
+        case "files-api-reference-streaming":
+            throw new Error(`google-genai: capability ${opts.capability} is multi-step; use iterateCaptureSteps from the plug-in, not buildRequestBody.`);
+        case "function-calling":
+        case "reasoning-content":
+        case "reasoning-content-streaming":
+        case "redacted-thinking":
+        case "redacted-thinking-streaming":
+        case "structured-output-refusal-streaming":
+            throw new CapabilityNotBuildableError(opts.capability, `google-genai: capability ${opts.capability} is not supported by any google-genai model`);
+        default: {
+            const exhaustive = opts.capability;
+            throw new Error(`google-genai: unhandled capability ${String(exhaustive)}`);
+        }
+    }
+}

package/dist/sse.d.ts

@@ -0,0 +1 @@
+export declare function reconstructResponseFromSSE(bytes: Uint8Array): unknown;

package/dist/sse.js

@@ -0,0 +1,109 @@
+// Gemini streams generateContent as Server-Sent Events: each `data: {json}`
+// line is a full GenerateContentResponse chunk whose candidates[0].content.parts
+// carry incremental deltas. To build a turn-2 multi-turn body for a streaming
+// capability, the assistant content has to be reconstructed from those chunks.
+//
+// Reconstruction flattens every chunk's parts in order and coalesces
+// consecutive text deltas that share the same shape — plain text (`{text}`)
+// with plain text, and thought text (`{text, thought: true}`) with thought
+// text — but never across shapes. Every non-text part (a functionCall, or any
+// part carrying a thoughtSignature) is emitted as-is, in order, so the
+// signature the API requires on an echoed thinking turn survives.
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// The coalescing signature of a streamed text delta, or null when the part is
+// not a plain text delta (a functionCall, a thoughtSignature-bearing part, …)
+// and must therefore stand as its own part.
+function textDeltaSignature(part) {
+    if (typeof part.text !== "string")
+        return null;
+    const keys = Object.keys(part);
+    if (keys.length === 1)
+        return "text";
+    if (keys.length === 2 && part.thought === true)
+        return "thought-text";
+    // A text delta carrying any further key (notably a thoughtSignature) is not
+    // coalescible: it stays its own part so the signature's exact placement in
+    // the thought stream survives verbatim into the echoed turn-2 content.
+    return null;
+}
+function sseDataPayloads(bytes) {
+    const text = new TextDecoder().decode(bytes);
+    const payloads = [];
+    for (const line of text.split(/\r?\n/)) {
+        if (!line.startsWith("data:"))
+            continue;
+        const payload = line.slice("data:".length).trim();
+        if (payload.length > 0 && payload !== "[DONE]")
+            payloads.push(payload);
+    }
+    return payloads;
+}
+// Reconstructs the shape a non-streaming turn-1 response would have —
+// `{ candidates: [{ content: { role, parts } }] }` — from a Gemini SSE stream,
+// so the multi-turn turn-2 builder consumes it unchanged.
+export function reconstructResponseFromSSE(bytes) {
+    const payloads = sseDataPayloads(bytes);
+    if (payloads.length === 0) {
+        throw new Error("google-genai SSE: stream carried no data payloads to reconstruct");
+    }
+    let role;
+    const parts = [];
+    let lastSignature = null;
+    for (const payload of payloads) {
+        const chunk = JSON.parse(payload);
+        if (!isRecord(chunk)) {
+            throw new Error("google-genai SSE: chunk is not a JSON object");
+        }
+        const candidates = chunk.candidates;
+        // Some trailing chunks carry only usageMetadata and no candidates.
+        if (candidates === undefined)
+            continue;
+        if (!Array.isArray(candidates) || candidates.length === 0) {
+            throw new Error("google-genai SSE: chunk.candidates is not a non-empty array");
+        }
+        const first = candidates[0];
+        if (!isRecord(first)) {
+            throw new Error("google-genai SSE: candidates[0] is not an object");
+        }
+        const content = first.content;
+        // A finishReason-only chunk closes the candidate without new content.
+        if (content === undefined)
+            continue;
+        if (!isRecord(content)) {
+            throw new Error("google-genai SSE: candidates[0].content is not an object");
+        }
+        if (typeof content.role === "string")
+            role = content.role;
+        const chunkParts = content.parts;
+        if (chunkParts === undefined)
+            continue;
+        if (!Array.isArray(chunkParts)) {
+            throw new Error("google-genai SSE: candidates[0].content.parts is not an array");
+        }
+        for (const part of chunkParts) {
+            if (!isRecord(part)) {
+                throw new Error("google-genai SSE: a content part is not an object");
+            }
+            const signature = textDeltaSignature(part);
+            const previous = parts[parts.length - 1];
+            if (signature !== null &&
+                signature === lastSignature &&
+                previous !== undefined) {
+                previous.text = `${String(previous.text)}${String(part.text)}`;
+            }
+            else {
+                parts.push({ ...part });
+                lastSignature = signature;
+            }
+        }
+    }
+    // The assistant role must come off the wire; defaulting it would fabricate a
+    // turn-1 shape the model never sent and mask a provider change the probe
+    // exists to catch. Gemini emits role on the first content-bearing chunk.
+    if (role === undefined) {
+        throw new Error("google-genai SSE: no candidate content carried a role; cannot reconstruct the assistant turn");
+    }
+    return { candidates: [{ content: { role, parts } }] };
+}

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "@intx/inference-discovery-google-genai",
-  "version": "0.1.2",
+  "description": "Google GenAI provider plug-in for the inference discovery rig",
+  "version": "0.3.0",
   "license": "LGPL-2.1-only",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "intx-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
-    "@intx/inference-discovery": "0.0.0",
+    "@intx/inference-discovery": "0.3.0",
     "arktype": "^2.1.29"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/auth.ts

@@ -1,8 +0,0 @@
-export const AUTH_HEADER = "x-goog-api-key";
-
-export function buildAuthHeaders(apiKey: string): Record<string, string> {
-  if (apiKey.length === 0) {
-    throw new Error("google-genai: apiKey must be a non-empty string");
-  }
-  return { [AUTH_HEADER]: apiKey };
-}

package/src/endpoint.ts

@@ -1,20 +0,0 @@
-import type { Capability } from "@intx/inference-discovery/catalog";
-
-export const GEMINI_BASE = "https://generativelanguage.googleapis.com/v1beta";
-
-export function isStreamingCapability(capability: Capability): boolean {
-  return capability.endsWith("-streaming");
-}
-
-export function buildEndpointURL(opts: {
-  model: string;
-  capability: Capability;
-}): string {
-  if (opts.model.length === 0) {
-    throw new Error("google-genai: model must be a non-empty string");
-  }
-  if (isStreamingCapability(opts.capability)) {
-    return `${GEMINI_BASE}/models/${opts.model}:streamGenerateContent?alt=sse`;
-  }
-  return `${GEMINI_BASE}/models/${opts.model}:generateContent`;
-}