@atomic-chat/core 0.5.1 → 0.13.2

package/dist/embedding/service.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The embedding module's surface: one embedding `llama-server` at most (stock llama.cpp), its
+ * lifecycle, and the target the public `/v1/embeddings` forwards to.
+ *
+ * Outside the sessions registry on purpose, like the decision model
+ * (ADR 2026-10-07-embedding-models-are-their-own-core-module): a chat model switch unloads every
+ * other session of its provider, and the model the API serves must stay up across it. So nothing here
+ * is a `LocalRuntime`; the module borrows only process mechanics.
+ *
+ * What it guarantees (the decision module's rules, minus the fail-open calls):
+ *  - start and stop are serialized, and a stop aborts a start still waiting for readiness;
+ *  - a process that dies after it was ready is restarted with backoff, at most `MAX_RESTARTS` times in
+ *    a row; a start that fails is not retried until a setting changes, `load` is asked for, or a
+ *    llama.cpp build is installed (`onEnginesChanged`); an `unsupported` module is also retried in
+ *    the background by a request, at most once per `UNSUPPORTED_RETRY_MS`, quietly;
+ *  - a request to a module that is enabled but idle starts it and waits for it (`acquire`);
+ *  - every state change is an `embedding:state` event, and a failure nobody awaits an `embedding:error`.
+ */
+import type { CoreEvents, EmbeddingEmbedResponse, EmbeddingEngineInfo, EmbeddingSettings, EmbeddingState, EmbeddingStatus } from '../contracts/index.js';
+import type { DecisionHttp } from '../decision/index.js';
+import type { EmbeddingBackend } from '../server/index.js';
+import type { EmbeddingModelFacts } from './model-facts.js';
+import type { EmbeddingProcessHandle, EmbeddingServerSpec } from './process.js';
+/** How often a request may retry an `unsupported` module in the background. */
+export declare const UNSUPPORTED_RETRY_MS: number;
+/** The control route's own request budget, once the model runs. */
+export declare const EMBED_REQUEST_TIMEOUT_MS = 120000;
+export type EmbeddingEmitter = <K extends 'embedding:state' | 'embedding:error'>(name: K, payload: CoreEvents[K]) => void;
+export type EmbeddingLogger = (level: 'info' | 'warn' | 'debug', msg: string) => void;
+export interface EmbeddingServiceDeps {
+    /** The core's data folder: relative model paths are resolved against it. */
+    dataFolder: string;
+    readSettings: () => EmbeddingSettings;
+    /** A checked write of the `embedding` settings section (`SettingsStore.updateEmbedding`). */
+    writeSettings: (patch: Record<string, unknown>) => Promise<unknown>;
+    /** The engine gate (`EmbeddingEngineResolver.resolve`). */
+    resolveEngine: (enginePath: string, minBuild: number) => Promise<EmbeddingEngineInfo>;
+    /** A resolved build that readiness refused: skipped from now on (`EmbeddingEngineResolver.reject`). */
+    rejectEngine?: (exe: string, why: string) => Promise<void>;
+    /** Try every refused build again (`EmbeddingEngineResolver.forgetRejected`). */
+    forgetRejectedEngines?: () => void;
+    /** Start one process and wait for readiness (`spawnEmbeddingServer` plus the journal). */
+    spawn: (spec: EmbeddingServerSpec, signal: AbortSignal) => Promise<EmbeddingProcessHandle>;
+    http: DecisionHttp;
+    emit: EmbeddingEmitter;
+    log: EmbeddingLogger;
+    now?: () => number;
+    /** Whether a file exists. */
+    fileExists?: (path: string) => Promise<boolean>;
+    /** What the GGUF header says (`readEmbeddingModelFacts`); `undefined` when it cannot be read. */
+    readModelFacts?: (path: string) => Promise<EmbeddingModelFacts | undefined>;
+    /** Run `fn` after `ms`; returns the cancel. The default timer never keeps the process alive. */
+    schedule?: (fn: () => void, ms: number) => () => void;
+}
+/** The settings a running process was started with; any change means a restart. */
+export declare function embeddingLaunchKey(settings: EmbeddingSettings): string;
+/** The name API clients pass as `model`: the setting, else the file name; `null` without a model. */
+export declare function embeddingModelIdOf(settings: EmbeddingSettings): string | null;
+/** Why a request cannot reach the model in `state`, for the public route's 503. */
+export declare function embeddingRefusal(state: EmbeddingState, configured: boolean): string;
+export declare class EmbeddingService {
+    private readonly deps;
+    private state;
+    private handle;
+    private runningKey;
+    /** `embeddingLaunchKey` of the start in flight, from the moment it read the settings. */
+    private loadingKey;
+    private readySince;
+    /** `embeddingLaunchKey` of the last start: a start with another one tries the refused builds again. */
+    private lastLaunchKey;
+    /** When a request last retried an `unsupported` module; a quiet retry that changes nothing emits nothing. */
+    private lastQuietRetry;
+    private loading;
+    private loadAbort;
+    private cancelRestart;
+    private cancelIdle;
+    private inFlight;
+    private stopping;
+    /** Called on every state change and when a start settles: the public route's waits. */
+    private readonly waiters;
+    /** Start and stop, one at a time. */
+    private chain;
+    private readonly now;
+    private readonly schedule;
+    constructor(deps: EmbeddingServiceDeps);
+    /** Called once by the owner: an enabled and configured module starts in the background. */
+    start(): void;
+    getStatus(): EmbeddingStatus;
+    getConfig(): EmbeddingSettings;
+    /** Write settings, then bring the process in line with them. */
+    configure(patch: Record<string, unknown>): Promise<EmbeddingStatus>;
+    /**
+     * After a settings change: turned off → stop; started (or starting) with other launch settings →
+     * restart; enabled and not running → start in the background. The crash count starts over. A change
+     * that does not touch the launch (`idle_unload_secs`, `startup_timeout_secs`) leaves a running
+     * process alone; `idle_unload_secs` takes effect at once.
+     */
+    reconcile(): Promise<EmbeddingStatus>;
+    /**
+     * A llama.cpp build was installed: a module that is `unsupported` or `failed` tries again, since the
+     * new build may be the first new enough for the model. Installs of other providers are ignored.
+     */
+    onEnginesChanged(provider?: string): Promise<EmbeddingStatus>;
+    /** Start now (or join the start in flight) and answer once it is ready; a failure is thrown. */
+    load(): Promise<EmbeddingStatus>;
+    /** Stop the process (or the start in flight). The module stays enabled: the next request starts it again. */
+    unload(): Promise<EmbeddingStatus>;
+    /**
+     * One `/v1/embeddings` request for the app (`POST /atomic/v1/embedding/embed`): the module is
+     * started when it is enabled and idle, the body is sent with the running model's name, and the
+     * engine's answer comes back as it is. `EMBEDDING_UNAVAILABLE` when the model cannot be reached.
+     */
+    embed(body: Record<string, unknown>): Promise<EmbeddingEmbedResponse>;
+    /** What the public server forwards `/embeddings` to. */
+    publicBackend(): EmbeddingBackend;
+    /** Stop everything for good: timers, a start in flight, the process. No events after this. */
+    shutdown(): Promise<void>;
+    private setState;
+    private notifyWaiters;
+    private serial;
+    /** `quietCode`: a background retry of a state the app already heard about (see `startProcess`). */
+    private startInBackground;
+    /** An `unsupported` module whose state is older than `UNSUPPORTED_RETRY_MS` tries again, quietly. */
+    private retryUnsupported;
+    private reportUnawaited;
+    private ensureLoaded;
+    /**
+     * `quiet`: a background retry of an `unsupported` module. It does not announce `starting` and, when
+     * it fails the same way again, leaves the state as it was without an event.
+     */
+    private startProcess;
+    /**
+     * Resolve an engine and spawn it; a build that readiness refuses as unsupported or that dies while
+     * loading (a ROCm build without kernels for the card) is handed to `rejectEngine` and the next one is
+     * tried (`spawnOnFirstGoodEngine`). An explicit `engine_path` has nothing to fall back to.
+     */
+    private spawnOnFirstGoodEngine;
+    private onExit;
+    private onRestartFailed;
+    private scheduleRestart;
+    private stopProcess;
+    /** (Re)arm the idle unload; a request in flight pushes it back. */
+    private armIdle;
+    /**
+     * The public route's target. An enabled, configured module that is idle is started (a failure is an
+     * `embedding:error`); one that is starting or restarting is waited on, up to `waitMs`, until it is
+     * ready or lands in a state no start will leave, or the client leaves (`signal`).
+     */
+    private acquire;
+    /** The handle once there is one; `undefined` on timeout, on `signal`, or once no start is on its way. */
+    private waitForHandle;
+}