Backend
Backoffice
Vulcan

Vulcan Agent Documentation

Overview

The Vulcan agent is responsible for managing the redemption gifts system within the TKM AI Agency Platform. It handles the creation, retrieval, updating, and deletion of gifts that users can redeem with their loyalty points. The agent supports various types of gifts including mobile top-ups, electronic pins, and service payments.

Directory Structure

Backend/
└── AI_Agency/
    └── Backoffice/
        └── Vulcan/
            ├── __init__.py
            ├── vulcan.py              # Main agent implementation
            ├── api_vulcan.py          # FastAPI endpoints
            └── vulcan_tools.py        # Helper functions and utilities

Main Components

VulcanAgent Class

The VulcanAgent class is the core component responsible for managing redemption gifts. It provides methods for:

  • Retrieving all available gifts
  • Getting specific gift details
  • Creating new gifts
  • Updating existing gifts
  • Deleting gifts
  • Validating gift data based on gift type

Key Features

Gift Management

The agent supports different types of gifts:

  1. Mobile Top-ups

    • Required fields: telco_supplier, recharge_amount, points_value
    • Used for mobile phone credit recharges

  2. Electronic Pins

    • Required fields: supplier, electronic_pin_amount, points_value
    • Used for digital gift cards and codes

  3. Service Payments

    • Required fields: service_provider
    • Used for utility and service bill payments

Data Validation

The agent performs validation checks based on gift type:

  • Ensures all required fields are present
  • Validates field types and values
  • Prevents duplicate gift creation
  • Maintains data integrity

Error Handling

Comprehensive error handling for:

  • Invalid gift data
  • Missing required fields
  • Database connection issues
  • Gift not found scenarios
  • Concurrent modification conflicts

Integration

Database Integration

The agent uses SingleStoreConnection for database operations:

from AI_Agency.Backoffice.Niger.niger_tools import SingleStoreConnection

Key database tables:

  • vulcan_gifts: Stores gift information
  • vulcan_redemptions: Tracks gift redemption history

Event System

The agent integrates with the event bus system for:

  • Gift creation notifications
  • Gift updates
  • Redemption events
  • Error notifications
from AI_Agency.Core_Components.events import AgentEventBus

Mediator Pattern

Uses the mediator pattern for inter-agent communication:

from AI_Agency.Core_Components.mediator import AgentMediator

Error Recovery

The agent implements several error recovery mechanisms:

  • Transaction rollback on database errors
  • Automatic retry for temporary failures
  • Event logging for debugging
  • State recovery for interrupted operations

Integration with Other Agents

Core Dependencies

  • Niger: For database operations
  • Gulosa: For points management
  • Bauri: For user data validation

Optional Integrations

  • Messor: For venue-specific gift availability
  • Hova: For gift image processing
  • Sessile: For billing integration

Configuration

The agent can be configured through environment variables:

VULCAN_CONFIDENCE_THRESHOLD=0.95
VULCAN_MAX_RETRIES=3
VULCAN_TIMEOUT=30

Usage Examples

Creating a Mobile Top-up Gift

gift_data = {
    "gift_name": "Mobile Recharge $10",
    "gift_type": "mobile_top-ups",
    "country": "US",
    "telco_supplier": "AT&T",
    "recharge_amount": 10.00,
    "points_value": 1000
}
result = await vulcan_agent.create_gift(gift_data)

Updating a Gift

update_data = {
    "points_value": 1200,
    "url_photo": "https://example.com/new-photo.jpg"
}
result = await vulcan_agent.update_gift(gift_id, update_data)

Best Practices

  1. Gift Creation

    • Always validate gift data before creation
    • Include clear gift descriptions
    • Set appropriate point values

  2. Gift Updates

    • Use atomic updates to prevent race conditions
    • Maintain update history
    • Validate changes before applying

  3. Gift Deletion

    • Check for active redemptions before deletion
    • Archive instead of hard delete when appropriate
    • Maintain referential integrity

  4. Error Handling

    • Log all errors with context
    • Implement appropriate retry mechanisms
    • Provide clear error messages

Troubleshooting

Common issues and solutions:

  1. Gift Creation Fails

    • Check required fields for gift type
    • Verify database connection
    • Check for duplicate entries

  2. Update Errors

    • Verify gift exists
    • Check field value types
    • Ensure atomic updates

  3. Database Connection Issues

    • Check connection string
    • Verify network connectivity
    • Check database permissions

API Reference

For detailed API documentation, see the Vulcan API Reference.

MessorYuno