@effect-uai/google 0.10.0 → 0.12.0

package/src/codec.ts

@@ -5,6 +5,7 @@ import type {
   InputImage,
   HistoryItem,
   Message,
+  Annotation,
 } from "@effect-uai/core/Items"
 import type { ToolDescriptor } from "@effect-uai/core/Tool"
 import type { Turn } from "@effect-uai/core/Turn"
@@ -50,8 +51,55 @@ const Content = Schema.Struct({
   parts: Schema.optional(Schema.Array(Part)),
 })
 
+// Google grounding metadata. On a grounded response the candidate carries
+// `groundingChunks[].web.{uri,title}` - the structured form of the inline `[n]`
+// / trailing `**Sources:**` list the model renders into the answer text.
+// Decoded defensively (every field optional) as it is absent on ungrounded
+// turns. Shared with the Interactions deep-research surface via `codec.ts`.
+const GroundingChunk = Schema.Struct({
+  web: Schema.optional(
+    Schema.NullOr(
+      Schema.Struct({
+        uri: Schema.optional(Schema.NullOr(Schema.String)),
+        title: Schema.optional(Schema.NullOr(Schema.String)),
+      }),
+    ),
+  ),
+})
+export const GroundingMetadata = Schema.Struct({
+  groundingChunks: Schema.optional(Schema.NullOr(Schema.Array(GroundingChunk))),
+})
+export type GroundingMetadata = typeof GroundingMetadata.Type
+
+// Two citations are the same source when they point at the same url.
+const sameUrlCitation = (a: Annotation, b: Annotation): boolean =>
+  a.type === "url_citation" && b.type === "url_citation" && a.url === b.url
+
+// Grounding chunks → `url_citation` annotations, de-duped by url across every
+// metadata block passed. `web.uri` is a `grounding-api-redirect` URL and
+// `web.title` the bare domain; both are kept as-is (the redirect resolves to
+// the real page).
+export const groundingToAnnotations = (
+  ...metas: ReadonlyArray<GroundingMetadata | null | undefined>
+): ReadonlyArray<Annotation> =>
+  pipe(
+    metas,
+    Arr.flatMap((meta) => meta?.groundingChunks ?? []),
+    Arr.filterMap((chunk) =>
+      chunk.web?.uri == null
+        ? Result.failVoid
+        : Result.succeed<Annotation>({
+            type: "url_citation",
+            url: chunk.web.uri,
+            title: chunk.web.title ?? chunk.web.uri,
+          }),
+    ),
+    Arr.dedupeWith(sameUrlCitation),
+  )
+
 const Candidate = Schema.Struct({
   content: Schema.optional(Content),
+  groundingMetadata: Schema.optional(GroundingMetadata),
   finishReason: Schema.optional(Schema.String),
   index: Schema.optional(Schema.Number),
 })
@@ -87,6 +135,7 @@ type RequestPart =
     }
   | {
       readonly functionResponse: {
+        readonly id?: string
         readonly name: string
         readonly response: Record<string, unknown>
       }
@@ -101,14 +150,24 @@ type RequestSystemInstruction = {
   readonly parts: ReadonlyArray<{ readonly text: string }>
 }
 
-/** Gemini's tool declaration. We translate one `ToolDescriptor` per entry. */
-type RequestTool = {
-  readonly functionDeclarations: ReadonlyArray<{
-    readonly name: string
-    readonly description: string
-    readonly parameters: Record<string, unknown>
-  }>
-}
+/**
+ * Gemini's tool declaration. A `tools[]` entry is either a function-declaration
+ * block (translated from `ToolDescriptor`s) or one of the native hosted-tool
+ * entries. The native entries are empty objects keyed camelCase per the REST
+ * v1beta `Tool` object, and sit as siblings of the declarations in the same
+ * `tools` array.
+ */
+export type RequestTool =
+  | {
+      readonly functionDeclarations: ReadonlyArray<{
+        readonly name: string
+        readonly description: string
+        readonly parameters: Record<string, unknown>
+      }>
+    }
+  | { readonly googleSearch: {} }
+  | { readonly urlContext: {} }
+  | { readonly codeExecution: {} }
 
 type RequestToolConfig = {
   readonly functionCallingConfig: {
@@ -282,6 +341,20 @@ const geminiField = (
   )
 
 const providerIdFor = (item: ToolCall): Option.Option<string> => geminiField(item, (g) => g.id)
+
+// The originating call's Gemini id, looked up from history by our `call_id`.
+// Gemini 3 maps a `functionResponse` back to its call by this id, so parallel
+// calls to the same function are mis-paired if we drop it.
+const providerIdForCallId = (
+  history: ReadonlyArray<HistoryItem>,
+  call_id: string,
+): Option.Option<string> =>
+  pipe(
+    history,
+    Arr.findFirst((item): item is ToolCall => isFunctionCallItem(item) && item.call_id === call_id),
+    Option.flatMap(providerIdFor),
+  )
+
 const signatureFor = (item: ToolCall): Option.Option<string> =>
   geminiField(item, (g) => g.thoughtSignature)
 
@@ -317,6 +390,10 @@ const itemToContent =
             parts: [
               {
                 functionResponse: {
+                  ...Option.match(providerIdForCallId(history, o.call_id), {
+                    onSome: (id) => ({ id }),
+                    onNone: () => ({}),
+                  }),
                   name: Option.getOrElse(nameForCallId(history, o.call_id), () => o.call_id),
                   response: parsedResponse(o.output),
                 },
@@ -402,11 +479,13 @@ export const buildRequestBody = (
   history: ReadonlyArray<HistoryItem>,
   generationConfig: Option.Option<GenerationConfig>,
   tools: ReadonlyArray<ToolDescriptor> = [],
+  providerToolEntries: ReadonlyArray<RequestTool> = [],
   toolChoice: CommonRequest["toolChoice"] = undefined,
 ): RequestBody => {
   const systemTexts = pipe(allMessages(history), Arr.filterMap(systemMessageText))
   const contents = pipe(history, Arr.filterMap(itemToContent(history)))
-  const requestTools = toolDescriptorsToTools(tools)
+  const functionTools = toolDescriptorsToTools(tools)
+  const requestTools = [...functionTools, ...providerToolEntries]
   return {
     contents,
     ...(systemTexts.length > 0 && {
@@ -416,8 +495,10 @@ export const buildRequestBody = (
       onNone: () => ({}),
       onSome: (cfg) => ({ generationConfig: cfg }),
     }),
-    ...(requestTools.length > 0 && {
-      tools: requestTools,
+    ...(requestTools.length > 0 && { tools: requestTools }),
+    // Only force a function-calling mode when there are function declarations;
+    // a grounding-only request must keep the API default.
+    ...(functionTools.length > 0 && {
       toolConfig: { functionCallingConfig: toolChoiceToFunctionCallingConfig(toolChoice) },
     }),
   }
@@ -452,6 +533,8 @@ export type Accumulator = {
   readonly text: string
   readonly reasoning: string
   readonly functionCalls: ReadonlyArray<AccumulatedFunctionCall>
+  /** Grounding citations, accumulated (de-duped by url) across chunks. */
+  readonly annotations: ReadonlyArray<Annotation>
   readonly finishReason: Option.Option<string>
   readonly usage: {
     readonly input_tokens?: number
@@ -466,6 +549,7 @@ export const emptyAccumulator: Accumulator = {
   text: "",
   reasoning: "",
   functionCalls: [],
+  annotations: [],
   finishReason: Option.none(),
   usage: {},
 }
@@ -584,6 +668,14 @@ const appendFunctionCalls = (
     prior,
   )
 
+// Grounding usually arrives on the final chunk, but merge across chunks and
+// de-dupe by url so a mid-stream metadata block is not lost or double-counted.
+const mergeAnnotations = (
+  prev: ReadonlyArray<Annotation>,
+  next: ReadonlyArray<Annotation>,
+): ReadonlyArray<Annotation> =>
+  next.length === 0 ? prev : Arr.dedupeWith(Arr.appendAll(prev, next), sameUrlCitation)
+
 export const ingestChunk = (acc: Accumulator, chunk: WireChunk): ChunkResult => {
   const parts = chunkParts(chunk)
   const finishReason = Option.fromNullishOr(chunk.candidates?.[0]?.finishReason)
@@ -594,6 +686,10 @@ export const ingestChunk = (acc: Accumulator, chunk: WireChunk): ChunkResult =>
       text: acc.text + sumStrings(parts, "text"),
       reasoning: acc.reasoning + sumStrings(parts, "reasoning"),
       functionCalls: appendFunctionCalls(acc.functionCalls, collectFunctionCalls(parts)),
+      annotations: mergeAnnotations(
+        acc.annotations,
+        groundingToAnnotations(chunk.candidates?.[0]?.groundingMetadata),
+      ),
       finishReason: Option.orElse(finishReason, () => acc.finishReason),
       usage: mergeUsage(acc.usage, chunk.usageMetadata),
     },
@@ -610,7 +706,13 @@ const assistantMessageItems = (acc: Accumulator): ReadonlyArray<HistoryItem> =>
         {
           type: "message",
           role: "assistant",
-          content: [{ type: "output_text", text: acc.text }],
+          content: [
+            {
+              type: "output_text",
+              text: acc.text,
+              ...(acc.annotations.length > 0 && { annotations: acc.annotations }),
+            },
+          ],
         },
       ]
 

package/src/geminiTools.test.ts

@@ -0,0 +1,106 @@
+import { Effect, Option, Result, Schema } from "effect"
+import * as Tool from "@effect-uai/core/Tool"
+import { descriptorsOf, providerToolsOf } from "@effect-uai/core/Tool"
+import * as Turn from "@effect-uai/core/Turn"
+import { describe, expect, it } from "vitest"
+import {
+  WireChunk,
+  accumulatorToTurn,
+  buildRequestBody,
+  emptyAccumulator,
+  ingestChunk,
+} from "./codec.js"
+import { codeExecutionTool, googleSearchTool, renderProviderTools } from "./GeminiTools.js"
+
+const localTool = Tool.make({
+  name: "get_weather",
+  description: "Look up the weather.",
+  inputSchema: Tool.fromEffectSchema(Schema.Struct({ city: Schema.String })),
+  run: ({ city }) => Effect.succeed(`sunny in ${city}`),
+})
+
+const build = (toolkit: Record<string, Tool.AnyTool>) => {
+  const entries = Result.getOrThrow(renderProviderTools(providerToolsOf(toolkit)))
+  return buildRequestBody([], Option.none(), descriptorsOf(toolkit), entries)
+}
+
+describe("Gemini provider tools", () => {
+  it("renders google_search to the native googleSearch entry", () => {
+    const body = build({ google_search: googleSearchTool })
+    expect(body.tools).toEqual([{ googleSearch: {} }])
+  })
+
+  it("renders a mixed toolkit to both a functionDeclarations entry and the native entry", () => {
+    const body = build({ get_weather: localTool, code_execution: codeExecutionTool })
+    expect(body.tools).toEqual([
+      {
+        functionDeclarations: [
+          expect.objectContaining({ name: "get_weather", description: "Look up the weather." }),
+        ],
+      },
+      { codeExecution: {} },
+    ])
+  })
+
+  it("omits toolConfig for a grounding-only request (no forced function-calling mode)", () => {
+    const body = build({ google_search: googleSearchTool })
+    expect(body.toolConfig).toBeUndefined()
+  })
+
+  it("sets toolConfig when a function declaration is present", () => {
+    const body = build({ get_weather: localTool, google_search: googleSearchTool })
+    expect(body.toolConfig).toEqual({ functionCallingConfig: { mode: "AUTO" } })
+  })
+
+  it("fails on a foreign provider tool", () => {
+    const foreign = Tool.provider({
+      name: "web_search",
+      description: "Anthropic web search.",
+      inputSchema: Tool.noInput,
+      provider: "anthropic",
+      config: { type: "web_search_20250305" },
+    })
+    const result = renderProviderTools(providerToolsOf({ web_search: foreign }))
+    expect(Result.isFailure(result)).toBe(true)
+  })
+
+  it("fails on an unrecognized config kind", () => {
+    const bogus = Tool.provider({
+      name: "mystery",
+      description: "Unknown Gemini tool.",
+      inputSchema: Tool.noInput,
+      provider: "gemini",
+      config: { kind: "telepathy" },
+    })
+    const result = renderProviderTools(providerToolsOf({ mystery: bogus }))
+    expect(Result.isFailure(result)).toBe(true)
+  })
+
+  it("maps groundingMetadata chunks to url_citation annotations on the turn", () => {
+    const grounded = {
+      candidates: [
+        {
+          content: { role: "model", parts: [{ text: "Grounded answer." }] },
+          groundingMetadata: {
+            webSearchQueries: ["effect ts"],
+            groundingChunks: [
+              { web: { uri: "https://example.com", title: "Example" } },
+              // Duplicate uri (de-duped) and a bare-domain title fallback.
+              { web: { uri: "https://example.com", title: "Example" } },
+              { web: { uri: "https://effect.website" } },
+            ],
+          },
+          finishReason: "STOP",
+        },
+      ],
+    }
+    const chunk = Schema.decodeUnknownSync(WireChunk)(grounded)
+    expect(chunk.candidates?.[0]?.content?.parts?.[0]).toEqual({ text: "Grounded answer." })
+
+    const turn = accumulatorToTurn(ingestChunk(emptyAccumulator, chunk).accumulator)
+    expect(Turn.citations(turn)).toEqual([
+      { type: "url_citation", url: "https://example.com", title: "Example" },
+      { type: "url_citation", url: "https://effect.website", title: "https://effect.website" },
+    ])
+  })
+})

package/src/index.ts

@@ -1,6 +1,8 @@
 export * as Gemini from "./Gemini.js"
+export * as GeminiTools from "./GeminiTools.js"
 export * as GeminiEmbedding from "./GeminiEmbedding.js"
 export * as GeminiSynthesizer from "./GeminiSynthesizer.js"
+export * as GoogleDeepResearch from "./GoogleDeepResearch.js"
 export * as LyriaGenerator from "./LyriaGenerator.js"
 export * as codec from "./codec.js"
 export * from "./models.js"

package/src/models.ts

@@ -17,6 +17,21 @@ export type GoogleModel =
   // eslint-disable-next-line @typescript-eslint/ban-types
   | (string & {})
 
+/**
+ * Deep-research agent identifiers for the Interactions API (`POST
+ * /v1beta/interactions`). `-preview` is the fast tier, `-max-` the
+ * comprehensive one. Preview surface: verify against live docs before relying on
+ * exact ids. The `(string & {})` tail accepts any string so a renamed agent
+ * works without an SDK update.
+ *
+ * Reference: https://ai.google.dev/gemini-api/docs/interactions/deep-research
+ */
+export type GoogleDeepResearchModel =
+  | "deep-research-preview-04-2026"
+  | "deep-research-max-preview-04-2026"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
 /**
  * Known Gemini embedding model identifiers.
  *