Metadata-Version: 2.4
Name: humemdb
Version: 0.1.0.dev0
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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Requires-Python: >=3.12
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)
[![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

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.

## 🧠 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 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 phase tracking: [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

The detailed internal roadmap and phase tracking now live in `things-to-do.md` instead
of this README.

## 📄 License

MIT.
