ai-inference-stepper 1.0.0

package/src/index.ts

@@ -0,0 +1,246 @@
+// packages/stepper/src/index.ts
+
+import { PromptInput, ReportOutput, ProviderResult, StepperCallbacks, StepperConfig, ProviderConfig } from './types.js';
+import { logger } from './logging.js';
+import {
+    buildCacheKey,
+    getReportCache,
+    setDehydrated,
+    isHydratedFresh,
+    isStaleButUsable,
+    deleteCacheEntry,
+} from './cache/redisCache.js';
+import { enqueueReportJob, getJobStatus } from './queue/producer.js';
+import { generateReportNow, registerCallbacks as registerOrchestratorCallbacks, initializeProviders, getProviderHealth } from './stepper/orchestrator.js';
+import { recordCacheHit, recordCacheMiss } from './metrics/metrics.js';
+import crypto from 'crypto';
+import { applyConfigOverrides } from './config.js';
+
+let isInitialized = false;
+
+function ensureInitialized(): void {
+    if (!isInitialized) {
+        const existingProviders = getProviderHealth();
+        if (existingProviders.length > 0) {
+            isInitialized = true;
+            return;
+        }
+        initStepper();
+    }
+}
+
+/**
+ * Initialize Stepper with optional config overrides.
+ * Useful for npm consumers who want programmatic config instead of env.
+ */
+export function initStepper(options?: { config?: Partial<StepperConfig>; providers?: ProviderConfig[] }): StepperConfig {
+    const overrides: Partial<StepperConfig> = options?.config ? { ...options.config } : {};
+    if (options?.providers) {
+        overrides.providers = options.providers;
+    }
+
+    const nextConfig = applyConfigOverrides(overrides);
+    initializeProviders(nextConfig.providers);
+    isInitialized = true;
+    return nextConfig;
+}
+
+/**
+ * Compute template hash for cache key
+ */
+function computeTemplateHash(template?: string): string {
+    const templateStr = template || 'default';
+    return crypto.createHash('sha256').update(templateStr).digest('hex').slice(0, 16);
+}
+
+/**
+ * Register lifecycle callbacks
+ * 
+ * @example
+ * registerCallbacks({
+ *   onSuccess: (jobId, provider, result) => {
+ *     // handle success
+ *   },
+ *   onFallback: (jobId, result, meta) => {
+ *     // handle fallback
+ *   }
+ * });
+ */
+export function registerCallbacks(callbacks: StepperCallbacks): void {
+    registerOrchestratorCallbacks(callbacks);
+    logger.info('Callbacks registered');
+}
+
+/**
+ * Enqueue a report generation job (async, non-blocking)
+ * 
+ * Returns cached result immediately if available (fresh or stale),
+ * or enqueues job and returns 202 status with jobId.
+ * 
+ * @param input - Commit information
+ * @returns Promise with either immediate result or job info
+ * 
+ * @example
+ * const result = await enqueueReport({
+ *   userId: 'user_123',
+ *   commitSha: 'abc123',
+ *   repo: 'myorg/myrepo',
+ *   message: 'Fix bug in auth',
+ *   files: ['src/auth.ts'],
+ *   components: ['auth'],
+ *   diffSummary: '+ fixed token validation'
+ * });
+ * 
+ * if (result.status === 200) {
+ *   // handle cached result
+ * } else {
+ *   // handle enqueued result
+ * }
+ */
+export async function enqueueReport(
+    input: PromptInput
+): Promise<
+    | { status: 200; data: ReportOutput; cached: true; stale?: boolean }
+    | { status: 202; jobId: string; cached: false }
+> {
+    ensureInitialized();
+    const templateHash = computeTemplateHash(input.template);
+    const cacheKey = buildCacheKey(input.userId, input.commitSha, templateHash);
+
+    // Check cache
+    const cached = await getReportCache(cacheKey);
+
+    if (cached && cached.status === 'hydrated' && cached.result) {
+        const fresh = isHydratedFresh(cached);
+
+        if (fresh) {
+            // Fresh cache hit - return immediately and cleanup
+            recordCacheHit('fresh');
+            logger.info({ cacheKey, userId: input.userId }, 'Cache hit (fresh), returning and clearing');
+
+            // We clear immediately because caller is expected to save this
+            deleteCacheEntry(cacheKey).catch(err => {
+                logger.error({ err, cacheKey }, 'Failed to cleanup cache after fresh hit');
+            });
+
+            return { status: 200, data: cached.result, cached: true };
+        }
+
+        // Stale but usable - return and schedule background refresh
+        if (isStaleButUsable(cached)) {
+            recordCacheHit('stale');
+            logger.info({ cacheKey, userId: input.userId }, 'Cache hit (stale), scheduling refresh');
+
+            // Schedule low-priority background refresh
+            enqueueReportJob(input, cacheKey, { priority: 10 }).catch((err) => {
+                logger.error({ err, cacheKey }, 'Failed to enqueue background refresh');
+            });
+
+            return { status: 200, data: cached.result, cached: true, stale: true };
+        }
+    }
+
+    // Cache miss or dehydrated - enqueue job
+    recordCacheMiss();
+    logger.info({ cacheKey, userId: input.userId }, 'Cache miss, enqueueing job');
+
+    const jobId = await enqueueReportJob(input, cacheKey);
+
+    // Create dehydrated placeholder
+    await setDehydrated(cacheKey, jobId);
+
+    return { status: 202, jobId, cached: false };
+}
+
+/**
+ * Generate report synchronously (blocking, immediate)
+ * 
+ * Useful for testing or when you need the result immediately.
+ * This bypasses the queue and calls providers directly.
+ * 
+ * @param input - Commit information
+ * @returns Promise with generated report and metadata
+ * 
+ * @example
+ * const result = await generateReportNow({
+ *   userId: 'user_123',
+ *   commitSha: 'abc123',
+ *   repo: 'myorg/myrepo',
+ *   message: 'Refactor API',
+ *   files: ['src/api.ts'],
+ *   components: ['api'],
+ *   diffSummary: '- old code\n+ new code'
+ * });
+ * 
+ * // handle provider and report result
+ */
+export async function generateReport(input: PromptInput): Promise<ProviderResult> {
+    ensureInitialized();
+    const jobId = `sync_${Date.now()}`;
+    return generateReportNow(input, jobId);
+}
+
+/**
+ * Get job status by ID
+ * 
+ * @param jobId - Job identifier returned from enqueueReport
+ * @returns Job status information or null if not found
+ */
+export async function getJob(jobId: string): Promise<{
+    id: string;
+    state: string;
+    progress?: number;
+    result?: unknown;
+    failedReason?: string;
+    data?: unknown;
+} | null> {
+    return getJobStatus(jobId);
+}
+
+/**
+ * Delete a cached report entry.
+ * 
+ * Call this once you have successfully saved the report to your own database
+ * to keep the Stepper's Redis storage footprint minimal.
+ * 
+ * @param userId - User identifier
+ * @param commitSha - Commit SHA
+ * @param template - Template name (optional)
+ */
+export async function deleteReport(userId: string, commitSha: string, template?: string): Promise<void> {
+    const templateHash = computeTemplateHash(template);
+    const cacheKey = buildCacheKey(userId, commitSha, templateHash);
+    await deleteCacheEntry(cacheKey);
+}
+
+/**
+ * Health check - returns provider status and system health
+ */
+export async function healthcheck(): Promise<{
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    providers: Array<{ name: string; healthy: boolean }>;
+    timestamp: string;
+}> {
+    ensureInitialized();
+    const providerHealth = getProviderHealth();
+    const healthyCount = providerHealth.filter((p) => p.healthy).length;
+
+    let status: 'healthy' | 'degraded' | 'unhealthy';
+    if (healthyCount === 0) {
+        status = 'unhealthy';
+    } else if (healthyCount < providerHealth.length) {
+        status = 'degraded';
+    } else {
+        status = 'healthy';
+    }
+
+    return {
+        status,
+        providers: providerHealth.map((p) => ({ name: p.name, healthy: p.healthy })),
+        timestamp: new Date().toISOString(),
+    };
+}
+
+// Re-export types for consumers
+export * from './types.js';
+export { config } from './config.js';

package/src/logging.ts

@@ -0,0 +1,46 @@
+import pino from 'pino';
+
+const isDev = process.env.NODE_ENV !== 'production';
+
+/**
+ * Base pino logger instance with structured logging
+ */
+export const logger = pino({
+  level: process.env.LOG_LEVEL || (isDev ? 'debug' : 'info'),
+  transport: isDev
+    ? {
+      target: 'pino-pretty',
+      options: {
+        colorize: true,
+        translateTime: 'SYS:standard',
+        ignore: 'pid,hostname',
+      },
+    }
+    : undefined,
+  base: {
+    service: 'stepper',
+    env: process.env.NODE_ENV || 'development',
+  },
+  redact: {
+    paths: [
+      'req.headers.authorization',
+      'req.headers.cookie',
+      'req.body.token',
+      'req.body.password',
+      'req.body.apiKey',
+      'input.token',
+      'config.providers[*].apiKeyEnvVar', // Don't log env var names if they contain secrets (unlikely but safe)
+      'context.input.token',
+      'error.config.headers.Authorization', // Redact axios/fetch error headers
+      'context.tokens',
+    ],
+    remove: true
+  }
+});
+
+/**
+ * Create a child logger with additional context (e.g., jobId, requestId)
+ */
+export function createChildLogger(context: Record<string, unknown>) {
+  return logger.child(context);
+}

package/src/metrics/README.md

@@ -0,0 +1,24 @@
+# 📊 Observability & Metrics
+
+The **Inference Stepper** provides deep insight into its internal operations via **Prometheus** metrics.
+
+## 🎯 Purpose
+
+- **Health Monitoring**: Track provider success rates and latencies.
+- **Capacity Planning**: Monitor job queue sizes and cache hit ratios.
+- **Alerting**: Provide the data source for the Discord alert system.
+
+## 🚀 Key Metrics Tracked
+
+| Metric                        | Type      | Description                                                       |
+| ----------------------------- | --------- | ----------------------------------------------------------------- |
+| `ai_requests_total`           | Counter   | Total requests per provider and status (success/fail).            |
+| `ai_request_duration_seconds` | Histogram | How long each provider takes to respond.                          |
+| `cache_hits_total`            | Counter   | Number of fresh and stale cache hits.                             |
+| `cache_misses_total`          | Counter   | Number of requests that weren't in the cache.                     |
+| `provider_failures_total`     | Counter   | Detailed breakdown of why providers failed (timeout, auth, etc.). |
+| `job_queue_size`              | Gauge     | How many jobs are waiting in the queue.                           |
+
+## 🛠️ Usage
+
+Metrics are exposed at the `/metrics` endpoint if the HTTP server is running. These can be scraped by a Prometheus server and visualized in **Grafana**.

package/src/metrics/metrics.ts

@@ -0,0 +1,84 @@
+
+
+// packages/stepper/src/metrics/metrics.ts
+
+import { Registry, Counter, Histogram, Gauge } from 'prom-client';
+
+// Create registry
+export const register = new Registry();
+
+// Metrics
+export const aiRequestsTotal = new Counter({
+    name: 'ai_requests_total',
+    help: 'Total number of AI provider requests',
+    labelNames: ['provider', 'status'],
+    registers: [register],
+});
+
+export const aiRequestDuration = new Histogram({
+    name: 'ai_request_duration_seconds',
+    help: 'Duration of AI provider requests in seconds',
+    labelNames: ['provider'],
+    buckets: [0.1, 0.5, 1, 2, 5, 10, 30],
+    registers: [register],
+});
+
+export const cacheHitsTotal = new Counter({
+    name: 'cache_hits_total',
+    help: 'Total number of cache hits',
+    labelNames: ['status'],
+    registers: [register],
+});
+export const cacheMissesTotal = new Counter({
+    name: 'cache_misses_total',
+    help: 'Total number of cache misses',
+    registers: [register],
+});
+export const jobQueueSize = new Gauge({
+    name: 'job_queue_size',
+    help: 'Current size of job queue',
+    registers: [register],
+});
+export const providerFailuresTotal = new Counter({
+    name: 'provider_failures_total',
+    help: 'Total number of provider failures',
+    labelNames: ['provider', 'reason'],
+    registers: [register],
+});
+export const jobsProcessedTotal = new Counter({
+    name: 'jobs_processed_total',
+    help: 'Total number of jobs processed',
+    labelNames: ['status'],
+    registers: [register],
+});
+// Helper functions
+export function recordProviderAttempt(provider: string): void {
+    aiRequestsTotal.inc({ provider, status: 'attempted' });
+}
+export function recordProviderSuccess(provider: string, durationMs: number): void {
+    aiRequestsTotal.inc({ provider, status: 'success' });
+    aiRequestDuration.observe({ provider }, durationMs / 1000);
+}
+export function recordProviderFailure(provider: string, reason: string): void {
+    aiRequestsTotal.inc({ provider, status: 'failed' });
+    providerFailuresTotal.inc({ provider, reason });
+}
+export function recordCacheHit(status: 'fresh' | 'stale'): void {
+    cacheHitsTotal.inc({ status });
+}
+export function recordCacheMiss(): void {
+    cacheMissesTotal.inc();
+}
+export function recordJobProcessed(): void {
+    jobsProcessedTotal.inc({ status: 'success' });
+}
+export function recordJobFailed(): void {
+    jobsProcessedTotal.inc({ status: 'failed' });
+}
+/**
+
+Get metrics in Prometheus format
+*/
+export async function getMetrics(): Promise<string> {
+    return register.metrics();
+}

package/src/providers/How the providers interact.md

@@ -0,0 +1,121 @@
+# Chat Conversation
+
+Note: _This is purely the output of the chat conversation and does not contain any raw data, codebase snippets, etc. used to generate the output._
+
+### User Input
+
+lets break down the explanation of  @[packages/stepper/src/providers] one by one and separetely
+ . i want to know what each functions means, how they work, possible results of it, why they work like that and how they help achieve what the inference stepper package is for.
+break down evey detail and explanton for me, to the lowest and clear enough for even a non programmer or technial person
+
+*Listed directory [providers](file:///home/blaze/mine/commitdiary/packages/stepper/src/providers) *
+
+*Viewed [README.md](file:///home/blaze/mine/commitdiary/packages/stepper/src/providers/README.md) *
+
+*Viewed [provider.interface.ts](file:///home/blaze/mine/commitdiary/packages/stepper/src/providers/provider.interface.ts) *
+
+*Viewed [factory.ts](file:///home/blaze/mine/commitdiary/packages/stepper/src/providers/factory.ts) *
+
+*Viewed [promptBuilder.ts](file:///home/blaze/mine/commitdiary/packages/stepper/src/providers/promptBuilder.ts) *
+
+*Viewed [specs.ts](file:///home/blaze/mine/commitdiary/packages/stepper/src/providers/specs.ts) *
+
+### Planner Response
+
+The `packages/stepper/src/providers` directory is the **"Communication Hub"** of the Inference Stepper. 
+
+Its job is simple: **Take the code changes you made, package them into a question (prompt), send them to an AI (like Gemini or OpenAI), and get back a structured report.**
+
+Think of it like a translation office that speaks "Software Code" to "AI Models" and brings back "Human Reports."
+
+Here is a breakdown of each file and its functions, explained simply:
+
+---
+
+### 1. `provider.interface.ts` (The Rule Book)
+This file doesn't "do" things itself; it sets the **Rules** for how any AI provider must behave. It's like a blueprint for a house.
+
+*   **`ProviderError`**: This is a special "Red Flag." If an AI goes wrong, this function helps the system label exactly *why* (e.g., "The AI is too busy" or "The password was wrong").
+*   **`ProviderAdapter` (Interface)**: This is a list of requirements. It says: "If you want to be an AI provider in this system, you **must** have a name and you **must** have a way to be 'called'."
+
+**Why it works like that:** It ensures that no matter which AI we use (Google, OpenAI, etc.), the rest of the system can talk to them in the exact same way.
+
+---
+
+### 2. `factory.ts` (The Concierge)
+This file acts like a hotel concierge that chooses the right AI for you.
+
+*   **`createProviderAdapter`**: 
+    *   **What it means:** "Make me a connector."
+    *   **How it works:** You give it a name (like "gemini"). It looks at your settings, checks if that AI is enabled, and then builds the "connector" object for it.
+    *   **Result:** You get a working "phone line" to that specific AI.
+*   **`createProviderAdapters`**: 
+    *   **What it means:** "Make me a list of connectors."
+    *   **How it works:** It just runs the function above for every AI you have configured.
+
+**How it helps:** It prevents the system from breaking if you misspell an AI name or forget a password. It gracefully says "I can't build that one right now."
+
+---
+
+### 3. `promptBuilder.ts` (The Professional Interviewer)
+This is the most important part for the "Inference Stepper." It writes the script that is sent to the AI.
+
+*   **`buildComprehensivePrompt`**: 
+    *   **What it means:** "Write a very detailed set of instructions."
+    *   **How it works:** It takes your code changes and wraps them in a professional set of rules. It tells the AI: "You are a senior engineer. Look at these files. Tell me the title, summary, and next steps. **Only** give me JSON (a data format)."
+    *   **Result:** A long, clear instruction manual for the AI to follow.
+*   **`redactSecrets`**: 
+    *   **What it means:** "Hide the secrets."
+    *   **How it works:** Before the message is sent, it scans for things like passwords or keys and replaces them with `[REDACTED]`.
+    *   **Why:** So you don't accidentally send your private passwords to the AI companies.
+
+**How it helps:** It ensures the AI gives us a **structured report** instead of just a conversational "Hey, nice code!" It makes the AI useful.
+
+---
+
+### 4. `specs.ts` (The Dictionary)
+Every AI provider (Gemini, OpenAI, Anthropic) has its own "dialect." This file is a dictionary that translates our request into their dialect.
+
+*   **`PROVIDER_SPECS`**: 
+    *   **What it means:** "How each AI likes to be talked to."
+    *   **How it works:** It lists the "Address" (URL) for each AI, what "Language" (Headers) they need, and how they "Package" (Body) their data.
+*   **`getProviderSpec`**: 
+    *   **What it means:** "Look up the rules for one AI."
+
+**Why it works like that:** Instead of writing complex code for every new AI, we just add a few lines of "rules" here. It makes the system very easy to expand.
+
+---
+
+### 5. `unified.adapter.ts` (The Multi-Lingual Robot)
+This is a single piece of machinery that can talk to *any* AI that follows standard rules.
+
+*   **`call`**: 
+    *   **What it means:** "Do the actual work."
+    *   **How it works:** 
+        1. It uses the `promptBuilder` to write the interview questions.
+        2. It uses the `specs.ts` to package the questions correctly.
+        3. It "calls" the AI over the internet.
+        4. It waits for the answer and "unpacks" it.
+    *   **Result:** A clean, finished report about your code.
+
+**How it helps:** It handles the boring technical stuff—like internet timeouts or "waiting in line"—so the rest of the app doesn't have to.
+
+---
+
+### 6. `hfSpace.adapter.ts` (The Specialist)
+Some AI providers (like Hugging Face Spaces) are unique and don't fit the standard "Multi-Lingual Robot" above.
+
+*   **`healthCheck`**: 
+    *   **What it means:** "Are you awake?"
+    *   **How it works:** It pings the Hugging Face AI to see if it's sleeping (they often "go to sleep" to save power). If it is, it waits for it to wake up before sending your code.
+
+**How it helps:** It handles the quirks of specific platforms so you never get a "failed" error just because the AI was taking a nap.
+
+---
+
+### Summary for a Non-Programmer:
+The **Inference Stepper** is like an automated newspaper.
+1. Your code changes are the **News**.
+2. `promptBuilder` is the **Editor** who writes the story outline.
+3. `factory` and `specs` are the **Courier** who knows exactly which office (AI) to take the story to.
+4. `unified.adapter` is the **Delivery Truck** that drives the story there, waits for a response, and brings back the finished **Newspaper (The Report)**.

package/src/providers/README.md

@@ -0,0 +1,121 @@
+# 🔌 AI Providers & Adapters
+
+The **Inference Stepper** supports multiple AI providers through a flexible adapter architecture. This allows the system to switch between providers if one is unavailable or rate-limited.
+
+## 🎯 Purpose
+
+The providers are the "brains" of the system. They:
+
+1.  **Format** code changes (diffs) into prompts the AI understands.
+2.  **Communicate** with external AI services (Hugging Face, Gemini, etc.).
+3.  **Parse** the AI's response into a standardized JSON report.
+4.  **Handle** errors specific to each service.
+
+## 🏗️ Architecture
+
+We use an **Adapter Pattern**. Every provider must implement the `ProviderAdapter` interface:
+
+- `name`: Unique identifier for the provider.
+- `call(input: PromptInput)`: The main method that sends data to the AI and returns a result.
+
+### Implementation Types
+
+1.  **HttpTemplateAdapter**: A universal adapter that can be configured for any HTTP-based AI service.
+2.  **HuggingFaceSpaceAdapter**: Specialized for Hugging Face Spaces with built-in health checks and specific prompt formatting.
+
+## 🛠️ Security
+
+Before sending any code to an AI provider, the system can **redact secrets**. It scans the diffs for passwords, API keys, and other sensitive information to ensure they never leave your infrastructure.
+
+## 📋 Common Errors Handled
+
+| Error                  | Description                                                          |
+| ---------------------- | -------------------------------------------------------------------- |
+| `AuthError`            | Invalid API key or expired credentials.                              |
+| `RateLimitError`       | The provider is busy; we need to wait (respected via `Retry-After`). |
+| `TimeoutError`         | The AI took too long to think (default limit is 1 minute).           |
+| `InvalidResponseError` | The AI returned something that wasn't a valid report.                |
+
+## 🔄 Adding a New Provider
+
+To add a new provider:
+
+1. Create a new adapter class (or use `HttpTemplateAdapter`).
+2. Register it in `config.ts`.
+3. The `Orchestrator` will automatically include it in the fallback rotation.
+
+## 🌟 Provider-Specific Implementations
+
+### Google Gemini (Gemini 3 Models)
+
+**Why Gemini is Different:**
+
+Gemini 3 models (like `gemini-2.5-flash`) have unique requirements that differ from other AI providers. Our implementation follows [Google's official prompting strategies](https://ai.google.dev/gemini-api/docs/prompting-strategies) to maximize performance and reliability.
+
+#### Key Differences:
+
+1. **XML-Structured Prompts**
+   - Gemini 3 responds best to prompts with clear XML-style tags
+   - Tags like `<role>`, `<instructions>`, `<constraints>`, `<context>`, `<task>`, and `<output_format>` help the model understand the request structure
+   - This is different from other providers that use markdown or plain text formatting
+   - Implemented in `buildGeminiPrompt()` function in `promptBuilder.ts`
+
+2. **API Key Authentication**
+   - Gemini requires the API key as a **query parameter** (`?key=YOUR_KEY`), not in headers
+   - Most other providers use `Authorization: Bearer` headers
+   - Conditional logic in `unified.adapter.ts` appends the key to the URL for Gemini only
+
+3. **Temperature Configuration**
+   - **CRITICAL**: Gemini 3 models MUST use `temperature: 1.0`
+   - Google's documentation explicitly warns: "Changing the temperature (setting it below 1.0) may lead to unexpected behavior, such as looping or degraded performance"
+   - Other providers typically use lower temperatures (0.2-0.7) for deterministic outputs
+   - Our specs.ts locks Gemini's temperature at 1.0
+
+4. **Increased Token Limit**
+   - Gemini 3 supports up to 4096 output tokens
+   - We use this higher limit for more detailed commit analysis reports
+   - Other providers typically limit to 2048 tokens
+
+5. **Model Naming**
+   - Gemini uses versioned model names: `gemini-2.5-flash`, `gemini-3-flash-preview`
+   - Different from OpenAI's `gpt-4` or Anthropic's `claude-3` naming schemes
+
+#### Implementation Pattern:
+
+```typescript
+// Conditional rendering based on provider name
+if (this.spec.name === 'gemini') {
+    // Use Gemini-specific XML prompt
+    prompt = buildGeminiPrompt(input);
+    // Append API key to URL
+    actualEndpoint = `${actualEndpoint}?key=${this.apiKey}`;
+} else {
+    // Use standard prompt for other providers
+    prompt = buildComprehensivePrompt(input);
+}
+```
+
+#### Configuration:
+
+```env
+GEMINI_ENABLED=true
+GEMINI_API_KEY=your_key_here
+GEMINI_MODEL=gemini-2.5-flash
+GEMINI_BASE_URL=https://generativelanguage.googleapis.com
+GEMINI_TIMEOUT=60000  # 60 seconds for complex analysis
+```
+
+#### References:
+- [Google Gemini API Prompting Strategies](https://ai.google.dev/gemini-api/docs/prompting-strategies)
+- [Gemini 3 Model Documentation](https://ai.google.dev/gemini-api/docs/models/gemini-v3)
+- [Text Generation Guide](https://ai.google.dev/gemini-api/docs/text-generation)
+
+#### When to Add Provider-Specific Logic:
+
+Consider adding provider-specific implementations when:
+1. The provider's API authentication differs from standard Bearer tokens
+2. The model performs significantly better with specific prompt structures
+3. The provider has unique configuration requirements (like temperature constraints)
+4. Response formats need special parsing logic
+
+This pattern ensures each provider can be optimized for maximum performance while maintaining a clean, maintainable codebase.