> ## Documentation Index
> Fetch the complete documentation index at: https://kumo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Demand Forecasting Solution

## Solution Background and Business Value

Demand forecasting is essential for industries such as sales, retail, manufacturing, and supply chain management. Accurate demand predictions help businesses optimize storage, transportation, and inventory planning, reducing waste and improving operational efficiency. For example, a meal kit delivery service benefits from demand forecasting by ensuring they order the correct amount of raw ingredients to match recipe demand, preventing shortages and minimizing waste.

Forecasting accuracy is typically measured using `MAE` (Mean Absolute Error) or `SMAPE` (Symmetric Mean Absolute Percentage Error). Depending on business needs, forecasts can be made for different time frames and aggregation levels, such as:

* Forecasting the number of orders per recipe group six weeks ahead.

* Predicting the total demand for specific ingredients over the next 28 days.

## Data Requirements and Schema

**Core Tables**

1. **Sales/Orders Table**: Captures historical sales transactions.

   * `order_id` (Primary Key)

   * `item_id` (Foreign Key referencing Items)

   * `buyer_id` (Foreign Key referencing Buyers)

   * `group_id` (Foreign Key referencing Groups)

   * `event_id` (Foreign Key referencing Events)

   * `timestamp` (Date and time of the sale)

   * `quantity` (Number of items sold)

2. **Items Table**: Stores static information about each item.

   * `item_id` (Primary Key)

3. **Groups Table**: Categorizes items for aggregated forecasting.

   * `group_id` (Primary Key)

4. **Buyers Table**: Contains buyer information to enhance predictive accuracy.

   * `buyer_id` (Primary Key)

5. **Events Table**: Records external factors that may affect demand, such as holidays or promotions.

   * `event_id` (Primary Key)

   * `timestamp` (Date and time of the event)

**Entity Relationship Diagram (ERD)**

```mermaid theme={null}
erDiagram
    SALES {
        INT order_id PK
        INT item_id FK
        INT buyer_id FK
        INT group_id FK
        INT event_id FK
        TIMESTAMP timestamp
        INT quantity
    }
    ITEMS {
        INT item_id PK
    }
    GROUPS {
        INT group_id PK
    }
    BUYERS {
        INT buyer_id PK
    }
    EVENTS {
        INT event_id PK
        TIMESTAMP timestamp
    }
    SALES ||--o{ ITEMS : "sold_as"
    SALES ||--o{ BUYERS : "purchased_by"
    SALES ||--o{ GROUPS : "belongs_to"
    SALES ||--o{ EVENTS : "affected_by"
```

## Predictive Queries

Kumo allows flexible demand forecasting using Predictive Queries. Below are five different ways to forecast demand:

1. **Forecasting demand using order count:**

   ```sql theme={null}
   PREDICT COUNT(sales.*, 0, 30, days)
   FOR EACH items.item_id
   ```

2. **Forecasting demand using sum of item quantities:**

   ```sql theme={null}
   PREDICT SUM(sales.quantity, 0, 30, days)
   FOR EACH items.item_id
   ```

3. **Forecasting at an aggregated category level:**

   ```sql theme={null}
   PREDICT SUM(sales.quantity, 0, 30, days)
   FOR EACH groups.group_id
   ```

4. **Predicting demand six weeks into the future:**

   ```sql theme={null}
   PREDICT SUM(sales.quantity, 35, 42, days)
   FOR EACH groups.group_id
   ```

5. **Filtering out instances where demand is zero:**

   ```sql theme={null}
   PREDICT SUM(sales.quantity, 0, 30, days)
   FOR EACH groups.group_id
   ASSUMING SUM(sales.quantity, 0, 30, days) > 0
   ```

## Deployment Strategy

Demand forecasting models are typically deployed in automated pipelines that refresh predictions on a set cadence (daily, weekly, or monthly). The workflow includes:

1. **Data Preparation:** The latest sales and entity data snapshots are refreshed in the data warehouse.

2. **Model Inference:** Kumo ingests the data and generates future demand predictions, which are stored in the desired output location.

3. **Data Transformation:** If necessary, post-processing is applied, such as ensuring non-negative predictions:

   ```sql theme={null}
   SELECT item_id,
          CASE
              WHEN TARGET_PRED < 0 THEN 0
              ELSE TARGET_PRED
          END AS TARGET_PRED
   FROM PREDICTIONS
   ```

4. **Consumption:** Predictions are either reviewed by analysts for strategic decision-making or directly integrated into downstream applications for inventory planning, marketing, and logistics.

## Building models in Kumo SDK

**1. Initialize the Kumo SDK**

```python theme={null}
import kumoai as kumo

# Initialize Kumo client
kumo.init(url="https://<customer_id>.kumoai.cloud/api", api_key=API_KEY)
```

**2. Connect Data**

```python theme={null}
connector = kumo.S3Connector("s3://your-dataset-location/")
```

**3. Select tables**

```python theme={null}
sales = kumo.Table.from_source_table(source_table=connector.table("sales"), primary_key="order_id", time_column="timestamp").infer_metadata()

items = kumo.Table.from_source_table(source_table=connector.table("items"), primary_key="item_id").infer_metadata()

groups = kumo.Table.from_source_table(source_table=connector.table("groups"), primary_key="group_id").infer_metadata()

buyers = kumo.Table.from_source_table(source_table=connector.table("buyers"), primary_key="buyer_id").infer_metadata()

events = kumo.Table.from_source_table(source_table=connector.table("events"), primary_key="event_id", time_column="timestamp").infer_metadata()
```

**4. Create graph schema**

```python theme={null}
graph = kumo.Graph(tables={"sales": sales, "items": items, "groups": groups, "buyers": buyers, "events": events}, edges=[
    {"src_table": "sales", "fkey": "item_id", "dst_table": "items"},
    {"src_table": "sales", "fkey": "buyer_id", "dst_table": "buyers"},
    {"src_table": "sales", "fkey": "group_id", "dst_table": "groups"},
    {"src_table": "sales", "fkey": "event_id", "dst_table": "events"}
])
graph.validate(verbose=True)
```

**5. Train the model**

```python theme={null}
pquery = kumo.PredictiveQuery(graph=graph, query="""PREDICT SUM(sales.quantity, 0, 30, days) FOR EACH items.item_id""")
pquery.validate(verbose=True)
model_plan = pquery.suggest_model_plan()
trainer = kumo.Trainer(model_plan)
training_job = trainer.fit(graph=graph, train_table=pquery.generate_training_table(non_blocking=True), non_blocking=False)
print(f"Training metrics: {training_job.metrics()}")
```