How kbajish/ai-supply-chain-forecasting works
1. This repository is a two-part ML application with a shared core library: a FastAPI backend in api/ and a Streamlit dashboard in dashboard/, both consuming model and inference code from src/. The project is organized around an offline training pipeline that produces artifacts, and an online serving layer that reads those artifacts to answer forecast, risk, and narrative requests.
2. The data subsystem lives in src/data/. generator.py creates the synthetic industrial supply chain datasets: daily demand series for SKUs and separate supplier risk records. preprocess.py turns raw demand into model-ready features such as lagged values, rolling statistics, and calendar signals. This is the first major boundary: raw synthetic data becomes structured training input.
3. The modeling layer is split by use case in src/models/. lstm_model.py defines and trains the demand forecaster using PyTorch LSTM logic, while risk_model.py trains the supplier risk classifier using XGBoost. These are separate model tracks, which is important architecturally because demand forecasting and supplier risk scoring have different inputs, outputs, and evaluation metrics.
4. Training artifacts appear to be persisted outside the source tree, with models/ used for saved binaries and mlruns/ for experiment tracking. The README indicates MLflow is used to track loss, MAE, and RMSE for both model families. So the training side is not just “fit a model,” but a reproducible experiment-and-artifact workflow.
5. Inference is handled in src/forecasting/predictor.py and src/risk/scorer.py. The predictor takes a trained demand model and generates the 28-day SKU forecast, including prediction intervals. The scorer combines the risk classifier output with SHAP explanations and produces risk labels and alert-style outputs. These modules are the bridge between trained models and API/dashboard consumers.
6. The LLM layer in src/llm/insight_chain.py adds a narrative-generation boundary on top of numeric outputs. It uses LangChain with a local Ollama model to synthesize forecast, risk, and reorder information into planner-readable text. This is a distinct subsystem from the predictive models: it does not forecast itself, but summarizes and contextualizes results.
7. api/main.py is the online service boundary. The FastAPI app exposes /forecast, /risk, /insights, and /health, which correspond directly to the three core capabilities plus liveness. The API is the integration layer that orchestrates the forecast engine, risk engine, and LLM chain into request/response workflows.
8. dashboard/app.py is the user-facing visualization boundary. The Streamlit app consumes API or local outputs to render the demand chart, supplier risk states, reorder alerts, and generated insights. This means the dashboard is not the analytical engine; it is a presentation layer on top of the backend services.
9. The repository also includes an M5 benchmark notebook in notebooks/02_m5_forecasting.ipynb. That notebook is a sidecar evaluation path for the same LSTM architecture on real Walmart-style retail data, separate from the synthetic industrial dataset used by the main system. Architecturally, it serves as validation and experimentation rather than part of the production request path.
10. Deployment and packaging are containerized with Dockerfile.api, Dockerfile.dashboard, and docker-compose.yml, which indicate the API and dashboard can run as separate services together. The requirements files split dependencies by runtime, and .env.example suggests configurable runtime settings. This is a clean multi-service layout rather than a single monolith.
11. Quality and governance are lightweight but explicit: tests/test_generator.py validates synthetic data generation and tests/test_imports.py keeps CI-safe import checks stable. .github/workflows/ci.yml automates these tests, and AI_ACT_COMPLIANCE.md indicates the repo includes documented compliance considerations. So the architecture includes both technical and process boundaries.
12. In diagram terms, the main flow is: synthetic data generation and preprocessing feed model training; trained models and MLflow artifacts feed inference modules; inference outputs feed the LLM narrative layer; and both API and dashboard sit on top as consumers. The most important separations are training vs serving, forecasting vs risk scoring, and numeric analytics vs natural-language explanation.
Main entry points: main.py FastAPI · predictor.py Forecasting · scorer.py Risk scoring · generator.py Data gen
Components 17
Data & ML
Synthetic data generation, preprocessing, model training, and experiment artifacts.
- Data gen · Creates daily demand series and supplier risk records.
src/data/generator.py - Prep features · Builds model-ready lag, rolling, and calendar features from raw demand.
src/data/preprocess.py - Demand model · Trains the demand forecaster for SKU-level time series prediction.
src/models/lstm_model.py - Risk model · Trains the supplier risk classifier used for risk scoring.
src/models/risk_model.py - Artifacts · Saved model files and experiment tracking used by training and serving.
Serving Layer
Forecasting, risk scoring, and narrative generation used at runtime.
- Forecasting · Generates 28-day demand forecasts and prediction intervals.
src/forecasting/predictor.py - Risk scoring · Produces risk labels, alerts, and SHAP-based explanations.
src/risk/scorer.py - Insights · Synthesizes forecast, risk, and reorder context into narrative text.
src/llm/insight_chain.py
Applications
API, dashboard, and deployment packaging around the shared core.
- FastAPI · Exposes forecast, risk, insights, and health endpoints.
api/main.py - Streamlit · Displays demand, supplier risk, alerts, and generated insights.
dashboard/app.py - API image · Container definition for the backend service.
Dockerfile.api - Dash image · Container definition for the dashboard service.
Dockerfile.dashboard - Compose · Runs API and dashboard together as a multi-service stack.
docker-compose.yml
Quality & Validation
Tests, benchmark notebook, and compliance/governance artifacts.
- M5 notebook · Sidecar evaluation of the LSTM architecture on benchmark retail data.
notebooks/02_m5_forecasting.ipynb - Tests · Validates synthetic generation and import stability.
tests/test_generator.py - CI · Automated test execution in GitHub Actions.
.github/workflows/ci.yml - Compliance · Documents AI Act-related compliance considerations.
AI_ACT_COMPLIANCE.md
Connections 21
- Data gen → Prep features: raw data · Synthetic demand data is transformed into training features.
- Prep features → Demand model: train input · Engineered demand features feed the forecaster.
- Data gen → Risk model: risk records · Synthetic supplier risk data feeds classifier training.
- Demand model → Artifacts: save model · Trained demand model is persisted as an artifact.
- Risk model → Artifacts: save model · Trained risk model is persisted as an artifact.
- Artifacts → Forecasting: load forecast · Inference reads trained demand artifacts.
- Artifacts → Risk scoring: load risk · Inference reads trained risk artifacts.
- Forecasting → FastAPI: forecast · API requests are served from the forecasting engine.
- Risk scoring → FastAPI: risk · API requests are served from the risk engine.
- Forecasting → Insights: signals · Forecast outputs contribute to narrative generation.
- Risk scoring → Insights: signals · Risk outputs contribute to narrative generation.
- Insights → FastAPI: insights · LLM-generated summaries are exposed through the API.
- FastAPI → Streamlit: serve data · Dashboard consumes backend endpoints or local outputs.
- FastAPI → API image: package · Backend service is containerized for deployment.
- Streamlit → Dash image: package · Dashboard service is containerized for deployment.
- API image → Compose: orchestrate · API container is part of the multi-service stack.
- Dash image → Compose: orchestrate · Dashboard container is part of the multi-service stack.
- M5 notebook → Demand model: evaluate · Benchmark notebook exercises the same forecasting architecture.
- Tests → Data gen: verify · Tests validate synthetic data generation behavior.
- CI → Tests: run · CI automates the test suite.
- Compliance → FastAPI: govern · Compliance guidance applies to the service boundary.