From 35ddc67b7c0813304f4a8d12beb72a1eefdbe7df Mon Sep 17 00:00:00 2001
From: Nik Richers <nik@validmind.ai>
Date: Tue, 10 Feb 2026 15:11:56 -0800
Subject: [PATCH] Document vm_today and datetime support in calculated fields

Add collapsible example for date arithmetic in model inventory
calculation fields: vm_today, date, datetime, timedelta, relativedelta.
Includes next review date and days-remaining countdown examples.
Notes timestamp input and string output behavior.

[sc-7465]
---
 site/guide/model-inventory/_field-types.qmd | 50 +++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/site/guide/model-inventory/_field-types.qmd b/site/guide/model-inventory/_field-types.qmd
index fdcba17f63..e5772b31f4 100644
--- a/site/guide/model-inventory/_field-types.qmd
+++ b/site/guide/model-inventory/_field-types.qmd
@@ -56,6 +56,56 @@ Your calculated field is grouped under `Model Risk` inventory fields, and can on
 :::
 :::
 
+::: {.callout-button .pl4 .nt4}
+::: {.callout collapse="true" appearance="minimal"}
+
+### Example — Date arithmetic and vm_today
+
+Formulas can use date and time types for scheduling and countdowns. The following are available in your formula:
+
+| Name | Description |
+|------|-------------|
+| `vm_today` | Today's date (updates each time the formula runs) |
+| `date` | Python's `datetime.date` class |
+| `datetime` | Python's `datetime.datetime` class |
+| `timedelta` | Duration in days, seconds, or microseconds |
+| `relativedelta` | Duration in months, years, etc. (from `dateutil`) |
+
+**Next review date** — Add an interval to an approval date based on risk tier:
+
+```python
+def formula(params):
+    if params.dmApprovedDate == "":
+        return "N/A"
+    approved_date = date.fromtimestamp(int(params.dmApprovedDate) / 1000)
+    review_frequency = {
+        "Tier 1": relativedelta(months=3),
+        "Tier 2": relativedelta(months=6),
+        "Tier 3": relativedelta(years=1),
+    }
+    frequency = review_frequency.get(params.dmRiskTier)
+    if not frequency:
+        return "N/A"
+    next_review_date = approved_date + frequency
+    return next_review_date.isoformat()
+```
+
+**Days remaining** — Use `vm_today` to show a countdown to the next review (formula re-evaluates so the countdown updates over time):
+
+```python
+def formula(params):
+    if not params.nextReviewDate:
+        return "N/A"
+    next_review = date.fromisoformat(params.nextReviewDate)
+    difference = next_review - vm_today
+    return f"{difference.days} days remaining"
+```
+
+**Note:** Date fields are passed into formulas as millisecond timestamps; use `date.fromtimestamp(int(params.fieldName) / 1000)` to convert. Formula results are strings — use `.isoformat()` for date values.
+
+:::
+:::
+
 
 ::::