LangGraph Refund Decision Bot

A sophisticated refund processing system built with LangGraph that follows a structured Mermaid decision tree for accurate and transparent refund decisions.

Features

• LangGraph Workflow: Structured workflow management with visual decision paths
• Mermaid Decision Tree: Exact implementation of business rules in flowchart format
• State Management: Comprehensive conversation state tracking
• Information Extraction: AI-powered extraction and validation of user information
• Multiple Decision Paths: Handles all refund scenarios with proper routing
• Transparent Processing: Clear decision path tracking and reasoning

Project Structure

LG/
├── config/
│   ├── config.py           # Configuration management
│   └── .env                # Environment variables
├── data/
│   └── customer_data.json  # Sample customer data
├── src/
│   ├── state.py           # State schema and management
│   ├── mermaid_tree.py    # Decision tree structure
│   ├── extraction.py      # Information extraction
│   ├── decision_nodes.py  # Individual decision nodes
│   ├── workflow.py        # LangGraph workflow
│   └── bot.py            # Main conversation interface
├── main.py               # Application entry point
├── requirements.txt      # Dependencies
└── README.md            # This file

Decision Tree Coverage

The bot handles the following decision points from the Mermaid chart:

1. Account Status Check: Validates customer account standing
2. Loyalty Tier Routing: Bronze/Silver vs Gold customer paths
3. Fraud Flag Check: Additional validation for Gold customers
4. Return Abuse Detection: Identifies customers who abuse returns
5. Item Category Classification: Physical/Digital/Perishable items
6. Return Eligibility: Checks if item is marked as returnable
7. Item Condition Assessment: Damaged/Defective/Normal condition
8. Return Window Validation: Within/Expired timing checks
9. Delivery Status: Delivered vs undelivered items
10. Shipping Issue Handling: Lost/Delayed/Neither scenarios
11. Seller Type Routing: In-house vs Third-party sellers
12. Policy Compliance: Various policy checks
13. Payment Method Processing: CreditCard/GiftCard/BNPL/Prepaid

Terminal Decisions

• RefundApproved: Standard approval
• RefundDenied1-12: Various denial reasons
• PartialRefund: Late return or gift card scenarios
• ManualReview: Requires human intervention

Installation

1. Clone or download the project
2. Install dependencies:

   pip install -r requirements.txt

3. Configure environment variables in config/.env:

   OPENAI_API_KEY=your_openai_api_key_here
   MODEL_NAME=gpt-4o-mini
   DEBUG_MODE=True
   

Usage

Run the bot:

python main.py

Example Interactions

Basic Refund Request:

You: I want to return my broken laptop
Bot: What type of item are you returning? Please specify: Physical, Digital, or Perishable.
You: Physical
Bot: Is this item marked as returnable? Please specify: Yes or No.
You: Yes
Bot: [Processing through decision tree...]
Bot: [APPROVED] Decision: RefundApproved

Complex Scenario:

You: I need a refund for software I bought with a gift card
Bot: What type of item are you returning? Please specify: Physical, Digital, or Perishable.
You: Digital
Bot: [DENIED] Decision: RefundDenied4
Reason: Digital goods not refundable

System Commands

• status - Show current workflow status and decision path
• reset - Start a new conversation
• export - Save conversation history to JSON
• debug - Show detailed state information
• help - Show comprehensive help
• quit - Exit the system

Configuration

Environment Variables

• OPENAI_API_KEY: Your OpenAI API key (required)
• MODEL_NAME: OpenAI model to use (default: gpt-4o-mini)
• EXTRACTION_TEMPERATURE: Temperature for information extraction (default: 0.5)
• NAVIGATION_TEMPERATURE: Temperature for decision navigation (default: 0.0)
• QUESTION_TEMPERATURE: Temperature for question generation (default: 0.3)
• DEBUG_MODE: Enable debug output (default: True)

Customer Data

Modify data/customer_data.json to test different customer scenarios:

{
  "customer_id": "CUST_67890",
  "account_status": "good_standing",
  "loyalty_tier": "Gold",
  "fraud_flag": "No",
  "return_abuse": "No"
}

Architecture

LangGraph Workflow

The system uses LangGraph to create a structured workflow that mirrors the Mermaid decision tree:

1. Entry Point: Load customer data and extract information
2. Decision Nodes: Individual nodes for each decision point
3. Conditional Routing: Smart routing based on extracted information
4. Terminal Nodes: Final decision points
5. Question Generation: Dynamic question creation for missing information

State Management

Comprehensive state tracking includes:

• User conversation history
• Extracted information
• Customer data
• Decision path tracking
• Current workflow status

Information Extraction

AI-powered extraction with:

• Natural language understanding
• Context-aware mapping
• Validation against valid keywords
• Fallback pattern matching