ai_qc/backend/NEW_FEATURES_QUICKSTART.md

New Features Quick Start Guide

This guide provides quick examples for the two new features added to AI QC:

1. Usage Tracking Reports - Generate comprehensive usage and cost reports
2. Profile Auto-Versioning & Visibility Control - Automatic version control and client-specific profiles

---

1. Usage Tracking Reports

Quick Examples

Generate a Report for Last 7 Days

cd backend
python generate_usage_report.py --last-days 7

Generate Monthly Report and Save to File

python generate_usage_report.py --last-days 30 --output monthly_report.txt

Generate CSV Report for Excel

python generate_usage_report.py --last-days 30 --format csv --output report.csv

Filter by Specific Client

python generate_usage_report.py --client diageo --last-days 30
python generate_usage_report.py --client unilever --last-days 7
python generate_usage_report.py --client loreal --last-days 30

Specific Date Range

python generate_usage_report.py --start-date 2026-02-01 --end-date 2026-02-28

Report Formats Available

• text (default) - Human-readable format
• json - Machine-readable JSON
• csv - Spreadsheet-compatible

What's Included in Reports

• Summary: Total analyses, checks, estimated costs
• By Client: Usage per client with top profiles
• By User: Individual user statistics
• By Profile: Profile usage across clients
• By Date: Daily breakdown

Example Output

================================================================================
AI QC USAGE REPORT
================================================================================
Generated: 2026-02-02 13:06:23

SUMMARY
--------------------------------------------------------------------------------
Total Analyses: 156
Total QC Checks: 1,560
Total Estimated Cost: $78.00 USD
Average Checks per Analysis: 10.0
Average Cost per Analysis: $0.5000 USD

USAGE BY CLIENT
--------------------------------------------------------------------------------

DIAGEO
  Analyses: 45
  QC Checks: 495
  Unique Users: 3
  Average Score: 87.5/100
  Estimated Cost: $24.75 USD
  Top Profiles:
    • diageo_key_visual: 30 analyses
    • diageo_packaging: 15 analyses
...

Automation Examples

Daily Report Cron Job

Add to crontab (crontab -e):

# Daily report at 8 AM
0 8 * * * cd /opt/ai_qc/backend && python generate_usage_report.py --last-days 1 --output reports/daily_$(date +\%Y\%m\%d).txt

# Weekly report every Monday at 9 AM
0 9 * * 1 cd /opt/ai_qc/backend && python generate_usage_report.py --last-days 7 --output reports/weekly_$(date +\%Y\%m\%d).txt

---

2. Profile Auto-Versioning & Visibility Control

Auto-Versioning

How it works: When you edit a profile, the system automatically creates a new version (v2, v3, etc.) and keeps the original unchanged.

Example: Edit a Profile

Before Edit:

• my_profile.json (version 1)

After Edit:

• my_profile.json (version 1 - unchanged)
• my_profile_v2.json (version 2 - new version with changes)

After Second Edit:

• my_profile.json (version 1 - unchanged)
• my_profile_v2.json (version 2 - unchanged)
• my_profile_v3.json (version 3 - latest version)

Benefits

✅ Original profiles never overwritten ✅ Complete history preserved ✅ Easy rollback to previous versions ✅ Audit trail of who made changes and when

View Version History

# List all versions of a profile
ls -lh profiles/my_profile*.json

# Compare versions
diff profiles/my_profile.json profiles/my_profile_v2.json

Visibility Control

Control which clients can see and use specific profiles.

Option 1: All Clients (Default)

Profile visible to all clients (diageo, unilever, loreal, general).

{
  "name": "Universal Accessibility Check",
  "visibility": "all",
  "visible_to_clients": []
}

Option 2: Client-Specific

Profile visible only to selected clients.

{
  "name": "Diageo Premium Check",
  "visibility": "client_specific",
  "visible_to_clients": ["diageo"]
}

Option 3: Multi-Client

Profile visible to multiple specific clients.

{
  "name": "Luxury Brand Standards",
  "visibility": "client_specific",
  "visible_to_clients": ["diageo", "loreal"]
}

API Examples

Create Profile - All Clients

curl -X POST http://localhost:7183/api/profiles \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=YOUR_TOKEN" \
  -d '{
    "name": "My Global Profile",
    "description": "Available to all clients",
    "visibility": "all",
    "checks": {
      "text_readability_general": {
        "enabled": true,
        "weight": 1.0,
        "llm": "Gemini"
      }
    }
  }'

Create Profile - Specific Clients

curl -X POST http://localhost:7183/api/profiles \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=YOUR_TOKEN" \
  -d '{
    "name": "Diageo Custom Check",
    "description": "Only for Diageo",
    "visibility": "client_specific",
    "visible_to_clients": ["diageo"],
    "checks": {
      "logo_visibility_general": {
        "enabled": true,
        "weight": 1.5,
        "llm": "OpenAI"
      }
    }
  }'

Update Profile (Auto-Creates New Version)

curl -X PUT http://localhost:7183/api/profiles/my_profile \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=YOUR_TOKEN" \
  -d '{
    "name": "My Profile - Updated",
    "checks": {
      "text_readability_general": {
        "enabled": true,
        "weight": 1.0,
        "llm": "Gemini"
      },
      "logo_visibility_general": {
        "enabled": true,
        "weight": 1.0,
        "llm": "OpenAI"
      }
    }
  }'

Response:

{
  "status": "success",
  "message": "Profile updated to version 2. Original kept as \"my_profile\"",
  "profile_id": "my_profile_v2",
  "previous_profile_id": "my_profile",
  "version": 2
}

Web UI Usage

Creating a Profile

1. Navigate to profile management in web UI
2. Click "Create Profile"
3. Fill in profile details
4. Visibility Options:
   • ☑️ Check "Reveal to All Clients" - visible to everyone
   • ☐ Uncheck and select specific clients - limited visibility
5. Click "Create"

Editing a Profile

1. Select profile to edit
2. Make your changes
3. Click "Save"
4. System automatically:
   • Creates new version (e.g., profile_v2)
   • Keeps original unchanged
   • Updates all client configurations
5. Success message shows version number

---

Common Use Cases

Use Case 1: Weekly Usage Reports for Management

# Create weekly reports directory
mkdir -p reports/weekly

# Generate report every Monday
python generate_usage_report.py --last-days 7 \
  --output reports/weekly/report_$(date +%Y%m%d).txt

# Generate CSV for Excel analysis
python generate_usage_report.py --last-days 7 --format csv \
  --output reports/weekly/report_$(date +%Y%m%d).csv

Use Case 2: Client-Specific Cost Tracking

# Generate individual client reports
for client in diageo unilever loreal general; do
    python generate_usage_report.py \
      --client $client \
      --last-days 30 \
      --output reports/${client}_monthly.txt
done

Use Case 3: Create Brand-Specific Profile

1. In Web UI:

   • Create new profile "Diageo Premium 2026"
   • Uncheck "Reveal to All Clients"
   • Select "Diageo" only
   • Configure checks
   • Save

2. Result: Only Diageo users see this profile in dropdown

Use Case 4: Test Profile Changes Safely

1. Original: production_profile.json (v1)
2. Edit: Changes create production_profile_v2.json
3. Test: Test v2 with specific users
4. Rollback if needed: Point clients back to v1 in client_config.py
5. Keep both: Original preserved for emergency rollback

Use Case 5: Audit Profile Changes

# View version history
ls -lh profiles/diageo_check*.json

# See what changed
diff profiles/diageo_check.json profiles/diageo_check_v2.json

# Check metadata
cat profiles/diageo_check_v2.json | jq '{version, modified_at, modified_by, previous_version}'

---

Documentation

For detailed documentation, see:

• Usage Reports: USAGE_REPORTS.md
• Profile Management: PROFILE_MANAGEMENT.md

---

Support

For questions or issues:

1. Check the detailed documentation files
2. Review log files
3. Test in development environment first
4. Contact development team

---

Quick Reference

Usage Report Commands

# Last 7 days
python generate_usage_report.py --last-days 7

# Last 30 days, save to file
python generate_usage_report.py --last-days 30 --output report.txt

# Specific client
python generate_usage_report.py --client diageo --last-days 30

# CSV format
python generate_usage_report.py --last-days 30 --format csv --output report.csv

# JSON format
python generate_usage_report.py --last-days 30 --format json --output report.json

Profile Visibility Options

// All clients
{"visibility": "all", "visible_to_clients": []}

// Single client
{"visibility": "client_specific", "visible_to_clients": ["diageo"]}

// Multiple clients
{"visibility": "client_specific", "visible_to_clients": ["diageo", "unilever"]}

Available Client IDs

• diageo - Diageo
• unilever - Unilever
• loreal - L'Oreal
• general - General/Other

---

Questions? See the detailed documentation in USAGE_REPORTS.md and PROFILE_MANAGEMENT.md.