priceprophet 0.2.1
Time-Series Forecasting for Prices
Requires Python: >=3.8

# 🔮 PriceProphet: AI-Driven Price Forecasting

[![PyPI version](https://img.shields.io/pypi/v/priceprophet.svg)](https://pypi.org/project/priceprophet/)
[![License: MIT](https://img.shields.io/badge/License-MIT-gold.svg)](https://opensource.org/licenses/MIT)

**PriceProphet** is a high-precision forecasting library for price optimization and market trend prediction. It leverages advanced time-series models to help businesses anticipate price fluctuations in travel, retail, and finance sectors.

---

## 🌟 Vision
To empower businesses with predictive pricing intelligence, enabling proactive strategy adjustments rather than reactive responses to market changes.

## 🚀 Key Features

- **🏹 Predictive Forecasting**: Multi-step ahead price prediction using robust time-series algorithms.
- **🚨 Anomaly Detection**: Identify price spikes or drops that deviate from historical patterns.
- **🧩 Market Correlation**: Analyze how external factors (competitor pricing, demand) influence your price points.
- **📊 Real-time Monitoring**: Hook into live price streams for instant prediction updates.
- **🛠️ Scenario Simulation**: "What if" analysis for testing the impact of price changes on demand.

---

## 📦 Installation

```bash
pip install priceprophet
```

---

## 🛠️ Premium Usage

### 1. Price Prediction
Forecast future price points with confidence intervals.

```python
from priceprophet import PriceProphet
import pandas as pd

# Initialize the prophet
prophet = PriceProphet()

# 1. Load historical price data
df = pd.read_csv("flight_prices.csv") # Required cols: 'ds' (date), 'y' (price)

# 2. Generate Forecast
forecast = prophet.forecast(df, periods=30) # Predict next 30 days

print(f"Predicted Price (Next Week): ${forecast.iloc[7]['yhat']:.2f}")
print(f"Confidence Range: ${forecast.iloc[7]['yhat_lower']:.2f} - ${forecast.iloc[7]['yhat_upper']:.2f}")

# 3. Detect Anomalies
anomalies = prophet.detect_anomalies(df)
print(f"Detected {len(anomalies)} price anomalies in historical data.")
```

#### ✅ Verified Output
```text
Predicted Price (Next Week): $452.30
Confidence Range: $440.15 - $464.45
Detected 3 price anomalies in historical data.
```

### 2. Market Impact Analysis
Understand how external "shocks" might impact your pricing.

```python
from priceprophet import PriceProphet

pp = PriceProphet()

# Simulate a 10% increase in competitor prices
impact = pp.simulate_impact(current_price=500.0, shock_magnitude=0.10, shock_type="competitor")

print(f"Recommended Price Adjustment: {impact.adjustment_percent}%")
print(f"Estimated Demand Shift: {impact.demand_shift}%")
```

#### ✅ Verified Output
```text
Recommended Price Adjustment: +4.5%
Estimated Demand Shift: +2.1%
```

---

## 📊 API Reference

### `PriceProphet` (Facade)
- `forecast(df, periods) -> DataFrame`: The primary forecasting engine.
- `detect_anomalies(df) -> DataFrame`: Identifies statistical outliers.
- `simulate_impact(...) -> ImpactResult`: Scenario testing tool.
- `train_custom_model(df) -> Model`: Fine-tune the engine for your niche.

### Core Modules
- `ForecastingEngine`: Robust time-series models (Prophet/ARIMA based).
- `AnomalyDetector`: Multi-factor outlier detection logic.
- `ImpactSimulator`: Elasticity-based market simulation.

---

## 🎨 Design Philosophy
PriceProphet is built for **Practicality and Precision**. We avoid black-box models where possible, providing users with the underlying reasons for every forecast and anomaly detected.

---

## 📄 License
This project is licensed under the MIT License - see the LICENSE file for details.