[DOCS] Auto-gen doc pages based on codebase

.github/scripts/ai-provider/README.md

@@ -0,0 +1,179 @@
+# AI Provider Service
+
+Simple, configurable AI service for CI workflows supporting multiple providers.
+
+## Features
+
+- **Simple API**: One function to call any AI model
+- **Multiple Providers**: GitHub Models (GPT-4o) and Google Gemini
+- **Auto-detection**: Automatically uses available provider
+- **Rate Limiting**: Built-in request and token-based rate limiting
+- **Configurable**: Override provider and model via environment variables
+
+## Supported Providers
+
+| Provider | Models | Rate Limits | API Key |
+|----------|--------|-------------|---------|
+| **GitHub Models** | gpt-4o, gpt-4o-mini | 10 req/min, 40k tokens/min | `GITHUB_TOKEN` |
+| **Google Gemini** | gemini-1.5-flash, gemini-1.5-pro | 15 req/min, 1M tokens/min | `GOOGLE_AI_API_KEY` |
+
+## Usage
+
+### Basic Usage
+
+```javascript
+const ai = require('./ai-provider');
+
+const response = await ai.call(
+  'You are a helpful assistant',  // system prompt
+  'Explain quantum computing'      // user prompt
+);
+
+console.log(response);
+```
+
+### With Options
+
+```javascript
+const response = await ai.call(
+  systemPrompt,
+  userPrompt,
+  {
+    maxTokens: 1000,
+    onSuccess: (text, tokens) => {
+      console.log(`Success! Used ${tokens} tokens`);
+    },
+    onError: (error) => {
+      console.error('Failed:', error);
+    }
+  }
+);
+```
+
+## Environment Variables
+
+### Provider Selection
+
+```bash
+# Auto-detect (default) - Try other provider with fallback to Github
+AI_PROVIDER=auto
+
+# Use specific provider
+AI_PROVIDER=github    # Use GitHub Models
+AI_PROVIDER=gemini    # Use Google Gemini
+```
+
+### Model Override
+
+```bash
+# Override default model for the provider
+AI_MODEL=gpt-4o              # For GitHub Models
+AI_MODEL=gemini-1.5-pro      # For Gemini
+```
+
+### API Keys
+
+```bash
+# Google Gemini
+GOOGLE_AI_API_KEY=
+```
+
+## Examples
+
+## GitHub Actions Integration
+
+```yaml
+- name: Run AI-powered task
+  env:
+    # Option 1: Auto-detect (recommended)
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    GOOGLE_AI_API_KEY: ${{ secrets.GOOGLE_AI_API_KEY }}
+
+    # Option 2: Force specific provider
+    # AI_PROVIDER: 'gemini'
+    # AI_MODEL: 'gemini-1.5-pro'
+  run: node .github/scripts/your-script.js
+```
+
+## Architecture
+
+```
+ai-provider/
+├── index.js                 # Main service (singleton)
+├── base-provider.js         # Base provider class
+├── provider-factory.js      # Provider creation logic
+├── rate-limiter.js          # Rate limiting logic
+└── providers/
+    ├── github-models.js     # GitHub Models implementation
+    └── gemini.js            # Gemini implementation
+```
+
+## Adding a New Provider
+
+1. Create a new provider class in `providers/`:
+
+```javascript
+const BaseAIProvider = require('../base-provider');
+
+class MyProvider extends BaseAIProvider {
+  constructor(config, apiKey) {
+    super('My Provider', config, apiKey);
+  }
+
+  buildRequestOptions() {
+    // Return HTTP request options
+  }
+
+  buildRequestBody(systemPrompt, userPrompt, maxTokens) {
+    // Return JSON.stringify(...) of request body
+  }
+
+  extractContent(response) {
+    // Return { content: string, tokens: number|null }
+  }
+}
+
+module.exports = MyProvider;
+```
+
+2. Register in `provider-factory.js`:
+
+```javascript
+const MyProvider = require('./providers/my-provider');
+
+function createMyProvider(customModel) {
+  const apiKey = process.env.MY_PROVIDER_API_KEY;
+  if (!apiKey) return null;
+
+  return new MyProvider({ model: customModel || 'default-model' }, apiKey);
+}
+```
+
+3. Add to auto-detection or switch statement.
+
+## Rate Limiting
+
+The service automatically handles rate limiting:
+
+- **Request-based**: Ensures minimum delay between requests
+- **Token-based**: Tracks token consumption in a 60-second rolling window
+- **Smart waiting**: Calculates exact wait time needed
+
+Rate limits are provider-specific and configured automatically.
+
+## Error Handling
+
+```javascript
+try {
+  const response = await ai.call(systemPrompt, userPrompt);
+  // Use response
+} catch (error) {
+  if (error.message.includes('429')) {
+    console.log('Rate limited - try again later');
+  } else if (error.message.includes('401')) {
+    console.log('Invalid API key');
+  } else {
+    console.log('Other error:', error.message);
+  }
+}
+```

.github/scripts/ai-provider/index.js

@@ -0,0 +1,132 @@
+/**
+ * AI Provider Service
+ * Simple, configurable AI service supporting multiple providers
+ * 
+ * Usage:
+ *   const ai = require('./ai-provider');
+ *   const response = await ai.call(systemPrompt, userPrompt);
+ * 
+ * Environment Variables:
+ *   AI_PROVIDER - 'github' | 'gemini' | 'auto' (default: auto)
+ *   AI_MODEL - Override default model
+ *   GITHUB_TOKEN - For GitHub Models
+ *   GOOGLE_AI_API_KEY - For Gemini
+ */
+
+const { getProvider } = require('./provider-factory');
+const RateLimiter = require('./rate-limiter');
+
+class AIProvider {
+  constructor() {
+    this.provider = null;
+    this.rateLimiter = new RateLimiter();
+    this.initialized = false;
+  }
+
+  /**
+   * Initialize the provider (lazy loading)
+   */
+  _init() {
+    if (this.initialized) {
+      return;
+    }
+
+    this.provider = getProvider();
+    if (!this.provider) {
+      throw new Error(
+        'No AI provider available. Set AI_PROVIDER or corresponding API key.'
+      );
+    }
+
+    this.rateLimiter.setProvider(this.provider);
+    this.initialized = true;
+  }
+
+  /**
+   * Make an AI call
+   * 
+   * @param {string} systemPrompt - System prompt
+   * @param {string} userPrompt - User prompt
+   * @param {object} options - Optional settings
+   * @param {number} options.maxTokens - Override max tokens
+   * @param {function} options.onSuccess - Success callback
+   * @param {function} options.onError - Error callback
+   * @returns {Promise<string>} Response text
+   */
+  async call(systemPrompt, userPrompt, options = {}) {
+    this._init();
+
+    const {
+      maxTokens = null,
+      onSuccess = null,
+      onError = null,
+    } = options;
+
+    if (!systemPrompt || !userPrompt) {
+      throw new Error('systemPrompt and userPrompt are required');
+    }
+
+    try {
+      // Estimate tokens and wait for rate limits
+      const tokensToUse = maxTokens || this.provider.getMaxTokens();
+      const estimatedTokens = this.rateLimiter.estimateTokenUsage(
+        systemPrompt,
+        userPrompt,
+        tokensToUse
+      );
+
+      await this.rateLimiter.waitForRateLimit(estimatedTokens);
+
+      // Build and send request
+      const requestBody = this.provider.buildRequestBody(systemPrompt, userPrompt, tokensToUse);
+      const requestOptions = this.provider.buildRequestOptions();
+
+      const response = await this._makeRequest(requestOptions, requestBody);
+
+      // Extract content
+      const extracted = this.provider.extractContent(response);
+      if (!extracted) {
+        throw new Error('Invalid response format from API');
+      }
+
+      // Record actual token usage
+      const actualTokens = extracted.tokens || estimatedTokens;
+      this.rateLimiter.recordTokenConsumption(actualTokens);
+
+      if (onSuccess) {
+        onSuccess(extracted.content, actualTokens);
+      }
+
+      return extracted.content;
+
+    } catch (error) {
+      if (onError) {
+        onError(error);
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Make HTTPS request
+   */
+  async _makeRequest(options, body) {
+    const { makeHttpsRequest } = require('../workflow-utils');
+    return await makeHttpsRequest(options, body);
+  }
+
+  /**
+   * Get provider info
+   */
+  getProviderInfo() {
+    this._init();
+    return {
+      name: this.provider.name,
+      limits: this.provider.getRateLimits(),
+      maxTokens: this.provider.getMaxTokens(),
+    };
+  }
+}
+
+module.exports = new AIProvider();

.github/scripts/ai-provider/provider-factory.js

@@ -0,0 +1,65 @@
+/**
+ * Provider Factory
+ * Creates the appropriate AI provider based on environment variables
+ */
+
+const { createGitHubProvider } = require('./providers/github-models');
+const { createGeminiProvider } = require('./providers/gemini');
+
+/**
+ * Get the active AI provider based on environment configuration
+ * 
+ * Environment variables:
+ * - AI_PROVIDER: 'github' | 'gemini' | 'auto' (default: 'auto')
+ * - AI_MODEL: Override default model for the provider
+ * - GITHUB_TOKEN: API key for GitHub Models
+ * - GOOGLE_AI_API_KEY: API key for Gemini
+ * 
+ * @returns {BaseAIProvider|null} Provider instance or null if none available
+ */
+function getProvider() {
+  const providerName = (process.env.AI_PROVIDER || 'auto').toLowerCase();
+  const customModel = process.env.AI_MODEL;
+
+  if (providerName === 'auto') {
+    return autoDetectProvider(customModel);
+  }
+
+  switch (providerName) {
+    case 'github':
+    case 'github-models':
+      return createGitHubProvider(customModel);
+
+    case 'gemini':
+    case 'google':
+      return createGeminiProvider(customModel);
+
+    default:
+      console.warn(`⚠️  Unknown provider: ${providerName}. Falling back to auto-detect.`);
+      return autoDetectProvider(customModel);
+  }
+}
+
+/**
+ * Auto-detect provider based on available API keys
+ */
+function autoDetectProvider(customModel) {
+  // Try Gemini
+  const geminiProvider = createGeminiProvider(customModel);
+  if (geminiProvider) {
+    return geminiProvider;
+  }
+
+  // Fallback to GitHub Models (free in GitHub Actions)
+  const githubProvider = createGitHubProvider(customModel);
+  if (githubProvider) {
+    return githubProvider;
+  }
+
+  return null;
+}
+
+module.exports = {
+  getProvider,
+};
+