AI Demand Sense (pv_ai_demand_sense) — User Manual

Version v1 • For Odoo 18.0 • Forecasting, replenishment, alerts, profitability, anomalies & what-if simulation

1) Overview

AI Demand Sense adds real-time demand forecasting and replenishment logic to Odoo Inventory. It computes daily demand from done deliveries, applies seasonality and demand events, chooses the best forecasting model per product, and writes Min/Max to orderpoints (optional). You get coverage/stockout alerts, profit-aware recommendations, anomaly detection, and a clear “reorder up to” recommendation with a What-If simulator.

2) Installation & Upgrade

1. Install the module pv_ai_demand_sense.
2. After install, open Settings → Technical → Scheduled Actions and enable AI Demand Sense: Weekly Forecast & Orderpoint Update.
3. On upgrade: if you previously created PDFs links, they are no longer needed — guides are now embedded below.

3) Quick Setup (10 minutes)

1. Enable on categories: Inventory → Configuration → AI Demand Sense Categories.
   • Enable Forecasting ✓ • Strategy: Auto (best) • History: 90 days
   • Coverage Target: 14 days • Smoothing Alpha (if ES): 0.3 • Auto-update Orderpoints ✓
   • Service Level: 0.95 • Lead Time: your average inbound • Carrying Rate/Year: e.g., 0.25
2. (Optional) enable Apply Monthly Seasonality; add Demand Events for promos/holidays.
3. Run first forecast: Settings → Technical → Scheduled Actions → run the ADS job manually.
4. Review results: Inventory → Reporting → AI Demand Sense → Warehouse Coverage (use the Columns picker to show/hide fields).

If you lack history, create a few back-dated deliveries and set them to Done, then run the scheduler.

4) Concepts & How It Works

• Avg Demand / Day from daily delivered quantities in a lookback window; zeros are included to avoid overreacting.
• Auto model chooses among Moving Average, Weighted MA, Exponential Smoothing via backtesting (MAPE/RMSE).
• Seasonality scales current month by its historical factor; Events multiply daily demand by date-range factors (e.g., ×1.3 for promotions).
• Safety Stock = Z(service level) × σ(daily) × √H, where H = coverage + lead time (days).
• Base Stock Level = Avg × H + Safety; Min/Max Targets are derived from coverage and a max-multiplier; Reorder Up To = max(Base Stock, Max Target).
• Profit view: recommended order value, holding cost, net gain.
• Alerts & anomalies highlight risky items and unusual days.

5) Menu Map

• Inventory → Reporting → AI Demand Sense → Warehouse Coverage
• Inventory → Reporting → AI Demand Sense → Anomalies
• Inventory → Configuration → AI Demand Sense Categories
• Inventory → Configuration → Demand Events

6) Field & Column Reference

6.1 Warehouse Coverage (list view)

You can hide any column via the Columns picker (⋯) in the list header.

Beginner example: Avg=5/day, Coverage=14, H=14+LT(7)=21, Z(0.95)=1.645, σ=3 → Safety≈10.8 → Base≈5×21+10.8=115.8; Max Target=Min×1.5=105 ⇒ ReorderUpTo=120.1. On-Hand=80 ⇒ Recommended≈40.

6.2 Product Category (AI Demand Sense tab)

6.3 Demand Events

6.4 Anomalies

Daily log of unusual demand so planners can react early.

How detection works: build baseline over N previous days (default 28), compute z; if Std=0, use ratio/absolute rules so single big sales still trigger.

7) Typical Workflows

7.1 Weekly Purchasing Review

1. Open Warehouse Coverage, filter your main WH, sort by DTS asc.
2. Check Low Coverage flags; use Recommended (Profit) to place RFQs/POs.
3. Optionally run Simulate for borderline cases.

7.2 Promotion Planning

1. Create a Demand Event with multiplier (e.g., ×1.5), scoped to products/warehouses and dates.
2. Run scheduler; confirm coverage and adjust orderpoints/POs.

7.3 Daily Anomalies Triage

1. Open Anomalies, filter by Severity desc.
2. For spikes, consider raising coverage or adding a temporary event; for drops, investigate causes.

7.4 New Season

• Enable Monthly Seasonality on categories; validate month factors after first run.

7.5 New Product (no history)

• Start with shorter History (14–30) and Fixed model; add an event if you expect a launch burst.
• Switch to Auto once you have history.

8) Scheduler & Automation

• Name: AI Demand Sense: Weekly Forecast & Orderpoint Update
• Executes: env['product.template'].ads_run_now()
• Default interval: Weekly (adjust as needed)
• Writes: product metrics, per-warehouse coverage, and orderpoint Min/Max (optional)

9) Data & Backfilling Tips

• Engine reads done outgoing moves; confirming deliveries builds history.
• To seed test DB fast: create back-dated deliveries, mark Done, run scheduler.
• Multi-company & multi-warehouse supported; calculations are scoped accordingly.

10) Troubleshooting & FAQ

I sold 10 today, but Avg/Day ≈ 1.43.

Average includes zero-sale days in the window: 10 over 7 days ≈ 1.43. This avoids overreacting to one-offs.

No anomalies after large delivery.

If baseline Std=0, ADS uses ratio/absolute rules. Check Anomaly Ratio and Abs Qty on the category.

Access error opening Simulation.

Add your user to the ADS / Simulation security group.

Columns can’t be hidden.

Use the Columns picker (⋯) in list views; we extended these lists to support hide/show.

11) Best Practices

• Prefer Auto model unless you have strong reason to fix it.
• Keep Lead Time realistic; over-optimistic LT reduces safety stock too much.
• Use Events for known promos/holidays instead of editing demand manually.

12) Real User Cases

Case A — Hanna (Purchaser) in a Large Oil Company: Avoid Stockouts of Critical Components

Scenario. Critical gaskets/filters must never stock out at Main WH; lead times 10–14 days.

Show: Avg/Day, On Hand, DTS, Coverage, Min/Max, Reorder Up To, Recommended (Profit), SL, LT, Safety Stock. Hide: Model/Errors/CI, Unit Margin (if unused).

1. Enable ADS on the category; Strategy Auto; History 90; Coverage 14; SL 0.95; Lead Time 12; Auto-update ✓.
2. Run scheduler → open Coverage; filter Main WH; sort by DTS asc.
3. Simulate raising Coverage to 18 for erratic supply; place RFQs using Recommended (Profit).

Case B — Marco (Retail Planner): Black Friday Promotion

Scenario. 1-week 30% promo on headphones across two warehouses; expect +60% demand.

Show: Avg/Day, On Hand, Reorder Up To, Recommended (Profit), SL, Lead Time, Safety Stock, Est. Order Value/Holding/Net Gain. Hide: Errors/CI, Min/Max if focusing on Reorder Up To.

1. Create Demand Event: dates BF week, Multiplier 1.6, scope warehouses/products.
2. Run scheduler → Avg/Day rises; group by Warehouse to plan inbound split.
3. Simulate higher SL (0.98) during the week; place POs accordingly; deactivate event after.

Case C — Amina (Ops Manager, Food Distribution): Detect & React to Anomalies

Show: DTS, Avg/Day, On Hand, Low Coverage, Reorder Up To, Recommended (Profit). In Anomalies: Date, Product, WH, Observed, Mean/Std, zscore, Severity, Message, Assigned/Ack.

1. Set Anomaly |z|=2.5, Baseline=28, Ratio=2.5, Abs=20.
2. Let scheduler run; check Anomalies morning; act on spikes/drops; adjust coverage or add events.

Case D — Viktor (Production Planner, MTO Manufacturing): Keep Common Components Available

Scenario. Make-to-order shop; repeat components (bearings/fasteners) must be in stock to meet quotes.

1. Place all repeat components in an ADS-enabled category; Coverage 21–28 days.
2. Use Warehouse Coverage weekly; order Recommended (Profit) to avoid shortages delaying jobs.

Case E — Sofia (After-Sales, Spare-Parts Service): Hit SLA at Regional Depots

Scenario. North/West/Central depots; next-day repair SLA; winter heater spikes.

Show: Avg/Day, On Hand, DTS, SL, LT, Safety Stock, Reorder Up To, Recommended (Profit), Low Coverage. In Anomalies: same core fields.

1. Set Coverage 30–45, SL 0.98–0.99, LT from OEMs; Auto-update ✓.
2. Create seasonal Demand Events (winter ×1.4, summer ×1.3) by depot.
3. Group Coverage by Product to compare depots; plan transfers; use Anomalies daily to rebalance.

13) Change Log (high level)

• v1 — MVP + seasonality/events + finance + anomalies + simulation; column picker enabled on major lists.

14) Beginner Guide

AI Demand Sense — Beginner Guide
  
Audience:

Absolute beginners in purchasing and inventory planning.

1.WHAT THIS APP DOES:

- Looks at your past deliveries and estimates how many units you usually need per day.
- Shows which items will run low soon (per warehouse).
- Suggests how many units to buy now to stay safe.
- Optional: shows a simple money view (order value, holding cost, net gain).

2.KEY WORDS (PLAIN LANGUAGE):

- Warehouse: A physical place that stores products. Each warehouse is handled separately.
- On Hand: How many units you have right now in that warehouse.
- Average per Day: How many units you usually send out per day, based on past deliveries. Days with no sales count as zero.
- Days to Stockout: If you keep selling at the usual speed, how many days until you hit zero.
- Coverage Target: How many days of stock you want to keep as a rule. You set this on the product category.
- Recommended Qty: How many units to buy now to return to a safe level.

3.ONE-TIME SETUP (5–10 MINUTES):

- Go to Inventory → Configuration → AI Demand Sense Categories.
- Open a category you use and tick “Enable Forecasting”.
- Set Coverage Target (start with 14 days) and History Window (start with 90 days). Tick “Auto-update Orderpoints”.
- Optional money view: set Service Level to 0.95 and Lead Time to your typical supplier days.
- Save.

4.WEEKLY ROUTINE (SIMPLE CHECKLIST):

- Validate last week’s deliveries as usual.
- Run the scheduler: Settings → Technical → Scheduled Actions → “AI Demand Sense: Weekly Forecast & Orderpoint Update” → Run Manually.
- Open Inventory → Reporting → AI Demand Sense → Warehouse Coverage.
- Sort by Days to Stockout (smallest first). These are the risky items.
- Create purchase RFQs using Recommended Qty (or “Recommended Qty (Profit)” if you use the money view).

5.WHICH COLUMNS TO SHOW (BEGINNER):

- Turn on: Product Tmpl, Warehouse, Avg Demand / Day, On Hand (WH), Days to Stockout, Coverage Target, Recommended Qty (and/or Recommended Qty (Profit)), Last Computed On.
- Turn off for now: Model, MAPE, RMSE, CI Low/High, Safety Stock, Base Stock, Reorder Up To, Unit Margin, Est. Holding, Est. Net Gain. You can show them later when comfortable.

6.HOW TO READ THE MAIN NUMBERS (WITHOUT FORMULAS):

- Avg Demand / Day: One big sale spread over a week becomes a small daily average. This prevents over-buying because of a single lucky day.
- Days to Stockout: Example: 50 on hand, selling 5/day ≈ 10 days left.
- Coverage Target: Your rule of thumb (for example, 14 days). The app aims to keep you near this level.
- Recommended Qty: How much to buy now to get back to your safe level.

7.WHAT-IF (WHEN YOU NEED MORE SAFETY):

- In Warehouse Coverage, click “Simulate” on a product line.
- Try increasing Coverage (for slow suppliers), increasing Service Level (if you cannot accept stockouts), or increasing Lead Time (if the vendor is late).
- The wizard shows a new Recommended Qty. Use it for your RFQ.

8.PROMOTIONS OR SEASONAL PEAKS (EASY):

- Inventory → Configuration → AI Demand Sense → Demand Events.
- Create an event for the dates (for example, Black Friday week) and set a Multiplier (for example, 1.6 means +60%). Choose the products/warehouses it affects.
- Run the scheduler.
- Warehouse Coverage will show higher Avg Demand / Day and a larger Recommended Qty during that period.

9.ALERTS AND ANOMALIES (WHAT THEY DO):

- Low coverage alerts: When an item will run out too soon (below your rule), the app can post a note or create a task for you or a teammate.
- Anomalies: When a day’s demand is very unusual (spike or drop), it is logged so you can investigate. Use the “Anomalies” menu to review and act.

Simple examples:

Example 1 — A steady sellerYou have 80 units on hand. You normally sell about 5/day. Your target is 14 days of stock. The system will likely suggest buying around 40 units to get back to a safe level for the next weeks.
Example 2 — One big sale this weekYou sold 10 units on one day and nothing on other days. The average becomes about 1.4/day (10 divided by 7 days), not 10/day. This prevents over-buying due to a single large order.
Example 3 — Promotion next weekYou set a Demand Event with a multiplier of 1.6. The app increases the expected daily demand and suggests buying more so you don’t run out during the promo. Remove or end the event after the promo.

10.TROUBLESHOOTING (BEGINNER):

- The list shows zeros: Run the scheduler. If still zero, you may have no done deliveries in the window. Create a few test deliveries and validate them.
- The numbers didn’t change: Run the scheduler again; check “Last Computed On” in the report.
- I don’t see some menus: Ask your admin to add you to “AI Demand Sense User” (or Manager).
- Too many columns: Use the Columns button to keep just the basics listed above.

That’s it. Start with a single category, keep the basics visible, run the scheduler weekly, and use Recommended Qty to drive your RFQs.

When comfortable, move on to the Advanced Guide for profit, accuracy and simulation tools.

15) Advanced Guide

AI Demand Sense — Advanced Guide
  
Audience:

Users who completed the beginner guide and now want to tune accuracy, interpret diagnostics, plan promotions, and manage multi-warehouse inventories with confidence.

Learning goals:
- Choose and tune forecasting options by category (history, method, alpha, coverage).
- Read and act on advanced columns: MAPE, RMSE, CI, Safety Stock, Base Stock, Reorder Up To, Profit signals.
- Use Demand Events, What-If Simulation, Alerts, and Anomalies in real planning cycles.
- Align parameters with business scenarios (steady sellers, seasonal, MTO components, spare parts depots).
- Run a clean weekly/monthly operating rhythm with KPIs and saved views.

1.HOW THE ENGINE WORKS (PRACTICAL VIEW)

- Source of demand: done outgoing stock moves (deliveries). Days with no sales count as zero to avoid over-reacting to one-off peaks. Returns reduce net demand for that day.
- Computation cadence: by the scheduled action (weekly by default) or on demand.
- Scope: per product template × warehouse. Companywide totals are sums across warehouses (use groupings in the report).

Output family: 

- Demand level: Avg Demand / Day (seasonality/events applied).
- Coverage & targets: Min Target, Max Target (via multiplier), Days to Stockout.
- Risk buffers: Safety Stock, Base Stock Level, Reorder Up To.
- Recommendation: Recommended Qty (and Recommended Qty (Profit) when finance inputs are set).
- Diagnostics: Chosen Model, MAPE, RMSE, CI Low/High, Last Computed On.

2.CATEGORY TUNING — THE 4 KNOBS 

Open: Inventory → Configuration → AI Demand Sense Categories

History Window (days)

- Shorter (30–60): faster reactions, noisier.
- Longer (90–180): smoother, slower to react; good for stable items.
- Tip: If Avg/Day is unstable, lengthen. If it lags behind real changes, shorten.

Method (Auto or Fixed)

- Auto (best): uses backtesting to prefer the model that previously produced lower error.
- Moving Average: simple, robust for steady items.
- Exponential Smoothing (alpha): emphasizes recent sales; good for trending or slowly seasonal lines.

Alpha (only if using exponential smoothing)

- 0.2–0.4: gentle reaction.
- 0.5–0.8: swift reaction for promotional or volatile items.

Coverage Target (days)

- Sets the baseline days of stock you want on hand.
- Increase for slow/critical suppliers or strict service promises.
- Decrease for fast suppliers or costly items you don’t want to hold.

Advanced multipliers

- Max Qty Multiplier: scales Max Target above Min to reduce order frequency (e.g.,
Min=14d, Max Multiplier=1.5 → Max=21d).
- Service Level (0–1) and Lead Time (days): used for Safety Stock and the profit view; raise
these for critical items.

3.ADVANCED COLUMNS — HOW TO READ THEM

(Show/hide columns from the ⋯ Columns picker in Warehouse Coverage)

- Model: The method used after testing (Auto) or the fixed choice.
- MAPE (Mean Absolute Percentage Error): lower is better; below 20% is solid for many retail/wholesale
contexts.
- RMSE (Root Mean Squared Error): absolute error in units; compare SKUs of similar volume
- CI Low / CI High: the range the model expects (uncertainty band). Wide bands = unpredictable
SKU; consider higher coverage.
- Safety Stock: extra buffer driven by variability, service level, and lead time/coverage horizon.
- Base Stock Level: Avg × (Coverage + Lead Time) + Safety.
- Reorder Up To: max(Base Stock Level, Max Target).
- Recommended Qty: max(0, Reorder Up To − On Hand).
- Unit Cost, Unit Margin (if configured), Est. Holding, Est. Net Gain (cycle): finance view to prioritize RFQs by value, not just volume.

Quick formulas (operational, not strict math proofs):

- Avg/Day: rolling daily mean over history (zeros included) → adjusted by events/seasonality.
- DTS (Days to Stockout) = On Hand ÷ Avg/Day.
- Min Target = Coverage × Avg/Day.
- Max Target = Min Target × Max Multiplier.
- Safety Stock ↑ with higher variability (σ), higher service level (Z), longer horizon (Coverage + Lead Time).
- Base Stock Level = Avg × (Coverage + Lead Time) + Safety.
- Reorder Up To = max(Base Stock, Max Target).

4. WHAT-IF SIMULATION — DECISION PLAYGROUND

Open: Warehouse Coverage → select a line → Simulate

Use cases:

• Supplier warning of delays → increase Lead Time.
• Contractual service level change → raise Service Level to see Safety Stock impact.
• DC rationalization → change Coverage to test central vs. local stocking strategy.

Action: The wizard outputs a new “Reorder Up To” and “Recommended” for that scenario.
Use it to size your RFQ/transfer.

5.DEMAND EVENTS — RUN PROMOS WITHOUT BREAKING THE MODEL

Open: Inventory → Configuration → AI Demand Sense → Demand Events

- When: short-term campaigns, season kicks, planned spikes.
- How: set the date window, scope (products/warehouses), and a multiplier (e.g., 1.6 for +60%).
- Rhythm: create event → run scheduler → review higher recommendations → close event after the period.
- Tip: For massive events, shorten History Window temporarily or plan post-event to avoid lingering uplift.

6. ALERTS & ANOMALIES — MANAGE EXCEPTIONS

Low coverage alerts:

- Category settings: threshold in “Days to Stockout” and whether to post a chatter note and/or create an activity, and assignee.
- Use for morning triage: filter Warehouse Coverage by low DTS; work top-down.

Anomalies (spikes/drops):

Tuning knobs (category level):
- z-score threshold (sensitivity to deviations from baseline),
- ratio threshold (today vs. baseline mean),
- absolute quantity threshold (ignore tiny blips).

Playbook: if no anomalies appear, lower thresholds; if too many, raise them. Confirm genuine causes (promo/returns) before changing parameters.

7. SCENARIO RECIPES (PARAMETER PLAYBOOK)

Steady seller (predictable):
- History: 90–180 days
- Method: Moving Average or Auto
- Alpha: n/a or ≤0.4
- Coverage: 14–21 days
- Notes: watch MAPE; if consistently if consistently below 15%, you’re in the sweet spot.

Seasonal/promoted:
- History: 60–120 days
- Method: Exponential Smoothing or Auto
- Alpha: 0.5–0.7
- Coverage: 21+ during season; revert after
- Use Demand Events for the exact window.

MTO components (must not block MOs):
- History: 60–120
- Method: Auto
- Alpha: 0.4–0.6
- Coverage: lead-time + 7–14 buffer
- Service Level: 0.97–0.99
- Tip: accept some over-stock to protect throughput.

Spare parts depot (erratic, critical):
- History: 120–180
- Method: Exponential Smoothing or Auto
- Alpha: 0.3–0.5
- Coverage: 30+ for critical SKUs
- Service Level: 0.98–0.99
- Use Anomalies to catch outlier claims; keep CI columns visible.

8.MULTI-WAREHOUSE STRATEGY

- Group by Product Tmpl to compare depots side by side.
- Sort by Days to Stockout to spot deficits; consider internal transfers from surplus sites.
- Don’t force identical Coverage across very different lead times; tune by region/vendor.
- For central DC + spokes: higher Coverage at DC, lower at spokes; plan transfers weekly.

9.PROFIT VIEW — BUY SMARTER, NOT JUST MORE

Pre-requisites: correct Standard Price (cost) and either List Price or margin inputs in your environment.

- Show: Unit Cost, Unit Margin, Est. Order Value, Est. Holding (cycle), Est. Net Gain (cycle).
- Compare SKUs by Est. Net Gain to prioritize RFQs.
- What-If: raising Service Level raises Safety Stock and Holding Cost; balance against lostsales risk.
- Pitfall: unreliable prices → misleading profit view; fix product pricing first.

10.WEEKLY/MONTHLY OPERATING RHYTHM (CHECKLIST)

Weekly:
- Validate deliveries, returns.
- Run scheduler.
- Warehouse Coverage → “Buyer View”: DTS ↑, Recommended (Profit), Last Computed On.
- Create RFQs; note exceptions (supplier caps, MO priorities).
- Review Alerts/Activities and Anomalies.

Monthly / Post-season:
- Compare MAPE/RMSE across categories; if high, revisit method/history/alpha.
- Adjust Coverage targets (up for unreliable supply, down for fast supply/costly stock).
- Audit Demand Events that ended; ensure they’re closed.
- Export pivots to track KPI trends.

11.DATA QUALITY & PERFORMANCE TIPS

- Deliveries must be “Done” with accurate dates; otherwise history is thin or mis-timed.
- Returns should be posted correctly to avoid inflated averages.
- Avoid extreme History Windows (too long hides turning points; too short creates whiplash).
- Scheduler: keep weekly; add mid-week run during promos.
- Saved Views: create role-based column sets (Buyer, Planner, Analyst).

12.ADVANCED TROUBLESHOOTING

- Avg/Day feels too low after a big order: remember zeros are counted; consider Demand Event if a sustained uplift is expected.
- Wide CI bands: SKU is volatile; increase Coverage or Service Level; consider separate stocking at DC vs. spokes.
- Too many anomalies: raise z-score, ratio, or abs thresholds; exclude known event dates.
- Profit recommendations look odd: verify Standard Price/List Price; check Lead Time and carrying cost rate on the category.
- Orderpoints not updating: ensure “Auto-update Orderpoints” is enabled on category and user has rights; rerun scheduler and check chatter for “[ADS]” entries.

13.ADVANCED FAQ

Q: When should I lock method to “Exponential Smoothing” instead of Auto?
A: When you know the SKU has trend/seasonality and Auto keeps flipping to moving average due to short noisy windows.

Q: How do I pick alpha?
A: Start 0.5 for fast-moving seasonal; lower (0.3–0.4) for noisier/erratic SKUs to avoid overreacting.

Q: My supplier doubled lead time temporarily. What’s the quickest response?
A: Use What-If to test Lead Time +7 to +15 days and raise Coverage. Save the new RFQ size; revert after supplier stabilizes.

Q: How to justify stock increases to finance?
A: Show CI (uncertainty), Service Level requirement, and Est. Net Gain vs. Est. Holding from the profit view; tie to lost-sales risk.

Q: Why do two warehouses show different Avg/Day for the same SKU?
A: Averages are per-warehouse based on their own deliveries. That’s intended; plan transfers accordingly.

14.QUICK START FOR POWER USERS (ONE PAGE)

- Categories: Enable, set History 90, Coverage 14–21, Auto, Alpha 0.5 for seasonal only.
- Events: create before promos; remove after.
- Weekly: run scheduler → “Buyer View” → RFQs by Recommended (Profit).
- Analyst View: Model, MAPE, RMSE, CI, Safety, Base, Reorder Up To.
- What-If: tune Service Level/Lead Time/ Coverage for critical SKUs; use results immediately.
- Multi-warehouse: group by product; transfer from surplus to deficit.
- KPIs: aim MAPE below 20%; if higher, revisit parameters or data quality.

That’s it. With these tools you can (1) keep service high, (2) control risk with the CI/Safety Stock
lens, and (3) spend money where it produces the best return.

Need a branded edition (logo/company name) or screenshots? Add them to this HTML or contact your implementer to embed as a QWeb page.