@rigour-labs/core 3.0.6 → 4.0.1

package/dist/gates/deep-analysis.js

@@ -0,0 +1,302 @@
+/**
+ * Deep Analysis Gate — LLM-powered code quality analysis.
+ *
+ * Three-step pipeline:
+ * 1. AST extracts facts → "UserService has 8 public methods touching 4 domains"
+ * 2. LLM interprets facts → "UserService violates Single Responsibility"
+ * 3. AST verifies LLM → Does UserService actually have those methods? ✓
+ *
+ * AST grounds LLM. LLM interprets AST. Neither works alone.
+ */
+import { Gate } from './base.js';
+import { createProvider } from '../inference/index.js';
+import { extractFacts, factsToPromptString, chunkFacts, buildAnalysisPrompt, buildCrossFilePrompt, verifyFindings } from '../deep/index.js';
+import { Logger } from '../utils/logger.js';
+/** Max files to analyze before truncating (prevents OOM on huge repos) */
+const MAX_ANALYZABLE_FILES = 500;
+/** Setup timeout: 120s for model download, 30s for API connection */
+const SETUP_TIMEOUT_MS = 120_000;
+export class DeepAnalysisGate extends Gate {
+    config;
+    provider = null;
+    constructor(config) {
+        super('deep-analysis', 'Deep Code Quality Analysis');
+        this.config = config;
+    }
+    get provenance() {
+        return 'deep-analysis';
+    }
+    async run(context) {
+        const { onProgress } = this.config;
+        const failures = [];
+        const startTime = Date.now();
+        try {
+            // Step 0: Initialize inference provider (with timeout)
+            onProgress?.('\n  Setting up Rigour Brain...\n');
+            this.provider = createProvider(this.config.options);
+            await Promise.race([
+                this.provider.setup(onProgress),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('Setup timed out. Check network or model availability.')), SETUP_TIMEOUT_MS)),
+            ]);
+            const isLocal = !this.config.options.apiKey || this.config.options.provider === 'local';
+            if (isLocal) {
+                onProgress?.('\n  🔒 100% local analysis. Your code never leaves this machine.\n');
+            }
+            else {
+                onProgress?.(`\n  ☁️  Using ${this.config.options.provider} API. Code is sent to cloud.\n`);
+            }
+            // Step 1: AST extracts facts
+            onProgress?.('  Extracting code facts...');
+            let allFacts = await extractFacts(context.cwd, context.ignore);
+            if (allFacts.length === 0) {
+                onProgress?.('  No analyzable files found. Check ignore patterns and file extensions.');
+                return [];
+            }
+            // Cap file count to prevent OOM on huge repos
+            if (allFacts.length > MAX_ANALYZABLE_FILES) {
+                onProgress?.(`  ⚠ Found ${allFacts.length} files, capping at ${MAX_ANALYZABLE_FILES} (largest files prioritized).`);
+                // Sort by line count descending — analyze the biggest files first
+                allFacts.sort((a, b) => b.lineCount - a.lineCount);
+                allFacts = allFacts.slice(0, MAX_ANALYZABLE_FILES);
+            }
+            const agentCount = this.config.options.agents || 1;
+            const isCloud = !!this.config.options.apiKey;
+            onProgress?.(`  Found ${allFacts.length} files to analyze${agentCount > 1 ? ` with ${agentCount} parallel agents` : ''}.`);
+            // Step 2: LLM interprets facts (in chunks)
+            const chunks = chunkFacts(allFacts);
+            const allFindings = [];
+            let failedChunks = 0;
+            if (agentCount > 1 && isCloud) {
+                // ── Multi-agent mode: partition chunks across N agents, analyze in parallel ──
+                // Each agent gets its own provider instance for true parallelism.
+                // Local mode stays sequential (single sidecar process).
+                onProgress?.(`  Spawning ${agentCount} parallel agents...`);
+                const agentBuckets = Array.from({ length: agentCount }, () => []);
+                chunks.forEach((chunk, i) => agentBuckets[i % agentCount].push(chunk));
+                // Create N independent provider instances
+                const agentProviders = [];
+                for (let a = 0; a < agentCount; a++) {
+                    if (agentBuckets[a].length === 0)
+                        continue;
+                    const p = createProvider(this.config.options);
+                    await p.setup(); // Already connected — cloud setup is instant after first
+                    agentProviders.push(p);
+                }
+                // Run all agents in parallel
+                const agentResults = await Promise.allSettled(agentProviders.map(async (provider, agentIdx) => {
+                    const bucket = agentBuckets[agentIdx];
+                    const findings = [];
+                    let failed = 0;
+                    for (let ci = 0; ci < bucket.length; ci++) {
+                        const globalIdx = agentIdx + ci * agentCount + 1;
+                        onProgress?.(`  Agent ${agentIdx + 1}: batch ${ci + 1}/${bucket.length} (global ${globalIdx}/${chunks.length})`);
+                        const factsStr = factsToPromptString(bucket[ci]);
+                        const prompt = buildAnalysisPrompt(factsStr, this.config.checks);
+                        try {
+                            const response = await provider.analyze(prompt, {
+                                maxTokens: this.config.maxTokens || 8192,
+                                temperature: this.config.temperature || 0.1,
+                                timeout: this.config.timeoutMs || 120000,
+                                jsonMode: true,
+                            });
+                            findings.push(...parseFindings(response));
+                        }
+                        catch (error) {
+                            failed++;
+                            Logger.warn(`Agent ${agentIdx + 1} chunk ${ci + 1} failed: ${error.message}`);
+                        }
+                    }
+                    return { findings, failed };
+                }));
+                // Merge results and dispose extra providers
+                for (let i = 0; i < agentResults.length; i++) {
+                    const result = agentResults[i];
+                    if (result.status === 'fulfilled') {
+                        allFindings.push(...result.value.findings);
+                        failedChunks += result.value.failed;
+                    }
+                    else {
+                        failedChunks += agentBuckets[i].length;
+                        Logger.warn(`Agent ${i + 1} failed entirely: ${result.reason?.message || 'unknown'}`);
+                    }
+                    agentProviders[i]?.dispose();
+                }
+                onProgress?.(`  All ${agentCount} agents completed.`);
+            }
+            else {
+                // ── Single-agent mode: sequential chunk processing ──
+                let chunkIndex = 0;
+                for (const chunk of chunks) {
+                    chunkIndex++;
+                    onProgress?.(`  Analyzing batch ${chunkIndex}/${chunks.length}...`);
+                    const factsStr = factsToPromptString(chunk);
+                    const prompt = buildAnalysisPrompt(factsStr, this.config.checks);
+                    try {
+                        const response = await this.provider.analyze(prompt, {
+                            maxTokens: this.config.maxTokens || (isCloud ? 4096 : 512),
+                            temperature: this.config.temperature || 0.1,
+                            timeout: this.config.timeoutMs || (isCloud ? 120000 : 60000),
+                            jsonMode: true,
+                        });
+                        const findings = parseFindings(response);
+                        allFindings.push(...findings);
+                    }
+                    catch (error) {
+                        failedChunks++;
+                        Logger.warn(`Chunk ${chunkIndex} inference failed: ${error.message}`);
+                        onProgress?.(`  ⚠ Batch ${chunkIndex} failed: ${error.message}`);
+                    }
+                }
+            }
+            // Cross-file analysis (if we have enough files and at least some chunks succeeded)
+            if (allFacts.length >= 3 && failedChunks < chunks.length) {
+                onProgress?.('  Running cross-file analysis...');
+                try {
+                    const crossPrompt = buildCrossFilePrompt(allFacts);
+                    const crossResponse = await this.provider.analyze(crossPrompt, {
+                        maxTokens: this.config.maxTokens || (isCloud ? 4096 : 512),
+                        temperature: this.config.temperature || 0.1,
+                        timeout: this.config.timeoutMs || (isCloud ? 120000 : 60000),
+                        jsonMode: true,
+                    });
+                    const crossFindings = parseFindings(crossResponse);
+                    allFindings.push(...crossFindings);
+                }
+                catch (error) {
+                    Logger.warn(`Cross-file analysis failed: ${error.message}`);
+                }
+            }
+            // Step 3: AST verifies LLM
+            onProgress?.('  Verifying findings...');
+            const verified = verifyFindings(allFindings, allFacts);
+            const durationMs = Date.now() - startTime;
+            onProgress?.(`  ✓ ${verified.length} verified findings (${allFindings.length - verified.length} dropped) in ${(durationMs / 1000).toFixed(1)}s`);
+            if (failedChunks > 0) {
+                onProgress?.(`  ⚠ ${failedChunks}/${chunks.length} batches failed — results may be incomplete.`);
+            }
+            // Convert to Failure format
+            for (const finding of verified) {
+                const failure = this.createFailure(finding.description, [finding.file], finding.suggestion, `[${finding.category}] ${finding.description.substring(0, 80)}`, finding.line, undefined, finding.severity);
+                // Tag with deep analysis metadata
+                failure.confidence = finding.confidence;
+                failure.source = 'llm';
+                failure.category = finding.category;
+                failure.verified = finding.verified;
+                failures.push(failure);
+            }
+        }
+        catch (error) {
+            Logger.error(`Deep analysis failed: ${error.message}`);
+            onProgress?.(`  ⚠ Deep analysis error: ${error.message}`);
+            // Don't fail the whole check — deep is advisory
+        }
+        finally {
+            this.provider?.dispose();
+        }
+        return failures;
+    }
+}
+/**
+ * Parse LLM response into structured findings.
+ * Handles various response formats (raw JSON, markdown-wrapped JSON, etc.)
+ */
+function parseFindings(response) {
+    if (!response || response.trim().length === 0) {
+        Logger.warn('Empty LLM response received');
+        return [];
+    }
+    try {
+        // Try direct JSON parse first
+        const parsed = JSON.parse(response);
+        if (Array.isArray(parsed.findings))
+            return validateFindings(parsed.findings);
+        if (Array.isArray(parsed))
+            return validateFindings(parsed);
+        return [];
+    }
+    catch {
+        // Try extracting JSON from markdown code blocks
+        const jsonMatch = response.match(/```(?:json)?\s*([\s\S]*?)```/);
+        if (jsonMatch) {
+            try {
+                const parsed = JSON.parse(jsonMatch[1]);
+                if (Array.isArray(parsed.findings))
+                    return validateFindings(parsed.findings);
+                if (Array.isArray(parsed))
+                    return validateFindings(parsed);
+            }
+            catch {
+                // Fall through
+            }
+        }
+        // Try finding JSON object in response
+        const objectMatch = response.match(/\{[\s\S]*"findings"[\s\S]*\}/);
+        if (objectMatch) {
+            try {
+                const parsed = JSON.parse(objectMatch[0]);
+                if (Array.isArray(parsed.findings))
+                    return validateFindings(parsed.findings);
+            }
+            catch {
+                // Give up
+            }
+        }
+        // Last resort: try to recover truncated JSON arrays
+        // LLMs sometimes exceed token limits, truncating the response mid-JSON
+        const recovered = recoverTruncatedFindings(response);
+        if (recovered.length > 0) {
+            Logger.info(`Recovered ${recovered.length} findings from truncated response`);
+            return recovered;
+        }
+        Logger.warn(`Could not parse LLM response as findings JSON. First 200 chars: ${response.substring(0, 200)}`);
+        return [];
+    }
+}
+/**
+ * Attempt to recover individual finding objects from a truncated JSON response.
+ * Extracts complete JSON objects from partial arrays.
+ */
+function recoverTruncatedFindings(response) {
+    const findings = [];
+    // Match individual complete objects within the response
+    const objectRegex = /\{\s*"category"\s*:\s*"[^"]+"\s*,[\s\S]*?"description"\s*:\s*"[^"]*"[^}]*\}/g;
+    let match;
+    while ((match = objectRegex.exec(response)) !== null) {
+        try {
+            const obj = JSON.parse(match[0]);
+            if (obj.category && obj.file && obj.description) {
+                findings.push(obj);
+            }
+        }
+        catch {
+            // Individual object was itself truncated — skip
+        }
+    }
+    return validateFindings(findings);
+}
+/**
+ * Validate and sanitize findings from LLM response.
+ * Drops malformed entries that lack required fields.
+ */
+function validateFindings(raw) {
+    return raw.filter(f => {
+        if (!f || typeof f !== 'object')
+            return false;
+        if (!f.category || typeof f.category !== 'string')
+            return false;
+        if (!f.file || typeof f.file !== 'string')
+            return false;
+        if (!f.description || typeof f.description !== 'string')
+            return false;
+        // Normalize confidence
+        if (typeof f.confidence !== 'number' || f.confidence < 0 || f.confidence > 1) {
+            f.confidence = 0.5;
+        }
+        // Normalize severity
+        const validSeverities = ['critical', 'high', 'medium', 'low', 'info'];
+        if (!validSeverities.includes(f.severity)) {
+            f.severity = 'medium';
+        }
+        return true;
+    });
+}

package/dist/gates/runner.d.ts

@@ -1,5 +1,5 @@
 import { Gate } from './base.js';
-import { Config, Report } from '../types/index.js';
+import { Config, Report, DeepOptions } from '../types/index.js';
 export declare class GateRunner {
     private config;
     private gates;
@@ -9,5 +9,7 @@ export declare class GateRunner {
      * Allows adding custom gates dynamically (SOLID - Open/Closed Principle)
      */
     addGate(gate: Gate): void;
-    run(cwd: string, patterns?: string[]): Promise<Report>;
+    run(cwd: string, patterns?: string[], deepOptions?: DeepOptions & {
+        onProgress?: (msg: string) => void;
+    }): Promise<Report>;
 }

package/dist/gates/runner.js

@@ -1,4 +1,5 @@
 import { SEVERITY_WEIGHTS } from '../types/index.js';
+import { DeepAnalysisGate } from './deep-analysis.js';
 import { FileGate } from './file.js';
 import { ContentGate } from './content.js';
 import { StructureGate } from './structure.js';
@@ -102,7 +103,7 @@ export class GateRunner {
     addGate(gate) {
         this.gates.push(gate);
     }
-    async run(cwd, patterns) {
+    async run(cwd, patterns, deepOptions) {
         const start = Date.now();
         const failures = [];
         const summary = {};
@@ -164,6 +165,43 @@ export class GateRunner {
                 }
             }
         }
+        // 3. Run Deep Analysis (if enabled)
+        let deepStats = undefined;
+        if (deepOptions?.enabled) {
+            const deepSetupStart = Date.now();
+            const deepGate = new DeepAnalysisGate({
+                options: deepOptions,
+                checks: this.config.gates.deep?.checks,
+                threads: this.config.gates.deep?.threads,
+                maxTokens: this.config.gates.deep?.max_tokens,
+                temperature: this.config.gates.deep?.temperature,
+                timeoutMs: this.config.gates.deep?.timeout_ms,
+                onProgress: deepOptions.onProgress,
+            });
+            try {
+                const deepFailures = await deepGate.run({ cwd, ignore, patterns });
+                if (deepFailures.length > 0) {
+                    failures.push(...deepFailures);
+                    summary['deep-analysis'] = 'FAIL';
+                }
+                else {
+                    summary['deep-analysis'] = 'PASS';
+                }
+                deepStats = {
+                    enabled: true,
+                    tier: deepOptions.apiKey ? 'cloud' : (deepOptions.pro ? 'pro' : 'deep'),
+                    model: deepOptions.apiKey ? (deepOptions.provider || 'cloud') : (deepOptions.pro ? 'Qwen2.5-Coder-1.5B' : 'Qwen2.5-Coder-0.5B'),
+                    total_ms: Date.now() - deepSetupStart,
+                    findings_count: deepFailures.length,
+                    findings_verified: deepFailures.filter((f) => f.verified).length,
+                };
+            }
+            catch (error) {
+                Logger.error(`Deep analysis failed: ${error.message}`);
+                summary['deep-analysis'] = 'ERROR';
+                deepStats = { enabled: true };
+            }
+        }
         const status = failures.length > 0 ? 'FAIL' : 'PASS';
         // Severity-weighted scoring: each failure deducts based on its severity
         const severityBreakdown = {};
@@ -180,11 +218,13 @@ export class GateRunner {
         // preventing security criticals from incorrectly zeroing structural_score.
         let aiDeduction = 0;
         let structuralDeduction = 0;
+        let deepDeduction = 0;
         const provenanceCounts = {
             'ai-drift': 0,
             'traditional': 0,
             'security': 0,
             'governance': 0,
+            'deep-analysis': 0,
         };
         for (const f of failures) {
             const sev = (f.severity || 'medium');
@@ -198,6 +238,9 @@ export class GateRunner {
                 case 'traditional':
                     structuralDeduction += weight;
                     break;
+                case 'deep-analysis':
+                    deepDeduction += weight;
+                    break;
                 // security and governance contribute to overall score (totalDeduction)
                 // but do NOT pollute the sub-scores
                 case 'security':
@@ -214,8 +257,10 @@ export class GateRunner {
                 score,
                 ai_health_score: Math.max(0, 100 - aiDeduction),
                 structural_score: Math.max(0, 100 - structuralDeduction),
+                ...(deepOptions?.enabled ? { code_quality_score: Math.max(0, 100 - deepDeduction) } : {}),
                 severity_breakdown: severityBreakdown,
                 provenance_breakdown: provenanceCounts,
+                ...(deepStats ? { deep: deepStats } : {}),
             },
         };
     }

package/dist/index.d.ts

@@ -9,3 +9,13 @@ export { RetryLoopBreakerGate } from './gates/retry-loop-breaker.js';
 export * from './utils/logger.js';
 export * from './services/score-history.js';
 export * from './hooks/index.js';
+export { loadSettings, saveSettings, getSettingsPath, resolveDeepOptions, getProviderKey, getAgentConfig, getCliPreferences, updateProviderKey, removeProviderKey } from './settings.js';
+export type { RigourSettings, ResolvedDeepOptions, CLIDeepOptions } from './settings.js';
+export { DeepAnalysisGate } from './gates/deep-analysis.js';
+export { createProvider } from './inference/index.js';
+export type { InferenceProvider, DeepFinding, DeepAnalysisResult, ModelTier } from './inference/types.js';
+export { MODELS } from './inference/types.js';
+export { isModelCached, getModelsDir, getModelInfo } from './inference/model-manager.js';
+export { extractFacts, factsToPromptString } from './deep/fact-extractor.js';
+export { openDatabase, isSQLiteAvailable, insertScan, insertFindings, getRecentScans, getScoreTrendFromDB, getTopIssues, reinforcePattern, getStrongPatterns } from './storage/index.js';
+export type { RigourDB } from './storage/index.js';

package/dist/index.js

@@ -9,7 +9,17 @@ export { RetryLoopBreakerGate } from './gates/retry-loop-breaker.js';
 export * from './utils/logger.js';
 export * from './services/score-history.js';
 export * from './hooks/index.js';
+// Settings Module (Global user config at ~/.rigour/settings.json)
+export { loadSettings, saveSettings, getSettingsPath, resolveDeepOptions, getProviderKey, getAgentConfig, getCliPreferences, updateProviderKey, removeProviderKey } from './settings.js';
+// Deep Analysis Pipeline (v4.0+)
+export { DeepAnalysisGate } from './gates/deep-analysis.js';
+export { createProvider } from './inference/index.js';
+export { MODELS } from './inference/types.js';
+export { isModelCached, getModelsDir, getModelInfo } from './inference/model-manager.js';
+export { extractFacts, factsToPromptString } from './deep/fact-extractor.js';
+// Storage (SQLite Brain)
+export { openDatabase, isSQLiteAvailable, insertScan, insertFindings, getRecentScans, getScoreTrendFromDB, getTopIssues, reinforcePattern, getStrongPatterns } from './storage/index.js';
 // Pattern Index is intentionally NOT exported here to prevent
-// native dependency issues (sharp/transformers) from leaking into 
-// non-AI parts of the system. 
+// native dependency issues (sharp/transformers) from leaking into
+// non-AI parts of the system.
 // Import from @rigour-labs/core/pattern-index instead.

package/dist/inference/cloud-provider.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Cloud API Provider — runs inference via ANY cloud LLM API.
+ *
+ * The moat is local-first. But if a user brings their own key,
+ * we don't block them. No limitations. Support EVERY provider:
+ *
+ * - 'claude'/'anthropic' → Anthropic SDK (native)
+ * - Everything else → OpenAI-compatible SDK (works with OpenAI, Gemini, Groq,
+ *   Mistral, Together, Fireworks, Perplexity, DeepSeek, self-hosted vLLM,
+ *   Ollama, LM Studio, any OpenAI-compatible endpoint)
+ *
+ * User provides: api_key + provider name + optional base_url + optional model_name
+ * We figure out the rest. Their key, their choice.
+ */
+import type { InferenceProvider, InferenceOptions } from './types.js';
+export declare class CloudProvider implements InferenceProvider {
+    readonly name: string;
+    private client;
+    private providerName;
+    private apiKey;
+    private baseUrl?;
+    private modelName;
+    private isClaude;
+    constructor(providerName: string, apiKey: string, options?: {
+        baseUrl?: string;
+        modelName?: string;
+    });
+    isAvailable(): Promise<boolean>;
+    setup(onProgress?: (message: string) => void): Promise<void>;
+    analyze(prompt: string, options?: InferenceOptions): Promise<string>;
+    private analyzeClaude;
+    private analyzeOpenAICompat;
+    dispose(): void;
+}

package/dist/inference/cloud-provider.js

@@ -0,0 +1,126 @@
+/** Default models per provider (user can override via model_name) */
+const DEFAULT_MODELS = {
+    claude: 'claude-opus-4-6',
+    anthropic: 'claude-sonnet-4-6',
+    openai: 'gpt-4o-mini',
+    gemini: 'gemini-3-flash',
+    groq: 'llama-3.1-70b-versatile',
+    mistral: 'mistral-large-latest',
+    together: 'meta-llama/Llama-3.1-70B-Instruct-Turbo',
+    fireworks: 'accounts/fireworks/models/llama-v3p1-70b-instruct',
+    deepseek: 'deepseek-coder',
+    perplexity: 'llama-3.1-sonar-large-128k-online',
+    ollama: 'qwen2.5-coder:7b',
+    lmstudio: 'qwen2.5-coder-7b-instruct',
+};
+/** Default base URLs per provider */
+const DEFAULT_BASE_URLS = {
+    openai: 'https://api.openai.com/v1',
+    gemini: 'https://generativelanguage.googleapis.com/v1beta/openai',
+    groq: 'https://api.groq.com/openai/v1',
+    mistral: 'https://api.mistral.ai/v1',
+    together: 'https://api.together.xyz/v1',
+    fireworks: 'https://api.fireworks.ai/inference/v1',
+    deepseek: 'https://api.deepseek.com/v1',
+    perplexity: 'https://api.perplexity.ai',
+    ollama: 'http://localhost:11434/v1',
+    lmstudio: 'http://localhost:1234/v1',
+};
+export class CloudProvider {
+    name;
+    client = null;
+    providerName;
+    apiKey;
+    baseUrl;
+    modelName;
+    isClaude;
+    constructor(providerName, apiKey, options) {
+        if (!apiKey || apiKey.trim().length === 0) {
+            throw new Error(`API key cannot be empty for provider "${providerName}"`);
+        }
+        this.providerName = providerName.toLowerCase();
+        this.apiKey = apiKey.trim();
+        this.baseUrl = options?.baseUrl;
+        this.modelName = options?.modelName || DEFAULT_MODELS[this.providerName] || 'gpt-4o-mini';
+        this.isClaude = this.providerName === 'claude' || this.providerName === 'anthropic';
+        this.name = `cloud-${this.providerName}`;
+    }
+    async isAvailable() {
+        return !!this.apiKey;
+    }
+    async setup(onProgress) {
+        if (this.isClaude) {
+            try {
+                const { default: Anthropic } = await import('@anthropic-ai/sdk');
+                this.client = new Anthropic({ apiKey: this.apiKey });
+                onProgress?.(`✓ ${this.providerName} API connected (model: ${this.modelName})`);
+            }
+            catch {
+                throw new Error('Claude API SDK not installed. Run: npm install @anthropic-ai/sdk');
+            }
+        }
+        else {
+            // OpenAI-compatible SDK — works with literally everything.
+            // OpenAI, Groq, Mistral, Together, Fireworks, DeepSeek, Perplexity,
+            // Gemini, Ollama, LM Studio, vLLM, any OpenAI-compatible endpoint.
+            // No limitations. User's key, user's choice.
+            try {
+                const { default: OpenAI } = await import('openai');
+                const baseURL = this.baseUrl || DEFAULT_BASE_URLS[this.providerName] || undefined;
+                this.client = new OpenAI({
+                    apiKey: this.apiKey,
+                    ...(baseURL ? { baseURL } : {}),
+                });
+                onProgress?.(`✓ ${this.providerName} API connected (model: ${this.modelName})`);
+            }
+            catch {
+                throw new Error('OpenAI SDK not installed (used for all OpenAI-compatible APIs). Run: npm install openai');
+            }
+        }
+    }
+    async analyze(prompt, options) {
+        if (!this.client) {
+            throw new Error('Provider not set up. Call setup() first.');
+        }
+        if (this.isClaude) {
+            return this.analyzeClaude(prompt, options);
+        }
+        else {
+            return this.analyzeOpenAICompat(prompt, options);
+        }
+    }
+    async analyzeClaude(prompt, options) {
+        const response = await this.client.messages.create({
+            model: this.modelName,
+            max_tokens: options?.maxTokens || 2048,
+            temperature: options?.temperature || 0.1,
+            messages: [
+                { role: 'user', content: prompt }
+            ],
+        });
+        const textBlock = response.content.find((b) => b.type === 'text');
+        if (!textBlock?.text) {
+            throw new Error(`Empty response from ${this.providerName} API (model: ${this.modelName}). Response had ${response.content.length} blocks but no text.`);
+        }
+        return textBlock.text;
+    }
+    async analyzeOpenAICompat(prompt, options) {
+        const response = await this.client.chat.completions.create({
+            model: this.modelName,
+            max_tokens: options?.maxTokens || 2048,
+            temperature: options?.temperature || 0.1,
+            messages: [
+                { role: 'user', content: prompt }
+            ],
+            ...(options?.jsonMode ? { response_format: { type: 'json_object' } } : {}),
+        });
+        const content = response.choices[0]?.message?.content;
+        if (!content) {
+            throw new Error(`Empty response from ${this.providerName} API (model: ${this.modelName}). No content in choices.`);
+        }
+        return content;
+    }
+    dispose() {
+        this.client = null;
+    }
+}

package/dist/inference/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Inference provider factory and exports.
+ */
+export type { InferenceProvider, InferenceOptions, DeepFinding, DeepAnalysisResult, ModelTier, ModelInfo } from './types.js';
+export { MODELS } from './types.js';
+export { SidecarProvider } from './sidecar-provider.js';
+export { CloudProvider } from './cloud-provider.js';
+export { ensureModel, isModelCached, getModelPath, getModelInfo, downloadModel, getModelsDir } from './model-manager.js';
+import type { InferenceProvider } from './types.js';
+import type { DeepOptions } from '../types/index.js';
+/**
+ * Create the appropriate inference provider based on options.
+ *
+ * - No API key → SidecarProvider (local llama.cpp binary)
+ * - API key + any provider → CloudProvider (no restrictions, user's key, user's choice)
+ */
+export declare function createProvider(options: DeepOptions): InferenceProvider;

package/dist/inference/index.js

@@ -0,0 +1,23 @@
+export { MODELS } from './types.js';
+export { SidecarProvider } from './sidecar-provider.js';
+export { CloudProvider } from './cloud-provider.js';
+export { ensureModel, isModelCached, getModelPath, getModelInfo, downloadModel, getModelsDir } from './model-manager.js';
+import { SidecarProvider } from './sidecar-provider.js';
+import { CloudProvider } from './cloud-provider.js';
+/**
+ * Create the appropriate inference provider based on options.
+ *
+ * - No API key → SidecarProvider (local llama.cpp binary)
+ * - API key + any provider → CloudProvider (no restrictions, user's key, user's choice)
+ */
+export function createProvider(options) {
+    if (options.apiKey && options.provider && options.provider !== 'local') {
+        return new CloudProvider(options.provider, options.apiKey, {
+            baseUrl: options.apiBaseUrl,
+            modelName: options.modelName,
+        });
+    }
+    // Default: local sidecar
+    const tier = options.pro ? 'pro' : 'deep';
+    return new SidecarProvider(tier);
+}