@mcmcjs/stan 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,263 @@
+import { CommandRunner, DrawBatch, ToolInfo, Engine, FitProgress, FitResult, RuntimeVersion } from '@mcmcjs/engine';
+import { ResolvedSpec, Samples } from '@mcmcjs/core';
+
+/** The spec channel meaning "use whatever CmdStan is installed locally". */
+declare const INSTALLED_CMDSTAN_CHANNEL = "installed";
+/** The CmdStan version `mcmc setup --engine stan` provisions. */
+declare const PINNED_CMDSTAN_VERSION = "2.39.0";
+/** A CmdStan installation found on this machine. */
+interface CmdStanInstall {
+    version: string;
+    /** The cmdstan home directory (contains makefile, bin/stanc, examples/). */
+    home: string;
+}
+/** The managed root for CmdStan installs: `<data>/mcmcjs/stan`. */
+declare function managedStanRoot(): string;
+/** A directory is a usable CmdStan home when the makefile and stanc are present. */
+declare function isCmdStanHome(dir: string): boolean;
+/**
+ * Every CmdStan install visible to mcmcjs, newest first: an explicit
+ * MCMCJS_CMDSTAN/CMDSTAN home wins, then the managed root, then the
+ * conventional `~/.cmdstan` used by other Stan interfaces.
+ */
+declare function listCmdStanInstalls(): CmdStanInstall[];
+/**
+ * Resolves the CmdStan install a fit runs on. `installed` (the default channel)
+ * takes the newest local install; an explicit version must match exactly.
+ */
+declare function resolveCmdStan(requested?: string): CmdStanInstall;
+
+interface CompiledModel {
+    /** Path to the compiled model executable. */
+    binaryPath: string;
+    /** True when a previously compiled binary was reused. */
+    cached: boolean;
+}
+interface CompileOptions {
+    /** Runs make; injectable for tests. Compiles can take minutes. */
+    runner?: CommandRunner;
+    /** Cache root; defaults to `<managed>/models`. */
+    cacheRoot?: string;
+}
+/** The compile cache directory for a model source on a CmdStan version. */
+declare function modelCacheDir(source: string, version: string, cacheRoot?: string): string;
+/**
+ * Compiles a Stan model to an executable through CmdStan's make, cached by
+ * source content and CmdStan version so edits recompile and reruns are instant.
+ */
+declare function compileModel(install: CmdStanInstall, modelPath: string, options?: CompileOptions): Promise<CompiledModel>;
+
+/** Stan CSV column -> streamed leaf name; null for dropped diagnostic columns. */
+declare function columnToLeaf(column: string): string | null;
+interface StanCsvTail {
+    /** Reads newly appended rows and emits any full batches. */
+    poll(): void;
+    /** Final poll plus a flush of the remaining partial batch. */
+    finish(): void;
+}
+/**
+ * Incrementally tails one growing CmdStan CSV, batching completed draws into
+ * DrawBatch messages. Comment lines (the config echo, adaptation block, and
+ * timing footer) are skipped; the first non-comment line is the header. A
+ * trailing line without its newline is left buffered until it completes, and a
+ * row is only accepted when its field count matches the header.
+ */
+declare function createStanCsvTail(filePath: string, opts: {
+    /** 0-based chain index reported in batches. */
+    chain: number;
+    /** Draws per batch. */
+    batchSize: number;
+    onBatch: (batch: DrawBatch) => void;
+}): StanCsvTail;
+
+/** A summary of the Stan toolchain available for inference. */
+interface StanDoctorReport {
+    cmdstan: ToolInfo;
+    stanc: ToolInfo;
+    make: ToolInfo;
+    cxx: ToolInfo;
+    /** The install a fit would use, when one exists. */
+    install?: CmdStanInstall;
+    /** True when a fit can compile and sample: CmdStan plus the build toolchain. */
+    ready: boolean;
+}
+/** Detects the installed Stan toolchain and reports whether inference can run. */
+declare function runDoctor(runner?: CommandRunner): Promise<StanDoctorReport>;
+
+declare const stanEngine: Engine;
+
+interface StanSpawnResult {
+    code: number;
+    stderr: string;
+    cancelled?: boolean;
+}
+interface StanSpawnOptions {
+    /** Called once per complete stdout line (CmdStan prints progress there). */
+    onStdoutLine?: (line: string) => void;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+/** Spawns one CmdStan process, streaming stdout lines to the caller. */
+type StanSpawn = (command: string, args: string[], opts?: StanSpawnOptions) => Promise<StanSpawnResult>;
+/**
+ * The production StanSpawn: detached on POSIX so cancellation kills the whole
+ * process group, stdout parsed line-by-line for progress, stderr captured for
+ * error reporting.
+ */
+declare function createStanSpawn(defaultTimeoutMs?: number): StanSpawn;
+/** Parses one CmdStan progress line; null when the line is not progress. */
+declare function parseIterationLine(line: string): {
+    iteration: number;
+    total: number;
+    warmup: boolean;
+} | null;
+
+interface StanFitIo {
+    /** Spawns CmdStan processes; injectable so runFit is testable without CmdStan. */
+    spawn?: StanSpawn;
+    /** Where the samples file is written. */
+    outPath: string;
+    /** Where the run record is written; defaults to `<outPath>.run.json`. */
+    recordPath?: string;
+    /** Streamed per-chain sampling progress. */
+    onProgress?: (progress: FitProgress) => void;
+    /** Streamed draw batches as sampling proceeds. */
+    onDraws?: (batch: DrawBatch) => void;
+    /** Draws per streamed batch (default 25). */
+    drawBatchSize?: number;
+    /** Aborts an in-progress fit; the run then ends with a "cancelled" status. */
+    signal?: AbortSignal;
+    /** Source path when the data came from a referenced file; recorded, not copied. */
+    dataFile?: string;
+    /** Overrides the recorded data hash (e.g. the data file's bytes hash). */
+    dataSha256?: string;
+    /** Model compile pass-through, injectable for tests. */
+    compile?: CompileOptions;
+    tmpDir?: string;
+}
+/** The per-chain CmdStan invocation. Chains share one seed; `id` varies the stream. */
+declare function chainArgs(spec: ResolvedSpec, chain1: number, dataPath: string, csvPath: string): string[];
+/** Runs one Stan inference on a resolved CmdStan install. */
+declare function runFit(spec: ResolvedSpec, install: CmdStanInstall, io: StanFitIo): Promise<FitResult>;
+
+interface StanMatrixEntry {
+    version: string;
+    status: "ok" | "error" | "cancelled";
+    samplesFile?: string;
+    runtimeActual?: string;
+    elapsedMs: number;
+    stage?: FitResult["stage"];
+    error?: string;
+}
+interface StanMatrixResult {
+    entries: StanMatrixEntry[];
+    /** True only when every requested version ran and succeeded. */
+    ok: boolean;
+}
+interface StanMatrixIo {
+    /** Directory the per-version samples files are written into. */
+    outDir: string;
+    dataFile?: string;
+    dataSha256?: string;
+    /** Continue after a version fails instead of stopping. */
+    keepGoing?: boolean;
+    signal?: AbortSignal;
+    /** Fit pass-through, injectable for tests. */
+    fit?: Pick<StanFitIo, "spawn" | "compile">;
+}
+/** Runs one spec across several installed CmdStan versions. */
+declare function runMatrix(spec: ResolvedSpec, versions: string[], io: StanMatrixIo): Promise<StanMatrixResult>;
+
+interface StanPredictIo {
+    /** Where the posterior-predictive samples file is written. */
+    outPath: string;
+    /** The posterior samples file fed to prediction. */
+    samplesPath: string;
+    /** Spawns CmdStan processes; injectable so runPredict is testable without CmdStan. */
+    spawn?: StanSpawn;
+    /** Model compile pass-through, injectable for tests. */
+    compile?: CompileOptions;
+    signal?: AbortSignal;
+    tmpDir?: string;
+}
+/**
+ * The prediction data: [data] with [predict].data overrides. Unlike the Julia
+ * engines, targets are not blanked; Stan predictions come from the model's own
+ * generated quantities block, which reads the data as-is.
+ */
+declare function predictData(spec: ResolvedSpec): Record<string, unknown>;
+/**
+ * One Stan-CSV of fitted parameters per chain, rebuilt from the samples file.
+ * CmdStan's generate_quantities reads parameters by header name and ignores
+ * extra columns, so a header plus the parameter draws is sufficient.
+ */
+declare function fittedParamsCsv(samples: Samples, chain: number): string;
+/** Whether a scalarized variable name belongs to a predict target base name. */
+declare function matchesTarget(name: string, targets: readonly string[]): boolean;
+/**
+ * Draws posterior-predictive samples through CmdStan's generate_quantities:
+ * the model's generated quantities block re-runs once per posterior draw, and
+ * the columns matching [predict].targets become the predictive samples file.
+ */
+declare function runPredict(spec: ResolvedSpec, install: CmdStanInstall, io: StanPredictIo): Promise<FitResult>;
+
+/** An executable and its arguments, run directly (no shell word-splitting). */
+interface InstallCommand {
+    command: string;
+    args: string[];
+}
+/** A single provisioning step needed to make the toolchain ready. */
+interface SetupStep {
+    tool: "toolchain" | "cmdstan" | "build";
+    label: string;
+    /** The command to run, or null when the step cannot be performed automatically. */
+    command: InstallCommand | null;
+}
+/** The managed home a given CmdStan version installs into. */
+declare function managedCmdStanHome(version: string): string;
+/** The ordered steps needed to reach a ready toolchain, given the current state. */
+declare function planSetup(report: StanDoctorReport, platform: NodeJS.Platform, version?: string): SetupStep[];
+type StepStatus = "ran" | "skipped" | "failed" | "unsupported";
+interface SetupStepResult extends SetupStep {
+    status: StepStatus;
+    /** Error detail when the step failed. */
+    detail?: string;
+}
+interface StanSetupResult {
+    cmdstan: ToolInfo;
+    stanc: ToolInfo;
+    make: ToolInfo;
+    cxx: ToolInfo;
+    /** True when a Stan fit can run after setup. */
+    ready: boolean;
+    steps: SetupStepResult[];
+}
+interface StanSetupOptions {
+    /** Runs detection commands. Injectable for tests. */
+    runner?: CommandRunner;
+    /** Runs install steps, which may take several minutes. Injectable for tests. */
+    installer?: CommandRunner;
+    /** Target platform; defaults to the current process platform. */
+    platform?: NodeJS.Platform;
+    /** Plan the steps but do not run them. */
+    dryRun?: boolean;
+    /** CmdStan version to provision; defaults to the pinned version. */
+    version?: string;
+}
+/** Installs the CmdStan toolchain needed for Stan inference. */
+declare function runSetup(options?: StanSetupOptions): Promise<StanSetupResult>;
+
+/**
+ * Lists the installed CmdStan versions, newest first. The newest is the
+ * default: the `installed` channel resolves to it.
+ */
+declare function listVersions(): RuntimeVersion[];
+/** Installs a CmdStan version into the managed root. */
+declare function addVersion(version: string, options?: Omit<StanSetupOptions, "version">): Promise<StanSetupResult>;
+/**
+ * Removes a managed CmdStan install. Only versions under the managed root are
+ * removable; `~/.cmdstan` installs and explicit env-var homes are never touched.
+ */
+declare function removeVersion(version: string): void;
+
+export { type CmdStanInstall, type CompileOptions, type CompiledModel, INSTALLED_CMDSTAN_CHANNEL, PINNED_CMDSTAN_VERSION, type SetupStep, type SetupStepResult, type StanCsvTail, type StanDoctorReport, type StanFitIo, type StanMatrixEntry, type StanMatrixIo, type StanMatrixResult, type StanPredictIo, type StanSetupOptions, type StanSetupResult, type StanSpawn, type StanSpawnResult, type StepStatus, addVersion, chainArgs, columnToLeaf, compileModel, createStanCsvTail, createStanSpawn, fittedParamsCsv, isCmdStanHome, listCmdStanInstalls, listVersions, managedCmdStanHome, managedStanRoot, matchesTarget, modelCacheDir, parseIterationLine, planSetup, predictData, removeVersion, resolveCmdStan, runDoctor, runFit, runMatrix, runPredict, runSetup, stanEngine };