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

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. 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.28; 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.28

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

Total release size: 38.3 MB

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

Download URL fathomdb-0.8.28-cp310-abi3-win_amd64.whl
Size 6.8 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
708027d6476887b9b3aa4a02c7b49bf0f22ed1c76f4229657fde0fde6bcf7f2d
BLAKE2b-256 checksum
How to use checksums
0ea1d130b587b51ea4640e3670ed9d1823afeb5fe7767d64a0d0eb832d644c00
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 10, 2026.

Transparency log

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

Download URL fathomdb-0.8.28-cp310-abi3-manylinux_2_28_x86_64.whl
Size 9.8 MB
Tags CPython 3.10 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
100b1df9196f2b5ede95011a0ed7c00baa6283ace2790e2987e30a9ed905cd87
BLAKE2b-256 checksum
How to use checksums
d4a3229d9368639d307e64cbc61cb1a06669cfaa62e615895f6fd136537895cc
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 10, 2026.

Transparency log

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

Download URL fathomdb-0.8.28-cp310-abi3-manylinux_2_28_aarch64.whl
Size 7.6 MB
Tags CPython 3.10 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
77c9b56600f37e5eb4e6af086f4a18f084af7030048b67eb2e15737e95084356
BLAKE2b-256 checksum
How to use checksums
6668ccc79a6ce48495020e60516ebdc6b8d0f2512b57afccc9f706a8c5f62f18
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 10, 2026.

Transparency log

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

Download URL fathomdb-0.8.28-cp310-abi3-macosx_11_0_arm64.whl
Size 6.9 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
d3c08c3ce4a3ddd358f357db6ec8b4951b4f06b5217af6c72f6a47219b994bbb
BLAKE2b-256 checksum
How to use checksums
8d9fb0cba02f7882367d192580d7279e5b82995e20bc6c3012b0a03d283253f1
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 10, 2026.

Transparency log

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

Download URL fathomdb-0.8.28-cp310-abi3-macosx_10_12_x86_64.whl
Size 7.2 MB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
cbe09e7caa292822912f900407a1a8ba83aa48041306ae52f7202b77b4e27d47
BLAKE2b-256 checksum
How to use checksums
990fa62aeec36b2047416150ac933d7fce63f7e91a7e60df682aa69e2d9adde6
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 10, 2026.

Transparency log

Security for fathomdb 0.8.28

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.28-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 10, 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.28 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