feat(providers): route openai and gemini protocols to sdk providers

[mingmxren]

📝 Description

This PR restructures provider routing to use official SDKs where protocol-specific behavior is required, while keeping the external Provider.Chat contract stable.

Main changes:

• Route openai/* (API-key path) to a new openai_sdk provider based on github.com/openai/openai-go/v3.
• Route gemini/* and google/* to a new gemini_sdk provider based on google.golang.org/genai.
• Keep antigravity/* unchanged.
• Keep other OpenAI-compatible vendors on the existing openai_compat HTTP adapter.
• Remove Gemini-specific host/prefix branching from openai_compat request shaping, reducing API base coupling.
• Preserve tool-call mapping compatibility, including Gemini thought-signature persistence/restore behavior across message/session flows.

Also included:

• Factory routing updates and regression tests.
• New provider-level tests for request/response mapping, tool calls, options, timeout, proxy, and error paths.
• Design/implementation plan docs for the SDK routing work.

🗣️ Type of Change

• 🐞 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 📖 Documentation update
• ⚡ Code refactoring (no functional changes, no api changes)

🤖 AI Code Generation

• 🤖 Fully AI-generated (100% AI, 0% Human)
• 🛠️ Mostly AI-generated (AI draft, Human verified/modified)
• 👨‍💻 Mostly Human-written (Human lead, AI assisted or none)

🔗 Related Issue

N/A

📚 Technical Context (Skip for Docs)

• Reference URL:
  • https://github.com/openai/openai-go
  • https://pkg.go.dev/google.golang.org/genai
• Reasoning:
  • Host-based feature detection in openai_compat was brittle behind API proxies/gateways.
  • Protocol-based routing to official SDKs is more robust and extensible.
  • This hybrid approach minimizes risk: migrate OpenAI and Gemini transport layers first, keep other compatible providers and antigravity behavior stable.

🧪 Test Environment

• Hardware: mac mini
• OS: Macos
• Model/Provider: gpt-5.2, gemini-3-flash-preview, gemini-3-pro-preview
• Channels: telegram

📸 Evidence (Optional)

Click to view Logs/Screenshots

☑️ Checklist

• My code/docs follow the style of this project.
• I have performed a self-review of my own changes.
• I have updated the documentation accordingly.

[nikolasdehor]

Review: feat(providers): route openai and gemini protocols to sdk providers

Large PR (2385+/28-) with well-documented design docs. I focused my review on the factory routing, provider implementations, and critical paths.

Architecture

1. Clean separation -- The hybrid approach (SDK for OpenAI/Gemini, keep openai_compat for other compatible providers, keep antigravity untouched) is the right strategy. It minimizes blast radius while improving protocol correctness.

2. Design docs are thorough -- The three plan documents cover design rationale, implementation steps, and compatibility considerations well. Good to see explicit thought-signature compatibility analysis for Gemini.

Factory Routing (reviewed)

3. Factory changes look correct -- The case "openai" routing to openai_sdk.NewProvider for API-key path, and case "gemini", "google" routing to gemini_sdk.NewProvider, match the design. Factory tests confirm the routing.

4. Question: what happens with openai protocol behind a proxy/gateway? Some users run OpenAI-compatible endpoints (like LiteLLM, vLLM) with protocol: "openai". With this change, those would be routed to the SDK provider instead of openai_compat. Is that intentional? The SDK provider may not handle all the dialect variations that openai_compat supports. If this is an issue, consider adding a config flag like force_compat: true or routing based on whether apiBase differs from api.openai.com.

OpenAI SDK Provider

5. Message mapping -- The role mapping (system/user/assistant/tool) and tool-call parsing look correct from what I can see.

6. maxTokensField handling -- Good that you support both max_tokens and max_completion_tokens to handle API version differences.

Gemini SDK Provider

7. Thought-signature dual-write -- Writing to both ExtraContent.Google.ThoughtSignature and Function.ThoughtSignature for backward compatibility is the right approach. The read-path priority (extra_content first, then function fallback) ensures old sessions remain usable.

8. Session serialization compatibility -- The compatibility strategy (new writes both fields, old readers use function field) is sound.

Concerns

9. Test coverage -- 306 lines of OpenAI SDK tests and 404 lines of Gemini SDK tests is good for a new provider. However, I would want to see integration-level tests that verify the full factory -> provider -> response path with mock servers.

10. Dependency footprint -- Adding both openai-go/v3 and google.golang.org/genai increases the dependency tree significantly (13 new go.mod entries, 71 new go.sum entries). This is the cost of using official SDKs, but worth noting for binary size and supply chain considerations.

11. openai_compat cleanup -- The PR description says it removes "Gemini-specific host/prefix branching from openai_compat", but the diff shows only 18 deletions in openai_compat/provider.go. Make sure the thought-signature response parsing in openai_compat is preserved for non-Gemini OpenAI-compatible gateways that might relay Gemini responses.

Minor

12. The PR is marked as both "Fully AI-generated (100%)" and "Mostly AI-generated (AI draft, Human verified)". These are mutually exclusive -- please clarify.

Overall a solid architectural refactor. The main risk is point #4 (proxy/gateway users with protocol: "openai" getting unexpected behavior changes).

[mingmxren]

@yinwm Would you like to have a review on this PR. It is an optimization mentioned in this comment which generally won't affect existing functionality.

#790 (comment)