ACCEPTEDRoadmap: V2.02026-09-06 — updated 2026-09-06
ADR-003: Google Gemini API native integration for Ask Alan RAG
Adopt Google Gemini 2.5 Flash via the official @google/genai SDK for Ask Alan RAG generation, replacing proprietary proxies.
Launch stateThese entries are placeholders while the real case studies and experiment write-ups are prepared for publication.
Context
- Ask Alan was coupled to an external AI gateway and proprietary proxy credentials.
- The system required a cost-effective, low-latency, and reliable multimodal LLM with strong context window capabilities to ground responses in the public engineering brain.
- Google Gemini 2.5 Flash offers high throughput, generous free tier quotas, and first-class TypeScript SDK support.
Decision
- Integrate Google GenAI SDK (@google/genai) natively in server-side functions (ask.server.ts).
- Standardize on gemini-2.5-flash as the primary generation model for operational and architectural questions.
- Feed full graph context, ADR citations, and conversation history directly via systemInstruction and structured contents.
Alternatives considered
- Maintain third-party proxy gateways. Rejected due to vendor lock-in, latency overhead, and lack of direct SDK control.
- Run self-hosted local models (e.g. Ollama/vLLM). Rejected due to container resource constraints in Cloud Run environments.
Consequences
- Direct API communication with minimal hops and standard GEMINI_API_KEY credential management.
- Lower latency on conversational RAG queries.
- Requires explicit handling of rate limits (HTTP 429) with user-friendly retry hints.
Roadmap & Marcos de Implementação
V2.0Native AI Engine Migration
Progresso da Execução Arquitetural100% CONCLUÍDO
- Zero-Intermediary Architecture(Phase 1: Gateway Proxy Decoupling)Concluído
Purged vendor-locked API gateways, proprietary headers, and proxy latency hops in favor of direct Google infrastructure.
- Google GenAI SDK Integration(Phase 2: Official SDK Implementation)Concluído
Standardized on @google/genai in server functions (ask.server.ts) with gemini-2.5-flash as the primary generation model.
- Multimodal Structured Grounding(Phase 3: Context Window Optimization)Concluído
Configured direct systemInstruction prompt pipelines with conversation thread memory and candidate citation arrays.
- HTTP 429 Graceful Recovery(Phase 4: Resilience & Rate Limit Handling)Concluído
Added friendly backoff notifications, hourly client quotas, and structured fallback messaging.