project-merlin-00/cysmic-fuel-forecasting

Agentic AI framework for fuel demand forecasting in Kenya's oil & gas retail sector # CYSMIC Fuel Forecasting Agentic AI framework for fuel demand forecasting in Kenya's oil & gas retail sector. ## Overview This project implements the framework described in the EPRA 2026 Research Paper: *"Fuel Demand Forecasting in Kenya's Oil & Gas Retail Sector: A Framework for Agentic Orchestration"* ## Quick Start (Demo Mode) ```bash # Clone the repo git clone github.com cd cysmic-fuel-forecasting # Create virtual environment (recommended) python3 -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows # Install dependencies pip install -r requirements.txt # Run demo (synthetic data) python3 demo.py ``` ## Demo Features The demo showcases: - **Synthetic data generation** - 4 stations, 3 products, 90 days - **Demand forecasting** - 7-day predictions with confidence intervals - **Inventory management** - Stock level monitoring with alerts - **Natural language queries** - Simulated LLM responses - **Export** - CSV/JSON export of forecasts ### Demo Commands ```bash # Generate sample data python3 demo.py data # Run forecast python3 demo.py forecast NBO001 diesel # Check inventory python3 demo.py inventory NBO001 # Ask question python3 demo.py ask "Should I order more stock?" # Export python3 demo.py export csv ``` ## Full System (With ML + LLM) For the full agentic system with real ML models and LLM integration: ```bash # Install full dependencies pip install -r requirements-full.txt # Start Ollama (for local LLM) ollama serve ollama pull llama2 # Run the full system python3 -m src.orchestration.langgraph_ollama ``` ### Full System Requirements - Python 3.10+ - Ollama (ollama.ai) - 8GB+ RAM for ML models ## Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ ORCHESTRATION LAYER │ │ (Controller Agent - LangGraph) │ ├────────────────────────────────────── …