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

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

Total release size: 39.1 MB

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

Download URL fathomdb-0.8.29-cp310-abi3-win_amd64.whl
Size 6.9 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
72fd6d6b6e7e7a2d1aa0841c322786b3b00221743b58c676264cdff46a726806
BLAKE2b-256 checksum
How to use checksums
fa874b1a7142be58307a09c4ed0736181605889416166c163e41e967f7a10d81
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 18, 2026.

Transparency log

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

Download URL fathomdb-0.8.29-cp310-abi3-manylinux_2_28_x86_64.whl
Size 10.1 MB
Tags CPython 3.10 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
fd651614f68faecac5f4ad3ea529d7a92b70d08a62f44ab24439488e2217b3c6
BLAKE2b-256 checksum
How to use checksums
060c2292900d6cf2f8041c15c2fe68e956d44926337a0e5ed933b715fe8991dc
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 18, 2026.

Transparency log

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

Download URL fathomdb-0.8.29-cp310-abi3-manylinux_2_28_aarch64.whl
Size 7.7 MB
Tags CPython 3.10 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
28d4d52fcd865a22e5034377be445694648b51b08971e3b7d0bb63f3f710dcbd
BLAKE2b-256 checksum
How to use checksums
c6135912a685fa0e0b5327b6e315f4c1a1f41c0d038e4ab72db22c3292aa88bd
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 18, 2026.

Transparency log

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

Download URL fathomdb-0.8.29-cp310-abi3-macosx_11_0_arm64.whl
Size 7.0 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
75fd9fd591a2d99de99c9af4ca51e0674526cc08ad909b4f60e12191e2f8434c
BLAKE2b-256 checksum
How to use checksums
2e64ab5a99807a59dd8627546c293fcd90a8801ed34a5df93e2f0f91607a21ec
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 18, 2026.

Transparency log

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

Download URL fathomdb-0.8.29-cp310-abi3-macosx_10_12_x86_64.whl
Size 7.4 MB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
64f90c0296aa3a1b32e9c74557a6a12d5f8a63abd4b83d42b7f495704708f08b
BLAKE2b-256 checksum
How to use checksums
0ef6c55ae4ae5c7959215c1226e9a7d756272cb83f86b21b74653a8a8489da52
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 18, 2026.

Transparency log

Security for fathomdb 0.8.29

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.29-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 18, 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.29 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