Gulosa - Loyalty Management Agent

Overview

Gulosa is the Loyalty Management agent in the TKM AI Agency Platform, responsible for managing the points system, referral program, and reward mechanisms. It handles point tracking, referral processing, and reward distribution across the platform.

Directory Structure

Backend/Backoffice/Gulosa/
├── data/                # Points and referral data
├── gulosa.py           # Main agent implementation
├── api_gulosa.py       # FastAPI endpoints
├── points_rules.py     # Points calculation rules
├── tools.py            # Loyalty utilities
├── tools_schema.py     # Data models and schemas
└── test_gulosa.py      # Unit tests

Main Components

GulosaAgent Class

The core component that handles loyalty operations:

• Points management
• Referral processing
• Reward distribution
• Action tracking

Processing Pipeline

1. Points Management

   • Balance tracking
   • Points calculation
   • Transaction logging
   • Expiration handling

2. Referral Processing

   • QR code generation
   • Referral validation
   • Points assignment
   • Status tracking

3. Reward Management

   • Reward catalog
   • Points redemption
   • Reward delivery
   • History tracking

Key Features

Points System

• Balance tracking
• Points calculation
• Transaction history
• Expiration management

Referral Program

• QR code generation
• Referral tracking
• Points distribution
• Program analytics

Reward Management

• Reward catalog
• Points redemption
• Delivery tracking
• Status updates

Action Tracking

• User activities
• Points history
• Referral status
• Reward claims

Integration

Database Connection

• SingleStore integration
• Transaction management
• History tracking
• Data archival

Event System

• Points updates
• Referral events
• Reward claims
• Status changes

External Services

• QR code generation
• Email notifications
• Payment processing
• Delivery tracking

Error Handling

Transaction Errors

• Points calculation
• Referral validation
• Reward redemption
• Balance updates

Recovery Mechanisms

• Transaction rollback
• Point reconciliation
• Status recovery
• Error notification

Integration with Other Agents

Core Dependencies

• Niger: Data persistence
• Barbatus: Authentication
• Lyra: Notifications
• Messor: Receipt processing

Optional Integration

• Alfari: Configuration
• Gigantea: Feedback processing
• Sessile: Cache management