zerda 0.1.0__py3-none-any.whl

zerda/__init__.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+"""
+zerda — Advanced Retrieval-Augmented Generation (RAG) Toolkit for Arabic & Multilingual LLM Apps
+===================================================================================================
+
+zerda is a modular, production-grade toolkit for building Retrieval-Augmented
+Generation systems, with first-class support for Arabic text processing
+alongside general multilingual use.
+
+It bundles, as independent sub-packages that can be used together or on
+their own:
+
+    zerda.rag              High-level RAG systems (agentic, graph, hybrid,
+                            multi-hop, multi-document, conversational,
+                            federated, self-improving, streaming, domain RAG)
+    zerda.embeddings       Embedding providers (OpenAI, Gemini, Mistral,
+                            HuggingFace, Ollama, Arabic-specialized)
+    zerda.llm               LLM chat-completion clients (OpenAI, Anthropic,
+                            Groq, Mistral, Gemini, Ollama)
+    zerda.vector_database  Vector store backends (Chroma, FAISS, Pinecone)
+    zerda.document_loaders Loaders for PDF, DOCX, HTML, CSV/Excel, JSON, text
+    zerda.chunks           Chunking & text-splitting strategies
+    zerda.context          Query analysis, retrieval fusion, context building
+    zerda.cache             Multi-level semantic caching
+    zerda.memory            Conversation / long-term memory management
+    zerda.prompt             Prompt construction & templating
+    zerda.output_parser      Structured output parsing & validation
+    zerda.router             Intent routing & handler dispatch
+    zerda.observability      Tracing & metrics exporters
+    zerda.plugins            Plugin system for extending zerda
+
+Most third-party integrations (OpenAI, Anthropic, FAISS, Chroma, ...) are
+optional and imported lazily, so installing the base ``zerda`` package
+never forces heavy dependencies onto users who don't need them. Install
+the extras you need, e.g.::
+
+    pip install "zerda[openai,faiss]"
+    pip install "zerda[all]"
+
+This top-level module intentionally does **not** eagerly import every
+sub-package: submodules that depend on optional third-party libraries are
+left for the caller to import explicitly (``from zerda.llm import
+OpenAIClient``, etc.) so that a bare ``import zerda`` never fails due to a
+missing optional dependency.
+"""
+
+from __future__ import annotations
+
+__title__ = "zerda"
+__description__ = (
+    "Advanced Retrieval-Augmented Generation (RAG) toolkit with first-class "
+    "Arabic language support. For Arabic Communities, Multilingual LLM Apps, and RAG Systems."
+)
+__version__ = "0.1.0"
+__author__ = "Zerda Contributors"
+__license__ = "MIT"
+
+__all__ = [
+    "__title__",
+    "__description__",
+    "__version__",
+    "__author__",
+    "__license__",
+]

zerda/cache/__init__.py

@@ -0,0 +1,30 @@
+from .multi_level_cache import MultiLevelCache 
+from .cache_strategies import CacheStrategy
+from .config_cache import CacheConfig,SemanticConfig,SQLiteConfig,SecurityConfig,StorageBackend,RoutingDecision,CostConfig , RedisConfig , PerformanceConfig
+from .cache_entry import CacheEntry
+from .cache_metrics import CacheMetrics
+from .embedding_index import EmbeddingIndex, EmbeddingProvider,OllamaEmbeddingProvider,OpenAIEmbeddingProvider,HuggingFaceEmbeddingProvider,EmbeddingConfig
+from .metrics import CacheMetricsCollector,RollingCounter 
+from .models import IntelligentCacheEntry,TenantQuotaState
+from .normalization import QueryNormalizer,NormalizationConfig
+from .policy_learner import CachePolicyLearner,RLConfig,FeedbackSignal
+from .security import SecurityGuard,SecurityViolation
+from .tenant_manager import TenantManager,TenantConfig,TenantRegistration , QuotaExceeded
+from .cache_manager import CacheManager,CacheLookupResult,CachedEmbedder
+from .storage import RedisStorage,SQLiteStorage,MemoryStorage,build_storage
+from .cost_model import CostModel,DecisionEngine,OperationCostEstimate
+
+__all__=["CacheEntry","CacheStrategy","MultiLevelCache","CacheMetrics","CacheConfig",
+         "EmbeddingIndex","EmbeddingProvider","OllamaEmbeddingProvider","OpenAIEmbeddingProvider","HuggingFaceEmbeddingProvider","EmbeddingConfig",
+         "CostModel","CacheMetricsCollector","RollingCounter",
+         "IntelligentCacheEntry","TenantQuotaState",
+         "QueryNormalizer","NormalizationConfig",
+         "CachePolicyLearner",
+         "SecurityGuard","SecurityViolation","SecurityConfig","CostConfig",
+         "TenantManager","TenantConfig","TenantQuotaState","TenantRegistration",
+         "CacheManager","CacheLookupResult","CachedEmbedder",
+            "RedisStorage","SQLiteStorage","MemoryStorage","build_storage","RLConfig",
+            "SemanticConfig","SQLiteConfig","SecurityConfig","StorageBackend","FeedbackSignal","RoutingDecision","RedisConfig","PerformanceConfig",
+            
+            "DecisionEngine","OperationCostEstimate","QuotaExceeded"
+        ]

zerda/cache/cache_entry.py

@@ -0,0 +1,102 @@
+from dataclasses import dataclass, field
+import time
+from typing import Any, Optional
+import pickle
+from .config_cache import CacheConfig
+config=CacheConfig()
+
+
+@dataclass
+class CacheEntry:
+    """
+    Represents a cached item with metadata
+    """
+    key: str                                          
+    value: Any                                        
+    created_at: float = field(default_factory=time.time)    
+    last_access: float = field(default_factory=time.time)   
+    hits: int = 0                                      
+    ttl: Optional[float] = None                        
+    size_bytes: int = 0                                
+    
+    def __post_init__(self):
+        """
+        Calculate size after initialization
+        """
+        if self.size_bytes == 0:
+            self.size_bytes = self._calculate_size()
+    
+    def _calculate_size(self) -> int:
+        """
+        Estimate memory size of cached value
+        
+        """
+        try:
+            # Try to calculate actual size
+            return len(pickle.dumps(self.value))
+        except Exception:
+            # Default size if calculation fails
+            return config.size_bytes  # Default 1KB
+    
+    def increment_hits(self) -> None:
+        """
+        Increment hit counter and update access time
+        """
+        self.hits += 1
+        self.last_access = time.time()
+    
+    def is_expired(self) -> bool:
+        """
+        Check if entry has expired based on TTL
+        
+        Returns:
+             True if expired
+        """
+        if self.ttl is None:
+            return False
+        
+        # Calculate expiration time
+        expiration_time = self.created_at + self.ttl
+        return time.time() > expiration_time
+    
+    def age(self) -> float:
+        """
+        Get age of entry in seconds
+        Returns:
+             Age in seconds
+        """
+        return time.time() - self.created_at
+    
+    def idle_time(self) -> float:
+        """
+        Get time since last access in seconds
+        
+        Returns:
+            Idle time in seconds
+        """
+        return time.time() - self.last_access
+    
+    def get_stats(self) -> dict:
+        """
+        Get entry statistics
+        
+        Returns:
+             Statistics dictionary
+        """
+        return {
+            'key': self.key,                           
+            'hits': self.hits,                         
+            'age_seconds': self.age(),                 
+            'idle_seconds': self.idle_time(),          
+            'size_bytes': self.size_bytes,             
+            'is_expired': self.is_expired(),           
+            'ttl': self.ttl                            
+        }
+    
+    def __repr__(self) -> str:
+        """
+        Text representation of entry
+        """
+        status = "expired" if self.is_expired() else "valid"
+        return (f"CacheEntry(key='{self.key}', hits={self.hits}, "
+                f"age={self.age():.1f}s, status={status})")