bulldb 1.0.0__tar.gz

bulldb-1.0.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: bulldb
+Version: 1.0.0
+Summary: One Model. Every Database.
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: passlib>=1.7.4
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: redis>=5.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"

bulldb-1.0.0/bulldb/__init__.py

@@ -0,0 +1,48 @@
+from .models import BaseModel, PrimaryKey, Unique, Index, Relationship
+from .database import MultiDatabase
+from .generator import ModelGenerator
+from .adapters import FastAPILifespan, FlaskMiddleware, SanicMiddleware
+from .types import (
+    UUID, ULID, Email, Phone, URL, IPAddress, JSON, JSONB, Array,
+    Enum, Money, Decimal, TimestampTZ, EncryptedString, HashedPassword,
+    Secret, Binary, GeoPoint, Polygon, Vector, Embedding, Document,
+    ImageEmbedding, AudioEmbedding, VideoEmbedding
+)
+
+__all__ = [
+    "BaseModel",
+    "PrimaryKey",
+    "Unique",
+    "Index",
+    "Relationship",
+    "MultiDatabase",
+    "ModelGenerator",
+    "FastAPILifespan",
+    "FlaskMiddleware",
+    "SanicMiddleware",
+    "UUID",
+    "ULID",
+    "Email",
+    "Phone",
+    "URL",
+    "IPAddress",
+    "JSON",
+    "JSONB",
+    "Array",
+    "Enum",
+    "Money",
+    "Decimal",
+    "TimestampTZ",
+    "EncryptedString",
+    "HashedPassword",
+    "Secret",
+    "Binary",
+    "GeoPoint",
+    "Polygon",
+    "Vector",
+    "Embedding",
+    "Document",
+    "ImageEmbedding",
+    "AudioEmbedding",
+    "VideoEmbedding"
+]

bulldb-1.0.0/bulldb/adapters.py

@@ -0,0 +1,89 @@
+from contextlib import asynccontextmanager
+from typing import Callable, Any
+
+class FastAPILifespan:
+    def __init__(self, db_client: Any):
+        self.db_client = db_client
+
+    @asynccontextmanager
+    async def lifespan(self, app: Any):
+        # 1. Connect all pools on startup
+        await self.db_client.connect_all()
+        # Register db in BaseModel
+        from .models import BaseModel
+        BaseModel.set_db(self.db_client)
+        
+        yield # Application executes
+        
+        # 2. Cleanup pools on shutdown
+        await self.db_client.disconnect_all()
+
+
+class FlaskMiddleware:
+    def __init__(self, app: Any, db_client: Any):
+        self.app = app
+        self.db_client = db_client
+        self.setup_lifecycle()
+
+    def setup_lifecycle(self):
+        # Flask requests setup/teardowns hook
+        from .models import BaseModel
+        BaseModel.set_db(self.db_client)
+
+        @self.app.before_request
+        def before_request_hook():
+            pass
+
+        @self.app.teardown_request
+        def teardown_request_hook(exception=None):
+            pass
+
+
+class SanicMiddleware:
+    @staticmethod
+    def register(app: Any, db_client: Any):
+        from .models import BaseModel
+
+        @app.listener("before_server_start")
+        async def setup_db(app_instance, loop):
+            await db_client.connect_all()
+            BaseModel.set_db(db_client)
+
+        @app.listener("after_server_stop")
+        async def close_db(app_instance, loop):
+            await db_client.disconnect_all()
+
+
+class DjangoMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        from .models import BaseModel
+        from .database import db
+        BaseModel.set_db(db)
+        
+        response = self.get_response(request)
+        return response
+
+
+class DjangoLifecycle:
+    @staticmethod
+    def register(db_client: Any = None):
+        try:
+            from django.core.signals import request_started, request_finished
+            from .models import BaseModel
+            from .database import db
+            
+            target_db = db_client or db
+
+            def on_request_started(sender, **kwargs):
+                BaseModel.set_db(target_db)
+
+            def on_request_finished(sender, **kwargs):
+                pass
+
+            request_started.connect(on_request_started)
+            request_finished.connect(on_request_finished)
+        except Exception:
+            pass

bulldb-1.0.0/bulldb/ai.py

@@ -0,0 +1,121 @@
+import os
+from typing import List, Dict, Any, Optional
+import httpx
+
+class AIEngine:
+    _embedding_cache: Dict[str, List[float]] = {}
+
+    @classmethod
+    async def generate_embeddings(cls, text: str, provider: str = "openai") -> List[float]:
+        # Clean string
+        text = text.replace("\n", " ").strip()
+        if not text:
+            return [0.0] * 1536
+
+        # Check Cache
+        if text in cls._embedding_cache:
+            return cls._embedding_cache[text]
+
+        # Call remote API or trigger local/mock fallback
+        api_key = os.getenv("OPENAI_API_KEY")
+        gemini_key = os.getenv("GEMINI_API_KEY")
+        ollama_url = os.getenv("OLLAMA_URL", "http://localhost:11434")
+
+        try:
+            if provider == "openai" and api_key:
+                async with httpx.AsyncClient(timeout=10.0) as client:
+                    resp = await client.post(
+                        "https://api.openai.com/v1/embeddings",
+                        headers={"Authorization": f"Bearer {api_key}"},
+                        json={"input": text, "model": "text-embedding-3-small"}
+                    )
+                    resp.raise_for_status()
+                    vector = resp.json()["data"][0]["embedding"]
+                    cls._embedding_cache[text] = vector
+                    return vector
+            elif provider == "gemini" and gemini_key:
+                async with httpx.AsyncClient(timeout=10.0) as client:
+                    resp = await client.post(
+                        f"https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:embedContent?key={gemini_key}",
+                        json={"content": {"parts": [{"text": text}]}}
+                    )
+                    resp.raise_for_status()
+                    vector = resp.json()["embedding"]["values"]
+                    cls._embedding_cache[text] = vector
+                    return vector
+            elif provider == "ollama":
+                async with httpx.AsyncClient(timeout=10.0) as client:
+                    resp = await client.post(
+                        f"{ollama_url}/api/embeddings",
+                        json={"model": "nomic-embed-text", "prompt": text}
+                    )
+                    resp.raise_for_status()
+                    vector = resp.json()["embedding"]
+                    cls._embedding_cache[text] = vector
+                    return vector
+        except Exception:
+            # Fallback embedding generation using hash weights (deterministic, zero-dependency)
+            return cls._generate_mock_vector(text)
+
+        return cls._generate_mock_vector(text)
+
+    @classmethod
+    def _generate_mock_vector(cls, text: str, dimension: int = 1536) -> List[float]:
+        # Generate pseudo-random deterministic vector based on text characters
+        import hashlib
+        h = hashlib.sha256(text.encode("utf-8")).digest()
+        vector = []
+        for i in range(dimension):
+            byte_idx = (i * 7) % len(h)
+            weight = (h[byte_idx] / 255.0) - 0.5
+            vector.append(weight)
+        
+        # L2 Normalize
+        import math
+        norm = math.sqrt(sum(x*x for x in vector))
+        if norm > 0:
+            vector = [x / norm for x in vector]
+        return vector
+
+class TextChunker:
+    @staticmethod
+    def chunk_text(text: str, chunk_size: int = 500, chunk_overlap: int = 50) -> List[str]:
+        if not text:
+            return []
+        
+        words = text.split()
+        chunks = []
+        i = 0
+        while i < len(words):
+            chunk_words = words[i : i + chunk_size]
+            chunks.append(" ".join(chunk_words))
+            i += (chunk_size - chunk_overlap)
+            if i <= 0:
+                break
+        return chunks
+
+class RAGPipeline:
+    def __init__(self, model_class: Any, embedding_field: str, text_field: str):
+        self.model_class = model_class
+        self.embedding_field = embedding_field
+        self.text_field = text_field
+
+    async def ingest_document(self, text: str, extra_meta: Optional[dict] = None) -> Any:
+        chunks = TextChunker.chunk_text(text)
+        inserted_instances = []
+        for chunk in chunks:
+            payload = {self.text_field: chunk}
+            if extra_meta:
+                payload.update(extra_meta)
+            
+            # create and save model (triggers auto-embedding generation hook)
+            instance = self.model_class(**payload)
+            await instance.save()
+            inserted_instances.append(instance)
+        return inserted_instances
+
+    async def query_similarity(self, query_text: str, limit: int = 5) -> List[Any]:
+        # 1. Generate query embedding
+        query_vector = await AIEngine.generate_embeddings(query_text)
+        # 2. Query builder vector search
+        return await self.model_class.find().vector_search(self.embedding_field, query_vector, limit).execute()

bulldb-1.0.0/bulldb/database.py

@@ -0,0 +1,313 @@
+import os
+import urllib.parse
+import asyncio
+import logging
+from typing import Dict, Any, List, Optional, Callable
+
+logger = logging.getLogger("bulldb.database")
+
+class CircuitBreakerOpenException(Exception):
+    pass
+
+class CircuitBreaker:
+    def __init__(self, failure_threshold: int = 5, recovery_timeout: float = 10.0):
+        self.failure_threshold = failure_threshold
+        self.recovery_timeout = recovery_timeout
+        self.failure_count = 0
+        self.state = "CLOSED" # CLOSED, OPEN, HALF-OPEN
+        self.last_state_change = 0.0
+
+    def record_success(self):
+        self.failure_count = 0
+        self.state = "CLOSED"
+
+    def record_failure(self):
+        self.failure_count += 1
+        import time
+        if self.failure_count >= self.failure_threshold:
+            self.state = "OPEN"
+            self.last_state_change = time.time()
+            logger.warning(f"Circuit breaker tripped! State set to OPEN. Threshold: {self.failure_threshold}")
+
+    def allow_request(self) -> bool:
+        import time
+        if self.state == "CLOSED":
+            return True
+        if self.state == "OPEN":
+            if time.time() - self.last_state_change > self.recovery_timeout:
+                self.state = "HALF-OPEN"
+                logger.info("Circuit breaker entering HALF-OPEN state, checking system viability.")
+                return True
+            return False
+        if self.state == "HALF-OPEN":
+            return True
+        return False
+
+class DatabaseDriver:
+    def __init__(self, name: str, url: str):
+        self.name = name
+        self.url = url
+        self.parsed_url = urllib.parse.urlparse(url)
+        self.circuit_breaker = CircuitBreaker()
+
+    async def connect(self):
+        pass
+
+    async def disconnect(self):
+        pass
+
+    async def ping(self) -> bool:
+        return True
+
+    async def ensure_connected(self):
+        try:
+            if not await self.ping():
+                await self.connect()
+        except Exception:
+            await self.connect()
+
+    async def execute(self, query: str, params: Optional[tuple] = None) -> List[Dict[str, Any]]:
+        return []
+
+    async def insert(self, table: str, payload: Dict[str, Any]) -> Any:
+        return {}
+
+    async def update(self, table: str, payload: Dict[str, Any], filters: Dict[str, Any]) -> Any:
+        return {}
+
+    async def delete(self, table: str, filters: Dict[str, Any]) -> Any:
+        return {}
+
+    async def execute_mongo_find(self, collection: str, filters: Dict[str, Any], projection: Dict[str, Any], limit: Optional[int]) -> List[Dict[str, Any]]:
+        if hasattr(self, "db") and not isinstance(self.db, dict):
+            cursor = self.db[collection].find(filters, projection)
+            if limit:
+                cursor = cursor.limit(limit)
+            return list(cursor)
+        return []
+
+    async def execute_search(self, index: str, body: Dict[str, Any], limit: int) -> List[Dict[str, Any]]:
+        return []
+
+    async def execute_vector_search(self, collection: str, vector: Optional[List[float]], filters: Dict[str, Any], limit: int) -> List[Dict[str, Any]]:
+        return []
+
+class SQLiteDriver(DatabaseDriver):
+    async def connect(self):
+        # In-memory or file-based sqlite3
+        import sqlite3
+        db_path = self.parsed_url.path.strip("/") or ":memory:"
+        if hasattr(self, "conn") and self.conn:
+            try:
+                self.conn.close()
+            except Exception:
+                pass
+        self.conn = sqlite3.connect(db_path, check_same_thread=False)
+        self.conn.row_factory = sqlite3.Row
+        self.cursor = self.conn.cursor()
+
+    async def disconnect(self):
+        if hasattr(self, "conn") and self.conn:
+            try:
+                self.conn.close()
+            except Exception:
+                pass
+
+    async def ping(self) -> bool:
+        try:
+            if not hasattr(self, "cursor") or self.cursor is None:
+                return False
+            self.cursor.execute("SELECT 1")
+            return True
+        except Exception:
+            return False
+
+    async def execute(self, query: str, params: Optional[tuple] = None) -> List[Dict[str, Any]]:
+        if not self.circuit_breaker.allow_request():
+            raise CircuitBreakerOpenException(f"Database driver {self.name} circuit is OPEN")
+        try:
+            self.cursor.execute(query, params or ())
+            self.conn.commit()
+            rows = self.cursor.fetchall()
+            self.circuit_breaker.record_success()
+            return [dict(row) for row in rows]
+        except Exception as e:
+            self.circuit_breaker.record_failure()
+            raise e
+
+    async def insert(self, table: str, payload: Dict[str, Any]) -> Any:
+        keys = list(payload.keys())
+        values = list(payload.values())
+        placeholders = ", ".join(["?" for _ in keys])
+        query = f"INSERT INTO {table} ({', '.join(keys)}) VALUES ({placeholders})"
+        await self.execute(query, tuple(values))
+        return payload
+
+    async def update(self, table: str, payload: Dict[str, Any], filters: Dict[str, Any]) -> Any:
+        set_clause = ", ".join([f"{k} = ?" for k in payload.keys()])
+        where_clause = " AND ".join([f"{k} = ?" for k in filters.keys()])
+        query = f"UPDATE {table} SET {set_clause} WHERE {where_clause}"
+        params = tuple(list(payload.values()) + list(filters.values()))
+        await self.execute(query, params)
+        return payload
+
+    async def delete(self, table: str, filters: Dict[str, Any]) -> Any:
+        where_clause = " AND ".join([f"{k} = ?" for k in filters.keys()])
+        query = f"DELETE FROM {table} WHERE {where_clause}"
+        await self.execute(query, tuple(filters.values()))
+        return True
+
+class MongoDriver(DatabaseDriver):
+    async def connect(self):
+        # Dynamically import pymongo
+        try:
+            from pymongo import MongoClient
+            if hasattr(self, "client") and self.client:
+                try:
+                    self.client.close()
+                except Exception:
+                    pass
+            self.client = MongoClient(self.url)
+            db_name = self.parsed_url.path.strip("/") or "bulldb"
+            self.db = self.client[db_name]
+        except ImportError:
+            # Fallback mock for testing in case pymongo isn't installed
+            self.db = {}
+
+    async def disconnect(self):
+        if hasattr(self, "client") and self.client:
+            try:
+                self.client.close()
+            except Exception:
+                pass
+
+    async def ping(self) -> bool:
+        if isinstance(self.db, dict): return True
+        try:
+            self.client.admin.command('ping')
+            return True
+        except Exception:
+            return False
+
+    async def insert(self, table: str, payload: Dict[str, Any]) -> Any:
+        if isinstance(self.db, dict): return payload
+        self.db[table].insert_one(payload)
+        return payload
+
+    async def update(self, table: str, payload: Dict[str, Any], filters: Dict[str, Any]) -> Any:
+        if isinstance(self.db, dict): return payload
+        self.db[table].update_many(filters, {"$set": payload})
+        return payload
+
+    async def delete(self, table: str, filters: Dict[str, Any]) -> Any:
+        if isinstance(self.db, dict): return True
+        self.db[table].delete_many(filters)
+        return True
+
+class MultiDatabase:
+    def __init__(self):
+        self.drivers: Dict[str, DatabaseDriver] = {}
+        self.primary_name: Optional[str] = None
+        self.replicas: List[str] = []
+        self.shards: Dict[str, List[str]] = {}
+        self.discover_environment()
+
+    def discover_environment(self):
+        # Auto DB detection from standard environment variables
+        env_mappings = {
+            "SQLITE_URL": "sqlite",
+            "POSTGRES_URL": "postgres",
+            "DATABASE_URL": "postgres",
+            "MYSQL_URL": "mysql",
+            "MONGO_URL": "mongo"
+        }
+        for env_var, engine in env_mappings.items():
+            url = os.getenv(env_var)
+            if url:
+                self.register_database(engine, url)
+                if not self.primary_name:
+                    self.primary_name = engine
+
+        # Default SQLite memory driver if no variables exist
+        if not self.drivers:
+            self.register_database("sqlite", "sqlite:///:memory:")
+            self.primary_name = "sqlite"
+
+    def register_database(self, name: str, url: str, is_replica: bool = False, shard_key: Optional[str] = None):
+        if url.startswith("sqlite"):
+            driver = SQLiteDriver(name, url)
+        elif url.startswith("mongodb"):
+            driver = MongoDriver(name, url)
+        else:
+            driver = DatabaseDriver(name, url) # Generic wrapper
+
+        self.drivers[name] = driver
+        if is_replica:
+            self.replicas.append(name)
+        
+        if shard_key:
+            if shard_key not in self.shards:
+                self.shards[shard_key] = []
+            self.shards[shard_key].append(name)
+
+    async def connect_all(self):
+        for driver in self.drivers.values():
+            await driver.connect()
+
+    async def disconnect_all(self):
+        for driver in self.drivers.values():
+            await driver.disconnect()
+
+    def get_route(self, table: str, is_write: bool = False, shard_id: Optional[str] = None) -> DatabaseDriver:
+        # 1. Sharding routing
+        if shard_id and shard_id in self.shards:
+            target_names = self.shards[shard_id]
+            import random
+            return self.drivers[random.choice(target_names)]
+
+        # 2. Read/Write splitting
+        if not is_write and self.replicas:
+            import random
+            return self.drivers[random.choice(self.replicas)]
+
+        # 3. Default to primary
+        return self.drivers[self.primary_name]
+
+    async def execute(self, query: str, params: Optional[tuple] = None, is_write: bool = False) -> List[Dict[str, Any]]:
+        driver = self.get_route("", is_write=is_write)
+        return await self._retry_with_backoff(driver, driver.execute, query, params)
+
+    async def write(self, table: str, payload: Dict[str, Any], upsert: bool = False) -> Any:
+        driver = self.get_route(table, is_write=True)
+        await driver.ensure_connected()
+        if upsert:
+            pk_field = "id"
+            pk_val = payload.get(pk_field)
+            if pk_val:
+                # check existence
+                check_query = f"SELECT {pk_field} FROM {table} WHERE {pk_field} = ?"
+                exists = await driver.execute(check_query, (pk_val,))
+                if exists:
+                    filters = {pk_field: pk_val}
+                    payload_no_pk = {k: v for k, v in payload.items() if k != pk_field}
+                    return await driver.update(table, payload_no_pk, filters)
+        return await driver.insert(table, payload)
+
+    async def delete(self, table: str, filters: Dict[str, Any]) -> Any:
+        driver = self.get_route(table, is_write=True)
+        await driver.ensure_connected()
+        return await driver.delete(table, filters)
+
+    async def _retry_with_backoff(self, driver: DatabaseDriver, func: Callable, *args, retries: int = 3, initial_delay: float = 0.5, **kwargs):
+        delay = initial_delay
+        last_exception = None
+        for i in range(retries):
+            try:
+                await driver.ensure_connected()
+                return await func(*args, **kwargs)
+            except Exception as e:
+                last_exception = e
+                logger.warning(f"Database operation failed. Retry {i+1}/{retries} in {delay}s. Error: {str(e)}")
+                await asyncio.sleep(delay)
+                delay *= 2
+        raise last_exception or Exception("Database execution retries exhausted.")

bulldb-1.0.0/bulldb/generator.py

@@ -0,0 +1,99 @@
+import os
+from typing import Any, List, Dict
+
+class ModelGenerator:
+    @staticmethod
+    async def reverse_engineer(db: Any, output_path: str):
+        driver_name = db.primary_name
+        
+        # 1. Fetch tables
+        tables = []
+        try:
+            if "sqlite" in driver_name:
+                sql = "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE 'bulldb_%'"
+                rows = await db.execute(sql)
+                tables = [r["name"] for r in rows]
+            else:
+                # postgres information_schema
+                sql = "SELECT table_name FROM information_schema.tables WHERE table_schema='public' AND table_name NOT LIKE 'bulldb_%'"
+                rows = await db.execute(sql)
+                tables = [r["table_name"] for r in rows]
+        except Exception as e:
+            # fallback tables for mock
+            tables = ["users"]
+
+        # 2. Build model class definitions
+        lines = [
+            "from bulldb import BaseModel, PrimaryKey, Unique, Index, UUID, Email, EncryptedString, HashedPassword\n",
+            "# Automatically generated by BullDB Reverse-Engineering Generator\n"
+        ]
+
+        for table in tables:
+            class_name = "".join([part.capitalize() for part in table.split("_")]).rstrip("s")
+            if not class_name:
+                class_name = "Model"
+            
+            lines.append(f"class {class_name}(BaseModel):")
+            lines.append(f"    __table_name__ = '{table}'\n")
+
+            # Fetch columns details
+            columns = []
+            try:
+                if "sqlite" in driver_name:
+                    col_rows = await db.execute(f"PRAGMA table_info({table})")
+                    for r in col_rows:
+                        columns.append({
+                            "name": r["name"],
+                            "type": r["type"].upper(),
+                            "pk": r["pk"] == 1
+                        })
+                else:
+                    col_rows = await db.execute(
+                        f"SELECT column_name, data_type FROM information_schema.columns WHERE table_name = '{table}'"
+                    )
+                    for r in col_rows:
+                        columns.append({
+                            "name": r["column_name"],
+                            "type": r["data_type"].upper(),
+                            "pk": False # fallback pk parser or check constraint
+                        })
+            except Exception:
+                # mock table fields fallback
+                columns = [
+                    {"name": "id", "type": "TEXT", "pk": True},
+                    {"name": "email", "type": "TEXT", "pk": False},
+                    {"name": "secret_note", "type": "BLOB", "pk": False}
+                ]
+
+            for col in columns:
+                col_name = col["name"]
+                db_type = col["type"]
+                is_pk = col["pk"]
+
+                # Map back to Universal Types
+                mapped_type = "str"
+                decorator = ""
+                if is_pk:
+                    mapped_type = "UUID"
+                    decorator = " = PrimaryKey()"
+                elif "INT" in db_type:
+                    mapped_type = "int"
+                elif "FLOAT" in db_type or "NUMERIC" in db_type or "REAL" in db_type:
+                    mapped_type = "float"
+                elif "BLOB" in db_type or "BYTEA" in db_type:
+                    mapped_type = "str"
+                    decorator = " = EncryptedString()"
+                else:
+                    if "EMAIL" in col_name.upper():
+                        mapped_type = "Email"
+                        decorator = " = Unique()"
+                    else:
+                        mapped_type = "str"
+
+                lines.append(f"    {col_name}: {mapped_type}{decorator}")
+            lines.append("\n")
+
+        # Write to file
+        os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write("\n".join(lines))