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. There is no server, no daemon and no network call: you open a path and you have hybrid full-text + vector search over your own data, in your own process.

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

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.

Erasing data

Every canonical row carries a source_id, and that is deliberate: it is what makes the row erasable. 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.

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.27; use the Rust SDK installation guide. The fathomdb crate remains the separate lower-level engine facade.

Building from source

From a checkout of the repository:

pip install -e src/python/

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

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.27
File Actions
fathomdb-0.8.27-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for fathomdb-0.8.27-cp310-abi3-win_amd64.whl
fathomdb-0.8.27-cp310-abi3-manylinux_2_28_x86_64.whl CPython 3.10 abi3 Linux glibc 2.28+ x86-64 Details for fathomdb-0.8.27-cp310-abi3-manylinux_2_28_x86_64.whl
fathomdb-0.8.27-cp310-abi3-manylinux_2_28_aarch64.whl CPython 3.10 abi3 Linux glibc 2.28+ ARM64 Details for fathomdb-0.8.27-cp310-abi3-manylinux_2_28_aarch64.whl
fathomdb-0.8.27-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for fathomdb-0.8.27-cp310-abi3-macosx_11_0_arm64.whl
fathomdb-0.8.27-cp310-abi3-macosx_10_12_x86_64.whl CPython 3.10 abi3 macOS 10.12+ x86-64 Details for fathomdb-0.8.27-cp310-abi3-macosx_10_12_x86_64.whl

Total release size: 36.1 MB

Release files / fathomdb-0.8.27-cp310-abi3-win_amd64.whl

Download URL fathomdb-0.8.27-cp310-abi3-win_amd64.whl
Size 6.4 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
2ff2c470518836d258ee5648c2d2e2d6c8dbaa4debd3fe041a2e8ea1843ef55e
BLAKE2b-256 checksum
How to use checksums
d7459a38ec3da57aeb6026b23404727bd6d3625ff4858e3a335b62eeabf3b024
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 Oct 11, 2026.

Transparency log

Release files / fathomdb-0.8.27-cp310-abi3-manylinux_2_28_x86_64.whl

Download URL fathomdb-0.8.27-cp310-abi3-manylinux_2_28_x86_64.whl
Size 9.3 MB
Tags CPython 3.10 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
ce089ad982c4ca7955747e7e009637914e3803c9ce46a14482c0fecc024c69eb
BLAKE2b-256 checksum
How to use checksums
08b831460b9a3f7faf6ee64094fc5aebbaa84d62bbaec57809cee171189ba7e2
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 Oct 11, 2026.

Transparency log

Release files / fathomdb-0.8.27-cp310-abi3-manylinux_2_28_aarch64.whl

Download URL fathomdb-0.8.27-cp310-abi3-manylinux_2_28_aarch64.whl
Size 7.1 MB
Tags CPython 3.10 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
84975f099f48e0a03ae83fbe2dc9a631668c8a0e18e15ff2a89065175489e821
BLAKE2b-256 checksum
How to use checksums
dd2f21f8d8151f2be7d99b74a6bbb7a05d308e942e38fbc72d3921d9c0fad66a
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 Oct 11, 2026.

Transparency log

Release files / fathomdb-0.8.27-cp310-abi3-macosx_11_0_arm64.whl

Download URL fathomdb-0.8.27-cp310-abi3-macosx_11_0_arm64.whl
Size 6.5 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
fcc6a7b40e883e60fa2740ec1cf340cfbdf58cf6e948d51c5a9640d6206b7f62
BLAKE2b-256 checksum
How to use checksums
481f95175d2835f8a26ee64f09b60aafc6beb8835ffa5dcd5d91c42fb7647773
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 Oct 11, 2026.

Transparency log

Release files / fathomdb-0.8.27-cp310-abi3-macosx_10_12_x86_64.whl

Download URL fathomdb-0.8.27-cp310-abi3-macosx_10_12_x86_64.whl
Size 6.8 MB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
1846f801515f32149e291da21bc77868e12fc4abcade289bed4a8c32df09674a
BLAKE2b-256 checksum
How to use checksums
497a465d20914f7b972a977c09939b1898830a6bd349dd4819fb110b8779adcd
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 Oct 11, 2026.

Transparency log

Security for fathomdb 0.8.27

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.27-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 Oct 11, 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.27 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