# Siro Pricing Engine

Statistical analysis engine for competitor ride-hailing pricing data.

## Architecture

```
MySQL (scraped_competitor_prices)
       ↓
Pricing Engine (Node.js/TypeScript)
       ↓
  ├─ Outlier Detection (MAD)
  ├─ Tier Clustering (K-Means on PPK)
  ├─ Multiple Linear Regression (Gaussian Elimination)
  ├─ Minimum Fare Detection
  ├─ Surge Pricing Analysis
  └─ Zone-Based Analysis
       ↓
MySQL (competitor_secret_formulas + competitor_surge_insights)
       ↓
PHP Backend reads formulas → adjusts Siro pricing
```

## Quick Start

```bash
# Install
cd backend/pricing-engine
npm install

# Configure
cp .env.example .env
# Edit .env with your MySQL/Redis credentials

# Run migration once
mysql -u root siro < migrations/001_add_columns.sql

# Full analysis
npm run analyze

# TaxiF only
npm run analyze:taxif
```

## CLI Commands

| Command | Description | Schedule |
|---------|-------------|----------|
| `npm run analyze` | Full analysis all competitors | Every 3h |
| `npm run analyze:taxif` | TaxiF deep dive | On-demand |
| `npm run cron:hourly` | Surge + zone quick check (3h window) | Hourly |
| `npm run cron:daily` | Full analysis (72h window) | Daily 6am |
| `npm run cron:weekly` | Full report (7d window) | Weekly Mon 8am |

## Analysis Pipeline

1. **Fetch** raw data from `scraped_competitor_prices`
2. **Clean**: MAD-based outlier removal, extract base (non-surge) prices
3. **Cluster**: K-Means on price_per_km → Economy / Standard / Premium tiers
4. **Regress**: Multiple Linear Regression per tier: `price = base + km·dist + min·dur`
5. **Detect Min Fare**: Knee-point detection on short rides
6. **Analyze Surge**: Per-route price variation × time of day
7. **Zone Analysis**: 2.5km grid pricing heatmap
8. **Save** results to `competitor_secret_formulas` and `competitor_surge_insights`

## Integration with PHP Backend

The PHP cron jobs (`cron_ai_engine.php`, `cron_kazan_adjuster.php`) read from `competitor_secret_formulas` instead of doing their own simplistic math. The workflow becomes:

```
Pricing Engine (Node.js) → writes formulas + surge insights → MySQL
                                                                    ↓
PHP (cron_ai_engine.php)  → reads formulas, adjusts kazan pricing
PHP (cron_kazan_adjuster) → reads surge insights, adjusts commissions
PHP (cron_gemini_advisor) → sends formulas to Gemini for TEXTUAL strategy only
```