wolbarg 0.5.5 → 0.5.7

package/dist/index.d.cts

@@ -371,6 +371,10 @@ interface ConcurrencyConfig$1 {
     baseBackoffMs?: number;
     maxBackoffMs?: number;
     lockTimeoutMs?: number;
+    /** Total lock-wait + retry budget in ms. */
+    lockDeadlineMs?: number;
+    /** Use multi-process-oriented defaults when many OS processes share one DB file. */
+    multiProcess?: boolean;
 }
 /** Transparent embedding cache configuration. */
 interface EmbeddingCacheConfig {
@@ -2149,7 +2153,7 @@ interface WolbargOptionsBase {
     organization: string;
     /**
      * Storage provider instance or config.
-     * Prefer `database` in docs; `storage` remains fully supported.
+     * Prefer `storage: sqlite(...)` / `postgres(...)` in docs; `database` remains supported.
      */
     storage?: StorageInput;
     /**
@@ -2725,7 +2729,7 @@ declare class Wolbarg<HasLlm extends boolean = false> {
 declare function wolbarg$1(options: WolbargOptions): Wolbarg;
 
 /** Published SDK semver — keep in sync with `package.json` `version`. */
-declare const SDK_VERSION = "0.5.5";
+declare const SDK_VERSION = "0.5.6";
 
 /**
  * Operation-scoped errors with stable `code`, human `reason`, and actionable `suggestion`.
@@ -2896,10 +2900,6 @@ declare class GraphCheckpointNotSupportedError extends WolbargError {
  */
 declare function wrapOperationError(operation: string, error: unknown): WolbargError;
 
-/**
- * Public factory helpers for storage, telemetry, checkpoints, and graph providers (v0.5.5).
- */
-
 /**
  * Create a SQLite {@link StorageProvider} from a filesystem path or `:memory:`.
  *
@@ -2911,7 +2911,9 @@ declare function wrapOperationError(operation: string, error: unknown): WolbargE
  * wolbarg({ organization: "acme", storage: sqlite("./memory.db"), embedding: ... })
  * ```
  */
-declare function sqlite(connectionString: string): StorageProvider;
+declare function sqlite(connectionString: string, options?: {
+    concurrency?: ConcurrencyConfig$1;
+}): StorageProvider;
 /**
  * Create a SQLite storage **config object** (for `database` / `init` options).
  *
@@ -3046,6 +3048,16 @@ interface ConcurrencyConfig {
     maxBackoffMs?: number;
     /** SQLite busy_timeout pragma in ms. Default: 5000 */
     lockTimeoutMs?: number;
+    /**
+     * Hard ceiling for total lock-wait + retry budget in ms.
+     * Default: lockTimeoutMs * (maxRetries + 1).
+     */
+    lockDeadlineMs?: number;
+    /**
+     * When true, use multi-process-oriented defaults (higher busy_timeout / retries)
+     * unless the caller overrides individual fields.
+     */
+    multiProcess?: boolean;
 }
 
 /**
@@ -3082,6 +3094,20 @@ declare class SqliteStorageProvider implements StorageProvider {
     private transactionDepth;
     /** Incrementing counter for deterministic savepoint names. */
     private savepointCounter;
+    /**
+     * Serializes top-level write transactions on the single SQLite connection.
+     * SQLite is single-writer; serializing in-process avoids SQLITE_BUSY churn
+     * AND prevents interleaved BEGIN/SAVEPOINT state corruption when many async
+     * callers share one connection (see "no such savepoint" class of bugs).
+     */
+    private readonly writeMutex;
+    /**
+     * Async-context flag: true while executing inside a top-level write
+     * transaction held by this provider. Used so writes issued from within an
+     * ambient transaction (e.g. compress()) join that ACID unit, WITHOUT
+     * mistaking the coalescer's own flush window for an ambient transaction.
+     */
+    private readonly txContext;
     /** Hot in-process ANN for blob backend (sqlite-vec unavailable platforms). */
     private memoryIndex;
     private memoryIndexDirty;
@@ -3115,6 +3141,8 @@ declare class SqliteStorageProvider implements StorageProvider {
     setRetryLogger(fn: ((msg: string) => void) | null): void;
     /** Open the database, run migrations, and prepare statements. */
     open(): Promise<void>;
+    /** Single open attempt — connect, apply pragmas, migrate, prepare. */
+    private openOnce;
     /** Drain pending inserts, optimize, and close the SQLite connection. */
     close(): Promise<void>;
     /**
@@ -3320,6 +3348,8 @@ declare class PostgresStorageProvider implements StorageProvider {
     private insertFlushScheduled;
     private insertFlushTimer;
     private insertFlushInFlight;
+    /** Per-provider TX context — never share across PostgresStorageProvider instances. */
+    private readonly txStore;
     /**
      * @param options - Connection string, pool size, and durability flags.
      */
@@ -4119,4 +4149,111 @@ declare function runBenchmark(name: string, iterations: number, fn: () => Promis
  */
 declare function summarizeBenchmark(samples: BenchmarkSample[], startedAt: string, finishedAt: string): BenchmarkReport;
 
-export { type BenchmarkReport, type BenchmarkSample, type ChatMessage, type CheckpointInfo, type CheckpointMeta, type CheckpointOptions, type CheckpointProvider, type Chunk, type ChunkingOptions, type ChunkingStrategy, type ClearOptions, type CompressOptions, type CompressResult, CompressionError, type CompressionProvider, type ConcurrencyConfig$1 as ConcurrencyConfig, ConfigurationError, type ConversationMessage, type CreateCheckpointOptions, type DatabaseConfig, DatabaseError, type DatabaseProvider, type DatabaseProviderName, type EmbeddingCacheConfig, type EmbeddingConfig, EmbeddingError, type EmbeddingProvider, type EventDatabase, type ExportResult, FixedChunkingStrategy, type ForgetByFilterOptions, type ForgetByIdOptions, type ForgetOptions, type GetRelatedOptions, GraphCheckpointNotSupportedError, type GraphConfig, type GraphDirection, type GraphEntityInput, type GraphHealthResult, type GraphInput$1 as GraphInput, type GraphProvider, HeadingChunkingStrategy, type HistoryEvent, type HistoryOptions, type HistoryResult, type HybridConfig, type ImportResult, type IngestOptions, type IngestResult, type InitOptions, InitializationError, type KeywordDocument, type KeywordSearchHit, type KeywordSearchProvider, type LatencyBreakdown, LlmCompressionProvider, type LlmConfig, type LlmProvider, MarkdownChunkingStrategy, type MemoryChangeCallback, type MemoryChangeEvent, type MemoryContent, type MemoryDedupeConfig, type MemoryDedupeStrategy, type MemoryFilter, type MemoryMetadata, MemoryNotFoundError, type MemoryProvider, type MemoryRecord, type MetadataFilter as MetaFilter, type MetadataComparison, type MetadataFilter, type MmrConfig, Neo4jGraphProvider, NoopTelemetryProvider, type OCRProvider, type OcrResult, ParagraphChunkingStrategy, type PersistedRecallExplainPayload, type PostgresDatabaseConfig, PostgresStorageProvider, ProviderNotConfiguredError, type RecallExplainResponse, type RecallExplanationHit, type RecallOptions, type RecallResult, type RememberAction, type RememberFromMessagesOptions, type RememberFromMessagesRawStrategy, type RememberOptions, type RememberResult, type RerankDocument, type RerankHit, type RerankerProvider, type RetrievalConfig, SDK_VERSION, SentenceChunkingStrategy, SqliteCheckpointProvider, type SqliteDatabaseConfig, SqliteDatabaseProvider, SqliteEventDatabase, SqliteGraphProvider, SqliteStorageProvider, SqliteTelemetryProvider, type StageSpan, type StatsResult, type StorageConfig, StorageLockedError, type StorageProvider, type StorageProviderName, type SubscribableEvent, type SubscribeFilter, type TelemetryConfig, TelemetryEmitter, type TelemetryEvent, type TelemetryEventInput, type TelemetryLogLevel, type TelemetryOperation, type TelemetryProvider, type TelemetryQuery, type TelemetryQueryResult, type TelemetryStatus, type Unsubscribe, ValidationError, type VisionProvider, type VisionResult, Wolbarg, WolbargError, WolbargLogger, type WolbargOptions, type WolbargOptionsWithLlm, type WolbargOptionsWithoutLlm, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, createWolbarg, crossEncoder, geminiEmbedding, geminiVision, jinaReranker, lmStudioEmbedding, meta, neo4jGraph, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, runBenchmark, sqlite, sqliteCheckpoint, sqliteConfig, sqliteGraph, sqliteTelemetry, summarizeBenchmark, tesseract, togetherEmbedding, vllmEmbedding, wolbarg$1 as wolbarg, wrapOperationError };
+/**
+ * Embedding provider presets for `wolbarg init` and project config.
+ *
+ * Base URLs are defaults the user must see and may edit — never silently applied
+ * without showing the field.
+ */
+type EmbeddingProviderId = "openai" | "ollama" | "openrouter" | "lmstudio" | "gemini" | "together" | "vllm" | "custom";
+interface EmbeddingProviderPreset {
+    id: EmbeddingProviderId;
+    label: string;
+    /** Default OpenAI-compatible embeddings base URL (shown to the user). */
+    defaultBaseUrl: string;
+    /** Suggested default model id (shown to the user). */
+    defaultModel: string;
+    /** Env var name written into config / `.env`. */
+    apiKeyEnv: string;
+    /** Hint shown next to the API key prompt. */
+    apiKeyHint?: string;
+}
+declare const EMBEDDING_PROVIDER_PRESETS: readonly EmbeddingProviderPreset[];
+declare function getEmbeddingProviderPreset(id: string): EmbeddingProviderPreset | undefined;
+declare const DEFAULT_SQLITE_DB_PATH = ".wolbarg/shared-memory/memory.db";
+declare const DEFAULT_ORGANIZATION = "default";
+declare const DEFAULT_CONFIG_PATH = ".wolbarg/config.json";
+declare const DEFAULT_ENV_PATH = ".wolbarg/.env";
+
+/**
+ * Project-level Wolbarg configuration written by `wolbarg init`.
+ */
+
+interface WolbargProjectDatabaseConfig {
+    provider: "sqlite" | "postgres";
+    /** SQLite file path or Postgres connection URL. */
+    url: string;
+}
+interface WolbargProjectEmbeddingConfig {
+    /** Named provider preset id (or `custom`). */
+    provider: EmbeddingProviderId;
+    /** OpenAI-compatible embeddings base URL (always stored explicitly). */
+    baseUrl: string;
+    /** Embedding model id. */
+    model: string;
+    /** Env var that holds the API key (preferred over storing secrets). */
+    apiKeyEnv: string;
+}
+interface WolbargProjectConfig {
+    version: 1;
+    organization: string;
+    database: WolbargProjectDatabaseConfig;
+    embedding?: WolbargProjectEmbeddingConfig;
+    /** Relative paths written by init (informational). */
+    paths?: {
+        config: string;
+        env?: string;
+    };
+}
+interface SaveProjectConfigOptions {
+    cwd?: string;
+    configPath?: string;
+    /** Absolute or cwd-relative path for `.env` (optional). */
+    envPath?: string;
+    /** Raw API key to write into the env file (optional). */
+    apiKey?: string;
+    /** When true, overwrite an existing config without merging. */
+    overwrite?: boolean;
+}
+declare function defaultProjectConfig(): WolbargProjectConfig;
+declare function resolveConfigPath(cwd?: string, configPath?: string): string;
+declare function resolveEnvPath(cwd?: string, envPath?: string): string;
+declare function loadProjectConfig(cwd?: string, configPath?: string): WolbargProjectConfig | null;
+declare function saveProjectConfig(config: WolbargProjectConfig, options?: SaveProjectConfigOptions): {
+    configPath: string;
+    envPath?: string;
+};
+declare function upsertEnvVar(envPath: string, key: string, value: string): void;
+/**
+ * Resolve the API key for a project config from process.env (and optional `.env` load).
+ * Does not invent keys — returns empty string if unset.
+ */
+declare function resolveEmbeddingApiKey(config: WolbargProjectConfig, env?: NodeJS.ProcessEnv): string;
+declare function assertEmbeddingPreset(provider: string): EmbeddingProviderId;
+
+/**
+ * Build a Wolbarg instance from `.wolbarg/config.json` (+ env).
+ */
+
+interface CreateFromProjectConfigOptions {
+    cwd?: string;
+    configPath?: string;
+    /** Extra env overlay (defaults to process.env after optional .env load). */
+    env?: NodeJS.ProcessEnv;
+    /** Load `.wolbarg/.env` into the env overlay when present (default true). */
+    loadEnvFile?: boolean;
+    /** Override organization. */
+    organization?: string;
+}
+/**
+ * Load key=value pairs from a dotenv-style file into a shallow copy of `base`.
+ * Does not mutate `process.env` unless `base` is `process.env`.
+ */
+declare function applyEnvFile(envPath: string, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+declare function projectConfigToWolbargOptions(config: WolbargProjectConfig, env?: NodeJS.ProcessEnv): WolbargOptions;
+/**
+ * Create a {@link Wolbarg} context from project config written by `wolbarg init`.
+ */
+declare function createWolbargFromProjectConfig(options?: CreateFromProjectConfigOptions): Wolbarg;
+
+export { type BenchmarkReport, type BenchmarkSample, type ChatMessage, type CheckpointInfo, type CheckpointMeta, type CheckpointOptions, type CheckpointProvider, type Chunk, type ChunkingOptions, type ChunkingStrategy, type ClearOptions, type CompressOptions, type CompressResult, CompressionError, type CompressionProvider, type ConcurrencyConfig$1 as ConcurrencyConfig, ConfigurationError, type ConversationMessage, type CreateCheckpointOptions, type CreateFromProjectConfigOptions, DEFAULT_CONFIG_PATH, DEFAULT_ENV_PATH, DEFAULT_ORGANIZATION, DEFAULT_SQLITE_DB_PATH, type DatabaseConfig, DatabaseError, type DatabaseProvider, type DatabaseProviderName, EMBEDDING_PROVIDER_PRESETS, type EmbeddingCacheConfig, type EmbeddingConfig, EmbeddingError, type EmbeddingProvider, type EmbeddingProviderId, type EmbeddingProviderPreset, type EventDatabase, type ExportResult, FixedChunkingStrategy, type ForgetByFilterOptions, type ForgetByIdOptions, type ForgetOptions, type GetRelatedOptions, GraphCheckpointNotSupportedError, type GraphConfig, type GraphDirection, type GraphEntityInput, type GraphHealthResult, type GraphInput$1 as GraphInput, type GraphProvider, HeadingChunkingStrategy, type HistoryEvent, type HistoryOptions, type HistoryResult, type HybridConfig, type ImportResult, type IngestOptions, type IngestResult, type InitOptions, InitializationError, type KeywordDocument, type KeywordSearchHit, type KeywordSearchProvider, type LatencyBreakdown, LlmCompressionProvider, type LlmConfig, type LlmProvider, MarkdownChunkingStrategy, type MemoryChangeCallback, type MemoryChangeEvent, type MemoryContent, type MemoryDedupeConfig, type MemoryDedupeStrategy, type MemoryFilter, type MemoryMetadata, MemoryNotFoundError, type MemoryProvider, type MemoryRecord, type MetadataFilter as MetaFilter, type MetadataComparison, type MetadataFilter, type MmrConfig, Neo4jGraphProvider, NoopTelemetryProvider, type OCRProvider, type OcrResult, ParagraphChunkingStrategy, type PersistedRecallExplainPayload, type PostgresDatabaseConfig, PostgresStorageProvider, ProviderNotConfiguredError, type RecallExplainResponse, type RecallExplanationHit, type RecallOptions, type RecallResult, type RememberAction, type RememberFromMessagesOptions, type RememberFromMessagesRawStrategy, type RememberOptions, type RememberResult, type RerankDocument, type RerankHit, type RerankerProvider, type RetrievalConfig, SDK_VERSION, type SaveProjectConfigOptions, SentenceChunkingStrategy, SqliteCheckpointProvider, type SqliteDatabaseConfig, SqliteDatabaseProvider, SqliteEventDatabase, SqliteGraphProvider, SqliteStorageProvider, SqliteTelemetryProvider, type StageSpan, type StatsResult, type StorageConfig, StorageLockedError, type StorageProvider, type StorageProviderName, type SubscribableEvent, type SubscribeFilter, type TelemetryConfig, TelemetryEmitter, type TelemetryEvent, type TelemetryEventInput, type TelemetryLogLevel, type TelemetryOperation, type TelemetryProvider, type TelemetryQuery, type TelemetryQueryResult, type TelemetryStatus, type Unsubscribe, ValidationError, type VisionProvider, type VisionResult, Wolbarg, WolbargError, WolbargLogger, type WolbargOptions, type WolbargOptionsWithLlm, type WolbargOptionsWithoutLlm, type WolbargProjectConfig, type WolbargProjectDatabaseConfig, type WolbargProjectEmbeddingConfig, applyEnvFile, assertEmbeddingPreset, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, createWolbarg, createWolbargFromProjectConfig, crossEncoder, defaultProjectConfig, geminiEmbedding, geminiVision, getEmbeddingProviderPreset, jinaReranker, lmStudioEmbedding, loadProjectConfig, meta, neo4jGraph, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, projectConfigToWolbargOptions, resolveConfigPath, resolveEmbeddingApiKey, resolveEnvPath, runBenchmark, saveProjectConfig, sqlite, sqliteCheckpoint, sqliteConfig, sqliteGraph, sqliteTelemetry, summarizeBenchmark, tesseract, togetherEmbedding, upsertEnvVar, vllmEmbedding, wolbarg$1 as wolbarg, wrapOperationError };

package/dist/index.d.ts

@@ -371,6 +371,10 @@ interface ConcurrencyConfig$1 {
     baseBackoffMs?: number;
     maxBackoffMs?: number;
     lockTimeoutMs?: number;
+    /** Total lock-wait + retry budget in ms. */
+    lockDeadlineMs?: number;
+    /** Use multi-process-oriented defaults when many OS processes share one DB file. */
+    multiProcess?: boolean;
 }
 /** Transparent embedding cache configuration. */
 interface EmbeddingCacheConfig {
@@ -2149,7 +2153,7 @@ interface WolbargOptionsBase {
     organization: string;
     /**
      * Storage provider instance or config.
-     * Prefer `database` in docs; `storage` remains fully supported.
+     * Prefer `storage: sqlite(...)` / `postgres(...)` in docs; `database` remains supported.
      */
     storage?: StorageInput;
     /**
@@ -2725,7 +2729,7 @@ declare class Wolbarg<HasLlm extends boolean = false> {
 declare function wolbarg$1(options: WolbargOptions): Wolbarg;
 
 /** Published SDK semver — keep in sync with `package.json` `version`. */
-declare const SDK_VERSION = "0.5.5";
+declare const SDK_VERSION = "0.5.6";
 
 /**
  * Operation-scoped errors with stable `code`, human `reason`, and actionable `suggestion`.
@@ -2896,10 +2900,6 @@ declare class GraphCheckpointNotSupportedError extends WolbargError {
  */
 declare function wrapOperationError(operation: string, error: unknown): WolbargError;
 
-/**
- * Public factory helpers for storage, telemetry, checkpoints, and graph providers (v0.5.5).
- */
-
 /**
  * Create a SQLite {@link StorageProvider} from a filesystem path or `:memory:`.
  *
@@ -2911,7 +2911,9 @@ declare function wrapOperationError(operation: string, error: unknown): WolbargE
  * wolbarg({ organization: "acme", storage: sqlite("./memory.db"), embedding: ... })
  * ```
  */
-declare function sqlite(connectionString: string): StorageProvider;
+declare function sqlite(connectionString: string, options?: {
+    concurrency?: ConcurrencyConfig$1;
+}): StorageProvider;
 /**
  * Create a SQLite storage **config object** (for `database` / `init` options).
  *
@@ -3046,6 +3048,16 @@ interface ConcurrencyConfig {
     maxBackoffMs?: number;
     /** SQLite busy_timeout pragma in ms. Default: 5000 */
     lockTimeoutMs?: number;
+    /**
+     * Hard ceiling for total lock-wait + retry budget in ms.
+     * Default: lockTimeoutMs * (maxRetries + 1).
+     */
+    lockDeadlineMs?: number;
+    /**
+     * When true, use multi-process-oriented defaults (higher busy_timeout / retries)
+     * unless the caller overrides individual fields.
+     */
+    multiProcess?: boolean;
 }
 
 /**
@@ -3082,6 +3094,20 @@ declare class SqliteStorageProvider implements StorageProvider {
     private transactionDepth;
     /** Incrementing counter for deterministic savepoint names. */
     private savepointCounter;
+    /**
+     * Serializes top-level write transactions on the single SQLite connection.
+     * SQLite is single-writer; serializing in-process avoids SQLITE_BUSY churn
+     * AND prevents interleaved BEGIN/SAVEPOINT state corruption when many async
+     * callers share one connection (see "no such savepoint" class of bugs).
+     */
+    private readonly writeMutex;
+    /**
+     * Async-context flag: true while executing inside a top-level write
+     * transaction held by this provider. Used so writes issued from within an
+     * ambient transaction (e.g. compress()) join that ACID unit, WITHOUT
+     * mistaking the coalescer's own flush window for an ambient transaction.
+     */
+    private readonly txContext;
     /** Hot in-process ANN for blob backend (sqlite-vec unavailable platforms). */
     private memoryIndex;
     private memoryIndexDirty;
@@ -3115,6 +3141,8 @@ declare class SqliteStorageProvider implements StorageProvider {
     setRetryLogger(fn: ((msg: string) => void) | null): void;
     /** Open the database, run migrations, and prepare statements. */
     open(): Promise<void>;
+    /** Single open attempt — connect, apply pragmas, migrate, prepare. */
+    private openOnce;
     /** Drain pending inserts, optimize, and close the SQLite connection. */
     close(): Promise<void>;
     /**
@@ -3320,6 +3348,8 @@ declare class PostgresStorageProvider implements StorageProvider {
     private insertFlushScheduled;
     private insertFlushTimer;
     private insertFlushInFlight;
+    /** Per-provider TX context — never share across PostgresStorageProvider instances. */
+    private readonly txStore;
     /**
      * @param options - Connection string, pool size, and durability flags.
      */
@@ -4119,4 +4149,111 @@ declare function runBenchmark(name: string, iterations: number, fn: () => Promis
  */
 declare function summarizeBenchmark(samples: BenchmarkSample[], startedAt: string, finishedAt: string): BenchmarkReport;
 
-export { type BenchmarkReport, type BenchmarkSample, type ChatMessage, type CheckpointInfo, type CheckpointMeta, type CheckpointOptions, type CheckpointProvider, type Chunk, type ChunkingOptions, type ChunkingStrategy, type ClearOptions, type CompressOptions, type CompressResult, CompressionError, type CompressionProvider, type ConcurrencyConfig$1 as ConcurrencyConfig, ConfigurationError, type ConversationMessage, type CreateCheckpointOptions, type DatabaseConfig, DatabaseError, type DatabaseProvider, type DatabaseProviderName, type EmbeddingCacheConfig, type EmbeddingConfig, EmbeddingError, type EmbeddingProvider, type EventDatabase, type ExportResult, FixedChunkingStrategy, type ForgetByFilterOptions, type ForgetByIdOptions, type ForgetOptions, type GetRelatedOptions, GraphCheckpointNotSupportedError, type GraphConfig, type GraphDirection, type GraphEntityInput, type GraphHealthResult, type GraphInput$1 as GraphInput, type GraphProvider, HeadingChunkingStrategy, type HistoryEvent, type HistoryOptions, type HistoryResult, type HybridConfig, type ImportResult, type IngestOptions, type IngestResult, type InitOptions, InitializationError, type KeywordDocument, type KeywordSearchHit, type KeywordSearchProvider, type LatencyBreakdown, LlmCompressionProvider, type LlmConfig, type LlmProvider, MarkdownChunkingStrategy, type MemoryChangeCallback, type MemoryChangeEvent, type MemoryContent, type MemoryDedupeConfig, type MemoryDedupeStrategy, type MemoryFilter, type MemoryMetadata, MemoryNotFoundError, type MemoryProvider, type MemoryRecord, type MetadataFilter as MetaFilter, type MetadataComparison, type MetadataFilter, type MmrConfig, Neo4jGraphProvider, NoopTelemetryProvider, type OCRProvider, type OcrResult, ParagraphChunkingStrategy, type PersistedRecallExplainPayload, type PostgresDatabaseConfig, PostgresStorageProvider, ProviderNotConfiguredError, type RecallExplainResponse, type RecallExplanationHit, type RecallOptions, type RecallResult, type RememberAction, type RememberFromMessagesOptions, type RememberFromMessagesRawStrategy, type RememberOptions, type RememberResult, type RerankDocument, type RerankHit, type RerankerProvider, type RetrievalConfig, SDK_VERSION, SentenceChunkingStrategy, SqliteCheckpointProvider, type SqliteDatabaseConfig, SqliteDatabaseProvider, SqliteEventDatabase, SqliteGraphProvider, SqliteStorageProvider, SqliteTelemetryProvider, type StageSpan, type StatsResult, type StorageConfig, StorageLockedError, type StorageProvider, type StorageProviderName, type SubscribableEvent, type SubscribeFilter, type TelemetryConfig, TelemetryEmitter, type TelemetryEvent, type TelemetryEventInput, type TelemetryLogLevel, type TelemetryOperation, type TelemetryProvider, type TelemetryQuery, type TelemetryQueryResult, type TelemetryStatus, type Unsubscribe, ValidationError, type VisionProvider, type VisionResult, Wolbarg, WolbargError, WolbargLogger, type WolbargOptions, type WolbargOptionsWithLlm, type WolbargOptionsWithoutLlm, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, createWolbarg, crossEncoder, geminiEmbedding, geminiVision, jinaReranker, lmStudioEmbedding, meta, neo4jGraph, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, runBenchmark, sqlite, sqliteCheckpoint, sqliteConfig, sqliteGraph, sqliteTelemetry, summarizeBenchmark, tesseract, togetherEmbedding, vllmEmbedding, wolbarg$1 as wolbarg, wrapOperationError };
+/**
+ * Embedding provider presets for `wolbarg init` and project config.
+ *
+ * Base URLs are defaults the user must see and may edit — never silently applied
+ * without showing the field.
+ */
+type EmbeddingProviderId = "openai" | "ollama" | "openrouter" | "lmstudio" | "gemini" | "together" | "vllm" | "custom";
+interface EmbeddingProviderPreset {
+    id: EmbeddingProviderId;
+    label: string;
+    /** Default OpenAI-compatible embeddings base URL (shown to the user). */
+    defaultBaseUrl: string;
+    /** Suggested default model id (shown to the user). */
+    defaultModel: string;
+    /** Env var name written into config / `.env`. */
+    apiKeyEnv: string;
+    /** Hint shown next to the API key prompt. */
+    apiKeyHint?: string;
+}
+declare const EMBEDDING_PROVIDER_PRESETS: readonly EmbeddingProviderPreset[];
+declare function getEmbeddingProviderPreset(id: string): EmbeddingProviderPreset | undefined;
+declare const DEFAULT_SQLITE_DB_PATH = ".wolbarg/shared-memory/memory.db";
+declare const DEFAULT_ORGANIZATION = "default";
+declare const DEFAULT_CONFIG_PATH = ".wolbarg/config.json";
+declare const DEFAULT_ENV_PATH = ".wolbarg/.env";
+
+/**
+ * Project-level Wolbarg configuration written by `wolbarg init`.
+ */
+
+interface WolbargProjectDatabaseConfig {
+    provider: "sqlite" | "postgres";
+    /** SQLite file path or Postgres connection URL. */
+    url: string;
+}
+interface WolbargProjectEmbeddingConfig {
+    /** Named provider preset id (or `custom`). */
+    provider: EmbeddingProviderId;
+    /** OpenAI-compatible embeddings base URL (always stored explicitly). */
+    baseUrl: string;
+    /** Embedding model id. */
+    model: string;
+    /** Env var that holds the API key (preferred over storing secrets). */
+    apiKeyEnv: string;
+}
+interface WolbargProjectConfig {
+    version: 1;
+    organization: string;
+    database: WolbargProjectDatabaseConfig;
+    embedding?: WolbargProjectEmbeddingConfig;
+    /** Relative paths written by init (informational). */
+    paths?: {
+        config: string;
+        env?: string;
+    };
+}
+interface SaveProjectConfigOptions {
+    cwd?: string;
+    configPath?: string;
+    /** Absolute or cwd-relative path for `.env` (optional). */
+    envPath?: string;
+    /** Raw API key to write into the env file (optional). */
+    apiKey?: string;
+    /** When true, overwrite an existing config without merging. */
+    overwrite?: boolean;
+}
+declare function defaultProjectConfig(): WolbargProjectConfig;
+declare function resolveConfigPath(cwd?: string, configPath?: string): string;
+declare function resolveEnvPath(cwd?: string, envPath?: string): string;
+declare function loadProjectConfig(cwd?: string, configPath?: string): WolbargProjectConfig | null;
+declare function saveProjectConfig(config: WolbargProjectConfig, options?: SaveProjectConfigOptions): {
+    configPath: string;
+    envPath?: string;
+};
+declare function upsertEnvVar(envPath: string, key: string, value: string): void;
+/**
+ * Resolve the API key for a project config from process.env (and optional `.env` load).
+ * Does not invent keys — returns empty string if unset.
+ */
+declare function resolveEmbeddingApiKey(config: WolbargProjectConfig, env?: NodeJS.ProcessEnv): string;
+declare function assertEmbeddingPreset(provider: string): EmbeddingProviderId;
+
+/**
+ * Build a Wolbarg instance from `.wolbarg/config.json` (+ env).
+ */
+
+interface CreateFromProjectConfigOptions {
+    cwd?: string;
+    configPath?: string;
+    /** Extra env overlay (defaults to process.env after optional .env load). */
+    env?: NodeJS.ProcessEnv;
+    /** Load `.wolbarg/.env` into the env overlay when present (default true). */
+    loadEnvFile?: boolean;
+    /** Override organization. */
+    organization?: string;
+}
+/**
+ * Load key=value pairs from a dotenv-style file into a shallow copy of `base`.
+ * Does not mutate `process.env` unless `base` is `process.env`.
+ */
+declare function applyEnvFile(envPath: string, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+declare function projectConfigToWolbargOptions(config: WolbargProjectConfig, env?: NodeJS.ProcessEnv): WolbargOptions;
+/**
+ * Create a {@link Wolbarg} context from project config written by `wolbarg init`.
+ */
+declare function createWolbargFromProjectConfig(options?: CreateFromProjectConfigOptions): Wolbarg;
+
+export { type BenchmarkReport, type BenchmarkSample, type ChatMessage, type CheckpointInfo, type CheckpointMeta, type CheckpointOptions, type CheckpointProvider, type Chunk, type ChunkingOptions, type ChunkingStrategy, type ClearOptions, type CompressOptions, type CompressResult, CompressionError, type CompressionProvider, type ConcurrencyConfig$1 as ConcurrencyConfig, ConfigurationError, type ConversationMessage, type CreateCheckpointOptions, type CreateFromProjectConfigOptions, DEFAULT_CONFIG_PATH, DEFAULT_ENV_PATH, DEFAULT_ORGANIZATION, DEFAULT_SQLITE_DB_PATH, type DatabaseConfig, DatabaseError, type DatabaseProvider, type DatabaseProviderName, EMBEDDING_PROVIDER_PRESETS, type EmbeddingCacheConfig, type EmbeddingConfig, EmbeddingError, type EmbeddingProvider, type EmbeddingProviderId, type EmbeddingProviderPreset, type EventDatabase, type ExportResult, FixedChunkingStrategy, type ForgetByFilterOptions, type ForgetByIdOptions, type ForgetOptions, type GetRelatedOptions, GraphCheckpointNotSupportedError, type GraphConfig, type GraphDirection, type GraphEntityInput, type GraphHealthResult, type GraphInput$1 as GraphInput, type GraphProvider, HeadingChunkingStrategy, type HistoryEvent, type HistoryOptions, type HistoryResult, type HybridConfig, type ImportResult, type IngestOptions, type IngestResult, type InitOptions, InitializationError, type KeywordDocument, type KeywordSearchHit, type KeywordSearchProvider, type LatencyBreakdown, LlmCompressionProvider, type LlmConfig, type LlmProvider, MarkdownChunkingStrategy, type MemoryChangeCallback, type MemoryChangeEvent, type MemoryContent, type MemoryDedupeConfig, type MemoryDedupeStrategy, type MemoryFilter, type MemoryMetadata, MemoryNotFoundError, type MemoryProvider, type MemoryRecord, type MetadataFilter as MetaFilter, type MetadataComparison, type MetadataFilter, type MmrConfig, Neo4jGraphProvider, NoopTelemetryProvider, type OCRProvider, type OcrResult, ParagraphChunkingStrategy, type PersistedRecallExplainPayload, type PostgresDatabaseConfig, PostgresStorageProvider, ProviderNotConfiguredError, type RecallExplainResponse, type RecallExplanationHit, type RecallOptions, type RecallResult, type RememberAction, type RememberFromMessagesOptions, type RememberFromMessagesRawStrategy, type RememberOptions, type RememberResult, type RerankDocument, type RerankHit, type RerankerProvider, type RetrievalConfig, SDK_VERSION, type SaveProjectConfigOptions, SentenceChunkingStrategy, SqliteCheckpointProvider, type SqliteDatabaseConfig, SqliteDatabaseProvider, SqliteEventDatabase, SqliteGraphProvider, SqliteStorageProvider, SqliteTelemetryProvider, type StageSpan, type StatsResult, type StorageConfig, StorageLockedError, type StorageProvider, type StorageProviderName, type SubscribableEvent, type SubscribeFilter, type TelemetryConfig, TelemetryEmitter, type TelemetryEvent, type TelemetryEventInput, type TelemetryLogLevel, type TelemetryOperation, type TelemetryProvider, type TelemetryQuery, type TelemetryQueryResult, type TelemetryStatus, type Unsubscribe, ValidationError, type VisionProvider, type VisionResult, Wolbarg, WolbargError, WolbargLogger, type WolbargOptions, type WolbargOptionsWithLlm, type WolbargOptionsWithoutLlm, type WolbargProjectConfig, type WolbargProjectDatabaseConfig, type WolbargProjectEmbeddingConfig, applyEnvFile, assertEmbeddingPreset, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, createWolbarg, createWolbargFromProjectConfig, crossEncoder, defaultProjectConfig, geminiEmbedding, geminiVision, getEmbeddingProviderPreset, jinaReranker, lmStudioEmbedding, loadProjectConfig, meta, neo4jGraph, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, projectConfigToWolbargOptions, resolveConfigPath, resolveEmbeddingApiKey, resolveEnvPath, runBenchmark, saveProjectConfig, sqlite, sqliteCheckpoint, sqliteConfig, sqliteGraph, sqliteTelemetry, summarizeBenchmark, tesseract, togetherEmbedding, upsertEnvVar, vllmEmbedding, wolbarg$1 as wolbarg, wrapOperationError };