A curated collection of practical AI projects implementing OCR systems, RAG, AI agents, and other AI use cases.
audit: fix hybrid_rag_system - add env comment, rewrite em dashes, add module docstring, add 26 missing docstrings
Tiioluwaniaa9d8b2e6882
diff --git a/rag_apps/hybrid_rag_system/.env.example b/rag_apps/hybrid_rag_system/.env.exampleindex b263636..86490cc 100644--- a/rag_apps/hybrid_rag_system/.env.example+++ b/rag_apps/hybrid_rag_system/.env.example@@ -1 +1,2 @@+# Your Mistral AI API key. Get one for free at https://platform.mistral.aiMISTRAL_API_KEY=your_mistral_api_key_herediff --git a/rag_apps/hybrid_rag_system/README.md b/rag_apps/hybrid_rag_system/README.mdindex 04fb207..549d157 100644--- a/rag_apps/hybrid_rag_system/README.md+++ b/rag_apps/hybrid_rag_system/README.md@@ -12,14 +12,14 @@ Hybrid RAG System dual-indexes every uploaded document: a knowledge graph captur## Features-- **Dual indexing** — every document is indexed into both a knowledge graph and a vector store in a single ingestion pass-- **Parallel retrieval** — graph and vector queries run concurrently via `ThreadPoolExecutor`, minimising latency-- **Context fusion** — graph entities/relationships and ranked vector chunks are merged into one unified prompt-- **Adjustable retrieval** — sliders to tune top-K vector chunks (1–20) and max graph entities (5–50) at query time-- **Document cache** — SHA-256 hash check skips re-indexing files that are already processed-- **Progress tracking** — two-phase progress bar shows entity extraction and embedding status during ingestion-- **Source transparency** — answer panel shows graph sources and vector sources in separate labelled sections with similarity scores-- **Performance metrics** — per-query timing for graph retrieval, vector retrieval, and generation+- **Dual indexing**: every document is indexed into both a knowledge graph and a vector store in a single ingestion pass+- **Parallel retrieval**: graph and vector queries run concurrently via `ThreadPoolExecutor`, minimising latency+- **Context fusion**: graph entities/relationships and ranked vector chunks are merged into one unified prompt+- **Adjustable retrieval**: sliders to tune top-K vector chunks (1–20) and max graph entities (5–50) at query time+- **Document cache**: SHA-256 hash check skips re-indexing files that are already processed+- **Progress tracking**: two-phase progress bar shows entity extraction and embedding status during ingestion+- **Source transparency**: answer panel shows graph sources and vector sources in separate labelled sections with similarity scores+- **Performance metrics**: per-query timing for graph retrieval, vector retrieval, and generation## Tech Stack@@ -29,8 +29,8 @@ Hybrid RAG System dual-indexes every uploaded document: a knowledge graph captur| Vector retrieval | LangChain + ChromaDB || LLM | Mistral Small 4 (`mistral-small-latest`) via Mistral AI API || Embeddings | `nomic-embed-text` via Ollama (local, no API key needed) |-| Graph store | NetworkX — persisted as JSON |-| Vector database | ChromaDB — local persistent storage |+| Graph store | NetworkX, persisted as JSON |+| Vector database | ChromaDB, local persistent storage || UI | Streamlit || Configuration | python-dotenv |@@ -94,7 +94,7 @@ streamlit run app.pyThe app opens at `http://localhost:8501`.1. Upload a PDF or TXT file using the sidebar uploader-2. Click **Process Document** — the progress bar tracks entity extraction (Phase 1) then chunk embedding (Phase 2)+2. Click **Process Document**. The progress bar tracks entity extraction (Phase 1) then chunk embedding (Phase 2)3. Type a question in the main panel and click **Ask**4. Review the answer and expand **Graph Sources** and **Vector Sources** to inspect the retrieved evidence@@ -116,7 +116,7 @@ Ollama runs locally and requires no API key.```texthybrid-rag-system/-├── app.py # Streamlit application — UI, session state, parallel retrieval+├── app.py # Streamlit application: UI, session state, parallel retrieval├── config.py # Constants and automatic data-directory creation├── src/│ ├── document_processor.py # PDF/TXT loading, text chunking, hash-based document cache@@ -136,3 +136,7 @@ hybrid-rag-system/├── .env.example # Environment variable template└── requirements.txt # Python dependencies```++---++[Back to top](#hybrid-rag-system)diff --git a/rag_apps/hybrid_rag_system/app.py b/rag_apps/hybrid_rag_system/app.pyindex d48b13d..4f34d45 100644--- a/rag_apps/hybrid_rag_system/app.py+++ b/rag_apps/hybrid_rag_system/app.py@@ -1,3 +1,4 @@+"""Streamlit application combining knowledge graph retrieval and vector retrieval into a hybrid RAG pipeline for document question answering."""import osimport sysimport timediff --git a/rag_apps/hybrid_rag_system/src/context_fusion.py b/rag_apps/hybrid_rag_system/src/context_fusion.pyindex e17f28c..39b9ce5 100644--- a/rag_apps/hybrid_rag_system/src/context_fusion.py+++ b/rag_apps/hybrid_rag_system/src/context_fusion.py@@ -2,6 +2,7 @@ from typing import Anydef format_graph_context(graph_results: dict[str, Any]) -> str:+ """Formats graph retrieval results into a plain-text block listing entities and relationships."""entities = graph_results.get("entities", [])relationships = graph_results.get("relationships", [])@@ -27,6 +28,7 @@ def format_graph_context(graph_results: dict[str, Any]) -> str:def format_vector_context(vector_results: list[dict[str, Any]]) -> str:+ """Formats vector retrieval results into a plain-text block of numbered chunks with similarity scores."""if not vector_results:return "No vector context available."lines = []@@ -42,6 +44,7 @@ def fuse_context(graph_results: dict[str, Any],vector_results: list[dict[str, Any]],) -> str:+ """Combines formatted graph and vector contexts into a single prompt-ready string."""graph_ctx = format_graph_context(graph_results)vector_ctx = format_vector_context(vector_results)return (diff --git a/rag_apps/hybrid_rag_system/src/document_processor.py b/rag_apps/hybrid_rag_system/src/document_processor.pyindex 40318be..23072b0 100644--- a/rag_apps/hybrid_rag_system/src/document_processor.py+++ b/rag_apps/hybrid_rag_system/src/document_processor.py@@ -9,6 +9,7 @@ from config import CACHE_FILE, CHUNK_SIZE, CHUNK_OVERLAPdef load_document(file_bytes: bytes, filename: str) -> str:+ """Reads a PDF or TXT file from bytes and returns its full text content."""suffix = Path(filename).suffix.lower()if suffix == ".pdf":import io@@ -26,6 +27,7 @@ def load_document(file_bytes: bytes, filename: str) -> str:def chunk_text(text: str) -> list[str]:+ """Splits text into overlapping chunks using LangChain's RecursiveCharacterTextSplitter."""splitter = RecursiveCharacterTextSplitter(chunk_size=CHUNK_SIZE,chunk_overlap=CHUNK_OVERLAP,@@ -35,10 +37,12 @@ def chunk_text(text: str) -> list[str]:def compute_hash(content: str) -> str:+ """Returns an MD5 hex digest of the given text string."""return hashlib.md5(content.encode()).hexdigest()def load_cache() -> dict:+ """Loads the processed-documents registry from disk, returning an empty dict if absent or unreadable."""if CACHE_FILE.exists():try:return json.loads(CACHE_FILE.read_text(encoding="utf-8"))@@ -48,14 +52,17 @@ def load_cache() -> dict:def save_cache(cache: dict) -> None:+ """Writes the processed-documents registry to disk as JSON."""CACHE_FILE.write_text(json.dumps(cache, indent=2), encoding="utf-8")def is_cached(content_hash: str) -> Optional[dict]:+ """Returns the cached metadata dict for a document hash, or None if it has not been indexed."""return load_cache().get(content_hash)def add_to_cache(content_hash: str, filename: str, num_chunks: int, num_entities: int) -> None:+ """Adds a processed document's metadata to the on-disk cache."""cache = load_cache()cache[content_hash] = {"filename": filename,@@ -67,4 +74,5 @@ def add_to_cache(content_hash: str, filename: str, num_chunks: int, num_entitiesdef list_cached_docs() -> list[dict]:+ """Returns a list of all cached document metadata dicts."""return list(load_cache().values())diff --git a/rag_apps/hybrid_rag_system/src/graph_indexer.py b/rag_apps/hybrid_rag_system/src/graph_indexer.pyindex affd22b..b6458a4 100644--- a/rag_apps/hybrid_rag_system/src/graph_indexer.py+++ b/rag_apps/hybrid_rag_system/src/graph_indexer.py@@ -31,6 +31,7 @@ JSON:"""def _parse_extraction(raw: str) -> dict:+ """Extracts the first JSON object from a raw string and returns it as a dict, or an empty scaffold on failure."""match = re.search(r'\{.*\}', raw, re.DOTALL)if match:try:@@ -41,6 +42,7 @@ def _parse_extraction(raw: str) -> dict:def _extract_from_chunk(client: Mistral, text: str) -> dict:+ """Sends a text chunk to Mistral and returns extracted entities and relationships, retrying up to three times."""for attempt in range(3):try:resp = client.chat.complete(@@ -61,6 +63,7 @@ def build_doc_graph(client: Mistral,progress_cb: Optional[Callable[[int, int], None]] = None,) -> nx.Graph:+ """Builds a NetworkX graph from a list of text chunks by extracting entities and relationships via Mistral."""G = nx.Graph()for i, chunk in enumerate(chunks):if progress_cb:@@ -106,6 +109,7 @@ def build_doc_graph(def merge_into_combined(G_new: nx.Graph) -> nx.Graph:+ """Merges a new document graph into the persisted combined graph and saves it."""G = load_combined_graph()for node, data in G_new.nodes(data=True):if G.has_node(node):@@ -127,12 +131,14 @@ def merge_into_combined(G_new: nx.Graph) -> nx.Graph:def save_doc_graph(G: nx.Graph, doc_hash: str) -> None:+ """Serialises a document graph to a JSON file named by its hash."""path = GRAPHS_DIR / f"{doc_hash}.json"data = nx.node_link_data(G)path.write_text(json.dumps(data, indent=2), encoding="utf-8")def load_combined_graph() -> nx.Graph:+ """Loads the combined graph from disk, returning an empty graph if not found."""if COMBINED_GRAPH_FILE.exists():try:data = json.loads(COMBINED_GRAPH_FILE.read_text(encoding="utf-8"))@@ -143,5 +149,6 @@ def load_combined_graph() -> nx.Graph:def save_combined_graph(G: nx.Graph) -> None:+ """Serialises the combined graph to its fixed JSON path."""data = nx.node_link_data(G)COMBINED_GRAPH_FILE.write_text(json.dumps(data, indent=2), encoding="utf-8")diff --git a/rag_apps/hybrid_rag_system/src/graph_retriever.py b/rag_apps/hybrid_rag_system/src/graph_retriever.pyindex 139963c..cfac56a 100644--- a/rag_apps/hybrid_rag_system/src/graph_retriever.py+++ b/rag_apps/hybrid_rag_system/src/graph_retriever.py@@ -14,11 +14,13 @@ _STOP_WORDS = {def _query_terms(query: str) -> list[str]:+ """Tokenises a query string and returns non-stop-word terms longer than two characters."""words = re.findall(r'\b\w+\b', query.lower())return [w for w in words if w not in _STOP_WORDS and len(w) > 2]def _score_node(node_name: str, terms: list[str]) -> float:+ """Returns a relevance score for a graph node based on how many query terms match its name."""name_lower = node_name.lower()score = 0.0for term in terms:@@ -30,6 +32,7 @@ def _score_node(node_name: str, terms: list[str]) -> float:def retrieve_from_graph(G: nx.Graph, query: str, max_entities: int) -> dict[str, Any]:+ """Performs BFS from top-scoring seed nodes and returns matched entities and relationships up to max_entities."""if G.number_of_nodes() == 0:return {"entities": [], "relationships": [], "seed_nodes": []}diff --git a/rag_apps/hybrid_rag_system/src/mistral_client.py b/rag_apps/hybrid_rag_system/src/mistral_client.pyindex 17a77a3..7e1d96d 100644--- a/rag_apps/hybrid_rag_system/src/mistral_client.py+++ b/rag_apps/hybrid_rag_system/src/mistral_client.py@@ -18,6 +18,7 @@ Provide a clear, well-structured answer based on the context above."""def generate_answer(client: Mistral, question: str, fused_context: str) -> str:+ """Sends the fused context and question to Mistral Small 4 and returns the generated answer string."""resp = client.chat.complete(model="mistral-small-latest",messages=[diff --git a/rag_apps/hybrid_rag_system/src/vector_indexer.py b/rag_apps/hybrid_rag_system/src/vector_indexer.pyindex 7f0c053..b144fd7 100644--- a/rag_apps/hybrid_rag_system/src/vector_indexer.py+++ b/rag_apps/hybrid_rag_system/src/vector_indexer.py@@ -21,6 +21,7 @@ class OllamaEmbeddingFunction(EmbeddingFunction):def check_ollama() -> tuple[bool, str]:+ """Checks whether Ollama is reachable and whether the embedding model is installed, returning a status tuple."""try:resp = requests.get(f"{OLLAMA_URL}/api/tags", timeout=5)if resp.status_code == 200:@@ -35,6 +36,7 @@ def check_ollama() -> tuple[bool, str]:def get_chroma_collection() -> chromadb.Collection:+ """Creates or retrieves the persistent ChromaDB collection using the Ollama embedding function."""client = chromadb.PersistentClient(path=str(CHROMA_DIR))return client.get_or_create_collection(name=CHROMA_COLLECTION,@@ -49,6 +51,7 @@ def index_chunks(doc_hash: str,progress_cb: Optional[Callable[[int, int], None]] = None,) -> None:+ """Embeds and stores text chunks in ChromaDB, calling progress_cb after each batch."""batch_size = 5total = len(chunks)for i in range(0, total, batch_size):@@ -61,6 +64,7 @@ def index_chunks(def collection_has_doc(collection: chromadb.Collection, doc_hash: str) -> bool:+ """Returns True if the ChromaDB collection already contains chunks for the given document hash."""try:results = collection.get(where={"doc_hash": doc_hash}, limit=1)return len(results["ids"]) > 0diff --git a/rag_apps/hybrid_rag_system/src/vector_retriever.py b/rag_apps/hybrid_rag_system/src/vector_retriever.pyindex b1cebf7..b3f7386 100644--- a/rag_apps/hybrid_rag_system/src/vector_retriever.py+++ b/rag_apps/hybrid_rag_system/src/vector_retriever.py@@ -7,6 +7,7 @@ def retrieve_from_vector(query: str,top_k: int,) -> list[dict[str, Any]]:+ """Queries ChromaDB for the top-k most semantically similar chunks to the query string."""count = collection.count()if count == 0:return []