Skip to main content

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. A soft_fallback field reports when a branch could not contribute, rather than degrading silently.
  • Reads — the fathomdb.read module: read.get, read.get_many, read.list, read.collection, read.mutations, read.projections, read.crossed_boundary_since. Each takes a ReadView selecting existence state and world-time validity.
  • Graph — fathomdb.graph.neighbors and fathomdb.graph.search_expand for 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.EngineError with typed payload attributes, so you branch on DatabaseLockedError or EmbedderNotConfiguredError instead 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)

Table of built distributions (wheels) for fathomdb 0.8.30
File Actions
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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Security 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.

Select from 5 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.8.30 This release

5 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page