Configuration

Reference for every environment variable, every CLI flag, every constructor option, and every config record the project recognizes.

Environment variables

The CLI programs accept all configuration as flags. The test suite, the smoke probes, and the demo runner read environment variables. The table below covers everything either tier reads.

Tests gracefully skip with a Check(true, '...') log line whenever a required env var is missing, so the unit-test suite stays green even on an unconfigured machine.

CLI flags

See the CLI Reference page for the per-CLI flag tables. Every CLI:

• Honours --help and exits 0 with a stable usage block.
• Returns exit code 1 (CLI_EXIT_ARG_ERROR) on argument errors.
• Returns exit code 2 (CLI_EXIT_RUNTIME_ERROR) on unhandled exceptions.

Constructor options

TMormotHttpTransport

TMormotHttpTransport.Create(
  ReceiveTimeoutMS: integer = 120000,
  KeepAliveMS: cardinal = 30000,
  const UserAgent: RawUtf8 = 'mormot2-pgvector/0.1');

TRetryingHttpTransport

TRetryingHttpTransport.Create(
  const AInner: IHttpTransport,
  AMaxAttempts: integer = 3,
  AInitialDelayMs: cardinal = 250);

Wraps any IHttpTransport. Retries on HTTP 5xx, HTTP 429, and any exception escaping the inner Post. Backoff is binary exponential starting from AInitialDelayMs (so 250 / 500 / 1000 ms with the defaults). HTTP 4xx other than 429 surfaces immediately without retry.

TConcurrencyLimitedHttpTransport

TConcurrencyLimitedHttpTransport.Create(
  const AInner: IHttpTransport,
  ALimit: integer);

Caps in-flight Post calls to ALimit. K=1 serializes everything through the inner transport; useful when the inner transport is not thread-safe (the default TMormotHttpTransport holds a single socket).

TOllamaEmbeddingClient

TOllamaEmbeddingClient.Create(
  const ATransport: IHttpTransport,
  const ABaseUrl: RawUtf8 = '',     // -> 'http://localhost:11434'
  const AModel: RawUtf8 = '',       // -> 'embeddinggemma'
  ADim: integer = 0);

ADim:

• 0 (default): flexible mode. Whatever dimension the server returns is accepted as-is. Use this for the probe pattern at startup.
• >0: strict mode. Must be in {128, 256, 512, 768} (the PGVECTOR_MRL_DIMS constant). The client sends "dimensions":N in every request body, raises on shorter server responses, and MRL-truncates longer responses to ADim.
• <0: rejected at construction time.

TPascalChunkerOptions

type
  TPascalChunkerOptions = record
    SplitThresholdTokens: integer;     // default 800
    SplitOverlapLines: integer;        // default 4
    OnMalformedRaise: boolean;         // default false
  end;

CHUNKER_DEFAULT_OPTIONS exposes the defaults.

TPgVectorSchemaConfig

type
  TPgVectorSchemaConfig = record
    TableName: RawUtf8;            // 'mormot_chunks'
    EmbeddingDim: integer;         // 768
    HnswM: integer;                // 16
    HnswEfConstruction: integer;   // 64
  end;

PgVectorSchemaConfigDefault returns the design-brief defaults. Override any field before calling PgVectorSchemaSql / PgVectorSetupSchema. The defaults match the canonical schema in the brief:

CREATE TABLE mormot_chunks (
  ...,
  embedding VECTOR(768),
  ts TSVECTOR ...
);
CREATE INDEX ... USING hnsw (embedding vector_cosine_ops)
  WITH (m=16, ef_construction=64);

Tuning the hybrid retrieval blend

The retrieval combined score is

α · (1 − cosine_distance) + (1 − α) · ts_rank_cd

with α = 0.7 by default (vector-dominant). Move α toward 1.0 if your corpus has a lot of paraphrased content and the question wording is loose. Move α toward 0.0 when the user is searching for a specific identifier and the wording is precise.

libpq location on Windows

If your PostgreSQL install is in a non-default path, set MORMOT2_PGVECTOR_LIBPQ to the absolute path of libpq.dll (next to postgres.exe, typically <install>\bin\libpq.dll). The CLI programs accept the same value via --libpq. Either path:

• the env var sets SynDBPostgresLibrary before any connection is opened.
• the flag has the same effect, but only for the program that consumed it.

Connection-string format

Libpq accepts both URI form (postgres://user:pass@host:port/db) and the keyword=value form. mormot2-pgvector consumes the keyword form for its --pg argument:

host=localhost;port=5432;dbname=mormot2_pgvector_test;user=postgres;password=...

Recognized keywords: host, port, dbname (or db), user, password (or pass). Whitespace inside the value is preserved. Other libpq parameters (sslmode, application_name, …) are not parsed by the CLI's connection-string parser; for those, use the direct TSqlDBPostgresConnectionProperties constructor in code.