@kindgi/adapter-model-gemini 0.0.0-bootstrap.0 → 0.1.0

package/src/provider.ts

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import {
+  type GenerateContentConfig,
+  type GenerateContentParameters,
+  type GenerateContentResponse,
+  GoogleGenAI,
+} from '@google/genai';
+import type {
+  AdapterFactory,
+  ModelCallInput,
+  ModelCallResult,
+  ModelProvider,
+  ProviderMetadata,
+} from '@kindgi/capabilities';
+
+import { type GeminiModelInfo, computeCostUsd, toFrameworkUsage } from './cost.js';
+import { fromGeminiResponse, toGeminiFunctions, toGeminiRequest } from './translate.js';
+
+/** The adapter id servers register `geminiAdapterFactory` under. */
+export const GEMINI_ADAPTER_ID = '@kindgi/adapter-model-gemini';
+
+/** The slice of the SDK client the adapter calls. Tests pass a fake. */
+export interface GeminiClient {
+  readonly models: {
+    generateContent(params: GenerateContentParameters): Promise<GenerateContentResponse>;
+  };
+}
+
+export interface GeminiProviderOptions {
+  /**
+   * Metadata surfaced to the router. `models[]` lists every model the
+   * caller expects to invoke through this connection; per-model `cost`
+   * takes Gemini's cached-token and long-context rates.
+   */
+  readonly metadata: Omit<ProviderMetadata, 'models'> & {
+    readonly models: readonly GeminiModelInfo[];
+  };
+  /** The Vertex AI project and location (`global`, or a region such as `us-central1`). */
+  readonly vertex: { readonly project: string; readonly location: string };
+  /**
+   * A service-account key (its JSON), resolved on every call. Absent:
+   * Google Application Default Credentials — `gcloud auth
+   * application-default login` on a laptop, the attached service account
+   * on Cloud Run and other Google Cloud runtimes.
+   */
+  readonly credentials?: () => string | Promise<string>;
+  /** An injected client, used as is (tests). `vertex` and `credentials` are then unused. */
+  readonly client?: GeminiClient;
+}
+
+const CLOUD_PLATFORM_SCOPE = 'https://www.googleapis.com/auth/cloud-platform';
+
+/**
+ * A Gemini `ModelProvider` on Vertex AI. Non-streaming, tool-use enabled:
+ * one `generateContent` call per `invoke`.
+ */
+export function createGeminiProvider(options: GeminiProviderOptions): ModelProvider {
+  const { metadata } = options;
+  checkVertexTarget(metadata.id, options.vertex);
+  const modelsByName = new Map<string, GeminiModelInfo>(
+    metadata.models.map((m) => [m.name, m] as const),
+  );
+
+  // One client per credential: reused while the resolved key stays the
+  // same, rebuilt when it rotates. `''` stands for ADC.
+  let cached: { readonly key: string; readonly client: GeminiClient } | undefined;
+  async function resolveClient(): Promise<GeminiClient> {
+    if (options.client !== undefined) return options.client;
+    const key = options.credentials !== undefined ? await options.credentials() : '';
+    if (cached?.key === key) return cached.client;
+    const client = new GoogleGenAI({
+      vertexai: true,
+      project: options.vertex.project,
+      location: options.vertex.location,
+      ...(key !== '' && {
+        googleAuthOptions: {
+          credentials: parseServiceAccountKey(key),
+          scopes: [CLOUD_PLATFORM_SCOPE],
+        },
+      }),
+    });
+    cached = { key, client };
+    return client;
+  }
+
+  return {
+    metadata,
+    async invoke(input: ModelCallInput): Promise<ModelCallResult> {
+      const model = modelsByName.get(input.model);
+      if (model === undefined) {
+        throw new Error(
+          `${GEMINI_ADAPTER_ID}: provider "${metadata.id}" does not expose model "${input.model}". ` +
+            `Available: ${[...modelsByName.keys()].join(', ') || '<none>'}.`,
+        );
+      }
+      const startedAt = Date.now();
+      const { systemInstruction, contents } = toGeminiRequest(input.messages);
+      const maxOutputTokens = input.maxOutputTokens ?? model.maxOutputTokens;
+      const config: GenerateContentConfig = {
+        ...(systemInstruction !== undefined && { systemInstruction }),
+        ...(input.tools !== undefined &&
+          input.tools.length > 0 && {
+            tools: [{ functionDeclarations: [...toGeminiFunctions(input.tools)] }],
+          }),
+        ...(input.structuredOutput !== undefined && {
+          responseMimeType: 'application/json',
+          responseJsonSchema: input.structuredOutput.schema,
+        }),
+        ...(input.temperature !== undefined && { temperature: input.temperature }),
+        ...(maxOutputTokens !== undefined && { maxOutputTokens }),
+        ...(input.abortSignal !== undefined && { abortSignal: input.abortSignal }),
+      };
+
+      const client = await resolveClient();
+      const response = await client.models.generateContent({
+        model: input.model,
+        contents: [...contents],
+        config,
+      });
+
+      const { message, finishReason } = fromGeminiResponse(response);
+      const usage = toFrameworkUsage(response.usageMetadata);
+      return {
+        message,
+        finishReason,
+        usage,
+        costUsd: computeCostUsd(usage, model.cost),
+        durationMs: Date.now() - startedAt,
+        provider: { id: metadata.id, model: input.model },
+      };
+    },
+  };
+}
+
+/**
+ * A service-account key's JSON, reduced to the fields a service-account
+ * key has. google-auth-library acts on a credential's `type`: an
+ * `external_account` fetches URLs it names (with its headers) and reads
+ * files it names, `token_uri` and `universe_domain` move the token
+ * exchange. A tenant writes this secret, so only `service_account` is
+ * accepted, and Google's own token endpoint is always used.
+ */
+export function parseServiceAccountKey(key: string): Record<string, string> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(key);
+  } catch {
+    throw new Error(`${GEMINI_ADAPTER_ID}: the credential isn't a service-account key (not JSON).`);
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(
+      `${GEMINI_ADAPTER_ID}: the credential isn't a service-account key (not an object).`,
+    );
+  }
+  const fields = parsed as Record<string, unknown>;
+  if (fields.type !== 'service_account') {
+    throw new Error(
+      `${GEMINI_ADAPTER_ID}: the credential must be a service-account key ("type": "service_account"); other credential types aren't accepted.`,
+    );
+  }
+  if (typeof fields.client_email !== 'string' || typeof fields.private_key !== 'string') {
+    throw new Error(
+      `${GEMINI_ADAPTER_ID}: the credential isn't a service-account key (no client_email / private_key).`,
+    );
+  }
+  const reduced: Record<string, string> = {
+    type: 'service_account',
+    client_email: fields.client_email,
+    private_key: fields.private_key,
+  };
+  for (const optional of ['project_id', 'private_key_id', 'client_id'] as const) {
+    const value = fields[optional];
+    if (typeof value === 'string') reduced[optional] = value;
+  }
+  return reduced;
+}
+
+/**
+ * The adapter factory servers register under `GEMINI_ADAPTER_ID`. A
+ * provider registered with it carries:
+ *
+ *   - `adapter_config.project` — the Vertex AI project (required);
+ *   - `metadata.region` — the Vertex location (`global`, `us-central1`,
+ *     `northamerica-northeast1`, …); `'unspecified'` means `global`;
+ *   - `secret_ref` (optional) — a service-account key. Without one the
+ *     adapter uses Application Default Credentials.
+ */
+export const geminiAdapterFactory: AdapterFactory = (input) =>
+  createGeminiProvider({
+    metadata: input.metadata as GeminiProviderOptions['metadata'],
+    vertex: vertexTarget(input),
+    ...(input.resolveApiKey !== undefined && { credentials: input.resolveApiKey }),
+  });
+
+/** The Vertex project and location a registration names (see `geminiAdapterFactory`). */
+export function vertexTarget(
+  input: Parameters<AdapterFactory>[0],
+): GeminiProviderOptions['vertex'] {
+  const project = input.config?.project;
+  if (typeof project !== 'string' || project.length === 0) {
+    throw new Error(
+      `${GEMINI_ADAPTER_ID}: provider "${input.metadata.id}" needs adapter_config.project (the Vertex AI project).`,
+    );
+  }
+  const target = {
+    project,
+    location: input.metadata.region === 'unspecified' ? 'global' : input.metadata.region,
+  };
+  checkVertexTarget(input.metadata.id, target);
+  return target;
+}
+
+/**
+ * The SDK puts the project in the request path and builds the hostname
+ * from the location (`https://<location>-aiplatform.googleapis.com/`):
+ * anything but a project id and one DNS label could move the request,
+ * with the server's credentials, to another host.
+ */
+function checkVertexTarget(providerId: string, vertex: GeminiProviderOptions['vertex']): void {
+  if (!VERTEX_PROJECT.test(vertex.project)) {
+    throw new Error(
+      `${GEMINI_ADAPTER_ID}: provider "${providerId}" adapter_config.project must be a Google Cloud project id or number.`,
+    );
+  }
+  if (!VERTEX_LOCATION.test(vertex.location)) {
+    throw new Error(
+      `${GEMINI_ADAPTER_ID}: provider "${providerId}" metadata.region must be a Vertex AI location (one DNS label, e.g. us-central1).`,
+    );
+  }
+}
+
+/** A Google Cloud project id (6–30: lowercase, digits, hyphens) or project number. */
+const VERTEX_PROJECT = /^(?:[a-z][a-z0-9-]{4,28}[a-z0-9]|[0-9]{1,20})$/;
+/** A Vertex AI location: one DNS label. */
+const VERTEX_LOCATION = /^[a-z][a-z0-9-]{0,62}$/;

package/src/translate.ts

@@ -0,0 +1,215 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { randomUUID } from 'node:crypto';
+
+import type {
+  Content,
+  FunctionCall,
+  FunctionDeclaration,
+  GenerateContentResponse,
+  Part,
+} from '@google/genai';
+import type {
+  ModelCallResult,
+  ModelMessage,
+  ModelToolCall,
+  ModelToolDefinition,
+} from '@kindgi/capabilities';
+
+/**
+ * Gemini function names: a letter or `_` first, then letters, digits,
+ * `_ . : -`, at most 64 characters. The framework's `<pack>.<tool>` ids
+ * fit as they are, so names go over the wire unchanged.
+ */
+const FUNCTION_NAME = /^[A-Za-z_][A-Za-z0-9_.:-]{0,63}$/;
+
+export function checkFunctionName(name: string): string {
+  if (!FUNCTION_NAME.test(name)) {
+    throw new Error(
+      `@kindgi/adapter-model-gemini: tool "${name}" isn't a valid Gemini function name (a letter or _ first, then letters, digits, _ . : -, at most 64 characters).`,
+    );
+  }
+  return name;
+}
+
+/**
+ * The framework's message trail as a Gemini request:
+ *
+ *   - `system` messages lift into `systemInstruction` (several join with
+ *     a blank line, in order);
+ *   - `user` messages become `user` turns; `assistant` messages become
+ *     `model` turns — text, then one `functionCall` part per tool call,
+ *     carrying the call's thought signature back;
+ *   - `tool` messages become `functionResponse` parts in a `user` turn.
+ *     Gemini names the function it answers, so the name comes from the
+ *     assistant tool call with the same id. The tool's output goes under
+ *     `response.output` (parsed when it is JSON).
+ *
+ * Consecutive turns of the same role merge into one `Content`.
+ */
+export function toGeminiRequest(messages: readonly ModelMessage[]): {
+  readonly systemInstruction: string | undefined;
+  readonly contents: readonly Content[];
+} {
+  const systemParts: string[] = [];
+  const contents: Content[] = [];
+  const callNames = new Map<string, string>();
+
+  for (const msg of messages) {
+    if (msg.role === 'system') {
+      if (msg.content.length > 0) systemParts.push(msg.content);
+    } else if (msg.role === 'user') {
+      append(contents, 'user', [{ text: msg.content }]);
+    } else if (msg.role === 'assistant') {
+      const parts = modelParts(msg, callNames);
+      // An empty model turn is invalid; the agent loop never produces one.
+      if (parts.length > 0) append(contents, 'model', parts);
+    } else {
+      append(contents, 'user', [functionResponsePart(msg, callNames)]);
+    }
+  }
+
+  return {
+    systemInstruction: systemParts.length > 0 ? systemParts.join('\n\n') : undefined,
+    contents,
+  };
+}
+
+/** An assistant message's parts: its text, then a `functionCall` per tool call. */
+function modelParts(msg: ModelMessage, callNames: Map<string, string>): Part[] {
+  const parts: Part[] = msg.content.length > 0 ? [{ text: msg.content }] : [];
+  for (const call of msg.toolCalls ?? []) {
+    callNames.set(call.id, call.name);
+    parts.push({
+      functionCall: {
+        id: call.id,
+        name: checkFunctionName(call.name),
+        args: { ...call.arguments },
+      },
+      ...(call.signature !== undefined && { thoughtSignature: call.signature }),
+    });
+  }
+  return parts;
+}
+
+/** A tool result, named after the call it answers. */
+function functionResponsePart(msg: ModelMessage, callNames: ReadonlyMap<string, string>): Part {
+  const id = msg.toolCallId ?? '';
+  const name = callNames.get(id);
+  if (name === undefined) {
+    throw new Error(
+      `@kindgi/adapter-model-gemini: a tool result answers call "${id}", which no earlier assistant turn made.`,
+    );
+  }
+  return { functionResponse: { id, name, response: { output: parseOutput(msg.content) } } };
+}
+
+function append(contents: Content[], role: 'user' | 'model', parts: readonly Part[]): void {
+  const last = contents[contents.length - 1];
+  if (last !== undefined && last.role === role) {
+    last.parts = [...(last.parts ?? []), ...parts];
+    return;
+  }
+  contents.push({ role, parts: [...parts] });
+}
+
+/** A tool's output: its JSON value when it is JSON, else the text. */
+function parseOutput(content: string): unknown {
+  try {
+    return JSON.parse(content);
+  } catch {
+    return content;
+  }
+}
+
+/**
+ * Tool definitions as Gemini function declarations. The input schema is
+ * full JSON Schema, which `parametersJsonSchema` takes as it is.
+ */
+export function toGeminiFunctions(
+  tools: readonly ModelToolDefinition[],
+): readonly FunctionDeclaration[] {
+  return tools.map((t) => ({
+    name: checkFunctionName(t.name),
+    description: t.description,
+    parametersJsonSchema: t.inputSchema,
+  }));
+}
+
+/**
+ * A Gemini response as the framework's assistant message: the text of
+ * the first candidate (thinking parts left out), and a tool call per
+ * `functionCall` part, with its thought signature. Gemini may omit the
+ * call id; one is generated then, so the tool result can refer to it.
+ */
+export function fromGeminiResponse(response: GenerateContentResponse): {
+  readonly message: ModelMessage;
+  readonly finishReason: ModelCallResult['finishReason'];
+} {
+  const candidate = response.candidates?.[0];
+  if (candidate === undefined) {
+    // No candidate: the prompt itself was blocked.
+    const blocked = response.promptFeedback?.blockReason !== undefined;
+    return {
+      message: { role: 'assistant', content: '' },
+      finishReason: blocked ? 'content-filter' : 'error',
+    };
+  }
+
+  const parts = candidate.content?.parts ?? [];
+  const text = parts
+    .filter((part) => part.functionCall === undefined && part.thought !== true)
+    .map((part) => part.text ?? '');
+  const toolCalls = parts.flatMap((part) =>
+    part.functionCall !== undefined ? [toToolCall(part.functionCall, part.thoughtSignature)] : [],
+  );
+
+  return {
+    message: {
+      role: 'assistant',
+      content: text.join(''),
+      ...(toolCalls.length > 0 && { toolCalls }),
+    },
+    finishReason: toolCalls.length > 0 ? 'tool-use' : mapFinishReason(candidate.finishReason),
+  };
+}
+
+function toToolCall(call: FunctionCall, signature: string | undefined): ModelToolCall {
+  return {
+    id: call.id ?? `gemini-call-${randomUUID()}`,
+    name: call.name ?? '',
+    arguments: (call.args ?? {}) as Readonly<Record<string, unknown>>,
+    ...(signature !== undefined && { signature }),
+  };
+}
+
+const FILTERED = new Set([
+  'SAFETY',
+  'RECITATION',
+  'BLOCKLIST',
+  'PROHIBITED_CONTENT',
+  'SPII',
+  'IMAGE_SAFETY',
+  'IMAGE_PROHIBITED_CONTENT',
+  'IMAGE_RECITATION',
+]);
+
+/**
+ * Gemini's `finishReason` as the framework's:
+ *   - `STOP`, unspecified or absent → `stop` (a response with function
+ *     calls is `tool-use` before this is consulted);
+ *   - `MAX_TOKENS` → `length`;
+ *   - the safety, recitation, blocklist and sensitive-data stops →
+ *     `content-filter`;
+ *   - anything else (a malformed or unexpected function call, too many
+ *     tool calls, an unsupported language, `OTHER`) → `error`.
+ */
+export function mapFinishReason(reason: string | undefined): ModelCallResult['finishReason'] {
+  if (reason === undefined || reason === 'STOP' || reason === 'FINISH_REASON_UNSPECIFIED') {
+    return 'stop';
+  }
+  if (reason === 'MAX_TOKENS') return 'length';
+  if (FILTERED.has(reason)) return 'content-filter';
+  return 'error';
+}