@wanshi-kg/wanshi 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,269 @@
+#! /usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const info = __importStar(require("../../package.json"));
+const commands_1 = require("./commands");
+const di_1 = require("../core/di");
+const shared_1 = require("../shared");
+const config_1 = require("../config");
+const optionsToConfig_1 = require("./optionsToConfig");
+const program = new commander_1.Command();
+program
+    .name(info.name)
+    .description(info.description)
+    .option("--config <file>", "path to yaml/json configuration file with processing options")
+    // Core Processing
+    .option("-i, --input <path>", "input directory (default: pwd)")
+    .option("-f, --filter <filter>", "include files by filter (default: **/*)")
+    .option("-e, --exclude <filter...>", "exclude files by filter(s) (default: empty)")
+    .option("-o, --output <path>", "output knowledge graph file")
+    .option("-d, --description <text>", "short description for the files being processed")
+    // LLM Configuration
+    .option("--provider <name>", "LLM provider for generation (ollama|openai). 'openai' targets any OpenAI-compatible endpoint via --host")
+    .option("-m, --model <name>", "LLM to use for generation")
+    .option("-h, --host <url>", "Ollama host URL, or OpenAI-compatible base URL when --provider openai")
+    .option("--api-key <key>", "API key for the OpenAI-compatible provider (falls back to OPENAI_API_KEY / WANSHI_API_KEY env)")
+    .option("--temperature <number>", "model temperature")
+    .option("--repeat-penalty <number>", "repeat penalty, Ollama only (>1.0 discourages repetition, <1.0 promotes it, 1.0 = off)")
+    .option("--context-length <number>", "model context length, should be long enough to fit system prompt, file content/chunk and response (default: 8192)")
+    .option("--max-tokens <number>", "max output tokens per generation; raise it (or lower --chunk-size) if large knowledge-graph JSON gets truncated mid-output")
+    .option("--seed <number>", "model seed")
+    .option("-s, --system <prompt|path>", "LLM system prompt or path to handlebars template")
+    .option("--prompt-version <version>", "prompt template version under templates/ (default v5; use v4.5 for the legacy prompts)")
+    .option("--embeddings-provider <name>", "embeddings provider (ollama|openai). Independent from --provider; defaults to local Ollama")
+    .option("--embeddings-model <name>", "embeddings model used for observations similarity merging")
+    .option("--embeddings-host <url>", "embeddings host / OpenAI-compatible base URL")
+    .option("--embeddings-api-key <key>", "API key for OpenAI-compatible embeddings (falls back to OPENAI_API_KEY / WANSHI_API_KEY env)")
+    .option("--embeddings-max-input-chars <n>", "truncate embedding inputs to at most N characters (auto-shrinks further if the model still rejects them)")
+    // Text Processing
+    .option("--chunking <mode>", "set chunking mode (disabled|auto|enabled)")
+    .option("-c, --chunk-size <size>", "maximum chunk size in characters")
+    .option("--overlap-size <size>", "overlap size between chunks in characters")
+    // Whisper Audio/Video Processing
+    .option("--asr <mode>", "set automatic speech recognition mode (disabled|auto|enabled)")
+    .option("--asr-engine <engine>", "transcription engine: whisper (built-in) | dual (vendored Python VAD+dual-STT+diarization, Apple-Silicon only)")
+    .option("--whisper-model <name>", "set whisper model (default: medium)")
+    .option("--language <lang>", "set speech recognition language (default: auto)")
+    .option("--translate", "translate to english (default: false)")
+    .option("--asr-models <which>", "dual engine: which ASR backends to run (both|parakeet|whisper)")
+    .option("--num-speakers <n>", "dual engine: hint the diarizer's speaker count", (v) => parseInt(v, 10))
+    // PDF reading engine selection
+    .option("--pdf-engine <engine>", "PDF reading engine: pdf2json (built-in) | tesseract (pure-JS/WASM OCR) | docling | marker (Python subprocess) | mistral (HTTP OCR API)")
+    .option("--marker-use-llm", "marker engine: enable --use_llm hybrid mode (better tables, costs LLM calls)")
+    .option("--tesseract-lang <lang>", "tesseract engine: OCR language code(s), e.g. \"eng\" or \"eng+deu\" (default: eng)")
+    .option("--chandra-method <method>", "chandra engine: backend hf (HuggingFace, M4-runnable) | vllm (GPU server) (default: hf)")
+    // Quarantine trailing references/bibliography sections before extraction
+    .option("--strip-references", "quarantine trailing references/bibliography sections before extraction (PDF + markdown, default: false)")
+    // Image metadata enrichment (deterministic, default off)
+    .option("--exif", "extract image EXIF (GPS→location, capture time→validAt, camera/author/software) into graph facts")
+    .option("--c2pa", "read C2PA content credentials (via c2patool) into a trust observation on the image")
+    .option("--object-detection", "CV pre-pass: detect objects in images → VLM context + cv-detection graph facts")
+    .option("--detection-mode <mode>", "object-detection mode: closed (COCO classes) | zero-shot (open-vocab via readers.cv.detection.labels)")
+    // Reference & link resolution (Phase 0, network-free; off by default)
+    .option("--reference-links", "resolve internal links ([x](./other.md), [[wikilinks]], HTML href) to corpus files as links_to edges (default: false)")
+    .option("--reference-citations", "parse bibliography + inline arXiv/DOI/PMID into cites edges (network-free; default: false)")
+    .option("--reference-follow", "follow internal links to discover & process referenced files (each once); network-free, confined to input (default: false)")
+    .option("--reference-web", "fetch allowlisted external web links, extract, emit references edges (opt-in network; needs references.web.allowlist) (default: false)")
+    // Reference & link resolution (Phase 2, citation span-fetch; opt-in network, off by default)
+    .option("--reference-citation-fetch", "resolve id-bearing cites to OA full text and fetch it (opt-in network; auto-enables citation extraction) (default: false)")
+    .option("--unpaywall-email <email>", "Unpaywall polite-pool email (or $UNPAYWALL_EMAIL) — required to resolve DOI citations")
+    .option("--grobid", "use a local GROBID service to link citation markers to references (enables span-select + faithfulness) (default: false)")
+    .option("--grobid-url <url>", "GROBID service base URL (default: http://localhost:8070)")
+    .option("--reference-title-resolver", "resolve id-less references to a DOI/arXiv id via Crossref/Semantic Scholar/OpenAlex (default: false)")
+    // JSON reading strategy
+    .option("--json-strategy <mode>", "JSON reader strategy: structural (compact + split on JSON structure, default) or raw (compact + text split)")
+    // Content Classification
+    .option("--classifier <mode>", "content classifier mode (disabled|heuristic|llm|cascade)")
+    // Enable Image Processing
+    .option("--images <mode>", "enable image processing (disabled|auto|enabled)")
+    // Context Retrieval
+    .option("--retrieval <mode>", "set retrieval mode (disabled|auto|enabled)")
+    .option("--retrieval-limit <number>", "context retrieval limit")
+    .option("--retrieval-scope <mode>", "retrieval granularity: chunk (per-chunk, default) or file (once per file from first chunk)")
+    // Inline Grounding Gate
+    .option("--grounding <mode>", "inline grounding gate: disabled | flag (annotate observations) | drop (remove ungrounded ones)")
+    .option("--grounding-min-score <number>", "minimum keyword-overlap grounding score (0..1) an observation must reach")
+    .option("--grounding-checker <checker>", "grounding checker: keyword (overlap) | minicheck (local NLI fact-checker)")
+    .option("--grounding-model <model>", "Ollama model for the minicheck grounding checker (default bespoke-minicheck:7b)")
+    // Corpus Analysis Pre-pass (experimental)
+    .option("--corpus-profiling <mode>", "corpus analysis pre-pass: disabled | enabled (term frequency + cached classification + LLM glossary, injected as naming hints)")
+    .option("--corpus-top-terms <number>", "number of most-frequent terms fed to the glossary call")
+    .option("--corpus-profile-path <path>", "corpus profile sidecar path (default: <output>.corpus-profile.json)")
+    // AST symbol seed (code extraction)
+    .option("--ast <mode>", "AST symbol seed: enabled | disabled (seed code definitions + exported members as entities before the LLM)")
+    // Knowledge Graph Merging
+    .option("--entity-similarity-threshold <number>", "Jaro-Winkler similarity threshold for entity names merging")
+    .option("--observation-similarity-threshold <number>", "how similar observation embeddings needs to be so they are considered same")
+    .option("--enable-similarity-merging", "set similarity merging for entities and observations")
+    .option("--supersession <mode>", "merge-time supersession (KG-10): disabled | heuristic | llm — invalidate an older contradicted fact instead of deleting it")
+    // Export Options
+    .option("--export-format <format>", "export format (json|jsonl|mcp-jsonl|dot|kblam|lora|graphiti)")
+    // Logging & Debug
+    .option("-L, --log-level <level>", "log level")
+    .option("-l, --log-file <path>", "log file")
+    .option("-D, --debug", "debug mode")
+    .option("-S, --silent", "silent mode")
+    .option("--progress-ndjson", "emit structured NDJSON progress events (and log lines) to stdout for a parent process / UI to consume; suppresses pretty logging so stdout stays a clean NDJSON stream")
+    // Resume / Continuation
+    .option("--resume", "checkpoint each processed chunk and skip already-done chunks on re-run (survives interrupted/credit-exhausted runs)")
+    .option("--checkpoint <path>", "checkpoint sidecar file path (default: <output>.checkpoint.jsonl)")
+    // Debug/observability run-trace
+    .option("--trace", "emit a structured decision run-trace to a JSONL sidecar (debug/observability; off by default)")
+    .option("--trace-path <path>", "trace sidecar file path (default: <output>.trace.jsonl)")
+    // Cost / token metering
+    .option("--cost", "meter LLM token usage + cost: print a pre-run estimate and an end-of-run tally (off by default)")
+    .option("--max-cost <amount>", "hard spend cap for this run; stops gracefully (checkpoints + exports) when exceeded (implies --cost)")
+    .option("--cost-ledger <path>", "cumulative cost ledger sidecar (default: <output>.cost.json)")
+    // Structured-emit adapters (data-sink track)
+    .option("--sqlite", "map .db/.sqlite files directly to a graph (tables→types, rows→entities, FK→edges; no LLM; off by default)")
+    // Runtime Modes
+    .option("-w, --watch", "watch for changes and update knowledge graph")
+    .option("--export-only", "convert an existing knowledge-graph JSON file (--input) to --export-format, written to --output")
+    .version(info.version)
+    .action((cliOptions) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b;
+    // Resolve the effective config: defaults < file < CLI flags < env. CLI flags
+    // carry no Commander defaults, so an unset flag never overrides file config.
+    const fileRaw = cliOptions.config
+        ? (yield (0, shared_1.readConfigurationFile)(cliOptions.config))
+        : {};
+    const cliRaw = (0, optionsToConfig_1.cliArgsToConfig)(cliOptions);
+    const merged = (0, optionsToConfig_1.deepMerge)(fileRaw, cliRaw);
+    // API keys may come from the environment instead of CLI/config.
+    // WANSHI_API_KEY is the branded var; KG_API_KEY kept as a deprecated fallback.
+    const envApiKey = process.env.OPENAI_API_KEY || process.env.WANSHI_API_KEY || process.env.KG_API_KEY;
+    if (envApiKey) {
+        if (!((_a = merged.llm) === null || _a === void 0 ? void 0 : _a.apiKey))
+            (0, optionsToConfig_1.setPath)(merged, "llm.apiKey", envApiKey);
+        if (!((_b = merged.embeddings) === null || _b === void 0 ? void 0 : _b.apiKey))
+            (0, optionsToConfig_1.setPath)(merged, "embeddings.apiKey", envApiKey);
+    }
+    let options;
+    try {
+        options = (0, config_1.parseConfig)(merged);
+    }
+    catch (error) {
+        if (error instanceof config_1.ConfigError) {
+            console.error(error.message);
+            process.exit(1);
+        }
+        throw error;
+    }
+    // Initialize DI container
+    const container = di_1.ContainerFactory.createContainer({
+        processingOptions: options,
+    });
+    const logger = yield container.resolve(di_1.TYPES.Logger);
+    try {
+        if (options.runtime.exportOnly) {
+            yield (0, commands_1.exportCommand)(container);
+        }
+        else if (options.runtime.watch) {
+            yield (0, commands_1.watchCommand)(container);
+        }
+        else {
+            yield (0, commands_1.processCommand)(container);
+        }
+    }
+    catch (error) {
+        logger.error(`Command failed: ${error}`);
+        process.exit(1);
+    }
+}));
+// `wanshi schema` — emit the config JSON Schema + UI metadata so a frontend can
+// render the run form without duplicating the option list. The single source of
+// truth is the Zod ConfigSchema in src/config.
+program
+    .command("schema")
+    .description("print the configuration JSON Schema (+ UI group metadata) as JSON")
+    .option("--json", "compact single-line JSON (default is pretty-printed)")
+    .action((opts) => {
+    const payload = (0, config_1.configSchemaPayload)();
+    process.stdout.write(JSON.stringify(payload, null, opts.json ? 0 : 2) + "\n");
+});
+// `wanshi metrics <graph.json>` — the no-ground-truth A/B scorecard (entity/
+// relation-type counts, self-loops, bidirectional contradictions, referential
+// integrity, parallel edges). With --ground-truth it adds semantic triple
+// precision/recall + fabricated-edge rate. Used to capture the baseline numbers
+// and to score every canonicalization arm uniformly.
+program
+    .command("metrics")
+    .description("compute knowledge-graph health metrics (and ground-truth scores) for a json graph")
+    .argument("<graph.json>", "path to a json-format knowledge graph ({entities, relations})")
+    .option("--config <file>", "config file (for embeddings/provider settings, used only with --ground-truth)")
+    .option("--ground-truth <file.jsonl>", "JSONL of ground-truth triples/edges for precision/recall + fabricated-edge rate")
+    .option("--match-threshold <number>", "semantic match cosine threshold (default 0.80)")
+    .option("--output <file>", "also write the full metrics report as JSON to this path")
+    .action((graphPath, opts) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        yield (0, commands_1.metricsCommand)(graphPath, opts);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}));
+// `wanshi inspect-merges <merges.jsonl>` — table view over the canonicalization
+// merge log: what got fused, how tight each cluster was, suspicious over-merges
+// first. The merge log is the experiment's deliverable, not the graph.
+program
+    .command("inspect-merges")
+    .description("render the canonicalization merge log as a table (suspicious over-merges first)")
+    .argument("<merges.jsonl>", "path to a merges.jsonl emitted by a canonicalization run")
+    .option("--target <kind>", "only show 'entity' or 'relation' clusters")
+    .option("--suspect-below <number>", "flag clusters whose min intra-cluster sim is below this (default 0.80)")
+    .option("--limit <number>", "limit the number of rows printed")
+    .action((logPath, opts) => {
+    try {
+        (0, commands_1.inspectMergesCommand)(logPath, opts);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/optionsToConfig.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * Translate Commander's flat, camelCase CLI options into the nested config shape
+ * (`src/config/schema.ts`). CLI flags stay flat and ergonomic (`--chunk-size`,
+ * not `--chunking.size`); this maps them onto their nested home so the schema —
+ * the single source of truth — validates and defaults everything.
+ *
+ * CLI flags carry NO Commander defaults (see cli/index.ts): an unset flag is
+ * absent here, so it never clobbers a file-config value. That makes precedence
+ * defaults < file < CLI < env work as a plain deep merge.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLAG_TO_PATH = void 0;
+exports.setPath = setPath;
+exports.cliArgsToConfig = cliArgsToConfig;
+exports.deepMerge = deepMerge;
+/** camelCase CLI option key → dotted path in the nested config. */
+exports.FLAG_TO_PATH = {
+    input: "input",
+    filter: "filter",
+    exclude: "exclude",
+    output: "output",
+    description: "description",
+    // llm
+    provider: "llm.provider",
+    model: "llm.model",
+    host: "llm.host",
+    apiKey: "llm.apiKey",
+    temperature: "llm.temperature",
+    repeatPenalty: "llm.repeatPenalty",
+    contextLength: "llm.contextLength",
+    maxTokens: "llm.maxTokens",
+    seed: "llm.seed",
+    system: "llm.system",
+    promptVersion: "llm.promptVersion",
+    // embeddings
+    embeddingsProvider: "embeddings.provider",
+    embeddingsModel: "embeddings.model",
+    embeddingsHost: "embeddings.host",
+    embeddingsApiKey: "embeddings.apiKey",
+    embeddingsMaxInputChars: "embeddings.maxInputChars",
+    // chunking
+    chunking: "chunking.mode",
+    chunkSize: "chunking.size",
+    overlapSize: "chunking.overlap",
+    // readers
+    asr: "readers.asr.mode",
+    asrEngine: "readers.asr.engine",
+    whisperModel: "readers.asr.whisperModel",
+    language: "readers.asr.language",
+    translate: "readers.asr.translate",
+    asrModels: "readers.asr.dual.asr",
+    numSpeakers: "readers.asr.dual.numSpeakers",
+    pdfEngine: "readers.pdfEngine",
+    markerUseLlm: "readers.marker.useLlm",
+    tesseractLang: "readers.tesseract.lang",
+    chandraMethod: "readers.chandra.method",
+    stripReferences: "readers.stripReferences",
+    jsonStrategy: "readers.json.strategy",
+    images: "readers.images",
+    exif: "readers.exif.enabled",
+    c2pa: "readers.c2pa.enabled",
+    objectDetection: "readers.cv.detection.enabled",
+    detectionMode: "readers.cv.detection.mode",
+    // references (Phase 0, network-free; off by default)
+    referenceLinks: "references.internalLinks.enabled",
+    referenceCitations: "references.citations.enabled",
+    referenceFollow: "references.follow.enabled",
+    referenceWeb: "references.web.enabled",
+    // references — Phase 2 citation span-fetch (opt-in network)
+    referenceCitationFetch: "references.citations.fetch.enabled",
+    unpaywallEmail: "references.citations.fetch.unpaywallEmail",
+    grobid: "references.citations.grobid.enabled",
+    grobidUrl: "references.citations.grobid.url",
+    referenceTitleResolver: "references.citations.titleResolver.enabled",
+    // classifier
+    classifier: "classifier.mode",
+    // retrieval
+    retrieval: "retrieval.mode",
+    retrievalLimit: "retrieval.limit",
+    retrievalScope: "retrieval.scope",
+    // grounding
+    grounding: "grounding.mode",
+    groundingMinScore: "grounding.minScore",
+    groundingChecker: "grounding.checker",
+    groundingModel: "grounding.model",
+    // corpus
+    corpusProfiling: "corpus.profiling",
+    corpusTopTerms: "corpus.topTerms",
+    corpusProfilePath: "corpus.profilePath",
+    // ast
+    ast: "ast.mode",
+    // merging
+    entitySimilarityThreshold: "merging.entitySimilarityThreshold",
+    observationSimilarityThreshold: "merging.observationSimilarityThreshold",
+    enableSimilarityMerging: "merging.enableSimilarityMerging",
+    supersession: "merging.supersession",
+    // export
+    exportFormat: "export.format",
+    // logging
+    logLevel: "logging.level",
+    logFile: "logging.file",
+    debug: "logging.debug",
+    silent: "logging.silent",
+    progressNdjson: "logging.progressNdjson",
+    // resume
+    resume: "resume.enabled",
+    checkpoint: "resume.checkpointPath",
+    // trace (debug/observability run-trace)
+    trace: "trace.enabled",
+    tracePath: "trace.path",
+    // cost (token/cost metering; --max-cost auto-enables in ContainerFactory)
+    cost: "cost.enabled",
+    maxCost: "cost.maxCost",
+    costLedger: "cost.ledgerPath",
+    // structured-emit adapters (data-sink track)
+    sqlite: "adapters.sqlite.enabled",
+    // runtime
+    watch: "runtime.watch",
+    exportOnly: "runtime.exportOnly",
+};
+/** Set a dotted path on a nested object, creating intermediate objects. */
+function setPath(target, path, value) {
+    const parts = path.split(".");
+    let node = target;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const key = parts[i];
+        if (typeof node[key] !== "object" || node[key] === null)
+            node[key] = {};
+        node = node[key];
+    }
+    node[parts[parts.length - 1]] = value;
+}
+/** Build a nested config partial from Commander's flat options (defined keys only). */
+function cliArgsToConfig(cliOptions) {
+    const out = {};
+    for (const [flag, path] of Object.entries(exports.FLAG_TO_PATH)) {
+        const value = cliOptions[flag];
+        if (value !== undefined)
+            setPath(out, path, value);
+    }
+    return out;
+}
+/** Recursively merge `override` onto `base` (plain objects deep-merged, arrays/scalars replaced). */
+function deepMerge(base, override) {
+    const out = Object.assign({}, base);
+    for (const [key, value] of Object.entries(override)) {
+        if (isPlainObject(value) && isPlainObject(out[key])) {
+            out[key] = deepMerge(out[key], value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+//# sourceMappingURL=optionsToConfig.js.map

package/dist/cli/optionsToConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optionsToConfig.js","sourceRoot":"","sources":["../../src/cli/optionsToConfig.ts"],"names":[],"mappings":"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"}

package/dist/config/index.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigError = exports.CONTROLLED_PATHS = exports.CONFIG_GROUPS = exports.formatConfigError = exports.LEGACY_KEY_HINTS = exports.ConfigSchema = void 0;
+exports.parseConfig = parseConfig;
+exports.configJsonSchema = configJsonSchema;
+exports.configSchemaPayload = configSchemaPayload;
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const schema_1 = require("./schema");
+const legacyHints_1 = require("./legacyHints");
+const ui_1 = require("./ui");
+var schema_2 = require("./schema");
+Object.defineProperty(exports, "ConfigSchema", { enumerable: true, get: function () { return schema_2.ConfigSchema; } });
+var legacyHints_2 = require("./legacyHints");
+Object.defineProperty(exports, "LEGACY_KEY_HINTS", { enumerable: true, get: function () { return legacyHints_2.LEGACY_KEY_HINTS; } });
+Object.defineProperty(exports, "formatConfigError", { enumerable: true, get: function () { return legacyHints_2.formatConfigError; } });
+var ui_2 = require("./ui");
+Object.defineProperty(exports, "CONFIG_GROUPS", { enumerable: true, get: function () { return ui_2.CONFIG_GROUPS; } });
+Object.defineProperty(exports, "CONTROLLED_PATHS", { enumerable: true, get: function () { return ui_2.CONTROLLED_PATHS; } });
+/**
+ * Validate a raw (merged) config object and apply all defaults. Throws a
+ * `ConfigError` with an actionable message (legacy keys → new nested paths) on
+ * a validation failure.
+ */
+function parseConfig(raw) {
+    const result = schema_1.ConfigSchema.safeParse(raw !== null && raw !== void 0 ? raw : {});
+    if (!result.success) {
+        throw new ConfigError((0, legacyHints_1.formatConfigError)(result.error), result.error);
+    }
+    return result.data;
+}
+/** Error carrying a human-formatted config validation message. */
+class ConfigError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "ConfigError";
+    }
+}
+exports.ConfigError = ConfigError;
+/** The config JSON Schema (inlined, no $refs) for external consumers. */
+function configJsonSchema() {
+    return (0, zod_to_json_schema_1.zodToJsonSchema)(schema_1.ConfigSchema, {
+        name: "KgGenConfig",
+        $refStrategy: "none",
+    });
+}
+/**
+ * The full schema payload the `wanshi schema` command emits and the frontend
+ * consumes: the JSON Schema (types/enums/defaults/help) plus UI layout metadata
+ * (groups + widget hints) so the run form is rendered without duplicating it.
+ */
+function configSchemaPayload() {
+    return {
+        jsonSchema: configJsonSchema(),
+        groups: ui_1.CONFIG_GROUPS,
+        controlledPaths: ui_1.CONTROLLED_PATHS,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":";;;AAiDA,kCAMC;AAWD,4CAKC;AAOD,kDAUC;AAvFD,2DAAqD;AACrD,qCAWkB;AAClB,+CAAkD;AAClD,6BAAuD;AAEvD,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AACrB,6CAAoE;AAA3D,+GAAA,gBAAgB,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AAC5C,2BAAuD;AAA9C,mGAAA,aAAa,OAAA;AAAE,sGAAA,gBAAgB,OAAA;AAyBxC;;;;GAIG;AACH,SAAgB,WAAW,CAAC,GAAY;IACtC,MAAM,MAAM,GAAG,qBAAY,CAAC,SAAS,CAAC,GAAG,aAAH,GAAG,cAAH,GAAG,GAAI,EAAE,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,WAAW,CAAC,IAAA,+BAAiB,EAAC,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,kEAAkE;AAClE,MAAa,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe,EAAW,KAAkB;QACtD,KAAK,CAAC,OAAO,CAAC,CAAC;QADqB,UAAK,GAAL,KAAK,CAAa;QAEtD,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AALD,kCAKC;AAED,yEAAyE;AACzE,SAAgB,gBAAgB;IAC9B,OAAO,IAAA,oCAAe,EAAC,qBAAY,EAAE;QACnC,IAAI,EAAE,aAAa;QACnB,YAAY,EAAE,MAAM;KACrB,CAA4B,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,SAAgB,mBAAmB;IAKjC,OAAO;QACL,UAAU,EAAE,gBAAgB,EAAE;QAC9B,MAAM,EAAE,kBAAa;QACrB,eAAe,EAAE,qBAAgB;KAClC,CAAC;AACJ,CAAC"}

package/dist/config/legacyHints.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_KEY_HINTS = void 0;
+exports.formatConfigError = formatConfigError;
+/**
+ * Map of legacy flat config keys → their new nested path, so a clean-break
+ * validation error can tell the user exactly where the key moved. Covers the
+ * pre-nesting flat shape (see docs/MIGRATION.md). Keys not listed here are reported
+ * as plain "unknown key".
+ */
+exports.LEGACY_KEY_HINTS = {
+    // llm
+    provider: "llm.provider",
+    model: "llm.model",
+    host: "llm.host",
+    apiKey: "llm.apiKey",
+    temperature: "llm.temperature",
+    repeatPenalty: "llm.repeatPenalty",
+    contextLength: "llm.contextLength",
+    maxTokens: "llm.maxTokens",
+    seed: "llm.seed",
+    system: "llm.system",
+    promptVersion: "llm.promptVersion",
+    // embeddings
+    embeddingsProvider: "embeddings.provider",
+    embeddingsModel: "embeddings.model",
+    embeddingsHost: "embeddings.host",
+    embeddingsApiKey: "embeddings.apiKey",
+    embeddingsMaxInputChars: "embeddings.maxInputChars",
+    // chunking
+    chunking: "chunking.mode",
+    chunkSize: "chunking.size",
+    overlapSize: "chunking.overlap",
+    // retrieval
+    retrieval: "retrieval.mode",
+    retrievalLimit: "retrieval.limit",
+    retrievalScope: "retrieval.scope",
+    // merging
+    entitySimilarityThreshold: "merging.entitySimilarityThreshold",
+    observationSimilarityThreshold: "merging.observationSimilarityThreshold",
+    enableSimilarityMerging: "merging.enableSimilarityMerging",
+    // grounding
+    grounding: "grounding.mode",
+    groundingMinScore: "grounding.minScore",
+    // corpus
+    corpusProfiling: "corpus.profiling",
+    corpusTopTerms: "corpus.topTerms",
+    corpusProfilePath: "corpus.profilePath",
+    corpusClustering: "corpus.clustering",
+    // classifier
+    classifier: "classifier.mode",
+    // readers
+    docling: "readers.pdfEngine: docling",
+    pdfEngine: "readers.pdfEngine",
+    images: "readers.images",
+    jsonStrategy: "readers.json.strategy",
+    jsonReader: "readers.json",
+    asr: "readers.asr.mode",
+    whisperModel: "readers.asr.whisperModel",
+    language: "readers.asr.language",
+    translate: "readers.asr.translate",
+    outline: "readers.outline",
+    // export
+    exportFormat: "export.format",
+    dotOptions: "export.dot",
+    // resume
+    resume: "resume.enabled",
+    checkpointPath: "resume.checkpointPath",
+    // logging
+    logLevel: "logging.level",
+    logFile: "logging.file",
+    debug: "logging.debug",
+    silent: "logging.silent",
+    progressNdjson: "logging.progressNdjson",
+    // runtime
+    watch: "runtime.watch",
+    exportOnly: "runtime.exportOnly",
+};
+/**
+ * Render a ZodError from `parseConfig` into an actionable message. Unrecognized
+ * keys (the common symptom of a legacy flat config) are listed with their new
+ * nested location; everything else is shown as a normal validation problem.
+ */
+function formatConfigError(error) {
+    const lines = ["Invalid configuration:"];
+    const moved = [];
+    const other = [];
+    for (const issue of error.issues) {
+        if (issue.code === "unrecognized_keys") {
+            for (const key of issue.keys) {
+                const hint = exports.LEGACY_KEY_HINTS[key];
+                moved.push(hint
+                    ? `  • '${key}' → '${hint}' (the config format is now nested)`
+                    : `  • unknown key '${key}'`);
+            }
+        }
+        else {
+            const path = issue.path.join(".") || "(root)";
+            other.push(`  • ${path}: ${issue.message}`);
+        }
+    }
+    if (moved.length) {
+        lines.push("", "Keys that moved (flat → nested):", ...moved);
+    }
+    if (other.length) {
+        lines.push("", "Validation problems:", ...other);
+    }
+    if (moved.length) {
+        lines.push("", "See docs/MIGRATION.md for the full flat → nested mapping.");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=legacyHints.js.map

package/dist/config/legacyHints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacyHints.js","sourceRoot":"","sources":["../../src/config/legacyHints.ts"],"names":[],"mappings":"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"}