Backend
Backoffice
Yuno

Yuno Agent Documentation

Overview

The Yuno agent is responsible for handling ticket scanning and loyalty points processing within the TKM AI Agency Platform. It uses computer vision and AI to analyze receipt images, identify venues and products, and award loyalty points based on purchases. The agent supports automated processing with manual validation capabilities for cases where confidence thresholds are not met.

Directory Structure

Backend/
└── AI_Agency/
    └── Backoffice/
        └── Yuno/
            ├── __init__.py
            ├── yuno.py                # Main agent implementation
            ├── api_yuno.py            # FastAPI endpoints
            ├── yuno_tools.py          # Image processing and analysis tools
            ├── yuno_schema.py         # Data models and schemas
            ├── yuno_definitions.py     # Constants and configurations
            └── yuno_migrations.py      # Database migrations

Main Components

Yuno Class

The Yuno class is the core component implementing the Singleton pattern. It provides methods for:

  • Processing ticket scans
  • Identifying venues and products
  • Managing loyalty points
  • Handling manual validations
  • Tracking ticket processing status

Key Features

Ticket Processing

  1. Image Processing

    • Receipt image upload and storage
    • Image preprocessing and enhancement
    • OCR and text extraction
    • Cloudinary integration for image management

  2. Venue Identification

    • Venue matching algorithms
    • Confidence scoring
    • Venue validation
    • Integration with venue database

  3. Product Recognition

    • Product matching from receipt text
    • Price and quantity extraction
    • Confidence scoring
    • Support for manual validation

  4. Points Management

    • Automatic points calculation
    • Points validation
    • Integration with loyalty system
    • Transaction tracking

Data Models

Key data models defined in yuno_schema.py:

class TicketScanRequest:
    user_id: str
    brand_id: str
    venue_id: str
    image: str  # Base64 encoded
 
class TicketScanStatus:
    id: str
    user_id: str
    brand_id: str
    venue_id: str
    status: str
    products: List[ProductMatch]
    validation_required: bool
    validation_status: str
 
class ProductMatch:
    id: str
    name: str
    confidence: float
    points: int
    needs_validation: bool

Integration

Database Integration

Uses SingleStoreConnection for database operations:

from AI_Agency.Backoffice.Niger.niger_tools import SingleStoreConnection

Key database tables:

  • yuno_ticket_scans: Stores ticket scan information
  • yuno_ticket_products: Stores identified products
  • yuno_ticket_analysis: Stores analysis results
  • yuno_loyalty_transactions: Tracks points transactions

Event System

Integrates with the event bus for various events:

from AI_Agency.Core_Components.events import AgentEventBus
 
# Event types
- ticket_scan_started
- ticket_scan_completed
- ticket_points_assigned
- ticket_validation_needed
- ticket_validated
- ticket_error

Integration with Other Agents

Core Dependencies

  • Messor: For venue and product data
  • Gulosa: For points management
  • Hova: For image processing
  • Bauri: For user data

Optional Integrations

  • Alfari: For notifications
  • Burchelli: For analytics
  • Sessile: For billing integration

Configuration

Environment variables and configuration options:

YUNO_CONFIDENCE_THRESHOLD=0.85
YUNO_MAX_RETRIES=3
YUNO_TIMEOUT=60
YUNO_IMAGE_MAX_SIZE=5242880  # 5MB

Processing Flow

  1. Image Upload

  2. Venue Identification

  3. Product Recognition

Error Handling

The agent implements comprehensive error handling:

  1. Image Processing Errors

    • Invalid image format
    • Upload failures
    • Processing timeouts

  2. Recognition Errors

    • Low confidence matches
    • Unrecognized venues
    • Ambiguous products

  3. System Errors

    • Database connection issues
    • Third-party service failures
    • Network timeouts

Best Practices

  1. Image Processing

    • Validate image format and size
    • Optimize image quality
    • Store original and processed versions

  2. Venue Matching

    • Maintain updated venue patterns
    • Regular pattern validation
    • Monitor match accuracy

  3. Product Recognition

    • Regular product database updates
    • Monitor recognition accuracy
    • Adjust confidence thresholds

  4. Points Processing

    • Validate points before awarding
    • Maintain transaction logs
    • Handle edge cases

Troubleshooting

Common issues and solutions:

  1. Image Processing Issues

    • Check image format and size
    • Verify Cloudinary configuration
    • Check network connectivity

  2. Recognition Problems

    • Review confidence thresholds
    • Update venue/product patterns
    • Check OCR quality

  3. Points Processing Errors

    • Verify user eligibility
    • Check points calculation
    • Review transaction logs

Monitoring and Metrics

Key metrics to monitor:

  1. Performance Metrics

    • Image processing time
    • Recognition accuracy
    • Points processing time

  2. Error Rates

    • Failed uploads
    • Recognition failures
    • Validation requirements

  3. Business Metrics

    • Points awarded
    • Validation rates
    • User engagement

API Reference

For detailed API documentation, see the Yuno API Reference.

VulcanCRM