FinAgentX

FinAgentX is a remote banking system designed to revolutionize the loan application process. It specifically targets tier 2 and tier 3 cities in India, enabling users to apply for loans seamlessly through a web interface. The system leverages a powerful multi-agent AI architecture to automate data collection, underwriting, and decision-making, providing a streamlined and efficient experience for both customers and bank officials.

🏗 Project Structure

The project is divided into four main components, each handling a specific aspect of the application:

1. Frontend (/frontend)

The core user interface for the banking portal. It provides the landing page and navigation to various services.

• Tech: HTML, CSS, JavaScript
• Key Files:
  • index.html: Main landing page for the bank.
  • chat.html: Interface for chatting with the AI agent.
  • status.html: Page for tracking loan application status.
  • documents.html: Document upload and management interface.

2. Avatar Interface (/avatar)

A visual, interactive 3D avatar that acts as the customer service representative, enhancing user engagement.

• Tech: React, Vite, React Three Fiber (R3F), Socket.io-client
• Key Features:
  • Real-time lip-sync and animation.
  • Interactive 3D environment.
  • Integration with the backend for dynamic responses.

3. Node.js Backend (/backend)

The primary server handling real-time communication, API orchestration, and bridging the frontend with the AI logic.

• Tech: Node.js, Express, Socket.io
• Key Features:
  • Handles WebSocket connections for the Avatar and Chat.
  • Integrates with text-to-speech and speech-to-text services.
  • Routes requests between the frontend and the AI agents.
  • Dependencies: google-generative-ai, groq-sdk, socket.io, express.

4. Python Agent Backend (/python_backend)

The intelligence layer powered by CrewAI, running autonomous agents for complex financial tasks.

• Tech: Python, Flask, CrewAI, LangChain
• Key Features:
  • Underwriter Agent: Analyzes creditworthiness and risk.
  • Verification Agent: Validates documents and user data.
  • Loan Officer Agent: Makes final approval/rejection decisions.
  • Dependencies: crewai, flask, langchain_google_genai, python-dotenv.

---

🚀 Installation & Setup

To run FinAgentX locally, you need to set up and run all three server components (Node.js Backend, Python Backend, and Avatar Frontend).

Prerequisites

• Node.js (v18 or higher)
• Python (v3.10 or higher)
• API Keys:
  • Google Gemini API Key
  • Groq API Key
  • (Any other specific keys used in .env)

Step 1: Python Backend Setup

This service handles the AI agents.

1. Navigate to the directory:

   cd python_backend

2. Create a virtual environment (optional but recommended):

   python -m venv venv
   # Windows
   venv\Scripts\activate
   # macOS/Linux
   source venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure Environment Variables:
   • Create a .env file in python_backend/.
   • Add your keys:

     GOOGLE_API_KEY=your_google_key

5. Start the server:

   python app.py

   Runs on default Flask port (usually 5000).

Step 2: Node.js Backend Setup

This service handles real-time socket communication.

1. Navigate to the directory:

   cd backend

2. Install dependencies:

   npm install

3. Configure Environment Variables:
   • Create a .env file in backend/ if required by the code (check server.js).
4. Start the server:

   npm start

   Runs on port specified in server.js (e.g., 3000).

Step 3: Avatar Frontend Setup

This serves the React application for the 3D Avatar.

1. Navigate to the directory:

   cd avatar

2. Install dependencies:

   npm install

3. Start the development server:

   npm run dev

   Runs on http://localhost:5173 (default Vite port).

Step 4: Accessing the Application

1. Open the Frontend files directly. You can typically just open frontend/index.html in your browser.
2. For a better experience, use a live server extension (like VS Code Live Server) to serve the frontend directory.
3. Ensure the frontend is configured to point to the correct backend URLs (check script.js or similar in frontend for API endpoints).

---

💡 Usage Workflow

1. Landing Page: Open index.html. Users are introduced to the banking platform.
2. Chat/Avatar: Navigate to the chat section. The 3D Avatar (served from port 5173) should load (likely via iframe or separate window).
3. Interaction:
   • User types or speaks to the agent.
   • Node.js Backend receives the input -> forwards to Python Backend (CrewAI) or processes it directly.
   • CrewAI Agents process the request (e.g., "I want a loan").
   • Response is sent back to Node.js Backend -> Frontend/Avatar.
   • Avatar speaks the response using lip-sync.
4. Loan Application: The agents guide the user through document submission (documents.html) and status checking (status.html).

📊 System Architecture

The following flowchart illustrates the data flow and interaction between the system components:

graph TD
    User((User))
    
    subgraph Client [Frontend / Avatar]
        UI[Web Interface]
        Avatar3D[3D Avatar]
    end
    
    subgraph NodeServer [Node.js Backend]
        SocketHandler[Socket.io Handler]
        Master[Master Agent (LLM)]
        Rules[Rule Engine]
        Dispatcher[Dispatcher]
        Sanction[Sanction Agent]
    end
    
    subgraph PythonServer [Python Backend]
        FlaskAPI[Flask API :8000]
        Crew[CrewAI Manager]
        Sales[Sales Agent]
        Verify[Verification Agent]
        Underwrite[Underwriting Agent]
    end

    User <-->|Voice/Text| UI
    UI <-->|WebSocket| SocketHandler
    Avatar3D <-->|WebSocket| SocketHandler

    SocketHandler -->|1. Text Input| Master
    Master -->|2. Generate Plan| Rules
    Rules -->|3. Validate Plan| Dispatcher
    
    Dispatcher -->|Local Call| Sanction
    Dispatcher -->|HTTP POST| FlaskAPI
    
    FlaskAPI -->|Run Task| Crew
    Crew --> Sales
    Crew --> Verify
    Crew --> Underwrite
    
    Crew -->|Result| FlaskAPI
    FlaskAPI -->|JSON Response| Dispatcher
    
    Dispatcher -->|Synthesize Reply| SocketHandler
    SocketHandler -->|Final Response/Audio| UI

Loading

🤝 Contributing

Feel free to submit issues and enhancement requests.

📄 License

[Your License Here]