Upload 20 files

Dockerfile

@@ -0,0 +1,38 @@
+# Dockerfile for FinAgent Backend - Hugging Face Spaces Deployment
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create directories for runtime data
+RUN mkdir -p sanctions logs
+
+# Expose port (Hugging Face uses 7860)
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:7860/health || exit 1
+
+# Run the application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

app/__init__.py

@@ -0,0 +1,8 @@
+"""
+FinAgent - Chat2Sanction Backend Application
+AI-powered loan processing platform with conversational interface.
+"""
+
+__version__ = "1.0.0"
+__author__ = "FinAgent Team"
+__description__ = "AI-powered loan processing platform"

app/agents/__init__.py

@@ -0,0 +1,23 @@
+"""
+Agents module for LangChain-based conversational AI.
+Contains the master agent and tool definitions.
+"""
+
+from app.agents.master_agent import MasterAgent, master_agent
+from app.agents.tools import (
+    all_tools,
+    create_loan_application_tool,
+    fetch_user_profile_tool,
+    generate_sanction_letter_tool,
+    run_underwriting_tool,
+)
+
+__all__ = [
+    "master_agent",
+    "MasterAgent",
+    "all_tools",
+    "fetch_user_profile_tool",
+    "run_underwriting_tool",
+    "generate_sanction_letter_tool",
+    "create_loan_application_tool",
+]

app/agents/master_agent.py

@@ -0,0 +1,276 @@
+"""
+Master agent using LangChain with Gemini LLM.
+Orchestrates loan processing conversation and tool calls.
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+
+from app.agents.tools import all_tools
+from app.config import settings
+from app.utils.logger import default_logger as logger
+from langchain.agents import AgentExecutor, create_react_agent
+from langchain.memory import ConversationBufferMemory
+from langchain.prompts import PromptTemplate
+from langchain_google_genai import ChatGoogleGenerativeAI
+
+
+class MasterAgent:
+    """Master conversational agent for loan processing."""
+
+    def __init__(self):
+        """Initialize the master agent with Gemini LLM and tools."""
+        self.llm = self._initialize_llm()
+        self.tools = all_tools
+        self.memory_store: Dict[str, ConversationBufferMemory] = {}
+        self.agent_executor = None
+        self._initialize_agent()
+
+    def _initialize_llm(self) -> ChatGoogleGenerativeAI:
+        """
+        Initialize Gemini LLM.
+
+        Returns:
+            ChatGoogleGenerativeAI instance
+        """
+        try:
+            llm = ChatGoogleGenerativeAI(
+                model=settings.GEMINI_MODEL,
+                temperature=settings.GEMINI_TEMPERATURE,
+                google_api_key=settings.GOOGLE_API_KEY,
+                convert_system_message_to_human=True,
+            )
+            logger.info(f"Initialized Gemini LLM: {settings.GEMINI_MODEL}")
+            return llm
+        except Exception as e:
+            logger.error(f"Failed to initialize Gemini LLM: {str(e)}")
+            raise
+
+    def _initialize_agent(self) -> None:
+        """Initialize the ReAct agent with tools."""
+        try:
+            # Create the prompt template
+            template = """You are FinAgent, an AI-powered loan processing assistant for personal loans.
+
+Your role is to help users get instant personal loan approvals through a conversational interface.
+
+IMPORTANT GUIDELINES:
+1. Be friendly, professional, and conversational
+2. Guide users through the loan application process step by step
+3. Use the available tools to fetch user data, evaluate eligibility, and generate sanction letters
+4. Always explain decisions clearly in simple language
+5. Never expose technical details or raw tool outputs to users
+6. Format monetary values in Indian Rupees (₹) with proper formatting
+7. Be empathetic when delivering rejection decisions and suggest improvements
+
+CONVERSATION FLOW:
+1. Greet the user warmly and understand their loan requirement
+2. Ask for loan amount and tenure if not provided
+3. Use fetch_user_profile tool to get user's financial data
+4. Use run_underwriting tool to evaluate loan eligibility
+5. Explain the decision clearly with key details (amount, EMI, tenure, interest rate)
+6. If approved, use generate_sanction_letter tool to create the sanction letter
+7. Provide the loan_id and next steps to the user
+
+DECISION EXPLANATION:
+- APPROVED: Congratulate the user, explain the approved amount, EMI, tenure, and risk band
+- ADJUST: Explain why adjustment is needed and what the new terms are
+- REJECTED: Be empathetic, explain the reasons (credit score, FOIR), and suggest improvements
+
+AVAILABLE TOOLS:
+{tools}
+
+TOOL NAMES: {tool_names}
+
+When using tools, follow this format:
+Thought: [Your reasoning about what to do next]
+Action: [Tool name from {tool_names}]
+Action Input: [Input for the tool]
+Observation: [Tool output]
+... (repeat Thought/Action/Action Input/Observation as needed)
+Thought: I now know the final answer
+Final Answer: [Your response to the user in natural, friendly language]
+
+Current conversation:
+{chat_history}
+
+User: {input}
+
+{agent_scratchpad}"""
+
+            prompt = PromptTemplate(
+                input_variables=[
+                    "input",
+                    "chat_history",
+                    "agent_scratchpad",
+                    "tools",
+                    "tool_names",
+                ],
+                template=template,
+            )
+
+            # Create the agent
+            agent = create_react_agent(self.llm, self.tools, prompt)
+
+            # Create agent executor
+            self.agent_executor = AgentExecutor(
+                agent=agent,
+                tools=self.tools,
+                verbose=True,
+                handle_parsing_errors=True,
+                max_iterations=10,
+            )
+
+            logger.info("Master agent initialized successfully")
+
+        except Exception as e:
+            logger.error(f"Failed to initialize agent: {str(e)}")
+            raise
+
+    def get_or_create_memory(self, session_id: str) -> ConversationBufferMemory:
+        """
+        Get or create conversation memory for a session.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            ConversationBufferMemory instance
+        """
+        if session_id not in self.memory_store:
+            self.memory_store[session_id] = ConversationBufferMemory(
+                memory_key="chat_history",
+                return_messages=False,
+                input_key="input",
+            )
+            logger.info(f"Created new memory for session {session_id}")
+
+        return self.memory_store[session_id]
+
+    def chat(self, session_id: str, user_id: str, message: str) -> Dict[str, Any]:
+        """
+        Process a chat message and return response.
+
+        Args:
+            session_id: Session ID
+            user_id: User ID
+            message: User message
+
+        Returns:
+            Dictionary with reply, decision, loan_id, and metadata
+        """
+        try:
+            logger.info(f"Processing chat for session {session_id}, user {user_id}")
+
+            # Get conversation memory
+            memory = self.get_or_create_memory(session_id)
+
+            # Prepare input with user context
+            agent_input = {
+                "input": f"[User ID: {user_id}] {message}",
+                "chat_history": memory.load_memory_variables({}).get(
+                    "chat_history", ""
+                ),
+            }
+
+            # Run agent
+            result = self.agent_executor.invoke(agent_input)
+
+            # Extract response
+            response_text = result.get(
+                "output",
+                "I apologize, but I encountered an issue processing your request.",
+            )
+
+            # Save to memory
+            memory.save_context({"input": message}, {"output": response_text})
+
+            # Parse response for structured data
+            parsed_data = self._parse_response(response_text)
+
+            return {
+                "reply": response_text,
+                "decision": parsed_data.get("decision"),
+                "loan_id": parsed_data.get("loan_id"),
+                "meta": parsed_data.get("meta"),
+            }
+
+        except Exception as e:
+            logger.error(f"Error in chat processing: {str(e)}")
+            return {
+                "reply": "I apologize, but I encountered an error processing your request. Please try again.",
+                "decision": None,
+                "loan_id": None,
+                "meta": {"error": str(e)},
+            }
+
+    def _parse_response(self, response_text: str) -> Dict[str, Any]:
+        """
+        Parse agent response to extract structured data.
+
+        Args:
+            response_text: Agent response text
+
+        Returns:
+            Dictionary with parsed data
+        """
+        parsed = {
+            "decision": None,
+            "loan_id": None,
+            "meta": {},
+        }
+
+        # Look for decision keywords
+        if "approved" in response_text.lower():
+            if (
+                "adjustment" in response_text.lower()
+                or "adjust" in response_text.lower()
+            ):
+                parsed["decision"] = "ADJUST"
+            else:
+                parsed["decision"] = "APPROVED"
+        elif (
+            "rejected" in response_text.lower()
+            or "cannot approve" in response_text.lower()
+        ):
+            parsed["decision"] = "REJECTED"
+
+        # Look for loan ID pattern
+        import re
+
+        loan_id_match = re.search(
+            r"loan[_\s]?id[:\s]+([a-zA-Z0-9\-]+)", response_text, re.IGNORECASE
+        )
+        if loan_id_match:
+            parsed["loan_id"] = loan_id_match.group(1)
+
+        # Look for EMI amount
+        emi_match = re.search(
+            r"₹\s?([\d,]+(?:\.\d{2})?)\s*(?:per month|monthly|emi)",
+            response_text,
+            re.IGNORECASE,
+        )
+        if emi_match:
+            parsed["meta"]["emi"] = emi_match.group(1)
+
+        return parsed
+
+    def clear_session_memory(self, session_id: str) -> bool:
+        """
+        Clear conversation memory for a session.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            True if cleared, False if not found
+        """
+        if session_id in self.memory_store:
+            del self.memory_store[session_id]
+            logger.info(f"Cleared memory for session {session_id}")
+            return True
+        return False
+
+
+# Singleton instance
+master_agent = MasterAgent()

app/agents/tools.py

@@ -0,0 +1,247 @@
+"""
+LangChain tools for the master agent.
+Defines tool functions that the agent can call to interact with services.
+"""
+
+import json
+from typing import Any, Dict
+
+from app.services.firebase_service import firebase_service
+from app.services.pdf_service import pdf_service
+from app.services.underwriting_service import underwriting_service
+from app.utils.logger import default_logger as logger
+from langchain.tools import Tool
+
+
+def fetch_user_profile_tool_func(user_id: str) -> str:
+    """
+    Fetch user profile from Firebase.
+
+    Args:
+        user_id: User ID to fetch
+
+    Returns:
+        JSON string with user profile or error message
+    """
+    try:
+        logger.info(f"Tool: Fetching user profile for {user_id}")
+
+        profile = firebase_service.get_user_profile(user_id)
+
+        if not profile:
+            return json.dumps({"success": False, "error": "User profile not found"})
+
+        # Return relevant profile information
+        result = {
+            "success": True,
+            "user_id": profile.get("user_id"),
+            "full_name": profile.get("full_name"),
+            "monthly_income": profile.get("monthly_income"),
+            "existing_emi": profile.get("existing_emi"),
+            "credit_score": profile.get("mock_credit_score"),
+            "segment": profile.get("segment"),
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error in fetch_user_profile_tool: {str(e)}")
+        return json.dumps({"success": False, "error": str(e)})
+
+
+def run_underwriting_tool_func(payload: str) -> str:
+    """
+    Run underwriting evaluation for a loan application.
+
+    Args:
+        payload: JSON string with user_id, requested_amount, and requested_tenure_months
+
+    Returns:
+        JSON string with underwriting decision
+    """
+    try:
+        logger.info(f"Tool: Running underwriting")
+
+        # Parse payload
+        data = json.loads(payload)
+        user_id = data.get("user_id")
+        requested_amount = float(data.get("requested_amount", 0))
+        requested_tenure = int(data.get("requested_tenure_months", 0))
+
+        # Fetch user profile
+        user_profile = firebase_service.get_user_profile(user_id)
+
+        if not user_profile:
+            return json.dumps({"success": False, "error": "User profile not found"})
+
+        # Run underwriting
+        decision = underwriting_service.evaluate_application(
+            user_profile, requested_amount, requested_tenure
+        )
+
+        result = {
+            "success": True,
+            "decision": decision["decision"],
+            "approved_amount": decision["approved_amount"],
+            "tenure_months": decision["tenure_months"],
+            "emi": decision["emi"],
+            "interest_rate": decision["interest_rate"],
+            "credit_score": decision["credit_score"],
+            "foir": decision["foir"],
+            "risk_band": decision["risk_band"],
+            "explanation": decision["explanation"],
+            "total_payable": decision.get("total_payable", 0),
+            "processing_fee": decision.get("processing_fee", 0),
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error in run_underwriting_tool: {str(e)}")
+        return json.dumps({"success": False, "error": str(e)})
+
+
+def generate_sanction_letter_tool_func(payload: str) -> str:
+    """
+    Generate sanction letter PDF for approved loan.
+
+    Args:
+        payload: JSON string with loan application data
+
+    Returns:
+        JSON string with PDF path and URL
+    """
+    try:
+        logger.info(f"Tool: Generating sanction letter")
+
+        # Parse payload
+        loan_data = json.loads(payload)
+
+        # Validate that loan is approved
+        decision = loan_data.get("decision")
+        if decision not in ["APPROVED", "ADJUST"]:
+            return json.dumps(
+                {
+                    "success": False,
+                    "error": "Cannot generate sanction letter for rejected loans",
+                }
+            )
+
+        # Create loan application record in Firebase
+        loan_record = firebase_service.create_loan_application(loan_data)
+        loan_id = loan_record.get("loan_id")
+
+        # Generate PDF
+        pdf_result = pdf_service.generate_sanction_letter(loan_record)
+
+        # Update loan record with PDF path
+        firebase_service.update_loan_application(
+            loan_id,
+            {
+                "sanction_pdf_path": pdf_result["pdf_path"],
+                "sanction_pdf_url": pdf_result["pdf_url"],
+            },
+        )
+
+        result = {
+            "success": True,
+            "loan_id": loan_id,
+            "pdf_path": pdf_result["pdf_path"],
+            "pdf_url": pdf_result["pdf_url"],
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error in generate_sanction_letter_tool: {str(e)}")
+        return json.dumps({"success": False, "error": str(e)})
+
+
+def create_loan_application_tool_func(payload: str) -> str:
+    """
+    Create a loan application record in Firebase.
+
+    Args:
+        payload: JSON string with loan application data
+
+    Returns:
+        JSON string with created loan application
+    """
+    try:
+        logger.info(f"Tool: Creating loan application")
+
+        # Parse payload
+        loan_data = json.loads(payload)
+
+        # Create loan application
+        loan_record = firebase_service.create_loan_application(loan_data)
+
+        result = {
+            "success": True,
+            "loan_id": loan_record.get("loan_id"),
+            "user_id": loan_record.get("user_id"),
+            "decision": loan_record.get("decision"),
+            "approved_amount": loan_record.get("approved_amount"),
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error in create_loan_application_tool: {str(e)}")
+        return json.dumps({"success": False, "error": str(e)})
+
+
+# Define LangChain tools
+fetch_user_profile_tool = Tool(
+    name="fetch_user_profile",
+    func=fetch_user_profile_tool_func,
+    description="""
+    Fetch user profile information from the database.
+    Input should be a user_id string.
+    Returns JSON with user's full_name, monthly_income, existing_emi, credit_score, and segment.
+    Use this tool to get user information before processing loan applications.
+    """,
+)
+
+run_underwriting_tool = Tool(
+    name="run_underwriting",
+    func=run_underwriting_tool_func,
+    description="""
+    Run underwriting evaluation for a loan application.
+    Input should be a JSON string with keys: user_id, requested_amount, requested_tenure_months.
+    Example: {"user_id": "123", "requested_amount": 500000, "requested_tenure_months": 36}
+    Returns JSON with decision (APPROVED/REJECTED/ADJUST), approved_amount, emi, interest_rate, foir, risk_band, and explanation.
+    Use this tool after getting user profile to evaluate loan eligibility.
+    """,
+)
+
+generate_sanction_letter_tool = Tool(
+    name="generate_sanction_letter",
+    func=generate_sanction_letter_tool_func,
+    description="""
+    Generate a sanction letter PDF for an approved loan application.
+    Input should be a JSON string with complete loan application data including:
+    user_id, full_name, decision, approved_amount, tenure_months, emi, interest_rate, credit_score, foir, risk_band, explanation.
+    Returns JSON with loan_id, pdf_path, and pdf_url.
+    Use this tool only after underwriting approval (APPROVED or ADJUST decision).
+    """,
+)
+
+create_loan_application_tool = Tool(
+    name="create_loan_application",
+    func=create_loan_application_tool_func,
+    description="""
+    Create a loan application record in the database without generating PDF.
+    Input should be a JSON string with loan application data.
+    Returns JSON with loan_id and basic loan information.
+    Use this tool to save loan application data for rejected or pending applications.
+    """,
+)
+
+# List of all tools
+all_tools = [
+    fetch_user_profile_tool,
+    run_underwriting_tool,
+    generate_sanction_letter_tool,
+    create_loan_application_tool,
+]

app/config.py

@@ -0,0 +1,85 @@
+"""
+Configuration module for FinAgent backend.
+Handles environment variables and service initialization.
+"""
+
+import os
+from functools import lru_cache
+from typing import List
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    # API Configuration
+    APP_NAME: str = "FinAgent - Chat2Sanction API"
+    APP_VERSION: str = "1.0.0"
+    DEBUG: bool = True
+
+    # Gemini AI Configuration
+    GOOGLE_API_KEY: str
+    GEMINI_MODEL: str = "gemini-1.5-pro"
+    GEMINI_TEMPERATURE: float = 0.3
+
+    # Firebase Configuration
+    FIREBASE_PROJECT_ID: str = "finagent-fdc80"
+    FIREBASE_API_KEY: str = "AIzaSyCS95PURecjhaLyyEc7RSYfR63YiN2kzec"
+    FIREBASE_AUTH_DOMAIN: str = "finagent-fdc80.firebaseapp.com"
+    FIREBASE_STORAGE_BUCKET: str = "finagent-fdc80.firebasestorage.app"
+    FIREBASE_MESSAGING_SENDER_ID: str = "613182907538"
+    FIREBASE_APP_ID: str = "1:613182907538:web:5fb81003908baccecbf24b"
+    FIREBASE_MEASUREMENT_ID: str = "G-CLXYJVNRSP"
+
+    # Firebase Admin SDK (for Firestore and Auth verification)
+    # Can be JSON string or path to service account file
+    FIREBASE_CREDENTIALS: str = ""  # Will use Application Default Credentials if empty
+
+    # CORS Configuration
+    ALLOWED_ORIGINS: List[str] = [
+        "http://localhost:3000",
+        "http://localhost:5173",
+        "https://finagent-fdc80.web.app",
+        "https://finagent-fdc80.firebaseapp.com",
+    ]
+
+    # Server Configuration
+    HOST: str = "0.0.0.0"
+    PORT: int = 8000
+    WORKERS: int = 1
+
+    # PDF Configuration
+    PDF_OUTPUT_DIR: str = "sanctions"
+    PDF_VALIDITY_DAYS: int = 7
+
+    # Loan Configuration
+    DEFAULT_INTEREST_RATE: float = 12.0  # Annual percentage
+    MIN_LOAN_AMOUNT: float = 50000.0
+    MAX_LOAN_AMOUNT: float = 5000000.0
+    MIN_TENURE_MONTHS: int = 6
+    MAX_TENURE_MONTHS: int = 60
+
+    # Underwriting Thresholds
+    EXCELLENT_CREDIT_SCORE: int = 720
+    GOOD_CREDIT_SCORE: int = 680
+    FOIR_THRESHOLD_A: float = 0.4
+    FOIR_THRESHOLD_B: float = 0.5
+
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+        case_sensitive = True
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """
+    Get cached settings instance.
+    Uses LRU cache to avoid recreating settings on every call.
+    """
+    return Settings()
+
+
+# Global settings instance
+settings = get_settings()

app/main.py

@@ -0,0 +1,155 @@
+"""
+Main FastAPI application for FinAgent backend.
+Chat2Sanction - AI-powered loan processing platform.
+"""
+
+import os
+from contextlib import asynccontextmanager
+
+from app.config import settings
+from app.routers import admin, auth, chat, loan
+from app.utils.logger import setup_logger
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+# Setup logger
+logger = setup_logger("finagent", log_file="finagent.log")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Lifespan context manager for startup and shutdown events.
+    """
+    # Startup
+    logger.info("=" * 80)
+    logger.info(f"Starting {settings.APP_NAME} v{settings.APP_VERSION}")
+    logger.info("=" * 80)
+    logger.info(f"Environment: {'Development' if settings.DEBUG else 'Production'}")
+    logger.info(f"Firebase Project: {settings.FIREBASE_PROJECT_ID}")
+    logger.info(f"Gemini Model: {settings.GEMINI_MODEL}")
+
+    # Initialize services
+    try:
+        from app.agents.master_agent import master_agent
+        from app.services.firebase_service import firebase_service
+        from app.services.pdf_service import pdf_service
+        from app.services.session_service import session_service
+        from app.services.underwriting_service import underwriting_service
+
+        logger.info("All services initialized successfully")
+    except Exception as e:
+        logger.error(f"Failed to initialize services: {str(e)}")
+
+    # Create output directories
+    os.makedirs(settings.PDF_OUTPUT_DIR, exist_ok=True)
+    logger.info(f"PDF output directory: {settings.PDF_OUTPUT_DIR}")
+
+    logger.info("✓ Application startup complete")
+    logger.info("=" * 80)
+
+    yield
+
+    # Shutdown
+    logger.info("=" * 80)
+    logger.info("Shutting down application")
+    logger.info("=" * 80)
+
+
+# Create FastAPI app
+app = FastAPI(
+    title=settings.APP_NAME,
+    description="AI-powered loan processing platform with conversational interface",
+    version=settings.APP_VERSION,
+    lifespan=lifespan,
+    docs_url="/api/docs",
+    redoc_url="/api/redoc",
+    openapi_url="/api/openapi.json",
+)
+
+# Configure CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# Health check endpoint
+@app.get("/")
+async def root():
+    """Root endpoint with API information."""
+    return {
+        "name": settings.APP_NAME,
+        "version": settings.APP_VERSION,
+        "status": "running",
+        "docs": "/api/docs",
+    }
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint."""
+    from app.services.firebase_service import firebase_service
+
+    return {
+        "status": "healthy",
+        "firebase": "connected" if firebase_service.initialized else "disconnected",
+        "gemini": "configured" if settings.GOOGLE_API_KEY else "not configured",
+    }
+
+
+# Include routers
+app.include_router(auth.router, prefix="/api/auth", tags=["Authentication"])
+app.include_router(chat.router, prefix="/api/chat", tags=["Chat"])
+app.include_router(loan.router, prefix="/api/loan", tags=["Loans"])
+app.include_router(admin.router, prefix="/api/admin", tags=["Admin"])
+
+
+# Global exception handler
+@app.exception_handler(Exception)
+async def global_exception_handler(request, exc):
+    """Global exception handler for unhandled errors."""
+    logger.error(f"Unhandled exception: {str(exc)}", exc_info=True)
+    return JSONResponse(
+        status_code=500,
+        content={
+            "error": "Internal server error",
+            "detail": str(exc) if settings.DEBUG else "An unexpected error occurred",
+        },
+    )
+
+
+# Request logging middleware
+@app.middleware("http")
+async def log_requests(request, call_next):
+    """Log all HTTP requests."""
+    from time import time
+
+    start_time = time()
+
+    # Process request
+    response = await call_next(request)
+
+    # Log request
+    duration = (time() - start_time) * 1000  # Convert to milliseconds
+    logger.info(
+        f"{request.method} {request.url.path} - {response.status_code} ({duration:.2f}ms)"
+    )
+
+    return response
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(
+        "app.main:app",
+        host=settings.HOST,
+        port=settings.PORT,
+        reload=settings.DEBUG,
+        workers=settings.WORKERS,
+    )

app/routers/admin.py

@@ -0,0 +1,243 @@
+"""
+Admin router for dashboard metrics and loan management.
+Provides endpoints for admin analytics and bulk operations.
+"""
+
+from typing import Optional
+
+from app.schemas import AdminLoansResponse, AdminMetrics, LoanListItem, MessageResponse
+from app.services.firebase_service import firebase_service
+from app.utils.logger import default_logger as logger
+from fastapi import APIRouter, HTTPException, Query, status
+
+router = APIRouter()
+
+
+@router.get("/metrics", response_model=AdminMetrics)
+async def get_admin_metrics():
+    """
+    Get aggregated metrics for admin dashboard.
+
+    Returns:
+        AdminMetrics with loan statistics and analytics
+    """
+    try:
+        logger.info("Fetching admin metrics")
+
+        summary = firebase_service.get_admin_summary()
+
+        metrics = AdminMetrics(
+            total_applications=summary.get("total_applications", 0),
+            approved_count=summary.get("approved_count", 0),
+            rejected_count=summary.get("rejected_count", 0),
+            adjust_count=summary.get("adjust_count", 0),
+            avg_loan_amount=round(summary.get("avg_loan_amount", 0), 2),
+            avg_emi=round(summary.get("avg_emi", 0), 2),
+            avg_credit_score=round(summary.get("avg_credit_score", 0), 0),
+            today_applications=summary.get("today_applications", 0),
+            risk_distribution=summary.get("risk_distribution", {}),
+        )
+
+        return metrics
+
+    except Exception as e:
+        logger.error(f"Error fetching admin metrics: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to fetch admin metrics",
+        )
+
+
+@router.get("/loans", response_model=AdminLoansResponse)
+async def get_all_loans(
+    page: int = Query(1, ge=1, description="Page number"),
+    page_size: int = Query(20, ge=1, le=100, description="Items per page"),
+    decision: Optional[str] = Query(None, description="Filter by decision"),
+    risk_band: Optional[str] = Query(None, description="Filter by risk band"),
+):
+    """
+    Get all loan applications with pagination and filtering.
+
+    Args:
+        page: Page number (starts at 1)
+        page_size: Number of items per page
+        decision: Optional filter by decision (APPROVED/REJECTED/ADJUST)
+        risk_band: Optional filter by risk band (A/B/C)
+
+    Returns:
+        AdminLoansResponse with paginated loan list
+    """
+    try:
+        logger.info(f"Fetching loans: page={page}, page_size={page_size}")
+
+        # Calculate offset
+        offset = (page - 1) * page_size
+
+        # Fetch loans
+        all_loans = firebase_service.get_all_loans(limit=page_size * 10, offset=0)
+
+        # Apply filters
+        filtered_loans = all_loans
+        if decision:
+            filtered_loans = [
+                loan for loan in filtered_loans if loan.get("decision") == decision
+            ]
+        if risk_band:
+            filtered_loans = [
+                loan for loan in filtered_loans if loan.get("risk_band") == risk_band
+            ]
+
+        # Get total count
+        total = len(filtered_loans)
+
+        # Apply pagination
+        start_idx = offset
+        end_idx = start_idx + page_size
+        paginated_loans = filtered_loans[start_idx:end_idx]
+
+        # Format loan list
+        loan_items = []
+        for loan in paginated_loans:
+            # Get user profile for full name
+            user_id = loan.get("user_id")
+            user_profile = firebase_service.get_user_profile(user_id)
+            full_name = (
+                user_profile.get("full_name", "User") if user_profile else "User"
+            )
+
+            loan_items.append(
+                LoanListItem(
+                    loan_id=loan.get("loan_id"),
+                    user_id=loan.get("user_id"),
+                    full_name=full_name,
+                    requested_amount=loan.get("requested_amount", 0),
+                    approved_amount=loan.get("approved_amount", 0),
+                    decision=loan.get("decision", "PENDING"),
+                    risk_band=loan.get("risk_band", "C"),
+                    created_at=loan.get("created_at"),
+                )
+            )
+
+        response = AdminLoansResponse(
+            loans=loan_items, total=total, page=page, page_size=page_size
+        )
+
+        return response
+
+    except Exception as e:
+        logger.error(f"Error fetching loans: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to fetch loans",
+        )
+
+
+@router.get("/stats/summary")
+async def get_stats_summary():
+    """
+    Get detailed statistics summary.
+
+    Returns:
+        Detailed statistics including approval rates, average amounts, etc.
+    """
+    try:
+        logger.info("Fetching detailed statistics")
+
+        summary = firebase_service.get_admin_summary()
+
+        total = summary.get("total_applications", 0)
+        approved = summary.get("approved_count", 0)
+        rejected = summary.get("rejected_count", 0)
+        adjust = summary.get("adjust_count", 0)
+
+        # Calculate rates
+        approval_rate = (approved / total * 100) if total > 0 else 0
+        rejection_rate = (rejected / total * 100) if total > 0 else 0
+        adjustment_rate = (adjust / total * 100) if total > 0 else 0
+
+        stats = {
+            "overview": {
+                "total_applications": total,
+                "approved_count": approved,
+                "rejected_count": rejected,
+                "adjust_count": adjust,
+                "today_applications": summary.get("today_applications", 0),
+            },
+            "rates": {
+                "approval_rate": round(approval_rate, 2),
+                "rejection_rate": round(rejection_rate, 2),
+                "adjustment_rate": round(adjustment_rate, 2),
+            },
+            "averages": {
+                "avg_loan_amount": round(summary.get("avg_loan_amount", 0), 2),
+                "avg_emi": round(summary.get("avg_emi", 0), 2),
+                "avg_credit_score": round(summary.get("avg_credit_score", 0), 0),
+            },
+            "risk_distribution": summary.get("risk_distribution", {}),
+        }
+
+        return stats
+
+    except Exception as e:
+        logger.error(f"Error fetching stats summary: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to fetch statistics",
+        )
+
+
+@router.get("/health")
+async def health_check():
+    """
+    Health check endpoint for admin services.
+
+    Returns:
+        Health status
+    """
+    try:
+        # Check Firebase connection
+        firebase_status = (
+            "connected" if firebase_service.initialized else "disconnected"
+        )
+
+        return {
+            "status": "healthy",
+            "firebase": firebase_status,
+            "timestamp": __import__("datetime").datetime.utcnow().isoformat(),
+        }
+
+    except Exception as e:
+        logger.error(f"Health check failed: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Health check failed",
+        )
+
+
+@router.post("/cleanup")
+async def cleanup_old_data():
+    """
+    Cleanup old sessions and temporary data.
+
+    Returns:
+        Cleanup result
+    """
+    try:
+        logger.info("Running cleanup tasks")
+
+        from app.services.session_service import session_service
+
+        # Cleanup old sessions (older than 24 hours)
+        deleted_sessions = session_service.cleanup_old_sessions(max_age_hours=24)
+
+        return MessageResponse(
+            message=f"Cleanup completed: {deleted_sessions} sessions removed",
+            success=True,
+        )
+
+    except Exception as e:
+        logger.error(f"Cleanup error: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Cleanup failed",
+        )

app/routers/auth.py

@@ -0,0 +1,238 @@
+"""
+Authentication router for user login and registration.
+Handles Firebase Authentication integration.
+"""
+
+from datetime import datetime
+from typing import Optional
+
+from app.config import settings
+from app.schemas import (
+    ErrorResponse,
+    LoginRequest,
+    LoginResponse,
+    MessageResponse,
+    RegisterRequest,
+)
+from app.services.firebase_service import firebase_service
+from app.utils.logger import default_logger as logger
+from fastapi import APIRouter, Header, HTTPException, status
+
+router = APIRouter()
+
+
+@router.post("/login", response_model=LoginResponse)
+async def login(request: LoginRequest):
+    """
+    Login endpoint for user authentication.
+
+    For hackathon: Simple email/password validation.
+    In production: This would validate Firebase ID tokens.
+
+    Args:
+        request: Login request with email and password
+
+    Returns:
+        LoginResponse with access token and user info
+    """
+    try:
+        logger.info(f"Login attempt for email: {request.email}")
+
+        # For hackathon: Simple validation
+        if len(request.password) < 6:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid credentials"
+            )
+
+        # Try to find user by email in Firestore
+        # In production, Firebase Auth would handle this
+        user_profile = None
+
+        # For now, we'll check if user exists or create a mock response
+        # In production, you'd verify Firebase ID token here
+
+        # Generate a mock user_id from email (for demo)
+        user_id = request.email.split("@")[0].replace(".", "_")
+
+        # Try to fetch existing user
+        user_profile = firebase_service.get_user_profile(user_id)
+
+        if not user_profile:
+            # For demo: Create a basic profile if doesn't exist
+            logger.info(f"Creating new user profile for {request.email}")
+            user_profile = {
+                "user_id": user_id,
+                "email": request.email,
+                "full_name": request.email.split("@")[0].title(),
+                "monthly_income": 50000.0,
+                "existing_emi": 0.0,
+                "mock_credit_score": 680,
+                "segment": "New to Credit",
+            }
+            firebase_service.create_user_profile(user_profile)
+
+        # Generate access token (in production, use proper JWT)
+        access_token = f"finagent_token_{user_id}_{datetime.utcnow().timestamp()}"
+
+        response = LoginResponse(
+            access_token=access_token,
+            token_type="Bearer",
+            user_id=user_profile.get("user_id", user_id),
+            full_name=user_profile.get("full_name", "User"),
+            email=user_profile.get("email", request.email),
+        )
+
+        logger.info(f"Login successful for user: {user_id}")
+        return response
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Login error: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Login failed"
+        )
+
+
+@router.post("/register", response_model=LoginResponse)
+async def register(request: RegisterRequest):
+    """
+    Register a new user.
+
+    Args:
+        request: Registration request with user details
+
+    Returns:
+        LoginResponse with access token and user info
+    """
+    try:
+        logger.info(f"Registration attempt for email: {request.email}")
+
+        # Generate user_id from email
+        user_id = request.email.split("@")[0].replace(".", "_")
+
+        # Check if user already exists
+        existing_user = firebase_service.get_user_profile(user_id)
+        if existing_user:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST, detail="User already exists"
+            )
+
+        # Create user profile
+        user_profile = {
+            "user_id": user_id,
+            "email": request.email,
+            "full_name": request.full_name,
+            "monthly_income": request.monthly_income,
+            "existing_emi": request.existing_emi,
+            "mock_credit_score": 650,  # Default credit score
+            "segment": "New to Credit",
+        }
+
+        created_profile = firebase_service.create_user_profile(user_profile)
+
+        # Generate access token
+        access_token = f"finagent_token_{user_id}_{datetime.utcnow().timestamp()}"
+
+        response = LoginResponse(
+            access_token=access_token,
+            token_type="Bearer",
+            user_id=created_profile.get("user_id", user_id),
+            full_name=created_profile.get("full_name"),
+            email=created_profile.get("email"),
+        )
+
+        logger.info(f"Registration successful for user: {user_id}")
+        return response
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Registration error: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Registration failed",
+        )
+
+
+@router.post("/verify-token")
+async def verify_token(authorization: Optional[str] = Header(None)):
+    """
+    Verify Firebase ID token.
+
+    Args:
+        authorization: Authorization header with Bearer token
+
+    Returns:
+        Token verification result
+    """
+    try:
+        if not authorization:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Authorization header missing",
+            )
+
+        # Extract token from Bearer scheme
+        parts = authorization.split()
+        if len(parts) != 2 or parts[0].lower() != "bearer":
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid authorization header format",
+            )
+
+        token = parts[1]
+
+        # For hackathon: Simple token validation
+        if token.startswith("finagent_token_"):
+            # Extract user_id from token
+            parts = token.split("_")
+            if len(parts) >= 3:
+                user_id = "_".join(parts[2:-1])
+                return MessageResponse(message="Token valid", success=True)
+
+        # In production: Verify Firebase ID token
+        # decoded_token = firebase_service.verify_token(token)
+        # if decoded_token:
+        #     return MessageResponse(message="Token valid", success=True)
+
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid or expired token"
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Token verification error: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED, detail="Token verification failed"
+        )
+
+
+@router.post("/logout")
+async def logout(authorization: Optional[str] = Header(None)):
+    """
+    Logout endpoint.
+
+    For stateless JWT tokens, this is mainly for client-side cleanup.
+    In production with Firebase, you might want to revoke refresh tokens.
+
+    Args:
+        authorization: Authorization header with Bearer token
+
+    Returns:
+        Success message
+    """
+    try:
+        logger.info("Logout request received")
+
+        # In production: Could revoke Firebase refresh tokens here
+        # or add token to blacklist
+
+        return MessageResponse(message="Logged out successfully", success=True)
+
+    except Exception as e:
+        logger.error(f"Logout error: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Logout failed"
+        )

app/routers/chat.py

@@ -0,0 +1,182 @@
+"""
+Chat router for conversational loan processing.
+Handles chat messages and integrates with the master agent.
+"""
+
+from typing import Optional
+
+from app.agents.master_agent import master_agent
+from app.schemas import ChatRequest, ChatResponse, ErrorResponse
+from app.services.firebase_service import firebase_service
+from app.services.session_service import session_service
+from app.utils.logger import default_logger as logger
+from fastapi import APIRouter, HTTPException, status
+
+router = APIRouter()
+
+
+@router.post("/", response_model=ChatResponse)
+async def chat(request: ChatRequest):
+    """
+    Process a chat message and return agent response.
+
+    Args:
+        request: Chat request with session_id, user_id, and message
+
+    Returns:
+        ChatResponse with agent reply and metadata
+    """
+    try:
+        logger.info(
+            f"Chat request from user {request.user_id}, session {request.session_id}"
+        )
+
+        # Get or create session
+        session_id = session_service.get_or_create_session(
+            request.session_id, request.user_id
+        )
+
+        # Fetch user profile if not in session
+        user_profile = session_service.get_user_profile(session_id)
+        if not user_profile:
+            user_profile = firebase_service.get_user_profile(request.user_id)
+            if user_profile:
+                session_service.set_user_profile(session_id, user_profile)
+
+        # Add user message to session history
+        session_service.add_to_chat_history(session_id, "user", request.message)
+
+        # Determine current step
+        current_step = session_service.get_step(session_id)
+
+        # Process message with master agent
+        agent_response = master_agent.chat(session_id, request.user_id, request.message)
+
+        # Add agent response to session history
+        session_service.add_to_chat_history(
+            session_id, "assistant", agent_response["reply"]
+        )
+
+        # Update session step based on decision
+        new_step = current_step
+        if agent_response.get("decision"):
+            if agent_response["decision"] in ["APPROVED", "ADJUST"]:
+                new_step = "SANCTION_GENERATED"
+            elif agent_response["decision"] == "REJECTED":
+                new_step = "REJECTED"
+        elif "loan" in request.message.lower() and "amount" in request.message.lower():
+            new_step = "GATHERING_DETAILS"
+        elif current_step == "GATHERING_DETAILS":
+            new_step = "UNDERWRITING"
+
+        session_service.set_step(session_id, new_step)
+
+        # Prepare response
+        response = ChatResponse(
+            reply=agent_response["reply"],
+            step=new_step,
+            decision=agent_response.get("decision"),
+            loan_id=agent_response.get("loan_id"),
+            meta=agent_response.get("meta"),
+            session_id=session_id,
+        )
+
+        logger.info(
+            f"Chat response sent: decision={response.decision}, step={response.step}"
+        )
+        return response
+
+    except Exception as e:
+        logger.error(f"Chat error: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to process chat message",
+        )
+
+
+@router.get("/history/{session_id}")
+async def get_chat_history(session_id: str):
+    """
+    Get chat history for a session.
+
+    Args:
+        session_id: Session ID
+
+    Returns:
+        List of chat messages
+    """
+    try:
+        history = session_service.get_chat_history(session_id)
+        return {"session_id": session_id, "history": history, "count": len(history)}
+
+    except Exception as e:
+        logger.error(f"Error fetching chat history: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to fetch chat history",
+        )
+
+
+@router.delete("/session/{session_id}")
+async def clear_session(session_id: str):
+    """
+    Clear a chat session.
+
+    Args:
+        session_id: Session ID
+
+    Returns:
+        Success message
+    """
+    try:
+        session_service.clear_session(session_id)
+        master_agent.clear_session_memory(session_id)
+
+        logger.info(f"Cleared session {session_id}")
+        return {"message": "Session cleared successfully", "success": True}
+
+    except Exception as e:
+        logger.error(f"Error clearing session: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to clear session",
+        )
+
+
+@router.get("/session/{session_id}/info")
+async def get_session_info(session_id: str):
+    """
+    Get session information and state.
+
+    Args:
+        session_id: Session ID
+
+    Returns:
+        Session information
+    """
+    try:
+        session = session_service.get_session(session_id)
+
+        if not session:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND, detail="Session not found"
+            )
+
+        # Return session info without sensitive data
+        return {
+            "session_id": session["session_id"],
+            "user_id": session["user_id"],
+            "current_step": session["current_step"],
+            "message_count": len(session["chat_history"]),
+            "created_at": session["created_at"].isoformat(),
+            "updated_at": session["updated_at"].isoformat(),
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error fetching session info: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to fetch session info",
+        )

app/routers/loan.py

@@ -0,0 +1,279 @@
+"""
+Loan router for loan application operations and sanction letter management.
+Handles loan retrieval, PDF generation, and loan status queries.
+"""
+
+from typing import Optional
+
+from app.schemas import (
+    ErrorResponse,
+    LoanApplication,
+    LoanSummaryResponse,
+    MessageResponse,
+    SanctionLetterResponse,
+)
+from app.services.firebase_service import firebase_service
+from app.services.pdf_service import pdf_service
+from app.utils.logger import default_logger as logger
+from fastapi import APIRouter, HTTPException, status
+from fastapi.responses import FileResponse
+
+router = APIRouter()
+
+
+@router.get("/{loan_id}", response_model=LoanSummaryResponse)
+async def get_loan(loan_id: str):
+    """
+    Get loan application details by ID.
+
+    Args:
+        loan_id: Loan application ID
+
+    Returns:
+        LoanSummaryResponse with loan details
+    """
+    try:
+        logger.info(f"Fetching loan application: {loan_id}")
+
+        # Fetch loan from Firebase
+        loan = firebase_service.get_loan_application(loan_id)
+
+        if not loan:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Loan application not found",
+            )
+
+        # Fetch user profile for full name
+        user_id = loan.get("user_id")
+        user_profile = firebase_service.get_user_profile(user_id)
+        full_name = user_profile.get("full_name", "User") if user_profile else "User"
+
+        # Prepare response
+        response = LoanSummaryResponse(
+            loan_id=loan.get("loan_id"),
+            user_id=loan.get("user_id"),
+            full_name=full_name,
+            approved_amount=loan.get("approved_amount", 0),
+            tenure_months=loan.get("tenure_months", 0),
+            emi=loan.get("emi", 0),
+            interest_rate=loan.get("interest_rate", 0),
+            decision=loan.get("decision", "PENDING"),
+            risk_band=loan.get("risk_band", "C"),
+            created_at=loan.get("created_at"),
+            sanction_pdf_url=loan.get("sanction_pdf_url"),
+        )
+
+        return response
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error fetching loan: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to fetch loan application",
+        )
+
+
+@router.get("/{loan_id}/sanction-pdf")
+async def get_sanction_pdf(loan_id: str):
+    """
+    Get sanction letter PDF for a loan application.
+
+    Args:
+        loan_id: Loan application ID
+
+    Returns:
+        PDF file response or URL to PDF
+    """
+    try:
+        logger.info(f"Fetching sanction PDF for loan: {loan_id}")
+
+        # Check if PDF exists
+        if not pdf_service.pdf_exists(loan_id):
+            # Try to fetch loan and regenerate PDF if approved
+            loan = firebase_service.get_loan_application(loan_id)
+
+            if not loan:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail="Loan application not found",
+                )
+
+            if loan.get("decision") not in ["APPROVED", "ADJUST"]:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Sanction letter only available for approved loans",
+                )
+
+            # Get user profile for full name
+            user_profile = firebase_service.get_user_profile(loan.get("user_id"))
+            if user_profile:
+                loan["full_name"] = user_profile.get("full_name", "Valued Customer")
+
+            # Generate PDF
+            pdf_result = pdf_service.generate_sanction_letter(loan)
+            pdf_path = pdf_result["pdf_path"]
+        else:
+            pdf_path = pdf_service.get_pdf_path(loan_id)
+
+        # Return PDF file
+        return FileResponse(
+            path=pdf_path,
+            media_type="application/pdf",
+            filename=f"sanction_letter_{loan_id}.pdf",
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error fetching sanction PDF: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to fetch sanction letter PDF",
+        )
+
+
+@router.get("/{loan_id}/sanction-info", response_model=SanctionLetterResponse)
+async def get_sanction_info(loan_id: str):
+    """
+    Get sanction letter information without downloading PDF.
+
+    Args:
+        loan_id: Loan application ID
+
+    Returns:
+        SanctionLetterResponse with PDF path and URL
+    """
+    try:
+        logger.info(f"Fetching sanction info for loan: {loan_id}")
+
+        # Fetch loan
+        loan = firebase_service.get_loan_application(loan_id)
+
+        if not loan:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Loan application not found",
+            )
+
+        if loan.get("decision") not in ["APPROVED", "ADJUST"]:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Sanction letter only available for approved loans",
+            )
+
+        pdf_path = loan.get("sanction_pdf_path", "")
+        pdf_url = loan.get("sanction_pdf_url", f"/api/loan/{loan_id}/sanction-pdf")
+
+        response = SanctionLetterResponse(
+            loan_id=loan_id, pdf_url=pdf_url, pdf_path=pdf_path
+        )
+
+        return response
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error fetching sanction info: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to fetch sanction letter info",
+        )
+
+
+@router.get("/user/{user_id}/loans")
+async def get_user_loans(user_id: str, limit: int = 10):
+    """
+    Get all loan applications for a user.
+
+    Args:
+        user_id: User ID
+        limit: Maximum number of loans to return
+
+    Returns:
+        List of loan applications
+    """
+    try:
+        logger.info(f"Fetching loans for user: {user_id}")
+
+        loans = firebase_service.get_user_loans(user_id)
+
+        # Limit results
+        loans = loans[:limit]
+
+        # Get user profile for full name
+        user_profile = firebase_service.get_user_profile(user_id)
+        full_name = user_profile.get("full_name", "User") if user_profile else "User"
+
+        # Format loans
+        loan_list = []
+        for loan in loans:
+            loan_list.append(
+                {
+                    "loan_id": loan.get("loan_id"),
+                    "user_id": loan.get("user_id"),
+                    "full_name": full_name,
+                    "requested_amount": loan.get("requested_amount", 0),
+                    "approved_amount": loan.get("approved_amount", 0),
+                    "emi": loan.get("emi", 0),
+                    "tenure_months": loan.get("tenure_months", 0),
+                    "decision": loan.get("decision"),
+                    "risk_band": loan.get("risk_band"),
+                    "created_at": loan.get("created_at").isoformat()
+                    if loan.get("created_at")
+                    else None,
+                }
+            )
+
+        return {"user_id": user_id, "loans": loan_list, "count": len(loan_list)}
+
+    except Exception as e:
+        logger.error(f"Error fetching user loans: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to fetch user loans",
+        )
+
+
+@router.delete("/{loan_id}/sanction-pdf")
+async def delete_sanction_pdf(loan_id: str):
+    """
+    Delete sanction letter PDF for a loan.
+
+    Args:
+        loan_id: Loan application ID
+
+    Returns:
+        Success message
+    """
+    try:
+        logger.info(f"Deleting sanction PDF for loan: {loan_id}")
+
+        # Delete PDF file
+        deleted = pdf_service.delete_pdf(loan_id)
+
+        if not deleted:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Sanction letter PDF not found",
+            )
+
+        # Update loan record to remove PDF path
+        firebase_service.update_loan_application(
+            loan_id, {"sanction_pdf_path": None, "sanction_pdf_url": None}
+        )
+
+        return MessageResponse(
+            message="Sanction letter PDF deleted successfully", success=True
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error deleting sanction PDF: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to delete sanction letter PDF",
+        )

app/schemas.py

@@ -0,0 +1,243 @@
+"""
+Pydantic schemas for request/response validation.
+Defines data models for API endpoints.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, EmailStr, Field
+
+# ============================================================================
+# Authentication Schemas
+# ============================================================================
+
+
+class LoginRequest(BaseModel):
+    """Login request with email and password."""
+
+    email: EmailStr
+    password: str = Field(..., min_length=6)
+
+
+class LoginResponse(BaseModel):
+    """Login response with user info and token."""
+
+    access_token: str
+    token_type: str = "Bearer"
+    user_id: str
+    full_name: str
+    email: str
+
+
+class RegisterRequest(BaseModel):
+    """User registration request."""
+
+    email: EmailStr
+    password: str = Field(..., min_length=6)
+    full_name: str = Field(..., min_length=2)
+    monthly_income: float = Field(..., gt=0)
+    existing_emi: float = Field(default=0.0, ge=0)
+
+
+# ============================================================================
+# Chat Schemas
+# ============================================================================
+
+
+class ChatRequest(BaseModel):
+    """Chat message request."""
+
+    session_id: str
+    user_id: str
+    message: str = Field(..., min_length=1, max_length=2000)
+
+
+class ChatResponse(BaseModel):
+    """Chat response with agent reply and metadata."""
+
+    reply: str
+    step: Optional[str] = (
+        None  # WELCOME, GATHERING_DETAILS, UNDERWRITING, SANCTION_GENERATED
+    )
+    decision: Optional[str] = None  # APPROVED, REJECTED, ADJUST
+    loan_id: Optional[str] = None
+    meta: Optional[Dict[str, Any]] = None
+    session_id: str
+
+
+# ============================================================================
+# Loan Schemas
+# ============================================================================
+
+
+class LoanApplicationRequest(BaseModel):
+    """Manual loan application request."""
+
+    user_id: str
+    requested_amount: float = Field(..., gt=0)
+    requested_tenure_months: int = Field(..., gt=0, le=60)
+
+
+class LoanDecision(BaseModel):
+    """Loan underwriting decision details."""
+
+    decision: str  # APPROVED, REJECTED, ADJUST
+    approved_amount: float
+    tenure_months: int
+    emi: float
+    interest_rate: float
+    credit_score: int
+    foir: float
+    risk_band: str  # A, B, C
+    explanation: str
+
+
+class LoanApplication(BaseModel):
+    """Complete loan application record."""
+
+    loan_id: str
+    user_id: str
+    requested_amount: float
+    requested_tenure_months: int
+    approved_amount: float
+    tenure_months: int
+    emi: float
+    interest_rate: float
+    credit_score: int
+    foir: float
+    decision: str
+    risk_band: str
+    explanation: str
+    sanction_pdf_path: Optional[str] = None
+    sanction_pdf_url: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class LoanSummaryResponse(BaseModel):
+    """Loan summary for display."""
+
+    loan_id: str
+    user_id: str
+    full_name: str
+    approved_amount: float
+    tenure_months: int
+    emi: float
+    interest_rate: float
+    decision: str
+    risk_band: str
+    created_at: datetime
+    sanction_pdf_url: Optional[str] = None
+
+
+class SanctionLetterResponse(BaseModel):
+    """Sanction letter PDF response."""
+
+    loan_id: str
+    pdf_url: str
+    pdf_path: str
+
+
+# ============================================================================
+# User Profile Schemas
+# ============================================================================
+
+
+class UserProfile(BaseModel):
+    """User profile information."""
+
+    user_id: str
+    full_name: str
+    email: str
+    monthly_income: float
+    existing_emi: float
+    mock_credit_score: int
+    segment: str = "New to Credit"  # Existing Customer, New to Credit, etc.
+    created_at: Optional[datetime] = None
+
+
+class UserProfileUpdate(BaseModel):
+    """User profile update request."""
+
+    full_name: Optional[str] = None
+    monthly_income: Optional[float] = Field(None, gt=0)
+    existing_emi: Optional[float] = Field(None, ge=0)
+
+
+# ============================================================================
+# Admin Schemas
+# ============================================================================
+
+
+class AdminMetrics(BaseModel):
+    """Admin dashboard metrics."""
+
+    total_applications: int
+    approved_count: int
+    rejected_count: int
+    adjust_count: int
+    avg_loan_amount: float
+    avg_emi: float
+    avg_credit_score: float
+    today_applications: int
+    risk_distribution: Dict[str, int]  # {"A": 10, "B": 5, "C": 2}
+
+
+class LoanListItem(BaseModel):
+    """Abbreviated loan info for admin list."""
+
+    loan_id: str
+    user_id: str
+    full_name: str
+    requested_amount: float
+    approved_amount: float
+    decision: str
+    risk_band: str
+    created_at: datetime
+
+
+class AdminLoansResponse(BaseModel):
+    """List of loans for admin dashboard."""
+
+    loans: List[LoanListItem]
+    total: int
+    page: int
+    page_size: int
+
+
+# ============================================================================
+# Session Schemas
+# ============================================================================
+
+
+class SessionState(BaseModel):
+    """Internal session state for chat context."""
+
+    session_id: str
+    user_id: str
+    current_step: str = "WELCOME"
+    loan_details: Optional[Dict[str, Any]] = None
+    chat_history: List[Dict[str, str]] = []
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+
+
+# ============================================================================
+# Generic Response Schemas
+# ============================================================================
+
+
+class MessageResponse(BaseModel):
+    """Generic message response."""
+
+    message: str
+    success: bool = True
+
+
+class ErrorResponse(BaseModel):
+    """Error response."""
+
+    error: str
+    detail: Optional[str] = None
+    success: bool = False

app/services/firebase_service.py

@@ -0,0 +1,491 @@
+"""
+Firebase service for Firestore database and Authentication.
+Handles all Firebase operations including user profiles and loan applications.
+"""
+
+import json
+import os
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+import firebase_admin
+from app.config import settings
+from app.utils.logger import default_logger as logger
+from firebase_admin import auth, credentials, firestore
+from google.cloud.firestore_v1 import FieldFilter
+
+
+class FirebaseService:
+    """Service for Firebase Firestore and Authentication operations."""
+
+    def __init__(self):
+        """Initialize Firebase Admin SDK and Firestore client."""
+        self.db: Optional[firestore.Client] = None
+        self.initialized = False
+        self._initialize_firebase()
+
+    def _initialize_firebase(self) -> None:
+        """Initialize Firebase Admin SDK with credentials."""
+        try:
+            # Check if Firebase app is already initialized
+            if not firebase_admin._apps:
+                # Try to load credentials from environment or use default
+                if settings.FIREBASE_CREDENTIALS:
+                    # If FIREBASE_CREDENTIALS is a JSON string
+                    if settings.FIREBASE_CREDENTIALS.startswith("{"):
+                        cred_dict = json.loads(settings.FIREBASE_CREDENTIALS)
+                        cred = credentials.Certificate(cred_dict)
+                    else:
+                        # If it's a file path
+                        cred = credentials.Certificate(settings.FIREBASE_CREDENTIALS)
+
+                    firebase_admin.initialize_app(
+                        cred, {"projectId": settings.FIREBASE_PROJECT_ID}
+                    )
+                else:
+                    # Use Application Default Credentials (for local dev with gcloud)
+                    firebase_admin.initialize_app(
+                        options={"projectId": settings.FIREBASE_PROJECT_ID}
+                    )
+
+            self.db = firestore.client()
+            self.initialized = True
+            logger.info("Firebase initialized successfully")
+
+        except Exception as e:
+            logger.error(f"Failed to initialize Firebase: {str(e)}")
+            # For development, we can continue without Firebase
+            logger.warning("Running without Firebase connection (dev mode)")
+            self.initialized = False
+
+    # ========================================================================
+    # User Profile Operations
+    # ========================================================================
+
+    def get_user_profile(self, user_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Retrieve user profile from Firestore.
+
+        Args:
+            user_id: User ID
+
+        Returns:
+            User profile dict or None if not found
+        """
+        if not self.initialized:
+            logger.warning("Firebase not initialized, returning mock data")
+            return self._get_mock_user_profile(user_id)
+
+        try:
+            doc_ref = self.db.collection("users").document(user_id)
+            doc = doc_ref.get()
+
+            if doc.exists:
+                profile = doc.to_dict()
+                profile["user_id"] = user_id
+                logger.info(f"Retrieved profile for user {user_id}")
+                return profile
+            else:
+                logger.warning(f"User profile not found: {user_id}")
+                return None
+
+        except Exception as e:
+            logger.error(f"Error fetching user profile: {str(e)}")
+            return None
+
+    def create_user_profile(self, user_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create a new user profile in Firestore.
+
+        Args:
+            user_data: User profile data
+
+        Returns:
+            Created user profile with user_id
+        """
+        if not self.initialized:
+            logger.warning("Firebase not initialized, returning mock data")
+            return {**user_data, "user_id": "mock_user_123"}
+
+        try:
+            user_id = user_data.get("user_id")
+            if not user_id:
+                # Generate user_id from Firebase Auth UID or create new
+                user_id = self.db.collection("users").document().id
+
+            user_data["user_id"] = user_id
+            user_data["created_at"] = datetime.utcnow()
+            user_data["updated_at"] = datetime.utcnow()
+
+            # Set default values
+            user_data.setdefault("existing_emi", 0.0)
+            user_data.setdefault("mock_credit_score", 650)
+            user_data.setdefault("segment", "New to Credit")
+
+            doc_ref = self.db.collection("users").document(user_id)
+            doc_ref.set(user_data)
+
+            logger.info(f"Created user profile: {user_id}")
+            return user_data
+
+        except Exception as e:
+            logger.error(f"Error creating user profile: {str(e)}")
+            raise
+
+    def update_user_profile(
+        self, user_id: str, update_data: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Update an existing user profile.
+
+        Args:
+            user_id: User ID
+            update_data: Fields to update
+
+        Returns:
+            Updated user profile
+        """
+        if not self.initialized:
+            logger.warning("Firebase not initialized")
+            return {"user_id": user_id, **update_data}
+
+        try:
+            update_data["updated_at"] = datetime.utcnow()
+            doc_ref = self.db.collection("users").document(user_id)
+            doc_ref.update(update_data)
+
+            logger.info(f"Updated user profile: {user_id}")
+            return self.get_user_profile(user_id)
+
+        except Exception as e:
+            logger.error(f"Error updating user profile: {str(e)}")
+            raise
+
+    # ========================================================================
+    # Loan Application Operations
+    # ========================================================================
+
+    def create_loan_application(self, loan_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create a new loan application in Firestore.
+
+        Args:
+            loan_data: Loan application data
+
+        Returns:
+            Created loan application with loan_id
+        """
+        if not self.initialized:
+            logger.warning("Firebase not initialized, returning mock data")
+            return {**loan_data, "loan_id": "mock_loan_123"}
+
+        try:
+            # Generate loan ID
+            loan_ref = self.db.collection("loan_applications").document()
+            loan_id = loan_ref.id
+
+            loan_data["loan_id"] = loan_id
+            loan_data["created_at"] = datetime.utcnow()
+            loan_data["updated_at"] = datetime.utcnow()
+
+            loan_ref.set(loan_data)
+
+            logger.info(f"Created loan application: {loan_id}")
+            return loan_data
+
+        except Exception as e:
+            logger.error(f"Error creating loan application: {str(e)}")
+            raise
+
+    def update_loan_application(
+        self, loan_id: str, update_data: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Update an existing loan application.
+
+        Args:
+            loan_id: Loan application ID
+            update_data: Fields to update
+
+        Returns:
+            Updated loan application
+        """
+        if not self.initialized:
+            logger.warning("Firebase not initialized")
+            return {"loan_id": loan_id, **update_data}
+
+        try:
+            update_data["updated_at"] = datetime.utcnow()
+            doc_ref = self.db.collection("loan_applications").document(loan_id)
+            doc_ref.update(update_data)
+
+            logger.info(f"Updated loan application: {loan_id}")
+            return self.get_loan_application(loan_id)
+
+        except Exception as e:
+            logger.error(f"Error updating loan application: {str(e)}")
+            raise
+
+    def get_loan_application(self, loan_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Retrieve a loan application by ID.
+
+        Args:
+            loan_id: Loan application ID
+
+        Returns:
+            Loan application dict or None if not found
+        """
+        if not self.initialized:
+            logger.warning("Firebase not initialized, returning mock data")
+            return self._get_mock_loan_application(loan_id)
+
+        try:
+            doc_ref = self.db.collection("loan_applications").document(loan_id)
+            doc = doc_ref.get()
+
+            if doc.exists:
+                loan = doc.to_dict()
+                loan["loan_id"] = loan_id
+                logger.info(f"Retrieved loan application: {loan_id}")
+                return loan
+            else:
+                logger.warning(f"Loan application not found: {loan_id}")
+                return None
+
+        except Exception as e:
+            logger.error(f"Error fetching loan application: {str(e)}")
+            return None
+
+    def get_user_loans(self, user_id: str) -> List[Dict[str, Any]]:
+        """
+        Get all loan applications for a user.
+
+        Args:
+            user_id: User ID
+
+        Returns:
+            List of loan applications
+        """
+        if not self.initialized:
+            logger.warning("Firebase not initialized, returning empty list")
+            return []
+
+        try:
+            loans_ref = self.db.collection("loan_applications")
+            query = loans_ref.where(
+                filter=FieldFilter("user_id", "==", user_id)
+            ).order_by("created_at", direction=firestore.Query.DESCENDING)
+
+            loans = []
+            for doc in query.stream():
+                loan = doc.to_dict()
+                loan["loan_id"] = doc.id
+                loans.append(loan)
+
+            logger.info(f"Retrieved {len(loans)} loans for user {user_id}")
+            return loans
+
+        except Exception as e:
+            logger.error(f"Error fetching user loans: {str(e)}")
+            return []
+
+    def get_all_loans(self, limit: int = 50, offset: int = 0) -> List[Dict[str, Any]]:
+        """
+        Get all loan applications with pagination.
+
+        Args:
+            limit: Number of loans to retrieve
+            offset: Number of loans to skip
+
+        Returns:
+            List of loan applications
+        """
+        if not self.initialized:
+            logger.warning("Firebase not initialized, returning empty list")
+            return []
+
+        try:
+            loans_ref = self.db.collection("loan_applications")
+            query = loans_ref.order_by(
+                "created_at", direction=firestore.Query.DESCENDING
+            ).limit(limit)
+
+            if offset > 0:
+                # Get the document to start after
+                skip_query = loans_ref.order_by(
+                    "created_at", direction=firestore.Query.DESCENDING
+                ).limit(offset)
+                skip_docs = list(skip_query.stream())
+                if skip_docs:
+                    query = query.start_after(skip_docs[-1])
+
+            loans = []
+            for doc in query.stream():
+                loan = doc.to_dict()
+                loan["loan_id"] = doc.id
+                loans.append(loan)
+
+            logger.info(
+                f"Retrieved {len(loans)} loans (limit={limit}, offset={offset})"
+            )
+            return loans
+
+        except Exception as e:
+            logger.error(f"Error fetching all loans: {str(e)}")
+            return []
+
+    # ========================================================================
+    # Admin Operations
+    # ========================================================================
+
+    def get_admin_summary(self) -> Dict[str, Any]:
+        """
+        Get aggregated metrics for admin dashboard.
+
+        Returns:
+            Dictionary with admin metrics
+        """
+        if not self.initialized:
+            logger.warning("Firebase not initialized, returning mock data")
+            return self._get_mock_admin_summary()
+
+        try:
+            loans_ref = self.db.collection("loan_applications")
+            loans = list(loans_ref.stream())
+
+            total = len(loans)
+            approved = 0
+            rejected = 0
+            adjust = 0
+            total_amount = 0
+            total_emi = 0
+            total_credit = 0
+            risk_dist = {"A": 0, "B": 0, "C": 0}
+
+            today = datetime.utcnow().date()
+            today_count = 0
+
+            for doc in loans:
+                loan = doc.to_dict()
+
+                decision = loan.get("decision", "")
+                if decision == "APPROVED":
+                    approved += 1
+                elif decision == "REJECTED":
+                    rejected += 1
+                elif decision == "ADJUST":
+                    adjust += 1
+
+                total_amount += loan.get("approved_amount", 0)
+                total_emi += loan.get("emi", 0)
+                total_credit += loan.get("credit_score", 0)
+
+                risk_band = loan.get("risk_band", "C")
+                if risk_band in risk_dist:
+                    risk_dist[risk_band] += 1
+
+                created_at = loan.get("created_at")
+                if created_at and created_at.date() == today:
+                    today_count += 1
+
+            summary = {
+                "total_applications": total,
+                "approved_count": approved,
+                "rejected_count": rejected,
+                "adjust_count": adjust,
+                "avg_loan_amount": total_amount / total if total > 0 else 0,
+                "avg_emi": total_emi / total if total > 0 else 0,
+                "avg_credit_score": total_credit / total if total > 0 else 0,
+                "today_applications": today_count,
+                "risk_distribution": risk_dist,
+            }
+
+            logger.info("Generated admin summary")
+            return summary
+
+        except Exception as e:
+            logger.error(f"Error generating admin summary: {str(e)}")
+            return self._get_mock_admin_summary()
+
+    # ========================================================================
+    # Authentication Operations
+    # ========================================================================
+
+    def verify_token(self, id_token: str) -> Optional[Dict[str, Any]]:
+        """
+        Verify Firebase ID token.
+
+        Args:
+            id_token: Firebase ID token from client
+
+        Returns:
+            Decoded token with user info or None if invalid
+        """
+        if not self.initialized:
+            logger.warning("Firebase not initialized, skipping token verification")
+            return {"uid": "mock_user_123", "email": "test@example.com"}
+
+        try:
+            decoded_token = auth.verify_id_token(id_token)
+            logger.info(f"Token verified for user: {decoded_token.get('uid')}")
+            return decoded_token
+
+        except Exception as e:
+            logger.error(f"Token verification failed: {str(e)}")
+            return None
+
+    # ========================================================================
+    # Mock Data Methods (for development)
+    # ========================================================================
+
+    def _get_mock_user_profile(self, user_id: str) -> Dict[str, Any]:
+        """Return mock user profile for development."""
+        return {
+            "user_id": user_id,
+            "full_name": "John Doe",
+            "email": "john.doe@example.com",
+            "monthly_income": 75000.0,
+            "existing_emi": 5000.0,
+            "mock_credit_score": 720,
+            "segment": "Existing Customer",
+            "created_at": datetime.utcnow(),
+        }
+
+    def _get_mock_loan_application(self, loan_id: str) -> Dict[str, Any]:
+        """Return mock loan application for development."""
+        return {
+            "loan_id": loan_id,
+            "user_id": "mock_user_123",
+            "requested_amount": 500000.0,
+            "requested_tenure_months": 36,
+            "approved_amount": 500000.0,
+            "tenure_months": 36,
+            "emi": 16620.0,
+            "interest_rate": 12.0,
+            "credit_score": 720,
+            "foir": 0.29,
+            "decision": "APPROVED",
+            "risk_band": "A",
+            "explanation": "Approved based on excellent credit score and low FOIR",
+            "created_at": datetime.utcnow(),
+            "updated_at": datetime.utcnow(),
+        }
+
+    def _get_mock_admin_summary(self) -> Dict[str, Any]:
+        """Return mock admin summary for development."""
+        return {
+            "total_applications": 25,
+            "approved_count": 18,
+            "rejected_count": 5,
+            "adjust_count": 2,
+            "avg_loan_amount": 425000.0,
+            "avg_emi": 14250.0,
+            "avg_credit_score": 695,
+            "today_applications": 3,
+            "risk_distribution": {"A": 12, "B": 10, "C": 3},
+        }
+
+
+# Singleton instance
+firebase_service = FirebaseService()

app/services/pdf_service.py

@@ -0,0 +1,323 @@
+"""
+PDF service for generating loan sanction letters.
+Uses ReportLab to create professional PDF documents.
+"""
+
+import os
+from datetime import datetime, timedelta
+from typing import Any, Dict
+
+from app.config import settings
+from app.utils.logger import default_logger as logger
+from reportlab.lib import colors
+from reportlab.lib.pagesizes import A4, letter
+from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
+from reportlab.lib.units import inch
+from reportlab.platypus import (
+    Paragraph,
+    SimpleDocTemplate,
+    Spacer,
+    Table,
+    TableStyle,
+)
+
+
+class PdfService:
+    """Service for generating loan sanction letter PDFs."""
+
+    def __init__(self):
+        """Initialize PDF service with output directory."""
+        self.output_dir = settings.PDF_OUTPUT_DIR
+        self.validity_days = settings.PDF_VALIDITY_DAYS
+
+        # Create output directory if it doesn't exist
+        os.makedirs(self.output_dir, exist_ok=True)
+
+    def generate_sanction_letter(self, loan_data: Dict[str, Any]) -> Dict[str, str]:
+        """
+        Generate a professional sanction letter PDF.
+
+        Args:
+            loan_data: Loan application data with all details
+
+        Returns:
+            Dictionary with pdf_path and pdf_url
+        """
+        try:
+            loan_id = loan_data.get("loan_id", "unknown")
+            filename = f"{loan_id}.pdf"
+            filepath = os.path.join(self.output_dir, filename)
+
+            # Create PDF document
+            doc = SimpleDocTemplate(
+                filepath,
+                pagesize=A4,
+                rightMargin=0.75 * inch,
+                leftMargin=0.75 * inch,
+                topMargin=1 * inch,
+                bottomMargin=0.75 * inch,
+            )
+
+            # Build content
+            elements = []
+            styles = getSampleStyleSheet()
+
+            # Custom styles
+            title_style = ParagraphStyle(
+                "CustomTitle",
+                parent=styles["Heading1"],
+                fontSize=20,
+                textColor=colors.HexColor("#10b981"),
+                spaceAfter=30,
+                alignment=1,  # Center
+                fontName="Helvetica-Bold",
+            )
+
+            heading_style = ParagraphStyle(
+                "CustomHeading",
+                parent=styles["Heading2"],
+                fontSize=14,
+                textColor=colors.HexColor("#1f2937"),
+                spaceAfter=12,
+                fontName="Helvetica-Bold",
+            )
+
+            normal_style = ParagraphStyle(
+                "CustomNormal",
+                parent=styles["Normal"],
+                fontSize=11,
+                textColor=colors.HexColor("#374151"),
+                spaceAfter=8,
+            )
+
+            # Header
+            elements.append(Paragraph("FinAgent", title_style))
+            elements.append(Paragraph("Personal Loan Sanction Letter", heading_style))
+            elements.append(Spacer(1, 0.2 * inch))
+
+            # Reference details
+            sanction_date = datetime.utcnow()
+            validity_date = sanction_date + timedelta(days=self.validity_days)
+
+            ref_data = [
+                ["Sanction Reference No:", loan_id],
+                ["Sanction Date:", sanction_date.strftime("%B %d, %Y")],
+                [
+                    "Validity Date:",
+                    validity_date.strftime("%B %d, %Y")
+                    + f" ({self.validity_days} days)",
+                ],
+            ]
+
+            ref_table = Table(ref_data, colWidths=[2.5 * inch, 3.5 * inch])
+            ref_table.setStyle(
+                TableStyle(
+                    [
+                        ("FONTNAME", (0, 0), (0, -1), "Helvetica-Bold"),
+                        ("FONTNAME", (1, 0), (1, -1), "Helvetica"),
+                        ("FONTSIZE", (0, 0), (-1, -1), 10),
+                        ("TEXTCOLOR", (0, 0), (-1, -1), colors.HexColor("#374151")),
+                        ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
+                        ("BOTTOMPADDING", (0, 0), (-1, -1), 8),
+                    ]
+                )
+            )
+            elements.append(ref_table)
+            elements.append(Spacer(1, 0.3 * inch))
+
+            # Applicant details
+            elements.append(Paragraph("Applicant Details", heading_style))
+
+            user_id = loan_data.get("user_id", "N/A")
+            full_name = loan_data.get("full_name", "Valued Customer")
+
+            applicant_data = [
+                ["Applicant Name:", full_name],
+                ["Customer ID:", user_id],
+            ]
+
+            applicant_table = Table(applicant_data, colWidths=[2.5 * inch, 3.5 * inch])
+            applicant_table.setStyle(
+                TableStyle(
+                    [
+                        ("FONTNAME", (0, 0), (0, -1), "Helvetica-Bold"),
+                        ("FONTNAME", (1, 0), (1, -1), "Helvetica"),
+                        ("FONTSIZE", (0, 0), (-1, -1), 10),
+                        ("TEXTCOLOR", (0, 0), (-1, -1), colors.HexColor("#374151")),
+                        ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
+                        ("BOTTOMPADDING", (0, 0), (-1, -1), 8),
+                    ]
+                )
+            )
+            elements.append(applicant_table)
+            elements.append(Spacer(1, 0.3 * inch))
+
+            # Loan details
+            elements.append(Paragraph("Loan Sanction Details", heading_style))
+
+            approved_amount = loan_data.get("approved_amount", 0)
+            tenure = loan_data.get("tenure_months", 0)
+            emi = loan_data.get("emi", 0)
+            interest_rate = loan_data.get("interest_rate", 0)
+            total_payable = loan_data.get("total_payable", emi * tenure)
+            processing_fee = loan_data.get("processing_fee", approved_amount * 0.02)
+
+            loan_details_data = [
+                ["Sanctioned Amount:", f"₹ {approved_amount:,.2f}"],
+                [
+                    "Tenure:",
+                    f"{tenure} months ({tenure // 12} years {tenure % 12} months)",
+                ],
+                ["Interest Rate:", f"{interest_rate}% per annum"],
+                ["Monthly EMI:", f"₹ {emi:,.2f}"],
+                ["Total Amount Payable:", f"₹ {total_payable:,.2f}"],
+                ["Processing Fee (2%):", f"₹ {processing_fee:,.2f}"],
+                ["Risk Band:", loan_data.get("risk_band", "N/A")],
+            ]
+
+            loan_table = Table(loan_details_data, colWidths=[2.5 * inch, 3.5 * inch])
+            loan_table.setStyle(
+                TableStyle(
+                    [
+                        ("FONTNAME", (0, 0), (0, -1), "Helvetica-Bold"),
+                        ("FONTNAME", (1, 0), (1, -1), "Helvetica"),
+                        ("FONTSIZE", (0, 0), (-1, -1), 10),
+                        ("TEXTCOLOR", (0, 0), (-1, -1), colors.HexColor("#374151")),
+                        ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
+                        ("BOTTOMPADDING", (0, 0), (-1, -1), 8),
+                        ("BACKGROUND", (0, -2), (-1, -2), colors.HexColor("#f3f4f6")),
+                    ]
+                )
+            )
+            elements.append(loan_table)
+            elements.append(Spacer(1, 0.3 * inch))
+
+            # Terms and conditions
+            elements.append(Paragraph("Terms & Conditions", heading_style))
+
+            terms = [
+                "This sanction is valid for {} days from the date of issue.".format(
+                    self.validity_days
+                ),
+                "The loan is subject to verification of all documents submitted.",
+                "Processing fee is non-refundable and payable upfront.",
+                "EMI will be deducted on the same date every month.",
+                "Prepayment charges may apply as per loan agreement.",
+                "Interest rate is fixed for the entire tenure of the loan.",
+                "This is a system-generated sanction letter and is valid without signature.",
+            ]
+
+            for i, term in enumerate(terms, 1):
+                term_text = f"{i}. {term}"
+                elements.append(Paragraph(term_text, normal_style))
+
+            elements.append(Spacer(1, 0.3 * inch))
+
+            # Next steps
+            elements.append(Paragraph("Next Steps", heading_style))
+            next_steps_text = """
+            Please submit the following documents to complete your loan processing:
+            <br/>• PAN Card<br/>
+            • Aadhaar Card<br/>
+            • Last 3 months salary slips<br/>
+            • Last 6 months bank statements<br/>
+            • Address proof<br/>
+            <br/>
+            Our loan officer will contact you within 2 business days to guide you through the documentation process.
+            """
+            elements.append(Paragraph(next_steps_text, normal_style))
+            elements.append(Spacer(1, 0.3 * inch))
+
+            # Footer
+            footer_style = ParagraphStyle(
+                "Footer",
+                parent=styles["Normal"],
+                fontSize=9,
+                textColor=colors.HexColor("#6b7280"),
+                alignment=1,  # Center
+            )
+
+            elements.append(Spacer(1, 0.5 * inch))
+            elements.append(
+                Paragraph(
+                    "This is a system-generated document and does not require a signature.",
+                    footer_style,
+                )
+            )
+            elements.append(
+                Paragraph(
+                    "For queries, contact us at support@finagent.com | +91-1800-XXX-XXXX",
+                    footer_style,
+                )
+            )
+            elements.append(
+                Paragraph(
+                    f"Generated on {datetime.utcnow().strftime('%B %d, %Y at %H:%M UTC')}",
+                    footer_style,
+                )
+            )
+
+            # Build PDF
+            doc.build(elements)
+
+            # Generate URL (in production, this would be a cloud storage URL)
+            pdf_url = f"/api/loan/{loan_id}/sanction-pdf"
+
+            logger.info(f"Generated sanction letter PDF: {filepath}")
+
+            return {"pdf_path": filepath, "pdf_url": pdf_url}
+
+        except Exception as e:
+            logger.error(f"Error generating PDF: {str(e)}")
+            raise
+
+    def get_pdf_path(self, loan_id: str) -> str:
+        """
+        Get the file path for a sanction letter PDF.
+
+        Args:
+            loan_id: Loan application ID
+
+        Returns:
+            Full file path to the PDF
+        """
+        filename = f"{loan_id}.pdf"
+        return os.path.join(self.output_dir, filename)
+
+    def pdf_exists(self, loan_id: str) -> bool:
+        """
+        Check if a sanction letter PDF exists.
+
+        Args:
+            loan_id: Loan application ID
+
+        Returns:
+            True if PDF exists, False otherwise
+        """
+        filepath = self.get_pdf_path(loan_id)
+        return os.path.exists(filepath)
+
+    def delete_pdf(self, loan_id: str) -> bool:
+        """
+        Delete a sanction letter PDF.
+
+        Args:
+            loan_id: Loan application ID
+
+        Returns:
+            True if deleted successfully, False otherwise
+        """
+        try:
+            filepath = self.get_pdf_path(loan_id)
+            if os.path.exists(filepath):
+                os.remove(filepath)
+                logger.info(f"Deleted PDF: {filepath}")
+                return True
+            return False
+        except Exception as e:
+            logger.error(f"Error deleting PDF: {str(e)}")
+            return False
+
+
+# Singleton instance
+pdf_service = PdfService()

app/services/session_service.py

@@ -0,0 +1,388 @@
+"""
+Session service for managing chat context and state.
+Maintains in-memory session data for chat conversations.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, Optional
+from uuid import uuid4
+
+from app.utils.logger import default_logger as logger
+
+
+class SessionService:
+    """Service for managing user chat sessions and context."""
+
+    def __init__(self):
+        """Initialize session service with in-memory storage."""
+        self._sessions: Dict[str, Dict[str, Any]] = {}
+        self._max_history = 20  # Maximum chat history items per session
+
+    def create_session(self, user_id: str) -> str:
+        """
+        Create a new chat session for a user.
+
+        Args:
+            user_id: User ID
+
+        Returns:
+            Session ID
+        """
+        session_id = str(uuid4())
+
+        self._sessions[session_id] = {
+            "session_id": session_id,
+            "user_id": user_id,
+            "current_step": "WELCOME",
+            "loan_details": {},
+            "chat_history": [],
+            "user_profile": None,
+            "created_at": datetime.utcnow(),
+            "updated_at": datetime.utcnow(),
+            "context": {},
+        }
+
+        logger.info(f"Created session {session_id} for user {user_id}")
+        return session_id
+
+    def get_session(self, session_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get session data by ID.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            Session data dict or None if not found
+        """
+        session = self._sessions.get(session_id)
+
+        if not session:
+            logger.warning(f"Session not found: {session_id}")
+            return None
+
+        return session
+
+    def update_session(self, session_id: str, updates: Dict[str, Any]) -> bool:
+        """
+        Update session data.
+
+        Args:
+            session_id: Session ID
+            updates: Dictionary of fields to update
+
+        Returns:
+            True if updated successfully, False if session not found
+        """
+        session = self._sessions.get(session_id)
+
+        if not session:
+            logger.warning(f"Cannot update, session not found: {session_id}")
+            return False
+
+        # Update fields
+        for key, value in updates.items():
+            if key != "session_id":  # Don't allow changing session_id
+                session[key] = value
+
+        session["updated_at"] = datetime.utcnow()
+
+        logger.info(f"Updated session {session_id}")
+        return True
+
+    def add_to_chat_history(self, session_id: str, role: str, content: str) -> bool:
+        """
+        Add a message to chat history.
+
+        Args:
+            session_id: Session ID
+            role: Message role (user/assistant/system)
+            content: Message content
+
+        Returns:
+            True if added successfully, False otherwise
+        """
+        session = self._sessions.get(session_id)
+
+        if not session:
+            logger.warning(f"Cannot add to history, session not found: {session_id}")
+            return False
+
+        # Add message to history
+        message = {
+            "role": role,
+            "content": content,
+            "timestamp": datetime.utcnow().isoformat(),
+        }
+
+        session["chat_history"].append(message)
+
+        # Trim history if it exceeds max length
+        if len(session["chat_history"]) > self._max_history:
+            session["chat_history"] = session["chat_history"][-self._max_history :]
+            logger.debug(f"Trimmed chat history for session {session_id}")
+
+        session["updated_at"] = datetime.utcnow()
+
+        return True
+
+    def get_chat_history(self, session_id: str) -> list:
+        """
+        Get chat history for a session.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            List of chat messages
+        """
+        session = self._sessions.get(session_id)
+
+        if not session:
+            return []
+
+        return session.get("chat_history", [])
+
+    def set_user_profile(self, session_id: str, user_profile: Dict[str, Any]) -> bool:
+        """
+        Store user profile in session.
+
+        Args:
+            session_id: Session ID
+            user_profile: User profile data
+
+        Returns:
+            True if set successfully, False otherwise
+        """
+        session = self._sessions.get(session_id)
+
+        if not session:
+            logger.warning(f"Cannot set profile, session not found: {session_id}")
+            return False
+
+        session["user_profile"] = user_profile
+        session["updated_at"] = datetime.utcnow()
+
+        logger.info(f"Set user profile for session {session_id}")
+        return True
+
+    def get_user_profile(self, session_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get user profile from session.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            User profile dict or None
+        """
+        session = self._sessions.get(session_id)
+
+        if not session:
+            return None
+
+        return session.get("user_profile")
+
+    def set_loan_details(self, session_id: str, loan_details: Dict[str, Any]) -> bool:
+        """
+        Store loan details in session.
+
+        Args:
+            session_id: Session ID
+            loan_details: Loan details data
+
+        Returns:
+            True if set successfully, False otherwise
+        """
+        session = self._sessions.get(session_id)
+
+        if not session:
+            logger.warning(f"Cannot set loan details, session not found: {session_id}")
+            return False
+
+        session["loan_details"] = loan_details
+        session["updated_at"] = datetime.utcnow()
+
+        logger.info(f"Set loan details for session {session_id}")
+        return True
+
+    def get_loan_details(self, session_id: str) -> Dict[str, Any]:
+        """
+        Get loan details from session.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            Loan details dict (empty if not set)
+        """
+        session = self._sessions.get(session_id)
+
+        if not session:
+            return {}
+
+        return session.get("loan_details", {})
+
+    def set_step(self, session_id: str, step: str) -> bool:
+        """
+        Set current conversation step.
+
+        Args:
+            session_id: Session ID
+            step: Step name (WELCOME, GATHERING_DETAILS, UNDERWRITING, etc.)
+
+        Returns:
+            True if set successfully, False otherwise
+        """
+        session = self._sessions.get(session_id)
+
+        if not session:
+            logger.warning(f"Cannot set step, session not found: {session_id}")
+            return False
+
+        session["current_step"] = step
+        session["updated_at"] = datetime.utcnow()
+
+        logger.info(f"Set step to {step} for session {session_id}")
+        return True
+
+    def get_step(self, session_id: str) -> str:
+        """
+        Get current conversation step.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            Current step name or "WELCOME" if not found
+        """
+        session = self._sessions.get(session_id)
+
+        if not session:
+            return "WELCOME"
+
+        return session.get("current_step", "WELCOME")
+
+    def set_context(self, session_id: str, key: str, value: Any) -> bool:
+        """
+        Set a context variable in the session.
+
+        Args:
+            session_id: Session ID
+            key: Context key
+            value: Context value
+
+        Returns:
+            True if set successfully, False otherwise
+        """
+        session = self._sessions.get(session_id)
+
+        if not session:
+            logger.warning(f"Cannot set context, session not found: {session_id}")
+            return False
+
+        if "context" not in session:
+            session["context"] = {}
+
+        session["context"][key] = value
+        session["updated_at"] = datetime.utcnow()
+
+        return True
+
+    def get_context(self, session_id: str, key: str, default: Any = None) -> Any:
+        """
+        Get a context variable from the session.
+
+        Args:
+            session_id: Session ID
+            key: Context key
+            default: Default value if not found
+
+        Returns:
+            Context value or default
+        """
+        session = self._sessions.get(session_id)
+
+        if not session:
+            return default
+
+        context = session.get("context", {})
+        return context.get(key, default)
+
+    def clear_session(self, session_id: str) -> bool:
+        """
+        Delete a session.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            True if deleted successfully, False if not found
+        """
+        if session_id in self._sessions:
+            del self._sessions[session_id]
+            logger.info(f"Cleared session {session_id}")
+            return True
+
+        logger.warning(f"Cannot clear, session not found: {session_id}")
+        return False
+
+    def get_or_create_session(self, session_id: str, user_id: str) -> str:
+        """
+        Get existing session or create new one if not found.
+
+        Args:
+            session_id: Session ID (can be None or empty)
+            user_id: User ID
+
+        Returns:
+            Session ID (existing or newly created)
+        """
+        if session_id and session_id in self._sessions:
+            return session_id
+
+        # Create new session
+        return self.create_session(user_id)
+
+    def get_session_count(self) -> int:
+        """
+        Get total number of active sessions.
+
+        Returns:
+            Number of sessions
+        """
+        return len(self._sessions)
+
+    def cleanup_old_sessions(self, max_age_hours: int = 24) -> int:
+        """
+        Clean up sessions older than specified hours.
+
+        Args:
+            max_age_hours: Maximum age in hours
+
+        Returns:
+            Number of sessions deleted
+        """
+        now = datetime.utcnow()
+        deleted = 0
+
+        # Find old sessions
+        old_sessions = []
+        for session_id, session in self._sessions.items():
+            age = now - session["updated_at"]
+            if age.total_seconds() > (max_age_hours * 3600):
+                old_sessions.append(session_id)
+
+        # Delete old sessions
+        for session_id in old_sessions:
+            del self._sessions[session_id]
+            deleted += 1
+
+        if deleted > 0:
+            logger.info(f"Cleaned up {deleted} old sessions")
+
+        return deleted
+
+
+# Singleton instance
+session_service = SessionService()

app/services/underwriting_service.py

@@ -0,0 +1,396 @@
+"""
+Underwriting service for loan decision logic.
+Implements credit evaluation and loan approval rules.
+"""
+
+import math
+from datetime import datetime
+from typing import Any, Dict
+
+from app.config import settings
+from app.utils.logger import default_logger as logger
+from app.utils.logger import log_underwriting_decision
+
+
+class UnderwritingService:
+    """Service for evaluating loan applications and making credit decisions."""
+
+    def __init__(self):
+        """Initialize underwriting service with configuration."""
+        self.interest_rate = settings.DEFAULT_INTEREST_RATE
+        self.min_loan_amount = settings.MIN_LOAN_AMOUNT
+        self.max_loan_amount = settings.MAX_LOAN_AMOUNT
+        self.min_tenure = settings.MIN_TENURE_MONTHS
+        self.max_tenure = settings.MAX_TENURE_MONTHS
+        self.excellent_credit_score = settings.EXCELLENT_CREDIT_SCORE
+        self.good_credit_score = settings.GOOD_CREDIT_SCORE
+        self.foir_threshold_a = settings.FOIR_THRESHOLD_A
+        self.foir_threshold_b = settings.FOIR_THRESHOLD_B
+
+    def evaluate_application(
+        self,
+        user_profile: Dict[str, Any],
+        requested_amount: float,
+        requested_tenure_months: int,
+    ) -> Dict[str, Any]:
+        """
+        Evaluate a loan application and make a credit decision.
+
+        Args:
+            user_profile: User profile with income and credit info
+            requested_amount: Requested loan amount
+            requested_tenure_months: Requested tenure in months
+
+        Returns:
+            Decision dict with approval status, amount, EMI, etc.
+        """
+        logger.info(
+            f"Evaluating loan: amount={requested_amount}, tenure={requested_tenure_months}"
+        )
+
+        # Extract user data
+        monthly_income = user_profile.get("monthly_income", 0)
+        existing_emi = user_profile.get("existing_emi", 0)
+        credit_score = user_profile.get("mock_credit_score", 650)
+        user_id = user_profile.get("user_id", "unknown")
+
+        # Validate basic requirements
+        validation_error = self._validate_loan_request(
+            requested_amount, requested_tenure_months, monthly_income
+        )
+        if validation_error:
+            return self._create_rejection_response(
+                user_id,
+                requested_amount,
+                requested_tenure_months,
+                credit_score,
+                0,
+                validation_error,
+            )
+
+        # Calculate EMI
+        emi = self._calculate_emi(requested_amount, requested_tenure_months)
+
+        # Calculate FOIR (Fixed Obligations to Income Ratio)
+        foir = self._calculate_foir(existing_emi, emi, monthly_income)
+
+        # Make decision based on credit score and FOIR
+        decision = self._make_decision(
+            credit_score,
+            foir,
+            requested_amount,
+            requested_tenure_months,
+            monthly_income,
+            existing_emi,
+        )
+
+        # Log decision
+        log_underwriting_decision(
+            logger,
+            user_id,
+            decision["decision"],
+            decision["approved_amount"],
+            credit_score,
+            foir,
+        )
+
+        return decision
+
+    def _validate_loan_request(
+        self, amount: float, tenure: int, monthly_income: float
+    ) -> str:
+        """
+        Validate basic loan request parameters.
+
+        Returns:
+            Error message if invalid, empty string if valid
+        """
+        if amount < self.min_loan_amount:
+            return f"Loan amount must be at least ₹{self.min_loan_amount:,.0f}"
+
+        if amount > self.max_loan_amount:
+            return f"Loan amount cannot exceed ₹{self.max_loan_amount:,.0f}"
+
+        if tenure < self.min_tenure:
+            return f"Tenure must be at least {self.min_tenure} months"
+
+        if tenure > self.max_tenure:
+            return f"Tenure cannot exceed {self.max_tenure} months"
+
+        if monthly_income <= 0:
+            return "Valid monthly income is required"
+
+        return ""
+
+    def _calculate_emi(self, principal: float, tenure_months: int) -> float:
+        """
+        Calculate EMI using reducing balance method.
+
+        Formula: EMI = P × r × (1 + r)^n / ((1 + r)^n - 1)
+        Where:
+            P = Principal loan amount
+            r = Monthly interest rate (annual rate / 12 / 100)
+            n = Tenure in months
+
+        Args:
+            principal: Loan amount
+            tenure_months: Loan tenure in months
+
+        Returns:
+            Monthly EMI amount
+        """
+        # Convert annual interest rate to monthly rate
+        monthly_rate = self.interest_rate / 12 / 100
+
+        # Calculate EMI using the standard formula
+        if monthly_rate == 0:
+            # If interest rate is 0, EMI is simply principal / tenure
+            emi = principal / tenure_months
+        else:
+            # Standard EMI calculation
+            emi = (
+                principal
+                * monthly_rate
+                * math.pow(1 + monthly_rate, tenure_months)
+                / (math.pow(1 + monthly_rate, tenure_months) - 1)
+            )
+
+        return round(emi, 2)
+
+    def _calculate_foir(
+        self, existing_emi: float, new_emi: float, monthly_income: float
+    ) -> float:
+        """
+        Calculate Fixed Obligations to Income Ratio.
+
+        FOIR = (Existing EMI + New EMI) / Monthly Income
+
+        Args:
+            existing_emi: Existing loan EMIs
+            new_emi: New loan EMI
+            monthly_income: Monthly income
+
+        Returns:
+            FOIR ratio (0.0 to 1.0)
+        """
+        if monthly_income <= 0:
+            return 1.0  # Maximum FOIR if income is invalid
+
+        total_obligations = existing_emi + new_emi
+        foir = total_obligations / monthly_income
+
+        return round(foir, 3)
+
+    def _make_decision(
+        self,
+        credit_score: int,
+        foir: float,
+        requested_amount: float,
+        requested_tenure: int,
+        monthly_income: float,
+        existing_emi: float,
+    ) -> Dict[str, Any]:
+        """
+        Make loan decision based on credit score and FOIR.
+
+        Decision Rules:
+        - Risk Band A (Excellent): Credit >= 720 AND FOIR <= 0.4
+          → APPROVED with full amount
+        - Risk Band B (Good): Credit >= 680 AND FOIR <= 0.5
+          → APPROVED with adjusted amount (80%) OR suggest lower amount
+        - Risk Band C (Poor): Otherwise
+          → REJECTED
+
+        Args:
+            credit_score: User's credit score
+            foir: Calculated FOIR
+            requested_amount: Requested loan amount
+            requested_tenure: Requested tenure
+            monthly_income: Monthly income
+            existing_emi: Existing EMIs
+
+        Returns:
+            Decision dictionary
+        """
+        # Risk Band A: Excellent - Full Approval
+        if (
+            credit_score >= self.excellent_credit_score
+            and foir <= self.foir_threshold_a
+        ):
+            return self._create_approval_response(
+                requested_amount,
+                requested_tenure,
+                credit_score,
+                foir,
+                "A",
+                f"Approved! Excellent credit score ({credit_score}) and healthy FOIR ({foir:.1%}). "
+                f"You qualify for the full amount with Risk Band A rating.",
+            )
+
+        # Risk Band B: Good - Conditional Approval or Adjustment
+        if credit_score >= self.good_credit_score and foir <= self.foir_threshold_b:
+            # If FOIR is slightly high, reduce the loan amount
+            if foir > self.foir_threshold_a:
+                # Calculate maximum affordable EMI
+                max_affordable_emi = (
+                    monthly_income * self.foir_threshold_a
+                ) - existing_emi
+
+                # Calculate maximum loan amount based on affordable EMI
+                monthly_rate = self.interest_rate / 12 / 100
+                if monthly_rate > 0:
+                    adjusted_amount = (
+                        max_affordable_emi
+                        * (math.pow(1 + monthly_rate, requested_tenure) - 1)
+                        / (monthly_rate * math.pow(1 + monthly_rate, requested_tenure))
+                    )
+                else:
+                    adjusted_amount = max_affordable_emi * requested_tenure
+
+                adjusted_amount = round(adjusted_amount, 2)
+
+                # Ensure adjusted amount is at least minimum
+                if adjusted_amount < self.min_loan_amount:
+                    return self._create_rejection_response(
+                        "unknown",
+                        requested_amount,
+                        requested_tenure,
+                        credit_score,
+                        foir,
+                        f"Your current FOIR ({foir:.1%}) is too high. "
+                        f"Maximum affordable loan amount (₹{adjusted_amount:,.0f}) "
+                        f"is below minimum requirement.",
+                    )
+
+                return self._create_adjustment_response(
+                    adjusted_amount,
+                    requested_tenure,
+                    credit_score,
+                    foir,
+                    "B",
+                    f"Approved with adjustment! Your credit score ({credit_score}) is good, "
+                    f"but your FOIR ({foir:.1%}) is slightly high. "
+                    f"We can approve ₹{adjusted_amount:,.0f} instead of ₹{requested_amount:,.0f} "
+                    f"to maintain healthy FOIR. Risk Band: B.",
+                )
+            else:
+                # Full approval for Risk Band B
+                return self._create_approval_response(
+                    requested_amount,
+                    requested_tenure,
+                    credit_score,
+                    foir,
+                    "B",
+                    f"Approved! Good credit score ({credit_score}) and acceptable FOIR ({foir:.1%}). "
+                    f"Risk Band B rating.",
+                )
+
+        # Risk Band C: Poor - Rejection
+        reasons = []
+        if credit_score < self.good_credit_score:
+            reasons.append(
+                f"credit score ({credit_score}) is below minimum requirement ({self.good_credit_score})"
+            )
+        if foir > self.foir_threshold_b:
+            reasons.append(
+                f"FOIR ({foir:.1%}) exceeds maximum threshold ({self.foir_threshold_b:.1%})"
+            )
+
+        explanation = (
+            f"Unfortunately, we cannot approve this loan because "
+            f"{' and '.join(reasons)}. "
+            f"Please improve your credit profile and try again."
+        )
+
+        return self._create_rejection_response(
+            "unknown",
+            requested_amount,
+            requested_tenure,
+            credit_score,
+            foir,
+            explanation,
+        )
+
+    def _create_approval_response(
+        self,
+        amount: float,
+        tenure: int,
+        credit_score: int,
+        foir: float,
+        risk_band: str,
+        explanation: str,
+    ) -> Dict[str, Any]:
+        """Create an approval decision response."""
+        emi = self._calculate_emi(amount, tenure)
+
+        return {
+            "decision": "APPROVED",
+            "approved_amount": amount,
+            "tenure_months": tenure,
+            "emi": emi,
+            "interest_rate": self.interest_rate,
+            "credit_score": credit_score,
+            "foir": foir,
+            "risk_band": risk_band,
+            "explanation": explanation,
+            "total_payable": round(emi * tenure, 2),
+            "processing_fee": round(amount * 0.02, 2),  # 2% processing fee
+        }
+
+    def _create_adjustment_response(
+        self,
+        adjusted_amount: float,
+        tenure: int,
+        credit_score: int,
+        foir: float,
+        risk_band: str,
+        explanation: str,
+    ) -> Dict[str, Any]:
+        """Create an adjustment decision response."""
+        emi = self._calculate_emi(adjusted_amount, tenure)
+
+        # Recalculate FOIR with adjusted amount
+        # Note: We don't have existing_emi here, so we use the provided foir
+        # In practice, you'd recalculate with actual existing_emi
+
+        return {
+            "decision": "ADJUST",
+            "approved_amount": adjusted_amount,
+            "tenure_months": tenure,
+            "emi": emi,
+            "interest_rate": self.interest_rate,
+            "credit_score": credit_score,
+            "foir": foir,
+            "risk_band": risk_band,
+            "explanation": explanation,
+            "total_payable": round(emi * tenure, 2),
+            "processing_fee": round(adjusted_amount * 0.02, 2),
+        }
+
+    def _create_rejection_response(
+        self,
+        user_id: str,
+        requested_amount: float,
+        tenure: int,
+        credit_score: int,
+        foir: float,
+        explanation: str,
+    ) -> Dict[str, Any]:
+        """Create a rejection decision response."""
+        return {
+            "decision": "REJECTED",
+            "approved_amount": 0.0,
+            "tenure_months": tenure,
+            "emi": 0.0,
+            "interest_rate": self.interest_rate,
+            "credit_score": credit_score,
+            "foir": foir,
+            "risk_band": "C",
+            "explanation": explanation,
+            "total_payable": 0.0,
+            "processing_fee": 0.0,
+        }
+
+
+# Singleton instance
+underwriting_service = UnderwritingService()

app/utils/__init__.py

@@ -0,0 +1,24 @@
+"""
+Utility modules for FinAgent backend.
+Contains logging, helpers, and common utilities.
+"""
+
+from app.utils.logger import (
+    default_logger,
+    log_agent_action,
+    log_error,
+    log_request,
+    log_response,
+    log_underwriting_decision,
+    setup_logger,
+)
+
+__all__ = [
+    "setup_logger",
+    "default_logger",
+    "log_request",
+    "log_response",
+    "log_error",
+    "log_agent_action",
+    "log_underwriting_decision",
+]

app/utils/logger.py

@@ -0,0 +1,227 @@
+"""
+Logging utility for structured logging across the application.
+Provides consistent logging format and helpers.
+"""
+
+import logging
+import sys
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+
+class ColoredFormatter(logging.Formatter):
+    """Custom formatter with colors for console output."""
+
+    # ANSI color codes
+    COLORS = {
+        "DEBUG": "\033[36m",  # Cyan
+        "INFO": "\033[32m",  # Green
+        "WARNING": "\033[33m",  # Yellow
+        "ERROR": "\033[31m",  # Red
+        "CRITICAL": "\033[35m",  # Magenta
+    }
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format log record with colors."""
+        # Add color to level name
+        levelname = record.levelname
+        if levelname in self.COLORS:
+            record.levelname = (
+                f"{self.COLORS[levelname]}{self.BOLD}{levelname}{self.RESET}"
+            )
+
+        # Format the message
+        formatted = super().format(record)
+
+        return formatted
+
+
+def setup_logger(
+    name: str = "finagent",
+    level: int = logging.INFO,
+    log_file: Optional[str] = None,
+) -> logging.Logger:
+    """
+    Set up a logger with console and optional file handlers.
+
+    Args:
+        name: Logger name
+        level: Logging level (default: INFO)
+        log_file: Optional path to log file
+
+    Returns:
+        Configured logger instance
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+
+    # Prevent duplicate handlers
+    if logger.handlers:
+        return logger
+
+    # Console handler with colors
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(level)
+    console_formatter = ColoredFormatter(
+        fmt="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    console_handler.setFormatter(console_formatter)
+    logger.addHandler(console_handler)
+
+    # File handler (optional)
+    if log_file:
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setLevel(level)
+        file_formatter = logging.Formatter(
+            fmt="%(asctime)s | %(levelname)s | %(name)s | %(funcName)s:%(lineno)d | %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        file_handler.setFormatter(file_formatter)
+        logger.addHandler(file_handler)
+
+    return logger
+
+
+def log_request(
+    logger: logging.Logger,
+    method: str,
+    path: str,
+    user_id: Optional[str] = None,
+    **kwargs: Any,
+) -> None:
+    """
+    Log an API request with structured data.
+
+    Args:
+        logger: Logger instance
+        method: HTTP method
+        path: Request path
+        user_id: Optional user ID
+        **kwargs: Additional context data
+    """
+    context = {
+        "method": method,
+        "path": path,
+        "user_id": user_id,
+        "timestamp": datetime.utcnow().isoformat(),
+        **kwargs,
+    }
+    logger.info(f"Request: {method} {path}", extra={"context": context})
+
+
+def log_response(
+    logger: logging.Logger,
+    method: str,
+    path: str,
+    status_code: int,
+    duration_ms: float,
+    **kwargs: Any,
+) -> None:
+    """
+    Log an API response with structured data.
+
+    Args:
+        logger: Logger instance
+        method: HTTP method
+        path: Request path
+        status_code: HTTP status code
+        duration_ms: Request duration in milliseconds
+        **kwargs: Additional context data
+    """
+    context = {
+        "method": method,
+        "path": path,
+        "status_code": status_code,
+        "duration_ms": round(duration_ms, 2),
+        "timestamp": datetime.utcnow().isoformat(),
+        **kwargs,
+    }
+    logger.info(
+        f"Response: {method} {path} - {status_code} ({duration_ms:.2f}ms)",
+        extra={"context": context},
+    )
+
+
+def log_error(
+    logger: logging.Logger,
+    error: Exception,
+    context: Optional[Dict[str, Any]] = None,
+) -> None:
+    """
+    Log an error with structured context.
+
+    Args:
+        logger: Logger instance
+        error: Exception instance
+        context: Optional context dictionary
+    """
+    error_context = {
+        "error_type": type(error).__name__,
+        "error_message": str(error),
+        "timestamp": datetime.utcnow().isoformat(),
+        **(context or {}),
+    }
+    logger.error(
+        f"Error: {type(error).__name__}: {str(error)}",
+        extra={"context": error_context},
+        exc_info=True,
+    )
+
+
+def log_agent_action(
+    logger: logging.Logger, action: str, details: Dict[str, Any]
+) -> None:
+    """
+    Log an agent action (tool call, decision, etc.).
+
+    Args:
+        logger: Logger instance
+        action: Action name/type
+        details: Action details
+    """
+    context = {
+        "action": action,
+        "timestamp": datetime.utcnow().isoformat(),
+        **details,
+    }
+    logger.info(f"Agent Action: {action}", extra={"context": context})
+
+
+def log_underwriting_decision(
+    logger: logging.Logger,
+    user_id: str,
+    decision: str,
+    amount: float,
+    credit_score: int,
+    foir: float,
+) -> None:
+    """
+    Log an underwriting decision with key metrics.
+
+    Args:
+        logger: Logger instance
+        user_id: User ID
+        decision: Decision (APPROVED/REJECTED/ADJUST)
+        amount: Approved amount
+        credit_score: Credit score
+        foir: FOIR ratio
+    """
+    context = {
+        "user_id": user_id,
+        "decision": decision,
+        "approved_amount": amount,
+        "credit_score": credit_score,
+        "foir": round(foir, 3),
+        "timestamp": datetime.utcnow().isoformat(),
+    }
+    logger.info(
+        f"Underwriting Decision: {decision} for user {user_id}",
+        extra={"context": context},
+    )
+
+
+# Default logger instance
+default_logger = setup_logger()

requirements.txt

@@ -0,0 +1,34 @@
+# FastAPI and Web Framework
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+python-multipart==0.0.6
+pydantic==2.5.0
+pydantic-settings==2.1.0
+
+# LangChain and AI
+langchain==0.1.0
+langchain-core==0.1.0
+langchain-google-genai==0.0.5
+google-generativeai==0.3.1
+
+# Firebase
+firebase-admin==6.3.0
+google-cloud-firestore==2.13.1
+
+# PDF Generation
+reportlab==4.0.7
+
+# Utilities
+python-dotenv==1.0.0
+typing-extensions==4.9.0
+
+# Date and Time
+python-dateutil==2.8.2
+
+# HTTP Client (for testing)
+httpx==0.25.2
+
+# Development Tools (optional)
+pytest==7.4.3
+pytest-asyncio==0.21.1
+black==23.12.0

sanctions/.gitkeep

@@ -0,0 +1,2 @@
+# This file ensures the sanctions directory is tracked by git
+# PDF files will be generated in this directory at runtime