Supply and Demand Planning Copilot
Outcome
Give the demand planner a consensus planning surface that reconciles statistical forecast, promotion lifts, open orders and weather-sensitive demand at the item-location level, explains every override, and routes exception-level changes for commercial sign-off.
| Portfolio attribute | Value |
|---|---|
| Primary persona | Planner |
| Primary aggregate | PlanningUnitForecast |
| Cosmos DB containers | 1 |
| Grounding data | forecasts, orders, inventory, promotions, weather |
| Development estimate | USD 60-220 monthly dev estimate |
| Runtime options | Python FastAPI and C# ASP.NET Core |
Productivity hypothesis
These measures reflect the workflow, evidence, decision boundary, and industry risk for this use case.
| Impact type | Measure | Conservative internal assumption | Customer measurement |
|---|---|---|---|
| Productivity | Planning cycle time | 10-18% reduction | (baseline median planning minutes - assisted median planning minutes) / baseline median planning minutes * 100 |
| Quality or risk | First-pass plan acceptance | 5-10 percentage-point improvement | assisted percentage of plans accepted without material rework - baseline percentage |
Important: Conservative internal pilot assumptions only; not public benchmarks, commitments, or expected customer results. Validate against a comparable baseline or matched control cohort with mandatory human review.
Rationale: Forecast, order, inventory, promotion, and weather evidence can accelerate draft-plan preparation and reduce revision loops.
Pilot guardrail: Expose forecast conflicts and uncertainty; planners retain inventory and allocation authority.
Customer validation plan
- Baseline the current workflow with representative users and tasks.
- Run the accelerator on the same task mix with human review retained.
- Measure planning cycle time and first-pass plan acceptance with the documented formulas.
- Replace internal assumptions with customer-observed results before a business case.
Why Azure Cosmos DB
This AI solution needs an operational data plane, not only a vector index:
- Hybrid vector and full-text retrieval combines semantic recall with exact identifiers, codes, names, and domain language.
- Hierarchical partition keys and metadata predicates keep tenant and domain boundaries in the normal query path.
- Operational JSON, source chunks, workflow and agent state, feedback, and audit records remain together for low-latency reads and governed writes.
- Change feed reacts to source and operational updates without polling.
- Autoscale throughput, configurable consistency, and multi-region distribution support variable demand and enterprise availability.
Domain workflow

| Stage | Actor | Input → output | Approval |
|---|---|---|---|
| 1. Statistical baseline generation | Forecast engine | DemandSignal → ForecastVersion | Policy controlled |
| 2. Promotion and event netting | Supply and demand planning copilot | PromotionPlan → adjustedForecastVersion | Policy controlled |
| 3. Exception detection and explanation | Supply and demand planning copilot | adjustedForecastVersion → ForecastOverride | Policy controlled |
| 4. Consensus review with commercial teams | Planner, sales and marketing | ForecastOverride → consensusDecision | Human required |
| 5. Consensus lock and supply handoff | Demand planner | consensusDecision → lockedForecastVersion | Human required |
Technical architecture

Cosmos DB data model
| Container | Hierarchical partition key | Documents | Search paths |
|---|---|---|---|
planningUnitForecasts | /tenantId, /planningUnitId | PlanningUnit, ForecastVersion, PromotionPlan, DemandSignal, PlanningNarrativeChunk, ForecastOverride | /chunkVectorEmbedding, /rationaleVectorEmbedding, /chunkVector, /rationaleVector |
Query contract
| Query | Container | Scope | Purpose |
|---|---|---|---|
| ExceptionPlanningUnits | planningUnitForecasts | single-partition | Evaluate whether one item-location planning unit exceeds the forecast-error review threshold for this cycle. The complete tenantId and planningUnitId hierarchical partition key routes the query to one logical partition. |
| ForecastVersionComparison | planningUnitForecasts | single-partition | Compare statistical, promotion-adjusted and consensus versions across buckets for one planning unit. |
| OverlappingPromotionWindows | planningUnitForecasts | single-partition | Detect promotions whose windows overlap so their lifts are netted rather than additively stacked. |
| OverrideJustificationRetrieval | planningUnitForecasts | single-partition | Retrieve prior consensus minutes and advisories that support or contradict a proposed override. |
Python and C# services route each document type to its declared container and hierarchical partition key. ETag-based writes protect mutable aggregates, while append-only records and bounded cross-partition queries preserve scale.
Azure deployment

Clone the source repository, authenticate with Azure, and run:
Set-Location accelerators/agriculture-food/supply-and-demand-planning-copilot
az login
./Deploy.ps1 -Runtime python -Location eastus2
Change python to csharp to deploy the .NET implementation.
Explore the implementation
- Launch signed-in demo
- Implementation article
- Domain data model
- Workflow and API contract
- Python application
- C# application
- Domain container Bicep
- Platform Bicep
- Cost and configuration
- Source repository