Metadata-Version: 2.4
Name: humemdb
Version: 0.1.0.dev4
Summary: Embedded multi-model database orchestration over SQLite, DuckDB, Cypher, and exact and ANN vector search
Project-URL: Homepage, https://github.com/humemai/humemdb
Project-URL: Documentation, https://docs.humem.ai/humemdb/
Project-URL: Repository, https://github.com/humemai/humemdb
Project-URL: Issues, https://github.com/humemai/humemdb/issues
Author: HumemAI
License: MIT License
        
        Copyright (c) 2026 HumemAI
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: database,humemdb,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Requires-Python: >=3.10
Requires-Dist: duckdb<2,>=1.4
Requires-Dist: lancedb<1,>=0.27
Requires-Dist: numpy<3,>=2
Requires-Dist: sqlglot[c]<31,>=30
Requires-Dist: threadpoolctl<4,>=3.6
Description-Content-Type: text/markdown

# HumemDB

Multi-model embedded data orchestration for SQL, Cypher, and vector search.

[![Docs](https://img.shields.io/badge/docs-humem.ai-0f766e)](https://docs.humem.ai/humemdb/)
[![Test](https://github.com/humemai/humemdb/actions/workflows/test.yml/badge.svg)](https://github.com/humemai/humemdb/actions/workflows/test.yml)
[![Examples](https://github.com/humemai/humemdb/actions/workflows/test-examples.yml/badge.svg)](https://github.com/humemai/humemdb/actions/workflows/test-examples.yml)
[![Build Docs](https://github.com/humemai/humemdb/actions/workflows/build-docs.yml/badge.svg)](https://github.com/humemai/humemdb/actions/workflows/build-docs.yml)
[![Publish PyPI](https://github.com/humemai/humemdb/actions/workflows/publish-pypi.yml/badge.svg)](https://github.com/humemai/humemdb/actions/workflows/publish-pypi.yml)

---

## ✨ What HumemDB is

HumemDB is a Python-first embedded runtime that keeps each engine doing the job it is
already good at.

- SQLite for OLTP.
- DuckDB for OLAP.
- Cypher support over SQL-backed graph storage.
- Exact and ANN vector search, with the default runtime path starting from an exact
  SQLite-plus-NumPy baseline today.
- LanceDB later where the benchmark justifies an indexed ANN path.

Today, it starts as a thin Python orchestration layer over embedded engines. The
longer-term goal is a single embedded system that supports standard SQL, Cypher, and
vector search without forcing one engine to do every job.

The goal is not to force SQL, graph, and vector workloads through one backend just
because that sounds clean. The goal is a simple, explicit orchestration layer with
clear routing and defensible tradeoffs.

## ✅ Current status

HumemDB already ships a real `v0` surface for three query modes:

- `HumemSQL v0`
- `HumemCypher v0`
- `HumemVector v0`

Current behavior is intentionally explicit:

- Route: `sqlite` or `duckdb`
- Query type: `sql`, `cypher`, or `vector`
- Writes go to SQLite
- DuckDB is the analytical read path
- Vector search starts from the exact baseline path today

## 🔗 Documentation

- [HumemDB docs](https://docs.humem.ai/humemdb/)

## Install

HumemDB supports Python 3.10 and newer.

Install from source:

```bash
uv pip install .
```

Install in editable mode for development:

```bash
uv pip install -e .
```

For contributors, use:

```bash
uv sync
```

`uv sync` makes the local environment match the project exactly using `pyproject.toml`
and `uv.lock`.

When dependencies change:

```bash
uv lock
uv sync
```

`uv lock` updates the lockfile with exact resolved versions. `uv sync` installs that
exact environment.

## Libraries HumemDB relies on

HumemDB is a pure Python orchestration layer, but it relies on a small set of core
Python libraries and embedded engines:

- `sqlite3` from the Python standard library for the canonical local write path.
- `duckdb` for analytical reads over the SQLite-backed source-of-truth database.
- `numpy` for the exact in-memory vector search baseline.
- `sqlglot[c]` for the current PostgreSQL-like SQL translation layer.
- `lancedb` for benchmark work and future indexed ANN paths.
- `threadpoolctl` for thread-pool coordination around compute-heavy dependencies.

Those dependencies are part of the public runtime story. HumemDB does not try to hide
them behind a fake "single engine" narrative.

## 🧠 What is supported today

### SQL

- PostgreSQL-like portable subset translated with `sqlglot`
- statement coverage: `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `CREATE`
- recursive CTEs intentionally unsupported in `v0`

### Cypher

- narrow `CREATE` and `MATCH` flows
- labeled nodes and single directed relationships
- relationship aliases and reverse-edge matches
- simple `WHERE ... AND ...` equality filtering
- `ORDER BY` and `LIMIT`

### Vector

- SQLite-backed vector storage
- exact NumPy baseline path
- bucket filtering
- benchmark path toward indexed ANN where justified

## ⚡ Quick example

```python
from humemdb import HumemDB

with HumemDB("app.sqlite3", "analytics.duckdb") as db:
    db.query(
        "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)",
        route="sqlite",
    )

    with db.transaction(route="sqlite"):
        db.query(
            "INSERT INTO users (name) VALUES (?)",
            route="sqlite",
            params=("Alice",),
        )

    result = db.query(
        "SELECT id, name FROM users",
        route="sqlite",
    )

    print(result.rows)
```

More examples live in [examples/](examples/) and in the docs site.

## 🔗 Quick links

- Docs: [docs.humem.ai/humemdb](https://docs.humem.ai/humemdb/)
- Repository: [github.com/humemai/humemdb](https://github.com/humemai/humemdb)
- Issues: [github.com/humemai/humemdb/issues](https://github.com/humemai/humemdb/issues)
- Internal roadmap notes: [things-to-do.md](things-to-do.md)

## 📦 Packaging

HumemDB itself is a pure Python package today. It does not ship platform-specific
project binaries, even though some dependencies may install native wheels on the user
side.

## 🗺️ Planning

Detailed internal roadmap notes now live in `things-to-do.md` instead of this README.

## 📄 License

HumemDB's own source code is licensed under MIT. See [LICENSE](LICENSE).

Third-party dependencies keep their own licenses. Installing HumemDB may also install
third-party Python packages and, in some cases, their native wheels. Those components
are not relicensed under MIT just because HumemDB depends on them.

For the concrete dependency set, see [pyproject.toml](pyproject.toml) and
[uv.lock](uv.lock).
