Support Parquet-Based Inputs for Planning API

[chripiermarini]

Support Parquet-Based Inputs for Planning API

Motivation

The current API requires users to manually build JSON payloads for forecasting, optimization, and planning endpoints.

While suitable for development and testing, this workflow does not reflect how logistics planners and supply chain teams typically interact with decision-support systems.

In real-world scenarios, planners usually export datasets from ERP, WMS, TMS, APS, SAP, Oracle, or Excel-based workflows and provide those datasets directly to the planning engine.

To better simulate production usage and improve the realism of the project, the API should support dataset-driven execution through Parquet files.

---

Current Workflow

Users must manually construct JSON requests such as:

{
  "sku": "A",
  "demand": [...]
}

and submit them to:

• POST /forecast
• POST /optimize
• POST /plan

This becomes cumbersome for larger datasets and does not represent enterprise planning workflows.

---

Proposed Solution

Extend the FastAPI interface to support Parquet file uploads.

Introduce alternative endpoints capable of receiving one or more .parquet files containing the required planning inputs.

Example:

• POST /forecast/upload
• POST /optimize/upload
• POST /plan/upload

or alternatively allow existing endpoints to accept multipart/form-data uploads.

The API should:

1. Receive uploaded Parquet datasets.
2. Validate schema and required columns.
3. Load data into Pandas DataFrames.
4. Execute the existing forecasting and optimization pipeline.
5. Return results as JSON and optionally downloadable Parquet outputs.

---

Benefits

• Better simulation of real enterprise planning workflows.
• Eliminates the need to manually construct large JSON payloads.
• Easier integration with ERP and analytics systems.
• Demonstrates practical data engineering capabilities.
• Improves scalability for larger planning scenarios.
• Creates a more realistic portfolio project.

---

Example User Journey

A planner exports:

• demand.parquet
• inventory.parquet
• constraints.parquet

The planner uploads these files to:

POST /plan/upload

The engine then:

1. Loads the datasets.
2. Generates forecasts.
3. Runs optimization.
4. Produces replenishment recommendations.
5. Returns planning results.

No manual JSON construction is required.

---

Expected Outcome

Users should be able to execute the complete planning workflow by providing Parquet datasets directly.

The API should support realistic planning scenarios where input data originates from enterprise systems rather than handcrafted JSON payloads.

---

Acceptance Criteria

• Parquet upload support implemented.
• Input schema validation added.
• Forecasting pipeline compatible with uploaded datasets.
• Optimization pipeline compatible with uploaded datasets.
• Planning endpoint supports end-to-end execution from Parquet files.
• Example datasets added to the repository.
• Swagger documentation updated.
• README updated with usage examples.