← back to Handbag Auth Nextjs

analytics/README.md

357 lines

# LUXVAULT Advanced Analytics System

## Overview

The LUXVAULT Advanced Analytics System provides comprehensive data science and machine learning capabilities for luxury handbag auction analysis. It combines predictive modeling, trend analysis, value scoring, and personalized recommendations to identify the best investment opportunities.

## Features

### 1. Predictive Analytics

#### Price Prediction
- **Technology**: Linear regression with time series analysis
- **Output**: 30-day price forecasts with confidence intervals
- **Metrics**: Predicted price, trend percentage, confidence bounds
- **Use Case**: Anticipate future price movements for strategic bidding

```python
# Example prediction output
{
    'brand': 'Hermes Birkin',
    'predicted_price': 15875.47,
    'confidence_lower': 7172.97,
    'confidence_upper': 24577.97,
    'trend_percent_annual': 27.82,
    'sample_size': 71
}
```

#### Undervalued Auction Detection
- **Algorithm**: Statistical z-score analysis comparing current prices to historical averages
- **Threshold**: Configurable discount percentage (default: 20%)
- **Output**: Items selling significantly below market value
- **Use Case**: Identify exceptional bargains before they're gone

#### Optimal Bid Guidance
- **Method**: Percentile-based analysis of historical hammer prices
- **Tiers**: Conservative (25th), Median (50th), Competitive (75th), Aggressive (90th)
- **Output**: Suggested bid amounts with statistical backing
- **Use Case**: Enter confident bids based on data, not emotion

#### ROI Potential Analysis
- **Model**: Compound growth projections based on historical appreciation
- **Timeframes**: 1-year, 3-year, and 5-year projections
- **Factors**: Brand performance, market trends, current deal quality
- **Use Case**: Evaluate pieces as long-term investments

### 2. Trend Analysis

#### Brand Momentum Tracking
- **Algorithm**: Weighted momentum score combining auction frequency and price changes
- **Categories**: Hot (>10), Stable (-10 to 10), Cooling (<-10)
- **Timeframe**: 90-day rolling window (configurable)
- **Metrics**:
  - Frequency change percentage
  - Price change percentage
  - Momentum score
- **Use Case**: Ride the wave of trending brands or find overlooked gems

#### Price Movement Over Time
- **Aggregation**: Monthly price statistics by brand
- **Metrics**: Mean, median, standard deviation, count
- **Visualization**: Time series data ready for charting
- **Use Case**: Understand long-term price trajectories

#### Seasonal Pattern Detection
- **Method**: Month-by-month seasonality index calculation
- **Indices**: Price seasonality, volume seasonality (normalized to 1.0)
- **Discovery**: Peak auction seasons (Nov-Dec, May-Jun)
- **Use Case**: Time purchases to coincide with high-inventory periods

#### Auction House Performance
- **Comparison Metrics**:
  - Total auctions
  - Average price and median
  - Average savings percentage
  - Number of exceptional deals (>20% savings)
- **Ranking**: Sorted by best average savings
- **Use Case**: Focus on auction houses with best deal rates

### 3. Value Scoring System

#### Composite Deal Score (0-100 scale)
Multi-factor scoring algorithm combining:

1. **Savings vs Estimate** (30 points max)
   - Based on percentage discount from estimate
   - Rewards items selling below reserve

2. **Price vs Historical Average** (25 points max)
   - Compares to brand's historical performance
   - Identifies truly exceptional values

3. **Brand Trend** (20 points max)
   - Hot brands get full points
   - Rewards buying into momentum

4. **Rarity Score** (15 points max)
   - Based on auction frequency
   - Rare items score higher

5. **Auction House Reputation** (10 points max)
   - Christie's and Sotheby's get premium
   - Reflects authentication confidence

**Letter Grades**:
- A+ (80-100): Exceptional opportunity
- A (70-79): Excellent value
- B+ (60-69): Very good deal
- B (50-59): Good value
- C+ (40-49): Fair deal
- C (30-39): Average
- D (<30): Below average

#### Investment Grade Rating (1-5 stars)
Long-term investment quality assessment:

**Criteria**:
- Annual appreciation potential (0-2 stars)
- Current deal quality (0-2 stars)
- Brand prestige (0-1 star)

**Ratings**:
- 5 stars: "Excellent - Strong Buy"
- 4 stars: "Excellent - Strong Buy"
- 3 stars: "Good - Buy"
- 2 stars: "Fair - Consider"
- 1 star: "Speculative - Pass"

### 4. Reports & Insights

#### Daily Insights Report
Automated report generation including:
- Total auctions analyzed
- Recent activity summary
- Top 10 deals of the day
- Trending brands (top 5)
- Best-performing auction houses (top 3)

#### Brand Comparison Matrix
Comprehensive side-by-side comparison:
- Total auction count
- Average and median prices
- Average savings percentage
- Price range (min/max)
- Predicted trend
- Rarity score

#### Personalized Recommendations
Smart recommendation engine with filters:

**Input Filters**:
- Maximum budget
- Preferred brands (multi-select)
- Minimum deal score

**Output**:
- Top 20 matches ranked by deal score
- Investment grade ratings
- Complete deal metrics

## API Endpoints

### Predictive Analytics

```
GET /api/analytics/predictions?brand={brand}&days_ahead={days}
GET /api/analytics/undervalued?threshold={percent}&limit={count}
GET /api/analytics/optimal-bid?brand={brand}
GET /api/analytics/roi-potential?auction_id={id}
```

### Trend Analysis

```
GET /api/analytics/trends?days={period}&limit={count}
GET /api/analytics/price-movement?brand={brand}
GET /api/analytics/seasonality?brand={brand}
GET /api/analytics/auction-houses
```

### Value Scoring

```
GET /api/analytics/deal-score?auction_id={id}
GET /api/analytics/investment-grade?auction_id={id}
GET /api/analytics/top-deals?limit={count}&min_score={score}
```

### Reports & Insights

```
GET /api/analytics/reports/daily
GET /api/analytics/reports/brand-comparison
GET /api/analytics/recommendations?max_budget={amount}&brands={list}&min_score={score}
```

### System

```
GET /api/analytics/status
POST /api/analytics/refresh
```

## Installation

### Requirements
```bash
pip install -r requirements.txt
```

**Dependencies**:
- flask==3.0.0
- flask-cors==4.0.0
- pandas==2.1.4
- numpy==1.26.2
- scipy==1.11.4
- scikit-learn==1.3.2

### Generate Sample Data
```bash
python3 generate_sample_data.py
```

This creates 2,000 realistic auction records spanning 2 years with:
- 22 luxury handbag brands
- Realistic price trends (appreciation/depreciation)
- Seasonal variations
- 5 major auction houses
- Statistical noise and variance

### Start Analytics API
```bash
python3 analytics_api.py
```

Server runs on port 7501:
- API: http://45.61.58.125:7501/api/analytics/
- Documentation: http://45.61.58.125:7501/

## Statistical Methodology

### Price Prediction Model
- **Algorithm**: Ordinary Least Squares (OLS) Linear Regression
- **Features**: Days since first auction
- **Validation**: Confidence intervals using residual standard error
- **Assumptions**: Linear trend over time (validated per brand)

### Undervalued Detection
- **Method**: Z-score normalization
- **Formula**: z = (x - μ) / σ
- **Threshold**: Configurable percentage below mean
- **Validation**: Minimum sample size requirements

### Trend Analysis
- **Momentum Score**: Weighted average of frequency change (40%) and price change (60%)
- **Statistical Test**: Comparison of recent period vs. historical average
- **Seasonality Index**: Monthly averages normalized to overall mean

### Value Scoring
- **Normalization**: All component scores scaled to defined ranges
- **Weighting**: Evidence-based weights prioritizing savings and brand performance
- **Validation**: Backtesting against known high-value acquisitions

## Usage Examples

### Finding Undervalued Hermes Birkins
```bash
curl "http://45.61.58.125:7501/api/analytics/undervalued?threshold=25" | grep "Hermes Birkin"
```

### Getting Price Prediction for Chanel Classic Flap
```bash
curl "http://45.61.58.125:7501/api/analytics/predictions?brand=Chanel%20Classic%20Flap"
```

### Personalized Recommendations Under $5,000
```bash
curl "http://45.61.58.125:7501/api/analytics/recommendations?max_budget=5000&min_score=60"
```

### Daily Top 10 Deals
```bash
curl "http://45.61.58.125:7501/api/analytics/top-deals?limit=10"
```

## Dashboard

Web-based analytics dashboard available at:
```
http://45.61.58.125:7500/analytics-dashboard.html
```

**Features**:
- Interactive trend visualizations
- Real-time deal scoring
- Personalized recommendation filters
- Brand comparison matrix
- Auction house performance rankings

## Performance Considerations

### Data Volume
- Optimized for datasets up to 100,000 auctions
- In-memory pandas operations for speed
- Database queries use proper indexing

### Caching
- Analytics engine loads data once on startup
- Manual refresh available via POST /api/analytics/refresh
- Consider implementing Redis for high-traffic scenarios

### Scalability
- Stateless API design allows horizontal scaling
- Each request is independent
- Can deploy multiple instances behind load balancer

## Future Enhancements

### Machine Learning Models
- Random Forest for price prediction (ensemble approach)
- ARIMA for time series forecasting
- Clustering for brand similarity analysis
- Neural networks for complex pattern recognition

### Advanced Analytics
- Image analysis for condition assessment
- Natural language processing for description analysis
- Provenance tracking and authentication scoring
- Market sentiment analysis from social media

### Visualization
- Interactive charts (Chart.js, D3.js)
- Heat maps for seasonal patterns
- Network graphs for brand relationships
- Real-time dashboard updates

## License

Proprietary - LUXVAULT Analytics System

## Support

For technical support or feature requests:
- System: LUXVAULT Analytics v1.0
- Documentation: /root/Projects/handbag-auth-nextjs/analytics/README.md
- API: http://45.61.58.125:7501/

## Credits

Developed using:
- Python 3.10
- Flask web framework
- scikit-learn machine learning library
- pandas data analysis library
- NumPy numerical computing
- SciPy statistical functions