ragforge-framework 0.1.0__py3-none-any.whl

ragforge_framework/rag/chain.py

@@ -0,0 +1,28 @@
+from langchain_classic.chains import create_retrieval_chain
+from langchain_classic.chains.combine_documents import (
+    create_stuff_documents_chain,
+)
+
+from .prompt import get_prompt
+from .retriever import get_retriever
+from ..llm.service import LLMService
+
+
+def get_chain(config):
+    """
+    Constructs the full LangChain document retrieval and query chain.
+    """
+    service = LLMService(config)
+    llm = service.get_langchain_model()
+
+    document_chain = create_stuff_documents_chain(
+        llm,
+        get_prompt()
+    )
+
+    rag_chain = create_retrieval_chain(
+        get_retriever(config),
+        document_chain
+    )
+
+    return rag_chain

ragforge_framework/rag/embeddings.py

@@ -0,0 +1,10 @@
+from langchain_huggingface import HuggingFaceEmbeddings
+
+
+def get_embeddings(config):
+    """
+    Instantiates HuggingFace Embeddings based on the configuration.
+    """
+    return HuggingFaceEmbeddings(
+        model_name=config.EMBEDDING_MODEL
+    )

ragforge_framework/rag/engine.py

@@ -0,0 +1,31 @@
+from .chain import get_chain
+from ..llm.gateway import current_ip_var
+
+
+class RAGEngine:
+    """
+    RAG Execution Engine.
+    Executes LangChain query calls while logging execution state via contextvars.
+    """
+    def __init__(self, config):
+        self.config = config
+        self.chain = None
+
+    def chat(self, prompt: str, ip: str = None) -> str:
+        if self.chain is None:
+            self.chain = get_chain(self.config)
+
+        token = None
+        if ip:
+            token = current_ip_var.set(ip)
+
+        try:
+            response = self.chain.invoke(
+                {
+                    "input": prompt
+                }
+            )
+            return response["answer"]
+        finally:
+            if token:
+                current_ip_var.reset(token)

ragforge_framework/rag/injest.py

@@ -0,0 +1,81 @@
+import os
+from langchain_community.document_loaders import TextLoader, PyPDFLoader
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+from .embeddings import get_embeddings
+from .vectorstore import (
+    create_vectorstore,
+    save_vectorstore,
+)
+
+
+def _load_single_file(file_path: str):
+    """
+    Loads a single document file using the appropriate loader based on file extension.
+    """
+    ext = os.path.splitext(file_path)[1].lower()
+    try:
+        if ext == ".txt":
+            # Using TextLoader with UTF-8 encoding
+            return TextLoader(file_path, encoding="utf-8").load()
+        elif ext == ".pdf":
+            # Using PyPDFLoader for PDFs
+            return PyPDFLoader(file_path).load()
+        else:
+            print(f"  [!] Skipping unsupported file extension: {file_path}")
+            return []
+    except Exception as e:
+        print(f"  [!] Error loading file {file_path}: {e}")
+        return []
+
+
+def _load_documents(path: str):
+    """
+    Scans and loads files from a directory recursively, or loads a single file directly.
+    """
+    if os.path.isdir(path):
+        documents = []
+        for root, _, files in os.walk(path):
+            for file in files:
+                full_path = os.path.join(root, file)
+                documents.extend(_load_single_file(full_path))
+        return documents
+    elif os.path.isfile(path):
+        return _load_single_file(path)
+    else:
+        raise FileNotFoundError(f"Path not found: {path}")
+
+
+def ingest(config):
+    """
+    Ingests source text and PDF documents into the FAISS vector database.
+    """
+    print(f"\nLoading documents from {config.DATA_PATH}...")
+    documents = _load_documents(config.DATA_PATH)
+    print(f"Loaded {len(documents)} document page(s)/file(s).")
+
+    if not documents:
+        print("  [!] No valid text content was loaded. Ingestion skipped.")
+        return
+
+    print("\nSplitting documents...")
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=config.CHUNK_SIZE,
+        chunk_overlap=config.CHUNK_OVERLAP
+    )
+    chunks = splitter.split_documents(documents)
+    print(f"Created {len(chunks)} chunks.")
+
+    print("\nLoading embedding model...")
+    embeddings = get_embeddings(config)
+
+    print("Creating FAISS index...")
+    vectorstore = create_vectorstore(
+        chunks,
+        embeddings
+    )
+
+    print("Saving FAISS index...")
+    save_vectorstore(vectorstore, config)
+
+    print("\nRAGForge ingestion completed successfully!")

ragforge_framework/rag/prompt.py

@@ -0,0 +1,61 @@
+from langchain_core.prompts import ChatPromptTemplate
+
+
+def get_prompt():
+    """
+    Creates and returns the chat prompt template for document retrieval.
+    """
+    return ChatPromptTemplate.from_template(
+        """
+You are the official AI assistant for Yashodeep Hundiwale.
+
+Your purpose is to help visitors learn about Yashodeep by answering questions ONLY using the provided context.
+
+You can answer questions about:
+
+- Education
+- Skills
+- Technical expertise
+- AI/ML projects
+- Work experience
+- Internships
+- Certifications
+- Achievements
+- Portfolio
+- Resume
+- Contact information
+- Career goals
+
+Guidelines:
+
+1. Answer ONLY using the provided context.
+
+2. Never invent, guess or assume information.
+
+3. If the answer is unavailable in the context reply exactly:
+
+"Sorry, I don't have that information about Yashodeep."
+
+4. Keep answers concise.
+
+5. Be professional.
+
+6. If the user greets you, greet them back naturally.
+
+7. If the question is unrelated to Yashodeep, reply:
+
+"I'm designed to answer questions about Yashodeep Hundiwale and his portfolio."
+
+<context>
+
+{context}
+
+</context>
+
+Question:
+
+{input}
+
+Answer:
+"""
+    )

ragforge_framework/rag/retriever.py

@@ -0,0 +1,19 @@
+from .embeddings import get_embeddings
+from .vectorstore import load_vectorstore
+
+
+def get_retriever(config):
+    """
+    Builds the document retriever from the configured vector database.
+    """
+    embeddings = get_embeddings(config)
+    vectorstore = load_vectorstore(embeddings, config)
+
+    return vectorstore.as_retriever(
+        search_type=config.SEARCH_TYPE,
+        search_kwargs={
+            "k": config.TOP_K,
+            "fetch_k": config.FETCH_K,
+            "lambda_mult": config.LAMBDA_MULT
+        }
+    )

ragforge_framework/rag/vectorstore.py

@@ -0,0 +1,31 @@
+from langchain_community.vectorstores import FAISS
+
+
+def create_vectorstore(documents, embeddings):
+    """
+    Creates a new FAISS vector database from document text chunks.
+    """
+    return FAISS.from_documents(
+        documents,
+        embeddings
+    )
+
+
+def save_vectorstore(vectorstore, config):
+    """
+    Persists the vector index to local storage.
+    """
+    vectorstore.save_local(
+        config.FAISS_PATH
+    )
+
+
+def load_vectorstore(embeddings, config):
+    """
+    Loads a FAISS vector index from local storage.
+    """
+    return FAISS.load_local(
+        config.FAISS_PATH,
+        embeddings,
+        allow_dangerous_deserialization=True
+    )

ragforge_framework-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,28 @@
+ragforge_framework/__init__.py,sha256=7McZG9pq7Uf50gHLxI3pp7cdmFHcjizaG8QX-juHaNw,298
+ragforge_framework/app.py,sha256=ByIxn9C7ML0wMg8avu9eH8iWRSlNZgMR2Z4zMkWBccU,2581
+ragforge_framework/cli.py,sha256=1ViW9U3D9FyonDAdQiKLB9P9tenkw6xZZqJfbmMsX2s,3432
+ragforge_framework/config.py,sha256=pgPA30F2RjLQ0_YdFNpgFEhqVt99paG_5LPM0Y_5Gfk,1766
+ragforge_framework/core.py,sha256=pIbJz0hqmOMUsGvl4onlTjMv7ZfzWuz5vpj6OWJL078,1420
+ragforge_framework/admin/__init__.py,sha256=ueJuO7uDQLSqgycAHg7vI27Hwuzv9r_e4XNwFVjanSo,31
+ragforge_framework/admin/routes.py,sha256=J5jl5pEiQHq2qX-INpLdLkaubfYASqKSFDymTvdZrkY,6548
+ragforge_framework/cache/__init__.py,sha256=phh4bDz18CO_ee3CPSaxl_2g-486SL8E7zM_Uq2oWEk,31
+ragforge_framework/cache/repository.py,sha256=GHuo9XaYB3cLsgEDyD8f3Nfa6doBJ5GBP7mWgrSj6cQ,4070
+ragforge_framework/cache/response_cache.py,sha256=XTSSgNSfTnR_Lalf7_pWesXdYn9ZJFsy0KnwnNf6ks4,2753
+ragforge_framework/cache/user_manager.py,sha256=KYfqGSNNhZIJ6BQ18i8GvQYE4q7BkWesOaFLcfY0b5A,8499
+ragforge_framework/llm/__init__.py,sha256=shJneb6VyTWc0xYtd5bQHY1qwkwsd9m0EEPR88Bwero,29
+ragforge_framework/llm/gateway.py,sha256=n7yASnt7gf_YbfzuxteS4GIg46kC4Q92v7HtF9a_R3I,2675
+ragforge_framework/llm/service.py,sha256=bKvRFnHKEN6M-UAcYRTsSh99-TyWMQ4WgKE8RtnuBuo,1497
+ragforge_framework/models/__init__.py,sha256=lrhqx1ts0qG0CSFDGmndU3gM7IHg53VtO4J-ly2lMas,32
+ragforge_framework/models/schemas.py,sha256=DViLeWGhv8N61yAMzKn0nOuh7RrK8iNvBiw9rrUjHJA,1211
+ragforge_framework/rag/__init__.py,sha256=R6sTrirMw8Ic81opuSWxQS0xA_m_E85TEG6b2WtiVUU,29
+ragforge_framework/rag/chain.py,sha256=1DNuEElD8nJ5CQp_Zrv3ZgSKxuHpFK4_kjEah4xOB4E,658
+ragforge_framework/rag/embeddings.py,sha256=-qXGsX7mOiJYpfycezg75DWuS7x6cdtvQGvASEeNjcY,252
+ragforge_framework/rag/engine.py,sha256=wOet9Vo7U9iCjVmJMk1yqU91KD3lKmExwZOuYRB_Gq8,779
+ragforge_framework/rag/injest.py,sha256=K6SVqSPBr5AFk3HHd04SqyY_45mzSJ9H-g5gYW9nthk,2497
+ragforge_framework/rag/prompt.py,sha256=NbHTSCnwSsHocNBOrz_eOdfd80M7gdTEhsLLAvRtZNA,1141
+ragforge_framework/rag/retriever.py,sha256=3JZPG_SxNubWi37e-JrIRvtF4_nwsRIvUEQn6fI-GOw,526
+ragforge_framework/rag/vectorstore.py,sha256=26K_e678eRTf40TPMcYouKLhMVKnmjyzLVgECnQfuTg,667
+ragforge_framework-0.1.0.dist-info/METADATA,sha256=S9pI_3uR7t9QL9vZ66HO4mipuwPQpqbOAzFMqoiFV5s,5673
+ragforge_framework-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+ragforge_framework-0.1.0.dist-info/entry_points.txt,sha256=AUkoOCwgNB81F0hpo3urqKxde8sDkO73S-ilhe7NVnI,57
+ragforge_framework-0.1.0.dist-info/RECORD,,

ragforge_framework-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ragforge_framework-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ragforge = ragforge_framework.cli:main