credit-card-advisor

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

credit-card-advisor

★ 14 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Hệ thống Tư vấn Thẻ tín dụng với LangGraph và Amazon Bedrock

Ứng dụng multi-agent sử dụng LangGraph và Amazon Bedrock (Anthropic Claude Sonnet 3.7) để tư vấn thẻ tín dụng phù hợp dựa trên hồ sơ khách hàng với giao diện Streamlit. Hệ thống được xây dựng với kiến trúc workflow hoàn chỉnh, xử lý lỗi toàn diện và khả năng phục hồi tự động.

## Cấu trúc dự án

```
credit_card_advisor/
├── streamlit_app.py                    # Giao diện Streamlit chính với tích hợp workflow
├── langgraph_workflow.py               # LangGraph workflow hoàn chỉnh với error handling
├── enhanced_logging.py                 # Hệ thống logging và error recovery nâng cao
├── enhanced_streamlit_workflow.py      # Enhanced workflow wrapper cho Streamlit
├── app.py                              # Ứng dụng console (legacy)
├── demo_app.py                         # Demo với dữ liệu mẫu
├── agents/                             # Các agent chuyên biệt
│   ├── __init__.py
│   ├── customer_profile_agent.py       # Agent phân tích hồ sơ khách hàng
│   ├── credit_card_knowledge_agent.py  # Agent kiến thức về thẻ tín dụng
│   └── recommendation_agent.py         # Agent đề xuất thẻ tín dụng
├── data/
│   └── credit_cards.json               # Dữ liệu thẻ tín dụng
├── utils/
│   ├── __init__.py
│   └── aws_config.py                   # Cấu hình AWS Bedrock
├── tests/                              # Test files và validation scripts
│   ├── test_*.py                       # Various test files
│   ├── verify_demo_values.py           # Demo validation
│   └── README.md                       # Test documentation
├── scripts/                            # Utility scripts
│   ├── clear_streamlit_cache.py        # Cache management
│   └── README.md                       # Scripts documentation
├── docs/                               # Documentation files
│   ├── *.md                           # Various documentation
│   └── README.md                       # Documentation index
├── logs/                               # Log files và reports
│   ├── test_error_recovery_integration.py # Error recovery tests
│   ├── test_error_handling.py          # Error handling tests
│   ├── test_complete_integration.py    # Complete system tests
│   ├── test_streamlit_integration.py   # Streamlit integration tests
│   └── run_all_integration_tests.py    # Test runner tổng hợp
└── .kiro/                              # Kiro IDE configuration và specs
    └── specs/langgraph-workflow-implementation/
        ├── requirements.md             # Chi tiết requirements
        ├── design.md                   # Thiết kế hệ thống
        └── tasks.md                    # Implementation tasks
```

## Cài đặt

### 1. Tạo môi trường Python

#### Sử dụng venv (khuyến nghị):

```bash
# Tạo môi trường ảo
python -m venv credit_card_env

# Kích hoạt môi trường ảo
# Trên macOS/Linux:
source credit_card_env/bin/activate
# Trên Windows:
# credit_card_env\Scripts\activate
```

### 2. Cài đặt các thư viện cần thiết:

```bash
pip install -r requirements.txt
```

### 3. Thiết lập AWS credentials:

```bash
aws configure
```

Hoặc thiết lập biến môi trường:

```bash
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1
```

## Sử dụng

### 🚀 Quick Start

```bash
# Chạy demo chính
streamlit run streamlit_app.py --server.port 8080

# Chạy tests
python run_tests.py

# Validation nhanh
python run_tests.py --quick
```

### 🤖 Multi-Agent Demo UI

```bash
# Chạy Streamlit demo với multi-agent features
streamlit run streamlit_app.py --server.port 8080
```

**🎯 Tính năng Demo Multi-Agent:**
- 🎛️ **Agent Dashboard**: Theo dõi trạng thái real-time của từng agent
- 🔄 **Workflow Visualization**: Xem tiến trình workflow qua từng bước  
- 💬 **Agent Communication Log**: Theo dõi tương tác giữa các agent
- 🎮 **Quick Demo Scenarios**: Test nhanh với data mẫu (Nhân viên văn phòng, Sinh viên, Doanh nhân)
- 🎭 **Demo Mode**: Bật/tắt để xem chi tiết agent interactions

### Giao diện Console
```

Mở trình duyệt và truy cập `http://localhost:8080`

### Ứng dụng Console

```bash
python app.py
```

## Kiến trúc LangGraph Workflow

### Workflow Architecture

Hệ thống sử dụng LangGraph để quản lý workflow với 4 node chính:

```mermaid
graph TD
    A[START] --> B[analyze_profile]
    B --> C[filter_cards]
    C --> D[recommend_cards]
    D --> E[explain_recommendation]
    E --> F[END]
    
    B --> G[Error Handler]
    C --> G
    D --> G
    E --> G
    G --> F
```

### Workflow Steps:

#### 1. **analyze_profile**
- Phân tích thông tin khách hàng sử dụng CustomerProfileAgent
- Ước tính điểm tín dụng và khả năng tài chính
- Xác định mức độ rủi ro và thói quen chi tiêu
- **Fallback**: Sử dụng profile mặc định nếu agent không khả dụng

#### 2. **filter_cards**
- Lọc thẻ tín dụng phù hợp sử dụng CreditCardKnowledgeAgent
- Áp dụng tiêu chí dựa trên profile khách hàng
- Điều chỉnh ngưỡng phí dựa trên khả năng tài chính
- **Fallback**: Trả về danh sách rỗng nếu không tìm thấy thẻ phù hợp

#### 3. **recommend_cards**
- Tạo đề xuất thẻ tín dụng sử dụng RecommendationAgent
- Xếp hạng thẻ theo mức độ phù hợp
- Tạo lý do và lợi ích cho từng đề xuất
- **Fallback**: Sử dụng thuật toán đề xuất cơ bản

#### 4. **explain_recommendation**
- Tạo giải thích chi tiết cho đề xuất
- Phân tích lý do tại sao thẻ phù hợp với khách hàng
- Cung cấp lời khuyên sử dụng thẻ
- **Fallback**: Tạo giải thích cơ bản dựa trên template

### Enhanced State Management:

```python
class CreditCardAdvisorState(TypedDict):
    customer_info: Dict[str, Any]          # Thông tin đầu vào
    customer_profile: Dict[str, Any]       # Hồ sơ tài chính đã phân tích
    available_cards: List[Dict[str, Any]]  # Danh sách thẻ phù hợp
    recommendations: Dict[str, Any]        # Đề xuất cuối cùng
    explanation: str                       # Giải thích chi tiết
    status: str                           # Trạng thái workflow
    error_message: Optional[str]          # Thông tin lỗi (nếu có)
```

### Error Handling và Recovery:

- **Retry Logic**: Tự động thử lại với exponential backoff
- **Fallback Mechanisms**: Sử dụng phương pháp dự phòng khi agent thất bại
- **Graceful Degradation**: Hệ thống tiếp tục hoạt động ngay cả khi một số thành phần lỗi
- **User-Friendly Errors**: Thông báo lỗi bằng tiếng Việt với hướng dẫn khắc phục

## Các agent

### Customer Profile Agent
- Phân tích thông tin khách hàng
- Xác định nhu cầu tài chính
- Ước tính điểm tín dụng và khả năng tài chính

### Credit Card Knowledge Agent
- Cung cấp thông tin về các loại thẻ tín dụng
- Lọc thẻ theo tiêu chí
- So sánh các thẻ tín dụng

### Recommendation Agent
- Đề xuất thẻ tín dụng phù hợp
- Giải thích lý do đề xuất
- Cung cấp lời khuyên sử dụng thẻ

## Amazon Bedrock

Ứng dụng này sử dụng Amazon Bedrock với model Anthropic Claude Sonnet 3.7. Để sử dụng Amazon Bedrock, bạn cần:

1. Có tài khoản AWS với quyền truy cập vào Amazon Bedrock
2. Đảm bảo model Anthropic Claude đã được kích hoạt trong tài khoản của bạn
3. Có IAM role hoặc user với quyền truy cập vào Bedrock API

## Tính năng nâng cao

### 🔄 LangGraph Workflow Integration
- **State Management**: Quản lý trạng thái workflow với TypedDict
- **Error Recovery**: Cơ chế phục hồi tự động với retry logic
- **Fallback Mechanisms**: Phương pháp dự phòng cho tất cả các thành phần
- **Session Tracking**: Theo dõi từng phiên làm việc với unique session ID
- **Performance Monitoring**: Đo lường thời gian thực thi và metrics

### 🎯 Enhanced Error Handling
- **Categorized Error Types**: Phân loại lỗi (AWS, JSON, Network, Validation)
- **User-Friendly Messages**: Thông báo lỗi bằng tiếng Việt với hướng dẫn
- **Automatic Recovery**: Tự động khôi phục từ lỗi tạm thời
- **Comprehensive Logging**: Ghi log chi tiết cho debugging và monitoring

### 🖥️ Streamlit UI Enhancements
- **Real-time Status Updates**: Cập nhật trạng thái workflow theo thời gian thực
- **Progress Tracking**: Thanh tiến trình và status indicators
- **System Diagnostics**: Công cụ chẩn đoán hệ thống tích hợp
- **Export Functionality**: Xuất kết quả dưới dạng JSON
- **Enhanced Error Display**: Hiển thị lỗi với hướng dẫn khắc phục

### 📊 Comprehensive Testing
- **Integration Tests**: 20+ test cases cho workflow integration
- **Error Recovery Tests**: Kiểm tra khả năng phục hồi từ lỗi
- **Performance Tests**: Đánh giá hiệu suất và memory usage
- **Concurrent Execution Tests**: Kiểm tra khả năng xử lý đồng thời
- **Robustness Tests**: Kiểm tra với dữ liệu edge cases

### 🔍 Advanced Logging và Monitoring
- **Structured Logging**: JSON-formatted logs với multiple handlers
- **Session-based Tracking**: Theo dõi từng workflow execution
- **Performance Metrics**: Đo lường execution time cho từng node
- **Error Analytics**: Phân tích và categorize các loại lỗi
- **Health Checks**: Kiểm tra trạng thái hệ thống tự động

## Testing và Quality Assurance

### Chạy Test Suite

#### Chạy tất cả integration tests:
```bash
python run_all_integration_tests.py
```

#### Chạy từng loại test riêng biệt:
```bash
# Core workflow integration tests
python test_workflow_integration.py

# Error recovery tests
python test_error_recovery_integration.py

# Enhanced error handling tests
python test_error_handling.py

# Complete system integration tests
python test_complete_integration.py

# Streamlit integration tests
python test_streamlit_integration.py
```

### Test Coverage

- **Core Workflow**: 20 test cases covering workflow initialization, state management, validation
- **Error Recovery**: 15+ test cases covering agent failures, network issues, JSON parsing errors
- **Performance**: Memory usage stability, execution time validation, concurrent execution
- **Robustness**: Edge cases, unicode handling, large data processing

### Deployment Validation

#### 1. Kiểm tra System Health:
```python
from langgraph_workflow import CreditCardAdvisorWorkflow

workflow = CreditCardAdvisorWorkflow()
status = workflow.get_workflow_status()
print(status)
```

#### 2. Chạy Diagnostics:
```python
diagnostics = workflow.run_workflow_diagnostics({
    "name": "Test User",
    "age": 30,
    "monthly_income": 20000000,
    "credit_score": 700
})
print(diagnostics)
```

#### 3. Validate Configuration:
```python
validation = workflow.validate_workflow_configuration()
if validation['valid']:
    print("✅ System ready for deployment")
else:
    print("❌ Configuration issues:", validation['issues'])
```

## Production Deployment

### AWS Requirements
- AWS Account với quyền truy cập Amazon Bedrock
- IAM Role/User với permissions:
  - `bedrock:InvokeModel`
  - `bedrock:GetFoundationModel`
- Model Anthropic Claude Sonnet 3.7 được activate

### Environment Variables
```bash
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1
export MODEL_ID=anthropic.claude-3-sonnet-20240229-v1:0
```

### Docker Deployment (Optional)
```dockerfile
FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 8080
CMD ["streamlit", "run", "streamlit_app.py", "--server.port=8080", "--server.address=0.0.0.0"]
```

### Health Check Endpoint
Hệ thống cung cấp health check thông qua workflow diagnostics:
```python
# Health check script
def health_check():
    try:
        workflow = CreditCardAdvisorWorkflow()
        validation = workflow.validate_workflow_configuration()
        return validation['valid']
    except Exception:
        return False
```

## Monitoring và Logging

### Log Files
- `workflow_execution.log`: Chi tiết execution của workflow
- `workflow_errors.log`: Chỉ các lỗi và exceptions
- Console output: Thông tin general và status updates

### Metrics Tracking
- Execution time cho từng workflow node
- Success/failure rates
- Error categorization và frequency
- Session tracking và user analytics

## Troubleshooting

### Common Issues

#### 1. AWS Credentials Error
```
Error: NoCredentialsError: Unable to locate credentials
```
**Solution**: Kiểm tra AWS credentials configuration

#### 2. Model Not Available
```
Error: ValidationException: The model ID is not supported
```
**Solution**: Đảm bảo Anthropic Claude model đã được activate trong AWS Bedrock

#### 3. Network Timeout
```
Error: TimeoutError: Request timed out
```
**Solution**: Kiểm tra kết nối internet và AWS region settings

### Debug Mode
Để enable debug logging:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

## Mở rộng và Customization

### Thêm Agent mới
1. Tạo agent class trong `agents/` directory
2. Implement required methods
3. Integrate vào workflow trong `langgraph_workflow.py`
4. Thêm tests trong `tests/` directory

### Thêm Workflow Node
1. Define node function trong `CreditCardAdvisorWorkflow`
2. Add node vào workflow graph
3. Update state management nếu cần
4. Thêm error handling và fallback logic

### Custom Error Handling
1. Extend `ErrorRecoveryManager` trong `enhanced_logging.py`
2. Add custom error types và recovery strategies
3. Update user-friendly error messages

### Tích hợp External APIs
1. Thêm API client trong `utils/` directory
2. Implement caching và rate limiting
3. Add error handling cho API failures
4. Update tests để cover API integration

credit-card-advisor

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README