@devilsdev/rag-pipeline-utils 2.4.5 → 2.5.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,44 +1,59 @@
 /**
  * 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.
  */
 
-const { logger } = require("../../utils/logger.js");
+const { loadCliConfig } = require("../shared/config-context.js");
+const { query } = require("../services/rag-service.js");
+
+function printPassages(results) {
+  // A score of 0 means no overlap with the question at all.
+  const matches = results.filter((doc) => !(doc.score <= 0));
+  if (matches.length === 0) {
+    console.log("No matching passages found.");
+    return;
+  }
+  matches.forEach((doc, i) => {
+    const source = doc.metadata?.source || doc.id;
+    const score = typeof doc.score === "number" ? doc.score.toFixed(3) : "-";
+    console.log(`\n[${i + 1}] ${source} (score ${score})`);
+    console.log(doc.content);
+  });
+}
 
 /**
- * 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;
+
     if (globalOptions.dryRun) {
-      console.log("🧪 Dry run: Would execute query");
-      console.log(
-        `Prompt: ${prompt.substring(0, 100)}${prompt.length > 100 ? "..." : ""}`,
-      );
-      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");
-      }
+      console.log(`🧪 Dry run: would query the index for: ${question}`);
       return;
     }
 
-    console.log(
-      `🤔 Processing query: ${prompt.substring(0, 100)}${prompt.length > 100 ? "..." : ""}`,
-    );
-    console.log("\n📝 Response:");
-    console.log("Mock response to query");
+    const result = await query({ config, configDir, question, topK });
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    if (result.answer === null) {
+      console.log("No llm stage configured; showing retrieved passages.");
+    } else {
+      console.log(result.answer);
+      console.log("\nSources:");
+    }
+    printPassages(result.results);
   } catch (error) {
-    logger.error("❌ Query processing failed:", error.message);
-    process.exit(1);
+    console.error(`❌ Query failed: ${error.message}`);
+    process.exitCode = 1;
   }
 }
 

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);
   }
 }
 

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

@@ -0,0 +1,60 @@
+/**
+ * Serve command handler
+ * Runs DevServer: a local HTTP API (GET /health, POST /query) over the
+ * pipeline in .ragrc.json, reloading custom plugin modules on change.
+ */
+
+const path = require("path");
+const { loadCliConfig } = require("../shared/config-context.js");
+
+/**
+ * @param {object} globalOptions - Global CLI options from program.opts()
+ * @param {object} options - { port, host }
+ * @returns {Promise<object|undefined>} The started server (for tests)
+ */
+async function handleServe(globalOptions, options = {}) {
+  try {
+    // Validate the config up front so a broken file fails at startup.
+    const { config, configPath, configDir } = loadCliConfig(globalOptions);
+    const pluginFiles = Object.values(config.plugins || {})
+      .flatMap((group) => Object.values(group || {}))
+      .filter((p) => typeof p === "string")
+      .map((p) => path.resolve(configDir, p));
+
+    const { DevServer } = require("../../dev/dev-server.js");
+    const server = new DevServer({
+      port: options.port,
+      host: options.host,
+      configPath,
+      watchPaths: pluginFiles,
+      verbose: false,
+    });
+    await server.start();
+
+    console.log(`🚀 Serving ${path.basename(configPath)} at ${server.url}`);
+    console.log(`   GET  ${server.url}/health`);
+    console.log(`   POST ${server.url}/query  {"question": "...", "topK": 3}`);
+    if (
+      !["127.0.0.1", "localhost", "::1"].includes(options.host || "127.0.0.1")
+    ) {
+      console.warn(
+        `⚠️  Listening on ${options.host}: the API has no authentication and anyone who can reach this address can query your index.`,
+      );
+    }
+    console.log("Press Ctrl+C to stop.");
+
+    const shutdown = async () => {
+      await server.stop();
+      process.exit(0);
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    return server;
+  } catch (error) {
+    console.error(`❌ Server failed to start: ${error.message}`);
+    process.exitCode = 1;
+    return undefined;
+  }
+}
+
+module.exports = { handleServe };

package/src/cli/services/bench-stats.js

@@ -0,0 +1,54 @@
+"use strict";
+
+/**
+ * Summary statistics for latency samples measured by `rag-pipeline ai
+ * benchmark`. Pure functions so the math can be unit-tested.
+ */
+
+/**
+ * Nearest-rank percentile: the smallest sample such that at least p% of the
+ * samples are less than or equal to it. Always returns an observed value.
+ *
+ * @param {number[]} samples - Unsorted samples (not modified)
+ * @param {number} p - Percentile in (0, 100]
+ * @returns {number}
+ */
+function percentile(samples, p) {
+  if (!Array.isArray(samples) || samples.length === 0) {
+    throw new Error("percentile() needs at least one sample");
+  }
+  if (!(p > 0 && p <= 100)) {
+    throw new Error(`Percentile must be in (0, 100], got ${p}`);
+  }
+  const sorted = [...samples].sort((a, b) => a - b);
+  const rank = Math.ceil((p / 100) * sorted.length);
+  return sorted[rank - 1];
+}
+
+/**
+ * @param {number[]} samples
+ * @returns {number} Arithmetic mean
+ */
+function mean(samples) {
+  if (!Array.isArray(samples) || samples.length === 0) {
+    throw new Error("mean() needs at least one sample");
+  }
+  return samples.reduce((sum, x) => sum + x, 0) / samples.length;
+}
+
+/**
+ * @param {number[]} samples - Latencies in milliseconds
+ * @returns {{count: number, mean: number, p50: number, p95: number, min: number, max: number}}
+ */
+function summarize(samples) {
+  return {
+    count: samples.length,
+    mean: mean(samples),
+    p50: percentile(samples, 50),
+    p95: percentile(samples, 95),
+    min: Math.min(...samples),
+    max: Math.max(...samples),
+  };
+}
+
+module.exports = { percentile, mean, summarize };