ragforge-framework 0.1.0__tar.gz

ragforge_framework-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env
+
+response_cache/
+user_cache/
+

ragforge_framework-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

ragforge_framework-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: ragforge-framework
+Version: 0.1.0
+Summary: Modular AI Backend Framework built with FastAPI, LiteLLM and LangChain
+Requires-Python: >=3.12
+Requires-Dist: diskcache>=5.6.3
+Requires-Dist: faiss-cpu>=1.14.3
+Requires-Dist: fastapi>=0.139.0
+Requires-Dist: langchain-community>=0.4.2
+Requires-Dist: langchain-google-genai>=4.2.7
+Requires-Dist: langchain-groq>=1.1.3
+Requires-Dist: langchain-huggingface>=1.2.2
+Requires-Dist: langchain-litellm>=0.7.0
+Requires-Dist: langchain-mistralai>=1.1.6
+Requires-Dist: langchain-ollama>=1.1.0
+Requires-Dist: langchain-openai>=1.3.5
+Requires-Dist: langchain-redis>=0.2.5
+Requires-Dist: langchain-text-splitters>=1.1.2
+Requires-Dist: langchain>=1.3.12
+Requires-Dist: langgraph>=1.2.9
+Requires-Dist: litellm>=1.91.1
+Requires-Dist: pandas>=3.0.3
+Requires-Dist: pypdf>=6.14.2
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: sentence-transformers>=5.6.0
+Requires-Dist: uvicorn>=0.51.0
+Description-Content-Type: text/markdown
+
+# 🚀 RAGForge Framework
+
+### Production-Ready AI Backend Framework built with FastAPI, LiteLLM and LangChain
+
+RAGForge is a modular Python RAG (Retrieval-Augmented Generation) framework that helps developers build and deploy production-ready AI backends with built-in semantic caching, IP-based rate limiting, automatic LLM fallbacks, and comprehensive administrative APIs.
+
+---
+
+## 📖 Features
+
+- **Retrieval-Augmented Generation (RAG):** Powered by LangChain, FAISS Vector Store, and HuggingFace Embeddings.
+- **LiteLLM Gateway:** Connect to Ollama, Groq, Mistral, OpenAI, Gemini, etc. with automatic LLM fallback switching.
+- **Semantic caching:** Persistent cache layers using `diskcache` to reduce latency and API costs.
+- **IP-Based Rate Limiting:** Daily limit controls to prevent abuse.
+- **Admin APIs:** Built-in endpoints for viewing user statistics, resetting cache, tracking LLM provider metrics, and clearing cache.
+- **Unified CLI:** Simple CLI tool to initialize, build, and run applications.
+
+---
+
+## ⚙️ Installation
+
+To install RAGForge locally from source:
+
+```bash
+git clone https://github.com/yourusername/RAGForge.git
+cd RAGForge
+pip install -e .
+```
+
+---
+
+## 🚀 Quick Start (CLI Mode)
+
+RAGForge includes a CLI executable to quickly manage projects.
+
+### 1. Initialize a new project
+
+```bash
+ragforge init
+```
+
+This generates a starter project structure:
+
+- `data/data.txt`: Your source document repository.
+- `app.py`: The entry point script configuring your framework.
+
+### 2. Ingest documents
+
+Add your knowledge text database to `data/data.txt` and generate the vector index:
+
+```bash
+ragforge ingest
+```
+
+### 3. Start the API server
+
+```bash
+ragforge run --port 8000
+```
+
+This launches a FastAPI server. Open [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) in your browser to inspect the interactive Swagger API documentation.
+
+---
+
+## 🐍 Programmatic Usage
+
+You can import and configure `RAGForge` inside any Python application:
+
+```python
+from ragforge_framework import RAGForge
+
+# 1. Initialize with custom configurations
+forge = RAGForge(
+    data_path="data/data.txt",
+    faiss_path="faiss_index",
+    primary_model="ollama/llama3.2:latest",
+    fallback_models=["groq/llama-3.1-8b-instant"],
+    daily_limit=15,
+    admin_key="mysecretkey"
+)
+
+# Expose FastAPI application instance for uvicorn/gunicorn
+app = forge.app
+
+if __name__ == "__main__":
+    # 2. Run the application
+    forge.run(host="127.0.0.1", port=8000)
+```
+
+---
+
+## 🔧 Configuration Options
+
+The `RAGForge` orchestrator accepts the following keyword arguments during instantiation:
+
+| Parameter            | Type   | Default                              | Description                                    |
+| :------------------- | :----- | :----------------------------------- | :--------------------------------------------- |
+| `primary_model`      | `str`  | `"ollama/llama3.2:latest"`           | The primary LLM to query.                      |
+| `fallback_models`    | `list` | `["groq/llama-3.1-8b-instant", ...]` | Backup LLMs to trigger if primary fails.       |
+| `daily_limit`        | `int`  | `10`                                 | Daily LLM request quota per IP.                |
+| `admin_key`          | `str`  | `"yashodeep"`                        | The secret key to secure `/admin` endpoints.   |
+| `data_path`          | `str`  | `"data/data.txt"`                    | Path to the source text file to index.         |
+| `faiss_path`         | `str`  | `"faiss_index"`                      | Path to save the FAISS vector database.        |
+| `embedding_model`    | `str`  | `"sentence-transformers/..."`        | HuggingFace embedding model name.              |
+| `response_cache_dir` | `str`  | `"./response_cache"`                 | Directory to store query cache.                |
+| `user_cache_dir`     | `str`  | `"./user_cache"`                     | Directory to store user rate limit statistics. |
+| `chunk_size`         | `int`  | `800`                                | Size of split text chunks.                     |
+| `chunk_overlap`      | `int`  | `100`                                | Text chunk overlap tokens.                     |
+
+---
+
+## 📊 Administration Endpoints
+
+Secure administrative APIs are exposed under `/admin/` (requires `x-admin-key` header matching your `admin_key`):
+
+- `GET /admin/users`: Lists stats for all registered users.
+- `GET /admin/stats`: Exposes global metrics (total queries, cache hits, provider splits).
+- `GET /admin/cache`: Inspects all currently cached queries and responses.
+- `DELETE /admin/cache`: Clears the response cache.
+- `DELETE /admin/reset`: Clears all caches and user request quotas.

ragforge_framework-0.1.0/README.md

@@ -0,0 +1,120 @@
+# 🚀 RAGForge Framework
+
+### Production-Ready AI Backend Framework built with FastAPI, LiteLLM and LangChain
+
+RAGForge is a modular Python RAG (Retrieval-Augmented Generation) framework that helps developers build and deploy production-ready AI backends with built-in semantic caching, IP-based rate limiting, automatic LLM fallbacks, and comprehensive administrative APIs.
+
+---
+
+## 📖 Features
+
+- **Retrieval-Augmented Generation (RAG):** Powered by LangChain, FAISS Vector Store, and HuggingFace Embeddings.
+- **LiteLLM Gateway:** Connect to Ollama, Groq, Mistral, OpenAI, Gemini, etc. with automatic LLM fallback switching.
+- **Semantic caching:** Persistent cache layers using `diskcache` to reduce latency and API costs.
+- **IP-Based Rate Limiting:** Daily limit controls to prevent abuse.
+- **Admin APIs:** Built-in endpoints for viewing user statistics, resetting cache, tracking LLM provider metrics, and clearing cache.
+- **Unified CLI:** Simple CLI tool to initialize, build, and run applications.
+
+---
+
+## ⚙️ Installation
+
+To install RAGForge locally from source:
+
+```bash
+git clone https://github.com/yourusername/RAGForge.git
+cd RAGForge
+pip install -e .
+```
+
+---
+
+## 🚀 Quick Start (CLI Mode)
+
+RAGForge includes a CLI executable to quickly manage projects.
+
+### 1. Initialize a new project
+
+```bash
+ragforge init
+```
+
+This generates a starter project structure:
+
+- `data/data.txt`: Your source document repository.
+- `app.py`: The entry point script configuring your framework.
+
+### 2. Ingest documents
+
+Add your knowledge text database to `data/data.txt` and generate the vector index:
+
+```bash
+ragforge ingest
+```
+
+### 3. Start the API server
+
+```bash
+ragforge run --port 8000
+```
+
+This launches a FastAPI server. Open [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) in your browser to inspect the interactive Swagger API documentation.
+
+---
+
+## 🐍 Programmatic Usage
+
+You can import and configure `RAGForge` inside any Python application:
+
+```python
+from ragforge_framework import RAGForge
+
+# 1. Initialize with custom configurations
+forge = RAGForge(
+    data_path="data/data.txt",
+    faiss_path="faiss_index",
+    primary_model="ollama/llama3.2:latest",
+    fallback_models=["groq/llama-3.1-8b-instant"],
+    daily_limit=15,
+    admin_key="mysecretkey"
+)
+
+# Expose FastAPI application instance for uvicorn/gunicorn
+app = forge.app
+
+if __name__ == "__main__":
+    # 2. Run the application
+    forge.run(host="127.0.0.1", port=8000)
+```
+
+---
+
+## 🔧 Configuration Options
+
+The `RAGForge` orchestrator accepts the following keyword arguments during instantiation:
+
+| Parameter            | Type   | Default                              | Description                                    |
+| :------------------- | :----- | :----------------------------------- | :--------------------------------------------- |
+| `primary_model`      | `str`  | `"ollama/llama3.2:latest"`           | The primary LLM to query.                      |
+| `fallback_models`    | `list` | `["groq/llama-3.1-8b-instant", ...]` | Backup LLMs to trigger if primary fails.       |
+| `daily_limit`        | `int`  | `10`                                 | Daily LLM request quota per IP.                |
+| `admin_key`          | `str`  | `"yashodeep"`                        | The secret key to secure `/admin` endpoints.   |
+| `data_path`          | `str`  | `"data/data.txt"`                    | Path to the source text file to index.         |
+| `faiss_path`         | `str`  | `"faiss_index"`                      | Path to save the FAISS vector database.        |
+| `embedding_model`    | `str`  | `"sentence-transformers/..."`        | HuggingFace embedding model name.              |
+| `response_cache_dir` | `str`  | `"./response_cache"`                 | Directory to store query cache.                |
+| `user_cache_dir`     | `str`  | `"./user_cache"`                     | Directory to store user rate limit statistics. |
+| `chunk_size`         | `int`  | `800`                                | Size of split text chunks.                     |
+| `chunk_overlap`      | `int`  | `100`                                | Text chunk overlap tokens.                     |
+
+---
+
+## 📊 Administration Endpoints
+
+Secure administrative APIs are exposed under `/admin/` (requires `x-admin-key` header matching your `admin_key`):
+
+- `GET /admin/users`: Lists stats for all registered users.
+- `GET /admin/stats`: Exposes global metrics (total queries, cache hits, provider splits).
+- `GET /admin/cache`: Inspects all currently cached queries and responses.
+- `DELETE /admin/cache`: Clears the response cache.
+- `DELETE /admin/reset`: Clears all caches and user request quotas.

ragforge_framework-0.1.0/app.py

@@ -0,0 +1,15 @@
+from ragforge_framework import RAGForge
+
+# Instantiate the RAGForge framework config and services
+forge = RAGForge(
+    data_path="data/data.txt",
+    faiss_path="faiss_index",
+    primary_model="ollama/llama3.2:latest"
+)
+
+# Expose fastapi app for production WSGI/ASGI servers (e.g. gunicorn/uvicorn)
+app = forge.app
+
+if __name__ == "__main__":
+    # Start the server locally when running app.py directly
+    forge.run(host="127.0.0.1", port=8000)

ragforge_framework-0.1.0/data/data.txt

@@ -0,0 +1 @@
+Yashodeep Hundiwale is an experienced AI Engineer and creator of RAGForge.

ragforge_framework-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "ragforge-framework"
+version = "0.1.0"
+description = "Modular AI Backend Framework built with FastAPI, LiteLLM and LangChain"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "diskcache>=5.6.3",
+    "faiss-cpu>=1.14.3",
+    "fastapi>=0.139.0",
+    "langchain>=1.3.12",
+    "langchain-community>=0.4.2",
+    "langchain-google-genai>=4.2.7",
+    "langchain-groq>=1.1.3",
+    "langchain-huggingface>=1.2.2",
+    "langchain-litellm>=0.7.0",
+    "langchain-mistralai>=1.1.6",
+    "langchain-ollama>=1.1.0",
+    "langchain-openai>=1.3.5",
+    "langchain-redis>=0.2.5",
+    "langchain-text-splitters>=1.1.2",
+    "langgraph>=1.2.9",
+    "litellm>=1.91.1",
+    "pandas>=3.0.3",
+    "pypdf>=6.14.2",
+    "python-dotenv>=1.2.2",
+    "sentence-transformers>=5.6.0",
+    "uvicorn>=0.51.0",
+]
+
+[project.scripts]
+ragforge = "ragforge_framework.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

ragforge_framework-0.1.0/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-0.1.0/ragforge_framework/admin/__init__.py

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

ragforge_framework-0.1.0/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-0.1.0/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-0.1.0/ragforge_framework/cache/__init__.py

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