agentfootprint 9.12.0 → 9.14.0

package/dist/esm/adapters/llm/GeminiProvider.d.ts

@@ -0,0 +1,204 @@
+/**
+ * GeminiProvider — wraps `@google/genai` as an `LLMProvider` (9.13.0).
+ *
+ * Pattern: Adapter (GoF) + Ports-and-Adapters (Cockburn 2005).
+ * Role:    Outer ring — translates `LLMRequest`/`LLMResponse` to/from Google's
+ *          `generateContent` API. Knows nothing about agents, recorders, or
+ *          compositions.
+ * Emits:   N/A — providers don't emit; recorders observe via Agent.
+ *
+ * ─── Two doors, one adapter ─────────────────────────────────────────
+ *
+ * The same SDK reaches two different services, and which one you get is a
+ * property of the OPTIONS, not of a separate factory:
+ *
+ *   • **Vertex** — `gemini({ project, location })` builds
+ *     `new GoogleGenAI({ vertexai: true, project, location, googleAuthOptions })`.
+ *     Auth is Application Default Credentials (env key file, gcloud user
+ *     credentials, or the metadata server on GCE / Cloud Run / Agent Runtime).
+ *     No API key exists on this path.
+ *   • **Gemini API (AI Studio)** — `gemini({ apiKey })` builds
+ *     `new GoogleGenAI({ apiKey })`. One key, no cloud project.
+ *
+ * Neither is guessed. The factory refuses at construction when it can resolve
+ * neither a project nor a key, naming both doors — because the SDK's own
+ * behaviour in that case is to WARN on stderr, construct anyway, and fail on
+ * the first call, which reads like a network problem rather than a missing
+ * setting.
+ *
+ * ─── Why native, and not `openai({ baseURL })` ──────────────────────
+ *
+ * Google publishes an OpenAI-compatible endpoint, and it does work — for about
+ * an hour. It authenticates with an OAuth access token that expires and has no
+ * refresh home in `OpenAIProviderOptions`; its `tools.function.parameters` is
+ * **OpenAPI**, not JSON Schema, so `$ref` / `oneOf` / `additionalProperties`
+ * diverge silently; unsupported parameters are ignored rather than refused; and
+ * its documented response carries no cached- or reasoning-token counts. This
+ * adapter exists because every one of those is answerable on the native SDK:
+ * ADC refreshes itself, tools go over as JSON Schema untranslated
+ * (`parametersJsonSchema`), a forced single tool is expressible, and
+ * `usageMetadata` reports cached and thinking tokens as separate numbers.
+ *
+ * ─── Limitations (stated, not discovered) ───────────────────────────
+ *
+ * • Multi-modal input/output NOT supported — `LLMMessage.content` is `string`,
+ *   so this adapter sends and reads text parts only. Inline data, files and
+ *   generated images are out of scope for the port as it stands.
+ * • **Thought summaries are not requested.** `usage.thinking` is reported
+ *   honestly from `thoughtsTokenCount`, and `req.thinking.budget` is threaded
+ *   to `thinkingConfig.thinkingBudget` — but `includeThoughts` is deliberately
+ *   left unset, so no `rawThinking` is produced. Gemini's thought parts carry a
+ *   `thoughtSignature` that has to be echoed byte-exact on the next turn, and
+ *   there is no Gemini `ThinkingHandler` in this release to normalize and
+ *   round-trip them. Asking for content nothing can carry would be a leak, not
+ *   a feature. `thinkingConfig.thinkingLevel` has no field on `LLMRequest` and
+ *   is likewise not sent.
+ * • `responseJsonSchema` (native structured output) is NOT exposed; use
+ *   `.outputSchema(...)`, which goes over as a forced tool — a shape this
+ *   adapter DOES carry.
+ * • Grounding tools (Google Search, code execution, URL context, MCP servers)
+ *   are not exposed. `tools` carries function declarations only.
+ */
+import type { LLMCallHooks, LLMChunk, LLMProvider, LLMRequest, LLMResponse, WireRole } from '../types.js';
+import { type GoogleGenAIConnectionOptions } from './googleGenAI.js';
+/** One `parts[]` entry. Only the members this adapter reads or writes. */
+export interface GeminiPart {
+    readonly text?: string;
+    /** `true` on a thought-summary part. Never joined into visible content. */
+    readonly thought?: boolean;
+    readonly functionCall?: {
+        readonly id?: string;
+        readonly name?: string;
+        readonly args?: Record<string, unknown>;
+    };
+    readonly functionResponse?: {
+        readonly id?: string;
+        readonly name?: string;
+        readonly response?: Record<string, unknown>;
+    };
+}
+/** One conversation turn. Gemini's assistant role is spelled `'model'`. */
+export interface GeminiContent {
+    readonly role: 'user' | 'model';
+    readonly parts: readonly GeminiPart[];
+}
+/** A `FunctionDeclaration`, JSON-Schema flavour. */
+export interface GeminiFunctionDeclaration {
+    readonly name: string;
+    readonly description: string;
+    /**
+     * JSON Schema, passed through UNCHANGED. The sibling `parameters` field
+     * takes OpenAPI instead and is never set here — sending both is what makes
+     * an adapter's tool schemas quietly disagree with the ones it was given.
+     */
+    readonly parametersJsonSchema: Record<string, unknown>;
+}
+export interface GeminiGenerateConfig {
+    systemInstruction?: string;
+    temperature?: number;
+    maxOutputTokens?: number;
+    stopSequences?: string[];
+    abortSignal?: AbortSignal;
+    tools?: {
+        functionDeclarations: GeminiFunctionDeclaration[];
+    }[];
+    toolConfig?: {
+        functionCallingConfig: {
+            mode: 'AUTO' | 'ANY' | 'NONE';
+            allowedFunctionNames?: string[];
+        };
+    };
+    thinkingConfig?: {
+        thinkingBudget: number;
+    };
+}
+export interface GeminiGenerateParams {
+    readonly model: string;
+    readonly contents: readonly GeminiContent[];
+    readonly config?: GeminiGenerateConfig;
+}
+export interface GeminiUsageMetadata {
+    readonly promptTokenCount?: number;
+    readonly candidatesTokenCount?: number;
+    readonly cachedContentTokenCount?: number;
+    readonly thoughtsTokenCount?: number;
+    readonly totalTokenCount?: number;
+}
+export interface GeminiCandidate {
+    readonly content?: {
+        readonly parts?: readonly GeminiPart[];
+    };
+    readonly finishReason?: string;
+}
+export interface GeminiGenerateResponse {
+    readonly candidates?: readonly GeminiCandidate[];
+    readonly usageMetadata?: GeminiUsageMetadata;
+    readonly responseId?: string;
+}
+/**
+ * The `models` namespace, narrowed to the two operations this adapter
+ * dispatches.
+ *
+ * `countTokens` is deliberately ABSENT. It exists on the real namespace and it
+ * would be an easy way to fill in a usage number the wire did not report —
+ * which is precisely why it is not here. A count we asked for separately is not
+ * what the call was billed for; see the streaming note on `stream()`.
+ */
+export interface GeminiModelsLike {
+    generateContent(params: GeminiGenerateParams): Promise<GeminiGenerateResponse>;
+    /** Note the double await: the SDK returns a PROMISE of an async generator. */
+    generateContentStream(params: GeminiGenerateParams): Promise<AsyncIterable<GeminiGenerateResponse>>;
+}
+/** What `new GoogleGenAI(...)` gives us, narrowed to what we use. */
+export interface GeminiClientLike {
+    readonly models: GeminiModelsLike;
+}
+export interface GeminiProviderOptions extends GoogleGenAIConnectionOptions {
+    /**
+     * Default model used when `LLMRequest.model` is `'gemini'` (the shorthand).
+     * A request naming a full model id wins.
+     */
+    readonly defaultModel?: string;
+    /** Default `maxOutputTokens` when the request doesn't set it. Optional. */
+    readonly defaultMaxTokens?: number;
+    /** @internal Pre-built client for testing. Skips the SDK import entirely. */
+    readonly _client?: GeminiClientLike;
+}
+/**
+ * Build an `LLMProvider` backed by Gemini — on Vertex or on the Gemini API.
+ *
+ * @example  Vertex (Application Default Credentials)
+ * ```ts
+ * import { Agent } from 'agentfootprint';
+ * import { gemini } from 'agentfootprint/providers';
+ *
+ * const agent = Agent.create({
+ *   provider: gemini({ project: 'my-project', location: 'us-central1' }),
+ *   model: 'gemini',
+ * })
+ *   .tool(weatherTool)
+ *   .build();
+ * ```
+ *
+ * @example  Gemini API (one key, no cloud project)
+ * ```ts
+ * const provider = gemini({ apiKey: process.env.GEMINI_API_KEY });
+ * ```
+ *
+ * @throws at construction when neither a project nor an API key is resolvable,
+ *         and when `@google/genai` is not installed.
+ */
+export declare function gemini(options?: GeminiProviderOptions): LLMProvider;
+/**
+ * Class form for consumers who prefer `new GeminiProvider(...)` over the
+ * `gemini(...)` factory. Identical behavior; trivial wrapper.
+ */
+export declare class GeminiProvider implements LLMProvider {
+    readonly name = "gemini";
+    readonly carriesInMessages: readonly WireRole[];
+    readonly carriesForcedToolChoice = true;
+    private readonly inner;
+    constructor(options?: GeminiProviderOptions);
+    complete(req: LLMRequest, hooks?: LLMCallHooks): Promise<LLMResponse>;
+    stream(req: LLMRequest, hooks?: LLMCallHooks): AsyncIterable<LLMChunk>;
+}