Metadata-Version: 2.4
Name: general-predictor
Version: 0.1.0
Summary: General Time Series Forecasting Framework based on Darts
Requires-Python: <3.12,>=3.11
Requires-Dist: catboost
Requires-Dist: lightgbm
Requires-Dist: mcp
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: u8darts[notorch]>=0.30.0
Requires-Dist: xgboost
Description-Content-Type: text/markdown

# General Predictor

通用时序预测框架，基于Darts库，支持任意时间序列预测任务。

## 特性

- **通用预测能力**：支持销售预测、需求预测、交通流量、电力市场预测等任意时序任务
- **多种模型支持**：LightGBM、XGBoost、CatBoost、LinearRegression
- **特征工程**：时间特征、滞后特征、滚动统计（内置数据泄露防范）
- **预测模式**：支持滚动预测、日前预测、单步预测
- **多时间粒度**：15分钟(96点)、30分钟(48点)、1小时(24点)、日度等
- **MCP协议支持**：可作为MCP Server与Claude等AI助手集成

## 安装

```bash
pip install general-predictor
```

## 快速开始

### 命令行使用

```bash
# 启动MCP Server
general-predictor
```

### Python API使用

```python
from general_predictor import TimeSeriesForecaster, ForecastConfig

# 创建配置
config = ForecastConfig(
    data_path='data/power_load.csv',
    target_col='load',
    datetime_col='datetime',
    freq='15min',
    model_type='lightgbm'
)

# 初始化预测器
forecaster = TimeSeriesForecaster(config)

# 加载数据
forecaster.load_data()
df = forecaster.preprocess_data()

# 准备特征
forecaster.prepare_features(df)

# 创建模型
forecaster.create_model()

# 滚动预测（D日预测D+1日）
predictions = forecaster.rolling_forecast(
    test_start_date='2025-12-01',
    test_end_date='2025-12-31'
)

# 评估
metrics = forecaster.evaluate()

# 保存结果
forecaster.save_results('forecast_results.csv')
```

## MCP工具

### forecast_rolling - 滚动预测

执行滚动时序预测（日前预测模式：D日预测D+1日）

```json
{
  "tool": "forecast_rolling",
  "arguments": {
    "data_path": "data/power_load.csv",
    "target_col": "load",
    "datetime_col": "datetime",
    "freq": "15min",
    "test_start_date": "2025-12-01",
    "test_end_date": "2025-12-31",
    "model_type": "lightgbm",
    "prediction_mode": "direct",
    "lag_preset": "preset1"
  }
}
```

### forecast_single - 单次预测

训练并预测未来N个时间点

```json
{
  "tool": "forecast_single",
  "arguments": {
    "data_path": "data/sales.csv",
    "target_col": "sales",
    "forecast_horizon": 30,
    "train_ratio": 0.8,
    "model_type": "lightgbm"
  }
}
```

### get_lag_presets_info - 获取滞后预设

获取滞后特征预设配置信息

```json
{
  "tool": "get_lag_presets_info",
  "arguments": {
    "freq": "15min"
  }
}
```

### evaluate_forecast - 评估预测

评估预测结果

```json
{
  "tool": "evaluate_forecast",
  "arguments": {
    "predictions_path": "forecast_results.csv"
  }
}
```

### create_feature_config - 特征配置建议

创建特征工程配置建议

```json
{
  "tool": "create_feature_config",
  "arguments": {
    "scenario": "power_load",
    "freq": "15min"
  }
}
```

## 应用场景

### 电力市场预测

- **光伏功率预测**：考虑太阳辐射、云层覆盖
- **风电功率预测**：考虑风速、风向
- **系统负荷预测**：考虑温度、节假日
- **日前/实时电价预测**：考虑供需关系

### 商业预测

- **销售预测**：考虑促销、季节性
- **需求预测**：考虑趋势、周期
- **库存预测**：考虑补货周期

### 交通预测

- **道路流量预测**：考虑早晚高峰
- **网络流量预测**：考虑用户行为

## 数据泄露防范

本框架内置数据泄露防范机制：

1. **滞后特征**：基于实际值的特征至少滞后2天
2. **滚动统计**：先shift至少2天，再计算滚动统计
3. **训练集划分**：使用时序分割，不使用未来数据训练

## 滞后特征预设

### preset1 - 推荐配置（平衡型）

- lags: [-7d, -3d, -2d, -1d, -4h]
- 适用于：电力负荷、电价、销售预测

### preset2 - 短期依赖

- lags: [-1d, -4h, -1]
- 适用于：光伏、风电、交通流量

### preset3 - 长期依赖

- lags: [-7d, -14d, -30d]
- 适用于：长期趋势预测

## 项目结构

```
general_predictor/
├── __init__.py
├── _version.py
├── server.py          # MCP Server
└── forecaster.py      # 核心预测功能
```

## 依赖

- Python >= 3.11, < 3.12
- u8darts[notorch] >= 0.30.0
- lightgbm
- xgboost
- catboost
- scikit-learn
- pandas
- numpy

## 许可证

MIT
