FathomDB
Python SDK for FathomDB — a local-first, embedded retrieval engine for application and agent workloads, built on SQLite.
A FathomDB database is a single file on your disk and runs in your process without a server. Plain open uses no model network access. Explicitly enabling the pinned default embedder may fetch verified weights on a cold cache, as described below.
Status: pre-1.0, beta
The 0.8.x line is under active development. The public surface can change between minor releases, and scale/stability guarantees are staged for 0.9.x and later.
Install
pip install fathomdb==0.8.30
Requires Python 3.10 or newer. Wheels are abi3, so one wheel per platform serves every supported
interpreter. The package is a PyO3 binding to the FathomDB Rust engine and has no Python
dependencies of its own.
Quick start
from fathomdb import Engine
engine = Engine.open("./app.sqlite")
engine.write([
{
"kind": "doc",
"body": "the quick brown fox",
# Provenance is MANDATORY on every canonical row: source_id is the
# axis erase_source() erases on, so a row without one is unerasable.
"source_id": "import-2026-07",
}
])
result = engine.search("brown fox")
for hit in result.results:
print(hit.id, hit.kind)
engine.close()
What is on the surface
- Engine lifecycle —
Engine.open,engine.close,engine.drain,engine.counters(),engine.open_report(), and a logging-subscriber seam. - Writes —
engine.write(batch)of canonical nodes ({"kind", "body", "source_id", "logical_id"?, "state"?, "reason"?, "valid_from"?, "valid_until"?}) and edges ({"edge": {"kind", "from", "to", "source_id"}}). - Search —
engine.search(query, ...)fuses FTS5 lexical retrieval with dense vector retrieval, with optional cross-encoder reranking, JSON filters, and an opt-in explain sidecar. Asoft_fallbackfield reports when a branch could not contribute, rather than degrading silently. - Reads — the
fathomdb.readmodule:read.get,read.get_many,read.list,read.collection,read.mutations,read.projections,read.crossed_boundary_since. Each takes aReadViewselecting existence state and world-time validity. - Graph —
fathomdb.graph.neighborsandfathomdb.graph.search_expandfor bounded BFS expansion from search hits. - Record lifecycle —
engine.transition,engine.purge,engine.erase_source. - Projections —
engine.configure_projections, declaring which fields are filterable, searchable or rankable. The engine owns every derived index; you never maintain one by hand. - Typed errors — a single-rooted hierarchy under
fathomdb.errors.EngineErrorwith typed payload attributes, so you branch onDatabaseLockedErrororEmbedderNotConfiguredErrorinstead of parsing message strings.
Embeddings
Vector search needs vectors. Engine.open(path, use_default_embedder=True) opts into the engine's
pinned default embedder; on first use the weights are downloaded and cached under
~/.cache/fathomdb/embedders/. The default is False — a plain Engine.open performs no network
access at all, and vector writes then raise EmbedderNotConfiguredError rather than quietly doing
nothing.
Release cached module models
from fathomdb import release_models exposes release_models(), which drops
both standalone CLS and cross-encoder caches before success. Call it after
admitted model work finishes. Loading, cache waits, inference or another release
raises OverloadedError immediately and clears neither cache. Empty/repeated
release constructs nothing; later healthy calls reload on demand. Engine-owned
Mean providers close separately with their Engine. Terminal CUDA loss still
requires process restart. See model lifetime and examples.
Erasing data
Every canonical row carries a source_id, and that is deliberate: it is what makes the row
erasable. Under the default autonomous policy, engine.erase_source(source_id) removes every row written under that provenance together
with its full-text, vector and secondary-index shadows, and finishes the erasure at rest.
engine.purge(logical_id) does the same for a single governed record. Both are idempotent, so an
interrupted erasure obligation can simply be retried.
A store configured with physical_erasure_policy="explicit_maintenance"
requires an exclusive maintenance window for physical erasure; direct
erase/purge outside that window raises MaintenanceError. Queueing an erasure
intent does not delete or hide records. Completion is certified by the
maintenance result, while incomplete cleanup retains its durable fences. See
the maintenance guide.
Other SDKs
The same engine is available as a Node.js package (npm install fathomdb). The Rust
application peer is fathomdb-sdk (import fathomdb_sdk), available in
0.8.30; use the
Rust SDK installation guide.
The fathomdb crate remains the
separate lower-level engine facade.
Building from source
From an owned checkout, select its declared developer tools and create its own .venv:
bash scripts/setup-python-owned.sh --provision
The helper installs a locked, noneditable wheel built from this source tree, with the declared production features and owned interpreter. Its receipt records source, wheel and native-module identity. Linked worktrees need separate environments; never borrow or repoint another checkout's binding. The explicit test-hooks gate separately builds its candidate wheel for tests.
License
MIT. See the LICENSE file shipped in this distribution.
Source, issues and full documentation: https://github.com/fathomadb/fathomdb
Metadata
Release files for fathomdb 0.8.30
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| fathomdb-0.8.30-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details for fathomdb-0.8.30-cp310-abi3-win_amd64.whl |
| fathomdb-0.8.30-cp310-abi3-manylinux_2_28_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.28+ x86-64 | Details for fathomdb-0.8.30-cp310-abi3-manylinux_2_28_x86_64.whl |
| fathomdb-0.8.30-cp310-abi3-manylinux_2_28_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.28+ ARM64 | Details for fathomdb-0.8.30-cp310-abi3-manylinux_2_28_aarch64.whl |
| fathomdb-0.8.30-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details for fathomdb-0.8.30-cp310-abi3-macosx_11_0_arm64.whl |
| fathomdb-0.8.30-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details for fathomdb-0.8.30-cp310-abi3-macosx_10_12_x86_64.whl |
Total release size: 50.0 MB
Release files / fathomdb-0.8.30-cp310-abi3-win_amd64.whl
| Download URL | fathomdb-0.8.30-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 7.1 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
cc3ef3ee33fed70f4fc17be78121b4f10c922536eee54a4760afd25fcf0c4f7d
|
|
BLAKE2b-256 checksum How to use checksums |
fed02cf2e2382bf576a379bf8182e745e6615d61c86e3c5855607515a3c11d0d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / fathomdb-0.8.30-cp310-abi3-manylinux_2_28_x86_64.whl
| Download URL | fathomdb-0.8.30-cp310-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 20.5 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
c267919e78372cabd8b8a62538f42450d5485a8883719185886e1444fcf3d5cf
|
|
BLAKE2b-256 checksum How to use checksums |
4d4c0cbf47d10dafd3bcf82190f60ff998c17e22f34559a308c028178ad5a21c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / fathomdb-0.8.30-cp310-abi3-manylinux_2_28_aarch64.whl
| Download URL | fathomdb-0.8.30-cp310-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 7.8 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
0bc9fbef810c19855198ceded993cc1d33e8b7bcf163ed380d4d761efe218da4
|
|
BLAKE2b-256 checksum How to use checksums |
d813248b3d1f8b8f7844ee96dc813cea302ece4c1a40c5a2f540a9573e70fa00
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / fathomdb-0.8.30-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | fathomdb-0.8.30-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 7.1 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
26f047aa211870e7c8719a9c3aa7c5b26c74b4390391b9ead48caa6e1f4e546b
|
|
BLAKE2b-256 checksum How to use checksums |
a70cd020e676cda0b225fe11e758d2e9804be02a8abb2060a4169af06eab8729
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / fathomdb-0.8.30-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | fathomdb-0.8.30-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 7.5 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
9202c6ed484354c515f7d52c0bcc706e232667e914358ffc69e5626fc230356e
|
|
BLAKE2b-256 checksum How to use checksums |
5c4617e2064da225fb3c5b0127f83e19db7e9ec853ba04c7b78ce8b5a8fd25a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logSecurity for fathomdb 0.8.30
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 5 files in this release have been uploaded with provenance metadata.
Attestation for fathomdb-0.8.30-cp310-abi3-win_amd64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.