orbmem 1.0.4__py3-none-any.whl

orbmem/engines/memory/redis_backend.py

@@ -0,0 +1,85 @@
+# engines/memory/redis_backend.py
+
+import json
+from typing import Any, Dict, Optional, List
+from orbmem.db.redis import get_redis_client
+from orbmem.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class RedisMemoryBackend:
+    """
+    High-speed TTL memory using Redis.
+    Best for short-term memory, active sessions, caching.
+    """
+
+    def __init__(self):
+        self.client = get_redis_client()
+        if self.client:
+            logger.info("RedisMemoryBackend initialized.")
+        else:
+            logger.warning("REDIS_URL not configured. RedisBackend disabled.")
+
+    # ---------------------------------------------------------
+    # Core Operations
+    # ---------------------------------------------------------
+    def set(self, key: str, value: Any, ttl_seconds: Optional[int] = None):
+        if not self.client:
+            return
+
+        value_json = json.dumps(value)
+        if ttl_seconds:
+            self.client.setex(key, ttl_seconds, value_json)
+        else:
+            self.client.set(key, value_json)
+
+        logger.info(f"[Redis] Set key '{key}'")
+
+    def get(self, key: str) -> Optional[Any]:
+        if not self.client:
+            return None
+
+        val = self.client.get(key)
+        if val is None:
+            return None
+
+        return json.loads(val)
+
+    def delete(self, key: str):
+        if self.client:
+            self.client.delete(key)
+            logger.info(f"[Redis] Deleted key '{key}'")
+
+    def keys(self) -> List[str]:
+        if not self.client:
+            return []
+        return [k for k in self.client.keys("*")]
+
+    # ---------------------------------------------------------
+    # Session support via prefixing (session:<id>:key)
+    # ---------------------------------------------------------
+    def set_session(self, session_id: str, key: str, value: Any, ttl: Optional[int] = None):
+        full_key = f"session:{session_id}:{key}"
+        self.set(full_key, value, ttl)
+
+    def get_session(self, session_id: str) -> Dict[str, Any]:
+        if not self.client:
+            return {}
+
+        pattern = f"session:{session_id}:*"
+        results = {}
+        for key in self.client.keys(pattern):
+            clean_key = key.decode().split(":", 2)[2]
+            results[clean_key] = self.get(key)
+        return results
+
+    def delete_session(self, session_id: str):
+        if not self.client:
+            return
+
+        pattern = f"session:{session_id}:*"
+        for key in self.client.keys(pattern):
+            self.client.delete(key)
+
+        logger.info(f"[Redis] Deleted session '{session_id}'")

orbmem/engines/safety/mongo_backend.py

@@ -0,0 +1,97 @@
+# engines/safety/mongo_backend.py
+
+import re
+import time
+from typing import List, Dict, Any, Optional
+
+from orbmem.db.mongo import get_mongo_client
+from orbmem.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class SafetyEvent:
+    """
+    Represents a detected safety violation.
+    """
+
+    def __init__(
+        self,
+        text: str,
+        tag: str,
+        severity: float,
+        correction: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ):
+        self.text = text
+        self.tag = tag
+        self.severity = severity
+        self.correction = correction or None
+        self.details = metadata or {}
+        self.timestamp = time.time()
+
+    def to_dict(self):
+        return {
+            "text": self.text,
+            "tag": self.tag,
+            "severity": self.severity,
+            "correction": self.correction,
+            "details": self.details,
+            "timestamp": self.timestamp,
+        }
+
+
+class MongoSafetyBackend:
+    """
+    Scans text for unsafe content and logs events to MongoDB.
+    """
+
+    DEFAULT_PATTERNS = {
+        "self_harm": re.compile(r"(suicide|kill myself|hurt myself)", re.IGNORECASE),
+        "violence": re.compile(r"(kill|shoot|stab|attack)", re.IGNORECASE),
+        "hate": re.compile(r"(racial slur|hate\s+speech|bigot)", re.IGNORECASE),
+        "privacy": re.compile(r"(password|otp|aadhaar|credit card)", re.IGNORECASE),
+    }
+
+    def __init__(self):
+        self.client = get_mongo_client()
+        if self.client:
+            self.collection = self.client["ocdb"]["safety_events"]
+            logger.info("MongoSafetyBackend initialized.")
+        else:
+            self.collection = None
+            logger.warning("MongoSafetyBackend disabled (no MongoDB).")
+
+    # ---------------------------------------------------------
+    # Scoring model
+    # ---------------------------------------------------------
+    def _severity(self, tag: str, text: str) -> float:
+        base = {
+            "self_harm": 0.9,
+            "violence": 0.7,
+            "hate": 0.8,
+            "privacy": 0.6,
+        }.get(tag, 0.5)
+
+        length_factor = min(len(text) / 200, 1.0)
+        return round(base * length_factor, 3)
+
+    # ---------------------------------------------------------
+    # Main scan function
+    # ---------------------------------------------------------
+    def scan(self, text: str, metadata: Optional[Dict[str, Any]] = None) -> List[SafetyEvent]:
+        if not text:
+            return []
+
+        events = []
+
+        for tag, pattern in self.DEFAULT_PATTERNS.items():
+            if pattern.search(text):
+                severity = self._severity(tag, text)
+                evt = SafetyEvent(text, tag, severity, metadata=metadata)
+                events.append(evt)
+
+                if self.collection:
+                    self.collection.insert_one(evt.to_dict())
+
+        return events

orbmem/engines/safety/timeseries_backend.py

@@ -0,0 +1,36 @@
+# engines/safety/timeseries_backend.py
+
+import time
+from typing import Dict, List
+
+from orbmem.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class TimeSeriesSafetyBackend:
+    """
+    Stores a simple in-memory safety fingerprint time series.
+    In production, this could be replaced with TimescaleDB, InfluxDB, etc.
+    """
+
+    def __init__(self):
+        self.store: Dict[str, List[Dict]] = {}
+        logger.info("TimeSeriesSafetyBackend initialized.")
+
+    def add_point(self, tag: str, severity: float):
+        """
+        Adds a timestamped event to the timeseries.
+        """
+        if tag not in self.store:
+            self.store[tag] = []
+
+        self.store[tag].append({
+            "timestamp": time.time(),
+            "score": severity
+        })
+
+        logger.info(f"Added safety point: tag={tag}, severity={severity}")
+
+    def get_series(self, tag: str):
+        return self.store.get(tag, [])

orbmem/engines/vector/qdrant_backend.py

@@ -0,0 +1,75 @@
+# engines/vector/qdrant_backend.py
+# FAISS fallback vector engine (no Qdrant required)
+
+import faiss
+import numpy as np
+from typing import List, Dict, Any
+from ...utils.logger import get_logger
+from ...utils.embeddings import embed_text
+from orbmem.utils.exceptions import DatabaseError
+
+logger = get_logger(__name__)
+
+
+class QdrantVectorBackend:
+    """
+    Lightweight FAISS-based vector engine.
+    Behaves like Qdrant but stores vectors in-memory.
+    Fully compatible with OCDB vector API.
+    """
+
+    def __init__(self, dim: int = 384):
+        self.dim = dim
+
+        # FAISS L2 index for similarity search
+        self.index = faiss.IndexFlatL2(dim)
+
+        # Store payloads manually
+        self.payloads: List[Dict[str, Any]] = []
+
+        logger.info("FAISS vector engine initialized (Qdrant replacement).")
+
+    # ---------------------------------------------------------
+    # Insert text into vector DB
+    # ---------------------------------------------------------
+    def add_text(self, text: str, payload: Dict[str, Any]):
+        try:
+            vector = np.array([embed_text(text)], dtype="float32")
+
+            self.index.add(vector)
+            self.payloads.append(payload)
+
+            logger.info(f"Vector added for ID={payload.get('id')}")
+
+        except Exception as e:
+            logger.error(f"FAISS add_text error: {e}")
+            raise DatabaseError(str(e))
+
+    # ---------------------------------------------------------
+    # Search for similar vectors
+    # ---------------------------------------------------------
+    def search(self, query: str, k: int = 5) -> List[Dict[str, Any]]:
+        try:
+            vector = np.array([embed_text(query)], dtype="float32")
+
+            # If nothing stored yet
+            if self.index.ntotal == 0:
+                return []
+
+            distances, indices = self.index.search(vector, k)
+
+            results = []
+            for dist, idx in zip(distances[0], indices[0]):
+                if idx == -1:
+                    continue
+
+                results.append({
+                    "score": float(dist),
+                    "payload": self.payloads[idx]
+                })
+
+            return results
+
+        except Exception as e:
+            logger.error(f"FAISS search error: {e}")
+            raise DatabaseError(str(e))

orbmem/models/__init__.py

@@ -0,0 +1,11 @@
+# models/__init__.py
+
+from .memory import MemoryRecord
+from .safety import SafetyEvent
+from .fingerprints import SafetyFingerprint
+
+__all__ = [
+    "MemoryRecord",
+    "SafetyEvent",
+    "SafetyFingerprint",
+]

orbmem/models/fingerprints.py

@@ -0,0 +1,13 @@
+# models/fingerprints.py
+
+from sqlalchemy import Column, Integer, String, Float, TIMESTAMP
+from sqlalchemy.sql import func
+from orbmem.db.postgres import Base
+
+class SafetyFingerprint(Base):
+    __tablename__ = "safety_fingerprints"
+
+    id = Column(Integer, primary_key=True)
+    tag = Column(String, index=True, nullable=False)
+    score = Column(Float, nullable=False)
+    timestamp = Column(TIMESTAMP(timezone=True), server_default=func.now())

orbmem/models/memory.py

@@ -0,0 +1,15 @@
+# models/memory.py
+
+from sqlalchemy import Column, Integer, String, JSON, TIMESTAMP
+from sqlalchemy.sql import func
+from orbmem.db.postgres import Base
+
+class MemoryRecord(Base):
+    __tablename__ = "memory_records"
+
+    id = Column(Integer, primary_key=True, index=True)
+    key = Column(String, unique=True, index=True, nullable=False)
+    session_id = Column(String, index=True, nullable=True)
+    value = Column(JSON, nullable=False)
+    created_at = Column(TIMESTAMP(timezone=True), server_default=func.now())
+    expires_at = Column(TIMESTAMP(timezone=True), nullable=True)

orbmem/models/safety.py

@@ -0,0 +1,19 @@
+# models/safety.py
+
+from sqlalchemy import Column, Integer, String, Float, JSON, TIMESTAMP
+from sqlalchemy.sql import func
+from orbmem.db.postgres import Base
+
+class SafetyEvent(Base):
+    __tablename__ = "safety_events"
+
+    id = Column(Integer, primary_key=True)
+    text = Column(String, nullable=False)
+    tag = Column(String, index=True, nullable=False)
+    severity = Column(Float, nullable=False)
+    correction = Column(String, nullable=True)
+
+    # CHANGED: metadata → details
+    details = Column(JSON, nullable=True)
+
+    timestamp = Column(TIMESTAMP(timezone=True), server_default=func.now())

orbmem/utils/embeddings.py

@@ -0,0 +1,34 @@
+# utils/embeddings.py
+
+from functools import lru_cache
+from sentence_transformers import SentenceTransformer
+import numpy as np
+from orbmem.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@lru_cache(maxsize=1)
+def get_embedding_model():
+    """
+    Loads the embedding model once.
+    MiniLM-L6 model → 384-dimensional vectors.
+    """
+    model_name = "sentence-transformers/all-MiniLM-L6-v2"
+    logger.info(f"Loading embedding model: {model_name}")
+    return SentenceTransformer(model_name)
+
+
+def embed_text(text: str):
+    """
+    Convert text into a 384-d embedding vector.
+    Returns a Python list of floats (JSON serializable).
+    """
+    if not text or not isinstance(text, str):
+        return [0.0] * 384
+
+    model = get_embedding_model()
+    vector = model.encode(text)
+
+    # Convert NumPy array → list so Qdrant can store it
+    return vector.astype(float).tolist()

orbmem/utils/exceptions.py

@@ -0,0 +1,30 @@
+# utils/exceptions.py
+
+class OCDBError(Exception):
+    """Base exception for all OCDB-related errors."""
+    pass
+
+
+class ConfigError(OCDBError):
+    """Raised when configuration is missing or invalid."""
+    pass
+
+
+class DatabaseError(OCDBError):
+    """Raised for any database connection or query issues."""
+    pass
+
+
+class AuthError(OCDBError):
+    """Raised when authentication / API key validation fails."""
+    pass
+
+
+class NotFoundError(OCDBError):
+    """Raised when a requested resource is not found."""
+    pass
+
+
+class ValidationError(OCDBError):
+    """Raised when user input or payload is invalid."""
+    pass

orbmem/utils/helpers.py

@@ -0,0 +1,54 @@
+# utils/helpers.py
+
+import json
+import time
+from typing import Any, Dict
+
+
+def now_ts() -> float:
+    """
+    Returns the current time as a Unix timestamp.
+    """
+    return time.time()
+
+
+def safe_json(data: Any) -> str:
+    """
+    Convert Python dict/list/value → JSON string safely.
+    Used for logging or storing structured data.
+    """
+    try:
+        return json.dumps(data, ensure_ascii=False, default=str)
+    except Exception:
+        return "{}"
+
+
+def deep_clean_dict(data: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Remove None values from dict recursively.
+    Useful for preparing clean API responses.
+    """
+    if not isinstance(data, dict):
+        return data
+
+    cleaned = {}
+    for k, v in data.items():
+        if v is None:
+            continue
+        if isinstance(v, dict):
+            cleaned[k] = deep_clean_dict(v)
+        else:
+            cleaned[k] = v
+
+    return cleaned
+
+
+def ensure_str(value: Any) -> str:
+    """
+    Safely convert value → string.
+    Avoids crashes during logging or database operations.
+    """
+    try:
+        return str(value)
+    except Exception:
+        return "<unprintable>"

orbmem/utils/logger.py

@@ -0,0 +1,38 @@
+# utils/logger.py
+
+import logging
+import sys
+from typing import Optional
+
+
+def _create_handler() -> logging.Handler:
+    """Create a console handler with a clean, simple format."""
+    handler = logging.StreamHandler(sys.stdout)
+    formatter = logging.Formatter(
+        "[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    handler.setFormatter(formatter)
+    return handler
+
+
+def get_logger(name: Optional[str] = None) -> logging.Logger:
+    """
+    Get a configured logger instance.
+
+    Usage:
+        from utils.logger import get_logger
+        logger = get_logger(__name__)
+        logger.info("Hello from OCDB")
+    """
+    logger_name = name or "ocdb"
+    logger = logging.getLogger(logger_name)
+
+    # Avoid adding multiple handlers if called many times
+    if not logger.handlers:
+        handler = _create_handler()
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+        logger.propagate = False
+
+    return logger

orbmem/utils/validators.py

@@ -0,0 +1,53 @@
+# utils/validators.py
+
+import re
+from typing import Any, Dict
+
+
+class ValidationError(Exception):
+    """Custom validation error."""
+    pass
+
+
+def validate_non_empty(value: Any, field_name: str = "value"):
+    """Ensure a value is not empty or None."""
+    if value is None or (isinstance(value, str) and value.strip() == ""):
+        raise ValidationError(f"{field_name} cannot be empty.")
+    return value
+
+
+def validate_dict(value: Any, field_name: str = "value"):
+    """Ensure the input is a dictionary."""
+    if not isinstance(value, dict):
+        raise ValidationError(f"{field_name} must be a dictionary.")
+    return value
+
+
+def validate_key_in_dict(data: Dict, key: str):
+    """Ensure a key exists in a dictionary."""
+    if key not in data:
+        raise ValidationError(f"Missing required key: '{key}'")
+    return data[key]
+
+
+def validate_api_key(key: str):
+    """Simple API key format validator."""
+    validate_non_empty(key, "API key")
+
+    # Example: basic 32-char hex key (you can change this pattern)
+    pattern = r"^[A-Fa-f0-9]{32}$"
+
+    if not re.match(pattern, key):
+        raise ValidationError("Invalid API key format.")
+
+    return key
+
+
+def validate_memory_id(mem_id: str):
+    """Ensure memory ID follows a sane format."""
+    validate_non_empty(mem_id, "Memory ID")
+
+    if not re.match(r"^[A-Za-z0-9_\-]+$", mem_id):
+        raise ValidationError("Memory ID contains invalid characters.")
+
+    return mem_id