orbmem 1.0.4__py3-none-any.whl

orbmem/__init__.py

@@ -0,0 +1,3 @@
+from orbmem.core.ocdb import OCDB
+
+__all__ = ["OCDB"]

orbmem/core/auth.py

@@ -0,0 +1,26 @@
+# core/auth.py
+
+from fastapi import Request
+from orbmem.utils.exceptions import AuthError
+from orbmem.core.config import load_config
+
+def validate_api_key(request: Request):
+    """
+    Validates API key using latest .env values.
+    Reloads config every time to avoid stale values.
+    """
+    config = load_config()  # <-- reloads fresh env each request
+
+    auth_header = request.headers.get("Authorization")
+    if not auth_header:
+        raise AuthError("Missing Authorization header")
+
+    if not auth_header.startswith("Bearer "):
+        raise AuthError("Invalid Authorization format. Use: Bearer <API_KEY>")
+
+    api_key = auth_header.replace("Bearer ", "").strip()
+
+    if api_key not in config.api.api_keys:
+        raise AuthError("Invalid API key. Access denied.")
+
+    return True

orbmem/core/config.py

@@ -0,0 +1,123 @@
+# core/config.py
+
+import os
+from dataclasses import dataclass
+from typing import List, Optional
+
+from dotenv import load_dotenv
+from orbmem.utils.exceptions import ConfigError
+
+
+# ===========================
+# DATA CLASSES
+# ===========================
+
+@dataclass
+class DatabaseConfig:
+    postgres_url: str
+    redis_url: Optional[str] = None
+    mongo_url: Optional[str] = None
+    neo4j_url: Optional[str] = None
+
+
+@dataclass
+class APIConfig:
+    api_keys: List[str]
+    debug: bool = False
+    mode: str = "local"   # local | cloud
+
+
+@dataclass
+class OCDBConfig:
+    db: DatabaseConfig
+    api: APIConfig
+
+
+# ===========================
+# HELPERS
+# ===========================
+
+def _get_env(name: str, default: Optional[str] = None, required: bool = False) -> Optional[str]:
+    """Fetch env variable with optional requirement."""
+    value = os.getenv(name, default)
+
+    # treat empty string as None
+    if value is not None:
+        value = value.strip()
+        if value == "":
+            value = None
+
+    if required and not value:
+        raise ConfigError(f"Missing required environment variable: {name}")
+
+    return value
+
+
+# ===========================
+# MAIN CONFIG LOADER
+# ===========================
+
+def load_config() -> OCDBConfig:
+    """
+    Load configuration fresh every call.
+    Respects OCDB_MODE (local/cloud).
+    """
+
+    # Reload .env every time (Windows safe)
+    load_dotenv(override=True)
+
+    # -------------------------------
+    # MODE: local or cloud
+    # -------------------------------
+    mode = _get_env("OCDB_MODE", default="local").lower()
+    if mode not in ("local", "cloud"):
+        raise ConfigError("OCDB_MODE must be either 'local' or 'cloud'")
+
+    # -------------------------------
+    # DATABASES
+    # -------------------------------
+    postgres_url = _get_env("POSTGRES_URL", required=True)
+    redis_url = _get_env("REDIS_URL")
+    mongo_url = _get_env("MONGO_URL")
+    neo4j_url = _get_env("NEO4J_URL")  # will be None in local mode
+
+    # -------------------------------
+    # API Keys (only required in cloud mode)
+    # -------------------------------
+    api_keys_raw = _get_env(
+        "OCDB_API_KEYS",
+        required=(mode == "cloud")  # Only required in cloud mode
+    )
+
+    api_keys = []
+    if api_keys_raw:
+        api_keys = [k.strip() for k in api_keys_raw.split(",") if k.strip()]
+
+    # -------------------------------
+    # DEBUG MODE
+    # -------------------------------
+    debug_raw = _get_env("OCDB_DEBUG", default="0")
+    debug = debug_raw.lower() in ("1", "true", "yes", "y")
+
+    # -------------------------------
+    # Build config objects
+    # -------------------------------
+    db_cfg = DatabaseConfig(
+        postgres_url=postgres_url,
+        redis_url=redis_url,
+        mongo_url=mongo_url,
+        neo4j_url=neo4j_url,
+    )
+
+    api_cfg = APIConfig(
+        api_keys=api_keys,
+        debug=debug,
+        mode=mode,
+    )
+
+    print(f"🔧 Loaded OCDB_MODE: {mode}")
+    print(f"🔐 Loaded API keys: {api_keys}")
+    print(f"🐬 Redis enabled: {bool(redis_url)}")
+    print(f"🧠 Neo4j enabled: {bool(neo4j_url)}")
+
+    return OCDBConfig(db=db_cfg, api=api_cfg)

orbmem/core/ocdb.py

@@ -0,0 +1,126 @@
+# core/ocdb.py
+
+from typing import Any, Optional, List
+from .config import load_config
+
+# MEMORY ENGINE (SQLite/Postgres hybrid)
+from orbmem.engines.memory.postgres_backend import PostgresMemoryBackend
+
+# VECTOR ENGINE – Qdrant fallback to FAISS / in-memory
+from orbmem.engines.vector.qdrant_backend import QdrantVectorBackend
+
+# GRAPH ENGINE – fallback to NetworkX (in-memory)
+from orbmem.engines.graph.neo4j_backend import Neo4jGraphBackend
+
+# SAFETY ENGINE
+from orbmem.engines.safety.mongo_backend import MongoSafetyBackend
+from orbmem.engines.safety.timeseries_backend import TimeSeriesSafetyBackend
+
+
+class OCDB:
+    """
+    High-level interface combining all cognitive engines:
+      - Memory Engine (Postgres only, Redis disabled)
+      - Vector Engine (FAISS fallback)
+      - Graph Engine (NetworkX fallback)
+      - Safety Engine (Mongo + TimeSeries)
+    """
+
+    def __init__(self):
+        cfg = load_config()
+
+        # -------------------------------
+        # MEMORY ENGINE (NO REDIS)
+        # -------------------------------
+        self.pg_memory = PostgresMemoryBackend()
+        self.redis_memory = None  # Fully disabled
+
+        # -------------------------------
+        # VECTOR ENGINE
+        # -------------------------------
+        self.vector_engine = QdrantVectorBackend()
+
+        # -------------------------------
+        # GRAPH ENGINE
+        # -------------------------------
+        self.graph_engine = Neo4jGraphBackend()
+
+        # -------------------------------
+        # SAFETY ENGINE
+        # -------------------------------
+        self.safety_event_engine = MongoSafetyBackend()
+        self.safety_timeseries = TimeSeriesSafetyBackend()
+
+    # =====================================================
+    # MEMORY METHODS — SAFE & CLEAN (NO REDIS)
+    # =====================================================
+
+    def memory_set(self, key: str, value: dict, session_id: str = None, ttl_seconds: int = None):
+        """
+        Store memory in Postgres only (Redis disabled).
+        """
+        return self.pg_memory.set(key, value, session_id=session_id, ttl_seconds=ttl_seconds)
+
+    def memory_get(self, key: str):
+        """
+        Retrieve memory from Postgres only.
+        """
+        return self.pg_memory.get(key)
+
+    def memory_keys(self) -> List[str]:
+        """
+        List all memory keys.
+        """
+        return self.pg_memory.keys()
+
+    # =====================================================
+    # VECTOR METHODS
+    # =====================================================
+
+    def vector_search(self, query: str, k: int = 5):
+        """
+        Search vector embeddings using FAISS fallback (no Qdrant needed).
+        """
+        return self.vector_engine.search(query, k=k)
+
+    # =====================================================
+    # GRAPH METHODS
+    # =====================================================
+
+    def graph_add(self, node_id: str, content: str, parent: Optional[str] = None):
+        """
+        Add a node to in-memory reasoning graph.
+        """
+        return self.graph_engine.add_node(node_id, content, parent)
+
+    def graph_path(self, start: str, end: str):
+        """
+        Get path between two graph nodes.
+        """
+        return self.graph_engine.get_path(start, end)
+
+    # =====================================================
+    # SAFETY METHODS
+    # =====================================================
+
+    def safety_scan(self, text: str):
+        """
+        Detect safety events and record in timeseries engine.
+        """
+        events = self.safety_event_engine.scan(text)
+
+        # update timeseries fingerprint
+        for evt in events:
+            self.safety_timeseries.add_point(evt.tag, evt.severity)
+
+        return [
+            {
+                "text": evt.text,
+                "tag": evt.tag,
+                "severity": evt.severity,
+                "correction": evt.correction,
+                "details": evt.details,
+                "timestamp": evt.timestamp,
+            }
+            for evt in events
+        ]

orbmem/db/mongo.py

@@ -0,0 +1,25 @@
+# db/mongo.py
+
+from pymongo import MongoClient
+from orbmem.core.config import load_config
+from orbmem.utils.logger import get_logger
+from orbmem.utils.exceptions import DatabaseError
+
+logger = get_logger(__name__)
+
+CONFIG = load_config()
+MONGO_URL = CONFIG.db.mongo_url
+
+
+def get_mongo_client():
+    """Get MongoDB client for safety engine."""
+    if not MONGO_URL:
+        return None
+
+    try:
+        client = MongoClient(MONGO_URL)
+        logger.info("MongoDB connection established.")
+        return client
+    except Exception as e:
+        logger.error(f"MongoDB connection failed: {e}")
+        raise DatabaseError(f"MongoDB init error: {e}")

orbmem/db/neo4j.py

@@ -0,0 +1,31 @@
+# db/neo4j.py
+
+from neo4j import GraphDatabase
+from orbmem.utils.logger import get_logger
+from orbmem.utils.exceptions import DatabaseError
+from orbmem.core.config import load_config
+
+logger = get_logger(__name__)
+
+_driver = None
+
+
+def get_neo4j_driver():
+    global _driver
+
+    if _driver:
+        return _driver
+
+    cfg = load_config()
+    url = cfg.db.neo4j_url
+    user = cfg.db.neo4j_user
+    password = cfg.db.neo4j_password
+
+    try:
+        _driver = GraphDatabase.driver(url, auth=(user, password))
+        logger.info("Neo4j driver initialized.")
+        return _driver
+
+    except Exception as e:
+        logger.error(f"Neo4j initialization failed: {e}")
+        raise DatabaseError(f"Neo4j init error: {e}")

orbmem/db/postgres.py

@@ -0,0 +1,36 @@
+# db/postgres.py
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker, declarative_base
+from orbmem.core.config import load_config
+from orbmem.utils.logger import get_logger
+from orbmem.utils.exceptions import DatabaseError
+
+logger = get_logger(__name__)
+
+# Load configuration
+CONFIG = load_config()
+POSTGRES_URL = CONFIG.db.postgres_url
+
+# Create SQLAlchemy engine
+try:
+    engine = create_engine(
+        POSTGRES_URL,
+        echo=False,
+        pool_pre_ping=True,   # auto-detect dead connections
+        pool_recycle=1800      # refresh stale connections
+    )
+    logger.info("PostgreSQL engine initialized successfully.")
+except Exception as e:
+    logger.error(f"Failed to initialize PostgreSQL engine: {e}")
+    raise DatabaseError(f"PostgreSQL init error: {e}")
+
+# Create database session factory
+SessionLocal = sessionmaker(
+    autocommit=False,
+    autoflush=False,
+    bind=engine
+)
+
+# Base class for all SQLAlchemy ORM models
+Base = declarative_base()

orbmem/db/redis.py

@@ -0,0 +1,25 @@
+# db/redis.py
+
+import redis
+from orbmem.core.config import load_config
+from orbmem.utils.logger import get_logger
+from orbmem.utils.exceptions import DatabaseError
+
+logger = get_logger(__name__)
+
+CONFIG = load_config()
+REDIS_URL = CONFIG.db.redis_url
+
+
+def get_redis_client():
+    """Create and return a Redis client instance."""
+    if not REDIS_URL:
+        return None
+
+    try:
+        client = redis.Redis.from_url(REDIS_URL, decode_responses=True)
+        logger.info("Redis connection established.")
+        return client
+    except Exception as e:
+        logger.error(f"Redis connection failed: {e}")
+        raise DatabaseError(f"Redis init error: {e}")

orbmem/engines/base_engine.py

@@ -0,0 +1,47 @@
+# engines/base_engine.py
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+
+class BaseEngine(ABC):
+    """
+    Abstract base class for all OCDB engines.
+    Defines optional generic methods common across engines.
+    """
+
+    # -------------------------------
+    # MEMORY-LIKE INTERFACES
+    # -------------------------------
+    def set(self, key: str, value: Any, **kwargs):
+        raise NotImplementedError("set() not implemented for this engine")
+
+    def get(self, key: str) -> Any:
+        raise NotImplementedError("get() not implemented for this engine")
+
+    def delete(self, key: str):
+        raise NotImplementedError("delete() not implemented for this engine")
+
+    # -------------------------------
+    # GRAPH-LIKE INTERFACES
+    # -------------------------------
+    def add_node(self, *args, **kwargs):
+        raise NotImplementedError("add_node() not implemented")
+
+    def get_path(self, *args, **kwargs):
+        raise NotImplementedError("get_path() not implemented")
+
+    # -------------------------------
+    # VECTOR-LIKE INTERFACES
+    # -------------------------------
+    def add_text(self, *args, **kwargs):
+        raise NotImplementedError("add_text() not implemented")
+
+    def search(self, *args, **kwargs):
+        raise NotImplementedError("search() not implemented")
+
+    # -------------------------------
+    # SAFETY-LIKE INTERFACES
+    # -------------------------------
+    def scan(self, *args, **kwargs):
+        raise NotImplementedError("scan() not implemented")

orbmem/engines/graph/neo4j_backend.py

@@ -0,0 +1,70 @@
+# engines/graph/neo4j_backend.py
+# In-memory Graph Engine using NetworkX (Neo4j replacement)
+
+import networkx as nx
+from typing import Dict, Any, List
+from orbmem.utils.logger import get_logger
+from orbmem.utils.exceptions import DatabaseError
+
+logger = get_logger(__name__)
+
+
+class Neo4jGraphBackend:
+    """
+    Lightweight in-memory graph engine using NetworkX.
+    Fully compatible with OCDB.graph_add() and OCDB.graph_path().
+    """
+
+    def __init__(self):
+        try:
+            self.graph = nx.DiGraph()
+            logger.info("In-memory Graph Engine initialized (NetworkX).")
+        except Exception as e:
+            raise DatabaseError(f"Failed to initialize graph engine: {e}")
+
+    # ---------------------------------------------------------
+    # MATCHES ocdb.graph_add(node_id, content, parent)
+    # ---------------------------------------------------------
+    def add_node(self, node_id: str, content: str, parent: str = None):
+        try:
+            # Add node with content property
+            self.graph.add_node(node_id, content=content)
+            logger.info(f"Graph node added: {node_id}")
+
+            # Add edge to parent if provided
+            if parent:
+                self.graph.add_edge(parent, node_id, relation="next")
+                logger.info(f"Graph edge added: {parent} -> {node_id}")
+
+            return {"node_id": node_id, "parent": parent}
+
+        except Exception as e:
+            raise DatabaseError(f"Failed adding node: {e}")
+
+    # ---------------------------------------------------------
+    # MATCHES ocdb.graph_path(start, end)
+    # ---------------------------------------------------------
+    def get_path(self, start: str, end: str) -> List[str]:
+        try:
+            return nx.shortest_path(self.graph, source=start, target=end)
+        except Exception:
+            return []
+
+    # ---------------------------------------------------------
+    # Debug export (optional)
+    # ---------------------------------------------------------
+    def export(self):
+        return {
+            "nodes": [
+                {"id": n, "properties": self.graph.nodes[n]}
+                for n in self.graph.nodes
+            ],
+            "edges": [
+                {
+                    "from": u,
+                    "to": v,
+                    "relation": self.graph.edges[u, v].get("relation", "next")
+                }
+                for u, v in self.graph.edges
+            ]
+        }

orbmem/engines/memory/postgres_backend.py

@@ -0,0 +1,112 @@
+# engines/memory/postgres_backend.py
+# Repurposed as SQLite backend (lightweight local mode)
+
+import json
+import sqlite3
+from datetime import datetime, timedelta
+from orbmem.utils.logger import get_logger
+from orbmem.utils.exceptions import DatabaseError
+
+logger = get_logger(__name__)
+
+DB_PATH = "ocdb.sqlite3"
+
+
+class PostgresMemoryBackend:
+    """
+    Lightweight SQLite-based memory engine.
+    Replaces PostgreSQL for systems with low storage.
+    """
+
+    def __init__(self):
+        try:
+            self.conn = sqlite3.connect(DB_PATH, check_same_thread=False)
+            self.cursor = self.conn.cursor()
+            self._init_tables()
+            logger.info("SQLite Memory Backend initialized (replacing PostgreSQL).")
+        except Exception as e:
+            raise DatabaseError(f"SQLite init error: {e}")
+
+    # ---------------------------------------------------------
+    # Create tables if missing
+    # ---------------------------------------------------------
+    def _init_tables(self):
+        self.cursor.execute("""
+            CREATE TABLE IF NOT EXISTS memory (
+                key TEXT PRIMARY KEY,
+                value TEXT,
+                session_id TEXT,
+                expires_at TEXT
+            )
+        """)
+        self.conn.commit()
+
+    # ---------------------------------------------------------
+    # Set memory key
+    # ---------------------------------------------------------
+    def set(self, key: str, value, session_id: str = None, ttl_seconds: int = None):
+        try:
+            expires_at = None
+            if ttl_seconds:
+                expires_at = (datetime.utcnow() + timedelta(seconds=ttl_seconds)).isoformat()
+
+            value_json = json.dumps(value)
+
+            self.cursor.execute("""
+                INSERT INTO memory (key, value, session_id, expires_at)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(key) DO UPDATE SET
+                    value=excluded.value,
+                    session_id=excluded.session_id,
+                    expires_at=excluded.expires_at
+            """, (key, value_json, session_id, expires_at))
+
+            self.conn.commit()
+
+        except Exception as e:
+            raise DatabaseError(f"SQLite write error: {e}")
+
+    # ---------------------------------------------------------
+    # Get memory key
+    # ---------------------------------------------------------
+    def get(self, key: str):
+        try:
+            self.cursor.execute("SELECT value, expires_at FROM memory WHERE key=?", (key,))
+            row = self.cursor.fetchone()
+
+            if not row:
+                return None
+
+            value_json, expires_at = row
+
+            # TTL check
+            if expires_at:
+                if datetime.utcnow() > datetime.fromisoformat(expires_at):
+                    self.delete(key)
+                    return None
+
+            return json.loads(value_json)
+
+        except Exception as e:
+            raise DatabaseError(f"SQLite read error: {e}")
+
+    # ---------------------------------------------------------
+    # Delete a memory key
+    # ---------------------------------------------------------
+    def delete(self, key: str):
+        try:
+            self.cursor.execute("DELETE FROM memory WHERE key=?", (key,))
+            self.conn.commit()
+        except Exception as e:
+            raise DatabaseError(f"SQLite delete error: {e}")
+
+    # ---------------------------------------------------------
+    # List memory keys
+    # ---------------------------------------------------------
+    def keys(self):
+        try:
+            self.cursor.execute("SELECT key FROM memory")
+            rows = self.cursor.fetchall()
+            return [r[0] for r in rows]
+        except Exception as e:
+            raise DatabaseError(f"SQLite keys error: {e}")