ragforge-framework 0.1.0__py3-none-any.whl

ragforge_framework/__init__.py

@@ -0,0 +1,13 @@
+from .config import RAGForgeConfig
+from .core import RAGForge
+from .rag.engine import RAGEngine
+from .cache.user_manager import UserManager
+from .cache.response_cache import ResponseCache
+
+__all__ = [
+    "RAGForge",
+    "RAGForgeConfig",
+    "RAGEngine",
+    "UserManager",
+    "ResponseCache",
+]

ragforge_framework/admin/__init__.py

@@ -0,0 +1 @@
+# Admin Package Initialization

ragforge_framework/admin/routes.py

@@ -0,0 +1,224 @@
+from fastapi import APIRouter, Header, HTTPException, Request
+
+from ..models.schemas import (
+    UserResponse,
+    StatisticsResponse,
+    AllUsersResponse,
+    TopUsersResponse,
+    CacheInformationResponse
+)
+
+
+def get_admin_router(forge) -> APIRouter:
+    """
+    Admin Router Factory.
+    Builds the APIRouter instance dynamically, linking state dependencies to Request.app.state.
+    """
+    router = APIRouter(
+        prefix="/admin",
+        tags=["Admin"]
+    )
+
+    def verify_admin(request: Request, key: str):
+        config = request.app.state.config
+        if key != config.ADMIN_KEY:
+            raise HTTPException(
+                status_code=403,
+                detail="Invalid Admin Key."
+            )
+
+    # ==========================================================
+    # HOME
+    # ==========================================================
+
+    @router.get("/")
+    def admin_home(
+        request: Request,
+        x_admin_key: str = Header(...)
+    ):
+        verify_admin(request, x_admin_key)
+        return {
+            "message": "Admin API Running"
+        }
+
+    # ==========================================================
+    # ALL USERS
+    # ==========================================================
+
+    @router.get("/users", response_model=AllUsersResponse)
+    def get_all_users(
+        request: Request,
+        x_admin_key: str = Header(...)
+    ):
+        verify_admin(request, x_admin_key)
+        user_manager = request.app.state.user_manager
+        users = user_manager.get_all_users()
+
+        return {
+            "total_users": len(users),
+            "users": users
+        }
+
+    # ==========================================================
+    # SINGLE USER
+    # ==========================================================
+
+    @router.get("/user/{user_id}", response_model=UserResponse)
+    def get_user(
+        request: Request,
+        user_id: str,
+        x_admin_key: str = Header(...)
+    ):
+        verify_admin(request, x_admin_key)
+        user_manager = request.app.state.user_manager
+        user = user_manager.search_user(user_id)
+
+        if user is None:
+            raise HTTPException(
+                status_code=404,
+                detail="User not found."
+            )
+        return user
+
+    # ==========================================================
+    # RESET USER
+    # ==========================================================
+
+    @router.delete("/user/{user_id}")
+    def reset_user(
+        request: Request,
+        user_id: str,
+        x_admin_key: str = Header(...)
+    ):
+        verify_admin(request, x_admin_key)
+        user_manager = request.app.state.user_manager
+        success = user_manager.reset_user(user_id)
+
+        if not success:
+            raise HTTPException(
+                status_code=404,
+                detail="User not found."
+            )
+        return {
+            "message": "User reset successfully."
+        }
+
+    # ==========================================================
+    # RESET ALL USERS
+    # ==========================================================
+
+    @router.delete("/users")
+    def reset_all_users(
+        request: Request,
+        x_admin_key: str = Header(...)
+    ):
+        verify_admin(request, x_admin_key)
+        user_manager = request.app.state.user_manager
+        user_manager.reset_all()
+
+        return {
+            "message": "All users reset successfully."
+        }
+
+    # ==========================================================
+    # STATISTICS
+    # ==========================================================
+
+    @router.get("/stats", response_model=StatisticsResponse)
+    def statistics(
+        request: Request,
+        x_admin_key: str = Header(...)
+    ):
+        verify_admin(request, x_admin_key)
+        user_manager = request.app.state.user_manager
+
+        return user_manager.get_statistics()
+
+    # ==========================================================
+    # TOP USERS
+    # ==========================================================
+
+    @router.get("/top-users", response_model=TopUsersResponse)
+    def top_users(
+        request: Request,
+        limit: int = 10,
+        x_admin_key: str = Header(...)
+    ):
+        verify_admin(request, x_admin_key)
+        user_manager = request.app.state.user_manager
+
+        return {
+            "users": user_manager.get_top_users(limit)
+        }
+
+    # ==========================================================
+    # ACTIVE USERS
+    # ==========================================================
+
+    @router.get("/active-users", response_model=TopUsersResponse)
+    def active_users(
+        request: Request,
+        x_admin_key: str = Header(...)
+    ):
+        verify_admin(request, x_admin_key)
+        user_manager = request.app.state.user_manager
+
+        return {
+            "users": user_manager.active_users()
+        }
+
+    # ==========================================================
+    # CACHE INFO
+    # ==========================================================
+
+    @router.get("/cache", response_model=CacheInformationResponse)
+    def cache_information(
+        request: Request,
+        x_admin_key: str = Header(...)
+    ):
+        verify_admin(request, x_admin_key)
+        response_cache = request.app.state.response_cache
+
+        return {
+            "cached_responses": response_cache.total_cached_responses(),
+            "responses": response_cache.get_all()
+        }
+
+    # ==========================================================
+    # CLEAR RESPONSE CACHE
+    # ==========================================================
+
+    @router.delete("/cache")
+    def clear_cache(
+        request: Request,
+        x_admin_key: str = Header(...)
+    ):
+        verify_admin(request, x_admin_key)
+        response_cache = request.app.state.response_cache
+        response_cache.clear()
+
+        return {
+            "message": "Response cache cleared."
+        }
+
+    # ==========================================================
+    # RESET EVERYTHING
+    # ==========================================================
+
+    @router.delete("/reset")
+    def reset_everything(
+        request: Request,
+        x_admin_key: str = Header(...)
+    ):
+        verify_admin(request, x_admin_key)
+        user_manager = request.app.state.user_manager
+        response_cache = request.app.state.response_cache
+
+        user_manager.reset_all()
+        response_cache.clear()
+
+        return {
+            "message": "Users and response cache reset successfully."
+        }
+
+    return router

ragforge_framework/app.py

@@ -0,0 +1,88 @@
+from fastapi import FastAPI, Request, HTTPException
+from .models.schemas import ChatRequest, ChatResponse
+from .admin.routes import get_admin_router
+
+def create_app(forge) -> FastAPI:
+    """
+    App Factory.
+    Builds the FastAPI application at runtime and loads configuration and services
+    into app.state.
+    """
+    app = FastAPI(
+        title="RAGForge Framework Backend",
+        version="1.1.0"
+    )
+
+    # Attach orchestrator and configuration to app state
+    app.state.forge = forge
+    app.state.config = forge.config
+    app.state.user_manager = forge.user_manager
+    app.state.response_cache = forge.response_cache
+    app.state.engine = forge.engine
+
+    # Mount admin route router
+    app.include_router(get_admin_router(forge))
+
+    @app.get("/")
+    def home():
+        return {
+            "message": "🚀 RAGForge Framework Running Successfully"
+        }
+
+    @app.post("/chat", response_model=ChatResponse)
+    def chat(
+        data: ChatRequest,
+        request: Request
+    ):
+        prompt = data.prompt.strip()
+
+        # Resolve request IP (check proxy headers first)
+        ip = request.headers.get(
+            "X-Forwarded-For",
+            request.client.host
+        ).split(",")[0].strip()
+
+        # Load references from app.state
+        user_manager = request.app.state.user_manager
+        response_cache = request.app.state.response_cache
+        engine = request.app.state.engine
+        config = request.app.state.config
+
+        # 1. Register User Request
+        user_manager.register_request(ip)
+
+        # 2. Check Cache
+        cached = response_cache.get(ip, prompt)
+        if cached:
+            user = user_manager.get_user(ip)
+            return {
+                "success": True,
+                "cached": True,
+                "provider": "cache",
+                "remaining_questions": user["remaining"],
+                "answer": cached["answer"]
+            }
+
+        # 3. Check Rate Limit
+        allowed, user = user_manager.allow_request(ip)
+        if not allowed:
+            raise HTTPException(
+                status_code=429,
+                detail=f"Daily limit reached. ({user['llm_requests']}/{config.DAILY_LIMIT})"
+            )
+
+        # 4. Invoke RAG engine
+        answer = engine.chat(prompt, ip=ip)
+
+        # 5. Save response to cache
+        response_cache.save(prompt, answer)
+
+        return {
+            "success": True,
+            "cached": False,
+            "provider": "rag",
+            "remaining_questions": user["remaining"],
+            "answer": answer
+        }
+
+    return app

ragforge_framework/cache/__init__.py

@@ -0,0 +1 @@
+# Cache Package Initialization

ragforge_framework/cache/repository.py

@@ -0,0 +1,155 @@
+from typing import Any, Dict, List, Optional
+from diskcache import Cache
+
+
+class Repository:
+    """
+    DiskCache Repository layer.
+    Manages low-level cache read, write, update, delete operations.
+    """
+    def __init__(self, cache_dir: str):
+        self.cache = Cache(cache_dir)
+
+    # ==========================================================
+    # BASIC CRUD
+    # ==========================================================
+
+    def get(self, key: str) -> Optional[Dict]:
+        return self.cache.get(key)
+
+    def set(self, key: str, value: Dict):
+        self.cache[key] = value
+
+    def exists(self, key: str) -> bool:
+        return key in self.cache
+
+    def delete(self, key: str):
+        self.cache.pop(key, None)
+
+    def clear(self):
+        self.cache.clear()
+
+    # ==========================================================
+    # ITERATORS
+    # ==========================================================
+
+    def keys(self) -> List[str]:
+        return list(self.cache.iterkeys())
+
+    def values(self) -> List[Dict]:
+        return [self.cache[key] for key in self.cache.iterkeys()]
+
+    def items(self):
+        return [
+            (key, self.cache[key])
+            for key in self.cache.iterkeys()
+        ]
+
+    # ==========================================================
+    # UPDATE
+    # ==========================================================
+
+    def update(self, key: str, **kwargs):
+        data = self.get(key)
+        if data is None:
+            return None
+        data.update(kwargs)
+        self.set(key, data)
+        return data
+
+    # ==========================================================
+    # NESTED UPDATE
+    # ==========================================================
+
+    def update_nested(
+        self,
+        key: str,
+        field: str,
+        nested_key: str,
+        value: Any,
+    ):
+        data = self.get(key)
+        if data is None:
+            return None
+        if field not in data:
+            data[field] = {}
+        data[field][nested_key] = value
+        self.set(key, data)
+        return data
+
+    # ==========================================================
+    # INCREMENT
+    # ==========================================================
+
+    def increment(
+        self,
+        key: str,
+        field: str,
+        amount: int = 1,
+    ):
+        data = self.get(key)
+        if data is None:
+            return None
+        data[field] += amount
+        self.set(key, data)
+        return data
+
+    # ==========================================================
+    # INCREMENT NESTED
+    # ==========================================================
+
+    def increment_nested(
+        self,
+        key: str,
+        field: str,
+        nested_key: str,
+        amount: int = 1,
+    ):
+        data = self.get(key)
+        if data is None:
+            return None
+        if field not in data:
+            data[field] = {}
+        if nested_key not in data[field]:
+            data[field][nested_key] = 0
+        data[field][nested_key] += amount
+        self.set(key, data)
+        return data
+
+    # ==========================================================
+    # SEARCH
+    # ==========================================================
+
+    def find(
+        self,
+        field: str,
+        value: Any,
+    ) -> Optional[Dict]:
+        for _, data in self.items():
+            if data.get(field) == value:
+                return data
+        return None
+
+    def find_key(
+        self,
+        field: str,
+        value: Any,
+    ) -> Optional[str]:
+        for key, data in self.items():
+            if data.get(field) == value:
+                return key
+        return None
+
+    # ==========================================================
+    # COUNT
+    # ==========================================================
+
+    def count(self):
+        return len(self.cache)
+
+    # ==========================================================
+    # EXPORT
+    # ==========================================================
+
+    def export(self):
+        return self.values()

ragforge_framework/cache/response_cache.py

@@ -0,0 +1,105 @@
+from hashlib import sha256
+
+from .repository import Repository
+from .user_manager import UserManager
+
+
+class ResponseCache:
+    """
+    Cache layer for persisting generated responses.
+    """
+    def __init__(self, config):
+        self.repository = Repository(config.RESPONSE_CACHE_DIR)
+        self.user_manager = UserManager(config)
+
+    # =====================================================
+    # PRIVATE
+    # =====================================================
+
+    def _key(self, prompt: str):
+        return sha256(
+            prompt.strip().lower().encode()
+        ).hexdigest()
+
+    # =====================================================
+    # GET
+    # =====================================================
+
+    def get(self, ip: str, prompt: str):
+        key = self._key(prompt)
+        response = self.repository.get(key)
+        if response:
+            self.user_manager.cache_hit(ip)
+        else:
+            self.user_manager.cache_miss(ip)
+        return response
+
+    # =====================================================
+    # SAVE
+    # =====================================================
+
+    def save(
+        self,
+        prompt: str,
+        answer: str
+    ):
+        key = self._key(prompt)
+        self.repository.set(
+            key,
+            {
+                "answer": answer
+            }
+        )
+
+    # =====================================================
+    # DELETE
+    # =====================================================
+
+    def delete(
+        self,
+        prompt: str
+    ):
+        key = self._key(prompt)
+        self.repository.delete(key)
+
+    # =====================================================
+    # CLEAR
+    # =====================================================
+
+    def clear(self):
+        self.repository.clear()
+
+    # =====================================================
+    # EXISTS
+    # =====================================================
+
+    def exists(
+        self,
+        prompt: str
+    ):
+        key = self._key(prompt)
+        return self.repository.exists(key)
+
+    # =====================================================
+    # TOTAL CACHE
+    # =====================================================
+
+    def total_cached_responses(self):
+        return self.repository.count()
+
+    # =====================================================
+    # ALL CACHE
+    # =====================================================
+
+    def get_all(self):
+        return self.repository.values()
+
+    # =====================================================
+    # DEBUG
+    # =====================================================
+
+    def __len__(self):
+        return self.repository.count()
+
+    def __repr__(self):
+        return f"<ResponseCache size={len(self)}>"