Metadata-Version: 2.4
Name: motedb-python
Version: 0.12.7
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Implementation :: CPython
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
License-File: licenses/LICENSE
Summary: AI-native embedded multimodal database — SQL, vectors, full-text, spatial and time-series in one ACID engine, with edge presets for robots and edge devices.
Keywords: database,embedded-database,vector-search,full-text-search,spatial,time-series,rag,robotics,edge-ai,sql
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/motedb/motedb/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/motedb/motedb/tree/main/bindings/python
Project-URL: Homepage, https://github.com/motedb/motedb
Project-URL: Issues, https://github.com/motedb/motedb/issues
Project-URL: Repository, https://github.com/motedb/motedb
Project-URL: Source, https://github.com/motedb/motedb

# MoteDB Python Bindings

Embedded multimodal database for Python — SQL + vector search + full-text
search + spatial in one engine, with edge-presets for memory-constrained
devices.

## Install (from source)

```bash
pip install maturin
cd bindings/python
maturin develop --release
# no maturin / offline? scripts/build_wheel.sh builds a wheel with cargo+zip
```

## Quick start

```python
import motedb

db = motedb.Database("/data/store.mote", preset="edge")   # general|edge|robotics|embodied
db.execute("CREATE TABLE IF NOT EXISTS docs (id INT PRIMARY KEY AUTO_INCREMENT, text TEXT, emb VECTOR(384))")
db.execute("INSERT INTO docs (text, emb) VALUES (?, ?)", params=["hello world", [0.1] * 384])

rows = db.execute("SELECT id, text FROM docs WHERE text MATCH AGAINST('hello')")   # list[dict]
cols, tuples = db.query("SELECT id, text FROM docs")                               # (columns, list[tuple])

# Vector ANN — literal or parameter vectors both order correctly:
near = db.execute("SELECT id FROM docs ORDER BY emb <-> ? LIMIT 5", params=[[0.1] * 384])

tx = db.begin()
db.execute("UPDATE docs SET text = ? WHERE id = 1", params=["hi"])
db.rollback(tx)          # or db.commit(tx)

db.checkpoint()          # durability point
db.close()
```

## API

| Method | Notes |
|---|---|
| `Database(path, preset=None, create=True)` | create-or-open |
| `execute(sql, params=None)` | SELECT → `list[dict]`; DML → affected count; DDL → None |
| `query(sql, params=None)` | SELECT → `(columns, list[tuple])` |
| `executemany(sql, params)` | one INSERT per parameter set — single WAL fsync per batch |
| `begin()/commit(tx)/rollback(tx)` | transactions |
| `doctor()` | self-check → `{"verdict", "checks": [{name,status,detail}]}` |
| `checkpoint()/vacuum()/close()` | lifecycle |

Parameter types: `None/bool/int/float/str/list[float]` (→ embedding vector),
and geometry dicts for GEOMETRY columns:
`{"type": "Point3D", "x": 1.0, "y": -2.0, "z": 0.5}`,
`{"type": "Point", "x": 1.0, "y": -2.0}`,
`{"type": "LineString"|"Polygon", "points": [[x, y], ...]}`.
Result types: `None/bool/int/float/str/list[float]` (vector), timestamp as
int microseconds, geometry as the same dict shapes (tensor still renders as
a `<tensor>` tag).

## Benchmark

`bench/bench_edge.py` — reproducible edge-workload comparison vs stdlib
SQLite (see `bench/README.md` for methodology and reference numbers: point
2.9×, filter 3.7×, GROUP BY 9.8×, ANN 3.2×, RSS −12%; honest loss on batch
insert).

## Publishing

Wheels for 4 targets are built by `.github/workflows/python-wheels.yml` on
tag push; PyPI publishing uses Trusted Publisher (register the repo at
pypi.org → no token secret needed).

## Known gaps (pre-1.0)

- Tensor/Spatial/TextDoc values pass through as tags, not Python objects.

