tapirus 1.0.0__py3-none-any.whl

tapirus/__init__.py

@@ -0,0 +1,36 @@
+"""
+TapirusDB Official Python SDK
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An embedded quad-model database and AI agent memory engine engineered in 100% Safe Rust.
+
+Basic usage:
+
+    >>> import tapirus
+    >>> db = tapirus.connect("agent_memory.tapir")
+    >>> db.execute("CREATE TABLE products (id INT PRIMARY KEY, name TEXT);")
+    >>> db.execute("INSERT INTO products VALUES (1, 'Autonomous Drone');")
+    >>> rows = db.query("SELECT * FROM products;")
+    >>> print(rows)
+    [{'id': 1, 'name': 'Autonomous Drone'}]
+"""
+
+from .connection import Connection, connect
+from .exceptions import (
+    TapirusError,
+    ConnectionError,
+    QueryError,
+    AuthenticationError,
+    ConstraintError,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "connect",
+    "Connection",
+    "TapirusError",
+    "ConnectionError",
+    "QueryError",
+    "AuthenticationError",
+    "ConstraintError",
+]

tapirus/connection.py

@@ -0,0 +1,136 @@
+"""
+TapirusDB High-Level Python Connection API
+"""
+
+import json
+import ctypes
+from typing import Optional, List, Dict, Any, Union
+from .ffi import get_ffi
+from .exceptions import ConnectionError, QueryError, AuthenticationError
+
+class Connection:
+    """A connection to a TapirusDB database instance."""
+
+    @classmethod
+    def open(cls, path: Optional[str] = None, passphrase: Optional[str] = None) -> "Connection":
+        """Open a TapirusDB connection (factory method)."""
+        return cls(path=path, passphrase=passphrase)
+
+    def __init__(self, path: Optional[str] = None, passphrase: Optional[str] = None):
+        self._ffi = get_ffi()
+        self._handle = None
+        self._is_closed = False
+        self._path = path
+
+        if not self._ffi.is_native_available:
+            # Fallback in-memory Python emulator for environments without compiled C-FFI
+            self._emulator = True
+            self._local_tables: Dict[str, List[Dict[str, Any]]] = {}
+            return
+
+        self._emulator = False
+        lib = self._ffi._lib
+
+        if path is None or path == ":memory:":
+            self._handle = lib.tapirus_open_in_memory()
+        elif passphrase:
+            self._handle = lib.tapirus_open_encrypted(path.encode("utf-8"), passphrase.encode("utf-8"))
+        else:
+            self._handle = lib.tapirus_open(path.encode("utf-8"))
+
+        if not self._handle:
+            raise ConnectionError(f"Failed to open TapirusDB database at '{path}'")
+
+    def execute(self, sql: str) -> int:
+        """Execute a non-query SQL statement (CREATE, INSERT, UPDATE, DELETE)."""
+        if self._is_closed:
+            raise ConnectionError("Cannot execute on closed connection")
+
+        if self._emulator:
+            return self._emulate_execute(sql)
+
+        lib = self._ffi._lib
+        affected = lib.tapirus_execute(self._handle, sql.encode("utf-8"))
+        if affected < 0:
+            err_ptr = lib.tapirus_last_error(self._handle)
+            msg = "Query execution error"
+            if err_ptr:
+                msg = ctypes.string_at(err_ptr).decode("utf-8", errors="replace")
+                lib.tapirus_free_string(err_ptr)
+            raise QueryError(msg)
+        return affected
+
+    def query(self, sql: str) -> List[Dict[str, Any]]:
+        """Execute a SQL query and return results as a list of dict rows."""
+        if self._is_closed:
+            raise ConnectionError("Cannot query on closed connection")
+
+        if self._emulator:
+            return self._emulate_query(sql)
+
+        lib = self._ffi._lib
+        res_ptr = lib.tapirus_query(self._handle, sql.encode("utf-8"))
+        if not res_ptr:
+            err_ptr = lib.tapirus_last_error(self._handle)
+            msg = "Query failed"
+            if err_ptr:
+                msg = ctypes.string_at(err_ptr).decode("utf-8", errors="replace")
+                lib.tapirus_free_string(err_ptr)
+            raise QueryError(msg)
+
+        try:
+            raw_str = ctypes.string_at(res_ptr).decode("utf-8", errors="replace")
+            return json.loads(raw_str)
+        finally:
+            lib.tapirus_free_string(res_ptr)
+
+    def close(self):
+        """Close and deallocate connection resources."""
+        if not self._is_closed:
+            if not self._emulator and self._handle:
+                self._ffi._lib.tapirus_close(self._handle)
+                self._handle = None
+            self._is_closed = True
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def _emulate_execute(self, sql: str) -> int:
+        clean = sql.strip().rstrip(";")
+        if clean.upper().startswith("CREATE TABLE"):
+            parts = clean.split()
+            tbl_name = parts[2].split("(")[0]
+            if tbl_name not in self._local_tables:
+                self._local_tables[tbl_name] = []
+            return 0
+        elif clean.upper().startswith("INSERT INTO"):
+            parts = clean.split()
+            tbl_name = parts[2]
+            if tbl_name not in self._local_tables:
+                self._local_tables[tbl_name] = []
+            self._local_tables[tbl_name].append({"id": len(self._local_tables[tbl_name]) + 1, "raw": clean})
+            return 1
+        return 0
+
+    def _emulate_query(self, sql: str) -> List[Dict[str, Any]]:
+        clean = sql.strip().rstrip(";")
+        parts = clean.split()
+        if "FROM" in [p.upper() for p in parts]:
+            idx = [p.upper() for p in parts].index("FROM")
+            if idx + 1 < len(parts):
+                tbl_name = parts[idx + 1]
+                return self._local_tables.get(tbl_name, [])
+        return []
+
+def connect(path: Optional[str] = None, passphrase: Optional[str] = None) -> Connection:
+    """
+    Open a TapirusDB connection.
+
+    Args:
+        path: Path to `.tapir` file, or None / ':memory:' for transient RAM database.
+        passphrase: Optional encryption key for ChaCha20-Poly1305 AEAD security.
+    """
+    return Connection(path=path, passphrase=passphrase)

tapirus/exceptions.py

@@ -0,0 +1,23 @@
+"""
+TapirusDB Exception Hierarchy
+"""
+
+class TapirusError(Exception):
+    """Base exception for all TapirusDB errors."""
+    pass
+
+class ConnectionError(TapirusError):
+    """Raised when failing to open or connect to a database file."""
+    pass
+
+class QueryError(TapirusError):
+    """Raised when SQL syntax or query execution fails."""
+    pass
+
+class AuthenticationError(TapirusError):
+    """Raised when passphrase decryption or salt verification fails."""
+    pass
+
+class ConstraintError(TapirusError):
+    """Raised when primary key, NOT NULL, or uniqueness constraints are violated."""
+    pass

tapirus/ffi.py

@@ -0,0 +1,101 @@
+"""
+TapirusDB Low-Level C-FFI Loader
+"""
+
+import ctypes
+import os
+import sys
+import json
+from typing import Optional, List, Dict, Any
+from .exceptions import ConnectionError, QueryError, AuthenticationError
+
+def _find_library() -> Optional[str]:
+    """Search for the compiled TapirusDB shared library."""
+    lib_names = []
+    if sys.platform.startswith("linux"):
+        lib_names = ["libtapirus.so", "libtapirus_ffi.so"]
+    elif sys.platform == "darwin":
+        lib_names = ["libtapirus.dylib", "libtapirus.so"]
+    elif sys.platform == "win32":
+        lib_names = ["tapirus.dll", "tapirus_ffi.dll", "libtapirus.dll"]
+    else:
+        lib_names = ["libtapirus.so"]
+
+    search_dirs = [
+        os.path.dirname(__file__),
+        os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "..", "target", "release")),
+        os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "..", "target", "debug")),
+        os.path.expanduser("~/.tapirus/lib"),
+        "/usr/local/lib",
+        "/usr/lib",
+    ]
+
+    for d in search_dirs:
+        for name in lib_names:
+            p = os.path.join(d, name)
+            if os.path.isfile(p):
+                return p
+
+    return None
+
+class FFIWrapper:
+    def __init__(self):
+        self._lib_path = _find_library()
+        self._lib = None
+
+        if self._lib_path:
+            try:
+                self._lib = ctypes.CDLL(self._lib_path)
+                self._bind_functions()
+            except Exception as e:
+                self._lib = None
+
+    @property
+    def is_native_available(self) -> bool:
+        return self._lib is not None
+
+    def _bind_functions(self):
+        lib = self._lib
+        # tapirus_open
+        lib.tapirus_open.argtypes = [ctypes.c_char_p]
+        lib.tapirus_open.restype = ctypes.c_void_p
+
+        # tapirus_open_encrypted
+        lib.tapirus_open_encrypted.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
+        lib.tapirus_open_encrypted.restype = ctypes.c_void_p
+
+        # tapirus_open_in_memory
+        lib.tapirus_open_in_memory.argtypes = []
+        lib.tapirus_open_in_memory.restype = ctypes.c_void_p
+
+        # tapirus_close
+        lib.tapirus_close.argtypes = [ctypes.c_void_p]
+        lib.tapirus_close.restype = None
+
+        # tapirus_execute
+        lib.tapirus_execute.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+        lib.tapirus_execute.restype = ctypes.c_int32
+
+        # tapirus_query
+        lib.tapirus_query.argtypes = [ctypes.c_void_p, ctypes.c_char_p]
+        lib.tapirus_query.restype = ctypes.c_void_p
+
+        # tapirus_free_string
+        lib.tapirus_free_string.argtypes = [ctypes.c_void_p]
+        lib.tapirus_free_string.restype = None
+
+        # tapirus_last_error
+        lib.tapirus_last_error.argtypes = [ctypes.c_void_p]
+        lib.tapirus_last_error.restype = ctypes.c_void_p
+
+        # tapirus_version
+        lib.tapirus_version.argtypes = []
+        lib.tapirus_version.restype = ctypes.c_char_p
+
+_ffi_instance: Optional[FFIWrapper] = None
+
+def get_ffi() -> FFIWrapper:
+    global _ffi_instance
+    if _ffi_instance is None:
+        _ffi_instance = FFIWrapper()
+    return _ffi_instance

tapirus-1.0.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: tapirus
+Version: 1.0.0
+Summary: Official Python SDK for TapirusDB — Safe-Rust Quad-Model Embedded AI Database & Agent Memory Engine
+Home-page: https://tapirusdb.com
+Author: Ahmad Faiz
+Author-email: Ahmad Faiz <faiz@tapirusdb.com>
+License: BSL-1.1
+Project-URL: Homepage, https://tapirusdb.com
+Project-URL: Documentation, https://docs.tapirusdb.com
+Project-URL: Repository, https://github.com/tapiruslab/TapirusDB
+Keywords: tapirus,tapirusdb,embedded,database,sqlite,vector,graph,ai-memory,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary 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 :: Database Engines/Servers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# TapirusDB Python SDK (`tapirus`)
+
+Official Python client for **TapirusDB** — the 100% Safe-Rust Embedded Quad-Model Database & AI Agent Memory Engine.
+
+---
+
+## ⚡ Installation
+
+Install from source or local checkout:
+```bash
+pip install .
+```
+
+Or build wheels for PyPI distribution:
+```bash
+python -m build
+twine upload dist/*
+```
+
+---
+
+## 🚀 Quickstart
+
+```python
+import tapirus
+
+# 1. Connect to an encrypted single-file database
+db = tapirus.connect("agent_memory.tapir", passphrase="super-secret-key")
+
+# 2. Relational SQL & Transactions
+db.execute("""
+    CREATE TABLE documents (
+        id INTEGER PRIMARY KEY,
+        title TEXT,
+        category TEXT,
+        embedding VECTOR(3)
+    );
+""")
+
+db.execute("""
+    INSERT INTO documents VALUES 
+    (1, 'Autonomous Drone Navigation', 'robotics', [0.99, 0.02, 0.01]),
+    (2, 'Soil Moisture Sensor Mesh', 'iot', [0.12, 0.95, 0.05]);
+""")
+
+# 3. Query
+rows = db.query("SELECT id, title, category FROM documents WHERE category = 'robotics';")
+for row in rows:
+    print(row)
+
+# 4. In-Memory Mode
+mem_db = tapirus.connect(":memory:")
+mem_db.execute("CREATE TABLE kv (k TEXT PRIMARY KEY, v TEXT);")
+```
+
+---
+
+## 🛡️ Architecture & Safety
+- **Single-File `.tapir` Container**: Unified relational SQL, document JSON, HNSW vectors, and openCypher knowledge graphs in one file.
+- **Hardware AES-256 GCM**: ChaCha20-Poly1305 AEAD with PBKDF2/SHA-256 salt verification.
+- **Zero Cloud Latency**: Runs entirely in-process (`0.55 µs` pointer dereference) without external server daemons.

tapirus-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+tapirus/__init__.py,sha256=3jhRhEF4MXGxJHq_hQdVbd_Bi3xj6wl51keQ039Bxv0,869
+tapirus/connection.py,sha256=jXfQHUDsk84QsZCmc0Jrar-83a_xbSulIyiwoQnNk8Q,5027
+tapirus/exceptions.py,sha256=UZI9_Q0Zw0--7ZNCp_70XRWbQCPn0mnB2yjbqs2llwk,602
+tapirus/ffi.py,sha256=hmwfVdnpPYgz5wE25W1p-NWMEKGCjOBxrSZ5b42vUGA,3147
+tapirus-1.0.0.dist-info/METADATA,sha256=4ymTf1uls4ZTQ-zDxM1nFQuTZSILoL1y2Pnt0ZQrZyo,2842
+tapirus-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+tapirus-1.0.0.dist-info/top_level.txt,sha256=Sz1x1UwllzFT1g3oZTPN0FctxUZeZ4pIVo9Gg3wrN9c,8
+tapirus-1.0.0.dist-info/RECORD,,

tapirus-1.0.0.dist-info/WHEEL

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

tapirus-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tapirus