clef-mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,431 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+interface Limits {
+    /** Maximum number of questions per clef_decide call. */
+    maxQuestions: number;
+    /** Maximum serialized size of `state`, in bytes. */
+    maxStateBytes: number;
+    /** Maximum characters per question `instructions`. */
+    maxInstructionsChars: number;
+    /** Maximum number of criteria per question. */
+    maxCriteriaPerQuestion: number;
+    /** Maximum characters per criterion label/description. */
+    maxCriteriaDescChars: number;
+    /** Maximum characters per question id (the questions map key). */
+    maxQuestionIdChars: number;
+}
+declare const DEFAULT_LIMITS: Limits;
+declare function limitsFromEnv(env?: NodeJS.ProcessEnv): Limits;
+
+type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+type RuntimeId = 'llama-cpp';
+interface ClefConfig {
+    /** Model id, e.g. "clef-flash". */
+    model: string;
+    /** Cache/model home. Override with CLEF_HOME. */
+    clefHome: string;
+    /** Inference runtime. v0.1 ships only llama-cpp. */
+    runtime: RuntimeId;
+    logLevel: LogLevel;
+    /** Explicit path to a llama-server binary (CLEF_LLAMA_BIN). */
+    llamaBin?: string;
+    /** Pin the llama.cpp release tag used by the managed runtime download. */
+    llamaReleaseTag?: string;
+    limits: Limits;
+}
+declare function defaultClefHome(): string;
+declare function loadConfig(env?: NodeJS.ProcessEnv): ClefConfig;
+
+interface ClefPaths {
+    root: string;
+    modelsDir: string;
+    runtimeDir: string;
+    configJson: string;
+}
+declare function pathsFor(clefHome: string): ClefPaths;
+declare function modelQuantDir(modelsDir: string, model: string, quant: string): string;
+declare function manifestPathFor(modelsDir: string, model: string, quant: string): string;
+
+type LogSink = (line: string) => void;
+interface Logger {
+    error(msg: string, extra?: Record<string, unknown>): void;
+    warn(msg: string, extra?: Record<string, unknown>): void;
+    info(msg: string, extra?: Record<string, unknown>): void;
+    debug(msg: string, extra?: Record<string, unknown>): void;
+}
+declare class StderrLogger implements Logger {
+    private readonly level;
+    private readonly sink;
+    constructor(level: LogLevel, sink?: LogSink);
+    private write;
+    error(msg: string, extra?: Record<string, unknown>): void;
+    warn(msg: string, extra?: Record<string, unknown>): void;
+    info(msg: string, extra?: Record<string, unknown>): void;
+    debug(msg: string, extra?: Record<string, unknown>): void;
+}
+declare function createLogger(level: LogLevel, sink?: LogSink): Logger;
+
+declare const ClefErrorCode: {
+    readonly MODEL_NOT_INSTALLED: "MODEL_NOT_INSTALLED";
+    readonly MODEL_LOAD_FAILED: "MODEL_LOAD_FAILED";
+    readonly RUNTIME_NOT_FOUND: "RUNTIME_NOT_FOUND";
+    readonly RUNTIME_INIT_FAILED: "RUNTIME_INIT_FAILED";
+    readonly RUNTIME_NOT_SUPPORTED: "RUNTIME_NOT_SUPPORTED";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly CLEF_INFERENCE_FAILED: "CLEF_INFERENCE_FAILED";
+    readonly UNSUPPORTED_PLATFORM: "UNSUPPORTED_PLATFORM";
+    readonly OUT_OF_MEMORY: "OUT_OF_MEMORY";
+    readonly CHECKSUM_MISMATCH: "CHECKSUM_MISMATCH";
+    readonly DOWNLOAD_FAILED: "DOWNLOAD_FAILED";
+};
+type ClefErrorCode = (typeof ClefErrorCode)[keyof typeof ClefErrorCode];
+declare class ClefError extends Error {
+    readonly code: ClefErrorCode;
+    readonly hint?: string;
+    constructor(code: ClefErrorCode, message: string, hint?: string);
+}
+interface StructuredError {
+    error: {
+        code: ClefErrorCode;
+        message: string;
+        hint?: string;
+    };
+}
+/** Serialized form used both in MCP tool results and CLI output. */
+declare function errorJson(err: unknown): StructuredError;
+/** Exit codes for CLI commands. */
+declare function exitCodeFor(err: unknown): number;
+
+type QuestionType = 'noul' | 'choice' | 'score';
+interface ClefQuestion {
+    type: QuestionType;
+    instructions: string;
+    /**
+     * `choice`: map of option id -> description.
+     * `score`: ordered list of criterion descriptions (index == score).
+     * `noul`: optional map with "true"/"false" descriptions.
+     */
+    criteria?: string[] | Record<string, string>;
+}
+interface ClefDecideInput {
+    state: unknown;
+    questions: Record<string, ClefQuestion>;
+    model?: string;
+    options?: {
+        temperature?: number;
+    };
+}
+/** Probability distribution over answer options for one question. */
+type ClefDecisionAnswer = Record<string, number>;
+type ClefDecideOutput = {
+    model: string;
+    decisions: Record<string, {
+        answer: ClefDecisionAnswer;
+    }>;
+};
+
+/**
+ * Wire-level types for the SystemOne API (`POST /v1/systemone`), the de-facto
+ * interchange format for Clef decision models exposed by llama.cpp and the
+ * MLX loader alike.
+ */
+interface SystemOneQuestion {
+    type: 'noul' | 'choice' | 'score';
+    instructions?: string;
+    criteria?: string[] | Record<string, string>;
+}
+interface SystemOneRequest {
+    model: string;
+    state: string;
+    questions: Record<string, SystemOneQuestion>;
+}
+interface SystemOneUsage {
+    [key: string]: unknown;
+}
+interface SystemOneAnswer {
+    choice?: string;
+    confidence?: number;
+    /** Probability of `true` for noul questions (llama.cpp uses `noul`). */
+    noul?: number;
+    probability_true?: number;
+    probabilities?: Record<string, number> | number[];
+    expected_score?: number;
+    score?: number;
+    legend?: string[] | Record<string, string>;
+    [key: string]: unknown;
+}
+interface SystemOneResponse {
+    model?: string;
+    answers: Record<string, SystemOneAnswer>;
+    usage?: SystemOneUsage;
+}
+/** Map a validated clef_decide input to a SystemOne request body. */
+declare function toSystemOneRequest(input: ClefDecideInput, defaultModel: string): SystemOneRequest;
+/** Normalize a SystemOne response into the strict clef_decide output shape. */
+declare function fromSystemOneResponse(response: SystemOneResponse, questions: Record<string, ClefQuestion>, fallbackModel: string): ClefDecideOutput;
+
+interface RuntimeHealth {
+    status: 'ready' | 'loading' | 'unavailable';
+    detail?: string;
+}
+/**
+ * Inference runtime abstraction. Implementations load/unload the model and
+ * answer SystemOne requests, so the MCP layer never talks to an engine
+ * directly. Swapping runtimes (MLX, remote) must not change the MCP API.
+ */
+interface ClefRuntime {
+    load(): Promise<void>;
+    decide(input: SystemOneRequest): Promise<SystemOneResponse>;
+    unload(): Promise<void>;
+    health(): Promise<RuntimeHealth>;
+}
+
+interface LlamaCppRuntimeOptions {
+    serverBin: string;
+    modelPath: string;
+    alias?: string;
+    host?: string;
+    port?: number;
+    /** Max wait for the server to report ready after spawn. */
+    loadTimeoutMs?: number;
+    /** Per-request timeout for /v1/systemone. */
+    requestTimeoutMs?: number;
+    log?: Logger;
+}
+declare class LlamaCppRuntime implements ClefRuntime {
+    private readonly opts;
+    private proc?;
+    private resolvedPort?;
+    private readonly host;
+    private readonly loadTimeoutMs;
+    private readonly requestTimeoutMs;
+    /** Serializes decide() calls: the llama.cpp clef path handles one sequence per batch. */
+    private queue;
+    constructor(opts: LlamaCppRuntimeOptions);
+    get endpoint(): string;
+    get running(): boolean;
+    load(): Promise<void>;
+    private waitUntilReady;
+    decide(input: SystemOneRequest): Promise<SystemOneResponse>;
+    private decideOnce;
+    health(): Promise<RuntimeHealth>;
+    unload(): Promise<void>;
+}
+
+interface ResolvedBinary {
+    source: 'env' | 'managed' | 'path';
+    path: string;
+}
+interface BinaryResolveDeps {
+    existsExecutable?(p: string): boolean;
+    which?(name: string): string | undefined;
+    platform?: string;
+    arch?: string;
+}
+/**
+ * Resolution order: CLEF_LLAMA_BIN → managed binary under CLEF_HOME → `llama-server` on PATH.
+ * Managed wins over PATH because a user's PATH binary may predate clef support.
+ */
+declare function resolveLlamaServerBinary(cfg: ClefConfig, deps?: BinaryResolveDeps): ResolvedBinary;
+
+type QuantId = 'Q4_K_M' | 'Q8_0' | 'BF16';
+interface QuantSpec {
+    id: QuantId;
+    file: string;
+    bytes: number;
+    dirLabel: string;
+    /** Minimum total memory (RAM; on macOS unified) needed to run this quant comfortably. */
+    minTotalMemBytes: number;
+}
+interface ModelSpec {
+    id: string;
+    repo: string;
+    /** Pinned upstream revision for reproducible downloads + checksums. */
+    revision: string;
+    licenseId: string;
+    licenseUrl: string;
+    originUrl: string;
+    defaultQuant: QuantId;
+    quants: QuantSpec[];
+}
+declare const CLEF_FLASH: ModelSpec;
+declare const MODELS: Record<string, ModelSpec>;
+declare function getModelSpec(model: string): ModelSpec;
+declare function getQuantSpec(spec: ModelSpec, quant: string): QuantSpec;
+/**
+ * Auto-pick the largest quantization that fits in memory. The 9B clef-flash
+ * model needs headroom: Q4_K_M fits in 16 GB, Q8_0 in 32 GB, BF16 in 64 GB.
+ */
+declare function pickQuant(spec: ModelSpec, totalMemBytes: number, requested?: string): QuantSpec;
+
+interface ModelManifest {
+    schemaVersion: 1;
+    model: string;
+    quant: string;
+    file: string;
+    /** Absolute path to the model file. */
+    modelPath: string;
+    bytes: number;
+    /** sha256 of the model file (from the HF xet/LFS hash, verified after download). */
+    sha256?: string;
+    repo: string;
+    revision: string;
+    licenseId: string;
+    licenseUrl: string;
+    installedAt: string;
+    clefMcpVersion: string;
+}
+declare function readModelManifest(manifestPath: string): Promise<ModelManifest | undefined>;
+declare function writeModelManifest(manifestPath: string, manifest: ModelManifest): Promise<void>;
+interface ManifestCheck {
+    ok: boolean;
+    problems: string[];
+}
+/** Cheap structural verification: manifest present, file exists, size matches. */
+declare function verifyModelFiles(manifest: ModelManifest): Promise<ManifestCheck>;
+/** Full sha256 verification of the model file against the manifest hash. */
+declare function deepVerifyChecksum(manifest: ModelManifest): Promise<ManifestCheck>;
+/** Manifest for the newest installed quantization of a model, if any. */
+declare function findInstalledManifest(clefHome: string, spec: ModelSpec): Promise<ModelManifest | undefined>;
+
+interface ProbeResult {
+    latencyMs: number;
+    binarySource: 'env' | 'managed' | 'path';
+    binaryPath: string;
+}
+/**
+ * Full end-to-end check: start llama-server with the installed model, run one
+ * tiny decision, shut down. Used by `install` (verification step) and `doctor`.
+ */
+declare function probeInference(cfg: ClefConfig, manifest: ModelManifest, log?: Logger, loadTimeoutMs?: number): Promise<ProbeResult>;
+
+interface HfFileInfo {
+    downloadUrl: string;
+    /** sha256 from the HF xet/LFS hash, when advertised. */
+    sha256?: string;
+    size?: number;
+}
+/**
+ * Resolve download URL + expected checksum. The sha256 arrives as the
+ * `x-linked-etag` header on HF's 302, so we probe with redirect: 'manual'.
+ */
+declare function fetchFileInfo(repo: string, revision: string, file: string): Promise<HfFileInfo>;
+interface DownloadProgress {
+    bytes: number;
+    total?: number;
+}
+interface DownloadOptions {
+    expectedSha256?: string;
+    expectedSize?: number;
+    onProgress?(p: DownloadProgress): void;
+    signal?: AbortSignal;
+    attempts?: number;
+}
+interface DownloadResult {
+    bytes: number;
+    sha256: string;
+}
+/**
+ * Stream a file to dest, hashing while writing. Retries transient failures by
+ * restarting the download; checksum/size mismatches fail hard.
+ */
+declare function downloadFile(url: string, dest: string, opts?: DownloadOptions): Promise<DownloadResult>;
+interface InstallModelOptions {
+    clefHome: string;
+    modelSpec: ModelSpec;
+    quantSpec: QuantSpec;
+    clefMcpVersion: string;
+    onProgress?(p: DownloadProgress): void;
+    log?: Logger;
+}
+interface InstallModelResult {
+    manifest: ModelManifest;
+    alreadyInstalled: boolean;
+}
+/**
+ * Download a model quantization from its pinned HF revision, verify checksum,
+ * and write the manifest. Safe to re-run: an intact install is a no-op.
+ */
+declare function installModel(opts: InstallModelOptions): Promise<InstallModelResult>;
+
+interface ManagedRuntimeResult extends ResolvedBinary {
+    releaseTag: string;
+    freshInstall: boolean;
+}
+/**
+ * Ensure a llama-server binary exists: resolve env/managed/PATH first, else
+ * download the official ggml-org nightly build into CLEF_HOME/runtime.
+ */
+declare function ensureLlamaRuntime(cfg: ClefConfig, log?: Logger): Promise<ManagedRuntimeResult>;
+declare function downloadManagedLlama(cfg: ClefConfig, log?: Logger): Promise<ResolvedBinary & {
+    releaseTag: string;
+}>;
+/** Remove the managed llama.cpp runtime directory, if present. */
+declare function removeManagedRuntime(cfg: ClefConfig): Promise<boolean>;
+
+interface GpuInfo {
+    name?: string;
+    vramBytes?: number;
+}
+interface PlatformInfo {
+    platform: NodeJS.Platform;
+    arch: string;
+    totalMemBytes: number;
+    gpu?: GpuInfo;
+}
+declare function detectPlatform(): Promise<PlatformInfo>;
+/** llama.cpp clef builds ship for these platforms; anything else is rejected early. */
+declare function assertSupportedPlatform(info: Pick<PlatformInfo, 'platform' | 'arch'>): void;
+declare function formatBytes(bytes: number): string;
+
+declare const TOOL_NAME = "clef_decide";
+declare const SERVER_INSTRUCTIONS: string;
+interface ClefServerDeps {
+    config?: ClefConfig;
+    version?: string;
+    log?: Logger;
+    /** Test seam: override runtime construction (defaults to LlamaCppRuntime). */
+    runtimeFactory?: (opts: {
+        serverBin: string;
+        modelPath: string;
+        alias: string;
+        log?: Logger;
+    }) => ClefRuntime;
+}
+interface RunningClefServer {
+    server: McpServer;
+    start(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+declare function createClefServer(deps?: ClefServerDeps): RunningClefServer;
+
+declare function clefDecideInputSchema(limits: Limits): z.ZodObject<{
+    state: z.ZodUnknown;
+    questions: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            noul: "noul";
+            choice: "choice";
+            score: "score";
+        }>;
+        instructions: z.ZodString;
+        criteria: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+    }, z.core.$strip>>;
+    model: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodObject<{
+        temperature: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Output schema mirrored by the MCP tool result (structuredContent). */
+declare function clefDecideOutputSchema(): z.ZodObject<{
+    model: z.ZodString;
+    decisions: z.ZodRecord<z.ZodString, z.ZodObject<{
+        answer: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** `state` cannot be size-checked inside zod (it is `unknown`), so it is validated separately. */
+declare function validateStateSize(state: unknown, limits: Limits): void;
+
+declare const VERSION = "0.1.0";
+
+export { CLEF_FLASH, type ClefConfig, type ClefDecideInput, type ClefDecideOutput, type ClefDecisionAnswer, ClefError, ClefErrorCode, type ClefQuestion, type ClefRuntime, type ClefServerDeps, DEFAULT_LIMITS, type DownloadProgress, type InstallModelResult, type Limits, LlamaCppRuntime, type LlamaCppRuntimeOptions, type LogLevel, type Logger, MODELS, type ModelManifest, type ModelSpec, type PlatformInfo, type ProbeResult, type QuantSpec, type QuestionType, type ResolvedBinary, type RunningClefServer, type RuntimeHealth, SERVER_INSTRUCTIONS, StderrLogger, type SystemOneRequest, type SystemOneResponse, TOOL_NAME, VERSION, assertSupportedPlatform, clefDecideInputSchema, clefDecideOutputSchema, createClefServer, createLogger, deepVerifyChecksum, defaultClefHome, detectPlatform, downloadFile, downloadManagedLlama, ensureLlamaRuntime, errorJson, exitCodeFor, fetchFileInfo, findInstalledManifest, formatBytes, fromSystemOneResponse, getModelSpec, getQuantSpec, installModel, limitsFromEnv, loadConfig, manifestPathFor, modelQuantDir, pathsFor, pickQuant, probeInference, readModelManifest, removeManagedRuntime, resolveLlamaServerBinary, toSystemOneRequest, validateStateSize, verifyModelFiles, writeModelManifest };