@devilsdev/rag-pipeline-utils 2.4.5 → 2.6.0

package/src/cli/handlers/init-handler.js

@@ -1,51 +1,174 @@
 /**
  * Init command handler
- * Handles RAG pipeline configuration initialization
+ * Writes a .ragrc.json whose pipeline names built-in components (or custom
+ * plugins checked by the setup wizard), so the result works with
+ * `ingest` / `query` immediately.
  */
 
 const fs = require("fs/promises");
-const { logger } = require("../../utils/logger.js");
+const { buildInitConfig } = require("../wizard/config-builder.js");
+const { runInitWizard, ask } = require("../wizard/init-wizard.js");
+const {
+  buildComponents: defaultBuildComponents,
+} = require("../../config/component-factory");
+
+/**
+ * Starting points for `init --template <name>`. "local" needs no API keys or
+ * services; it has no llm stage, so `query` prints the retrieved passages.
+ * In interactive mode the template only sets the wizard's defaults.
+ */
+const TEMPLATES = {
+  local: { embedder: "local", llm: null },
+  openai: { embedder: "openai", llm: "openai" },
+  ollama: { embedder: "ollama", llm: "ollama" },
+  anthropic: { embedder: "local", llm: "anthropic" },
+};
+
+/**
+ * inquirer prompt function. With custom streams it uses a prompt module
+ * bound to them (inquirer@8 reads `{input, output}` from createPromptModule,
+ * not from prompt()'s second argument, which holds pre-filled answers).
+ */
+function inquirerPrompt({ input, output } = {}) {
+  const inquirer = require("inquirer");
+  if (!input && !output) return (questions) => inquirer.prompt(questions);
+  const promptModule = inquirer.createPromptModule({ input, output });
+  return (questions) => promptModule(questions);
+}
+
+/** Grace period before the CLI forces an exit after a connection test. */
+const EXIT_GRACE_MS = 1000;
+
+/**
+ * Last-resort exit for `rag-pipeline init` after a connection test ran.
+ *
+ * The test aborts each provider call on timeout (connectors that honour
+ * `options.signal` cancel their request), but a custom plugin or a provider
+ * SDK may still hold a socket or timer open, which would keep the process
+ * alive after "Configuration written". The exit timer is unref'd: when
+ * nothing is left running the process ends normally and the timer never
+ * fires; otherwise it exits with the current exit code after the grace
+ * period. Only the CLI command calls this, never the handler itself.
+ *
+ * @param {{connectionTested?: boolean}|undefined} result - handleInit result
+ * @param {object} [options]
+ * @param {number} [options.graceMs=1000]
+ * @param {Function} [options.exit=process.exit]
+ * @returns {NodeJS.Timeout|null} The scheduled timer, or null
+ */
+function exitAfterConnectionTest(result, options = {}) {
+  if (!result || !result.connectionTested) return null;
+  const { graceMs = EXIT_GRACE_MS, exit = (code) => process.exit(code) } =
+    options;
+  const timer = setTimeout(() => exit(process.exitCode ?? 0), graceMs);
+  if (typeof timer.unref === "function") timer.unref();
+  return timer;
+}
 
 /**
  * Handle init command
  * @param {object} globalOptions - Global CLI options from program.opts()
  * @param {object} options - Command-specific options
- * @param {Function} createBasicConfigFn - Function to create basic config
+ * @param {object} [deps] - Injectable dependencies for tests
+ * @param {Function} [deps.prompt] - inquirer-style prompt([question]) => answers
+ * @param {object} [deps.env] - Environment for the API key check
+ * @param {Function} [deps.buildComponents] - Used by the connection test
+ * @param {Function} [deps.log] - Wizard output (console.log)
+ * @param {number} [deps.timeoutMs] - Connection test timeout
+ * @param {import("stream").Readable} [deps.input] - Prompt input (process.stdin)
+ * @param {import("stream").Writable} [deps.output] - Prompt output (process.stdout)
+ * @returns {Promise<{written: boolean, connectionTested: boolean}>}
+ *   connectionTested is true when the connection test built a provider
  */
-async function handleInit(globalOptions, options, createBasicConfigFn) {
+async function handleInit(globalOptions, options, deps = {}) {
+  const outcome = { written: false, connectionTested: false };
   try {
+    const templateName = options.template || "local";
+    const template = TEMPLATES[templateName];
+    if (!template) {
+      throw new Error(
+        `Unknown template "${templateName}". Available: ${Object.keys(TEMPLATES).join(", ")}`,
+      );
+    }
+
+    // commander sets options.interactive=false for --no-interactive; only
+    // prompt when a person is at the terminal.
+    const interactive =
+      options.interactive !== false &&
+      Boolean((deps.input || process.stdin).isTTY);
+
     if (globalOptions.dryRun) {
-      console.log("🧪 Dry run: Would initialize RAG pipeline configuration");
+      console.log("🧪 Dry run: would write configuration");
       console.log(`Output file: ${options.output}`);
-      console.log(`Interactive mode: ${!options.noInteractive}`);
-      return;
+      console.log(`Template: ${templateName}`);
+      console.log(`Interactive: ${interactive}`);
+      return outcome;
     }
 
-    // Check if config already exists
-    if (!options.force) {
-      try {
-        await fs.access(options.output);
-        console.log(`❌ Configuration file already exists: ${options.output}`);
-        console.log(
-          "Use --force to overwrite or choose a different output path.",
+    const prompt =
+      deps.prompt || inquirerPrompt({ input: deps.input, output: deps.output });
+    const exists = await fs
+      .access(options.output)
+      .then(() => true)
+      .catch(() => false);
+    if (exists && !options.force) {
+      if (!interactive) {
+        throw new Error(
+          `Configuration file already exists: ${options.output}. Use --force to overwrite.`,
         );
-        return;
-      } catch (error) {
-        // File doesn't exist, which is good
+      }
+      const overwrite = await ask(prompt, {
+        type: "confirm",
+        name: "overwrite",
+        message: `${options.output} already exists. Replace it?`,
+        default: false,
+      });
+      if (!overwrite) {
+        console.log("Nothing written.");
+        return outcome;
       }
     }
 
-    if (!options.noInteractive) {
-      console.log("🧙‍♂️ Starting interactive configuration wizard...\n");
-      // Mock interactive wizard
-      await createBasicConfigFn(options.output);
+    let config;
+    if (interactive) {
+      const result = await runInitWizard({
+        prompt,
+        defaults: template,
+        outputPath: options.output,
+        overwrite: exists,
+        env: deps.env || process.env,
+        // Only the connection test builds components; note that it did, so
+        // the CLI can make sure no provider request keeps the process alive.
+        buildComponents: (...args) => {
+          outcome.connectionTested = true;
+          return (deps.buildComponents || defaultBuildComponents)(...args);
+        },
+        log: deps.log || console.log,
+        timeoutMs: deps.timeoutMs,
+      });
+      if (!result) {
+        console.log("Nothing written.");
+        return outcome;
+      }
+      config = result.config;
     } else {
-      await createBasicConfigFn(options.output);
+      config = buildInitConfig(template);
     }
+
+    await fs.writeFile(options.output, JSON.stringify(config, null, 2) + "\n");
+    console.log(`✅ Configuration written: ${options.output}`);
+    console.log("Next: rag-pipeline ingest <file-or-directory>");
+    outcome.written = true;
   } catch (error) {
-    logger.error("❌ Initialization failed:", error.message);
-    process.exit(1);
+    console.error(`❌ Initialization failed: ${error.message}`);
+    process.exitCode = 1;
   }
+  return outcome;
 }
 
-module.exports = { handleInit };
+module.exports = {
+  handleInit,
+  exitAfterConnectionTest,
+  buildInitConfig,
+  TEMPLATES,
+};

package/src/cli/handlers/query-handler.js

@@ -1,45 +1,223 @@
 /**
  * Query command handler
- * Handles RAG pipeline queries
+ * Answers a question from the ingested index. Without an llm stage it prints
+ * the retrieved passages instead of an answer.
+ *
+ * Options: --top-k, --json, --streaming, --timeout, --trace (per-stage
+ * timings), --explain (passage scores and the passages supporting each
+ * answer sentence), --stats (latency, estimated tokens and cost). The global
+ * --quiet prints only the answer or the passages.
  */
 
-const { logger } = require("../../utils/logger.js");
+const { loadCliConfig } = require("../shared/config-context.js");
+const { query } = require("../services/rag-service.js");
+const { CostCalculator } = require("../../cost/cost-calculator.js");
+
+const STAGES = ["embed", "retrieve", "rerank", "generate"];
+
+function sourceLabel(doc) {
+  return doc.metadata?.source || doc.id;
+}
+
+function printPassages(results, { quiet } = {}) {
+  // A score of 0 means no overlap with the question at all.
+  const matches = results.filter((doc) => !(doc.score <= 0));
+  if (matches.length === 0) {
+    if (!quiet) console.log("No matching passages found.");
+    return;
+  }
+  matches.forEach((doc, i) => {
+    const score = typeof doc.score === "number" ? doc.score.toFixed(3) : "-";
+    console.log(`\n[${i + 1}] ${sourceLabel(doc)} (score ${score})`);
+    console.log(doc.content);
+  });
+}
+
+/** Sum the recorded timings per stage. */
+function stageTimings(timings) {
+  const totals = {};
+  for (const { stage, ms } of timings)
+    totals[stage] = (totals[stage] || 0) + ms;
+  return totals;
+}
+
+function printTrace(result) {
+  const totals = stageTimings(result.timings);
+  console.log("\nTrace");
+  for (const stage of STAGES) {
+    const ms = totals[stage];
+    console.log(
+      `  ${stage.padEnd(9)} ${ms === undefined ? "-" : `${ms.toFixed(1)} ms`}`,
+    );
+  }
+  console.log(`  ${"total".padEnd(9)} ${result.durationMs.toFixed(1)} ms`);
+}
+
+/** Rough token count: about 4 characters per token for English text. */
+const estimateTokens = (text) => Math.ceil(String(text || "").length / 4);
+
+function computeStats(result, question, llmModel) {
+  const context = result.results.map((d) => d.content || "").join("\n");
+  const stats = {
+    durationMs: Math.round(result.durationMs),
+    passages: result.results.length,
+    answerChars: result.answer ? result.answer.length : 0,
+  };
+  if (result.answer !== null) {
+    stats.estimatedInputTokens = estimateTokens(`${question}\n${context}`);
+    stats.estimatedOutputTokens = estimateTokens(result.answer);
+    const calculator = new CostCalculator();
+    // Only price models in the table; unknown models would print a warning.
+    if (llmModel && calculator.getModelPricing(llmModel)) {
+      const cost = calculator.estimate(
+        llmModel,
+        stats.estimatedInputTokens,
+        stats.estimatedOutputTokens,
+      );
+      stats.estimatedCostUsd = Number(cost.totalCost.toFixed(6));
+      stats.model = cost.model;
+    }
+  }
+  return stats;
+}
+
+function printStats(stats) {
+  console.log("\nStats");
+  console.log(`  latency   ${stats.durationMs} ms`);
+  console.log(`  passages  ${stats.passages}`);
+  if (stats.estimatedInputTokens !== undefined) {
+    console.log(
+      `  tokens    ~${stats.estimatedInputTokens} in, ~${stats.estimatedOutputTokens} out (estimated)`,
+    );
+  }
+  if (stats.estimatedCostUsd !== undefined) {
+    console.log(
+      `  cost      ~$${stats.estimatedCostUsd} (${stats.model}, estimated)`,
+    );
+  }
+}
+
+/** Passage rank and score, and the passages that support each sentence. */
+function explanation(result) {
+  const passages = result.results.map((doc, i) => ({
+    rank: i + 1,
+    source: sourceLabel(doc),
+    score: typeof doc.score === "number" ? doc.score : null,
+  }));
+  if (!result.citations) return { passages };
+  const rankOf = new Map(result.results.map((d, i) => [String(d.id), i + 1]));
+  const sentences = (result.citations.citations || []).map((c) => ({
+    sentence: c.sentence,
+    supportedBy: (c.sources || []).map((s) => ({
+      rank: rankOf.get(String(s.docId)) ?? s.docIndex + 1,
+      source: sourceLabel(result.results[s.docIndex] || { id: s.docId }),
+      support: s.score,
+    })),
+  }));
+  return {
+    passages,
+    sentences,
+    groundedness: result.citations.groundednessScore,
+  };
+}
+
+function printExplanation(explained) {
+  console.log("\nExplanation");
+  console.log("  Passages, in ranked order:");
+  for (const p of explained.passages) {
+    const score = p.score === null ? "-" : p.score.toFixed(3);
+    console.log(`    [${p.rank}] ${p.source}  score ${score}`);
+  }
+  if (!explained.sentences) return;
+  console.log("  Answer sentences:");
+  for (const s of explained.sentences) {
+    const support = s.supportedBy.length
+      ? s.supportedBy
+          .map((p) => `[${p.rank}] ${p.source} (${p.support.toFixed(2)})`)
+          .join(", ")
+      : "not supported by any passage";
+    console.log(`    "${s.sentence}"`);
+    console.log(`      -> ${support}`);
+  }
+  console.log(`  Groundedness: ${explained.groundedness.toFixed(2)}`);
+}
 
 /**
- * Handle query command
  * @param {object} globalOptions - Global CLI options from program.opts()
- * @param {string} prompt - Query prompt
+ * @param {string} question - Query text
  * @param {object} options - Command-specific options
  */
-async function handleQuery(globalOptions, prompt, options) {
+async function handleQuery(globalOptions, question, options = {}) {
   try {
+    const { config, configDir } = loadCliConfig(globalOptions);
+    const topK = options.topK || 3;
+    const quiet = Boolean(globalOptions.quiet);
+
     if (globalOptions.dryRun) {
-      console.log("🧪 Dry run: Would execute query");
+      console.log(`🧪 Dry run: would query the index for: ${question}`);
+      return;
+    }
+
+    const hasLlm = (config.pipeline || []).some((s) => s.stage === "llm");
+    const streaming = Boolean(options.streaming && hasLlm && !options.json);
+    if (options.streaming && !hasLlm && !quiet && !options.json) {
+      console.log("--streaming needs an llm stage; showing passages instead.");
+    }
+
+    const result = await query({
+      config,
+      configDir,
+      question,
+      topK,
+      timeout: options.timeout,
+      ...(streaming && { onToken: (t) => process.stdout.write(t) }),
+    });
+
+    const llmStage = (config.pipeline || []).find((s) => s.stage === "llm");
+    const stats = options.stats
+      ? computeStats(result, question, llmStage?.config?.model)
+      : undefined;
+    const explained = options.explain ? explanation(result) : undefined;
+
+    if (options.json) {
+      const { timings, durationMs, ...rest } = result;
       console.log(
-        `Prompt: ${prompt.substring(0, 100)}${prompt.length > 100 ? "..." : ""}`,
+        JSON.stringify(
+          {
+            ...rest,
+            ...(options.trace && {
+              trace: { stages: stageTimings(timings), totalMs: durationMs },
+            }),
+            ...(stats && { stats }),
+            ...(explained && { explanation: explained }),
+          },
+          null,
+          2,
+        ),
       );
-      console.log(`Streaming: ${options.stream ? "enabled" : "disabled"}`);
-
-      if (options.explain) {
-        console.log("🔍 Query Explanation:");
-        console.log("Processing steps:");
-        console.log("  1. Text embedding generation");
-        console.log("  2. Vector similarity search");
-        console.log("  3. Context retrieval");
-        console.log("  4. Language model generation");
-      }
       return;
     }
 
-    console.log(
-      `🤔 Processing query: ${prompt.substring(0, 100)}${prompt.length > 100 ? "..." : ""}`,
-    );
-    console.log("\n📝 Response:");
-    console.log("Mock response to query");
+    if (result.answer === null) {
+      if (!quiet)
+        console.log("No llm stage configured; showing retrieved passages.");
+      printPassages(result.results, { quiet });
+    } else {
+      if (streaming) process.stdout.write("\n");
+      else console.log(result.answer);
+      if (!quiet) {
+        console.log("\nSources:");
+        printPassages(result.results);
+      }
+    }
+
+    if (options.explain) printExplanation(explained);
+    if (options.trace) printTrace(result);
+    if (options.stats) printStats(stats);
   } catch (error) {
-    logger.error("❌ Query processing failed:", error.message);
-    process.exit(1);
+    console.error(`❌ Query failed: ${error.message}`);
+    process.exitCode = 1;
   }
 }
 
-module.exports = { handleQuery };
+module.exports = { handleQuery, explanation, computeStats };

package/src/cli/handlers/run-handler.js

@@ -1,180 +1,29 @@
 /**
  * Run command handler
- * Handles pipeline execution with streaming, abort, and progress support
+ * Convenience wrapper: optionally ingest, then optionally query, in one call.
  */
 
-const { logger } = require("../../utils/logger.js");
-const { createProgressBar } = require("../shared/cli-utils.js");
+const { handleIngest } = require("./ingest-handler.js");
+const { handleQuery } = require("./query-handler.js");
 
 /**
- * Handle run command
  * @param {object} globalOptions - Global CLI options from program.opts()
- * @param {object} options - Command-specific options
+ * @param {object} options - { ingest?: string, query?: string, topK?: number, json?: boolean }
  */
-async function handleRun(globalOptions, options) {
-  if (globalOptions.dryRun) {
-    logger.info("🧪 Dry run: Would execute pipeline operation");
-    if (options.ingest) logger.info(`Would ingest: ${options.ingest}`);
-    if (options.query)
-      logger.info(`Would query: ${options.query.substring(0, 100)}...`);
-    logger.info(`Streaming: ${options.stream ? "enabled" : "disabled"}`);
-    logger.info(`Parallel: ${options.parallel ? "enabled" : "disabled"}`);
-    if (options.abortTimeout)
-      logger.info(`Abort timeout: ${options.abortTimeout}ms`);
+async function handleRun(globalOptions, options = {}) {
+  if (!options.ingest && !options.query) {
+    console.error(
+      "❌ Nothing to do: pass --ingest <path> and/or --query <text>",
+    );
+    process.exitCode = 1;
     return;
   }
-
-  try {
-    // Load configuration
-    const { loadRagConfig } = require("../../config/load-config.js");
-    const config = await loadRagConfig(globalOptions.config);
-
-    // Create AbortController for timeout handling
-    const abortController = new AbortController();
-    let timeoutId;
-
-    if (options.abortTimeout) {
-      timeoutId = setTimeout(() => {
-        logger.warn(
-          `Operation aborted after ${options.abortTimeout}ms timeout`,
-        );
-        abortController.abort();
-      }, options.abortTimeout);
-    }
-
-    // Setup SIGINT handling for clean shutdown
-    const sigintHandler = () => {
-      logger.info("Received SIGINT, aborting operation...");
-      abortController.abort();
-      if (timeoutId) clearTimeout(timeoutId);
-    };
-    process.once("SIGINT", sigintHandler);
-
-    try {
-      // Create pipeline with performance options
-      const { createRagPipeline } = require("../../core/create-pipeline.js");
-      const pipeline = createRagPipeline(config.pipeline[0], {
-        useParallelProcessing: options.parallel,
-        useStreamingSafeguards: options.stream,
-        useLogging: true,
-        useRetry: true,
-      });
-
-      // Execute operation based on options
-      if (options.ingest) {
-        logger.info(`Starting ingestion of: ${options.ingest}`);
-
-        if (options.stream) {
-          let lastProgressTime = Date.now();
-          for await (const progress of pipeline.ingestStream(options.ingest)) {
-            if (abortController.signal.aborted) {
-              logger.info("Ingestion aborted");
-              break;
-            }
-
-            const now = Date.now();
-            if (progress.type === "chunk_processed") {
-              // Show progress ticks every 500ms or every 10 chunks
-              if (
-                now - lastProgressTime > 500 ||
-                progress.progress.processed % 10 === 0
-              ) {
-                const percentage = Math.round(
-                  (progress.progress.processed / progress.progress.total) * 100,
-                );
-                const progressBar = createProgressBar(percentage, 20);
-                process.stdout.write(
-                  `\r${progressBar} ${percentage}% (${progress.progress.processed}/${progress.progress.total}) `,
-                );
-                lastProgressTime = now;
-              }
-            } else if (progress.type === "ingest_complete") {
-              process.stdout.write("\n");
-              logger.info(
-                `✅ Ingestion complete: ${progress.summary.processedChunks}/${progress.summary.totalChunks} chunks processed`,
-              );
-              if (progress.summary.failedChunks > 0) {
-                logger.warn(
-                  `⚠️  ${progress.summary.failedChunks} chunks failed`,
-                );
-              }
-            } else if (progress.type === "chunk_failed") {
-              process.stdout.write("✗");
-            }
-          }
-        } else {
-          // Non-streaming ingestion with progress callback
-          let currentStage = "";
-          const progressCallback = (progress) => {
-            if (progress.stage !== currentStage) {
-              if (currentStage) process.stdout.write("\n");
-              currentStage = progress.stage;
-              logger.info(
-                `${progress.stage}: ${progress.message || "Processing..."}`,
-              );
-            }
-            if (
-              progress.completed !== undefined &&
-              progress.total !== undefined
-            ) {
-              const percentage = Math.round(
-                (progress.completed / progress.total) * 100,
-              );
-              const progressBar = createProgressBar(percentage, 20);
-              process.stdout.write(
-                `\r${progressBar} ${percentage}% (${progress.completed}/${progress.total}) `,
-              );
-            }
-          };
-
-          const pipelineWithProgress = createRagPipeline(config.pipeline[0], {
-            useParallelProcessing: options.parallel,
-            useStreamingSafeguards: false,
-            useLogging: true,
-            useRetry: true,
-            onProgress: progressCallback,
-          });
-
-          await pipelineWithProgress.ingest(options.ingest);
-          process.stdout.write("\n");
-          logger.info("✅ Ingestion completed successfully");
-        }
-      }
-
-      if (options.query) {
-        logger.info(`Executing query: ${options.query.substring(0, 100)}...`);
-
-        if (options.stream) {
-          process.stdout.write("\nResponse: ");
-          for await (const token of pipeline.queryStream(options.query)) {
-            if (abortController.signal.aborted) {
-              logger.info("\nQuery aborted");
-              break;
-            }
-            process.stdout.write(token);
-          }
-          process.stdout.write("\n\n");
-        } else {
-          const response = await pipeline.query(options.query);
-          logger.info("Query completed successfully");
-          console.log("\nResponse:", response);
-        }
-      }
-
-      if (!options.ingest && !options.query) {
-        logger.error(
-          "No operation specified. Use --ingest <file> or --query <prompt>",
-        );
-        process.exit(1);
-      }
-    } finally {
-      // Cleanup
-      process.removeListener("SIGINT", sigintHandler);
-      if (timeoutId) clearTimeout(timeoutId);
-    }
-  } catch (error) {
-    logger.error("Pipeline operation failed", { error: error.message });
-    process.exit(1);
+  if (options.ingest) {
+    await handleIngest(globalOptions, options.ingest, options);
+    if (process.exitCode) return;
+  }
+  if (options.query) {
+    await handleQuery(globalOptions, options.query, options);
   }
 }