utils.py

import os
import logging
from typing import List, Dict, Any
from dotenv import load_dotenv
from langchain.schema import Document as LangchainDocument
from langchain_community.vectorstores import FAISS
from langchain_together.chat_models import ChatTogether
from langchain_together.embeddings import TogetherEmbeddings
import spacy
import pandas as pd
import json
import re

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('fact_checker.log'),
        logging.StreamHandler()
    ]
)
logger = logging.getLogger(__name__)

load_dotenv()
logger.info("Environment variables loaded")

# ---------- API Key Helper -------------------------------------------------
def get_together_api_key() -> str:
    """Get Together AI API key from environment variables."""
    try:
        key = os.getenv("TOGETHER_API_KEY")
        if key:
            logger.info("Together AI API key found")
            return key

        # If not found, raise error
        error_msg = (
            "TOGETHER_API_KEY not found. Please set it in one of these ways:\n"
            "1. Create a .env file with: TOGETHER_API_KEY=your_key_here\n"
            "2. Set environment variable: export TOGETHER_API_KEY=your_key_here"
        )
        logger.error(error_msg)
        raise EnvironmentError(error_msg)
    except Exception as e:
        logger.exception("Error retrieving Together AI API key")
        raise


# ========================================================================
# FACT-CHECKING SYSTEM COMPONENTS (OOP Architecture)
# ========================================================================

class ClaimExtractor:
    """
    Handles claim and entity extraction using NLP (spaCy).
    Follows Single Responsibility Principle.
    """

    # Supported entity types for extraction
    ENTITY_TYPES = ['ORG', 'GPE', 'PERSON', 'DATE', 'EVENT', 'MONEY',
                    'PERCENT', 'LAW', 'PRODUCT']

    def __init__(self, model_name: str = "en_core_web_sm"):
        """
        Initialize the ClaimExtractor with a spaCy model.

        Args:
            model_name: Name of the spaCy model to use
        """
        self.model_name = model_name
        self._nlp = None

    @property
    def nlp(self):
        """Lazy load spaCy model to avoid startup overhead."""
        if self._nlp is None:
            try:
                logger.info(f"Loading spaCy model: {self.model_name}")
                self._nlp = spacy.load(self.model_name)
                logger.info(f"Successfully loaded spaCy model: {self.model_name}")
            except OSError as e:
                logger.error(f"spaCy model '{self.model_name}' not found")
                raise RuntimeError(
                    f"spaCy model '{self.model_name}' not found. "
                    f"Please install it with: python -m spacy download {self.model_name}"
                )
            except Exception as e:
                logger.exception(f"Unexpected error loading spaCy model: {self.model_name}")
                raise
        return self._nlp

    def extract_entities(self, doc) -> List[Dict[str, Any]]:
        """
        Extract named entities from a spaCy document.

        Args:
            doc: spaCy document object

        Returns:
            List of entity dictionaries with text, type, and position
        """
        try:
            entities = []
            for ent in doc.ents:
                if ent.label_ in self.ENTITY_TYPES:
                    entities.append({
                        'text': ent.text,
                        'type': ent.label_,
                        'start': ent.start_char,
                        'end': ent.end_char
                    })
            logger.debug(f"Extracted {len(entities)} entities")
            return entities
        except Exception as e:
            logger.exception("Error extracting entities")
            return []

    def extract_claims(self, text: str, min_length: int = 10) -> List[Dict[str, Any]]:
        """
        Extract key claims and named entities from input text.

        Args:
            text: Input text (e.g., news post, social media statement)
            min_length: Minimum length for a sentence to be considered a claim

        Returns:
            List of claim dictionaries with 'text', 'type', and 'entities'
        """
        try:
            logger.info(f"Extracting claims from text ({len(text)} chars)")
            doc = self.nlp(text)
            entities = self.extract_entities(doc)

            # Extract sentences as potential claims
            claims = []
            for sent in doc.sents:
                sent_text = sent.text.strip()
                if len(sent_text) >= min_length:
                    # Find entities in this sentence
                    sent_entities = [
                        e for e in entities
                        if e['start'] >= sent.start_char and e['end'] <= sent.end_char
                    ]

                    claims.append({
                        'text': sent_text,
                        'type': 'statement',
                        'entities': sent_entities
                    })

            # If no claims extracted, treat entire text as one claim
            if not claims:
                logger.debug("No sentences found, using entire text as claim")
                claims.append({
                    'text': text.strip(),
                    'type': 'statement',
                    'entities': entities
                })

            logger.info(f"Extracted {len(claims)} claim(s)")
            return claims
        except Exception as e:
            logger.exception("Error extracting claims")
            # Return fallback claim
            return [{
                'text': text.strip(),
                'type': 'statement',
                'entities': []
            }]


class FactsDatabase:
    """
    Manages the verified facts database and vector store.
    Handles loading, embedding, and persistence.
    """

    DEFAULT_CSV_PATH = "verified_facts_db.csv"
    DEFAULT_INDEX_PATH = "faiss_index_facts"
    EMBEDDING_MODEL = "BAAI/bge-base-en-v1.5"

    def __init__(self, api_key: str = None):
        """
        Initialize the FactsDatabase.

        Args:
            api_key: Together AI API key (optional, can use get_together_api_key)
        """
        logger.info("Initializing FactsDatabase")
        self.api_key = api_key or get_together_api_key()

        try:
            self.embeddings = TogetherEmbeddings(
                model=self.EMBEDDING_MODEL,
                api_key=self.api_key
            )
            logger.info(f"Embeddings initialized with model: {self.EMBEDDING_MODEL}")

            # Initialize ClaimExtractor for entity extraction from facts
            self.claim_extractor = ClaimExtractor()
            logger.info("ClaimExtractor initialized for database entity extraction")

        except Exception as e:
            logger.exception("Error initializing embeddings")
            raise

    def load_from_csv(
        self,
        csv_path: str = None,
        index_path: str = None
    ) -> str:
        """
        Load verified facts from CSV and create FAISS vector store.

        Args:
            csv_path: Path to verified facts CSV file
            index_path: Path to save FAISS index

        Returns:
            Status message with count of loaded facts
        """
        csv_path = csv_path or self.DEFAULT_CSV_PATH
        index_path = index_path or self.DEFAULT_INDEX_PATH

        try:
            logger.info(f"Loading facts from CSV: {csv_path}")
            # Read verified facts
            df = pd.read_csv(csv_path)
            logger.info(f"Loaded {len(df)} rows from CSV")

            # Handle different CSV formats
            if 'fact_text' in df.columns:
                fact_column = 'fact_text'
                logger.debug("Using 'fact_text' column")
            elif 'fact' in df.columns:
                fact_column = 'fact'
                logger.debug("Using 'fact' column")
            else:
                error_msg = "CSV must contain a 'fact' or 'fact_text' column"
                logger.error(error_msg)
                raise ValueError(error_msg)

            # Create documents with metadata
            logger.info("Creating documents with metadata")
            documents = self._create_documents(df, fact_column)
            logger.info(f"Created {len(documents)} documents")

            # Create FAISS index
            logger.info("Creating FAISS vector index...")
            vector_store = FAISS.from_documents(documents, self.embeddings)
            logger.info("FAISS index created successfully")

            # Save to disk
            logger.info(f"Saving FAISS index to: {index_path}")
            vector_store.save_local(index_path)
            logger.info("FAISS index saved successfully")

            return f"✅ Successfully loaded {len(documents)} verified facts into vector store"

        except FileNotFoundError:
            raise FileNotFoundError(f"Verified facts CSV not found at: {csv_path}")
        except Exception as e:
            raise RuntimeError(f"Error loading verified facts: {str(e)}")

    def _create_documents(
        self,
        df: pd.DataFrame,
        fact_column: str
    ) -> List[LangchainDocument]:
        """
        Create LangChain documents from DataFrame with entity extraction.

        Args:
            df: Pandas DataFrame with facts
            fact_column: Name of the column containing fact text

        Returns:
            List of LangChain documents with metadata including extracted entities
        """
        try:
            documents = []
            multi_sentence_count = 0
            pronoun_count = 0

            for idx, row in df.iterrows():
                fact_text = row[fact_column]

                # Extract fact_id if available
                if 'fact_id' in df.columns:
                    fact_id = row['fact_id']
                else:
                    fact_id = f"F{idx:03d}"

                # DATA VALIDATION: Check for multi-sentence facts
                sentences = fact_text.split('.')
                if len([s for s in sentences if s.strip()]) > 1:
                    multi_sentence_count += 1
                    logger.warning(
                        f"Fact {fact_id} contains multiple sentences ({len(sentences)} sentences). "
                        f"Consider splitting for better retrieval: {fact_text[:80]}..."
                    )

                # DATA VALIDATION: Check for unresolved pronouns
                pronouns = ['he ', 'she ', 'it ', 'they ', 'them ', 'his ', 'her ', 'their ']
                if any(pronoun in fact_text.lower() for pronoun in pronouns):
                    pronoun_count += 1
                    logger.warning(
                        f"Fact {fact_id} contains pronouns - may cause coreference issues: {fact_text[:80]}..."
                    )

                # ENTITY EXTRACTION: Extract entities from fact text
                entities = []
                entities_dict = {}
                try:
                    claims = self.claim_extractor.extract_claims(fact_text)
                    if claims and len(claims) > 0:
                        entities = claims[0].get('entities', [])
                        # Convert entities list to dict for easier access
                        entities_dict = {
                            'organizations': [e['text'] for e in entities if e['type'] in ['ORG', 'ORGANIZATION']],
                            'locations': [e['text'] for e in entities if e['type'] in ['GPE', 'LOC', 'LOCATION']],
                            'persons': [e['text'] for e in entities if e['type'] in ['PERSON', 'PER']],
                            'dates': [e['text'] for e in entities if e['type'] == 'DATE'],
                            'percentages': [e['text'] for e in entities if e['type'] in ['PERCENT', 'PERCENTAGE']],
                            'money': [e['text'] for e in entities if e['type'] in ['MONEY', 'CURRENCY']],
                            'all_entities': [e['text'] for e in entities]
                        }
                        logger.debug(f"Fact {fact_id}: Extracted {len(entities)} entities")
                except Exception as e:
                    logger.warning(f"Failed to extract entities from fact {fact_id}: {str(e)}")

                # Create metadata with entities
                metadata = {
                    'source': row.get('source', 'Verified Database'),
                    'date': row.get('date', 'N/A'),
                    'category': row.get('category', 'General'),
                    'fact_id': fact_id,
                    'entities': entities,  # Full entity list with types
                    'entities_dict': entities_dict  # Organized by type for easy filtering
                }

                # Create LangChain document with metadata
                doc = LangchainDocument(
                    page_content=fact_text,
                    metadata=metadata
                )
                documents.append(doc)

            # Summary logging
            logger.info(f"Created {len(documents)} documents from DataFrame")
            if multi_sentence_count > 0:
                logger.warning(
                    f"⚠️  {multi_sentence_count}/{len(documents)} facts contain multiple sentences. "
                    f"Consider atomic splitting for better granularity."
                )
            if pronoun_count > 0:
                logger.warning(
                    f"⚠️  {pronoun_count}/{len(documents)} facts contain pronouns. "
                    f"Consider coreference resolution."
                )

            # Log entity extraction statistics
            total_entities = sum(len(doc.metadata.get('entities', [])) for doc in documents)
            avg_entities = total_entities / len(documents) if documents else 0
            logger.info(
                f"Entity extraction complete: {total_entities} total entities "
                f"({avg_entities:.1f} avg per fact)"
            )

            return documents
        except Exception as e:
            logger.exception("Error creating documents from DataFrame")
            raise


class FactRetriever:
    """
    Retrieves similar facts from the vector store using semantic search.
    Implements retrieval strategies and similarity scoring.
    """

    DEFAULT_INDEX_PATH = "faiss_index_facts"
    EMBEDDING_MODEL = "BAAI/bge-base-en-v1.5"

    def __init__(self, api_key: str = None, index_path: str = None):
        """
        Initialize the FactRetriever.

        Args:
            api_key: Together AI API key
            index_path: Path to FAISS index
        """
        self.api_key = api_key or get_together_api_key()
        self.index_path = index_path or self.DEFAULT_INDEX_PATH
        logger.info(f"Initializing FactRetriever with index path: {self.index_path}")

        try:
            self.embeddings = TogetherEmbeddings(
                model=self.EMBEDDING_MODEL,
                api_key=self.api_key
            )
            logger.info(f"Embeddings model initialized: {self.EMBEDDING_MODEL}")
        except Exception as e:
            logger.exception("Error initializing embeddings model")
            raise

        self._vector_store = None

    @property
    def vector_store(self):
        """Lazy load vector store to avoid unnecessary I/O."""
        if self._vector_store is None:
            try:
                logger.info(f"Loading FAISS index from: {self.index_path}")
                self._vector_store = FAISS.load_local(
                    self.index_path,
                    self.embeddings,
                    allow_dangerous_deserialization=True
                )
                logger.info("FAISS index loaded successfully")
            except FileNotFoundError:
                error_msg = f"FAISS index not found at: {self.index_path}. Please initialize the database first."
                logger.error(error_msg)
                raise FileNotFoundError(error_msg)
            except Exception as e:
                logger.exception("Error loading FAISS index")
                raise RuntimeError(f"Error loading FAISS index: {str(e)}")
        return self._vector_store

    def retrieve(
        self,
        claim: str,
        top_k: int = 3,
        similarity_threshold: float = 0.0
    ) -> List[Dict[str, Any]]:
        """
        Retrieve most similar verified facts for a given claim.

        Args:
            claim: The claim text to verify
            top_k: Number of similar facts to retrieve
            similarity_threshold: Minimum similarity score (0-1)

        Returns:
            List of dictionaries with 'fact', 'metadata', and 'similarity'
        """
        try:
            logger.info(f"Retrieving top-{top_k} facts for claim: {claim[:100]}...")

            # Perform similarity search with scores
            docs_with_scores = self.vector_store.similarity_search_with_score(
                claim, k=top_k
            )
            logger.debug(f"Retrieved {len(docs_with_scores)} documents from FAISS")

            # Format and filter results
            similar_facts = []
            for doc, score in docs_with_scores:
                # FAISS returns distance, convert to similarity
                similarity = self._normalize_similarity(score)

                if similarity >= similarity_threshold:
                    similar_facts.append({
                        'fact': doc.page_content,
                        'metadata': doc.metadata,
                        'similarity': round(similarity, 3)
                    })
                    logger.debug(f"Fact similarity: {similarity:.3f} - {doc.page_content[:50]}...")

            logger.info(f"Filtered to {len(similar_facts)} facts above threshold {similarity_threshold}")
            return similar_facts

        except Exception as e:
            logger.exception("Error retrieving similar facts")
            raise RuntimeError(f"Error retrieving similar facts: {str(e)}")

    @staticmethod
    def _normalize_similarity(distance: float) -> float:
        """
        Convert FAISS distance to similarity score (0-1 range).

        Args:
            distance: FAISS distance score (lower = more similar)

        Returns:
            Normalized similarity score
        """
        return 1 / (1 + distance)


class ClaimClassifier:
    """
    Uses LLM to classify claims as True/False/Unverifiable.
    Handles prompt engineering and response parsing.
    """

    LLM_MODEL = "meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo"
    TEMPERATURE = 0.3

    # Verdict constants
    VERDICT_TRUE = "Likely True"
    VERDICT_FALSE = "Likely False"
    VERDICT_UNVERIFIABLE = "Unverifiable"

    def __init__(self, api_key: str = None):
        """
        Initialize the ClaimClassifier.

        Args:
            api_key: Together AI API key
        """
        self.api_key = api_key or get_together_api_key()
        logger.info(f"Initializing ClaimClassifier with model: {self.LLM_MODEL}")

        try:
            self.llm = ChatTogether(
                model=self.LLM_MODEL,
                temperature=self.TEMPERATURE,
                api_key=self.api_key
            )
            logger.info(f"LLM initialized successfully (temperature={self.TEMPERATURE})")
        except Exception as e:
            logger.exception("Error initializing LLM")
            raise

    def classify(
        self,
        claim: str,
        retrieved_facts: List[Dict[str, Any]]
    ) -> Dict[str, Any]:
        """
        Classify a claim against retrieved facts using LLM.

        Args:
            claim: The original claim to verify
            retrieved_facts: List of similar facts with metadata

        Returns:
            Dictionary with 'verdict', 'confidence', 'reasoning', 'evidence_used'
        """
        logger.info(f"Classifying claim with {len(retrieved_facts)} retrieved facts")

        # Build prompt with evidence
        prompt = self._build_prompt(claim, retrieved_facts)
        logger.debug(f"Built prompt with {len(prompt)} characters")

        try:
            # Get LLM response
            logger.info("Invoking LLM for claim classification")
            response = self.llm.invoke([{"role": "user", "content": prompt}])
            response_text = response.content.strip()
            logger.debug(f"LLM response received ({len(response_text)} chars)")

            # Parse JSON response
            result = self._parse_response(response_text)
            logger.info(f"Classification result: {result['verdict']} (confidence: {result['confidence']})")

            # Add retrieved facts as evidence details
            result['evidence_details'] = retrieved_facts

            return result

        except json.JSONDecodeError as e:
            logger.error(f"JSON parsing failed: {str(e)}")
            return self._fallback_response(retrieved_facts, "JSON parsing failed")
        except Exception as e:
            logger.exception("Error during claim classification")
            return self._fallback_response(retrieved_facts, str(e))

    def _build_prompt(
        self,
        claim: str,
        retrieved_facts: List[Dict[str, Any]]
    ) -> str:
        """
        Build the classification prompt for the LLM.

        Args:
            claim: The claim to verify
            retrieved_facts: Retrieved evidence

        Returns:
            Formatted prompt string
        """
        # Format evidence
        evidence_text = self._format_evidence(retrieved_facts)

        # Construct prompt
        prompt = f"""You are a fact-checking assistant. Your task is to verify the following claim against verified evidence.

CLAIM TO VERIFY:
"{claim}"

VERIFIED EVIDENCE FROM DATABASE:
{evidence_text}

INSTRUCTIONS:
1. Compare the claim against the verified evidence carefully
2. Classify the claim as one of:
   - "{self.VERDICT_TRUE}" - if evidence strongly supports the claim
   - "{self.VERDICT_FALSE}" - if evidence contradicts the claim
   - "{self.VERDICT_UNVERIFIABLE}" - if insufficient or conflicting evidence

3. Provide your analysis in EXACTLY this JSON format (no additional text):
{{
  "verdict": "{self.VERDICT_TRUE}" | "{self.VERDICT_FALSE}" | "{self.VERDICT_UNVERIFIABLE}",
  "confidence": "high" | "medium" | "low",
  "reasoning": "Explain your decision in 2-3 sentences",
  "evidence_used": ["fact 1", "fact 2"]
}}

IMPORTANT:
- Be objective and base your verdict only on the evidence provided
- If the evidence is vague or irrelevant, mark as "{self.VERDICT_UNVERIFIABLE}"
- Consider dates, entities, and specific details when comparing
- Return ONLY the JSON object, no other text

YOUR RESPONSE:"""

        return prompt

    def _format_evidence(self, retrieved_facts: List[Dict[str, Any]]) -> str:
        """
        Format retrieved facts for the prompt.

        Args:
            retrieved_facts: List of facts with metadata

        Returns:
            Formatted evidence string
        """
        if not retrieved_facts:
            return "No similar verified facts found in the database."

        evidence_lines = []
        for i, fact in enumerate(retrieved_facts, 1):
            lines = [
                f"Evidence {i}:",
                f"{fact['fact']}",
                f"Source: {fact['metadata'].get('source', 'Unknown')}",
                f"Date: {fact['metadata'].get('date', 'Unknown')}",
                f"Similarity: {fact['similarity']:.2f}"
            ]
            evidence_lines.append("\n".join(lines))

        return "\n\n".join(evidence_lines)

    def _parse_response(self, response_text: str) -> Dict[str, Any]:
        """
        Parse LLM JSON response.

        Args:
            response_text: Raw LLM response

        Returns:
            Parsed result dictionary
        """
        try:
            # Try to extract JSON if LLM added extra text
            json_match = re.search(r'\{.*\}', response_text, re.DOTALL)
            if json_match:
                response_text = json_match.group(0)
                logger.debug("Extracted JSON from LLM response")

            result = json.loads(response_text)
            logger.debug("Successfully parsed JSON response")

            # Validate required fields
            required_fields = ['verdict', 'confidence', 'reasoning', 'evidence_used']
            missing_fields = [field for field in required_fields if field not in result]

            if missing_fields:
                logger.warning(f"Missing fields in LLM response: {missing_fields}")
                for field in missing_fields:
                    result[field] = "Unknown" if field != 'evidence_used' else []

            return result
        except Exception as e:
            logger.exception("Error parsing LLM response")
            raise

    def _fallback_response(
        self,
        retrieved_facts: List[Dict[str, Any]],
        error_msg: str
    ) -> Dict[str, Any]:
        """
        Create fallback response on error.

        Args:
            retrieved_facts: Retrieved evidence
            error_msg: Error message

        Returns:
            Fallback response dictionary
        """
        logger.warning(f"Creating fallback response due to: {error_msg}")
        return {
            'verdict': self.VERDICT_UNVERIFIABLE,
            'confidence': 'low',
            'reasoning': f'Error during fact-checking: {error_msg}',
            'evidence_used': [],
            'evidence_details': retrieved_facts,
            'error': error_msg
        }


class FactChecker:
    """
    Main orchestrator for the fact-checking pipeline.
    Coordinates ClaimExtractor, FactRetriever, and ClaimClassifier.
    Follows Facade pattern to provide simple interface.
    """

    def __init__(self, api_key: str = None):
        """
        Initialize the FactChecker with all required components.

        Args:
            api_key: Together AI API key
        """
        logger.info("Initializing FactChecker pipeline")
        self.api_key = api_key or get_together_api_key()

        try:
            # Initialize components (Dependency Injection)
            logger.debug("Initializing ClaimExtractor")
            self.claim_extractor = ClaimExtractor()

            logger.debug("Initializing FactRetriever")
            self.fact_retriever = FactRetriever(api_key=self.api_key)

            logger.debug("Initializing ClaimClassifier")
            self.claim_classifier = ClaimClassifier(api_key=self.api_key)

            logger.info("FactChecker initialization complete")
        except Exception as e:
            logger.exception("Error initializing FactChecker")
            raise

    def check_claim(self, user_claim: str, top_k: int = 3) -> Dict[str, Any]:
        """
        Main fact-checking pipeline that orchestrates the entire process.

        Args:
            user_claim: User's input claim/statement to verify
            top_k: Number of similar facts to retrieve

        Returns:
            Complete fact-check result with verdict, evidence, and reasoning
        """
        logger.info("=" * 60)
        logger.info(f"Starting fact-check pipeline for claim: {user_claim[:100]}...")
        logger.info("=" * 60)

        try:
            # Step 1: Extract claims from input
            logger.info("Step 1: Extracting claims from input")
            claims = self.claim_extractor.extract_claims(user_claim)

            # For simplicity, fact-check the first/main claim
            main_claim = claims[0]['text'] if claims else user_claim
            logger.info(f"Main claim identified: {main_claim[:100]}...")

            # Step 2: Retrieve similar facts
            logger.info(f"Step 2: Retrieving top-{top_k} similar facts")
            similar_facts = self.fact_retriever.retrieve(main_claim, top_k=top_k)
            logger.info(f"Retrieved {len(similar_facts)} similar facts")

            # Step 3: Classify using LLM
            logger.info("Step 3: Classifying claim using LLM")
            result = self.claim_classifier.classify(main_claim, similar_facts)

            # Step 4: Add metadata
            logger.info("Step 4: Adding metadata to result")
            result['original_input'] = user_claim
            result['extracted_claim'] = main_claim
            result['entities_found'] = claims[0].get('entities', []) if claims else []
            result['total_claims_extracted'] = len(claims)

            logger.info(f"Fact-check complete: {result['verdict']}")
            logger.info("=" * 60)
            return result

        except Exception as e:
            logger.exception("Error in fact-checking pipeline")
            logger.info("=" * 60)
            return self._error_response(user_claim, str(e))

    def _error_response(self, user_claim: str, error_msg: str) -> Dict[str, Any]:
        """
        Create error response when pipeline fails.

        Args:
            user_claim: Original user claim
            error_msg: Error message

        Returns:
            Error response dictionary
        """
        logger.error(f"Creating error response for claim: {error_msg}")
        return {
            'verdict': 'Unverifiable',
            'confidence': 'low',
            'reasoning': f'Error during fact-checking pipeline: {error_msg}',
            'evidence_used': [],
            'evidence_details': [],
            'original_input': user_claim,
            'extracted_claim': user_claim,
            'entities_found': [],
            'error': error_msg
        }


# ========================================================================
# LEGACY FUNCTION WRAPPERS (for backward compatibility)
# ========================================================================

def load_verified_facts(csv_path: str = "verified_facts_db.csv") -> str:
    """
    Legacy wrapper for backward compatibility.
    Uses FactsDatabase class internally.

    Args:
        csv_path: Path to verified facts CSV file

    Returns:
        Status message
    """
    db = FactsDatabase()
    return db.load_from_csv(csv_path)


def retrieve_similar_facts(
    claim: str,
    top_k: int = 3,
    similarity_threshold: float = 0.0
) -> List[Dict[str, Any]]:
    """
    Legacy wrapper for backward compatibility.
    Uses FactRetriever class internally.

    Args:
        claim: The claim text to verify
        top_k: Number of similar facts to retrieve
        similarity_threshold: Minimum similarity score (0-1)

    Returns:
        List of dictionaries with 'fact', 'metadata', and 'similarity'
    """
    retriever = FactRetriever()
    return retriever.retrieve(claim, top_k, similarity_threshold)


def classify_claim(claim: str, retrieved_facts: List[Dict[str, Any]]) -> Dict[str, Any]:
    """
    Legacy wrapper for backward compatibility.
    Uses ClaimClassifier class internally.

    Args:
        claim: The original claim to verify
        retrieved_facts: List of similar facts with metadata

    Returns:
        Dictionary with 'verdict', 'confidence', 'reasoning', 'evidence_used'
    """
    classifier = ClaimClassifier()
    return classifier.classify(claim, retrieved_facts)


def fact_check_claim(user_claim: str, top_k: int = 3) -> Dict[str, Any]:
    """
    Legacy wrapper for backward compatibility.
    Uses FactChecker class internally.

    Args:
        user_claim: User's input claim/statement to verify
        top_k: Number of similar facts to retrieve

    Returns:
        Complete fact-check result with verdict, evidence, and reasoning
    """
    checker = FactChecker()
    return checker.check_claim(user_claim, top_k)