@bndynet/ragbox 0.1.0 → 0.1.1

package/dist/src/folder-index/config.js

@@ -25,11 +25,18 @@ function parseExtraArgs(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed.split(/\s+/) : undefined;
 }
+function parsePageIndexRunner(value) {
+    if (value === "auto" || value === "single" || value === "batch") {
+        return value;
+    }
+    return undefined;
+}
 function loadPageIndexConfig(overrides = {}) {
     const env = overrides.env ?? process.env;
     return {
         pythonPath: overrides.pythonPath ?? env.PAGEINDEX_PYTHON ?? "python3",
         cliPath: overrides.cliPath ?? env.PAGEINDEX_CLI,
+        pageIndexRunner: overrides.pageIndexRunner ?? parsePageIndexRunner(env.PAGEINDEX_RUNNER) ?? "auto",
         model: overrides.model ?? env.PAGEINDEX_MODEL ?? env.LLM_MODEL ?? "gpt-4o-mini",
         baseUrl: overrides.baseUrl ?? env.OPENAI_BASE_URL ?? "https://api.openai.com/v1",
         apiKey: overrides.apiKey ?? env.OPENAI_API_KEY,

package/dist/src/folder-index/indexer.js

@@ -73,7 +73,7 @@ async function indexFolder(folder, options = {}) {
     });
     await promises_1.default.mkdir(node_path_1.default.join(outputDir, manifest_1.INDEXES_DIR), { recursive: true });
     await (0, manifest_1.removeDeletedIndexFiles)(rootDir, diff.deleted, config.outputDir);
-    const indexedRecords = await (0, queue_1.runWithConcurrency)(toIndex, config.concurrency, async (scannedFile, index) => {
+    async function indexOne(scannedFile, index) {
         const absoluteOutputPath = (0, manifest_1.resolveDocumentIndexPath)(rootDir, scannedFile.indexPath, config.outputDir);
         const progressIndex = index + 1;
         const progressTotal = toIndex.length;
@@ -105,7 +105,53 @@ async function indexFolder(folder, options = {}) {
                 error: errorMessage(error)
             });
         }
-    });
+    }
+    async function indexBatch() {
+        const outputPaths = toIndex.map((scannedFile) => (0, manifest_1.resolveDocumentIndexPath)(rootDir, scannedFile.indexPath, config.outputDir));
+        const results = await (0, pageindex_runner_1.runPageIndexBatchPool)(toIndex.map((scannedFile, index) => ({
+            inputPath: scannedFile.absolutePath,
+            outputPath: outputPaths[index]
+        })), config, {
+            onJobStart: (_job, index) => {
+                reportProgress(config, { type: "index-start", path: toIndex[index].path, index: index + 1, total: toIndex.length });
+            }
+        });
+        const records = [];
+        for (let index = 0; index < toIndex.length; index += 1) {
+            const scannedFile = toIndex[index];
+            const result = results[index];
+            if (result.ok) {
+                const summary = await (0, pageindex_runner_1.readPageIndexSummary)(outputPaths[index]);
+                reportProgress(config, {
+                    type: "index-done",
+                    path: scannedFile.path,
+                    index: index + 1,
+                    total: toIndex.length,
+                    summary
+                });
+                records.push((0, manifest_1.recordFromScannedFile)(scannedFile, { status: "ready", summary }));
+            }
+            else {
+                const previous = previousByPath.get(scannedFile.path);
+                reportProgress(config, {
+                    type: "index-failed",
+                    path: scannedFile.path,
+                    index: index + 1,
+                    total: toIndex.length,
+                    error: result.error
+                });
+                records.push((0, manifest_1.recordFromScannedFile)(scannedFile, {
+                    status: "failed",
+                    summary: previous?.summary,
+                    error: result.error
+                }));
+            }
+        }
+        return records;
+    }
+    const indexedRecords = config.pageIndexRunner === "single" || toIndex.length < 2
+        ? await (0, queue_1.runWithConcurrency)(toIndex, config.concurrency, indexOne)
+        : await indexBatch();
     const indexedByPath = new Map(indexedRecords.map((record) => [record.path, record]));
     const documents = [];
     for (const scannedFile of scannedFiles) {

package/dist/src/folder-index/pageindex-runner.d.ts

@@ -1,3 +1,18 @@
 import { PageIndexOptions } from "./types";
+export type PageIndexBatchJob = {
+    inputPath: string;
+    outputPath: string;
+};
+export type PageIndexBatchResult = (PageIndexBatchJob & {
+    ok: true;
+}) | (PageIndexBatchJob & {
+    ok: false;
+    error: string;
+});
+type PageIndexBatchCallbacks = {
+    onJobStart?: (job: PageIndexBatchJob, index: number) => void;
+};
+export declare function runPageIndexBatchPool(jobs: PageIndexBatchJob[], options?: PageIndexOptions, callbacks?: PageIndexBatchCallbacks): Promise<PageIndexBatchResult[]>;
 export declare function runPageIndex(inputPath: string, outputPath: string, options?: PageIndexOptions): Promise<void>;
 export declare function readPageIndexSummary(indexPath: string): Promise<string | undefined>;
+export {};

package/dist/src/folder-index/pageindex-runner.js

@@ -3,17 +3,78 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPageIndexBatchPool = runPageIndexBatchPool;
 exports.runPageIndex = runPageIndex;
 exports.readPageIndexSummary = readPageIndexSummary;
 const node_child_process_1 = require("node:child_process");
 const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
+const node_readline_1 = __importDefault(require("node:readline"));
 const config_1 = require("./config");
 const path_utils_1 = require("./path-utils");
 const MAX_CAPTURED_OUTPUT = 64 * 1024;
 const DEFAULT_MARKDOWN_ARGS = ["--if-add-node-text", "yes", "--if-add-node-id", "yes"];
 const unsupportedOutputArgs = new Set();
+const BATCH_WORKER_CODE = String.raw `
+import asyncio
+import json
+import os
+import sys
+import traceback
+
+_protocol_stdout = sys.stdout
+sys.stdout = sys.stderr
+
+def send(message):
+    _protocol_stdout.write(json.dumps(message, ensure_ascii=False) + "\n")
+    _protocol_stdout.flush()
+
+try:
+    from pageindex.page_index_md import md_to_tree
+    from pageindex.utils import ConfigLoader
+except Exception:
+    send({"type": "startup-error", "error": traceback.format_exc()})
+    raise SystemExit(0)
+
+send({"type": "ready"})
+
+for line in sys.stdin:
+    request = {}
+    try:
+        request = json.loads(line)
+        if request.get("type") == "stop":
+            break
+        request_id = request["id"]
+        user_opt = {
+            "model": request.get("model"),
+            "if_add_node_summary": request.get("ifAddNodeSummary"),
+            "if_add_doc_description": request.get("ifAddDocDescription"),
+            "if_add_node_text": request.get("ifAddNodeText"),
+            "if_add_node_id": request.get("ifAddNodeId"),
+        }
+        opt = ConfigLoader().load(user_opt)
+        tree = asyncio.run(md_to_tree(
+            md_path=request["inputPath"],
+            if_thinning=bool(request.get("ifThinning", False)),
+            min_token_threshold=int(request.get("thinningThreshold", 5000)),
+            if_add_node_summary=opt.if_add_node_summary,
+            summary_token_threshold=int(request.get("summaryTokenThreshold", 200)),
+            model=opt.model,
+            if_add_doc_description=opt.if_add_doc_description,
+            if_add_node_text=opt.if_add_node_text,
+            if_add_node_id=opt.if_add_node_id,
+        ))
+        output_path = request["outputPath"]
+        output_dir = os.path.dirname(output_path)
+        if output_dir:
+            os.makedirs(output_dir, exist_ok=True)
+        with open(output_path, "w", encoding="utf-8") as f:
+            json.dump(tree, f, indent=2, ensure_ascii=False)
+        send({"type": "done", "id": request_id})
+    except Exception:
+        send({"type": "error", "id": request.get("id"), "error": traceback.format_exc()})
+`;
 class PageIndexRunError extends Error {
     stdout;
     stderr;
@@ -27,11 +88,264 @@ function appendCapturedOutput(current, chunk) {
     const next = current + chunk.toString("utf8");
     return next.length > MAX_CAPTURED_OUTPUT ? next.slice(-MAX_CAPTURED_OUTPUT) : next;
 }
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function pageIndexRunError(code, stdout, stderr) {
     const trimmedStdout = stdout.trim();
     const trimmedStderr = stderr.trim();
     return new PageIndexRunError(`PageIndex failed with exit code ${code ?? "unknown"}\nSTDOUT:\n${trimmedStdout}\nSTDERR:\n${trimmedStderr}`, trimmedStdout, trimmedStderr);
 }
+function parseIntegerArg(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function parseBatchMarkdownArgs(extraArgs) {
+    const args = {
+        ifAddNodeId: "yes",
+        ifAddNodeText: "yes",
+        ifThinning: false,
+        summaryTokenThreshold: 200,
+        thinningThreshold: 5000
+    };
+    const unsupported = [];
+    const values = extraArgs ?? [];
+    for (let index = 0; index < values.length; index += 1) {
+        const key = values[index];
+        const value = values[index + 1];
+        switch (key) {
+            case "--if-thinning":
+                if (value === undefined) {
+                    unsupported.push(key);
+                    break;
+                }
+                args.ifThinning = value.toLowerCase() === "yes" || value.toLowerCase() === "true" || value === "1";
+                index += 1;
+                break;
+            case "--thinning-threshold": {
+                const parsed = parseIntegerArg(value);
+                if (parsed === undefined) {
+                    unsupported.push(key);
+                    break;
+                }
+                args.thinningThreshold = parsed;
+                index += 1;
+                break;
+            }
+            case "--summary-token-threshold": {
+                const parsed = parseIntegerArg(value);
+                if (parsed === undefined) {
+                    unsupported.push(key);
+                    break;
+                }
+                args.summaryTokenThreshold = parsed;
+                index += 1;
+                break;
+            }
+            case "--if-add-node-summary":
+                if (value === undefined) {
+                    unsupported.push(key);
+                    break;
+                }
+                args.ifAddNodeSummary = value;
+                index += 1;
+                break;
+            case "--if-add-doc-description":
+                if (value === undefined) {
+                    unsupported.push(key);
+                    break;
+                }
+                args.ifAddDocDescription = value;
+                index += 1;
+                break;
+            case "--if-add-node-text":
+                if (value === undefined) {
+                    unsupported.push(key);
+                    break;
+                }
+                args.ifAddNodeText = value;
+                index += 1;
+                break;
+            case "--if-add-node-id":
+                if (value === undefined) {
+                    unsupported.push(key);
+                    break;
+                }
+                args.ifAddNodeId = value;
+                index += 1;
+                break;
+            default:
+                unsupported.push(key);
+                break;
+        }
+    }
+    return { args, unsupported };
+}
+function workerEnv(config, cliDir) {
+    const env = {
+        ...process.env,
+        ...config.env,
+        OPENAI_BASE_URL: config.baseUrl,
+        OPENAI_API_KEY: config.apiKey ?? process.env.OPENAI_API_KEY ?? ""
+    };
+    const pythonPath = [cliDir, env.PYTHONPATH].filter((value) => Boolean(value)).join(node_path_1.default.delimiter);
+    return {
+        ...env,
+        PYTHONPATH: pythonPath
+    };
+}
+class PageIndexBatchWorker {
+    workerId;
+    config;
+    cliDir;
+    cwd;
+    child;
+    closed = false;
+    closedPromise;
+    nextId = 1;
+    pending = new Map();
+    stderr = "";
+    constructor(workerId, config, cliDir, cwd) {
+        this.workerId = workerId;
+        this.config = config;
+        this.cliDir = cliDir;
+        this.cwd = cwd;
+    }
+    async start() {
+        await promises_1.default.mkdir(this.cwd, { recursive: true });
+        const child = (0, node_child_process_1.spawn)(this.config.pythonPath, ["-u", "-c", BATCH_WORKER_CODE], {
+            cwd: this.cwd,
+            env: workerEnv(this.config, this.cliDir)
+        });
+        this.child = child;
+        this.closedPromise = new Promise((resolve) => {
+            child.on("close", () => resolve());
+        });
+        child.stderr.on("data", (chunk) => {
+            this.stderr = appendCapturedOutput(this.stderr, chunk);
+        });
+        return await new Promise((resolve, reject) => {
+            let readySettled = false;
+            const reader = node_readline_1.default.createInterface({ input: child.stdout });
+            const settleReady = (error) => {
+                if (readySettled) {
+                    return;
+                }
+                readySettled = true;
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            };
+            reader.on("line", (line) => {
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    this.stderr = appendCapturedOutput(this.stderr, Buffer.from(`${line}\n`, "utf8"));
+                    return;
+                }
+                if (message.type === "ready") {
+                    settleReady();
+                    return;
+                }
+                if (message.type === "startup-error") {
+                    settleReady(new Error(typeof message.error === "string" ? message.error : "PageIndex worker failed to start"));
+                    return;
+                }
+                const id = typeof message.id === "number" ? message.id : undefined;
+                const pending = id === undefined ? undefined : this.pending.get(id);
+                if (!pending) {
+                    return;
+                }
+                this.pending.delete(id);
+                if (message.type === "done") {
+                    pending.resolve({ ok: true });
+                    return;
+                }
+                pending.resolve({
+                    ok: false,
+                    error: typeof message.error === "string" ? message.error : "PageIndex worker returned an unknown error"
+                });
+            });
+            child.on("error", (error) => {
+                settleReady(error);
+                this.rejectPending(error);
+            });
+            child.on("close", (code) => {
+                this.closed = true;
+                const error = new Error(`PageIndex worker ${this.workerId} exited with code ${code ?? "unknown"}${this.stderr.trim() ? `\n${this.stderr.trim()}` : ""}`);
+                settleReady(error);
+                this.rejectPending(error);
+            });
+        });
+    }
+    async run(job, markdownArgs) {
+        if (!this.child || this.closed) {
+            throw new Error(`PageIndex worker ${this.workerId} is not running`);
+        }
+        const id = this.nextId;
+        this.nextId += 1;
+        return await new Promise((resolve, reject) => {
+            this.pending.set(id, { reject, resolve });
+            const payload = {
+                type: "run",
+                id,
+                inputPath: job.inputPath,
+                outputPath: job.outputPath,
+                model: this.config.model,
+                ifAddDocDescription: markdownArgs.ifAddDocDescription,
+                ifAddNodeId: markdownArgs.ifAddNodeId,
+                ifAddNodeSummary: markdownArgs.ifAddNodeSummary,
+                ifAddNodeText: markdownArgs.ifAddNodeText,
+                ifThinning: markdownArgs.ifThinning,
+                summaryTokenThreshold: markdownArgs.summaryTokenThreshold,
+                thinningThreshold: markdownArgs.thinningThreshold
+            };
+            this.child?.stdin.write(`${JSON.stringify(payload)}\n`, (error) => {
+                if (error) {
+                    this.pending.delete(id);
+                    reject(error);
+                }
+            });
+        });
+    }
+    async stop() {
+        if (!this.child || this.closed) {
+            return;
+        }
+        try {
+            this.child.stdin.write(`${JSON.stringify({ type: "stop" })}\n`);
+            this.child.stdin.end();
+        }
+        catch {
+            // Closing a failed worker is best-effort.
+        }
+        await Promise.race([
+            this.closedPromise,
+            new Promise((resolve) => {
+                setTimeout(() => {
+                    if (this.child && !this.closed) {
+                        this.child.kill();
+                    }
+                    resolve();
+                }, 1000);
+            })
+        ]);
+    }
+    rejectPending(error) {
+        for (const pending of this.pending.values()) {
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+}
 function unsupportedOutputArgKey(pythonPath, cliPath, outputArg) {
     return `${pythonPath}\0${cliPath}\0${outputArg}`;
 }
@@ -89,6 +403,128 @@ async function locatePageIndexResult(searchRoots, startedAtMs) {
     candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
     return candidates[0]?.filePath;
 }
+function normalizeBatchJobs(jobs) {
+    return jobs.map((job) => ({
+        inputPath: node_path_1.default.resolve(job.inputPath),
+        outputPath: node_path_1.default.resolve(job.outputPath)
+    }));
+}
+function failedBatchResults(jobs, error, callbacks) {
+    return jobs.map((job, index) => {
+        callbacks.onJobStart?.(job, index);
+        return {
+            ...job,
+            ok: false,
+            error
+        };
+    });
+}
+async function runPageIndexSingleFallback(job, options) {
+    try {
+        await runPageIndex(job.inputPath, job.outputPath, options);
+        return {
+            ...job,
+            ok: true
+        };
+    }
+    catch (error) {
+        return {
+            ...job,
+            ok: false,
+            error: errorMessage(error)
+        };
+    }
+}
+async function runAllSingleFallback(jobs, options, callbacks) {
+    const results = [];
+    for (let index = 0; index < jobs.length; index += 1) {
+        callbacks.onJobStart?.(jobs[index], index);
+        results.push(await runPageIndexSingleFallback(jobs[index], options));
+    }
+    return results;
+}
+async function runPageIndexBatchPool(jobs, options = {}, callbacks = {}) {
+    const config = (0, config_1.loadPageIndexConfig)(options);
+    const normalizedJobs = normalizeBatchJobs(jobs);
+    if (normalizedJobs.length === 0) {
+        return [];
+    }
+    if (!config.cliPath) {
+        return failedBatchResults(normalizedJobs, "PAGEINDEX_CLI is required to run PageIndex", callbacks);
+    }
+    const parsedArgs = parseBatchMarkdownArgs(config.extraArgs);
+    if (parsedArgs.unsupported.length > 0) {
+        if (config.pageIndexRunner === "auto") {
+            return await runAllSingleFallback(normalizedJobs, config, callbacks);
+        }
+        return failedBatchResults(normalizedJobs, `PageIndex batch runner does not support extra args: ${parsedArgs.unsupported.join(", ")}`, callbacks);
+    }
+    const cliPath = node_path_1.default.resolve(config.cliPath);
+    const cliDir = node_path_1.default.dirname(cliPath);
+    const workerCount = Math.min(Math.max(1, Math.floor(config.concurrency)), normalizedJobs.length);
+    const tempDir = await promises_1.default.mkdtemp(node_path_1.default.join(node_os_1.default.tmpdir(), "ragbox-batch-"));
+    const workers = [];
+    try {
+        for (let index = 0; index < workerCount; index += 1) {
+            const worker = new PageIndexBatchWorker(index + 1, config, cliDir, node_path_1.default.join(tempDir, `worker-${index + 1}`));
+            workers.push(worker);
+        }
+        try {
+            await Promise.all(workers.map((worker) => worker.start()));
+        }
+        catch (error) {
+            await Promise.allSettled(workers.map((worker) => worker.stop()));
+            if (config.pageIndexRunner === "auto") {
+                return await runAllSingleFallback(normalizedJobs, config, callbacks);
+            }
+            return failedBatchResults(normalizedJobs, errorMessage(error), callbacks);
+        }
+        const results = new Array(normalizedJobs.length);
+        let nextIndex = 0;
+        async function runWorkerLoop(worker) {
+            while (nextIndex < normalizedJobs.length) {
+                const currentIndex = nextIndex;
+                nextIndex += 1;
+                const job = normalizedJobs[currentIndex];
+                callbacks.onJobStart?.(job, currentIndex);
+                try {
+                    const result = await worker.run(job, parsedArgs.args);
+                    if (result.ok) {
+                        results[currentIndex] = {
+                            ...job,
+                            ok: true
+                        };
+                    }
+                    else {
+                        results[currentIndex] = {
+                            ...job,
+                            ok: false,
+                            error: result.error
+                        };
+                    }
+                }
+                catch (error) {
+                    results[currentIndex] =
+                        config.pageIndexRunner === "auto"
+                            ? await runPageIndexSingleFallback(job, config)
+                            : {
+                                ...job,
+                                ok: false,
+                                error: errorMessage(error)
+                            };
+                }
+            }
+        }
+        await Promise.all(workers.map((worker) => runWorkerLoop(worker)));
+        return results;
+    }
+    finally {
+        await Promise.allSettled(workers.map((worker) => worker.stop()));
+        if ((0, path_utils_1.isSubPath)(node_os_1.default.tmpdir(), tempDir)) {
+            await promises_1.default.rm(tempDir, { recursive: true, force: true });
+        }
+    }
+}
 async function runPageIndex(inputPath, outputPath, options = {}) {
     const config = (0, config_1.loadPageIndexConfig)(options);
     if (!config.cliPath) {

package/dist/src/folder-index/types.d.ts

@@ -39,9 +39,11 @@ export type LlmChatRequest = {
 export type LlmClient = {
     chatCompletion: (request: LlmChatRequest) => Promise<string>;
 };
+export type PageIndexRunner = "auto" | "single" | "batch";
 export type PageIndexOptions = {
     pythonPath?: string;
     cliPath?: string;
+    pageIndexRunner?: PageIndexRunner;
     model?: string;
     baseUrl?: string;
     apiKey?: string;

package/dist/src/index.d.ts

@@ -3,4 +3,5 @@ export { startServe } from "./serve";
 export type { RagboxConfig, RagboxConfigSource, RagboxIndexConfig, RagboxLlmConfig, RagboxPageIndexConfig } from "./config-file";
 export type { CreateIndexOptions, CreateIndexResult, IndexCounts, InspectIndexDocument, InspectIndexResult, LlmChatRequest, LlmClient, QueryIndexOptions, QueryResult, SdkOptions, ValidateIndexResult, ValidationIssue, WatchIndexHandle, WatchIndexOptions, WatchIndexReadyResult } from "./sdk";
 export type { ServeHandle, ServeHealthResult, ServeIndexesResult, ServeIndexSummary, ServeOptions } from "./serve";
+export type { PageIndexRunner } from "./folder-index/types";
 export * as advanced from "./advanced";

package/dist/src/sdk.d.ts

@@ -1,4 +1,4 @@
-import { DocumentRecord, IndexCounts, IndexProgressEvent, LlmClient, Manifest, QueryResult, RootTreeNode, WatchProgressEvent } from "./folder-index/types";
+import { DocumentRecord, IndexCounts, IndexProgressEvent, LlmClient, Manifest, PageIndexRunner, QueryResult, RootTreeNode, WatchProgressEvent } from "./folder-index/types";
 export type { IndexCounts, IndexProgressEvent, LlmChatRequest, LlmClient, QueryResult, WatchProgressEvent } from "./folder-index/types";
 export type SdkOptions = {
     apiKey?: string;
@@ -17,6 +17,7 @@ export type CreateIndexOptions = SdkOptions & {
     pageIndexPython?: string;
     pageIndexOutputArg?: string;
     pageIndexExtraArgs?: string[];
+    pageIndexRunner?: PageIndexRunner;
     concurrency?: number;
     onProgress?: (event: IndexProgressEvent) => void;
 };

package/dist/src/sdk.js

@@ -47,6 +47,7 @@ async function toPageIndexOptions(options = {}) {
         model: options.model,
         outputArg: createOptions.pageIndexOutputArg,
         outputDir: options.outputDir,
+        pageIndexRunner: createOptions.pageIndexRunner,
         progress: createOptions.onProgress,
         pythonPath: createOptions.pageIndexPython,
         trace: queryOptions.trace,

package/dist/src/serve.js

@@ -10,8 +10,6 @@ const config_file_1 = require("./config-file");
 const multi_query_1 = require("./folder-index/multi-query");
 const query_1 = require("./folder-index/query");
 const sdk_1 = require("./sdk");
-const DEFAULT_HOST = "127.0.0.1";
-const DEFAULT_PORT = 8787;
 const MAX_JSON_BODY_BYTES = 1024 * 1024;
 class ServeHttpError extends Error {
     status;
@@ -34,16 +32,6 @@ function mergeDefined(...values) {
     }
     return merged;
 }
-function parsePositivePort(value, fallback) {
-    if (!value) {
-        return fallback;
-    }
-    const parsed = Number.parseInt(value, 10);
-    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 65535) {
-        throw new Error(`Invalid serve port: ${value}`);
-    }
-    return parsed;
-}
 function parseSourceNames(source) {
     if (Array.isArray(source)) {
         return source.map((name) => name.trim()).filter(Boolean);
@@ -147,6 +135,21 @@ async function buildIndexes(targets) {
         indexes
     };
 }
+async function assertTargetsReadyForQuery(targets) {
+    const notReady = [];
+    for (const target of targets) {
+        const validation = await (0, sdk_1.validateIndex)(target.target);
+        if (validation.ok) {
+            continue;
+        }
+        const label = target.source ? `${target.source} (${target.target})` : target.target;
+        const firstError = validation.errors[0]?.message ?? "index is not query-ready";
+        notReady.push(`${label}: ${firstError}`);
+    }
+    if (notReady.length > 0) {
+        throw new ServeHttpError(503, "index_not_ready", `Index is not ready: ${notReady.join("; ")}`);
+    }
+}
 function healthFromIndexes(startedAt, lastReloadAt, indexes) {
     const ready = indexes.indexes.filter((index) => index.ok).length;
     const failed = indexes.indexes.length - ready;
@@ -344,9 +347,14 @@ async function queryTargets(targets, question, options) {
 }
 async function startServe(options = {}) {
     const env = options.env ?? process.env;
-    const host = options.host ?? env.RAGBOX_SERVE_HOST ?? DEFAULT_HOST;
-    const port = options.port ?? parsePositivePort(env.RAGBOX_SERVE_PORT, DEFAULT_PORT);
-    const authToken = options.authToken ?? env.RAGBOX_SERVE_TOKEN;
+    const { config } = await (0, config_file_1.readRagboxConfig)(options.configPath);
+    const { authToken, host, port } = (0, config_file_1.resolveRagboxServeConfig)({
+        config,
+        env,
+        authToken: options.authToken,
+        host: options.host,
+        port: options.port
+    });
     const serverOptions = {
         ...options,
         authToken,
@@ -426,6 +434,7 @@ async function startServe(options = {}) {
                         ...resolvedTarget,
                         options: queryOptionsFromServeOptions(resolvedTarget.options, serverOptions, trace)
                     }));
+                await assertTargetsReadyForQuery(targets);
                 writeJson(response, 200, await queryTargets(targets, question, serverOptions));
                 return;
             }