@contextrail/code-review-agent 0.1.1-alpha.0

package/dist/llm/index.js

@@ -0,0 +1,2 @@
+export { LlmService } from './service.js';
+export { createLlmService, createOpenRouterModelProvider } from './factory.js';

package/dist/llm/service.d.ts

@@ -0,0 +1,38 @@
+import { type ModelMessage } from 'ai';
+import type { z } from 'zod';
+import type { LlmCallResult, LlmCallConfig, ModelProvider, ToolsProvider, LlmObservabilityHooks } from './types.js';
+import type { Logger } from '../logging/logger.js';
+/**
+ * LLM Service abstraction layer.
+ * Provides a predictable contract for LLM calls with built-in observability.
+ */
+export declare class LlmService {
+    private modelProvider;
+    private toolsProvider?;
+    private hooks?;
+    private logger?;
+    constructor(config: {
+        modelProvider: ModelProvider;
+        toolsProvider?: ToolsProvider;
+        hooks?: LlmObservabilityHooks;
+        logger?: Logger;
+    });
+    /**
+     * Execute an LLM call with structured output.
+     *
+     * @param messages - Conversation messages
+     * @param schema - Zod schema for structured output
+     * @param config - LLM call configuration
+     * @returns Structured output with usage metrics and metadata
+     */
+    generateStructuredOutput<T extends z.ZodType>(messages: ModelMessage[], schema: T, config: LlmCallConfig): Promise<LlmCallResult<z.infer<T>>>;
+    /**
+     * Create a new LLM service instance with updated configuration.
+     * Useful for creating service instances with different tools or hooks.
+     */
+    withConfig(config: {
+        toolsProvider?: ToolsProvider;
+        hooks?: LlmObservabilityHooks;
+        logger?: Logger;
+    }): LlmService;
+}

package/dist/llm/service.js

@@ -0,0 +1,191 @@
+import { generateText, Output, stepCountIs } from 'ai';
+import { DEFAULT_TEMPERATURE } from '../config/defaults.js';
+/**
+ * LLM Service abstraction layer.
+ * Provides a predictable contract for LLM calls with built-in observability.
+ */
+export class LlmService {
+    modelProvider;
+    toolsProvider;
+    hooks;
+    logger;
+    constructor(config) {
+        this.modelProvider = config.modelProvider;
+        this.toolsProvider = config.toolsProvider;
+        this.hooks = config.hooks;
+        this.logger = config.logger;
+    }
+    /**
+     * Execute an LLM call with structured output.
+     *
+     * @param messages - Conversation messages
+     * @param schema - Zod schema for structured output
+     * @param config - LLM call configuration
+     * @returns Structured output with usage metrics and metadata
+     */
+    async generateStructuredOutput(messages, schema, config) {
+        const { model, maxSteps = 10, metadata, temperature = DEFAULT_TEMPERATURE, topK, topP, toolChoice, activeTools,
+        // maxTokens and timeout are available in config but handled by provider/OpenRouter
+        // They're included for future extensibility and documentation
+         } = config;
+        // Get tools if provider is available
+        let tools = this.toolsProvider?.();
+        // Filter tools if activeTools is specified
+        if (tools && activeTools && activeTools.length > 0) {
+            // Filter tool set to only include specified tools
+            const filteredTools = {};
+            for (const toolName of activeTools) {
+                if (tools && toolName in tools) {
+                    filteredTools[toolName] = tools[toolName];
+                }
+            }
+            const filteredKeys = Object.keys(filteredTools);
+            if (filteredKeys.length > 0) {
+                // Type assertion needed because we're filtering the tool set
+                tools = filteredTools;
+                this.logger?.debug(`[LLM] Filtered tools to: ${filteredKeys.join(', ')}`);
+            }
+            else {
+                // No matching tools found, disable tools
+                tools = undefined;
+                this.logger?.warn(`[LLM] No matching tools found for activeTools: ${activeTools.join(', ')}`);
+            }
+        }
+        // Call observability hook
+        this.hooks?.onCallStart?.(metadata);
+        const debugParams = [`model: ${model}`, `temperature: ${temperature}`];
+        if (topK !== undefined)
+            debugParams.push(`topK: ${topK}`);
+        if (topP !== undefined)
+            debugParams.push(`topP: ${topP}`);
+        if (toolChoice) {
+            debugParams.push(`toolChoice: ${typeof toolChoice === 'string' ? toolChoice : toolChoice.toolName}`);
+        }
+        this.logger?.debug(`[LLM] Starting call: ${metadata.operation} (${debugParams.join(', ')})`);
+        try {
+            // Build generateText options with reliability settings for structured output
+            // Lower temperature (0-0.3) improves consistency and reliability for structured output
+            const outputConfig = Output.object({ schema });
+            // Debug: Log schema info (for Azure compatibility debugging)
+            // Note: The AI SDK converts Zod to JSON Schema internally and sends it to the provider
+            // Azure's validator may be strict about optional fields in the JSON Schema
+            this.logger?.debug(`[LLM] Using structured output schema for ${metadata.operation}`);
+            this.logger?.debug(`[LLM] Schema type: ${schema._def?.typeName ?? 'unknown'}`);
+            const generateOptions = {
+                model: this.modelProvider(model),
+                messages,
+                output: outputConfig,
+                stopWhen: stepCountIs(maxSteps),
+                temperature, // Lower temperature for more reliable structured output
+                ...(tools ? { tools } : {}), // Only include tools if they exist
+            };
+            // Add optional sampling parameters (alternative/complement to temperature)
+            if (topK !== undefined) {
+                generateOptions.topK = topK;
+            }
+            if (topP !== undefined) {
+                generateOptions.topP = topP;
+            }
+            // Add tool choice if specified
+            if (toolChoice) {
+                if (toolChoice === 'auto' || toolChoice === 'none' || toolChoice === 'required') {
+                    generateOptions.toolChoice = toolChoice;
+                }
+                else if (toolChoice.type === 'tool') {
+                    generateOptions.toolChoice = { type: 'tool', toolName: toolChoice.toolName };
+                }
+            }
+            const result = await generateText(generateOptions);
+            if (!result.output) {
+                // Enhanced debug logging to understand what the model actually returned
+                this.logger?.debug(`[LLM] No structured output received for ${metadata.operation}`);
+                this.logger?.debug(`[LLM] Model: ${model}, Operation: ${metadata.operation}`);
+                this.logger?.debug(`[LLM] Finish reason: ${result.finishReason ?? 'unknown'}`);
+                this.logger?.debug(`[LLM] Raw text response:`, result.text ?? '(no text)');
+                this.logger?.debug(`[LLM] Token usage:`, result.usage);
+                this.logger?.debug(`[LLM] Tool calls made:`, result.toolCalls?.length ?? 0);
+                if (result.toolCalls && result.toolCalls.length > 0) {
+                    this.logger?.debug(`[LLM] Tool calls details:`, result.toolCalls.map((call) => ({
+                        toolName: call.toolName,
+                        input: call.input,
+                    })));
+                }
+                // Log schema description if available
+                const schemaDescription = schema.description ?? 'No description';
+                this.logger?.debug(`[LLM] Expected schema description: ${schemaDescription}`);
+                this.logger?.debug(`[LLM] Full result object (sanitized):`, {
+                    hasOutput: !!result.output,
+                    hasText: !!result.text,
+                    finishReason: result.finishReason,
+                    usage: result.usage,
+                    toolCallsCount: result.toolCalls?.length ?? 0,
+                    warnings: result.warnings ?? [],
+                });
+                throw new Error(`[LLM] Failed to generate structured output for ${metadata.operation}`);
+            }
+            // Parse and validate output
+            // Note: result.output should exist here due to check above, but TypeScript needs assertion
+            if (!result.output) {
+                // This should never happen due to check above, but handle defensively
+                throw new Error(`[LLM] Structured output validation failed: output is null/undefined`);
+            }
+            const parsed = schema.parse(result.output);
+            // Extract token usage
+            const usage = result.usage
+                ? {
+                    promptTokens: result.usage.inputTokens ?? 0,
+                    completionTokens: result.usage.outputTokens ?? 0,
+                    totalTokens: result.usage.totalTokens ??
+                        (result.usage.inputTokens ?? 0) + (result.usage.outputTokens ?? 0),
+                }
+                : undefined;
+            // Extract tool calls
+            const toolCalls = Array.isArray(result.toolCalls)
+                ? result.toolCalls.map((call) => ({
+                    toolName: call.toolName,
+                    input: call.input,
+                }))
+                : undefined;
+            // Call observability hooks
+            this.hooks?.onCallComplete?.(metadata, usage);
+            if (toolCalls) {
+                for (const call of toolCalls) {
+                    this.hooks?.onToolCall?.(metadata, call.toolName, call.input);
+                }
+            }
+            this.logger?.debug(`[LLM] Completed call: ${metadata.operation} (tokens: ${usage?.totalTokens ?? 'unknown'})`);
+            return {
+                output: parsed,
+                usage,
+                toolCalls,
+                metadata,
+            };
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            // Enhanced error logging for debugging
+            if (error && typeof error === 'object' && 'text' in error) {
+                const errorText = error.text;
+                this.logger?.error(`[LLM] Model returned empty or invalid response for ${metadata.operation}`);
+                this.logger?.error(`[LLM] Model: ${model}`);
+                this.logger?.error(`[LLM] Response text: ${errorText || '(empty)'}`);
+                this.logger?.error(`[LLM] This may indicate the model doesn't support structured output well. Consider trying a different model.`);
+            }
+            this.hooks?.onCallError?.(metadata, err);
+            this.logger?.error(`[LLM] Call failed: ${metadata.operation}`, err);
+            throw err;
+        }
+    }
+    /**
+     * Create a new LLM service instance with updated configuration.
+     * Useful for creating service instances with different tools or hooks.
+     */
+    withConfig(config) {
+        return new LlmService({
+            modelProvider: this.modelProvider,
+            toolsProvider: config.toolsProvider ?? this.toolsProvider,
+            hooks: config.hooks ?? this.hooks,
+            logger: config.logger ?? this.logger,
+        });
+    }
+}

package/dist/llm/types.d.ts

@@ -0,0 +1,119 @@
+import type { LanguageModel, ToolSet } from 'ai';
+/**
+ * Token usage metrics for a single LLM call.
+ */
+export type TokenUsage = {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+};
+/**
+ * Metadata for an LLM call operation.
+ */
+export type LlmCallMetadata = {
+    operation: string;
+    model: string;
+    iteration?: number;
+    reviewer?: string;
+    [key: string]: unknown;
+};
+/**
+ * Result from an LLM call with structured output.
+ */
+export type LlmCallResult<T> = {
+    output: T;
+    usage?: TokenUsage;
+    toolCalls?: Array<{
+        toolName: string;
+        input?: unknown;
+    }>;
+    metadata: LlmCallMetadata;
+};
+/**
+ * Tool choice strategy for tool calling.
+ */
+export type ToolChoice = 'auto' | 'none' | 'required' | {
+    type: 'tool';
+    toolName: string;
+};
+/**
+ * Configuration for an LLM call.
+ */
+export type LlmCallConfig = {
+    model: string;
+    maxSteps?: number;
+    metadata: LlmCallMetadata;
+    /**
+     * Temperature for generation (0-2).
+     * Lower values (0-0.3) make output more deterministic and reliable for structured output.
+     * Default: 0.2 for structured output reliability.
+     */
+    temperature?: number;
+    /**
+     * Top-K sampling: consider only top K most likely tokens.
+     * Lower values (1-10) make output more deterministic.
+     * Use with topP for nucleus sampling, or alone as alternative to temperature.
+     */
+    topK?: number;
+    /**
+     * Top-P (nucleus) sampling: consider tokens with cumulative probability up to P.
+     * Lower values (0.1-0.5) make output more deterministic.
+     * Often used with temperature for fine-grained control.
+     */
+    topP?: number;
+    /**
+     * Tool choice strategy.
+     * - 'auto': Model decides (default)
+     * - 'required': Force tool use (useful when tools are needed for structured output)
+     * - 'none': Don't use tools
+     * - { type: 'tool', toolName: string }: Force specific tool
+     */
+    toolChoice?: ToolChoice;
+    /**
+     * Limit which tools are available for this call.
+     * If not set, all tools from toolsProvider are available.
+     * Useful for restricting tool scope or debugging.
+     */
+    activeTools?: string[];
+    /**
+     * Maximum tokens to generate.
+     * If not set, uses model default. For structured output, ensure this is high enough.
+     */
+    maxTokens?: number;
+    /**
+     * Request timeout in milliseconds.
+     * Default: 120000 (2 minutes) for reliability.
+     */
+    timeout?: number;
+};
+/**
+ * Model provider factory function.
+ * Takes a model name and returns a LanguageModel instance.
+ */
+export type ModelProvider = (modelName: string) => LanguageModel;
+/**
+ * Tools provider factory function.
+ * Returns a ToolSet for the LLM call.
+ */
+export type ToolsProvider = () => ToolSet | undefined;
+/**
+ * Observability hooks for LLM calls.
+ */
+export type LlmObservabilityHooks = {
+    /**
+     * Called before an LLM call starts.
+     */
+    onCallStart?: (metadata: LlmCallMetadata) => void;
+    /**
+     * Called after an LLM call completes successfully.
+     */
+    onCallComplete?: (metadata: LlmCallMetadata, usage?: TokenUsage) => void;
+    /**
+     * Called when an LLM call fails.
+     */
+    onCallError?: (metadata: LlmCallMetadata, error: Error) => void;
+    /**
+     * Called when tool calls are made during an LLM call.
+     */
+    onToolCall?: (metadata: LlmCallMetadata, toolName: string, input?: unknown) => void;
+};

package/dist/llm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/logging/logger.d.ts

@@ -0,0 +1,9 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+export type Logger = {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};
+export declare const parseLogLevel: (value?: string) => LogLevel;
+export declare const createLogger: (level: LogLevel) => Logger;

package/dist/logging/logger.js

@@ -0,0 +1,52 @@
+const LEVEL_ORDER = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    silent: 50,
+};
+export const parseLogLevel = (value) => {
+    if (!value) {
+        return 'info';
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true') {
+        return 'debug';
+    }
+    if (normalized === 'false') {
+        return 'info';
+    }
+    if (normalized === 'debug' || normalized === 'info' || normalized === 'warn' || normalized === 'error') {
+        return normalized;
+    }
+    if (normalized === 'silent') {
+        return 'silent';
+    }
+    return 'info';
+};
+export const createLogger = (level) => {
+    const threshold = LEVEL_ORDER[level];
+    const shouldLog = (messageLevel) => LEVEL_ORDER[messageLevel] >= threshold;
+    return {
+        debug: (...args) => {
+            if (shouldLog('debug')) {
+                console.debug(...args);
+            }
+        },
+        info: (...args) => {
+            if (shouldLog('info')) {
+                console.info(...args);
+            }
+        },
+        warn: (...args) => {
+            if (shouldLog('warn')) {
+                console.warn(...args);
+            }
+        },
+        error: (...args) => {
+            if (shouldLog('error')) {
+                console.error(...args);
+            }
+        },
+    };
+};