> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server.

# Demand Forecasting Solution

## Solution Background and Business Value

Demand forecasting predicts future item demand so businesses can optimize inventory, reduce waste, and improve operational efficiency across sales, retail, manufacturing, and supply chain.

For example, a meal kit delivery service uses demand forecasting to order the correct amount of raw ingredients per recipe, 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 target different time frames and aggregation levels:

* 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
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 expresses demand forecasting logic as **Predictive Queries**: SQL-like statements that define what to predict and over what time window.
The syntax `PREDICT <aggregation>(table.column, start_offset, end_offset, time_unit) FOR EACH table.id_column` specifies the aggregation function, the prediction window as offsets from the anchor time, and the entity to predict for.

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

   ```sql
   PREDICT COUNT(sales.*, 0, 30, days)
   FOR EACH items.item_id
   ```

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

   ```sql
   PREDICT SUM(sales.quantity, 0, 30, days)
   FOR EACH items.item_id
   ```

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

   ```sql
   PREDICT SUM(sales.quantity, 0, 30, days)
   FOR EACH groups.group_id
   ```

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

   ```sql
   PREDICT SUM(sales.quantity, 35, 42, days)
   FOR EACH groups.group_id
   ```

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

   ```sql
   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).

1. **Data Preparation:** Refresh the latest sales and entity data snapshots in the data warehouse.

2. **Model Inference:** Kumo ingests the data and generates future demand predictions, storing results in the configured output location.

3. **Data Transformation:** Apply post-processing as needed. For example, clamp negative predictions to zero:

   ```sql
   SELECT item_id,
          CASE
              WHEN TARGET_PRED < 0 THEN 0
              ELSE TARGET_PRED
          END AS TARGET_PRED
   FROM PREDICTIONS
   ```

4. **Consumption:** Analysts review predictions for strategic decision-making or feed them directly into downstream applications for inventory planning, marketing, and logistics.

## Building models in Kumo Fine-Tune SDK

**1. Initialize the Kumo Fine-Tune SDK**

```python
import kumoai as kumo

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

**2. Connect Data**

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

**3. Select tables**

```python
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
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
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()}")
```