Skip to content

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.example
index 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.ai
MISTRAL_API_KEY=your_mistral_api_key_here
diff --git a/rag_apps/hybrid_rag_system/README.md b/rag_apps/hybrid_rag_system/README.md
index 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.py
The 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.
```text
hybrid-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.py
index 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 os
import sys
import time
diff --git a/rag_apps/hybrid_rag_system/src/context_fusion.py b/rag_apps/hybrid_rag_system/src/context_fusion.py
index 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 Any
def 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.py
index 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_OVERLAP
def 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_entities
def 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.py
index 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.py
index 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.0
for 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.py
index 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.py
index 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 = 5
total = 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"]) > 0
diff --git a/rag_apps/hybrid_rag_system/src/vector_retriever.py b/rag_apps/hybrid_rag_system/src/vector_retriever.py
index 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 []