edgevdb 1.0.0__py3-none-any.whl

edgevdb/__init__.py

@@ -0,0 +1,401 @@
+# -*- coding: utf-8 -*-
+"""
+EdgeVDB Python SDK -- ctypes wrapper for desktop/Raspberry Pi.
+"""
+
+import ctypes
+import os
+import platform
+import json
+from pathlib import Path
+from typing import List, Dict, Any, Optional, Tuple
+
+# Library loading
+def _find_library() -> str:
+    """Find the EdgeVDB shared library."""
+    system = platform.system()
+    if system == "Windows":
+        names = ["libedgevdb_shared.dll", "edgevdb_shared.dll", "edgevdb.dll"]
+    elif system == "Darwin":
+        names = ["libedgevdb_shared.dylib", "libedgevdb.dylib"]
+    else:
+        names = ["libedgevdb_shared.so", "libedgevdb.so"]
+
+    # Search paths — platform-specific lib/ subdirectory first
+    pkg_dir = Path(__file__).parent
+    plat_dir = {"Windows": "windows", "Darwin": "darwin", "Linux": "linux"}.get(system, "linux")
+    search_dirs = [
+        pkg_dir / "lib" / plat_dir,
+        pkg_dir / "lib",
+        pkg_dir,
+        Path.cwd(),
+        Path.cwd() / "build",
+        Path.cwd() / "build" / "desktop-release" / "core",
+        Path.cwd() / "build" / "desktop-debug" / "core",
+    ]
+
+    for dir_path in search_dirs:
+        for name in names:
+            lib_path = dir_path / name
+            if lib_path.exists():
+                return str(lib_path)
+
+    raise FileNotFoundError(
+        f"Could not find EdgeVDB library. Searched: {[str(d) for d in search_dirs]}"
+    )
+
+
+class _Lib:
+    """Lazy-loaded library singleton."""
+    _instance = None
+
+    @classmethod
+    def get(cls):
+        if cls._instance is None:
+            cls._instance = ctypes.CDLL(_find_library())
+            cls._setup_signatures(cls._instance)
+        return cls._instance
+
+    @staticmethod
+    def _setup_signatures(lib):
+        # evdb_default_config
+        lib.evdb_default_config.argtypes = [ctypes.c_void_p]
+        lib.evdb_default_config.restype = None
+
+        # evdb_open
+        lib.evdb_open.argtypes = [ctypes.c_void_p]
+        lib.evdb_open.restype = ctypes.c_void_p
+
+        # evdb_close
+        lib.evdb_close.argtypes = [ctypes.c_void_p]
+        lib.evdb_close.restype = None
+
+        # evdb_save
+        lib.evdb_save.argtypes = [ctypes.c_void_p]
+        lib.evdb_save.restype = ctypes.c_int
+
+        # evdb_embedder_create
+        lib.evdb_embedder_create.argtypes = [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int]
+        lib.evdb_embedder_create.restype = ctypes.c_void_p
+
+        # evdb_embedder_destroy
+        lib.evdb_embedder_destroy.argtypes = [ctypes.c_void_p]
+        lib.evdb_embedder_destroy.restype = None
+
+        # evdb_embed_text
+        lib.evdb_embed_text.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.POINTER(ctypes.c_float)]
+        lib.evdb_embed_text.restype = ctypes.c_int
+
+        # evdb_insert_text
+        lib.evdb_insert_text.argtypes = [
+            ctypes.c_void_p, ctypes.c_void_p, ctypes.c_char_p,
+            ctypes.c_uint32, ctypes.c_uint32, ctypes.POINTER(ctypes.c_uint64)
+        ]
+        lib.evdb_insert_text.restype = ctypes.c_int
+
+        # evdb_insert_chunk
+        lib.evdb_insert_chunk.argtypes = [
+            ctypes.c_void_p, ctypes.c_char_p, ctypes.POINTER(ctypes.c_float),
+            ctypes.c_uint32, ctypes.c_uint32, ctypes.POINTER(ctypes.c_uint64)
+        ]
+        lib.evdb_insert_chunk.restype = ctypes.c_int
+
+        # evdb_remove_chunk
+        lib.evdb_remove_chunk.argtypes = [ctypes.c_void_p, ctypes.c_uint64]
+        lib.evdb_remove_chunk.restype = ctypes.c_int
+
+        # evdb_query_text
+        lib.evdb_query_text.argtypes = [
+            ctypes.c_void_p, ctypes.c_void_p, ctypes.c_char_p,
+            ctypes.c_int, ctypes.c_int
+        ]
+        lib.evdb_query_text.restype = ctypes.c_void_p
+
+        # evdb_query_vector
+        lib.evdb_query_vector.argtypes = [
+            ctypes.c_void_p, ctypes.POINTER(ctypes.c_float),
+            ctypes.c_char_p, ctypes.c_int
+        ]
+        lib.evdb_query_vector.restype = ctypes.c_void_p
+
+        # evdb_result_count / text / score / chunk_id / page / context
+        lib.evdb_result_count.argtypes = [ctypes.c_void_p]
+        lib.evdb_result_count.restype = ctypes.c_int
+
+        lib.evdb_result_text.argtypes = [ctypes.c_void_p, ctypes.c_int]
+        lib.evdb_result_text.restype = ctypes.c_char_p
+
+        lib.evdb_result_score.argtypes = [ctypes.c_void_p, ctypes.c_int]
+        lib.evdb_result_score.restype = ctypes.c_float
+
+        lib.evdb_result_chunk_id.argtypes = [ctypes.c_void_p, ctypes.c_int]
+        lib.evdb_result_chunk_id.restype = ctypes.c_uint64
+
+        lib.evdb_result_page.argtypes = [ctypes.c_void_p, ctypes.c_int]
+        lib.evdb_result_page.restype = ctypes.c_uint32
+
+        lib.evdb_result_context_string.argtypes = [ctypes.c_void_p]
+        lib.evdb_result_context_string.restype = ctypes.c_char_p
+
+        lib.evdb_query_free.argtypes = [ctypes.c_void_p]
+        lib.evdb_query_free.restype = None
+
+        # Object store
+        lib.evdb_object_put.argtypes = [
+            ctypes.c_void_p, ctypes.c_char_p, ctypes.c_char_p,
+            ctypes.POINTER(ctypes.c_uint64)
+        ]
+        lib.evdb_object_put.restype = ctypes.c_int
+
+        lib.evdb_object_get.argtypes = [
+            ctypes.c_void_p, ctypes.c_uint64, ctypes.c_char_p, ctypes.c_int
+        ]
+        lib.evdb_object_get.restype = ctypes.c_int
+
+        lib.evdb_object_remove.argtypes = [ctypes.c_void_p, ctypes.c_uint64]
+        lib.evdb_object_remove.restype = ctypes.c_int
+
+        # Relations
+        lib.evdb_relation_add.argtypes = [
+            ctypes.c_void_p, ctypes.c_char_p, ctypes.c_uint64, ctypes.c_uint64
+        ]
+        lib.evdb_relation_add.restype = ctypes.c_int
+
+        # Version
+        lib.evdb_version_string.argtypes = []
+        lib.evdb_version_string.restype = ctypes.c_char_p
+
+        # Log level
+        lib.evdb_set_log_level.argtypes = [ctypes.c_int]
+        lib.evdb_set_log_level.restype = None
+
+
+class EvdbConfig(ctypes.Structure):
+    _fields_ = [
+        ("storage_dir", ctypes.c_char_p),
+        ("hnsw_M", ctypes.c_int),
+        ("hnsw_ef_construction", ctypes.c_int),
+        ("hnsw_ef_search", ctypes.c_int),
+        ("ranker_alpha", ctypes.c_float),
+        ("ranker_beta", ctypes.c_float),
+        ("ranker_gamma", ctypes.c_float),
+        ("token_budget", ctypes.c_int),
+        ("embedding_threads", ctypes.c_int),
+        ("enable_knowledge_graph", ctypes.c_int),
+        ("enable_sync", ctypes.c_int),
+        ("device_id", ctypes.c_char_p),
+    ]
+
+
+class ChunkResult:
+    """A single query result chunk."""
+    def __init__(self, chunk_id: int, text: str, score: float,
+                 page_number: int, doc_id: int = 0):
+        self.chunk_id = chunk_id
+        self.text = text
+        self.score = score
+        self.page_number = page_number
+        self.doc_id = doc_id
+
+    def __repr__(self):
+        return f"ChunkResult(id={self.chunk_id}, score={self.score:.3f}, page={self.page_number})"
+
+
+class QueryResults:
+    """Query results with lazy access to individual chunks."""
+    def __init__(self, handle):
+        self._handle = handle
+        self._lib = _Lib.get()
+
+    @property
+    def count(self) -> int:
+        return self._lib.evdb_result_count(self._handle)
+
+    def __getitem__(self, index: int) -> ChunkResult:
+        return ChunkResult(
+            chunk_id=self._lib.evdb_result_chunk_id(self._handle, index),
+            text=self._lib.evdb_result_text(self._handle, index).decode("utf-8"),
+            score=self._lib.evdb_result_score(self._handle, index),
+            page_number=self._lib.evdb_result_page(self._handle, index),
+        )
+
+    def __len__(self) -> int:
+        return self.count
+
+    def __iter__(self):
+        for i in range(self.count):
+            yield self[i]
+
+    @property
+    def context_string(self) -> str:
+        raw = self._lib.evdb_result_context_string(self._handle)
+        return raw.decode("utf-8") if raw else ""
+
+    def to_list(self) -> List[ChunkResult]:
+        return list(self)
+
+    def free(self):
+        if hasattr(self, '_handle') and self._handle:
+            self._lib.evdb_query_free(self._handle)
+            self._handle = None
+
+    def __del__(self):
+        self.free()
+
+
+class Embedder:
+    """ONNX embedding model wrapper."""
+    def __init__(self, model_path: str, vocab_path: str, threads: int = 2):
+        self._lib = _Lib.get()
+        self._handle = self._lib.evdb_embedder_create(
+            model_path.encode(), vocab_path.encode(), threads)
+        if not self._handle:
+            raise RuntimeError("Failed to create embedder")
+
+    @property
+    def handle(self):
+        return self._handle
+
+    def embed(self, text: str) -> List[float]:
+        out = (ctypes.c_float * 384)()
+        err = self._lib.evdb_embed_text(self._handle, text.encode(), out)
+        if err != 0:
+            raise RuntimeError(f"Embedding failed: {err}")
+        return list(out)
+
+    def destroy(self):
+        if self._handle:
+            self._lib.evdb_embedder_destroy(self._handle)
+            self._handle = None
+
+    def __del__(self):
+        self.destroy()
+
+
+class EdgeVDB:
+    """Main EdgeVDB database class."""
+
+    def __init__(self, storage_dir: str, **kwargs):
+        self._lib = _Lib.get()
+
+        config = EvdbConfig()
+        self._lib.evdb_default_config(ctypes.byref(config))
+        config.storage_dir = storage_dir.encode()
+
+        for key, value in kwargs.items():
+            if hasattr(config, key):
+                setattr(config, key, value)
+
+        os.makedirs(storage_dir, exist_ok=True)
+        self._handle = self._lib.evdb_open(ctypes.byref(config))
+        if not self._handle:
+            raise RuntimeError(f"Failed to open EdgeVDB at {storage_dir}")
+
+    def close(self):
+        if self._handle:
+            self._lib.evdb_close(self._handle)
+            self._handle = None
+
+    def save(self):
+        err = self._lib.evdb_save(self._handle)
+        if err != 0:
+            raise RuntimeError(f"Save failed: {err}")
+
+    # Vector store
+    def insert_text(self, embedder: Embedder, text: str,
+                    doc_id: int = 0, page_number: int = 0) -> int:
+        chunk_id = ctypes.c_uint64(0)
+        err = self._lib.evdb_insert_text(
+            self._handle, embedder.handle, text.encode(),
+            doc_id, page_number, ctypes.byref(chunk_id))
+        if err != 0:
+            raise RuntimeError(f"Insert failed: {err}")
+        return chunk_id.value
+
+    def insert_chunk(self, text: str, embedding: List[float],
+                     doc_id: int = 0, page_number: int = 0) -> int:
+        emb_arr = (ctypes.c_float * 384)(*embedding)
+        chunk_id = ctypes.c_uint64(0)
+        err = self._lib.evdb_insert_chunk(
+            self._handle, text.encode(), emb_arr,
+            doc_id, page_number, ctypes.byref(chunk_id))
+        if err != 0:
+            raise RuntimeError(f"Insert failed: {err}")
+        return chunk_id.value
+
+    def remove_chunk(self, chunk_id: int):
+        err = self._lib.evdb_remove_chunk(self._handle, chunk_id)
+        if err != 0:
+            raise RuntimeError(f"Remove failed: {err}")
+
+    # Query
+    def query_text(self, embedder: Embedder, query: str,
+                   top_k: int = 5, use_kg_expansion: bool = False) -> QueryResults:
+        qh = self._lib.evdb_query_text(
+            self._handle, embedder.handle, query.encode(),
+            top_k, 1 if use_kg_expansion else 0)
+        if not qh:
+            raise RuntimeError("Query failed")
+        return QueryResults(qh)
+
+    def query_vector(self, embedding: List[float], query_text: str = "",
+                     top_k: int = 5) -> QueryResults:
+        emb_arr = (ctypes.c_float * 384)(*embedding)
+        qh = self._lib.evdb_query_vector(
+            self._handle, emb_arr, query_text.encode(), top_k)
+        if not qh:
+            raise RuntimeError("Query failed")
+        return QueryResults(qh)
+
+    # Object store
+    def put_object(self, type_name: str, properties: Dict[str, Any]) -> int:
+        json_str = json.dumps(properties)
+        out_id = ctypes.c_uint64(0)
+        err = self._lib.evdb_object_put(
+            self._handle, type_name.encode(), json_str.encode(),
+            ctypes.byref(out_id))
+        if err != 0:
+            raise RuntimeError(f"Object put failed: {err}")
+        return out_id.value
+
+    def get_object(self, object_id: int) -> Optional[Dict[str, Any]]:
+        buf = ctypes.create_string_buffer(4096)
+        err = self._lib.evdb_object_get(self._handle, object_id, buf, 4096)
+        if err == 4:  # NOT_FOUND
+            return None
+        if err != 0:
+            raise RuntimeError(f"Object get failed: {err}")
+        return json.loads(buf.value.decode())
+
+    def remove_object(self, object_id: int):
+        err = self._lib.evdb_object_remove(self._handle, object_id)
+        if err != 0:
+            raise RuntimeError(f"Object remove failed: {err}")
+
+    # Relations
+    def add_relation(self, name: str, from_id: int, to_id: int):
+        err = self._lib.evdb_relation_add(
+            self._handle, name.encode(), from_id, to_id)
+        if err != 0:
+            raise RuntimeError(f"Relation add failed: {err}")
+
+    # Context manager
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.save()
+        self.close()
+
+    def __del__(self):
+        self.close()
+
+
+def version() -> str:
+    lib = _Lib.get()
+    return lib.evdb_version_string().decode()
+
+
+def set_log_level(level: int):
+    lib = _Lib.get()
+    lib.evdb_set_log_level(level)

edgevdb/embedder.py

@@ -0,0 +1,7 @@
+"""
+EdgeVDB Python embedder module — re-exported from __init__.py.
+"""
+
+from edgevdb import Embedder
+
+__all__ = ["Embedder"]

edgevdb/lib/README.md

@@ -0,0 +1,31 @@
+# EdgeVDB Native Libraries
+
+Platform-specific shared libraries for the EdgeVDB Python SDK.
+
+## Structure
+
+```
+lib/
+  windows/   → edgevdb_shared.dll, libedgevdb_shared.dll
+  linux/     → libedgevdb_shared.so
+  darwin/    → libedgevdb_shared.dylib
+```
+
+## Building
+
+Copy the built shared library from `build/desktop-release/core/` into the
+appropriate platform directory:
+
+```bash
+# Linux
+cp build/desktop-release/core/libedgevdb_shared.so python/edgevdb/lib/linux/
+
+# macOS
+cp build/desktop-release/core/libedgevdb_shared.dylib python/edgevdb/lib/darwin/
+
+# Windows (PowerShell)
+copy build\desktop-release\core\edgevdb_shared.dll python\edgevdb\lib\windows\
+```
+
+The Python SDK (`__init__.py`) automatically detects the host platform and
+loads the correct library from the matching subdirectory.

edgevdb/object_store.py

@@ -0,0 +1,27 @@
+"""
+EdgeVDB Python object_store module — re-exported from __init__.py.
+Provides convenience methods for the relational object store.
+"""
+
+from edgevdb import EdgeVDB
+
+__all__ = ["ObjectStoreHelper"]
+
+
+class ObjectStoreHelper:
+    """Convenience wrapper for object store operations."""
+
+    def __init__(self, db: EdgeVDB):
+        self._db = db
+
+    def put(self, type_name: str, properties: dict) -> int:
+        return self._db.put_object(type_name, properties)
+
+    def get(self, object_id: int) -> dict:
+        return self._db.get_object(object_id)
+
+    def remove(self, object_id: int):
+        self._db.remove_object(object_id)
+
+    def add_relation(self, name: str, from_id: int, to_id: int):
+        self._db.add_relation(name, from_id, to_id)

edgevdb/sync.py

@@ -0,0 +1,30 @@
+"""
+EdgeVDB Python sync module — file-based sync utilities.
+"""
+
+import os
+import json
+from typing import Optional
+
+from edgevdb import EdgeVDB
+
+
+class SyncHelper:
+    """File-based sync helper for Python SDK."""
+
+    def __init__(self, db: EdgeVDB, device_id: str = "python-desktop"):
+        self._db = db
+        self._device_id = device_id
+
+    def export_to_file(self, path: str, since_clock: int = 0) -> bool:
+        """Export sync delta to a JSON file."""
+        # Note: Requires sync engine handle — this is a placeholder
+        # In full implementation, would call evdb_sync_export_to_file
+        return False
+
+    def import_from_file(self, path: str) -> dict:
+        """Import sync delta from a JSON file."""
+        return {"applied": 0, "skipped": 0}
+
+
+__all__ = ["SyncHelper"]

edgevdb/vectordb.py

@@ -0,0 +1,8 @@
+"""
+EdgeVDB Python vectordb module — re-exported from __init__.py.
+This module provides the core VectorDB functionality as a standalone import.
+"""
+
+from edgevdb import EdgeVDB, Embedder, QueryResults, ChunkResult
+
+__all__ = ["EdgeVDB", "Embedder", "QueryResults", "ChunkResult"]

edgevdb-1.0.0.dist-info/METADATA

@@ -0,0 +1,666 @@
+Metadata-Version: 2.4
+Name: edgevdb
+Version: 1.0.0
+Summary: EdgeVDB — On-device vector database with HNSW, hybrid retrieval, knowledge graph, and CRDT sync
+Author-email: XformAI <contact@xformai.in>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/XformAI/EDGEVDB
+Project-URL: Documentation, https://xformai.github.io/EDGEVDB/
+Project-URL: Repository, https://github.com/XformAI/EDGEVDB
+Project-URL: Issues, https://github.com/XformAI/EDGEVDB/issues
+Keywords: vector-database,hnsw,embedding,rag,on-device,edge-ai,semantic-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Programming Language :: Python :: 3.13
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# EdgeVDB Python SDK
+
+> **Python wrapper for EdgeVDB on-device vector database with ctypes FFI binding.**
+
+The EdgeVDB Python SDK provides a Pythonic interface to the EdgeVDB C++ core library using ctypes. It enables Python applications to use EdgeVDB's vector database capabilities on desktop and Raspberry Pi platforms.
+
+## Features
+
+- **ctypes FFI Binding** — Direct calls to C API with no Python dependencies
+- **Context Manager Support** — Automatic resource cleanup with `with` statements
+- **Type Hints** — Full type annotations for IDE support
+- **Zero Python Dependencies** — Only standard library and ctypes
+- **Cross-Platform** — Linux, macOS, Windows, Raspberry Pi
+- **Flexible Embedding** — Use any embedding provider or built-in ONNX embedder
+
+## Installation
+
+### From Source
+
+```bash
+# Build the C++ core first
+cd ..
+cmake --preset desktop-release
+cmake --build build/desktop-release
+
+# Copy shared library to Python package (platform-specific)
+# Linux:
+cp build/desktop-release/core/libedgevdb_shared.so python/edgevdb/lib/linux/
+# macOS:
+# cp build/desktop-release/core/libedgevdb_shared.dylib python/edgevdb/lib/darwin/
+# Windows:
+# copy build\desktop-release\core\edgevdb_shared.dll python\edgevdb\lib\windows\
+
+# Install in development mode
+cd python
+pip install -e .
+```
+
+### From PyPI (after publishing)
+
+```bash
+pip install edgevdb
+```
+
+## Quick Start
+
+### Without ONNX (Recommended)
+
+Use embeddings from any provider (OpenAI, Cohere, sentence-transformers, etc.):
+
+```python
+from edgevdb import EdgeVDB
+
+# Open database
+db = EdgeVDB("./my_database")
+
+# Get embeddings from your preferred provider
+# Example with sentence-transformers:
+from sentence_transformers import SentenceTransformer
+model = SentenceTransformer('all-MiniLM-L6-v2')
+embedding = model.encode("Machine learning finds patterns in data")
+
+# Insert with pre-computed embedding
+chunk_id = db.insert_chunk(
+    text="Machine learning finds patterns in data",
+    embedding=embedding,
+    doc_id=1,
+    page_number=0
+)
+
+# Query
+query_emb = model.encode("what is ML?")
+results = db.query_vector(query_emb, query_text="what is ML?", top_k=5)
+
+for r in results:
+    print(f"score={r.score:.3f} text={r.text}")
+
+# Object store
+doc_id = db.put_object("Document", {"title": "ML Intro", "author": "Alice"})
+db.add_relation("has_chunk", doc_id, chunk_id)
+
+db.save()
+db.close()
+```
+
+### With Built-in Embedder
+
+```python
+from edgevdb import EdgeVDB, Embedder
+
+# Create embedder
+embedder = Embedder(
+    model_path="models/model.onnx",
+    vocab_path="models/vocab.txt",
+    threads=2
+)
+
+# Use with context manager
+with EdgeVDB("./my_database") as db:
+    # Auto-embed on insert
+    chunk_id = db.insert_text(
+        embedder, 
+        "Deep learning uses neural networks",
+        doc_id=1,
+        page_number=0
+    )
+
+    # Auto-embed on query
+    results = db.query_text(embedder, "neural network architecture", top_k=5)
+    print(results.context_string)
+```
+
+## API Reference
+
+### EdgeVDB
+
+Main database class.
+
+#### Constructor
+
+```python
+EdgeVDB(storage_dir: str, **kwargs)
+```
+
+**Parameters:**
+- `storage_dir` (str): Directory for database files
+- `hnsw_M` (int): HNSW M parameter (default: 16)
+- `hnsw_ef_construction` (int): HNSW ef_construction (default: 200)
+- `hnsw_ef_search` (int): HNSW ef_search (default: 64)
+- `ranker_alpha` (float): Cosine weight (default: 0.70)
+- `ranker_beta` (float): Page proximity weight (default: 0.20)
+- `ranker_gamma` (float): Keyword weight (default: 0.10)
+- `token_budget` (int): Max tokens in context (default: 3200)
+- `embedding_threads` (int): ONNX thread count (default: 2)
+- `enable_knowledge_graph` (bool): Enable KG (default: True)
+- `enable_sync` (bool): Enable sync (default: False)
+- `device_id` (str): Device ID for sync (default: auto-generated)
+
+#### Methods
+
+##### Vector Store
+
+**insert_chunk(text, embedding, doc_id=0, page_number=0) -> int**
+- Insert text with pre-computed embedding
+- Returns chunk ID
+
+```python
+chunk_id = db.insert_chunk(
+    text="Your text here",
+    embedding=[0.1, 0.2, ...],  # 384-dim float array
+    doc_id=1,
+    page_number=0
+)
+```
+
+**insert_text(embedder, text, doc_id=0, page_number=0) -> int**
+- Insert text with auto-embedding via embedder
+- Returns chunk ID
+
+```python
+chunk_id = db.insert_text(
+    embedder,
+    "Your text here",
+    doc_id=1,
+    page_number=0
+)
+```
+
+**remove_chunk(chunk_id)**
+- Remove chunk by ID
+
+```python
+db.remove_chunk(chunk_id)
+```
+
+**query_vector(embedding, query_text="", top_k=5) -> QueryResults**
+- Query with pre-computed embedding
+- Returns QueryResults object
+
+```python
+results = db.query_vector(
+    embedding=[0.1, 0.2, ...],
+    query_text="search query",
+    top_k=5
+)
+```
+
+**query_text(embedder, query, top_k=5, use_kg_expansion=False) -> QueryResults**
+- Query with auto-embedding via embedder
+- Returns QueryResults object
+
+```python
+results = db.query_text(
+    embedder,
+    "search query",
+    top_k=5,
+    use_kg_expansion=False
+)
+```
+
+##### Object Store
+
+**put_object(type_name, properties) -> int**
+- Store JSON object
+- Returns object ID
+
+```python
+doc_id = db.put_object(
+    "Document",
+    {"title": "My Doc", "author": "Alice"}
+)
+```
+
+**get_object(object_id) -> Optional[Dict]**
+- Retrieve object by ID
+- Returns dict or None if not found
+
+```python
+obj = db.get_object(doc_id)
+if obj:
+    print(obj["title"])
+```
+
+**remove_object(object_id)**
+- Soft delete object
+
+```python
+db.remove_object(doc_id)
+```
+
+##### Relations
+
+**add_relation(name, from_id, to_id)**
+- Add typed edge between objects
+
+```python
+db.add_relation("has_chunk", doc_id, chunk_id)
+```
+
+##### Lifecycle
+
+**save()**
+- Flush all data to disk
+
+```python
+db.save()
+```
+
+**close()**
+- Release native resources
+
+```python
+db.close()
+```
+
+**Context Manager**
+
+```python
+with EdgeVDB("./data") as db:
+    # Auto-save and close on exit
+    db.insert_chunk("text", embedding, doc_id=1)
+```
+
+### Embedder
+
+ONNX embedding model wrapper.
+
+#### Constructor
+
+```python
+Embedder(model_path: str, vocab_path: str, threads: int = 2)
+```
+
+**Parameters:**
+- `model_path` (str): Path to ONNX model file
+- `vocab_path` (str): Path to vocabulary file
+- `threads` (int): Number of inference threads (default: 2)
+
+#### Methods
+
+**embed(text: str) -> List[float]**
+- Embed text to 384-dim vector
+- Returns list of floats
+
+```python
+embedding = embedder.embed("Hello world")
+```
+
+**destroy()**
+- Release native resources
+
+```python
+embedder.destroy()
+```
+
+### QueryResults
+
+Query result container with lazy access.
+
+#### Properties
+
+**count** (int): Number of results
+
+```python
+print(f"Found {results.count} results")
+```
+
+**context_string** (str): Pre-assembled RAG context
+
+```python
+print(results.context_string)
+```
+
+#### Methods
+
+**__getitem__(index) -> ChunkResult**
+- Access individual result by index
+
+```python
+result = results[0]
+print(result.text)
+```
+
+**__iter__()**
+- Iterate over results
+
+```python
+for r in results:
+    print(f"{r.score}: {r.text}")
+```
+
+**to_list() -> List[ChunkResult]**
+- Convert to list
+
+```python
+results_list = results.to_list()
+```
+
+**free()**
+- Free native query handle (called automatically by __del__)
+
+```python
+results.free()
+```
+
+### ChunkResult
+
+Single query result.
+
+#### Attributes
+
+- **chunk_id** (int): Unique chunk identifier
+- **text** (str): Chunk text content
+- **score** (float): Hybrid similarity score [0.0, 1.0]
+- **page_number** (int): Page number in document
+- **doc_id** (int): Document identifier
+
+```python
+for r in results:
+    print(f"ID: {r.chunk_id}")
+    print(f"Text: {r.text}")
+    print(f"Score: {r.score:.3f}")
+    print(f"Page: {r.page_number}")
+```
+
+## Examples
+
+### RAG Pipeline
+
+```python
+from edgevdb import EdgeVDB
+from sentence_transformers import SentenceTransformer
+
+# Initialize
+model = SentenceTransformer('all-MiniLM-L6-v2')
+db = EdgeVDB("./rag_database")
+
+# Index documents
+documents = [
+    {"id": 1, "text": "Python is a high-level programming language."},
+    {"id": 2, "text": "Machine learning is a subset of AI."},
+    {"id": 3, "text": "Vector databases enable semantic search."},
+]
+
+for doc in documents:
+    embedding = model.encode(doc["text"])
+    db.insert_chunk(doc["text"], embedding, doc_id=doc["id"])
+
+# Query
+query = "What is semantic search?"
+query_emb = model.encode(query)
+results = db.query_vector(query_emb, query_text=query, top_k=2)
+
+# Assemble context
+context = results.context_string
+print(f"Context: {context}")
+
+db.save()
+db.close()
+```
+
+### Object Store + Relations
+
+```python
+from edgevdb import EdgeVDB
+
+db = EdgeVDB("./my_database")
+
+# Store documents
+doc1_id = db.put_object("Document", {
+    "title": "Introduction to ML",
+    "author": "Alice",
+    "year": 2024
+})
+
+doc2_id = db.put_object("Document", {
+    "title": "Advanced Topics",
+    "author": "Bob",
+    "year": 2024
+})
+
+# Store chunks with embeddings
+chunk1_id = db.insert_chunk("ML is fascinating", emb, doc_id=doc1_id)
+chunk2_id = db.insert_chunk("Deep learning is powerful", emb, doc_id=doc2_id)
+
+# Link chunks to documents
+db.add_relation("has_chunk", doc1_id, chunk1_id)
+db.add_relation("has_chunk", doc2_id, chunk2_id)
+
+db.save()
+db.close()
+```
+
+### Error Handling
+
+```python
+from edgevdb import EdgeVDB, set_log_level
+
+# Enable debug logging
+set_log_level(3)
+
+try:
+    db = EdgeVDB("./my_database")
+    
+    # Operations
+    chunk_id = db.insert_chunk("text", embedding, doc_id=1)
+    
+    # Object not found returns None (doesn't throw)
+    obj = db.get_object(999)
+    if obj is None:
+        print("Object not found")
+    
+    db.save()
+    db.close()
+    
+except RuntimeError as e:
+    print(f"EdgeVDB error: {e}")
+```
+
+## Library Discovery
+
+The Python SDK automatically searches for the EdgeVDB shared library in the following locations:
+
+1. Platform-specific directory (`edgevdb/lib/<platform>/`) — **preferred**
+2. Package lib directory (`edgevdb/lib/`)
+3. Package directory (`edgevdb/`)
+4. Current working directory
+5. `build/desktop-release/core/`
+6. `build/desktop-debug/core/`
+
+**Library Layout:**
+```
+python/edgevdb/lib/
+  linux/    → libedgevdb_shared.so
+  darwin/   → libedgevdb_shared.dylib
+  windows/  → edgevdb_shared.dll, libedgevdb_shared.dll
+```
+
+## Performance Considerations
+
+### Embedding Provider Choice
+
+| Provider | Speed | Quality | Offline | Cost |
+|----------|-------|--------|---------|------|
+| sentence-transformers | Fast | Good | ✅ | Free |
+| OpenAI API | Slow | Excellent | ❌ | Paid |
+| Cohere API | Medium | Good | ❌ | Paid |
+| Built-in ONNX | Medium | Good | ✅ | Free |
+
+### Batch Operations
+
+For large-scale operations, consider batching:
+
+```python
+# Batch insert
+embeddings = model.encode(texts)
+for text, emb in zip(texts, embeddings):
+    db.insert_chunk(text, emb, doc_id=doc_id)
+
+db.save()  # Save once after all inserts
+```
+
+### Memory Management
+
+- Query results hold native handles; call `results.free()` or use context manager
+- Embedders hold native resources; call `embedder.destroy()` when done
+- Database handles are released by `close()` or context manager
+
+## Platform-Specific Notes
+
+### Linux
+
+```bash
+# Build
+cmake --preset desktop-release
+cmake --build build/desktop-release
+
+# Install
+cp build/desktop-release/core/libedgevdb_shared.so python/edgevdb/lib/linux/
+pip install -e python/
+```
+
+### macOS
+
+```bash
+# Build
+cmake --preset desktop-release
+cmake --build build/desktop-release
+
+# Install
+cp build/desktop-release/core/libedgevdb_shared.dylib python/edgevdb/lib/darwin/
+pip install -e python/
+```
+
+### Windows
+
+```powershell
+# Build
+cmake --preset desktop-release
+cmake --build build/desktop-release
+
+# Install
+copy build\desktop-release\core\edgevdb_shared.dll python\edgevdb\lib\windows\
+pip install -e python\
+```
+
+### Raspberry Pi
+
+```bash
+# Build with NEON support
+cmake --preset desktop-release
+cmake --build build/desktop-release
+
+# Install
+cp build/desktop-release/core/libedgevdb_shared.so python/edgevdb/lib/linux/
+pip install -e python/
+```
+
+## Testing
+
+```bash
+cd python
+
+# Run tests
+python -m unittest tests.test_edgevdb -v
+
+# Or with pytest
+pytest tests/ -v
+```
+
+## Troubleshooting
+
+### Library Not Found
+
+**Error:** `FileNotFoundError: Could not find EdgeVDB library`
+
+**Solution:**
+1. Build the C++ core: `cmake --preset desktop-release && cmake --build build/desktop-release`
+2. Copy the shared library to `python/edgevdb/lib/<platform>/`
+3. Verify the library name matches your platform
+
+### Import Errors
+
+**Error:** `ImportError: dynamic module does not define init function`
+
+**Solution:**
+- Ensure the shared library was built for your platform
+- Check Python architecture matches library (32-bit vs 64-bit)
+- Rebuild the C++ core for your platform
+
+### Segmentation Faults
+
+**Error:** Python crashes with segmentation fault
+
+**Solution:**
+- Ensure you're using the correct library version
+- Check that you're not accessing freed handles
+- Verify embedding dimensions are exactly 384
+- Enable debug logging: `set_log_level(3)`
+
+## Contributing
+
+### Development Setup
+
+```bash
+# Build C++ core in debug mode
+cmake --preset desktop-debug
+cmake --build build/desktop-debug
+
+# Copy debug library
+cp build/desktop-debug/core/libedgevdb_shared.so python/edgevdb/
+
+# Install in development mode
+cd python
+pip install -e .
+```
+
+### Running Tests
+
+```bash
+cd python
+python -m unittest tests.test_edgevdb -v
+```
+
+### Code Style
+
+- Follow PEP 8
+- Use type hints
+- Add docstrings for public APIs
+- Run black and flake8
+
+## See Also
+
+- [../README.md](../README.md) — Project overview
+- [../../DEVELOPER_GUIDE.md](../../DEVELOPER_GUIDE.md) — Build and integration guide
+- [../../docs/python_integration.md](../../docs/python_integration.md) — Python integration guide
+- [examples/](examples/) — Example scripts

edgevdb-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+edgevdb/__init__.py,sha256=fGSvoYmn5r5JGQQdZkwVKLbMLLP78q1tNNdm5aoPyLI,13423
+edgevdb/embedder.py,sha256=K5pOgqAcgUULaM2WMXmnLfsBJ8Uh6bOok1Mnv_1nc7c,127
+edgevdb/object_store.py,sha256=fn_ydPEJvgAibYJDJNVSMqkbMVHieAq5Kh6y-Lh0aQU,755
+edgevdb/sync.py,sha256=Nmm4KY_YvUnihg8KP4-32hXotWjlVLDYdGAQgTRnhL4,800
+edgevdb/vectordb.py,sha256=Sg26gLffFDye0GyheF82pBAbE4bFKPb1IFgtCr3RgQo,282
+edgevdb/lib/README.md,sha256=j__VETKWC5fBAtgwnEHXdVmST_xZO4yVx-Q2RzGSvVs,802
+edgevdb/lib/darwin/libedgevdb_shared.dylib,sha256=yzBAcrwA_9FKT0fJEtH-t0YW5UyTfNGhnALqugF9Nlk,296664
+edgevdb/lib/linux/libedgevdb_shared.so,sha256=ozzQc31T_6zKMCcKOZhVgeZJykl8ZkUfDhi6l4u3gZA,439272
+edgevdb/lib/windows/libedgevdb_shared.dll,sha256=uJgOO3pvQHUBOB9ROP_uKTR1hYe6bLbBPDTl1r3uuAk,586681
+edgevdb-1.0.0.dist-info/METADATA,sha256=rjtMuSBg0OseEkpuRRWiVyD1ms6W6NDmG5xtcpoUUwY,15029
+edgevdb-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+edgevdb-1.0.0.dist-info/top_level.txt,sha256=BAh4GWbR3XbJXfgJyjfJf4rTaw9WQISnbwdVMKT2ZF4,8
+edgevdb-1.0.0.dist-info/RECORD,,

edgevdb-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

edgevdb-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+edgevdb