feat(gemini): support combined json_schema + grounding via Interactions API for Gemini 3+ (Fixes #3426)

[hpiclaranet]

Summary

Fixes #3426. Gemini 3+ models natively support combining Structured Output (json_schema) with built-in tools (grounding, url_context, code_execution), but only via the Interactions API (client.interactions.create()). The legacy generateContent endpoint silently drops grounding when both are active (HTTP 200, empty groundingMetadata) — see google-gemini/cookbook#1274.

The existing PR #3429 only relaxes the validator but does not implement the Interactions API routing — merging it as-is would replace the explicit InvokeError with a silent correctness bug. This PR provides the complete end-to-end implementation.

Changes

_is_gemini3_plus(model) — new static method. Robust to models/ path prefixes and other provider path segments, case-insensitive, rejects non-Gemini-3 names (e.g. gemini-30, gemini-3abc, claude-3-sonnet).

_validate_feature_compatibility — gains model: Optional[str] parameter. Rule 1 (json_schema exclusivity) is relaxed for Gemini 3+ with native tools and no custom tools. Other rules (Rule 3: url_context + code_execution, Rule 5: custom tools auto-disable) remain strict on all models.

_generate() routing — dispatched to _generate_via_interactions() when all conditions hold: gemini-3+ AND json_schema AND native tools AND no custom tools. All other paths use the existing generateContent endpoint unchanged.

_generate_via_interactions() — constructs and calls genai_client.interactions.create() with:

• Input converted from types.Content to Interactions API Step format
• system_instruction as a top-level string
• Tools as Interaction dict format ([{"type": "google_search"}])
• response_format as a single dict (not a list — prevents the "responseFormat must be set when responseMimeType is set" error)
• generation_config using only the subset supported by this endpoint
• store=False (Dify manages conversation history server-side)
• Support for both inline_data (base64-embedded) and file_data (Files API URI) multimodal content

_handle_interactions_response() — extracts output text and token usage from the completed Interaction into LLMResult.

_handle_interactions_stream_response() — iterates Stream[InteractionSSEEvent], handles step.delta (text chunks), interaction.completed (final usage), and error events. Wrapped in a try/except to surface SDK exceptions as Dify InvokeError.

Design decisions

• store=False: Dify is the conversation orchestrator and stores its own history. Passing store=True or using previous_interaction_id would duplicate state on Google servers, create desynchronization risks when Dify edits messages, and potentially violate data-sovereignty requirements. Stateless is the correct integration model for Dify.

• Client caching: _generate_via_interactions currently constructs its own genai.Client(...). The separate PR [gemini] Performance: client cache, FileCache, token fallback, splitter local counting (Fixes #3333) #3509 adds a module-level cached client helper. The two PRs are independent and can merge in any order — once both land, _generate_via_interactions will be updated to use the cache in a follow-up.

• Backward compatibility: Gemini 2.5, 2.0, and 1.5 models continue to use the strict validator + generateContent path unchanged.

Testing

• 28 new unit tests covering _is_gemini3_plus (15 cases), validator relaxation (8 cases), and response/stream handlers (5 cases)
• ruff check — All checks passed
• ruff format — clean
• python3 -m py_compile — pass
• pytest models/tests/ (excluding live) — 207/207 passed

Version

manifest.yaml: 0.9.3 → 0.9.4

References

• Issue [gemini] Structured output (json_schema) cannot be combined with grounding/url_context — needs Interactions API migration for Gemini 3+ #3426: Structured output cannot be combined with grounding/url_context
• PR fix(gemini): allow json_schema + grounding on Gemini 3+ models #3429 (incomplete: validator only, no Interactions API routing)
• PR [gemini] Performance: client cache, FileCache, token fallback, splitter local counting (Fixes #3333) #3509 (independent: performance client caching, no Interactions API changes)
• cookbook#1274: HTTP 200 but empty groundingMetadata on generateContent endpoint with json_schema + google_search