@tanstack/ai-gemini 0.10.10 → 0.12.0

package/src/experimental/text-interactions/events.ts

@@ -0,0 +1,191 @@
+import type { Interactions } from '@google/genai'
+import type { CustomEvent, StreamChunk } from '@tanstack/ai'
+
+/**
+ * `CUSTOM` event carrying the server-assigned Interactions API id. Emitted
+ * immediately before `RUN_FINISHED` on a successful run; pass `interactionId`
+ * back as `modelOptions.previous_interaction_id` to continue the conversation.
+ */
+export interface GeminiInteractionIdEvent extends Omit<
+  CustomEvent,
+  'name' | 'value'
+> {
+  name: 'gemini.interactionId'
+  value: { interactionId: string }
+}
+
+/**
+ * `CUSTOM` event carrying a raw `google_search_call` content delta from the
+ * Interactions API. Payload shape is owned by `@google/genai`.
+ */
+export interface GeminiGoogleSearchCallEvent extends Omit<
+  CustomEvent,
+  'name' | 'value'
+> {
+  name: 'gemini.googleSearchCall'
+  value: Interactions.ContentDelta.GoogleSearchCallDelta
+}
+
+/**
+ * `CUSTOM` event carrying a raw `google_search_result` content delta from
+ * the Interactions API.
+ */
+export interface GeminiGoogleSearchResultEvent extends Omit<
+  CustomEvent,
+  'name' | 'value'
+> {
+  name: 'gemini.googleSearchResult'
+  value: Interactions.ContentDelta.GoogleSearchResultDelta
+}
+
+/**
+ * `CUSTOM` event carrying a raw `code_execution_call` content delta from
+ * the Interactions API.
+ */
+export interface GeminiCodeExecutionCallEvent extends Omit<
+  CustomEvent,
+  'name' | 'value'
+> {
+  name: 'gemini.codeExecutionCall'
+  value: Interactions.ContentDelta.CodeExecutionCallDelta
+}
+
+/**
+ * `CUSTOM` event carrying a raw `code_execution_result` content delta from
+ * the Interactions API.
+ */
+export interface GeminiCodeExecutionResultEvent extends Omit<
+  CustomEvent,
+  'name' | 'value'
+> {
+  name: 'gemini.codeExecutionResult'
+  value: Interactions.ContentDelta.CodeExecutionResultDelta
+}
+
+/**
+ * `CUSTOM` event carrying a raw `url_context_call` content delta from the
+ * Interactions API.
+ */
+export interface GeminiUrlContextCallEvent extends Omit<
+  CustomEvent,
+  'name' | 'value'
+> {
+  name: 'gemini.urlContextCall'
+  value: Interactions.ContentDelta.URLContextCallDelta
+}
+
+/**
+ * `CUSTOM` event carrying a raw `url_context_result` content delta from the
+ * Interactions API.
+ */
+export interface GeminiUrlContextResultEvent extends Omit<
+  CustomEvent,
+  'name' | 'value'
+> {
+  name: 'gemini.urlContextResult'
+  value: Interactions.ContentDelta.URLContextResultDelta
+}
+
+/**
+ * `CUSTOM` event carrying a raw `file_search_call` content delta from the
+ * Interactions API.
+ */
+export interface GeminiFileSearchCallEvent extends Omit<
+  CustomEvent,
+  'name' | 'value'
+> {
+  name: 'gemini.fileSearchCall'
+  value: Interactions.ContentDelta.FileSearchCallDelta
+}
+
+/**
+ * `CUSTOM` event carrying a raw `file_search_result` content delta from the
+ * Interactions API.
+ */
+export interface GeminiFileSearchResultEvent extends Omit<
+  CustomEvent,
+  'name' | 'value'
+> {
+  name: 'gemini.fileSearchResult'
+  value: Interactions.ContentDelta.FileSearchResultDelta
+}
+
+/**
+ * Discriminated union of every `CUSTOM` event the
+ * `geminiTextInteractions()` adapter emits.
+ *
+ * Each variant carries the lifecycle fields `model?` / `timestamp?` /
+ * `rawEvent?` from {@link CustomEvent} so a single narrow against the
+ * `StreamChunk` union yields a fully typed payload — no helper or `as`
+ * cast required:
+ *
+ * ```ts
+ * for await (const chunk of stream as GeminiInteractionsStream) {
+ *   if (chunk.type === 'CUSTOM' && chunk.name === 'gemini.interactionId') {
+ *     chunk.value.interactionId // string
+ *   }
+ * }
+ * ```
+ *
+ * The four tool-delta variant pairs (`google_search`, `code_execution`,
+ * `url_context`, `file_search`) forward the raw
+ * `Interactions.ContentDelta.*Delta` payload from `@google/genai` so
+ * consumers stay in sync with SDK shape changes automatically.
+ * `computer_use` is accepted as a request tool but the API does not
+ * stream per-delta CUSTOM events for it.
+ */
+export type GeminiInteractionsCustomEvent =
+  | GeminiInteractionIdEvent
+  | GeminiGoogleSearchCallEvent
+  | GeminiGoogleSearchResultEvent
+  | GeminiCodeExecutionCallEvent
+  | GeminiCodeExecutionResultEvent
+  | GeminiUrlContextCallEvent
+  | GeminiUrlContextResultEvent
+  | GeminiFileSearchCallEvent
+  | GeminiFileSearchResultEvent
+
+/** String-literal union of the event names in {@link GeminiInteractionsCustomEvent}. */
+export type GeminiInteractionsCustomEventName =
+  GeminiInteractionsCustomEvent['name']
+
+/**
+ * Look up the typed `value` payload for a specific event name.
+ *
+ * ```ts
+ * const v: GeminiInteractionsCustomEventValue<'gemini.interactionId'>
+ * //    ^? { interactionId: string }
+ * ```
+ */
+export type GeminiInteractionsCustomEventValue<
+  TName extends GeminiInteractionsCustomEventName,
+> = Extract<GeminiInteractionsCustomEvent, { name: TName }>['value']
+
+/**
+ * Public stream type for `chatStream` results from the
+ * `geminiTextInteractions()` adapter. Yields the standard
+ * {@link StreamChunk} lifecycle events plus the Gemini-specific
+ * `CUSTOM` events declared in {@link GeminiInteractionsCustomEvent},
+ * so a single discriminated narrow on `chunk.name` gives a typed
+ * `chunk.value`:
+ *
+ * ```ts
+ * import type { GeminiInteractionsStream } from '@tanstack/ai-gemini/experimental'
+ *
+ * for await (const chunk of stream as GeminiInteractionsStream) {
+ *   if (chunk.type === 'CUSTOM' && chunk.name === 'gemini.interactionId') {
+ *     chunk.value.interactionId // typed as string
+ *   }
+ * }
+ * ```
+ *
+ * Caveat: server tools may emit arbitrary user-defined custom events via
+ * `emitCustomEvent(name, value)`. Those flow through the stream at
+ * runtime but are intentionally absent from this union — including a
+ * bare {@link CustomEvent} would collapse `chunk.value` back to `any`
+ * after the narrow. Branch on `CUSTOM` outside the literal-`name`
+ * narrows or cast explicitly if you rely on `emitCustomEvent`.
+ */
+export type GeminiInteractionsStream = AsyncIterable<
+  Exclude<StreamChunk, CustomEvent> | GeminiInteractionsCustomEvent
+>

package/src/experimental/text-interactions/provider-options.ts

@@ -0,0 +1,26 @@
+import type { Interactions } from '@google/genai'
+
+/**
+ * Provider options for `geminiTextInteractions()`. Derived from the SDK's
+ * own `interactions.create` param shape so field types (including the
+ * allowed `response_modalities` values and the `generation_config` schema)
+ * stay in sync with `@google/genai` automatically.
+ *
+ * `input`, `model`, `tools`, `stream`, and `api_version` are intentionally
+ * omitted — the adapter derives those from its constructor args and the
+ * chat options.
+ *
+ * @see https://ai.google.dev/gemini-api/docs/interactions
+ * @experimental Interactions API is in Beta.
+ */
+export type ExternalTextInteractionsProviderOptions = Pick<
+  Interactions.CreateModelInteractionParamsStreaming,
+  | 'previous_interaction_id'
+  | 'store'
+  | 'background'
+  | 'system_instruction'
+  | 'response_modalities'
+  | 'response_format'
+  | 'response_mime_type'
+  | 'generation_config'
+>

package/src/index.ts

@@ -62,7 +62,10 @@ export {
 } from './adapters/audio'
 
 // Re-export models from model-meta for convenience
-export { GEMINI_MODELS } from './model-meta'
+export {
+  GEMINI_MODELS,
+  GEMINI_COMBINED_TOOLS_AND_SCHEMA_MODELS,
+} from './model-meta'
 export { GEMINI_MODELS as GeminiTextModels } from './model-meta'
 export { GEMINI_IMAGE_MODELS as GeminiImageModels } from './model-meta'
 export { GEMINI_TTS_MODELS as GeminiTTSModels } from './model-meta'

package/src/model-meta.ts

@@ -1015,6 +1015,21 @@ export const GEMINI_MODELS = [
   GEMINI_3_5_FLASH.name,
 ] as const
 
+/**
+ * Gemini models that support combining `tools` + `responseSchema` in a
+ * single streaming `generateContent` call (per issue #605). Per the
+ * provider matrix, Gemini 3.x natively interleaves the schema-constrained
+ * answer with function-calling on one pass; Gemini 2.x is unsupported /
+ * brittle and keeps the engine's legacy finalization fallback.
+ */
+export const GEMINI_COMBINED_TOOLS_AND_SCHEMA_MODELS = new Set<string>([
+  GEMINI_3_1_PRO.name,
+  GEMINI_3_PRO.name,
+  GEMINI_3_FLASH.name,
+  GEMINI_3_1_FLASH_LITE.name,
+  GEMINI_3_5_FLASH.name,
+])
+
 export type GeminiModels = (typeof GEMINI_MODELS)[number]
 
 export type GeminiImageModels = (typeof GEMINI_IMAGE_MODELS)[number]