ai-inference-stepper 1.0.0

package/src/cache/README.md

@@ -0,0 +1,51 @@
+# 🧠 Cache System
+
+The **Inference Stepper** package is designed to generate AI-powered "commit diary" reports. Since generating these reports using AI services (like Gemini, Cohere, etc.) takes time and costs money, this module implements a **Redis-backed caching system**.
+
+## 🎯 Purpose
+
+1. **Remember** reports that were already generated
+2. **Return them instantly** when requested again
+3. **Track the progress** of reports being generated
+4. **Handle failures** gracefully
+
+## 🔑 Key Concepts
+
+### Dehydrated vs. Hydrated
+
+- **Dehydrated entry**: A placeholder in the cache saying "We're working on this report, come back later!". It contains a `jobId` to track progress.
+- **Hydrated entry**: A completed report ready to be served. It contains the actual AI-generated content and metadata about which providers were tried.
+
+### Stale-While-Revalidate
+
+This system implements the **Stale-While-Revalidate** pattern:
+
+1. Serve old (stale) data immediately to the user.
+2. Trigger a background refresh to generate fresh data.
+3. The next request gets the updated, fresh data.
+
+## 📋 Functions
+
+| Function             | Purpose                                                                       |
+| -------------------- | ----------------------------------------------------------------------------- |
+| `getRedisClient()`   | Manages the connection to the Redis database.                                 |
+| `buildCacheKey()`    | Creates unique identifiers like `stepper:report:user123:shaabc`.              |
+| `getReportCache()`   | Retrieves a cached report if it exists.                                       |
+| `setDehydrated()`    | Marks a report as "in progress".                                              |
+| `setHydrated()`      | Stores a completed AI report.                                                 |
+| `markFailed()`       | Records logic failures so we don't keep retrying broken requests immediately. |
+| `isHydratedFresh()`  | Checks if a report is young enough to serve without refresh.                  |
+| `isStaleButUsable()` | Checks if we can serve an old report while refreshing.                        |
+
+## 🎯 Flow
+
+```mermaid
+graph TD
+    A[Request In] --> B{Check Cache}
+    B -- Hit (Fresh) --> C[Serve Immediately]
+    B -- Hit (Stale) --> D[Serve + Refresh Background]
+    B -- Miss --> E[Enqueue Job + Mark Dehydrated]
+    E --> F[AI Generation]
+    F -- Success --> G[Mark Hydrated]
+    F -- Failure --> H[Mark Failed]
+```

package/src/cache/redisCache.ts

@@ -0,0 +1,194 @@
+// packages/stepper/src/cache/redisCache.ts
+
+import Redis from 'ioredis';
+import { CacheEntry, ReportOutput, ProviderAttemptMeta } from '../types.js';
+import { config } from '../config.js';
+import { logger } from '../logging.js';
+import { sendDiscordAlert } from '../alerts/discord.js';
+
+let redisClient: Redis | null = null;
+
+/**
+ * Get or create Redis client
+ */
+export function getRedisClient(): Redis {
+    if (!redisClient) {
+        redisClient = new Redis(config.redis.url, {
+            maxRetriesPerRequest: null, // Required by BullMQ for blocking operations
+            enableReadyCheck: true,
+            lazyConnect: false,
+        });
+
+        redisClient.on('error', (err) => {
+            logger.error({ err }, 'Redis client error');
+            void sendDiscordAlert({
+                title: 'Redis Connection Error',
+                message: `Redis client encountered an error: ${err.message}`,
+                severity: 'critical',
+                metadata: { error: err.message, timestamp: new Date().toISOString() }
+            });
+        });
+
+        redisClient.on('connect', () => {
+            logger.info('Redis client connected');
+        });
+    }
+
+    return redisClient;
+}
+
+/**
+ * Build cache key for a report
+ */
+export function buildCacheKey(userId: string, commitSha: string, templateHash: string = 'default'): string {
+    return `${config.redis.keyPrefix}report:${userId}:${commitSha}:${templateHash}`;
+}
+
+/**
+ * Get cache entry: Looks up a report in the cache using its key. Like asking: "Do we already have a copy of this report?"
+ */
+export async function getReportCache(key: string): Promise<CacheEntry | null> {
+    const redis = getRedisClient();
+
+    try {
+        const data = await redis.get(key);
+        if (!data) return null;
+
+        const entry: CacheEntry = JSON.parse(data);
+        return entry;
+    } catch (error) {
+        logger.error({ error, key }, 'Failed to get cache entry');
+        return null;
+    }
+}
+
+/**
+ * Set dehydrated cache entry (job enqueued)
+ */
+export async function setDehydrated(key: string, jobId: string): Promise<void> {
+    const redis = getRedisClient();
+
+    const entry: CacheEntry = {
+        status: 'dehydrated', //Mark it as "in progress"
+        jobId,
+        timestamps: {
+            created: new Date().toISOString(),
+            updated: new Date().toISOString(),
+        },
+    };
+
+    try {
+        await redis.setex(key, config.cache.ttlSeconds, JSON.stringify(entry)); //Store in Redis with expiration time Default is 604,800 seconds = 7 days
+        logger.debug({ key, jobId }, 'Created dehydrated cache entry');
+    } catch (error) {
+        logger.error({ error, key }, 'Failed to set dehydrated cache');
+        throw error;
+    }
+}
+
+/**
+ * Set hydrated cache entry (report generated)
+ * Stores a completed report in the cache. This is the "meal is ready!" moment.
+ */
+export async function setHydrated(
+    key: string,
+    result: ReportOutput,
+    providersAttempted: ProviderAttemptMeta[],
+    fallback: boolean = false,
+    ttl?: number // How long to keep it	604800 (7 days in seconds)
+): Promise<void> {
+    const redis = getRedisClient();
+
+    const entry: CacheEntry = {
+        status: 'hydrated', // Report is complete
+        result,
+        providersAttempted,
+        fallback,
+        timestamps: {
+            created: new Date().toISOString(),
+            updated: new Date().toISOString(),
+        },
+        ttl: ttl || config.cache.ttlSeconds,
+    };
+
+    try {
+        await redis.setex(key, ttl || config.cache.ttlSeconds, JSON.stringify(entry));
+        logger.debug({ key, fallback }, 'Stored hydrated cache entry');
+    } catch (error) {
+        logger.error({ error, key }, 'Failed to set hydrated cache');
+        throw error;
+    }
+}
+
+/**
+ * Mark cache entry as failed: Records that report generation failed completely. All AI providers were tried and none worked.
+ */
+export async function markFailed(key: string, errorMessage: string, providersAttempted: ProviderAttemptMeta[]): Promise<void> {
+    const redis = getRedisClient();
+
+    const entry: CacheEntry = {
+        status: 'failed',
+        error: errorMessage,
+        providersAttempted,
+        timestamps: {
+            created: new Date().toISOString(),
+            updated: new Date().toISOString(),
+        },
+    };
+
+    try {
+        await redis.setex(key, 3600, JSON.stringify(entry)); // Keep failed for 1 hour
+        logger.debug({ key }, 'Marked cache entry as failed');
+    } catch (error) {
+        logger.error({ error, key }, 'Failed to mark cache as failed');
+    }
+}
+
+/**
+ * Check if hydrated entry is fresh
+ */
+export function isHydratedFresh(entry: CacheEntry): boolean {
+    if (entry.status !== 'hydrated') return false; //Is this a complete report?
+
+    const updatedAt = new Date(entry.timestamps.updated).getTime();
+    const now = Date.now();
+    const ageSeconds = (now - updatedAt) / 1000; //How old is this report?
+
+    return ageSeconds < config.cache.staleThresholdSeconds;  //Is it younger than 24 hours?
+}
+
+/**
+ * Check if entry is stale but usable for stale-while-revalidate: Checks if a report is old but still usable while a new one is being generated in the background.
+ */
+export function isStaleButUsable(entry: CacheEntry): boolean {
+    if (entry.status !== 'hydrated') return false;
+    if (!config.cache.enableStaleWhileRevalidate) return false;
+
+    return !isHydratedFresh(entry);
+}
+
+/**
+ * Delete cache entry: Removes the record from Redis immediately.
+ * Call this once the backend has successfully saved the report to its database.
+ */
+export async function deleteCacheEntry(key: string): Promise<void> {
+    const redis = getRedisClient();
+
+    try {
+        await redis.del(key);
+        logger.debug({ key }, 'Deleted cache entry after successful delivery');
+    } catch (error) {
+        logger.error({ error, key }, 'Failed to delete cache entry');
+    }
+}
+
+/**
+ * Close Redis connection (for graceful shutdown)
+ */
+export async function closeRedis(): Promise<void> {
+    if (redisClient) {
+        await redisClient.quit();
+        redisClient = null;
+        logger.info('Redis client disconnected');
+    }
+}

package/src/ci/deploy.sh

@@ -0,0 +1,36 @@
+
+
+### `packages/stepper/src/ci/deploy.sh
+
+#!/bin/bash
+set -e
+
+echo "🚀 Deploying Stepper Service"
+
+# Build Docker image
+echo "📦 Building Docker image..."
+docker build -t commitdiary-stepper:latest .
+
+# Tag for registry (example)
+# docker tag commitdiary-stepper:latest registry.example.com/commitdiary-stepper:latest
+
+# Push to registry (example)
+# docker push registry.example.com/commitdiary-stepper:latest
+
+echo "✅ Build complete"
+
+# Example deployment commands (adjust for your platform)
+# For Railway:
+# railway up
+
+# For Render:
+# render deploy
+
+# For Kubernetes:
+# kubectl apply -f k8s/deployment.yml
+
+echo "📋 Next steps:"
+echo "1. Push image to your container registry"
+echo "2. Update deployment configuration with new image"
+echo "3. Apply deployment to your cluster/platform"
+echo "4. Verify with: curl https://your-domain.com/health"

package/src/cli.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { startServer } from './server/start.js';
+import { logger } from './logging.js';
+
+startServer().catch((error) => {
+  logger.error({ error }, 'Failed to start Stepper server');
+  process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,265 @@
+import { StepperConfig, ProviderConfig } from './types.js';
+
+/**
+ * Load configuration from environment variables with sensible defaults.
+ * This is the central brain for all timing, retry, and safety-switch logic.
+ */
+
+/**
+ * Load provider configurations from environment
+ */
+function loadProviderConfigs(): ProviderConfig[] {
+  const providers: ProviderConfig[] = [];
+
+  // Helper to add provider config
+  const addProvider = (name: string, envPrefix: string) => {
+    const enabled = process.env[`${envPrefix}_ENABLED`] === 'true';
+    if (enabled) {
+      providers.push({
+        name,
+        apiKey: process.env[`${envPrefix}_API_KEY`],
+        baseUrl: process.env[`${envPrefix}_BASE_URL`],
+        modelName: process.env[`${envPrefix}_MODEL`],
+        timeout: parseInt(process.env[`${envPrefix}_TIMEOUT`] || '15000', 10),
+        rateLimitRPS: parseInt(process.env[`${envPrefix}_RPS`] || '5', 10),
+        concurrency: parseInt(process.env[`${envPrefix}_CONCURRENCY`] || '2', 10),
+        enabled: true,
+      });
+    }
+  };
+
+  // Special case: HuggingFace Space
+  if (process.env.HF_SPACE_ENABLED === 'true') {
+    providers.push({
+      name: 'hf-space',
+      baseUrl: process.env.HF_SPACE_URL,
+      apiKey: process.env.HF_SPACE_API_KEY,
+      timeout: parseInt(process.env.HF_SPACE_TIMEOUT || '30000', 10),
+      rateLimitRPS: parseInt(process.env.HF_SPACE_RPS || '3', 10),
+      concurrency: parseInt(process.env.HF_SPACE_CONCURRENCY || '1', 10),
+      enabled: true,
+    });
+  }
+
+  // Add all other providers
+  addProvider('gemini', 'GEMINI');
+  addProvider('openai', 'OPENAI');
+  addProvider('anthropic', 'ANTHROPIC');
+  addProvider('cohere', 'COHERE');
+  addProvider('deepseek', 'DEEPSEEK');
+  addProvider('groq', 'GROQ');
+  addProvider('openrouter', 'OPENROUTER');
+  addProvider('mistral', 'MISTRAL');
+  addProvider('perplexity', 'PERPLEXITY');
+  addProvider('together', 'TOGETHER');
+
+  return providers;
+}
+export function loadConfig(): StepperConfig {
+  const redisUrl = process.env.REDIS_URL || 'redis://localhost:6379';
+
+  // Provider configurations: Rules for how we talk to each AI
+  const providers: ProviderConfig[] = [
+    {
+      name: 'hf-space',
+      enabled: process.env.HF_SPACE_ENABLED === 'true',
+      baseUrl: process.env.HF_SPACE_URL || 'https://your-space.hf.space',
+      apiKeyEnvVar: 'HF_SPACE_API_KEY',
+      // RPM (Requests Per Minute): We allow 5 requests every 60 seconds (one every 12 seconds)
+      // high RPM leads to "429 Too Many Requests" errors.
+      rateLimitRPM: parseInt(process.env.HF_SPACE_RPM || '5', 10),
+      // Concurrency: Max 2 active conversations at once. Prevents overloading the AI slot.
+      concurrency: parseInt(process.env.HF_SPACE_CONCURRENCY || '2', 10),
+      // Timeout: Give the AI 1 minute to think before we give up and try another provider.
+      timeout: parseInt(process.env.HF_SPACE_TIMEOUT || '60000', 10),
+    },
+    {
+      name: 'gemini',
+      enabled: process.env.GEMINI_ENABLED === 'true',
+      baseUrl: process.env.GEMINI_BASE_URL || 'https://generativelanguage.googleapis.com/v1',
+      modelName: process.env.GEMINI_MODEL || 'gemini-pro',
+      apiKeyEnvVar: 'GEMINI_API_KEY',
+      rateLimitRPM: parseInt(process.env.GEMINI_RPM || '5', 10),
+      concurrency: parseInt(process.env.GEMINI_CONCURRENCY || '2', 10),
+      timeout: parseInt(process.env.GEMINI_TIMEOUT || '60000', 10),
+    },
+    {
+      name: 'cohere',
+      enabled: process.env.COHERE_ENABLED === 'true',
+      baseUrl: process.env.COHERE_BASE_URL || 'https://api.cohere.ai/v1',
+      modelName: process.env.COHERE_MODEL || 'command',
+      apiKeyEnvVar: 'COHERE_API_KEY',
+      rateLimitRPM: parseInt(process.env.COHERE_RPM || '5', 10),
+      concurrency: parseInt(process.env.COHERE_CONCURRENCY || '2', 10),
+      timeout: parseInt(process.env.COHERE_TIMEOUT || '60000', 10),
+    },
+  ];
+
+  // Filter enabled providers and enforce order
+  const staticProviders = providers.filter((p) => p.enabled);
+  const dynamicProviders = loadProviderConfigs();
+
+  // Combine, preferring static if name conflicts
+  const allProviders = [...staticProviders];
+  for (const dp of dynamicProviders) {
+    if (!allProviders.some(sp => sp.name === dp.name)) {
+      allProviders.push(dp);
+    }
+  }
+
+  return {
+    providers: allProviders,
+    fallback: {
+      enabled: process.env.FALLBACK_ENABLED !== 'false',
+    },
+    redis: {
+      url: redisUrl,
+      keyPrefix: process.env.REDIS_KEY_PREFIX || 'stepper:',
+    },
+    cache: {
+      // TTL: How long the report stays in the database (Default: 2 days)
+      ttlSeconds: parseInt(process.env.CACHE_TTL_SECONDS || '172800', 10),
+      // Stale Threshold: After 24 hours (or effectively never if TTL < 24h), we consider the data "old"
+      staleThresholdSeconds: parseInt(process.env.CACHE_STALE_THRESHOLD || '86400', 10),
+      enableStaleWhileRevalidate: process.env.CACHE_STALE_WHILE_REVALIDATE !== 'false',
+    },
+    queue: {
+      name: process.env.QUEUE_NAME || 'report-generation',
+      // How many total background jobs we run across all providers
+      concurrency: parseInt(process.env.QUEUE_CONCURRENCY || '5', 10),
+    },
+    webhook: {
+      enabled: process.env.WEBHOOK_ENABLED !== 'false', // Enabled by default
+      secret: process.env.WEBHOOK_SECRET || '',
+      maxRetries: parseInt(process.env.WEBHOOK_MAX_RETRIES || '3', 10),
+      retryDelayMs: parseInt(process.env.WEBHOOK_RETRY_DELAY_MS || '5000', 10),
+    },
+    retry: {
+      // Max Attempts: Try a single provider 3 times before moving to the next one.
+      maxAttemptsPerProvider: parseInt(process.env.RETRY_MAX_ATTEMPTS || '3', 10),
+      // Base Delay: After a simple error (like network), wait 40 seconds before retrying.
+      baseDelayMs: parseInt(process.env.RETRY_BASE_DELAY_MS || '40000', 10),
+      // Jitter: Random +/- 10 seconds to prevent multiple retries hitting at once.
+      maxJitterMs: parseInt(process.env.RETRY_MAX_JITTER_MS || '10000', 10),
+      // Rate Limit Fallback: If AI says "Busy" but doesn't say for how long, wait ~2 hours (extreme safety).
+      // Note: User set this to 5400 in .env which is ~90mins.
+      rateLimitFallbackSeconds: parseInt(process.env.RETRY_RATE_LIMIT_FALLBACK || '7200', 10),
+    },
+    circuit: {
+      // Failure Threshold: Kill the provider if 5 requests in a row fail.
+      failureThreshold: parseInt(process.env.CIRCUIT_FAILURE_THRESHOLD || '5', 10),
+      // Window: Only look at failures from the last 5 minutes.
+      windowSeconds: parseInt(process.env.CIRCUIT_WINDOW_SECONDS || '300', 10),
+      // Cooldown: After killing a provider, wait 5 minutes before trying it again.
+      cooldownSeconds: parseInt(process.env.CIRCUIT_COOLDOWN_SECONDS || '300', 10),
+    },
+    security: {
+      redactBeforeSend: process.env.REDACT_BEFORE_SEND !== 'false',
+      // CORS: Control which domains can access your API
+      cors: {
+        enabled: process.env.CORS_ENABLED !== 'false', // Enabled by default
+        allowedOrigins: process.env.CORS_ALLOWED_ORIGINS
+          ? process.env.CORS_ALLOWED_ORIGINS.split(',').map(s => s.trim())
+          : ['*'], // Default allows all; in production, specify your domains
+        allowCredentials: process.env.CORS_ALLOW_CREDENTIALS === 'true',
+      },
+      // Rate Limiting: Prevent abuse and DDoS
+      rateLimit: {
+        enabled: process.env.RATE_LIMIT_ENABLED !== 'false', // Enabled by default
+        windowMs: parseInt(process.env.RATE_LIMIT_WINDOW_MS || '900000', 10), // 15 minutes default
+        maxRequests: parseInt(process.env.RATE_LIMIT_MAX_REQUESTS || '100', 10), // 100 per window per IP
+        maxRequestsPerUser: parseInt(process.env.RATE_LIMIT_MAX_PER_USER || '50', 10), // 50 per window per userId
+        skipHealthEndpoints: process.env.RATE_LIMIT_SKIP_HEALTH !== 'false', // Skip /health & /metrics by default
+      },
+      // Helmet: Security headers (XSS, clickjacking, etc.)
+      helmet: {
+        enabled: process.env.HELMET_ENABLED !== 'false', // Enabled by default
+      },
+      // API Key: Simple authentication for API access
+      apiKey: {
+        enabled: process.env.API_KEY_ENABLED === 'true', // Disabled by default; opt-in
+        headerName: process.env.API_KEY_HEADER || 'x-api-key',
+        skipHealthEndpoints: process.env.API_KEY_SKIP_HEALTH !== 'false', // Skip auth for health/metrics
+      },
+    },
+    server: {
+      port: parseInt(process.env.PORT || '3001', 10),
+      metricsPort: process.env.METRICS_PORT ? parseInt(process.env.METRICS_PORT, 10) : undefined,
+    },
+  };
+}
+
+function mergeConfig(base: StepperConfig, overrides: Partial<StepperConfig>): StepperConfig {
+  return {
+    ...base,
+    ...overrides,
+    providers: overrides.providers ?? base.providers,
+    providerConfigs: overrides.providerConfigs ?? base.providerConfigs,
+    redis: {
+      ...base.redis,
+      ...overrides.redis,
+    },
+    cache: {
+      ...base.cache,
+      ...overrides.cache,
+    },
+    queue: {
+      ...base.queue,
+      ...overrides.queue,
+    },
+    webhook: {
+      ...base.webhook,
+      ...overrides.webhook,
+    },
+    retry: {
+      ...base.retry,
+      ...overrides.retry,
+    },
+    circuit: {
+      ...base.circuit,
+      ...overrides.circuit,
+    },
+    security: {
+      ...base.security,
+      ...overrides.security,
+      cors: {
+        ...base.security.cors,
+        ...overrides.security?.cors,
+      },
+      rateLimit: {
+        ...base.security.rateLimit,
+        ...overrides.security?.rateLimit,
+      },
+      helmet: {
+        ...base.security.helmet,
+        ...overrides.security?.helmet,
+      },
+      apiKey: {
+        ...base.security.apiKey,
+        ...overrides.security?.apiKey,
+      },
+    },
+    server: {
+      ...base.server,
+      ...overrides.server,
+    },
+  };
+}
+
+export function createConfig(overrides?: Partial<StepperConfig>): StepperConfig {
+  const base = loadConfig();
+  if (!overrides) {
+    return base;
+  }
+  return mergeConfig(base, overrides);
+}
+
+export let config = loadConfig();
+
+export function applyConfigOverrides(overrides?: Partial<StepperConfig>): StepperConfig {
+  if (!overrides) {
+    return config;
+  }
+  config = mergeConfig(loadConfig(), overrides);
+  return config;
+}

package/src/fallback/templateFallback.ts

@@ -0,0 +1,32 @@
+import { PromptInput, ReportOutput } from '../types.js';
+
+/**
+ * Generate a deterministic, template-based fallback report
+ * Used when all AI providers fail
+ */
+export function generateTemplateFallback(input: PromptInput): ReportOutput {
+  const { message, files, components, diffSummary, repo } = input;
+
+  // Extract basic info from commit message
+  const firstLine = message.split('\n')[0] || 'Code changes';
+  const fileCount = files.length;
+  const componentCount = components.length;
+
+  return {
+    title: `${firstLine.slice(0, 80)}`,
+    summary: `This commit modifies ${fileCount} file${fileCount !== 1 ? 's' : ''} in ${repo}. ` +
+      `The changes affect ${componentCount} component${componentCount !== 1 ? 's' : ''}. ` +
+      `Commit message: "${message.slice(0, 200)}${message.length > 200 ? '...' : ''}"`,
+    changes: files.slice(0, 10).map((f) => `Modified ${f}`),
+    rationale: `Automated fallback: Unable to generate AI-powered analysis. ` +
+      `Diff summary: ${diffSummary.slice(0, 300)}${diffSummary.length > 300 ? '...' : ''}`,
+    impact_and_tests: `Please review the changes manually. Ensure tests are updated for modified files: ${files.slice(0, 5).join(', ')}`,
+    next_steps: [
+      'Review changes manually',
+      'Run test suite',
+      'Verify component integration',
+      'Update documentation if needed',
+    ],
+    tags: components.slice(0, 5).join(', ') || 'general',
+  };
+}