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

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

#### Generate Monthly Report and Save to File

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

#### Generate CSV Report for Excel

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

#### Filter by Specific Client

```bash
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

```bash
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`):

```bash
# 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

```bash
# 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).

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

#### Option 2: Client-Specific

Profile visible only to selected clients.

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

#### Option 3: Multi-Client

Profile visible to multiple specific clients.

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

### API Examples

#### Create Profile - All Clients

```bash
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

```bash
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)

```bash
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**:
```json
{
  "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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```json
// 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`.