pomaidb 0.1.0__tar.gz

pomaidb-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: pomaidb
+Version: 0.1.0
+Summary: Embedded vector database for Edge AI - fast in-process C-API bindings
+Author-email: PomaiDB Team <info@pomaidb.org>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/pomagrenate/pomaidb
+Project-URL: Repository, https://github.com/pomagrenate/pomaidb
+Keywords: vector,embeddings,hnsw,database,embedded,edge-ai
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# PomaiDB Python Bindings
+
+Official Python bindings for **PomaiDB**, an embedded vector database designed for high-performance Edge AI applications.
+
+## Installation
+
+```bash
+pip install pomaidb
+```
+
+## Quick Start
+
+```python
+import pomaidb
+
+# 1. Open database
+db = pomaidb.open_db("test_db", dim=4)
+
+# 2. Put vectors
+db.put(1, [1.0, 0.0, 0.0, 0.0])
+db.put(2, [0.0, 1.0, 0.0, 0.0], membrane="docs", payload=b"doc_payload", timestamp=1000)
+
+# 3. Search
+hits = db.search([1.0, 0.0, 0.0, 0.0], topk=5)
+for hit in hits:
+    print(f"ID: {hit.id}, Score: {hit.score}")
+
+# 4. Multi-membrane query
+hits_docs = db.search([0.0, 1.0, 0.0, 0.0], topk=5, membrane="docs")
+
+# 5. Flush and close
+db.flush()
+db.close()
+```
+
+## Features
+- In-process embedded execution (zero network overhead, zero configuration).
+- Pomegranate Engine Architecture: Rind MemTable, Locule immutable containers, and Press compaction.
+- Built-in Quantization: FP32, SQ8, FP16, 1-bit binary quantization, PQ8.
+- Native multi-membrane tenancy and arbitrary payload buffering.

pomaidb-0.1.0/README.md

@@ -0,0 +1,40 @@
+# PomaiDB Python Bindings
+
+Official Python bindings for **PomaiDB**, an embedded vector database designed for high-performance Edge AI applications.
+
+## Installation
+
+```bash
+pip install pomaidb
+```
+
+## Quick Start
+
+```python
+import pomaidb
+
+# 1. Open database
+db = pomaidb.open_db("test_db", dim=4)
+
+# 2. Put vectors
+db.put(1, [1.0, 0.0, 0.0, 0.0])
+db.put(2, [0.0, 1.0, 0.0, 0.0], membrane="docs", payload=b"doc_payload", timestamp=1000)
+
+# 3. Search
+hits = db.search([1.0, 0.0, 0.0, 0.0], topk=5)
+for hit in hits:
+    print(f"ID: {hit.id}, Score: {hit.score}")
+
+# 4. Multi-membrane query
+hits_docs = db.search([0.0, 1.0, 0.0, 0.0], topk=5, membrane="docs")
+
+# 5. Flush and close
+db.flush()
+db.close()
+```
+
+## Features
+- In-process embedded execution (zero network overhead, zero configuration).
+- Pomegranate Engine Architecture: Rind MemTable, Locule immutable containers, and Press compaction.
+- Built-in Quantization: FP32, SQ8, FP16, 1-bit binary quantization, PQ8.
+- Native multi-membrane tenancy and arbitrary payload buffering.

pomaidb-0.1.0/pomaidb/__init__.py

@@ -0,0 +1,657 @@
+"""
+PomaiDB — embedded vector database for Edge AI.
+
+Use the C library (libpomai_c.so / libpomai_c.dylib / pomai_c.dll) via ctypes.
+Set POMAI_C_LIB to the path to the shared library, or build from source
+and point to build/libpomai_c.so (Linux) or build/pomai_c.dll (Windows).
+"""
+
+import ctypes
+import json
+import os
+import sys
+from pathlib import Path
+
+__all__ = [
+    "Database", "open_db", "close", "flush", "put", "put_batch", "delete", "exists", "get",
+    "search", "search_batch", "search_zero_copy", "release_zero_copy_session",
+    "freeze", "compact", "compact_membrane", "create_membrane", "drop_membrane",
+    "open_membrane", "close_membrane", "list_membranes", "get_stats",
+    "resolve_effective_options", "PomaiDBError",
+    "MEMBRANE_KIND_VECTOR",
+    "QUANT_NONE", "QUANT_SQ8", "QUANT_FP16", "QUANT_BIT", "QUANT_PQ8",
+]
+
+MEMBRANE_KIND_VECTOR = 0
+
+QUANT_NONE = 0
+QUANT_SQ8 = 1
+QUANT_FP16 = 2
+QUANT_BIT = 3
+QUANT_PQ8 = 4
+
+class PomaiDBError(Exception):
+    pass
+
+def _find_lib():
+    env = os.environ.get("POMAI_C_LIB")
+    if env and os.path.exists(env):
+        return env
+    pkg_dir = Path(__file__).resolve().parent
+    for name in ["libpomai_c.dll", "pomai_c.dll", "libpomai_c.so", "libpomai_c.dylib"]:
+        if (pkg_dir / "lib" / name).is_file():
+            return str(pkg_dir / "lib" / name)
+        if (pkg_dir / name).is_file():
+            return str(pkg_dir / name)
+    for base in [Path(__file__).resolve().parents[3], Path(__file__).resolve().parents[2], Path.cwd()]:
+        for name in ["libpomai_c.so", "libpomai_c.dylib", "pomai_c.dll", "libpomai_c.dll"]:
+            p = base / "build" / name
+            if p.exists():
+                return str(p)
+            p_bin = base / "build" / "bin" / name
+            if p_bin.exists():
+                return str(p_bin)
+    return None
+
+_lib_path = _find_lib()
+_lib = None
+
+def _ensure_lib():
+    global _lib
+    if _lib is not None:
+        return
+    path = _find_lib()
+    if not path or not os.path.isfile(path):
+        raise PomaiDBError(
+            "PomaiDB C library not found. Set POMAI_C_LIB to path to libpomai_c.so (or .dll/.dylib), "
+            "or build the project and run from repo root."
+        )
+    if sys.platform == "win32" and hasattr(os, "add_dll_directory"):
+        dll_dir = os.path.dirname(os.path.abspath(path))
+        if os.path.isdir(dll_dir):
+            try:
+                os.add_dll_directory(dll_dir)
+            except Exception:
+                pass
+        for p in os.environ.get("PATH", "").split(os.pathsep):
+            if p and os.path.isdir(p):
+                try:
+                    os.add_dll_directory(p)
+                except Exception:
+                    pass
+    _lib = ctypes.CDLL(path)
+    _register_api(_lib)
+
+def _register_api(lib):
+    class PomaiOptions(ctypes.Structure):
+        _fields_ = [
+            ("struct_size", ctypes.c_uint32),
+            ("path", ctypes.c_char_p),
+            ("shards", ctypes.c_uint32),
+            ("dim", ctypes.c_uint32),
+            ("search_threads", ctypes.c_uint32),
+            ("fsync_policy", ctypes.c_int),
+            ("memory_budget_bytes", ctypes.c_uint64),
+            ("deadline_ms", ctypes.c_uint32),
+            ("index_type", ctypes.c_uint8),
+            ("hnsw_m", ctypes.c_uint32),
+            ("hnsw_ef_construction", ctypes.c_uint32),
+            ("hnsw_ef_search", ctypes.c_uint32),
+            ("adaptive_threshold", ctypes.c_uint32),
+            ("metric", ctypes.c_uint8),
+            ("edge_profile", ctypes.c_uint8),
+            ("tick_max_ops", ctypes.c_uint32),
+            ("tick_max_ms", ctypes.c_uint32),
+            ("strict_deterministic", ctypes.c_bool),
+            ("quant_type", ctypes.c_uint8),
+            ("pq_m", ctypes.c_uint32),
+            ("memtable_flush_threshold_mb", ctypes.c_uint32),
+            ("auto_freeze_on_pressure", ctypes.c_bool),
+            ("max_memtable_mb", ctypes.c_uint32),
+            ("write_coalesce_window_us", ctypes.c_uint32),
+            ("write_coalesce_batch_size", ctypes.c_uint32),
+            ("enable_encryption_at_rest", ctypes.c_bool),
+            ("encryption_key_hex", ctypes.c_char_p),
+        ]
+
+    class PomaiUpsert(ctypes.Structure):
+        _fields_ = [
+            ("struct_size", ctypes.c_uint32),
+            ("id", ctypes.c_uint64),
+            ("vector", ctypes.POINTER(ctypes.c_float)),
+            ("dim", ctypes.c_uint32),
+            ("metadata", ctypes.POINTER(ctypes.c_uint8)),
+            ("metadata_len", ctypes.c_uint32),
+            ("membrane", ctypes.c_char_p),
+            ("timestamp", ctypes.c_uint64),
+            ("payload", ctypes.POINTER(ctypes.c_uint8)),
+            ("payload_len", ctypes.c_uint32),
+        ]
+
+    class PomaiQuery(ctypes.Structure):
+        _fields_ = [
+            ("struct_size", ctypes.c_uint32),
+            ("vector", ctypes.POINTER(ctypes.c_float)),
+            ("dim", ctypes.c_uint32),
+            ("topk", ctypes.c_uint32),
+            ("filter_expression", ctypes.c_char_p),
+            ("partition_device_id", ctypes.c_char_p),
+            ("partition_location_id", ctypes.c_char_p),
+            ("deadline_ms", ctypes.c_uint32),
+            ("flags", ctypes.c_uint32),
+            ("membrane", ctypes.c_char_p),
+            ("as_of_ts", ctypes.c_uint64),
+            ("as_of_lsn", ctypes.c_uint64),
+        ]
+
+    class PomaiSemanticPointer(ctypes.Structure):
+        _fields_ = [
+            ("struct_size", ctypes.c_uint32),
+            ("raw_data_ptr", ctypes.c_void_p),
+            ("dim", ctypes.c_uint32),
+            ("quant_min", ctypes.c_float),
+            ("quant_inv_scale", ctypes.c_float),
+            ("session_id", ctypes.c_uint64),
+        ]
+
+    class PomaiSearchResults(ctypes.Structure):
+        _fields_ = [
+            ("struct_size", ctypes.c_uint32),
+            ("count", ctypes.c_size_t),
+            ("ids", ctypes.POINTER(ctypes.c_uint64)),
+            ("scores", ctypes.POINTER(ctypes.c_float)),
+            ("shard_ids", ctypes.POINTER(ctypes.c_uint32)),
+            ("total_shards_count", ctypes.c_uint32),
+            ("pruned_shards_count", ctypes.c_uint32),
+            ("zero_copy_pointers", ctypes.POINTER(PomaiSemanticPointer)),
+        ]
+
+    class PomaiRecord(ctypes.Structure):
+        _fields_ = [
+            ("struct_size", ctypes.c_uint32),
+            ("id", ctypes.c_uint64),
+            ("dim", ctypes.c_uint32),
+            ("vector", ctypes.POINTER(ctypes.c_float)),
+            ("metadata", ctypes.POINTER(ctypes.c_uint8)),
+            ("metadata_len", ctypes.c_uint32),
+            ("is_deleted", ctypes.c_bool),
+            ("timestamp", ctypes.c_uint64),
+            ("payload", ctypes.POINTER(ctypes.c_uint8)),
+            ("payload_len", ctypes.c_uint32),
+        ]
+
+    lib.PomaiOptions = PomaiOptions
+    lib.PomaiUpsert = PomaiUpsert
+    lib.PomaiQuery = PomaiQuery
+    lib.PomaiSemanticPointer = PomaiSemanticPointer
+    lib.PomaiSearchResults = PomaiSearchResults
+    lib.PomaiRecord = PomaiRecord
+
+    lib.pomai_options_init.argtypes = [ctypes.POINTER(PomaiOptions)]
+    lib.pomai_options_init.restype = None
+
+    lib.pomai_open.argtypes = [ctypes.POINTER(PomaiOptions), ctypes.POINTER(ctypes.c_void_p)]
+    lib.pomai_open.restype = ctypes.c_void_p
+
+    lib.pomai_close.argtypes = [ctypes.c_void_p]
+    lib.pomai_close.restype = ctypes.c_void_p
+
+    lib.pomai_flush.argtypes = [ctypes.c_void_p]
+    lib.pomai_flush.restype = ctypes.c_void_p
+
+    lib.pomai_compact.argtypes = [ctypes.c_void_p]
+    lib.pomai_compact.restype = ctypes.c_void_p
+
+    lib.pomai_freeze.argtypes = [ctypes.c_void_p]
+    lib.pomai_freeze.restype = ctypes.c_void_p
+
+    lib.pomai_freeze_membrane.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+    lib.pomai_freeze_membrane.restype = ctypes.c_void_p
+
+    lib.pomai_put.argtypes = [ctypes.c_void_p, ctypes.POINTER(PomaiUpsert)]
+    lib.pomai_put.restype = ctypes.c_void_p
+
+    lib.pomai_put_batch.argtypes = [ctypes.c_void_p, ctypes.POINTER(PomaiUpsert), ctypes.c_size_t]
+    lib.pomai_put_batch.restype = ctypes.c_void_p
+
+    lib.pomai_delete.argtypes = [ctypes.c_void_p, ctypes.c_uint64]
+    lib.pomai_delete.restype = ctypes.c_void_p
+
+    lib.pomai_exists.argtypes = [ctypes.c_void_p, ctypes.c_uint64, ctypes.POINTER(ctypes.c_bool)]
+    lib.pomai_exists.restype = ctypes.c_void_p
+
+    lib.pomai_get.argtypes = [ctypes.c_void_p, ctypes.c_uint64, ctypes.POINTER(ctypes.POINTER(PomaiRecord))]
+    lib.pomai_get.restype = ctypes.c_void_p
+
+    lib.pomai_record_free.argtypes = [ctypes.POINTER(PomaiRecord)]
+    lib.pomai_record_free.restype = None
+
+    lib.pomai_search.argtypes = [ctypes.c_void_p, ctypes.POINTER(PomaiQuery), ctypes.POINTER(ctypes.POINTER(PomaiSearchResults))]
+    lib.pomai_search.restype = ctypes.c_void_p
+
+    lib.pomai_search_results_free.argtypes = [ctypes.POINTER(PomaiSearchResults)]
+    lib.pomai_search_results_free.restype = None
+
+    lib.pomai_search_batch.argtypes = [
+        ctypes.c_void_p, ctypes.POINTER(PomaiQuery), ctypes.c_size_t,
+        ctypes.POINTER(ctypes.POINTER(PomaiSearchResults))
+    ]
+    lib.pomai_search_batch.restype = ctypes.c_void_p
+
+    lib.pomai_search_batch_free.argtypes = [ctypes.POINTER(PomaiSearchResults), ctypes.c_size_t]
+    lib.pomai_search_batch_free.restype = None
+
+    lib.pomai_create_membrane_kind.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.uint32 if hasattr(ctypes, "uint32") else ctypes.c_uint32, ctypes.c_uint32, ctypes.c_uint32]
+    lib.pomai_create_membrane_kind.restype = ctypes.c_void_p
+
+    lib.pomai_drop_membrane.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+    lib.pomai_drop_membrane.restype = ctypes.c_void_p
+
+    lib.pomai_open_membrane.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+    lib.pomai_open_membrane.restype = ctypes.c_void_p
+
+    lib.pomai_close_membrane.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+    lib.pomai_close_membrane.restype = ctypes.c_void_p
+
+    lib.pomai_list_membranes_json.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_char_p), ctypes.POINTER(ctypes.c_size_t)]
+    lib.pomai_list_membranes_json.restype = ctypes.c_void_p
+
+    lib.pomai_compact_membrane.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+    lib.pomai_compact_membrane.restype = ctypes.c_void_p
+
+    lib.pomai_get_stats_json.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_char_p), ctypes.POINTER(ctypes.c_size_t)]
+    lib.pomai_get_stats_json.restype = ctypes.c_void_p
+
+    lib.pomai_put_membrane.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.POINTER(PomaiUpsert)]
+    lib.pomai_put_membrane.restype = ctypes.c_void_p
+
+    lib.pomai_put_batch_membrane.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.POINTER(PomaiUpsert), ctypes.c_size_t]
+    lib.pomai_put_batch_membrane.restype = ctypes.c_void_p
+
+    lib.pomai_get_membrane.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_uint64, ctypes.POINTER(ctypes.POINTER(PomaiRecord))]
+    lib.pomai_get_membrane.restype = ctypes.c_void_p
+
+    lib.pomai_delete_membrane.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_uint64]
+    lib.pomai_delete_membrane.restype = ctypes.c_void_p
+
+    lib.pomai_exists_membrane.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_uint64, ctypes.POINTER(ctypes.c_bool)]
+    lib.pomai_exists_membrane.restype = ctypes.c_void_p
+
+    lib.pomai_search_membrane.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.POINTER(PomaiQuery), ctypes.POINTER(ctypes.POINTER(PomaiSearchResults))]
+    lib.pomai_search_membrane.restype = ctypes.c_void_p
+
+    lib.pomai_release_pointer.argtypes = [ctypes.c_uint64]
+    lib.pomai_release_pointer.restype = None
+
+    lib.pomai_free.argtypes = [ctypes.c_void_p]
+    lib.pomai_free.restype = None
+
+    lib.pomai_status_message.argtypes = [ctypes.c_void_p]
+    lib.pomai_status_message.restype = ctypes.c_char_p
+
+    lib.pomai_status_free.argtypes = [ctypes.c_void_p]
+    lib.pomai_status_free.restype = None
+
+def _check_status(st):
+    if not st:
+        return
+    msg = _lib.pomai_status_message(st)
+    err = msg.decode("utf-8", errors="replace") if msg else "Unknown PomaiDB error"
+    _lib.pomai_status_free(st)
+    raise PomaiDBError(err)
+
+def open_db(path, dim, shards=1, metric="l2", edge_profile=0, quant_type=0, memory_budget_bytes=0, auto_freeze_on_pressure=True, memtable_flush_threshold_mb=64):
+    _ensure_lib()
+    opts = _lib.PomaiOptions()
+    _lib.pomai_options_init(ctypes.byref(opts))
+    opts.path = path.encode("utf-8")
+    opts.dim = dim
+    opts.shards = shards
+    opts.metric = 2 if metric.lower() == "cosine" else (1 if metric.lower() in ("ip", "innerproduct") else 0)
+    opts.edge_profile = edge_profile
+    opts.quant_type = quant_type
+    opts.memory_budget_bytes = memory_budget_bytes
+    opts.auto_freeze_on_pressure = auto_freeze_on_pressure
+    opts.memtable_flush_threshold_mb = memtable_flush_threshold_mb
+    db_ptr = ctypes.c_void_p()
+    st = _lib.pomai_open(ctypes.byref(opts), ctypes.byref(db_ptr))
+    _check_status(st)
+    return db_ptr
+
+def close(db):
+    if db:
+        _check_status(_lib.pomai_close(db))
+
+def flush(db):
+    if db:
+        _check_status(_lib.pomai_flush(db))
+
+def freeze(db, membrane=""):
+    if membrane:
+        _check_status(_lib.pomai_freeze_membrane(db, membrane.encode("utf-8")))
+    else:
+        _check_status(_lib.pomai_freeze(db))
+
+def compact(db):
+    if db:
+        _check_status(_lib.pomai_compact(db))
+
+def compact_membrane(db, name):
+    _check_status(_lib.pomai_compact_membrane(db, name.encode("utf-8")))
+
+def put(db, id, vector, tenant="", membrane="", timestamp=0, payload=b""):
+    _ensure_lib()
+    up = _lib.PomaiUpsert()
+    up.struct_size = ctypes.sizeof(_lib.PomaiUpsert)
+    up.id = id
+    up.dim = len(vector)
+    c_floats = (ctypes.c_float * len(vector))(*vector)
+    up.vector = c_floats
+    if tenant:
+        t_bytes = tenant.encode("utf-8")
+        up.metadata = (ctypes.c_uint8 * len(t_bytes))(*t_bytes)
+        up.metadata_len = len(t_bytes)
+    if membrane:
+        up.membrane = membrane.encode("utf-8")
+    up.timestamp = timestamp
+    if payload:
+        p_bytes = payload if isinstance(payload, (bytes, bytearray)) else str(payload).encode("utf-8")
+        up.payload = (ctypes.c_uint8 * len(p_bytes))(*p_bytes)
+        up.payload_len = len(p_bytes)
+    _check_status(_lib.pomai_put(db, ctypes.byref(up)))
+
+def put_batch(db, ids, vectors, tenants=None, membrane=""):
+    _ensure_lib()
+    n = len(ids)
+    if n == 0:
+        return
+    arr_type = _lib.PomaiUpsert * n
+    arr = arr_type()
+    keep_alive = []
+    memb_bytes = membrane.encode("utf-8") if membrane else None
+    for i in range(n):
+        arr[i].struct_size = ctypes.sizeof(_lib.PomaiUpsert)
+        arr[i].id = ids[i]
+        arr[i].dim = len(vectors[i])
+        c_v = (ctypes.c_float * len(vectors[i]))(*vectors[i])
+        arr[i].vector = c_v
+        keep_alive.append(c_v)
+        if memb_bytes:
+            arr[i].membrane = memb_bytes
+        if tenants and i < len(tenants) and tenants[i]:
+            t_b = tenants[i].encode("utf-8")
+            c_m = (ctypes.c_uint8 * len(t_b))(*t_b)
+            arr[i].metadata = c_m
+            arr[i].metadata_len = len(t_b)
+            keep_alive.append(c_m)
+    _check_status(_lib.pomai_put_batch(db, arr, n))
+
+def delete(db, id, membrane=""):
+    if membrane:
+        _check_status(_lib.pomai_delete_membrane(db, membrane.encode("utf-8"), id))
+    else:
+        _check_status(_lib.pomai_delete(db, id))
+
+def exists(db, id, membrane=""):
+    out = ctypes.c_bool()
+    if membrane:
+        _check_status(_lib.pomai_exists_membrane(db, membrane.encode("utf-8"), id, ctypes.byref(out)))
+    else:
+        _check_status(_lib.pomai_exists(db, id, ctypes.byref(out)))
+    return out.value
+
+class Hit(tuple):
+    """Search hit (id, score) supporting tuple indexing, dict keys, and attributes."""
+    def __new__(cls, id, score):
+        return super(Hit, cls).__new__(cls, (id, score))
+    @property
+    def id(self):
+        return self[0]
+    @property
+    def score(self):
+        return self[1]
+    def __getitem__(self, item):
+        if item == "id":
+            return self[0]
+        if item == "score":
+            return self[1]
+        return super().__getitem__(item)
+    def __repr__(self):
+        return f"Hit(id={self[0]}, score={self[1]})"
+
+def get(db, id, membrane=""):
+    rec_ptr = ctypes.POINTER(_lib.PomaiRecord)()
+    if membrane:
+        _check_status(_lib.pomai_get_membrane(db, membrane.encode("utf-8"), id, ctypes.byref(rec_ptr)))
+    else:
+        _check_status(_lib.pomai_get(db, id, ctypes.byref(rec_ptr)))
+    if not rec_ptr:
+        return None
+    r = rec_ptr.contents
+    vec = [r.vector[i] for i in range(r.dim)]
+    meta = ""
+    if r.metadata and r.metadata_len > 0:
+        meta = bytes(r.metadata[:r.metadata_len]).decode("utf-8", errors="replace")
+    payload = b""
+    if r.payload and r.payload_len > 0:
+        payload = bytes(r.payload[:r.payload_len])
+    dim = r.dim
+    ts = r.timestamp
+    _lib.pomai_record_free(rec_ptr)
+    return {"id": id, "dim": dim, "vector": vec, "tenant": meta, "timestamp": ts, "payload": payload}
+
+def search(db, query_vector, topk=10, tenant="", membrane="", as_of_ts=0, as_of_lsn=0):
+    _ensure_lib()
+    q = _lib.PomaiQuery()
+    q.struct_size = ctypes.sizeof(_lib.PomaiQuery)
+    c_v = (ctypes.c_float * len(query_vector))(*query_vector)
+    q.vector = c_v
+    q.dim = len(query_vector)
+    q.topk = topk
+    if tenant:
+        q.filter_expression = f"tenant={tenant}".encode("utf-8")
+    if membrane:
+        q.membrane = membrane.encode("utf-8")
+    q.as_of_ts = as_of_ts
+    q.as_of_lsn = as_of_lsn
+    res_ptr = ctypes.POINTER(_lib.PomaiSearchResults)()
+    _check_status(_lib.pomai_search(db, ctypes.byref(q), ctypes.byref(res_ptr)))
+    if not res_ptr:
+        return []
+    res = res_ptr.contents
+    hits = [Hit(res.ids[i], res.scores[i]) for i in range(res.count)]
+    _lib.pomai_search_results_free(res_ptr)
+    return hits
+
+def search_batch(db, query_vectors, topk=10, membrane=""):
+    _ensure_lib()
+    n = len(query_vectors)
+    if n == 0:
+        return []
+    arr_type = _lib.PomaiQuery * n
+    arr = arr_type()
+    keep_alive = []
+    dim = len(query_vectors[0])
+    memb_bytes = membrane.encode("utf-8") if membrane else None
+    for i in range(n):
+        arr[i].struct_size = ctypes.sizeof(_lib.PomaiQuery)
+        c_v = (ctypes.c_float * dim)(*query_vectors[i])
+        arr[i].vector = c_v
+        arr[i].dim = dim
+        arr[i].topk = topk
+        if memb_bytes:
+            arr[i].membrane = memb_bytes
+        keep_alive.append(c_v)
+    res_ptr = ctypes.POINTER(_lib.PomaiSearchResults)()
+    _check_status(_lib.pomai_search_batch(db, arr, n, ctypes.byref(res_ptr)))
+    if not res_ptr:
+        return []
+    out = []
+    for i in range(n):
+        r = res_ptr[i]
+        hits = [Hit(r.ids[j], r.scores[j]) for j in range(r.count)] if r.count > 0 else []
+        out.append(hits)
+    _lib.pomai_search_batch_free(res_ptr, n)
+    return out
+
+def search_zero_copy(db, query_vector, topk=10, membrane=""):
+    _ensure_lib()
+    q = _lib.PomaiQuery()
+    q.struct_size = ctypes.sizeof(_lib.PomaiQuery)
+    c_v = (ctypes.c_float * len(query_vector))(*query_vector)
+    q.vector = c_v
+    q.dim = len(query_vector)
+    q.topk = topk
+    q.flags = 1  # ZERO_COPY
+    if membrane:
+        q.membrane = membrane.encode("utf-8")
+    res_ptr = ctypes.POINTER(_lib.PomaiSearchResults)()
+    _check_status(_lib.pomai_search(db, ctypes.byref(q), ctypes.byref(res_ptr)))
+    if not res_ptr:
+        return {"hits": [], "session_id": 0}
+    res = res_ptr.contents
+    hits = [{"id": res.ids[i], "score": res.scores[i]} for i in range(res.count)]
+    sess_id = res.zero_copy_pointers[0].session_id if res.count > 0 and res.zero_copy_pointers else 0
+    _lib.pomai_search_results_free(res_ptr)
+    return {"hits": hits, "session_id": sess_id}
+
+def release_zero_copy_session(session_id):
+    if session_id:
+        _lib.pomai_release_pointer(session_id)
+
+def create_membrane(db, name, dim, shard_count=1):
+    _check_status(_lib.pomai_create_membrane_kind(db, name.encode("utf-8"), dim, shard_count, 0))
+
+def drop_membrane(db, name):
+    _check_status(_lib.pomai_drop_membrane(db, name.encode("utf-8")))
+
+def open_membrane(db, name):
+    _check_status(_lib.pomai_open_membrane(db, name.encode("utf-8")))
+
+def close_membrane(db, name):
+    _check_status(_lib.pomai_close_membrane(db, name.encode("utf-8")))
+
+def list_membranes(db):
+    out_json = ctypes.c_char_p()
+    out_len = ctypes.c_size_t()
+    _check_status(_lib.pomai_list_membranes_json(db, ctypes.byref(out_json), ctypes.byref(out_len)))
+    if not out_json.value:
+        return []
+    s = out_json.value.decode("utf-8")
+    _lib.pomai_free(ctypes.cast(out_json, ctypes.c_void_p))
+    return json.loads(s)
+
+def get_stats(db):
+    out_json = ctypes.c_char_p()
+    out_len = ctypes.c_size_t()
+    _check_status(_lib.pomai_get_stats_json(db, ctypes.byref(out_json), ctypes.byref(out_len)))
+    if not out_json.value:
+        return {}
+    s = out_json.value.decode("utf-8")
+    _lib.pomai_free(ctypes.cast(out_json, ctypes.c_void_p))
+    return json.loads(s)
+
+def resolve_effective_options(path, dim, shards=1, edge_profile=0):
+    _ensure_lib()
+    opts = _lib.PomaiOptions()
+    _lib.pomai_options_init(ctypes.byref(opts))
+    opts.path = path.encode("utf-8")
+    opts.dim = dim
+    opts.shards = shards
+    opts.edge_profile = edge_profile
+    out_json = ctypes.c_char_p()
+    out_len = ctypes.c_size_t()
+    _check_status(_lib.pomai_options_resolve_json(ctypes.byref(opts), ctypes.byref(out_json), ctypes.byref(out_len)))
+    s = out_json.value.decode("utf-8")
+    _lib.pomai_free(ctypes.cast(out_json, ctypes.c_void_p))
+    return json.loads(s)
+
+
+class Database:
+    """Object-oriented wrapper around a PomaiDB database handle."""
+    def __init__(self, handle):
+        self._handle = handle
+
+    @classmethod
+    def open(cls, path, dim, shards=1, metric="l2", quant_type=QUANT_NONE, **kwargs):
+        h = open_db(path, dim, shards=shards, metric=metric, quant_type=quant_type, **kwargs)
+        return cls(h)
+
+    def close(self):
+        if self._handle:
+            close(self._handle)
+            self._handle = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def put(self, id, vector, membrane=None, timestamp=0, payload=None):
+        put(self._handle, id, vector, membrane=membrane, timestamp=timestamp, payload=payload)
+
+    def put_batch(self, ids, vectors, membrane=None):
+        put_batch(self._handle, ids, vectors, membrane=membrane)
+
+    def get(self, id, membrane=None, with_metadata=False):
+        res = get(self._handle, id, membrane=membrane)
+        if not with_metadata and isinstance(res, dict) and "vector" in res:
+            return res["vector"]
+        if with_metadata and isinstance(res, dict):
+            class Record:
+                def __init__(self, d):
+                    self.id = d.get("id")
+                    self.vector = d.get("vector")
+                    self.dim = d.get("dim")
+                    self.timestamp = d.get("timestamp")
+                    self.payload = d.get("payload")
+            return Record(res)
+        return res
+
+    def exists(self, id, membrane=None):
+        return exists(self._handle, id, membrane=membrane)
+
+    def delete(self, id, membrane=None):
+        delete(self._handle, id, membrane=membrane)
+
+    def search(self, query, topk=10, membrane=None, as_of_ts=0):
+        class Hit:
+            def __init__(self, item):
+                self.id = item[0]
+                self.score = item[1]
+            def __repr__(self):
+                return f"Hit(id={self.id}, score={self.score})"
+        raw = search(self._handle, query, topk=topk, membrane=membrane, as_of_ts=as_of_ts)
+        return [Hit(item) for item in raw]
+
+    def search_batch(self, queries, topk=10, membrane=None, as_of_ts=0):
+        return search_batch(self._handle, queries, topk=topk, membrane=membrane, as_of_ts=as_of_ts)
+
+    def flush(self):
+        flush(self._handle)
+
+    def freeze(self, membrane=None):
+        freeze(self._handle, membrane=membrane)
+
+    def compact(self, membrane=None):
+        compact(self._handle, membrane=membrane)
+
+    def create_membrane(self, name, dim, shard_count=1):
+        create_membrane(self._handle, name, dim, shard_count=shard_count)
+
+    def drop_membrane(self, name):
+        drop_membrane(self._handle, name)
+
+    def open_membrane(self, name):
+        open_membrane(self._handle, name)
+
+    def close_membrane(self, name):
+        close_membrane(self._handle, name)
+
+    def list_membranes(self):
+        return list_membranes(self._handle)
+
+    def get_stats(self):
+        return get_stats(self._handle)
+

pomaidb-0.1.0/pomaidb/zero_copy.py

@@ -0,0 +1,93 @@
+"""
+Zero-copy helpers for PomaiDB search results.
+
+This module uses the existing C ABI zero-copy semantic pointer path
+(`POMAI_QUERY_FLAG_ZERO_COPY`) and maps the returned memory into NumPy
+without copying.
+"""
+
+from __future__ import annotations
+
+import ctypes
+
+from . import _ensure_lib, _lib, PomaiDBError
+
+POMAI_QUERY_FLAG_ZERO_COPY = 1
+
+
+def release_zero_copy_session(session_id: int) -> None:
+    """Release a pinned zero-copy session id."""
+    _ensure_lib()
+    _lib.pomai_release_pointer(int(session_id))
+
+
+def search_zero_copy(db, query, topk: int = 10):
+    """
+    Execute one query with zero-copy enabled.
+
+    Returns list of dicts:
+      {"id", "score", "raw_u8", "dequant_f32", "session_id"}
+    """
+    _ensure_lib()
+    try:
+        import numpy as np
+    except Exception as exc:
+        raise PomaiDBError("numpy is required for zero-copy helpers") from exc
+
+    dim = len(query)
+    qvec = (ctypes.c_float * dim)(*query)
+    q = _lib._pomai_query()
+    q.struct_size = ctypes.sizeof(_lib._pomai_query())
+    q.vector = qvec
+    q.dim = dim
+    q.topk = int(topk)
+    q.filter_expression = None
+    q.partition_device_id = None
+    q.partition_location_id = None
+    q.as_of_ts = 0
+    q.as_of_lsn = 0
+    q.aggregate_op = 0
+    q.aggregate_field = None
+    q.aggregate_topk = 0
+    q.mesh_detail_preference = 0
+    q.alpha = 1.0
+    q.deadline_ms = 0
+    q.flags = POMAI_QUERY_FLAG_ZERO_COPY
+
+    out = ctypes.POINTER(_lib._pomai_search_results)()
+    st = _lib.pomai_search(db, ctypes.byref(q), ctypes.byref(out))
+    if st:
+        msg = _lib.pomai_status_message(st).decode("utf-8", errors="replace")
+        _lib.pomai_status_free(st)
+        raise PomaiDBError(msg)
+
+    rows = []
+    try:
+        count = out.contents.count
+        pointers = out.contents.zero_copy_pointers
+        for i in range(min(int(topk), count)):
+            session_id = 0
+            raw_u8 = None
+            dequant_f32 = None
+            if pointers:
+                p = pointers[i]
+                session_id = int(p.session_id)
+                if p.raw_data_ptr and p.dim > 0:
+                    addr = int(ctypes.cast(p.raw_data_ptr, ctypes.c_void_p).value or 0)
+                    if addr:
+                        buf = (ctypes.c_uint8 * int(p.dim)).from_address(addr)
+                        raw_u8 = np.frombuffer(buf, dtype=np.uint8, count=int(p.dim))
+                        dequant_f32 = raw_u8.astype(np.float32) * float(p.quant_inv_scale) + float(p.quant_min)
+            rows.append(
+                {
+                    "id": int(out.contents.ids[i]),
+                    "score": float(out.contents.scores[i]),
+                    "raw_u8": raw_u8,
+                    "dequant_f32": dequant_f32,
+                    "session_id": session_id,
+                }
+            )
+        return rows
+    finally:
+        _lib.pomai_search_results_free(out)
+

pomaidb-0.1.0/pomaidb.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: pomaidb
+Version: 0.1.0
+Summary: Embedded vector database for Edge AI - fast in-process C-API bindings
+Author-email: PomaiDB Team <info@pomaidb.org>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/pomagrenate/pomaidb
+Project-URL: Repository, https://github.com/pomagrenate/pomaidb
+Keywords: vector,embeddings,hnsw,database,embedded,edge-ai
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# PomaiDB Python Bindings
+
+Official Python bindings for **PomaiDB**, an embedded vector database designed for high-performance Edge AI applications.
+
+## Installation
+
+```bash
+pip install pomaidb
+```
+
+## Quick Start
+
+```python
+import pomaidb
+
+# 1. Open database
+db = pomaidb.open_db("test_db", dim=4)
+
+# 2. Put vectors
+db.put(1, [1.0, 0.0, 0.0, 0.0])
+db.put(2, [0.0, 1.0, 0.0, 0.0], membrane="docs", payload=b"doc_payload", timestamp=1000)
+
+# 3. Search
+hits = db.search([1.0, 0.0, 0.0, 0.0], topk=5)
+for hit in hits:
+    print(f"ID: {hit.id}, Score: {hit.score}")
+
+# 4. Multi-membrane query
+hits_docs = db.search([0.0, 1.0, 0.0, 0.0], topk=5, membrane="docs")
+
+# 5. Flush and close
+db.flush()
+db.close()
+```
+
+## Features
+- In-process embedded execution (zero network overhead, zero configuration).
+- Pomegranate Engine Architecture: Rind MemTable, Locule immutable containers, and Press compaction.
+- Built-in Quantization: FP32, SQ8, FP16, 1-bit binary quantization, PQ8.
+- Native multi-membrane tenancy and arbitrary payload buffering.

pomaidb-0.1.0/pomaidb.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+setup.py
+pomaidb/__init__.py
+pomaidb/py.typed
+pomaidb/zero_copy.py
+pomaidb.egg-info/PKG-INFO
+pomaidb.egg-info/SOURCES.txt
+pomaidb.egg-info/dependency_links.txt
+pomaidb.egg-info/not-zip-safe
+pomaidb.egg-info/top_level.txt
+pomaidb/lib/libpomai_c.dll
+tests/test_binding.py

pomaidb-0.1.0/pomaidb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pomaidb-0.1.0/pomaidb.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

pomaidb-0.1.0/pomaidb.egg-info/top_level.txt

@@ -0,0 +1 @@
+pomaidb

pomaidb-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pomaidb"
+version = "0.1.0"
+description = "Embedded vector database for Edge AI - fast in-process C-API bindings"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.8"
+authors = [{ name = "PomaiDB Team", email = "info@pomaidb.org" }]
+keywords = ["vector", "embeddings", "hnsw", "database", "embedded", "edge-ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/pomagrenate/pomaidb"
+Repository = "https://github.com/pomagrenate/pomaidb"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["pomaidb*"]
+
+[tool.setuptools.package-data]
+pomaidb = ["lib/*", "*.dll", "*.so", "*.dylib", "py.typed"]

pomaidb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pomaidb-0.1.0/setup.py

@@ -0,0 +1,12 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="pomaidb",
+    version="0.1.0",
+    packages=find_packages(),
+    package_data={
+        "pomaidb": ["lib/*", "*.dll", "*.so", "*.dylib", "py.typed"],
+    },
+    include_package_data=True,
+    zip_safe=False,
+)

pomaidb-0.1.0/tests/test_binding.py

@@ -0,0 +1,62 @@
+import shutil
+import tempfile
+import unittest
+import pomaidb
+
+class TestPomaiDBBinding(unittest.TestCase):
+    def setUp(self):
+        self.test_dir = tempfile.mkdtemp(prefix="pomai_py_test_")
+
+    def tearDown(self):
+        shutil.rmtree(self.test_dir, ignore_errors=True)
+
+    def test_database_class_api(self):
+        db = pomaidb.Database.open(self.test_dir, dim=4)
+        self.assertIsNotNone(db)
+
+        # Put vector
+        db.put(1, [1.0, 0.0, 0.0, 0.0])
+        db.create_membrane("mem1", dim=4)
+        db.open_membrane("mem1")
+        db.put(2, [0.0, 1.0, 0.0, 0.0], membrane="mem1", payload=b"payload_val", timestamp=42)
+
+        # Exists
+        self.assertTrue(db.exists(1))
+        self.assertTrue(db.exists(2, membrane="mem1"))
+
+        # Get
+        v1 = db.get(1)
+        self.assertEqual(len(v1), 4)
+        self.assertAlmostEqual(v1[0], 1.0, places=3)
+
+        rec2 = db.get(2, membrane="mem1", with_metadata=True)
+        self.assertEqual(rec2.payload, b"payload_val")
+        self.assertEqual(rec2.timestamp, 42)
+
+        # Search
+        res = db.search([1.0, 0.0, 0.0, 0.0], topk=2)
+        self.assertTrue(len(res) >= 1)
+        self.assertEqual(res[0].id, 1)
+
+        # Stats
+        stats = db.get_stats()
+        self.assertIn("version", stats)
+
+        db.flush()
+        db.close()
+
+    def test_functional_c_api(self):
+        dir2 = tempfile.mkdtemp(prefix="pomai_py_c_")
+        try:
+            h = pomaidb.open_db(dir2, dim=4)
+            pomaidb.put(h, 10, [0.5, 0.5, 0.5, 0.5])
+            self.assertTrue(pomaidb.exists(h, 10))
+            v = pomaidb.get(h, 10)
+            self.assertEqual(v["id"], 10)
+            pomaidb.flush(h)
+            pomaidb.close(h)
+        finally:
+            shutil.rmtree(dir2, ignore_errors=True)
+
+if __name__ == "__main__":
+    unittest.main()