socraticode/dist/services/embedding-config.d.ts

SocratiCode — MCP server for local codebase indexing, semantic search, and code dependency graphs. All private, all local via Docker.

/**
 * Embedding provider configuration — loaded from environment variables (MCP config).
 *
 * EMBEDDING_PROVIDER:
 *   - "ollama" (default): Use Ollama for embeddings (Docker or external).
 *   - "openai": Use OpenAI Embeddings API. Requires OPENAI_API_KEY.
 *   - "google": Use Google Generative AI Embedding API. Requires GOOGLE_API_KEY.
 *   - "lmstudio": Use a local LM Studio server (OpenAI-compatible). Requires
 *                 EMBEDDING_MODEL and EMBEDDING_DIMENSIONS to be set explicitly.
 *   - "litellm": Use a LiteLLM proxy server (OpenAI-compatible gateway in front of
 *                100+ underlying providers). Requires LITELLM_API_KEY,
 *                EMBEDDING_MODEL (must match an alias in the proxy's config.yaml),
 *                and EMBEDDING_DIMENSIONS (the alias's underlying dim).
 *
 * Ollama-specific:
 *   OLLAMA_MODE:
 *     - "auto" (default): Auto-detect. If Ollama is already running natively on port 11434,
 *       use it (external mode — fastest, GPU-accelerated on Mac/Windows). Otherwise fall back
 *       to a managed Docker container on port 11435. An explicit URL and API key
 *       select that external server without probing local Ollama.
 *     - "docker": Always use a managed Docker container on port 11435.
 *     - "external": User provides their own Ollama instance (native local, remote, etc.).
 *       SocratiCode will NOT create or manage Docker containers for Ollama.
 *       The user is responsible for having Ollama running at OLLAMA_URL.
 *   OLLAMA_URL:            Ollama API URL.
 *                          Default for docker mode: http://localhost:11435
 *                          Default for external mode: http://localhost:11434
 *   OLLAMA_API_KEY:        Optional API key for authenticated Ollama proxies.
 *   OLLAMA_MAX_CONNECTIONS: Max concurrent HTTP connections to Ollama.
 *                          Positive integer. Default: 4. Requests beyond the
 *                          cap queue client-side instead of opening sockets.
 *
 * Cloud provider-specific:
 *   OPENAI_API_KEY:        Required for openai provider.
 *   GOOGLE_API_KEY:        Required for google provider.
 *
 * LM Studio-specific:
 *   LMSTUDIO_URL:          OpenAI-compatible base URL for LM Studio's local server.
 *                          Default: http://localhost:1234/v1
 *   LMSTUDIO_API_KEY:      Optional API key. LM Studio's Local Server has no auth by default;
 *                          set this only if you've enabled an API key in LM Studio.
 *   LMSTUDIO_ALLOW_MISSING_MODEL_LISTING: Opt-in ("true" / "1" / "yes"). Accepts an
 *                          OpenAI-compatible server whose /v1/models endpoint is absent
 *                          (404/405) — e.g. HuggingFace Text Embeddings Inference — by
 *                          falling back to an /v1/embeddings probe. Default off.
 *                          Any other non-empty value is rejected with an error.
 *
 * LiteLLM-specific:
 *   LITELLM_URL:               OpenAI-compatible base URL of the LiteLLM proxy.
 *                              Default: http://localhost:4000/v1 (the /v1 suffix is required;
 *                              LiteLLM exposes /v1/embeddings under that prefix).
 *   LITELLM_API_KEY:           Required. Master key (general_settings.master_key) or a virtual
 *                              key issued via /key/generate. Unlike LM Studio, the proxy always
 *                              authenticates.
 *   LITELLM_SEND_DIMENSIONS:   Opt-in ("true" / "1" / "yes"). Forwards the OpenAI-style
 *                              `dimensions` parameter to the proxy for Matryoshka-aware
 *                              underlying models (text-embedding-3-*, voyage-3). Default off
 *                              because non-Matryoshka backends reject it.
 *
 * Shared:
 *   EMBEDDING_MODEL:       Model name (default depends on provider; required for lmstudio).
 *   EMBEDDING_DIMENSIONS:  Vector dimensions — must match the model (default depends on
 *                          provider; required for lmstudio).
 *   EMBEDDING_CONTEXT_LENGTH: Override context window in tokens (auto-detected for known models).
 *   EMBEDDING_QUERY_PREFIX:    Task prefix prepended to queries (default "search_query: ").
 *   EMBEDDING_DOCUMENT_PREFIX: Task prefix prepended to documents (default "search_document: ").
 *                              Both must match the model — see queryPrefix() below.
 *   EMBEDDING_DOCUMENT_INCLUDE_PATH: Whether the file path is embedded with the chunk
 *                              (default on). See documentIncludesPath() below.
 */
export type EmbeddingProvider = "ollama" | "openai" | "google" | "lmstudio" | "litellm";
export type OllamaMode = "docker" | "external" | "auto";
export interface EmbeddingConfig {
    /** Which embedding backend to use. */
    embeddingProvider: EmbeddingProvider;
    /** Ollama mode (only relevant when embeddingProvider is "ollama"). */
    ollamaMode: OllamaMode;
    /** Ollama API URL (only relevant when embeddingProvider is "ollama"). */
    ollamaUrl: string;
    /**
     * Per-origin cap on concurrent HTTP connections to Ollama. Node's default
     * fetch pool is unbounded, so concurrent embeds from several processes or
     * overlapping tool calls stack sockets without limit (issue 114); excess
     * requests queue on the bounded agent instead of opening new connections.
     */
    ollamaMaxConnections: number;
    /** LM Studio OpenAI-compatible base URL (only relevant when embeddingProvider is "lmstudio"). */
    lmstudioUrl: string;
    /** LiteLLM proxy OpenAI-compatible base URL (only relevant when embeddingProvider is "litellm"). */
    litellmUrl: string;
    /**
     * Accept an OpenAI-compatible server with no /v1/models endpoint (only relevant when
     * embeddingProvider is "lmstudio"). See LMSTUDIO_ALLOW_MISSING_MODEL_LISTING above.
     */
    allowMissingModelListing: boolean;
    embeddingModel: string;
    embeddingDimensions: number;
    /** Max context window in tokens. Used for client-side pre-truncation. */
    embeddingContextLength: number;
    /** Whether LiteLLM receives the output-dimension request parameter. */
    litellmSendDimensions: boolean;
    ollamaApiKey?: string;
}
/** Authenticated Docker requests use the port published by the managed container. */
export declare function defaultOllamaUrl(mode: OllamaMode, apiKey: string | undefined): string;
/** Parse the endpoint forms supported by the Ollama SDK, including a bare host or :port. */
export declare function parseOllamaUrl(host: string): URL | undefined;
export declare function ollamaDisplayOrigin(host: string): string;
/**
 * Task prefix for queries, from `EMBEDDING_QUERY_PREFIX`.
 *
 * `??`, not `||`: an explicit empty string is a meaningful value ("no prefix",
 * which bge-m3 requires) and `||` would silently replace it with the default.
 * Read lazily so tests can toggle it via `vi.stubEnv`.
 */
export declare function queryPrefix(): string;
/**
 * Task prefix for documents, from `EMBEDDING_DOCUMENT_PREFIX`. Change it only
 * together with {@link queryPrefix}; an asymmetric pair ranks badly. Existing
 * collections retain their persisted effective pair until freshly indexed.
 */
export declare function documentPrefix(): string;
/**
 * Whether the file path is embedded alongside the chunk content, from
 * `EMBEDDING_DOCUMENT_INCLUDE_PATH`.
 *
 * The path is part of the text handed to the vector store, so it feeds both the
 * dense embedding and the BM25 sparse vector built from that same string.
 * Turning it off therefore removes path-derived tokens from lexical search too,
 * and for context artifacts it drops the `context:<name>:<path>` identifier
 * those chunks carry. Path tokens help path-shaped queries but add noise on
 * prose-heavy corpora.
 *
 * Defaults to on, which is the pre-existing behaviour, so an index built before
 * the variable existed stays valid. Read lazily so tests can toggle it via
 * `vi.stubEnv`.
 */
export declare function documentIncludesPath(): boolean;
/**
 * Load embedding configuration from environment variables.
 * Called once on first access; cached thereafter.
 */
export declare function loadEmbeddingConfig(): EmbeddingConfig;
/** Get the current embedding configuration (loads if not yet loaded). */
export declare function getEmbeddingConfig(): EmbeddingConfig;
/**
 * Run one embedding operation with collection-specific output-shaping values.
 * Connectivity and credentials stay sourced from the live runtime config; only
 * values that define the vector space are overridden. AsyncLocalStorage keeps
 * concurrent searches for differently-profiled collections isolated.
 */
export declare function withEmbeddingConfig<T>(overrides: Pick<EmbeddingConfig, "embeddingProvider" | "embeddingModel" | "embeddingDimensions" | "embeddingContextLength" | "litellmSendDimensions">, operation: () => T): T;
/**
 * Update the resolved Ollama mode and URL after auto-detection.
 * Called by OllamaEmbeddingProvider when OLLAMA_MODE=auto resolves.
 */
export declare function setResolvedOllamaMode(mode: "docker" | "external", url: string): void;
/** Reset config cache (for testing). */
export declare function resetEmbeddingConfig(): void;
//# sourceMappingURL=embedding-config.d.ts.map