Merge pull request #115 from AOSSIE-Org/doc_strings_and_logger

Added Doc strings and logger

Author: ParagGhatage

backend/app/db/vector_store.py

@@ -1,5 +1,31 @@
+"""
+vector_store.py
+------------------
+Initializes and manages the Pinecone vector database connection for the Perspective API.
+
+This module:
+    - Loads Pinecone credentials from environment variables.
+    - Creates the Pinecone index if it does not exist.
+    - Connects to the specified index for vector operations.
+
+Attributes:
+    PINECONE_API_KEY (str): API key for authenticating with Pinecone.
+    INDEX_NAME (str): Name of the Pinecone index used for storing vectors.
+    DIMENSIONS (int): Dimensionality of vector embeddings.
+    METRIC (str): Similarity metric used for vector comparison.
+    index (pinecone.Index): Connected Pinecone index instance.
+
+Raises:
+    ValueError: If `PINECONE_API_KEY` is not set in environment variables.
+    RuntimeError: If Pinecone initialization or index connection fails.
+"""
+
 import os
 from pinecone import Pinecone, ServerlessSpec, CloudProvider, AwsRegion
+from app.logging.logging_config import setup_logger
+
+
+logger = setup_logger(__name__)
 
 # Load Pinecone credentials from environment variables
 PINECONE_API_KEY = os.getenv("PINECONE_API_KEY")
@@ -19,15 +45,15 @@
 
 # Create index if it doesn't exist
 if not pc.has_index(INDEX_NAME):
-    print(f"Creating index: {INDEX_NAME}")
+    logger.info(f"Creating index: {INDEX_NAME}")
     pc.create_index(
         name=INDEX_NAME,
         dimension=DIMENSIONS,
         metric=METRIC,
         spec=ServerlessSpec(cloud=CloudProvider.AWS, region=AwsRegion.US_EAST_1),
     )
 else:
-    print(f"Index '{INDEX_NAME}' already exists")
+    logger.info(f"Index '{INDEX_NAME}' already exists")
 
 try:
     # Connect to the index

backend/app/logging/logging_config.py

@@ -0,0 +1,39 @@
+import logging
+import sys
+
+def setup_logger(name: str) -> logging.Logger:
+    """
+    Creates and configures a logger with console + file output.
+
+    Args:
+        name (str): The logger's name (usually __name__ of the calling module).
+
+    Returns:
+        logging.Logger: Configured logger instance.
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.DEBUG)  # Log everything from DEBUG and above
+
+    # Avoid adding duplicate handlers if logger already set
+    if logger.handlers:
+        return logger
+
+    # Formatter with timestamp, log level, module name
+    formatter = logging.Formatter(
+        "[%(asctime)s] [%(levelname)s] [%(name)s]: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S"
+    )
+
+    # Console Handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(logging.INFO)
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+
+    # File Handler
+    file_handler = logging.FileHandler("app.log")
+    file_handler.setLevel(logging.DEBUG)  # Keep detailed logs in file
+    file_handler.setFormatter(formatter)
+    logger.addHandler(file_handler)
+
+    return logger

backend/app/modules/bias_detection/check_bias.py

@@ -1,7 +1,34 @@
+"""
+check_bias.py
+-------------
+Provides functionality to evaluate the bias score of an article using the Groq API.
+
+This module:
+    - Loads environment variables for Groq API credentials.
+    - Connects to the Groq client.
+    - Defines `check_bias()` to analyze a given article's bias and return a score.
+
+Functions:
+    check_bias(text: str) -> dict:
+        Analyzes the input article text and returns a bias score between 0 and 100,
+        where 0 indicates the least bias and 100 indicates the highest bias.
+
+Environment Variables:
+    GROQ_API_KEY (str): API key for authenticating with Groq.
+
+Raises:
+    ValueError: If `text` is missing or empty.
+    Exception: For errors during API interaction or response parsing.
+"""
+
+
 import os
 from groq import Groq
 from dotenv import load_dotenv
 import json
+from app.logging.logging_config import setup_logger
+
+logger = setup_logger(__name__)
 
 load_dotenv()
 
@@ -10,10 +37,11 @@
 
 def check_bias(text):
     try:
-        print(text)
-        print(json.dumps(text))
+        logger.debug(f"Raw article text: {text}")
+        logger.debug(f"JSON dump of text: {json.dumps(text)}")
 
         if not text:
+            logger.error("Missing or empty 'cleaned_text'")
             raise ValueError("Missing or empty 'cleaned_text'")
 
         chat_completion = client.chat.completions.create(
@@ -37,16 +65,16 @@ def check_bias(text):
             temperature=0.3,
             max_tokens=512,
         )
-
         bias_score = chat_completion.choices[0].message.content.strip()
+        logger.info(f"Bias score calculated: {bias_score}")
 
         return {
             "bias_score": bias_score,
             "status": "success",
         }
 
     except Exception as e:
-        print(f"Error in bias_detection: {e}")
+        logger.exception("Error in bias detection")
         return {
             "status": "error",
             "error_from": "bias_detection",

backend/app/modules/chat/embed_query.py

@@ -1,3 +1,25 @@
+"""
+embed_query.py
+--------------
+Provides functionality to generate vector embeddings for text queries using
+the Sentence Transformers library.
+
+This module:
+    - Loads a pre-trained "all-MiniLM-L6-v2" model.
+    - Defines a helper function `embed_query()` to encode a query string into
+      a list of numerical embeddings.
+
+Functions:
+    embed_query(query: str) -> list[float]:
+        Encodes the given query into a numerical vector representation.
+
+Model:
+    all-MiniLM-L6-v2 (from sentence-transformers):
+        A lightweight transformer model optimized for semantic search and
+        similarity tasks.
+"""
+
+
 from sentence_transformers import SentenceTransformer
 
 embedder = SentenceTransformer("all-MiniLM-L6-v2")

backend/app/modules/chat/get_rag_data.py

@@ -1,3 +1,29 @@
+"""
+get_rag_data.py
+---------------
+Provides functionality to perform semantic search queries on the Pinecone
+vector database for Retrieval-Augmented Generation (RAG) workflows.
+
+This module:
+    - Loads Pinecone credentials from environment variables.
+    - Connects to the "perspective" index in Pinecone.
+    - Defines `search_pinecone()` to search stored vector embeddings and
+      retrieve the most relevant matches.
+
+Functions:
+    search_pinecone(query: str, top_k: int = 5) -> list[dict]:
+        Encodes the input query, searches Pinecone for the most similar
+        vectors, and returns a list of matches with metadata.
+
+Environment Variables:
+    PINECONE_API_KEY (str): API key for authenticating with Pinecone.
+
+Dependencies:
+    - app.modules.chat.embed_query (for generating embeddings)
+    - pinecone (Pinecone client library)
+"""
+
+
 from pinecone import Pinecone
 from dotenv import load_dotenv
 from app.modules.chat.embed_query import embed_query

backend/app/modules/chat/llm_processing.py

@@ -1,6 +1,34 @@
+"""
+llm_processing.py
+-----------------
+Handles Large Language Model (LLM) interactions for context-based question answering.
+
+This module:
+    - Connects to the Groq API using credentials from environment variables.
+    - Builds a context string from retrieved documents.
+    - Sends user questions along with context to the LLM.
+    - Returns generated answers.
+
+Functions:
+    build_context(docs: list[dict]) -> str:
+        Extracts relevant fields (explanation or reasoning) from document
+        metadata and combines them into a single context string.
+
+    ask_llm(question: str, docs: list[dict]) -> str:
+        Builds context from the provided documents, sends it along with the
+        question to the LLM, and returns the model's answer.
+
+Environment Variables:
+    GROQ_API_KEY (str): API key for authenticating with Groq.
+"""
+
+
 import os
 from groq import Groq
 from dotenv import load_dotenv
+from app.logging.logging_config import setup_logger
+
+logger = setup_logger(__name__)
 
 load_dotenv()
 
@@ -16,7 +44,7 @@ def build_context(docs):
 
 def ask_llm(question, docs):
     context = build_context(docs)
-    print(context)
+    logger.debug(f"Generated context for LLM:\n{context}")
     prompt = f"""You are an assistant that answers based on context.
 
 Context:
@@ -33,5 +61,5 @@ def ask_llm(question, docs):
             {"role": "user", "content": prompt},
         ],
     )
-
+    logger.info("LLM response retrieved successfully.")
     return response.choices[0].message.content

backend/app/modules/facts_check/llm_processing.py

@@ -1,8 +1,36 @@
+"""
+llm_processing.py
+-----------------
+Handles claim extraction and fact verification tasks using the Groq LLM API.
+
+This module:
+    - Connects to the Groq API with credentials from environment variables.
+    - Extracts verifiable factual claims from text.
+    - Verifies claims using provided search results and evidence.
+    - Returns structured responses with verdicts and explanations.
+
+Functions:
+    run_claim_extractor_sdk(state: dict) -> dict:
+        Extracts up to three concise, verifiable claims from the input text
+        stored in the `state` dictionary.
+
+    run_fact_verifier_sdk(search_results: list[dict]) -> dict:
+        Evaluates provided claims against web search evidence and returns
+        structured JSON verdicts for each claim.
+
+Environment Variables:
+    GROQ_API_KEY (str): API key for authenticating with Groq.
+"""
+
+
 import os
 from groq import Groq
 from dotenv import load_dotenv
 import json
 import re
+from app.logging.logging_config import setup_logger
+
+logger = setup_logger(__name__)
 
 load_dotenv()
 
@@ -41,6 +69,8 @@ def run_claim_extractor_sdk(state):
         )
 
         extracted_claims = chat_completion.choices[0].message.content.strip()
+        logger.debug(f"Extracted claims:\n{extracted_claims}")
+
 
         return {
             **state,
@@ -49,7 +79,7 @@ def run_claim_extractor_sdk(state):
         }
 
     except Exception as e:
-        print(f"Error in claim_extraction: {e}")
+        logger.exception("Error in claim_extraction")
         return {
             "status": "error",
             "error_from": "claim_extraction",
@@ -107,13 +137,13 @@ def run_fact_verifier_sdk(search_results):
 
             # Strip markdown code blocks if present
             content = re.sub(r"^```json|```$", "", content).strip()
-            print(content)
+            logger.debug(f"Raw LLM fact verification output:\n{content}")
 
             # Try parsing the JSON response
             try:
                 parsed = json.loads(content)
             except Exception as parse_err:
-                print(f"❌ LLM JSON parse error: {parse_err}")
+                logger.error(f"LLM JSON parse error: {parse_err}")
 
             results_list.append(parsed)
 
@@ -124,7 +154,7 @@ def run_fact_verifier_sdk(search_results):
         }
 
     except Exception as e:
-        print(f"🔥 Error in fact_verification: {e}")
+        logger.exception("Error in fact_verification")
         return {
             "status": "error",
             "error_from": "fact_verification",

backend/app/modules/facts_check/web_search.py

@@ -1,3 +1,23 @@
+"""
+web-search.py
+-------------
+Provides a simple wrapper for performing Google Custom Search queries.
+
+This module:
+    - Loads the Google Search API key from environment variables.
+    - Sends search requests to the Google Custom Search API.
+    - Returns the first search result with title, link, and snippet.
+
+Functions:
+    search_google(query: str) -> list[dict]:
+        Executes a Google search for the given query and returns the top result
+        in a list containing its title, link, and snippet.
+
+Environment Variables:
+    SEARCH_KEY (str): API key for Google Custom Search API.
+"""
+
+
 import requests
 from dotenv import load_dotenv
 import os