@effect-uai/google 0.11.0 → 0.12.1

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>
       }
@@ -169,16 +218,12 @@ const messageText = (message: Message): string => message.content.map(blockText)
  */
 const imageSourceToParts = Match.type<InputImage["source"]>().pipe(
   Match.tag("url", (): ReadonlyArray<RequestPart> => []),
-  Match.tag(
-    "base64",
-    (s): ReadonlyArray<RequestPart> => [{ inlineData: { mimeType: s.mimeType, data: s.base64 } }],
-  ),
-  Match.tag(
-    "bytes",
-    (s): ReadonlyArray<RequestPart> => [
-      { inlineData: { mimeType: s.mimeType, data: Encoding.encodeBase64(s.bytes) } },
-    ],
-  ),
+  Match.tag("base64", (s): ReadonlyArray<RequestPart> => [
+    { inlineData: { mimeType: s.mimeType, data: s.base64 } },
+  ]),
+  Match.tag("bytes", (s): ReadonlyArray<RequestPart> => [
+    { inlineData: { mimeType: s.mimeType, data: Encoding.encodeBase64(s.bytes) } },
+  ]),
   Match.exhaustive,
 )
 
@@ -292,6 +337,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)
 
@@ -327,6 +386,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),
                 },
@@ -367,7 +430,9 @@ const sanitizeSchema = (schema: unknown): unknown => {
   )
 }
 
-const toolDescriptorsToTools = (tools: ReadonlyArray<ToolDescriptor>): ReadonlyArray<RequestTool> =>
+const toolDescriptorsToTools = (
+  tools: ReadonlyArray<ToolDescriptor>,
+): ReadonlyArray<RequestTool> =>
   tools.length === 0
     ? []
     : [
@@ -466,6 +531,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
@@ -480,6 +547,7 @@ export const emptyAccumulator: Accumulator = {
   text: "",
   reasoning: "",
   functionCalls: [],
+  annotations: [],
   finishReason: Option.none(),
   usage: {},
 }
@@ -598,6 +666,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)
@@ -608,6 +684,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),
     },
@@ -624,7 +704,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

@@ -1,8 +1,15 @@
 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, buildRequestBody } from "./codec.js"
+import {
+  WireChunk,
+  accumulatorToTurn,
+  buildRequestBody,
+  emptyAccumulator,
+  ingestChunk,
+} from "./codec.js"
 import { codeExecutionTool, googleSearchTool, renderProviderTools } from "./GeminiTools.js"
 
 const localTool = Tool.make({
@@ -69,14 +76,19 @@ describe("Gemini provider tools", () => {
     expect(Result.isFailure(result)).toBe(true)
   })
 
-  it("decodes a grounded chunk without throwing (groundingMetadata is dropped)", () => {
+  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" } }],
+            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",
         },
@@ -84,5 +96,11 @@ describe("Gemini provider tools", () => {
     }
     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" },
+    ])
   })
 })