README.md

---
title: Wildberries Analytics Dashboard
emoji: 🛍️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.7.1
app_file: app.py
pinned: false
license: mit
short_description: AI-powered analytics dashboard for Wildberries marketplace
tags:
- analytics
- dashboard
- e-commerce
- wildberries
- inventory
- forecasting
- business-intelligence
---

# 🛍️ Wildberries Analytics Dashboard

An AI-powered analytics dashboard for Wildberries marketplace sellers that provides sales insights and inventory forecasting capabilities.

## ✨ Features

- 📊 **Sales Analytics**: Track revenue, orders, and product performance
- 📦 **Inventory Forecasting**: Predict stockout dates using multiple algorithms
- ⚠️ **Risk Management**: Automated alerts for low stock situations
- 📈 **Interactive Dashboards**: Visual analytics with Plotly charts
- 🔄 **Real-time Data**: Integration with Wildberries API
- 🎯 **Demo Mode**: Works without API token for testing

## 🚀 Quick Start

### Using with Your Wildberries API Token

1. **Get your API token**:
   - Go to your Wildberries seller account
   - Navigate to Settings → Access to API
   - Generate a token with Analytics and Statistics permissions

2. **Configure the Space**:
   - Fork this Space or duplicate it
   - Go to Settings in your Space
   - Add a new secret: `WILDBERRIES_API_TOKEN` with your token value

3. **Start analyzing**:
   - Use the Sales Analytics tab for performance insights
   - Use the Inventory Forecasting tab for stock predictions

### Demo Mode

You can try the dashboard immediately without an API token - it will use sample data to demonstrate all features.

## 📊 Forecasting Methods

The dashboard implements multiple inventory forecasting algorithms:

### 1. Simple Division Method
```
Days Until Stockout = Current Stock ÷ Average Daily Sales
```
- **Best for**: Stable demand patterns
- **Pros**: Easy to understand and implement
- **Cons**: Doesn't account for variability

### 2. Safety Stock Method
```
Safety Stock = (Max Daily Sales × Max Lead Time) - (Avg Daily Sales × Avg Lead Time)
Adjusted Days = (Current Stock - Safety Stock) ÷ Average Daily Sales
```
- **Best for**: Critical inventory items
- **Pros**: Accounts for demand uncertainty
- **Cons**: More conservative estimates

### 3. Weighted Average Method
- Recent weeks: 50% weight
- Previous weeks: 30% weight
- Earlier periods: 20% weight
- **Best for**: Trending products
- **Pros**: Adapts to recent changes
- **Cons**: May overreact to short-term fluctuations

### 4. Seasonal Adjustment Method
```
Adjusted Demand = Base Daily Sales × Seasonal Factor
Days Until Stockout = Current Stock ÷ Adjusted Demand
```
- **Best for**: Seasonal products
- **Pros**: Accounts for seasonal patterns
- **Cons**: Requires historical seasonal data

## 🔧 Technical Architecture

### Core Components

- **Frontend**: Gradio web interface with Plotly visualizations
- **Backend**: Python with pandas for data processing
- **API Client**: Custom Wildberries API integration with rate limiting
- **Forecasting Engine**: Multiple statistical algorithms for prediction
- **Data Layer**: In-memory processing with CSV export capabilities

### API Integration

The dashboard respects Wildberries API rate limits:
- Maximum 300 requests per minute
- Uses token bucket algorithm
- Implements exponential backoff for 429 errors
- Automatic retry logic with circuit breaker

### Deployment

Optimized for Hugging Face Spaces:
- Single-file deployment (`app.py`)
- Environment variable configuration
- Gradio's built-in API endpoints
- Automatic scaling and load balancing

## 📈 Usage Examples

### Sales Analysis
```python
# Analyze last week's performance
analyze_sales_performance("week")

# Get monthly trends
analyze_sales_performance("month")
```

### Inventory Forecasting
```python
# Conservative approach with safety stock
calculate_stockout_forecast("safety_stock")

# Quick estimation
calculate_stockout_forecast("simple")

# Trend-aware forecasting
calculate_stockout_forecast("weighted")
```

## 🔒 Security & Privacy

- **No data storage**: All processing happens in-memory
- **Secure tokens**: API keys stored as Hugging Face Spaces secrets
- **Rate limiting**: Respects API limits to prevent account issues
- **Error handling**: Graceful fallback to demo mode if API unavailable

## 🛠️ Local Development

To run locally:

```bash
# Clone the repository
git clone <your-space-url>
cd <space-name>

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export WILDBERRIES_API_TOKEN="your_token_here"

# Run the application
python app.py
```

## 📋 API Permissions Required

Your Wildberries API token needs access to:
- ✅ Analytics API
- ✅ Statistics API
- ✅ Marketplace data (for product information)

## 🤝 Contributing

1. Fork this Space
2. Make your changes
3. Test with demo mode
4. Submit a discussion or create your own improved version

## 📚 Resources

- [Wildberries API Documentation](https://dev.wildberries.ru/en/openapi/api-information)
- [Hugging Face Spaces Documentation](https://huggingface.co/docs/hub/spaces)
- [Gradio Documentation](https://gradio.app/docs/)

## 📄 License

MIT License - see LICENSE file for details.

## 🐛 Troubleshooting

### Common Issues

**"Demo Mode" showing instead of real data**
- Check if `WILDBERRIES_API_TOKEN` is set in Space settings
- Verify token has correct permissions
- Ensure token hasn't expired (180-day validity)

**API Rate Limit Errors**
- Dashboard automatically handles rate limits
- If persistent, check if other applications are using the same token
- Consider upgrading to higher-tier API access

**Empty charts or data**
- May indicate no sales in selected period
- Try extending the analysis period
- Verify API token has access to your store data

## 🎯 Roadmap

- [ ] Multi-language support (Russian, English)
- [ ] Advanced seasonal analysis
- [ ] Export to Excel/PDF reports
- [ ] Integration with other marketplaces
- [ ] Mobile-responsive design improvements
- [ ] Real-time notifications for critical stock levels

---

**Made with ❤️ for Wildberries sellers**