A machine learning-powered meal demand forecasting system for cafeterias, built with Python and Streamlit.
KitchenCopilot helps cafeteria managers predict daily meal demand by combining historical sales data with real-time environmental factors. The system integrates weather forecasts, holiday calendars, and capacity planning to generate accurate meal demand predictions, reducing food waste and improving operational efficiency.
This project demonstrates end-to-end machine learning operations including data pipeline design, feature engineering with external APIs, model training and deployment, and interactive web-based visualization.
- Automated Feature Engineering: Automatically enriches forecasts with weather data (OpenWeatherMap API) and German holidays (Hessen)
- Interactive Forecasting Interface: Streamlit-based dashboard for generating predictions with custom date ranges
- AI-powered Insights: After displaying raw metrics, the app sends data to Claude (Anthropic API) which identifies actionable patterns — like systematic weekday biases or weather correlations — in plain language for kitchen staff.
- Performance Tracking: Compare actual vs predicted meals with exportable Excel reports
- SQLite Data Persistence: Stores predictions and actual sales for historical analysis
- Modular ML Pipeline: Separate model training workflow using Jupyter notebooks
- Languages: Support from English and German
- Python 3.9.6: Core programming language
- Streamlit 1.5: Interactive web application framework
- scikit-learn 1.6.1: Machine learning model training and prediction
- SQLAlchemy 2.0.45: Database ORM and connection management
- SQLite: Lightweight database for predictions and historical data
- Pandas 2.3.3: Data manipulation and analysis
- NumPy 2.0.2: Numerical computing
- requests 2.32.5: HTTP client for API integration
- Open Meteo API: 7-day weather forecasts (free tier). No API Key required.
- Claude API: Prediction data is serialized to JSON and sent to the Anthropic API The Streamlit caching layer stores responses to avoid redundant API calls.
kitchencopilot/
├── components/
│ ├── home.py/ # HTML components for Home Page
│ ├── sidebar.py/ # Sidebar Translation Toggle
├── data/
│ ├── models/ # trained models
│ ├── processed/ # Processed training data
│ ├── raw/ # raw data
│ └── kitchencopilot.db # SQLite database (created by init script)
├── scripts/
│ └── init_db.py # Database initialization script
│ └── seed_data.py # Seed database with Holiday Data of 2026
├── styles/
│ └── css
│ └── main.css # CSS Style for Homepage
│ └── images
│ └── kitchencopilot_.# Kitchencopilot Logo Transparent for Home and Logo
├── pages # Streamlit pages (auto-discovered)
│ └── 1_Prepare.py # Configure prediction timeframe and fetch weather
│ └── 2_Prediction.py # Display Predicted Meal Demand
│ └── 3_Actuals.py # Actuals vs. Predictions
│ └── 4_Import.py # Import Page for actual sales data
├── utils
│ └── __init__.py # Streamlit application
│ └── db_utils.py # Database operations
│ └── prediction_utils.py # ML Prediction logic
│ └── weather_utils.py # API Integration
│ └── llm_insights.py # LLM connection, prompts and API Integration
│ └── translations_utils.py # Translation logica
│ └── translations_json # English and German Translations with respective keys
├── .streamlit/
│ └── secrets.toml # Streamlit configuration (not in Git)
├── Home.py # Streamlit Landing Page
├── requirements.txt # Python dependencies
└── README.md
- Python 3.12 or higher
- OpenWeatherMap API key (free tier: https://openweathermap.org/api)
- Anthropic API key (https://console.anthropic.com)
- Clone the repository
git clone <repository-url>
cd kitchencopilot- Create and activate virtual environment
On macOS/Linux:
python -m venv .venv
source .venv/bin/activateOn Windows:
python -m venv .venv
.venv\Scripts\activate- Install dependencies
pip install -r requirements.txt- Set up OpenWeatherMap API key
Create a .streamlit/secrets.toml file:
ANTHROPIC_API_KEY = "your-key-here"
[connections.kitchencopilot_db]
url = "sqlite:///data/kitchencopilot.db"- Initialize the database
python scripts/init_db.pyYou should see:
Starting database initialization...
✓ Data directory ready at: data
✓ Created 'holidays' table
✓ Created 'predictions' table
✓ Created 'actual_sales' table
✓ Database initialization complete: data/kitchencopilot.db
- Seed the database
python scripts/seed_data.pyYou should see:
Starting data seeding...
✓ Cleared existing holidays data
✓ Seeded holidays table
✓ Data seeding complete!
Start the Streamlit app:
streamlit run Home.pyThe application will open in your browser at http://localhost:8501
For model training and data exploration:
jupyter notebook notebooks/extract_data.ipynbThe notebook includes:
- PDF sales report extraction using pdfplumber
- Data preprocessing and feature engineering
- Model training with scikit-learn
- Model persistence for production use
- Navigate to the Predictions page in the Streamlit app
- Select a start date and forecast period (up to 7 days)
- Input expected daily capacity
- Click "Fetch Weather & Generate Predictions"
- Review the forecast table and visualizations
- Use the "Export to Excel" button to download predictions
- Compare actual vs predicted meals for performance analysis
- Reports include all features used in the prediction
The system follows a modular architecture separating concerns:
- Offline Process: Historical data training using Jupyter notebooks
- Feature Engineering: Automated enrichment with weather and holiday data
- Prediction Engine: Trained scikit-learn model for demand forecasting
- Web Interface: Streamlit dashboard for user interaction
- Data Persistence: SQLite database for predictions and actuals
For detailed architecture documentation, see architektur_beschreibung_deutsch.md
- Automated daily scheduling for predictions
- Enhanced model features (menu item analysis, historical trends)
- Multi-location support for cafeteria chains
- Real-time model retraining pipeline
- Advanced visualization with confidence intervals
- Mobile-responsive interface improvements
Database Schema:
holidays: Holiday calendar with bank holidays, semester breaks, and bridge dayspredictions: Forecast results with all feature data and timestampsactual_sales: Actual meal counts for model validation
Model Details:
- Algorithm: Scikit-learn regression (specific model TBD based on training results)
- Features: Weekday, month, expected capacity, temperature, weather conditions, holiday flags
- Training data: Historical cafeteria sales with weather and calendar features
This project is a portfolio demonstration piece. Contact for usage inquiries.
For questions or collaboration opportunities, please reach out via GitHub.