fennec-rag 0.1.1__tar.gz

fennec_rag-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fennec-rag contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fennec_rag-0.1.1/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include fennec *.py
+recursive-include fennec *.typed
+exclude fennec/test.ipynb
+global-exclude __pycache__
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude .DS_Store

fennec_rag-0.1.1/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: fennec-rag
+Version: 0.1.1
+Summary: A comprehensive RAG framework with Arabic language support, multi-provider embeddings, and advanced RAG strategies
+Home-page: https://fennec-community.vercel.app/#overview
+Author: Yousef Khalil
+Author-email: yousefkhalil435@gmail.com
+License: MIT
+Project-URL: Documentation, https://github.com/YousefKhalil10/fennec-rag-projects
+Keywords: rag,retrieval-augmented-generation,arabic,nlp,llm,embeddings,vector-database,ai,machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Natural Language :: Arabic
+Classifier: Natural Language :: English
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: tiktoken>=0.5.0
+Requires-Dist: tqdm>=4.65.0
+Provides-Extra: faiss
+Requires-Dist: faiss-cpu>=1.7.4; extra == "faiss"
+Provides-Extra: faiss-gpu
+Requires-Dist: faiss-gpu>=1.7.4; extra == "faiss-gpu"
+Provides-Extra: chroma
+Requires-Dist: chromadb>=0.4.0; extra == "chroma"
+Provides-Extra: pinecone
+Requires-Dist: pinecone-client>=3.0.0; extra == "pinecone"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0.0; extra == "gemini"
+Provides-Extra: mistral
+Requires-Dist: mistralai>=1.0.0; extra == "mistral"
+Provides-Extra: huggingface
+Requires-Dist: transformers>=4.30.0; extra == "huggingface"
+Requires-Dist: torch>=2.0.0; extra == "huggingface"
+Provides-Extra: ollama
+Requires-Dist: aiohttp>=3.9.0; extra == "ollama"
+Provides-Extra: sentence-transformers
+Requires-Dist: sentence-transformers>=2.2.0; extra == "sentence-transformers"
+Provides-Extra: pdf
+Requires-Dist: pypdf>=3.0.0; extra == "pdf"
+Requires-Dist: PyPDF2>=3.0.0; extra == "pdf"
+Provides-Extra: docx
+Requires-Dist: python-docx>=1.0.0; extra == "docx"
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1.0; extra == "excel"
+Provides-Extra: html
+Requires-Dist: beautifulsoup4>=4.12.0; extra == "html"
+Requires-Dist: lxml>=4.9.0; extra == "html"
+Provides-Extra: web
+Requires-Dist: aiohttp>=3.9.0; extra == "web"
+Requires-Dist: beautifulsoup4>=4.12.0; extra == "web"
+Provides-Extra: chardet
+Requires-Dist: chardet>=5.0.0; extra == "chardet"
+Provides-Extra: jq
+Requires-Dist: jq>=1.6.0; extra == "jq"
+Provides-Extra: arabic
+Requires-Dist: stanza>=1.5.0; extra == "arabic"
+Requires-Dist: camel-tools>=1.5.0; extra == "arabic"
+Provides-Extra: jinja2
+Requires-Dist: jinja2>=3.1.0; extra == "jinja2"
+Provides-Extra: observability
+Requires-Dist: fastapi>=0.100.0; extra == "observability"
+Requires-Dist: uvicorn>=0.23.0; extra == "observability"
+Provides-Extra: eval
+Requires-Dist: scikit-learn>=1.3.0; extra == "eval"
+Provides-Extra: crypto
+Requires-Dist: cryptography>=41.0.0; extra == "crypto"
+Provides-Extra: all
+Requires-Dist: faiss-cpu>=1.7.4; extra == "all"
+Requires-Dist: chromadb>=0.4.0; extra == "all"
+Requires-Dist: pinecone-client>=3.0.0; extra == "all"
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: anthropic>=0.20.0; extra == "all"
+Requires-Dist: google-genai>=1.0.0; extra == "all"
+Requires-Dist: mistralai>=1.0.0; extra == "all"
+Requires-Dist: transformers>=4.30.0; extra == "all"
+Requires-Dist: torch>=2.0.0; extra == "all"
+Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
+Requires-Dist: aiohttp>=3.9.0; extra == "all"
+Requires-Dist: pypdf>=3.0.0; extra == "all"
+Requires-Dist: python-docx>=1.0.0; extra == "all"
+Requires-Dist: openpyxl>=3.1.0; extra == "all"
+Requires-Dist: beautifulsoup4>=4.12.0; extra == "all"
+Requires-Dist: lxml>=4.9.0; extra == "all"
+Requires-Dist: chardet>=5.0.0; extra == "all"
+Requires-Dist: jq>=1.6.0; extra == "all"
+Requires-Dist: stanza>=1.5.0; extra == "all"
+Requires-Dist: jinja2>=3.1.0; extra == "all"
+Requires-Dist: fastapi>=0.100.0; extra == "all"
+Requires-Dist: uvicorn>=0.23.0; extra == "all"
+Requires-Dist: scikit-learn>=1.3.0; extra == "all"
+Requires-Dist: cryptography>=41.0.0; extra == "all"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+
+<p align="center">
+  <img src="logo.png" alt="Fennec-RAG " width="300"/>
+</p>
+<div align="center">
+
+<br/>
+
+# 🦊 fennec-rag
+
+A comprehensive, production-ready **Retrieval-Augmented Generation (RAG)** framework with first-class **Arabic language support**, multi-provider embeddings, and a rich set of advanced RAG strategies.
+
+[![PyPI version](https://badge.fury.io/py/fennec-rag.svg)](https://badge.fury.io/py/fennec-rag)
+[![Python](https://img.shields.io/pypi/pyversions/fennec-rag)](https://pypi.org/project/fennec-rag/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## ✨ Features
+
+- 🌍 **Arabic-first NLP** — dedicated Arabic chunker, embedder, and prompt templates
+- 🔌 **Multi-provider LLMs** — OpenAI, Anthropic, Gemini, Mistral, HuggingFace, Ollama
+- 🗄️ **Multiple vector databases** — FAISS, ChromaDB, Pinecone
+- 🧩 **Advanced RAG strategies** — Conversational, Agentic, Graph, Multi-hop, Federated, Self-improving, Streaming, Domain-specific
+- 🛡️ **Hallucination Guard** — built-in hallucination detection and grounding
+- 📊 **Observability & Evaluation** — tracing, metrics, dashboards, RAG evaluation suite
+- 📄 **Rich document loaders** — PDF, DOCX, HTML, CSV, JSON, Excel, Web, Directory
+- 💾 **Caching & Persistence** — multi-level cache, backup, encryption support
+- 🔍 **Hybrid Search** — BM25 + semantic search with TF-IDF and Stanza
+- 🧠 **Memory systems** — Buffer, Window, Summary, and Entity memory
+- 🔌 **Plugin system** — extensible architecture for custom components
+- 🖥️ **Chat UI** — built-in RAG chat interface
+
+---
+
+## 📦 Installation
+
+### Basic install (core only)
+```bash
+pip install fennec-rag
+```
+
+### With specific providers
+```bash
+# OpenAI + FAISS
+pip install "fennec-rag[openai,faiss]"
+
+# Anthropic + ChromaDB
+pip install "fennec-rag[anthropic,chroma]"
+
+# Google Gemini + Pinecone
+pip install "fennec-rag[gemini,pinecone]"
+
+# Arabic NLP support
+pip install "fennec-rag[arabic]"
+
+# Document loaders
+pip install "fennec-rag[pdf,docx,html,excel]"
+
+# Full install (all optional dependencies)
+pip install "fennec-rag[all]"
+```
+
+
+
+
+---
+
+## 🔧 Optional Dependencies
+
+| Extra | Packages | Use case |
+|-------|----------|----------|
+| `faiss` | faiss-cpu | FAISS vector database |
+| `chroma` | chromadb | ChromaDB vector database |
+| `pinecone` | pinecone-client | Pinecone vector database |
+| `openai` | openai | OpenAI LLM & embeddings |
+| `anthropic` | anthropic | Claude LLM |
+| `gemini` | google-genai | Google Gemini LLM & embeddings |
+| `mistral` | mistralai | Mistral LLM & embeddings |
+| `huggingface` | transformers, torch | Local HuggingFace models |
+| `sentence-transformers` | sentence-transformers | Sentence embeddings |
+| `ollama` | aiohttp | Ollama local LLM |
+| `pdf` | pypdf, PyPDF2 | PDF loading |
+| `docx` | python-docx | Word document loading |
+| `excel` | openpyxl | Excel file loading |
+| `html` | beautifulsoup4, lxml | HTML loading |
+| `web` | aiohttp, beautifulsoup4 | Web page loading |
+| `arabic` | stanza, camel-tools | Advanced Arabic NLP |
+| `jinja2` | jinja2 | Jinja2 prompt templates |
+| `observability` | fastapi, uvicorn | Observability API server |
+| `eval` | scikit-learn | RAG evaluation metrics |
+| `crypto` | cryptography | Encrypted persistence |
+| `all` | everything above | Full installation |
+
+---
+
+## 📝 License
+
+MIT License — see [LICENSE](LICENSE) for details.

fennec_rag-0.1.1/README.md

@@ -0,0 +1,99 @@
+
+<p align="center">
+  <img src="logo.png" alt="Fennec-RAG " width="300"/>
+</p>
+<div align="center">
+
+<br/>
+
+# 🦊 fennec-rag
+
+A comprehensive, production-ready **Retrieval-Augmented Generation (RAG)** framework with first-class **Arabic language support**, multi-provider embeddings, and a rich set of advanced RAG strategies.
+
+[![PyPI version](https://badge.fury.io/py/fennec-rag.svg)](https://badge.fury.io/py/fennec-rag)
+[![Python](https://img.shields.io/pypi/pyversions/fennec-rag)](https://pypi.org/project/fennec-rag/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## ✨ Features
+
+- 🌍 **Arabic-first NLP** — dedicated Arabic chunker, embedder, and prompt templates
+- 🔌 **Multi-provider LLMs** — OpenAI, Anthropic, Gemini, Mistral, HuggingFace, Ollama
+- 🗄️ **Multiple vector databases** — FAISS, ChromaDB, Pinecone
+- 🧩 **Advanced RAG strategies** — Conversational, Agentic, Graph, Multi-hop, Federated, Self-improving, Streaming, Domain-specific
+- 🛡️ **Hallucination Guard** — built-in hallucination detection and grounding
+- 📊 **Observability & Evaluation** — tracing, metrics, dashboards, RAG evaluation suite
+- 📄 **Rich document loaders** — PDF, DOCX, HTML, CSV, JSON, Excel, Web, Directory
+- 💾 **Caching & Persistence** — multi-level cache, backup, encryption support
+- 🔍 **Hybrid Search** — BM25 + semantic search with TF-IDF and Stanza
+- 🧠 **Memory systems** — Buffer, Window, Summary, and Entity memory
+- 🔌 **Plugin system** — extensible architecture for custom components
+- 🖥️ **Chat UI** — built-in RAG chat interface
+
+---
+
+## 📦 Installation
+
+### Basic install (core only)
+```bash
+pip install fennec-rag
+```
+
+### With specific providers
+```bash
+# OpenAI + FAISS
+pip install "fennec-rag[openai,faiss]"
+
+# Anthropic + ChromaDB
+pip install "fennec-rag[anthropic,chroma]"
+
+# Google Gemini + Pinecone
+pip install "fennec-rag[gemini,pinecone]"
+
+# Arabic NLP support
+pip install "fennec-rag[arabic]"
+
+# Document loaders
+pip install "fennec-rag[pdf,docx,html,excel]"
+
+# Full install (all optional dependencies)
+pip install "fennec-rag[all]"
+```
+
+
+
+
+---
+
+## 🔧 Optional Dependencies
+
+| Extra | Packages | Use case |
+|-------|----------|----------|
+| `faiss` | faiss-cpu | FAISS vector database |
+| `chroma` | chromadb | ChromaDB vector database |
+| `pinecone` | pinecone-client | Pinecone vector database |
+| `openai` | openai | OpenAI LLM & embeddings |
+| `anthropic` | anthropic | Claude LLM |
+| `gemini` | google-genai | Google Gemini LLM & embeddings |
+| `mistral` | mistralai | Mistral LLM & embeddings |
+| `huggingface` | transformers, torch | Local HuggingFace models |
+| `sentence-transformers` | sentence-transformers | Sentence embeddings |
+| `ollama` | aiohttp | Ollama local LLM |
+| `pdf` | pypdf, PyPDF2 | PDF loading |
+| `docx` | python-docx | Word document loading |
+| `excel` | openpyxl | Excel file loading |
+| `html` | beautifulsoup4, lxml | HTML loading |
+| `web` | aiohttp, beautifulsoup4 | Web page loading |
+| `arabic` | stanza, camel-tools | Advanced Arabic NLP |
+| `jinja2` | jinja2 | Jinja2 prompt templates |
+| `observability` | fastapi, uvicorn | Observability API server |
+| `eval` | scikit-learn | RAG evaluation metrics |
+| `crypto` | cryptography | Encrypted persistence |
+| `all` | everything above | Full installation |
+
+---
+
+## 📝 License
+
+MIT License — see [LICENSE](LICENSE) for details.

fennec_rag-0.1.1/fennec/cache/__init__.py

@@ -0,0 +1,6 @@
+from .multi_level_cache import MultiLevelCache
+from .cache_strategies import CacheStrategy
+from .config_cache import CacheConfig
+from .cache_entry import CacheEntry
+from .cache_metrics import CacheMetrics
+__all__=["CacheEntry","CacheStrategy","MultiLevelCache","CacheMetrics","CacheConfig"]

fennec_rag-0.1.1/fennec/cache/cache_entry.py

@@ -0,0 +1,117 @@
+from dataclasses import dataclass, field
+import time
+from typing import Any, Optional
+import pickle
+from .config_cache import CacheConfig
+config=CacheConfig()
+
+
+@dataclass
+class CacheEntry:
+    """
+    يمثل عنصر مخزن مؤقتاً مع بيانات وصفية\n
+    Represents a cached item with metadata
+    """
+    key: str                                           # المفتاح | Key
+    value: Any                                         # القيمة المخزنة | Cached value
+    created_at: float = field(default_factory=time.time)    # وقت الإنشاء | Creation time
+    last_access: float = field(default_factory=time.time)   # آخر وصول | Last access time
+    hits: int = 0                                      # عدد مرات الوصول | Access count
+    ttl: Optional[float] = None                        # مدة الصلاحية بالثواني | Time to live in seconds
+    size_bytes: int = 0                                # الحجم بالبايتات | Size in bytes
+    
+    def __post_init__(self):
+        """
+        حساب الحجم بعد التهيئة\n
+        Calculate size after initialization
+        """
+        if self.size_bytes == 0:
+            self.size_bytes = self._calculate_size()
+    
+    def _calculate_size(self) -> int:
+        """
+        تقدير حجم الذاكرة للقيمة المخزنة\n
+        Estimate memory size of cached value
+        
+        Returns:
+            الحجم بالبايتات | Size in bytes
+        """
+        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:
+        """
+        زيادة عداد الوصول وتحديث وقت الوصول\n
+        Increment hit counter and update access time
+        """
+        self.hits += 1
+        self.last_access = time.time()
+    
+    def is_expired(self) -> bool:
+        """
+        التحقق من انتهاء صلاحية العنصر بناءً على TTL\n
+        Check if entry has expired based on TTL
+        
+        Returns:
+            True إذا انتهت الصلاحية | 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:
+        """
+        الحصول على عمر العنصر بالثواني\n
+        Get age of entry in seconds
+        
+        Returns:
+            العمر بالثواني | Age in seconds
+        """
+        return time.time() - self.created_at
+    
+    def idle_time(self) -> float:
+        """
+        الحصول على الوقت منذ آخر وصول بالثواني\n
+        Get time since last access in seconds
+        
+        Returns:
+            الوقت الخامل بالثواني | Idle time in seconds
+        """
+        return time.time() - self.last_access
+    
+    def get_stats(self) -> dict:
+        """
+        الحصول على إحصائيات العنصر\n
+        Get entry statistics
+        
+        Returns:
+            قاموس الإحصائيات | Statistics dictionary
+        """
+        return {
+            'key': self.key,                           # المفتاح | Key
+            'hits': self.hits,                         # عدد الوصولات | Hit count
+            'age_seconds': self.age(),                 # العمر | Age
+            'idle_seconds': self.idle_time(),          # الوقت الخامل | Idle time
+            'size_bytes': self.size_bytes,             # الحجم | Size
+            'is_expired': self.is_expired(),           # منتهي الصلاحية؟ | Is expired?
+            'ttl': self.ttl                            # مدة الصلاحية | TTL
+        }
+    
+    def __repr__(self) -> str:
+        """
+        تمثيل نصي للعنصر\n
+        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})")

fennec_rag-0.1.1/fennec/cache/cache_metrics.py

@@ -0,0 +1,146 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class CacheMetrics:
+    """
+    Track cache performance metrics\n
+    تتبع مقاييس أداء ذاكرة التخزين المؤقت
+    """
+    # L1 cache hits | إصابات المستوى الأول
+    l1_hits: int = 0
+    # L2 cache hits | إصابات المستوى الثاني
+    l2_hits: int = 0
+    # L3 cache hits | إصابات المستوى الثالث
+    l3_hits: int = 0
+    # L1 cache misses | إخفاقات المستوى الأول
+    l1_misses: int = 0
+    # L2 cache misses | إخفاقات المستوى الثاني
+    l2_misses: int = 0
+    # L3 cache misses | إخفاقات المستوى الثالث
+    l3_misses: int = 0
+    # Total set operations | إجمالي عمليات التعيين
+    sets: int = 0
+    # Total evictions | إجمالي عمليات الإخلاء
+    evictions: int = 0
+    # Total promotions | إجمالي عمليات الترقية
+    promotions: int = 0
+    # Total expirations | إجمالي عمليات انتهاء الصلاحية
+    expirations: int = 0
+    
+    def record_get(self, level: int, hit: bool) -> None:
+        """
+        Record a get operation\n
+        تسجيل عملية قراءة
+        
+        Args:
+            level: Cache level (1, 2, or 3) | مستوى التخزين المؤقت (1 أو 2 أو 3)
+            hit: Whether the get was a hit or miss | ما إذا كانت العملية إصابة أم إخفاق
+        """
+        if level == 1:
+            if hit:
+                self.l1_hits += 1
+            else:
+                self.l1_misses += 1
+        elif level == 2:
+            if hit:
+                self.l2_hits += 1
+            else:
+                self.l2_misses += 1
+        elif level == 3:
+            if hit:
+                self.l3_hits += 1
+            else:
+                self.l3_misses += 1
+    
+    def record_set(self) -> None:
+        """
+        Record a set operation\n
+        تسجيل عملية تعيين
+        """
+        self.sets += 1
+    
+    def record_eviction(self) -> None:
+        """
+        Record a cache eviction\n
+        تسجيل عملية إخلاء من ذاكرة التخزين عندما تمتلئ الذاكره
+        """
+        self.evictions += 1
+    
+    def record_promotion(self) -> None:
+        """
+        Record a promotion between cache levels\n
+        تسجيل عملية ترقية بين مستويات التخزين المؤقت
+        """
+        self.promotions += 1
+    
+    def record_expiration(self) -> None:
+        """
+        Record a cache entry expiration\n
+        تسجيل عملية انتهاء صلاحية عنصر في ذاكرة التخزين المؤقت
+        """
+        self.expirations += 1
+    
+    def get_hit_rate(self, level: Optional[int] = None) -> float:
+        """
+        Calculate hit rate for specified level or overall\n
+        حساب معدل الإصابة للمستوى المحدد أو الإجمالي
+        
+        Args:
+            level: Cache level (1, 2, 3) or None for overall | مستوى التخزين (1، 2، 3) أو None للإجمالي
+            
+        Returns:
+            Hit rate as a float between 0 and 1 | معدل الإصابة كرقم عشري بين 0 و 1
+        """
+        if level == 1:
+            total = self.l1_hits + self.l1_misses
+            return self.l1_hits / total if total > 0 else 0.0
+        elif level == 2:
+            total = self.l2_hits + self.l2_misses
+            return self.l2_hits / total if total > 0 else 0.0
+        elif level == 3:
+            total = self.l3_hits + self.l3_misses
+            return self.l3_hits / total if total > 0 else 0.0
+        else:
+            # Overall hit rate | معدل الإصابة الإجمالي
+            total_hits = self.l1_hits + self.l2_hits + self.l3_hits
+            total_gets = total_hits + self.l1_misses + self.l2_misses + self.l3_misses
+            return total_hits / total_gets if total_gets > 0 else 0.0
+    
+    def get_stats(self) -> dict:
+        """
+        Get all statistics as dictionary\n
+        الحصول على جميع الإحصائيات كقاموس
+        
+        Returns:
+            Dictionary containing all cache metrics | قاموس يحتوي على جميع مقاييس التخزين المؤقت
+        """
+        return {
+            'l1_hits': self.l1_hits,
+            'l2_hits': self.l2_hits,
+            'l3_hits': self.l3_hits,
+            'total_hits': self.l1_hits + self.l2_hits + self.l3_hits,
+            'l1_misses': self.l1_misses,
+            'l2_misses': self.l2_misses,
+            'l3_misses': self.l3_misses,
+            'total_misses': self.l1_misses + self.l2_misses + self.l3_misses,
+            'l1_hit_rate': self.get_hit_rate(1),
+            'l2_hit_rate': self.get_hit_rate(2),
+            'l3_hit_rate': self.get_hit_rate(3),
+            'overall_hit_rate': self.get_hit_rate(),
+            'sets': self.sets,
+            'evictions': self.evictions,
+            'promotions': self.promotions,
+            'expirations': self.expirations,
+         
+        }
+    
+    def reset(self) -> None:
+        """
+        Reset all metrics to zero\n
+        إعادة تعيين جميع المقاييس إلى الصفر
+        """
+        self.l1_hits = self.l2_hits = self.l3_hits = 0
+        self.l1_misses = self.l2_misses = self.l3_misses = 0
+        self.sets = self.evictions = self.promotions = self.expirations = 0

fennec_rag-0.1.1/fennec/cache/cache_strategies.py

@@ -0,0 +1,10 @@
+
+from enum import Enum
+
+class CacheStrategy(Enum):
+    """Cache eviction strategies"""
+    LRU = "lru"      # Least Recently Used
+    LFU = "lfu"      # Least Frequently Used
+    FIFO = "fifo"    # First In First Out
+    TTL = "ttl"      # Time To Live based
+    ADAPTIVE = "adaptive"  # Adaptive strategy