Settings

Settings management is handled via pydantic-settings, so either env vars with JUDITHA_ prefix or a local .env file works.

Storage and query

JUDITHA_URI

Path to the store directory. Holds the LevelDB aggregator (names.db/), the tantivy index (tantivy.db/), and the Aho-Corasick patterns file (automaton.txt). Supports any anystore-resolvable path: local filesystem, S3, ...

JUDITHA_FUZZY_THRESHOLD

Jaro similarity threshold for lookup / Store.search. Hits below this score are dropped. Lower for noisier inputs (OCR, NER spans with edit-distance corruption); raise to demand near-exact matches.

JUDITHA_LIMIT

Maximum candidate hits tantivy returns per search before the Jaro / rapidfuzz rerank stage. Raise if the rerank often drops the only correct candidate because it ranked outside the top-10 by BM25.

JUDITHA_MIN_LENGTH

Minimum length of the normalized query. Queries that normalize to fewer than this many characters return None without touching tantivy.

Index-time tuning

JUDITHA_MIN_TOKEN_LENGTH

Per-token length floor for the Aho-Corasick extractor's pattern-length filter, derived as min_token_length × MIN_TOKEN_COUNT (default 4 × 2 = 8 total normalized chars). Lower this to admit shorter patterns into the automaton (e.g. "Le Pen", "Al Qamar"). Cost: more spurious mentions from very short patterns.

The percolator does NOT consult this setting: it uses the hardcoded MIN_TOKEN_CHARS = 2 floor in juditha.percolator symmetrically at index time (the tokens field) and query time (the blocking_set). Noise above 2 chars is filtered at query time by percolate_min_should_match instead.

Load-time tuning

JUDITHA_GEONAMES_MIN_ALTERNATE_LENGTH

Minimum normalized length for name variants taken from the GeoNames alternatenames column. Short alternates are where most place false positives come from (Sind → Sindh, Mein → Maine, Kern → Kern County). The canonical name and asciiname use a fixed floor of 4 and are not affected. Lower toward 4 to match transliterations like "Roma"; raise for stricter, canonical-leaning matching. See Load data / GeoNames.

JUDITHA_PATCHES

Uri of a YAML file of datapatch lookups applied to every entity while loading, for example to turn a mislabelled Company into a PublicBody. Unset means no patching. See Load data / Patches.

Query-time tuning

JUDITHA_PERCOLATE_BLOCK_LIMIT

Maximum number of candidate Docs the percolator's blocking stage returns. Candidates are BM25-ranked by how many (and how rare) of the input text's tokens they match. See also JUDITHA_PERCOLATE_MIN_SHOULD_MATCH – raising that knob on a "clean" corpus removes most of the pressure on this cap by pruning weak-overlap candidates at the posting-list stage.

See Benchmark for the cost / recall curve at three corpus sizes.

JUDITHA_PERCOLATE_MIN_SHOULD_MATCH

minimum_number_should_match passed to the percolator blocking boolean_query (tantivy 0.26+). Counts the number of distinct input-text tokens a candidate Doc must share with the query before BM25 even ranks it.

Default 2 is recall-safe for names whose tokens all clear MIN_TOKEN_CHARS = 2 (a hardcoded floor in juditha.percolator that strips single-char long-tail noise like initials and lone digits, symmetric at index and query time). The percolator only ever phrase-queries names with >= MIN_TOKEN_COUNT == 2 tokens, so every percolatable doc that clears the char floor contributes >= 2 tokens to the index. Names like "A Lee" (where only "lee" clears 2 chars) silently miss – accepted as the noise-vs-recall trade-off of the char floor.

RPC

These only matter if you serve the store over gRPC, see Usage / gRPC api. JUDITHA_URI doubles as the client-side endpoint: set it to grpc://host:port and get_store() returns an ApiStore instead of a local one.

JUDITHA_RPC_HOST

Bind address for juditha serve. The default is deliberately the loopback interface: the api has no authentication, so exposing it further has to be an explicit act. The Docker image sets 0.0.0.0 because the container boundary decides what can reach it.

JUDITHA_RPC_PORT

Bind port for juditha serve. 50051 is the gRPC convention. Port 0 binds an ephemeral port, which the startup log line reports.

JUDITHA_RPC_WORKERS

Size of the server's thread pool, which caps concurrent in-flight requests. tantivy searchers and the finalized Aho-Corasick automaton are read-only, so requests need no locking and this can be raised freely. Note that percolate is the expensive call: its per-request cost scales with the number of candidates surviving blocking, so on a large corpus the thread pool is what bounds memory.

JUDITHA_RPC_MAX_MESSAGE_LENGTH

Maximum gRPC message size, applied to both send and receive on both ends. gRPC's own default is 4 MB, which extract and percolate exceed on real documents. Set this on the client as well as the server: a mismatch shows up as RESOURCE_EXHAUSTED on whichever side has the lower limit.

Debug

JUDITHA_DEBUG

When true, typer renders rich tracebacks on CLI errors. Useful for development.

Module-level constants (not settings)

Some thresholds live as module-level constants in juditha.percolator and juditha.extraction rather than on Settings, either because they're conceptually coupled to a class invariant or because changing them is invasive enough to warrant a code change: