Flowlity Co-planner

Return forecast accuracy, model setup, and review status for one product. Includes MAPE/MAE/FVA accuracy windows, the forecast model demand type, whether the planner configured expert models (for new products an expert/launch model is an alternative to a similar-product link), and the last demand/planning review dates by a planner.

Return Flowlity forecast versions for one product, by target month. Shows how the monthly forecast for a given target month evolved across forecast runs (e.g. May-26 run forecasted Aug-26 = 30; Jun-26 run forecasted Aug-26 = 45). Rows are sorted by target month then by forecast run date (`updated_date`) ascending, so the latest run is at the bottom of each target-month block. Forecasts are sourced from the Flowlity ML output at the site's configured granularity — `ml.demand_forecast_flowlity_day_aggregated`, `_week_aggregated`, or `_month_aggregated` depending on `config.site_global.forecast_granularity` (daily / weekly / monthly, default weekly). Day and week buckets are aggregated into calendar months via `date_trunc('month', target_date)`; a bucket whose start date straddles a month boundary is attributed to the month containing its start. Forecast runs that happen within the same calendar month as the target are excluded so partial-month sums don't appear as a sudden revision (matches the dbt accuracy convention). Dates must be in YYYY-MM-DD format. `target_month_start` and `target_month_end` are inclusive and bound the target months covered.

Return the future demand a site has received, bucketed by period. Reads `public.demand_future`: one row per product, customer and day, split by `status`: `firm` is a confirmed sales order, `planned` is expected demand not yet confirmed. Covers the whole site by default; pass `product_site_id` for one product, or `customer_id` (resolve it with `list_customers`) for one customer. `granularity` is `month` (default), `week` or `day`. The `Origin` line splits the total between the site's own customers, a child site (intercompany) and MRP explosion of a BOM. Only the first is a customer order: read the split before quoting `Total` as demand from customers, since a site whose demand is mostly intercompany transfers or exploded components would otherwise read as one with a full order book. `start_date` and `end_date` are inclusive, in YYYY-MM-DD format; past dates are allowed. A range that starts or ends inside a bucket makes that bucket partial, so ask from the 1st of a month to the last day of one before comparing monthly totals. `limit` caps how many buckets come back (default 50, max 1000), taking the earliest ones: a range that needs more is cut off at its far end, and the header says so when that happens. Set `chart=True` to also get firm and planned demand as a chart image, drawn from the same rows. Leave it off unless a picture is wanted: an image costs input tokens on this turn and on every later one.

Return latest import status rows by site, dataset, or specific import id.

Return monthly KPI trend points, with optional tag-level filtering. Valid `kpi` values: demand_plan, inventory_level, supply_plan, stock_coverage, zero_stock_days. Units: demand_plan / inventory_level / supply_plan trends carry a quantity (default unit) and a value (EUR). stock_coverage is expressed in days of coverage (site average) — it has no value/currency dimension. zero_stock_days is a 0-1 rate shown as a percentage. Set `chart=True` to also get the trend as a chart image, drawn from the same rows. Leave it off unless a picture is wanted: an image costs input tokens on this turn and on every later one.

Return demand and forecast bucketed by calendar month for a product. Use this tool for cross-year same-month comparisons (e.g. compare the forecast for Jul-26 against the actual demand for Jul-25 and Jul-24). Each row aggregates one calendar month between `start_date` and `end_date` (inclusive, YYYY-MM-DD). `Actual Demand` is summed from `public.demand` (typically populated for past months); `Final Forecast` and `Flowlity Forecast` are summed from `public.final_forecast` (typically populated for current/future months). Use a date range that spans the years you want to compare. Set `chart=True` to also get actuals and both forecasts as a chart image, drawn from the same rows. Leave it off unless a picture is wanted: an image costs input tokens on this turn and on every later one.

Return My Forecast (planner override) values for a product, past dates included. Reads `public.my_forecast`, which keeps planner-entered forecast values for past buckets as well as future ones. Each row is one forecast bucket date (site forecast granularity, typically the week start) with the quantity summed across customers, the date of the last edit, and the source (`user` = edited in the app, `data` = imported). Buckets whose override was cleared (no value) are omitted. Combine past values with actual demand (`get_monthly_demand_forecast`) and Flowlity forecast versions (`get_forecast_history`) to judge whether planner overrides improved or degraded forecast accuracy. Dates must be in YYYY-MM-DD format; past dates are allowed.

Get order alert summaries and recent alert rows.

One-call order review for a site: what to validate, what is late, and qty vs stock. Composite tool for the order-analysis use case. Returns a summary of open orders and validation deadlines (overdue / next 7d / 14d / 30d), the list of planned orders to validate (soonest deadline first, with order qty next to current stock), and the top suppliers with late firm deliveries. Use this instead of paging `list_orders` and cross-checking statuses and dates by hand. A planned order (`status_id = 1`) must be validated by its `latest_order_date`; a firm order (`status_id = 3`) whose delivery date has passed counts as a late delivery.

Return product-level planning constraints (coverage, min/max stock, shelf life). This is the product level (public.product_site): the inventory policy that constrains a product on its own, independent of supplier — minimum stock policy, target coverage days, maximum stock, shelf life and stock valuation price. Filter with ``product_ids`` and/or ``tag_ids``. For supplier-specific MOQ/lead time/price/lot size use ``get_product_supplier_constraints``.

Return full product details including tags, suppliers, alerts, and BOM. The "Forecast Model & Review" section reports the planner's expert/launch model (an alternative to a similar-product link for new products) and the last demand/planning review dates, so the forecast-audit skill can avoid flagging products that have an expert model or were recently reviewed.

Return the planning time series (stock, supply, demand, forecast, min, max) for ONE product over a date range. Use this to inspect a single product's projected stock curve. For "which products are in stock-out or at risk", use `list_product_alerts` instead. `granularity` is `day` (default), `week` or `month`. **Ask for `week` or `month` on any range longer than a month or so**: the default window is 90 days against a `limit` of 30, so a daily call over it returns a third of the range. Aggregating in SQL is the cheaper answer than a bigger `limit` — a year is 12 monthly buckets. Aggregation is per column, because the columns are not the same kind of number. Supply, demand and forecast are flows and are summed. Stock is a level, so it is the bucket's **closing** value, and a second column gives the bucket's **lowest** stock — which is what answers "does this week break the minimum", and what a daily table makes a reader scan for by eye. Set `chart=True` to also get this series as a chart image, drawn from the same rows. Leave it off unless a picture is wanted: an image costs input tokens on this turn and on every later one.

Return per-supplier sourcing constraints for products (MOQ, lead time, price, lot size). This is the product x supplier level (public.product_supplier_link): the MOQ, lead time, unit price, lot size and order frequency negotiated with each supplier for each product. Defaults to the primary supplier per product (highest active quota share, resolved from public.quota); set ``primary_supplier_only=False`` to list every supplier grouped by product x supplier. Filter with ``product_ids`` and/or ``tag_ids``. Products with no supplier linked are not in this list: use ``list_products(without_supplier=True)`` for them, never a comparison of the two lists. For supplier-wide constraints (basket MOQ, full truck) use ``get_supplier_constraints``; for product planning policy (coverage, min/max stock, shelf life) use ``get_product_constraints``; for tag-based supply agreements use ``get_tag_constraints``. When a row has a non-null Tag Family / Family MOQ, the line MOQ is enforced at the **tag-family scope** (sum over every product in the family >= Family MOQ) at sites where config.site_or.tag_family_moq is on. Audits like "MOQ vs forecast" should aggregate demand at the family level in that case, not per product. Use ``list_products(tag_ids=[<family_id>])`` to enumerate the family.

Get one promotion: its economics, its budget line, and its products. Returns the whole read-time cost derivation — mechanic preset, generosity rate, committed volume, redemption rate, redeemable units, forecast NIP cost, gross and net cost, max liability, flat fee, net coefficient — plus the invoiced/outstanding split for a NIP, the realised sell-out against the forecast for the days already past, and the per-product impact rows at `site_id`. Every euro figure is derived from the stored inputs at read time (the schema stores no cost), by the same math the Flowlity app uses, so a number here should equal the number on the promotion's page. Those figures are company-wide; the per-product table is the only site-scoped part of the answer, and `limit` bounds it.

Aggregate promotion volume, revenue and cost over one dimension. This is the reporting tool: it answers "net cost per retailer this quarter", "which mechanic costs most", "how much of each budget is consumed" in one query. Do **not** page `list_promotions` and add the rows up — 300 promotions is 300 rows of client-side arithmetic and the totals will not match the app's. `group_by` is one of: `customer`, `type`, `mechanic`, `status`, `month` (the promotion's start month), `budget`, `owner` (the envelope's key account manager). Set `chart=True` to also get net cost and revenue by month as a chart image, drawn from the same rows as the table. Only `group_by=month` records a series — the other dimensions are rankings, not a time axis. Filters: `period_start` / `period_end` (YYYY-MM-DD, inclusive) select promotions *overlapping* the window; `status` (`planned`, `in_progress`, `confirmed`; comma-separated), `customer_id` and `promotion_type` narrow further. `Allocated` is the total of the distinct budget envelopes the group's promotions charge, and `% Consumed` is the group's net cost against it — so with `group_by=budget` it is the envelope's own consumption, and with any other dimension it is that slice's share of the envelopes it touches. `Realised / Forecast` compares realised sell-out against the forecast for the days already past, never the whole period.

Fetch detailed site configuration and feature flags.

Return aggregated dashboard KPIs for a site (inventory, demand, supply, forecast). Call this first for a site-wide overview before drilling into per-product tools. For one KPI over a date range, use `get_kpi_trends`.

Fetch one of Flowlity's written procedures for a recurring planning job. Call this *before* starting the work it describes, not after: it gives the order to do things in, which tools to use, and the mistakes that make an answer wrong. If the user names a skill below — with or without a leading slash — fetch that one, even when a different skill looks like a better match for what they are asking about. A name they typed is an instruction, not a hint, and overriding it silently leaves them with no way to get the procedure they asked for. The identifier, the title, or a unique part of either all resolve, so pass whatever they wrote. When you have followed one, end with a single short line naming it — "Followed Flowlity's <title> procedure; ask for it by name next time." Most users never learn these exist, and the moment they have just been useful is the only moment worth spending a sentence on it. **The set is not listed here.** It is authored outside this deployment and changes without one, so call this with **no name** first to get the current list, then fetch the one you need by name. Do that for "what procedures do you have" asked in general, and equally when the user names or describes **one** job — "is there a guide for a replenishment review?" — because the list is where the exact name comes from. **Call it again every time you are asked, even when you already have a list.** The set changes while a conversation is open — someone adding, pausing or removing one between two questions is ordinary — so an earlier reply of yours is not evidence of what exists now. Answer from a fresh call, never from the transcript.

Return stock-coverage metrics and optional low-coverage filter.

Return past stock on hand for ONE product over a date range, by period. This is inventory *history* — what the product actually held on a past date. `get_stock_levels` gives stock as of today, and `get_product_planning` only starts at yesterday and runs forward, so this is the tool for "how much stock did we hold in March", for stock seasonality, and for any month-over-month inventory comparison. Reads `dbt_flowlity.past_stock`, the daily series the app's own inventory KPIs are built from, so the figures agree with the UI. It is `public.stocks` made continuous: that table holds a row only where an import wrote one, and a gap between two rows is the stock staying put rather than the stock being unknown — so each reading is carried forward until the next one, storage sites are summed, and shortend storage counts as zero. Querying `public.stocks` by date directly returns nothing on most dates for that reason. `granularity` is `day` (default), `week` or `month`. **Ask for `week` or `month` on a range longer than a month or so**: a year of daily buckets is past the ceiling this tool will return, and aggregating in SQL is the cheaper answer than a bigger `limit`. Stock is a level, not a flow, so it is never summed — an aggregated bucket reports its **closing** stock plus the average, lowest and highest stock inside it. The average is the inventory figure an S&OP or IBP review quotes for a period; the low is what says whether the period ran dry. `start_date` and `end_date` are inclusive, in YYYY-MM-DD format. A range starting or ending mid-bucket makes that bucket partial and its average an average of fewer days, so ask from the 1st of a month to the last day of one before comparing monthly figures. The series ends at the last completed day; for stock as of today call `get_stock_levels`, which also breaks it down by storage site. For a whole site or a tag rather than one product, use `get_kpi_trends` with `kpi='inventory_level'`: it is monthly, and it carries the value in EUR as well as the quantity. Set `chart=True` to also get the series as a chart image, drawn from the same rows. Leave it off unless a picture is wanted: an image costs input tokens on this turn and on every later one.

Return stock levels either by product or storage-site breakdown.

Return supplier-wide constraints (basket MOQ, full truck, order frequency). This is the supplier level (public.partner_site): constraints that apply to a whole order to a supplier rather than to one product line — the basket minimum order quantity, full-truck quantity, order frequency, max supplies per order and transportation lead time. Lists the suppliers used at the site. Filter with ``supplier_ids`` (partner_site IDs). For per-product MOQ/lead time/price/lot size use ``get_product_supplier_constraints``.

Return tag-based supply-agreement constraints applied to products. This is the tag level (public.tag via public.product_tag_link): lot size and supply-agreement / supply-price rules defined once on a tag and shared by every product carrying it. Returns one row per product x constraint-tag. Filter with ``product_ids`` and/or ``tag_ids``. Per-supplier MOQ/lead time/price lives in ``get_product_supplier_constraints``; supplier-wide rules in ``get_supplier_constraints``.

Return the full config of a view (columns, filters, sorting, compiled where). Use it to verify a view you just created, or to mirror an existing working view before cloning its column/filter set. Works for any view on a site you can access (not just ones you created).

One-call weekly supply-chain review for a site: KPIs, risks, and order actions. Capstone digest for the recurring weekly supply-chain presentation. Combines the site headline KPIs, the stock-out and overstock risk counts (including how many stock-outs have no firm order on the way), the order validation backlog (overdue / 7d / 14d / 30d) and late deliveries, plus short top-`top_n` lists of the orders to validate this week and the stock-outs that need an order. Use this for a weekly summary instead of calling the KPI, alert and order tools separately.

Compare two files the user uploaded, matched on a shared reference. The question this exists for is "last month's export against this month's": two files whose rows correspond through a SKU, a supplier code or an article reference, where the answer is a number over the pair rather than over either one. **The reply says how many rows found a partner**, always. A pairing that matched nothing looks exactly like a file with nothing above the threshold, and the usual cause is one of the two exports having lost an identifier's leading zeros in Excel — `describe_uploaded_file` warns about that, and this is where it bites. Rows that matched nothing are counted, not listed. Both files must belong to the caller's company; either one that does not resolves to nothing. Call `describe_uploaded_file` on each file first, for its column names. Pass `chart=True` on `/mcp` to get a grouped answer as an image as well; the agent bridge strips both the flag and this paragraph, since that channel has the cheaper `chart` event.

List site capacity units with supplier and product counts.

List the site company's customers with their internal ids. Use this to resolve a customer name or external id (e.g. "Aldi") into the internal id that `create_promotion(customer_ids=...)` expects. `search` matches name and external id; `Products` counts the products linked to the customer on this site.

List all tables in demo schemas (schemas starting with `demo`).

List products with an end-of-life (EOL) date and their remaining stock. Surfaces products carrying a `sale_end_at` date so planners can monitor and run down stock. Each row also carries **past demand and the forecast model**, which is what separates an item that is genuinely finished from one whose EOL date is simply wrong: zero 12-month demand with a `no_data` model is dead, while a named model and recent demand means the date needs correcting, not the status. Both come off a table this query already joins, so the whole set is one call rather than one `get_demand_summary` per row. Set `past_due_only=True` for products already past EOL, and `only_with_stock=True` to keep only those still holding stock: together they answer "which discontinued items still have warehouse stock to push to stores". The summary line also reports how many products have an EOL date defined at the site. Set `chart=True` to also get the stock value per item as a chart image, drawn from the same column the table prints. Leave it off unless a picture is wanted: an image costs input tokens on this turn and on every later one.

List order lines for a site, with optional product/supplier/status/date filters. Use this for orders placed, to validate, due soon, or late. For late or at-risk order lines specifically, see `get_order_alerts`.

List product alerts (stock-out, overstock, and other risks) with summary counts by criticality. This is the entry point for "what is in stock-out, at risk, or needs action". Each alert carries criticality, the exceeding quantity/value, and the last date to act. For one product's detailed stock curve, use `get_product_planning`.

Search and list products with inventory and demand KPIs, including end-of-life (sale end) date and default unit. ``without_supplier=True`` keeps only products with no supplier linked — the app's "Without supplier" filter. Use it for "which products have no supplier" rather than comparing this list with ``get_product_supplier_constraints``.

List the promotion budget envelopes with what the promotions charge them. One envelope is a (retailer × cost type × period) pocket of money. Only `Allocated` is stored: `Consumed`, `Confirmed only`, `Ceiling` and `Remaining` are summed at read time from the promotions pointing at the envelope, the same way the app's budget checkbook does it. - `Consumed (net)` — every linked promotion's net forecast cost. - `Confirmed only` — the subset in status `confirmed`; the finance-grade number, since that is what reaches the ERP. - `Ceiling` — the worst case: for a NIP, the whole committed volume selling through with every unit redeemed. - `Remaining` — allocated − consumed. Negative means overcommitted. Filters: `customer_id` (resolve with `list_customers`), `budget_type` (`nip` consumer discounts, `rsf` invoice discounts, `tmp` trade-marketing fees — comma-separated for several), `period_start` / `period_end` for envelopes *overlapping* that window, and `owner_email` for one key account manager's envelopes (substring match).

List promotions / forecast events with their retailer and net cost. Filters, all optional and all combinable: - `status`: one or more of `planned`, `in_progress`, `confirmed` (comma-separated). `planned` is the weekly Promotion Optim algorithm's own proposal (the retailer vocabulary's *proposed*), `in_progress` is a planner's draft that the algorithm leaves alone (their *planned*), `confirmed` is validated. Only `confirmed` **product links** feed the stored final forecast and the ERP export, so a report about what is in the forecast slices on that. There is no `rejected` status: a refused promotion is deleted today. - `customer_id`: the retailer the promotion was negotiated with — resolve the id with `list_customers`. This is the per-retailer reporting axis; a promotion with no customer is company-wide. - `promotion_type`: `nip` (consumer checkout discount), `discount` (invoice discount / RSF), `catalog`, `featured_placement`, `other`. - `budget_id`: only promotions charging one budget envelope (`list_promotion_budgets` has the ids). - `period_start` / `period_end` (YYYY-MM-DD, inclusive): promotions whose period *overlaps* the window, not only those contained in it. - `search`: matches the name and the external id. `Net Cost` is the forecast cost that charges the budget envelope, derived read-time from the promotion's own inputs — the same math the Flowlity app shows. It is a company-wide figure: `site_id` scopes the `Products` count and the access check, not the money. Use `get_promotion_detail` for how a cost was built, and `get_promotion_kpis` to aggregate rather than paging this list.

List detected past shortage periods (possible shortages) for a site. Flowlity detects periods in the demand history where a drop in demand is likely explained by a stock shortage rather than a real demand decrease. Status reflects planner review: `possible` (detected, not yet reviewed), `confirmed`, or `rejected`. When a planner adjusted the period, the user-set dates replace the detected ones. Use this to avoid flagging past demand drops that are already explained by a (possible) shortage. `start_date`/`end_date` (YYYY-MM-DD) keep only periods overlapping the given range.

List accessible sites with key company and feature data.

List products in stock-out (or below minimum) that have no firm order incoming. Composite tool for the "stock-out + no firm order" review: it finds product-sites with an active or upcoming shortage alert (`OUT_OF_STOCK` or `BELOW_FLOWLITY_MIN`) and no firm (released) order with a delivery date today or later. Use this instead of calling `list_product_alerts` and `list_orders` separately and cross-checking. Pass `horizon_days` to keep only shortages starting within that many days.

List tags available for a site's company and product links.

List the column keys a view of `module` accepts, each with a human label. Pass `site_id` to also list this company's tag categories as `tag_category_id:{id}` columns (usable as columns or as `group_by`). Unlisted snake_case KPI keys are also accepted; the app ignores unknown columns at render, so they never crash a view.