@effect-uai/google 0.11.0 → 0.12.0

package/src/GoogleDeepResearch.ts

@@ -1,6 +1,20 @@
-import { Context, Effect, Layer, Match, Redacted, Ref, Schema, Stream } from "effect"
+import {
+  Array as Arr,
+  Context,
+  Effect,
+  Layer,
+  Match,
+  Option,
+  Redacted,
+  Ref,
+  Result,
+  Schema,
+  Stream,
+  pipe,
+} from "effect"
 import { HttpClient, HttpClientRequest } from "effect/unstable/http"
 import * as AiError from "@effect-uai/core/AiError"
+import type { Source } from "@effect-uai/core/Citation"
 import {
   DeepResearch,
   type DeepResearchService,
@@ -13,6 +27,7 @@ import * as Job from "@effect-uai/core/Job"
 import type { ResearchJobRef, ResearchRequest, ResearchState } from "@effect-uai/core/Research"
 import * as SSE from "@effect-uai/core/SSE"
 import { type Turn, TurnEvent } from "@effect-uai/core/Turn"
+import { GroundingMetadata, groundingToAnnotations } from "./codec.js"
 import type { GoogleDeepResearchModel } from "./models.js"
 
 // ---------------------------------------------------------------------------
@@ -61,23 +76,28 @@ const decodeSubmit = Schema.decodeUnknownEffect(WireSubmit)
 
 // A completed interaction's text lives at `outputs[].text` (SDK `outputs`) or,
 // in some doc examples, `steps[].content[].text`. Decode both defensively and
-// extract from whichever is populated. Citations are undocumented on this
-// preview surface, so none are mapped yet (the report text carries inline
-// `[n]` markers); enrich once a live response confirms the shape.
+// extract from whichever is populated. Grounding sources ride Google's
+// `groundingMetadata.groundingChunks[]`; this preview surface is undocumented,
+// so decode it at every plausible level (interaction / output / step) and map
+// whichever is populated onto `url_citation` annotations. The report text also
+// carries the sources as an inline `[n]` / `**Sources:**` list.
 const WireTextPart = Schema.Struct({
   type: Schema.optional(Schema.NullOr(Schema.String)),
   text: Schema.optional(Schema.NullOr(Schema.String)),
+  groundingMetadata: Schema.optional(Schema.NullOr(GroundingMetadata)),
 })
 const WireStep = Schema.Struct({
   type: Schema.optional(Schema.NullOr(Schema.String)),
   text: Schema.optional(Schema.NullOr(Schema.String)),
   content: Schema.optional(Schema.NullOr(Schema.Array(WireTextPart))),
+  groundingMetadata: Schema.optional(Schema.NullOr(GroundingMetadata)),
 })
 export const WireInteraction = Schema.Struct({
   id: Schema.optional(Schema.NullOr(Schema.String)),
   status: Schema.optional(Schema.NullOr(Schema.String)),
   outputs: Schema.optional(Schema.NullOr(Schema.Array(WireTextPart))),
   steps: Schema.optional(Schema.NullOr(Schema.Array(WireStep))),
+  groundingMetadata: Schema.optional(Schema.NullOr(GroundingMetadata)),
   error: Schema.optional(
     Schema.NullOr(
       Schema.Struct({
@@ -104,18 +124,94 @@ const reportText = (wire: WireInteraction): string => {
   return fromStep.length > 0 ? fromStep : (lastStep?.text ?? "")
 }
 
-const turnFromInteraction = (wire: WireInteraction): Turn => ({
-  items: [
-    {
-      type: "message",
-      role: "assistant",
-      content: [{ type: "output_text", text: reportText(wire) }],
-      providerData: wire,
-    },
-  ],
-  usage: {},
-  stop_reason: "stop",
+/**
+ * The subset of the domain `Citation.Source` this provider can populate.
+ * Declared here rather than derived from the wire schema, so the exported
+ * shape is ours and a wire change cannot silently alter it.
+ */
+const SourceSchema = Schema.Struct({
+  url: Schema.String,
+  title: Schema.optional(Schema.String),
+})
+
+/**
+ * The research trace: what the model did at each step and which sources it
+ * consulted there. The `Turn` keeps only the final report and the deduped
+ * union of all sources, so the per-step breakdown lives here or nowhere.
+ *
+ * Lands on `providerData.gemini`; read it with {@link researchDataOf}.
+ */
+export const GeminiResearchData = Schema.Struct({
+  steps: Schema.Array(
+    Schema.Struct({
+      text: Schema.String,
+      sources: Schema.Array(SourceSchema),
+    }),
+  ),
 })
+export type GeminiResearchData = typeof GeminiResearchData.Type
+
+const decodeResearchData = Schema.decodeUnknownResult(Schema.Struct({ gemini: GeminiResearchData }))
+
+/** Read this provider's data off an item, if it is there and ours. */
+export const researchDataOf = (item: Items.HistoryItem): Option.Option<GeminiResearchData> =>
+  pipe(
+    decodeResearchData(item.providerData),
+    Result.match({
+      onSuccess: (d) => Option.some(d.gemini),
+      onFailure: () => Option.none<GeminiResearchData>(),
+    }),
+  )
+
+const sourcesOf = (meta: GroundingMetadata | null | undefined): ReadonlyArray<Source> =>
+  (meta?.groundingChunks ?? []).flatMap((chunk) =>
+    chunk.web?.uri == null
+      ? []
+      : [{ url: chunk.web.uri, ...(chunk.web.title != null && { title: chunk.web.title }) }],
+  )
+
+// A step contributes to the trace if it said something or consulted something.
+const researchSteps = (wire: WireInteraction): GeminiResearchData["steps"] =>
+  (wire.steps ?? []).flatMap((step) => {
+    const text = textOfParts(step.content) || (step.text ?? "")
+    const sources = [
+      ...sourcesOf(step.groundingMetadata),
+      ...(step.content ?? []).flatMap((p) => sourcesOf(p.groundingMetadata)),
+    ]
+    return text.length === 0 && sources.length === 0 ? [] : [{ text, sources }]
+  })
+
+// Grounding can live at any level of the interaction envelope; gather it from
+// all three (interaction / output part / step) and let `groundingToAnnotations`
+// de-dupe by url.
+const interactionAnnotations = (wire: WireInteraction): ReadonlyArray<Items.Annotation> =>
+  groundingToAnnotations(
+    wire.groundingMetadata,
+    ...Arr.map(wire.outputs ?? [], (o) => o.groundingMetadata),
+    ...Arr.map(wire.steps ?? [], (s) => s.groundingMetadata),
+  )
+
+const turnFromInteraction = (wire: WireInteraction): Turn => {
+  const annotations = interactionAnnotations(wire)
+  return {
+    items: [
+      {
+        type: "message",
+        role: "assistant",
+        content: [
+          {
+            type: "output_text",
+            text: reportText(wire),
+            ...(annotations.length > 0 && { annotations }),
+          },
+        ],
+        providerData: { gemini: { steps: researchSteps(wire) } },
+      },
+    ],
+    usage: {},
+    stop_reason: "stop",
+  }
+}
 
 // Map the interaction status onto the generic `JobState`.
 export const jobStateOf = (wire: WireInteraction): ResearchState =>
@@ -226,6 +322,9 @@ const pollJob = (
       return yield* httpStatusError(response.status, text)
     }
     const json = yield* response.json.pipe(Effect.mapError(transportFailure))
+    // Preview surface: log the raw interaction so the (undocumented) grounding
+    // path can be confirmed against a live completed job at LOG_LEVEL=Debug.
+    yield* Effect.logDebug("google interactions poll response", { interaction: json })
     const wire = yield* decodeInteraction(json).pipe(Effect.mapError(transportFailure))
     return jobStateOf(wire)
   })
@@ -284,7 +383,7 @@ const completedTurn = (wire: WireInteraction | null | undefined, streamed: strin
             type: "message",
             role: "assistant",
             content: [{ type: "output_text", text: streamed }],
-            ...(wire != null && { providerData: wire }),
+            ...(wire != null && { providerData: { gemini: { steps: researchSteps(wire) } } }),
           },
         ],
         usage: {},

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>
       }
@@ -292,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)
 
@@ -327,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),
                 },
@@ -466,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
@@ -480,6 +549,7 @@ export const emptyAccumulator: Accumulator = {
   text: "",
   reasoning: "",
   functionCalls: [],
+  annotations: [],
   finishReason: Option.none(),
   usage: {},
 }
@@ -598,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)
@@ -608,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),
     },
@@ -624,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

@@ -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" },
+    ])
   })
 })