@eldrforge/ai-service 0.1.1

package/eslint.config.mjs

@@ -0,0 +1,84 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import typescriptEslint from "@typescript-eslint/eslint-plugin";
+import importPlugin from "eslint-plugin-import";
+import globals from "globals";
+import tsParser from "@typescript-eslint/parser";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import js from "@eslint/js";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const compat = new FlatCompat({
+    baseDirectory: __dirname,
+    recommendedConfig: js.configs.recommended,
+    allConfig: js.configs.all
+});
+
+export default defineConfig([
+    globalIgnores([
+        "dist/**",
+        "node_modules/**",
+        "**/*.test.ts",
+        "temp-dist/**",
+    ]),
+    {
+        extends: compat.extends("eslint:recommended", "plugin:@typescript-eslint/recommended"),
+
+        plugins: {
+            "@typescript-eslint": typescriptEslint,
+            "import": importPlugin,
+        },
+
+        languageOptions: {
+            globals: {
+                ...globals.node,
+            },
+
+            parser: tsParser,
+            ecmaVersion: "latest",
+            sourceType: "module",
+        },
+
+        rules: {
+            "@typescript-eslint/no-explicit-any": "off",
+            "@typescript-eslint/explicit-function-return-type": "off",
+
+            "@typescript-eslint/no-unused-vars": ["warn", {
+                argsIgnorePattern: "^_",
+            }],
+
+            indent: ["warn", 4, {
+                SwitchCase: 1,
+            }],
+
+            "import/extensions": ["error", "never", {
+                ignorePackages: true,
+                pattern: {
+                    "js": "never",
+                    "ts": "never",
+                    "d": "always"
+                }
+            }],
+
+            "import/no-extraneous-dependencies": ["error", {
+                devDependencies: true,
+                optionalDependencies: false,
+                peerDependencies: false,
+            }],
+
+            "no-console": ["error"],
+
+            "no-restricted-imports": ["error", {
+                paths: [],
+                patterns: [
+                    {
+                        group: ["src/**"],
+                        message: "Use absolute imports instead of relative imports"
+                    }
+                ]
+            }]
+        },
+    }]);
+

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@eldrforge/ai-service",
+  "version": "0.1.1",
+  "description": "AI-powered content generation for automation - OpenAI integration with structured prompts",
+  "main": "dist/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/calenvarek/ai-service.git"
+  },
+  "scripts": {
+    "build": "npm run lint && tsc --noEmit && vite build",
+    "dev": "vite",
+    "watch": "vite build --watch",
+    "test": "vitest run --coverage",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "clean": "rm -rf dist",
+    "precommit": "npm run clean && npm run build && npm run lint && npm run test",
+    "prepublishOnly": "npm run clean && npm run lint && npm run build && npm run test"
+  },
+  "keywords": [
+    "ai",
+    "openai",
+    "llm",
+    "prompt-engineering",
+    "content-generation",
+    "automation",
+    "gpt",
+    "commit-messages",
+    "release-notes"
+  ],
+  "author": "Calen Varek <calenvarek@gmail.com>",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@eldrforge/git-tools": "^0.1.3",
+    "@riotprompt/riotprompt": "^0.0.8",
+    "openai": "^6.3.0"
+  },
+  "peerDependencies": {
+    "winston": "^3.17.0"
+  },
+  "peerDependenciesMeta": {
+    "winston": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.33.0",
+    "@swc/core": "^1.13.3",
+    "@types/node": "^24.2.1",
+    "@types/winston": "^2.4.4",
+    "@typescript-eslint/eslint-plugin": "^8.39.1",
+    "@typescript-eslint/parser": "^8.39.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "esbuild": "0.25.10",
+    "eslint": "^9.33.0",
+    "eslint-plugin-import": "^2.32.0",
+    "globals": "^16.3.0",
+    "mockdate": "^3.0.5",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.2",
+    "vite-plugin-dts": "^4.3.0",
+    "vite-plugin-node": "^7.0.0",
+    "vitest": "^3.2.4",
+    "winston": "^3.17.0"
+  }
+}

package/src/ai.ts

@@ -0,0 +1,421 @@
+import { OpenAI } from 'openai';
+import type { ChatCompletionMessageParam } from 'openai/resources';
+import { safeJsonParse } from '@eldrforge/git-tools';
+import fs from 'fs';
+import { getLogger } from './logger';
+import type { AIConfig, Transcription, StorageAdapter, Logger } from './types';
+
+export interface OpenAIOptions {
+    responseFormat?: any;
+    model?: string;
+    debug?: boolean;
+    debugFile?: string;
+    debugRequestFile?: string;
+    debugResponseFile?: string;
+    maxTokens?: number;
+    openaiReasoning?: 'low' | 'medium' | 'high';
+    openaiMaxOutputTokens?: number;
+    storage?: StorageAdapter;
+    logger?: Logger;
+}
+
+export interface TranscriptionOptions {
+    model?: string;
+    debug?: boolean;
+    debugFile?: string;
+    debugRequestFile?: string;
+    debugResponseFile?: string;
+    outputDirectory?: string;
+    storage?: StorageAdapter;
+    logger?: Logger;
+    onArchive?: (audioPath: string, transcriptionText: string) => Promise<void>;
+}
+
+/**
+ * Get the appropriate model to use based on command-specific configuration
+ * Command-specific model overrides the global model setting
+ */
+export function getModelForCommand(config: AIConfig, commandName: string): string {
+    let commandModel: string | undefined;
+
+    switch (commandName) {
+        case 'commit':
+        case 'audio-commit':
+            commandModel = config.commands?.commit?.model;
+            break;
+        case 'release':
+            commandModel = config.commands?.release?.model;
+            break;
+        case 'review':
+        case 'audio-review':
+            commandModel = config.commands?.review?.model;
+            break;
+        default:
+            // For other commands, just use global model
+            break;
+    }
+
+    // Return command-specific model if available, otherwise global model
+    return commandModel || config.model || 'gpt-4o-mini';
+}
+
+/**
+ * Get the appropriate OpenAI reasoning level based on command-specific configuration
+ * Command-specific reasoning overrides the global reasoning setting
+ */
+export function getOpenAIReasoningForCommand(config: AIConfig, commandName: string): 'low' | 'medium' | 'high' {
+    let commandReasoning: 'low' | 'medium' | 'high' | undefined;
+
+    switch (commandName) {
+        case 'commit':
+        case 'audio-commit':
+            commandReasoning = config.commands?.commit?.reasoning;
+            break;
+        case 'release':
+            commandReasoning = config.commands?.release?.reasoning;
+            break;
+        case 'review':
+        case 'audio-review':
+            commandReasoning = config.commands?.review?.reasoning;
+            break;
+        default:
+            // For other commands, just use global reasoning
+            break;
+    }
+
+    // Return command-specific reasoning if available, otherwise global reasoning
+    return commandReasoning || config.reasoning || 'low';
+}
+
+export class OpenAIError extends Error {
+    constructor(message: string, public readonly isTokenLimitError: boolean = false) {
+        super(message);
+        this.name = 'OpenAIError';
+    }
+}
+
+// Check if an error is a token limit exceeded error
+export function isTokenLimitError(error: any): boolean {
+    if (!error?.message) return false;
+
+    const message = error.message.toLowerCase();
+    return message.includes('maximum context length') ||
+           message.includes('context_length_exceeded') ||
+           message.includes('token limit') ||
+           message.includes('too many tokens') ||
+           message.includes('reduce the length');
+}
+
+// Check if an error is a rate limit error
+export function isRateLimitError(error: any): boolean {
+    if (!error?.message && !error?.code && !error?.status) return false;
+
+    // Check for OpenAI specific rate limit indicators
+    if (error.status === 429 || error.code === 'rate_limit_exceeded') {
+        return true;
+    }
+
+    // Only check message if it exists
+    if (error.message) {
+        const message = error.message.toLowerCase();
+        return message.includes('rate limit exceeded') ||
+               message.includes('too many requests') ||
+               message.includes('quota exceeded') ||
+               (message.includes('rate') && message.includes('limit'));
+    }
+
+    return false;
+}
+
+/**
+ * Create OpenAI completion with optional debug and retry support
+ */
+export async function createCompletion(
+    messages: ChatCompletionMessageParam[],
+    options: OpenAIOptions = { model: "gpt-4o-mini" }
+): Promise<string | any> {
+    const logger = options.logger || getLogger();
+    let openai: OpenAI | null = null;
+
+    try {
+        const apiKey = process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new OpenAIError('OPENAI_API_KEY environment variable is not set');
+        }
+
+        // Create the client which we'll close in the finally block.
+        const timeoutMs = parseInt(process.env.OPENAI_TIMEOUT_MS || '300000'); // Default to 5 minutes
+        openai = new OpenAI({
+            apiKey: apiKey,
+            timeout: timeoutMs,
+        });
+
+        const modelToUse = options.model || "gpt-4o-mini";
+
+        // Calculate request size
+        const requestSize = JSON.stringify(messages).length;
+        const requestSizeKB = (requestSize / 1024).toFixed(2);
+
+        // Log model, reasoning level, and request size
+        const reasoningInfo = options.openaiReasoning ? ` | Reasoning: ${options.openaiReasoning}` : '';
+        logger.info('🤖 Making request to OpenAI');
+        logger.info('   Model: %s%s', modelToUse, reasoningInfo);
+        logger.info('   Request size: %s KB (%s bytes)', requestSizeKB, requestSize.toLocaleString());
+
+        logger.debug('Sending prompt to OpenAI: %j', messages);
+
+        // Use openaiMaxOutputTokens if specified (highest priority), otherwise fall back to maxTokens, or default to 10000
+        const maxCompletionTokens = options.openaiMaxOutputTokens ?? options.maxTokens ?? 10000;
+
+        // Save request debug file if enabled
+        if (options.debug && (options.debugRequestFile || options.debugFile) && options.storage) {
+            const requestData = {
+                model: modelToUse,
+                messages,
+                max_completion_tokens: maxCompletionTokens,
+                response_format: options.responseFormat,
+                reasoning_effort: options.openaiReasoning,
+            };
+            const debugFile = options.debugRequestFile || options.debugFile;
+            await options.storage.writeTemp(debugFile!, JSON.stringify(requestData, null, 2));
+            logger.debug('Wrote request debug file to %s', debugFile);
+        }
+
+        // Prepare the API call options
+        const apiOptions: any = {
+            model: modelToUse,
+            messages,
+            max_completion_tokens: maxCompletionTokens,
+            response_format: options.responseFormat,
+        };
+
+        // Add reasoning parameter if specified and model supports it
+        if (options.openaiReasoning && (modelToUse.includes('gpt-5') || modelToUse.includes('o3'))) {
+            apiOptions.reasoning_effort = options.openaiReasoning;
+        }
+
+        // Add timeout wrapper to the OpenAI API call
+        const startTime = Date.now();
+        const completionPromise = openai.chat.completions.create(apiOptions);
+
+        // Create timeout promise with proper cleanup to prevent memory leaks
+        let timeoutId: NodeJS.Timeout | null = null;
+        const timeoutPromise = new Promise<never>((_, reject) => {
+            const timeoutMs = parseInt(process.env.OPENAI_TIMEOUT_MS || '300000'); // Default to 5 minutes
+            timeoutId = setTimeout(() => reject(new OpenAIError(`OpenAI API call timed out after ${timeoutMs/1000} seconds`)), timeoutMs);
+        });
+
+        let completion;
+        try {
+            completion = await Promise.race([completionPromise, timeoutPromise]);
+        } finally {
+            // Clear the timeout to prevent memory leaks
+            if (timeoutId !== null) {
+                clearTimeout(timeoutId);
+            }
+        }
+
+        const elapsedTime = Date.now() - startTime;
+
+        // Save response debug file if enabled
+        if (options.debug && (options.debugResponseFile || options.debugFile) && options.storage) {
+            const debugFile = options.debugResponseFile || options.debugFile;
+            await options.storage.writeTemp(debugFile!, JSON.stringify(completion, null, 2));
+            logger.debug('Wrote response debug file to %s', debugFile);
+        }
+
+        const response = completion.choices[0]?.message?.content?.trim();
+        if (!response) {
+            throw new OpenAIError('No response received from OpenAI');
+        }
+
+        // Calculate and log response size
+        const responseSize = response.length;
+        const responseSizeKB = (responseSize / 1024).toFixed(2);
+        logger.info('   Response size: %s KB (%s bytes)', responseSizeKB, responseSize.toLocaleString());
+
+        // Log elapsed time
+        const elapsedTimeFormatted = elapsedTime >= 1000
+            ? `${(elapsedTime / 1000).toFixed(1)}s`
+            : `${elapsedTime}ms`;
+        logger.info('   Time: %s', elapsedTimeFormatted);
+
+        // Log token usage if available
+        if (completion.usage) {
+            logger.info('   Token usage: %s prompt + %s completion = %s total',
+                completion.usage.prompt_tokens?.toLocaleString() || '?',
+                completion.usage.completion_tokens?.toLocaleString() || '?',
+                completion.usage.total_tokens?.toLocaleString() || '?'
+            );
+        }
+
+        logger.debug('Received response from OpenAI: %s...', response.substring(0, 30));
+        if (options.responseFormat) {
+            return safeJsonParse(response, 'OpenAI API response');
+        } else {
+            return response;
+        }
+
+    } catch (error: any) {
+        logger.error('Error calling OpenAI API: %s %s', error.message, error.stack);
+        const isTokenError = isTokenLimitError(error);
+        throw new OpenAIError(`Failed to create completion: ${error.message}`, isTokenError);
+    } finally {
+        // OpenAI client cleanup is handled automatically by the library
+        // No manual cleanup needed for newer versions
+    }
+}
+
+/**
+ * Create completion with automatic retry on token limit errors
+ */
+export async function createCompletionWithRetry(
+    messages: ChatCompletionMessageParam[],
+    options: OpenAIOptions = { model: "gpt-4o-mini" },
+    retryCallback?: (attempt: number) => Promise<ChatCompletionMessageParam[]>
+): Promise<string | any> {
+    const logger = options.logger || getLogger();
+    const maxRetries = 3;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            const messagesToSend = attempt === 1 ? messages : (retryCallback ? await retryCallback(attempt) : messages);
+            return await createCompletion(messagesToSend, options);
+        } catch (error: any) {
+            if (error instanceof OpenAIError && error.isTokenLimitError && attempt < maxRetries && retryCallback) {
+                logger.warn('Token limit exceeded on attempt %d/%d, retrying with reduced content...', attempt, maxRetries);
+                // Add exponential backoff for token limit errors
+                const backoffMs = Math.min(1000 * Math.pow(2, attempt - 1), 10000);
+                await new Promise(resolve => setTimeout(resolve, backoffMs));
+                continue;
+            } else if (isRateLimitError(error) && attempt < maxRetries) {
+                // Handle rate limiting with exponential backoff
+                const backoffMs = Math.min(2000 * Math.pow(2, attempt - 1), 15000); // More reasonable backoff: 2s, 4s, 8s, max 15s
+                logger.warn(`Rate limit hit on attempt ${attempt}/${maxRetries}, waiting ${backoffMs}ms before retry...`);
+                await new Promise(resolve => setTimeout(resolve, backoffMs));
+                continue;
+            }
+            throw error;
+        }
+    }
+
+    // This should never be reached, but TypeScript requires it
+    throw new OpenAIError('Max retries exceeded');
+}
+
+/**
+ * Transcribe audio file using OpenAI Whisper API
+ */
+export async function transcribeAudio(
+    filePath: string,
+    options: TranscriptionOptions = { model: "whisper-1" }
+): Promise<Transcription> {
+    const logger = options.logger || getLogger();
+    let openai: OpenAI | null = null;
+    let audioStream: fs.ReadStream | null = null;
+    let streamClosed = false;
+
+    // Helper function to safely close the stream
+    const closeAudioStream = () => {
+        if (audioStream && !streamClosed) {
+            try {
+                // Only call destroy if it exists and the stream isn't already destroyed
+                if (typeof audioStream.destroy === 'function' && !audioStream.destroyed) {
+                    audioStream.destroy();
+                }
+                streamClosed = true;
+                logger.debug('Audio stream closed successfully');
+            } catch (streamErr) {
+                logger.debug('Failed to destroy audio read stream: %s', (streamErr as Error).message);
+                streamClosed = true; // Mark as closed even if destroy failed
+            }
+        }
+    };
+
+    try {
+        const apiKey = process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new OpenAIError('OPENAI_API_KEY environment variable is not set');
+        }
+
+        openai = new OpenAI({
+            apiKey: apiKey,
+        });
+
+        logger.debug('Transcribing audio file: %s', filePath);
+
+        // Save request debug file if enabled
+        if (options.debug && (options.debugRequestFile || options.debugFile) && options.storage) {
+            const requestData = {
+                model: options.model || "whisper-1",
+                file: filePath, // Can't serialize the stream, so just save the file path
+                response_format: "json",
+            };
+            const debugFile = options.debugRequestFile || options.debugFile;
+            await options.storage.writeTemp(debugFile!, JSON.stringify(requestData, null, 2));
+            logger.debug('Wrote request debug file to %s', debugFile);
+        }
+
+        audioStream = fs.createReadStream(filePath);
+
+        // Set up error handler for the stream to ensure cleanup on stream errors
+        // Only add handler if the stream has the 'on' method (real streams)
+        if (audioStream && typeof audioStream.on === 'function') {
+            audioStream.on('error', (streamError) => {
+                logger.error('Audio stream error: %s', streamError.message);
+                closeAudioStream();
+            });
+        }
+
+        let transcription;
+        try {
+            transcription = await openai.audio.transcriptions.create({
+                model: options.model || "whisper-1",
+                file: audioStream,
+                response_format: "json",
+            });
+            // Close the stream immediately after successful API call to prevent race conditions
+            closeAudioStream();
+        } catch (apiError) {
+            // Close the stream immediately if the API call fails
+            closeAudioStream();
+            throw apiError;
+        }
+
+        // Save response debug file if enabled
+        if (options.debug && (options.debugResponseFile || options.debugFile) && options.storage) {
+            const debugFile = options.debugResponseFile || options.debugFile;
+            await options.storage.writeTemp(debugFile!, JSON.stringify(transcription, null, 2));
+            logger.debug('Wrote response debug file to %s', debugFile);
+        }
+
+        const response = transcription;
+        if (!response) {
+            throw new OpenAIError('No transcription received from OpenAI');
+        }
+
+        logger.debug('Received transcription from OpenAI: %s', response);
+
+        // Archive the audio file and transcription if callback provided
+        if (options.onArchive) {
+            try {
+                await options.onArchive(filePath, response.text);
+            } catch (archiveError: any) {
+                // Don't fail the transcription if archiving fails, just log the error
+                logger.warn('Failed to archive audio file: %s', archiveError.message);
+            }
+        }
+
+        return response;
+
+    } catch (error: any) {
+        logger.error('Error transcribing audio file: %s %s', error.message, error.stack);
+        throw new OpenAIError(`Failed to transcribe audio: ${error.message}`);
+    } finally {
+        // Ensure the audio stream is properly closed to release file handles
+        closeAudioStream();
+        // OpenAI client cleanup is handled automatically by the library
+        // No manual cleanup needed for newer versions
+    }
+}
+

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @eldrforge/ai-service
+ *
+ * AI-powered content generation for automation tools.
+ * Provides OpenAI integration with structured prompts for
+ * generating commit messages, release notes, and code reviews.
+ */
+
+// Core functionality
+export * from './types';
+export * from './logger';
+export * from './ai';
+export * from './interactive';
+export * from './prompts';