Skip to content

Quickstart

Five-minute walkthrough: install, populate a tiny corpus, build the index, run a lookup. CLI version first, then the same flow from Python.

Install

juditha is on PyPI. It pulls in tantivy, rigour, FollowTheMoney, and anystore.

pip install juditha
pip install "juditha[geonames]"   # if you want to load places from GeoNames

You can verify the install with juditha --version.

CLI flow

juditha keeps its state in a directory. By default this is juditha.db in the current working directory; override it with the JUDITHA_URI environment variable.

1. Load names

Each line in the input becomes a known name. You can pipe from stdin or point at a file / URL.

printf "Jane Doe\nAlice Smith\nACME Holdings" | juditha load-names

2. Build the index

Loading is cheap (it just writes to the LevelDB aggregator). The tantivy index and the Aho-Corasick extractor are built in one pass over the aggregator:

juditha build

You need to rerun juditha build whenever you load new data.

3. Lookup

juditha lookup "Jane Doe"
juditha lookup "jane doe"         # case-insensitive, matches
juditha lookup "doe, jane"        # order-independent, matches
juditha lookup "Jane Dae"         # one-character typo, requires lower threshold
juditha lookup "Jane Dae" --threshold 0.5

The default fuzzy threshold is 0.97; lower it for noisier inputs.

Python flow

The same corpus is reachable from Python via the juditha package:

from juditha import lookup

# Hits at the default threshold (0.97)
res = lookup("Jane Doe")
assert res is not None
assert "Jane Doe" in res.names

# Same canonical key, different surface form
assert lookup("doe, jane") is not None

# Below threshold returns None
assert lookup("Jane Dae") is None
assert lookup("Jane Dae", threshold=0.5) is not None

The result is a juditha.model.Result (a Doc extended with query, score, caption, common_schema). See Usage / Python for the full surface.

Where to point JUDITHA_URI

For a long-running worker, set JUDITHA_URI once before starting the process:

export JUDITHA_URI=/var/lib/juditha
juditha build
juditha lookup "Jane Doe"

Inside Python the same env var is read by juditha.settings.Settings; you can also pass uri= explicitly to lookup() or get_store().

To share one built corpus across several workers or hosts, point JUDITHA_URI at a juditha serve process instead of at a directory:

# on the host that holds the store
JUDITHA_URI=/var/lib/juditha juditha serve --host 0.0.0.0

# in the worker
export JUDITHA_URI=grpc://juditha-host:50051
juditha lookup "Jane Doe"

Everything read-only (lookup, extract, percolate) then goes over the wire unchanged. See Usage / gRPC api.

Next