feat: introduce persistent, active and repeated populate types

docs/input-types.md

@@ -0,0 +1,76 @@
+# TRICC Input/Populate Types
+
+This document explains the different kinds of input/populate nodes available in TRICC for drawio authors and content creators. These nodes allow fetching and managing data from previous encounters, patient records, or encounter context.
+
+## Overview
+
+TRICC supports three main populate/input types with distinct behaviors:
+
+### 1\. **Persistent** (`persistent`)
+
+- **Purpose**: Stable data with one current value (updates in place).
+- **Use Case**: Patient-level data like facility context demographics that persist across encounters.
+- **Attribute** `context`:
+    - **Default Context**: `patient` (`facility` for CHT HF strategy)
+    - **Other Contexts**: `practitioner`, `facility`, `location`
+- **Behavior**: Supports inheritance, last version, default value, relevance.
+- **Drawio Usage**: Set `odk_type="persistent"` or use the dedicated persistent shape. Add `context` attribute if needed.
+
+### 2\. **Active** (`active`)
+
+- **Purpose**: Current/active data that can be skipped if already known (`skip_or_new` update mode).
+- **Use Case**: Encounter-specific data like current symptoms or measurements that may carry over or be updated.
+- **Attribute** `from`:
+    - **Default** : `encounter`
+    - **Other**: ISO duration like `P14D` (14 days), `P1M` (1 month).
+- **Behavior**: Supports inheritance, last version, default, relevance.
+- **Drawio Usage**: Set `odk_type="active"` or dedicated shape. Use `from` attribute for lookup scope.
+
+### 3\. **Repeated** (`repeated`)
+
+- **Purpose**: Repeated/chartable data that **always creates a new entry** (`always_new`).
+- **Use Case**: Serial measurements, visit history, or chartable events (e.g., blood pressure readings over time).
+- **Attribute** `from`:
+    - **Default**: `encounter`
+    - **Other**: ISO duration like `P14D` (14 days), `P1M` (1 month).
+- **Behavior**: **No** inheritance, last-version, default value, or relevance based on last version. **Mandatory** `last.` prefix in calculations.
+- **Drawio Usage**: Set `odk_type="repeated"` or dedicated shape. Use `from` attribute.
+
+**Backward Compatibility**: `odk_type="input"` or old `history` maps to `persistent`.
+
+## Core Behavior Matrix
+
+| Type | Update Mode | Inheritance | Last Version | Default | Relevance | Calc Prefix |
+| --- | --- | --- | --- | --- | --- | --- |
+| persistent | update_existing | Yes | Yes | Yes | Yes | No |
+| active | skip_or_new | Yes | Yes | Yes | Yes | No |
+| repeated | always_new | **No** | **No** | **No** | **No** | `last.` (mandatory) |
+
+**Note**: Repeated nodes are completely excluded from version inheritance and last-version logic to ensure new entries.
+
+## Attributes
+
+- **context** (persistent): patient (default), practitioner, facility, location. Used for lookup/storage.
+- **from** (active/repeated): encounter (default) or ISO duration string (e.g., `P1Y` for 1 year). Note: XML uses `from`, mapped to `from_` in model.
+
+## How to Use in Drawio
+
+1.  Use the TRICC tools shapes or set the object type/semantic in properties.
+2.  For persistent/active/repeated, set the `odk_type` property or use the corresponding object in TYPE_MAP.
+3.  Add attributes like `context="location"` or `from="P14D"` in the shape properties.
+4.  For calculations referencing them, the expression builder automatically applies the correct prefix ( `last.`).
+5.  In CHT outputs:
+    - Persistent: appears in Contact Summary.
+    - Active/Repeated: in calculated contact summary and CHT tasks (see `imci-task.js` patterns for task generation).
+
+## Examples
+
+- **Patient Name**: semantic=persistent, context=patient, name=name.
+- **Active Encounter BP**: semantic=active, from=encounter, name=bp_reading.
+- **Repeated Measurements**: semantic=repeated, from=P7D, name=weight (creates new entry each time).
+
+See `docs/tricc-elements.md` for shape details and `tests/data/` for example drawio files with these nodes.
+
+For XLSForm/CHT/HF outputs, the types map to appropriate fields, calculations, and task configurations.
+
+**Author Tip**: Use the new types to reduce duplication in forms. Persistent for core patient data, active for current state, repeated for longitudinal tracking.

tricc_oo/converters/drawio_type_map.py

@@ -15,7 +15,9 @@
     TriccNodeExclusive,
     TriccNodeProposedDiagnosis,
     TriccNodeDiagnosis,
-    TriccNodeInput,
+    TriccNodePopulatePersistent,
+    TriccNodePopulateActive,
+    TriccNodePopulateRepeated,
 )
 
 from tricc_oo.models.tricc import (
@@ -294,11 +296,29 @@
         "mandatory_attributes": ["name", "label"],
         "model": TriccNodeProposedDiagnosis,
     },
-    TriccNodeType.input: {
+    TriccNodeType.input: { # depreated
         "objects": ["UserObject", "object"],
-        "attributes": ["save", "reference", "data_type", "concept_type"],
+        "attributes": ["save", "reference", "data_type", "concept_type", "context"],
         "mandatory_attributes": ["name", "label"],
-        "model": TriccNodeInput,
+        "model": TriccNodePopulatePersistent,
+    },
+    TriccNodeType.persistent: {
+        "objects": ["UserObject", "object"],
+        "attributes": ["save", "reference", "data_type", "concept_type", "context"],
+        "mandatory_attributes": ["name", "label"],
+        "model": TriccNodePopulatePersistent,
+    },
+    TriccNodeType.active: {
+        "objects": ["UserObject", "object"],
+        "attributes": ["save", "reference", "data_type", "concept_type", "from"],
+        "mandatory_attributes": ["name", "label"],
+        "model": TriccNodePopulateActive,
+    },
+    TriccNodeType.repeated: {
+        "objects": ["UserObject", "object"],
+        "attributes": ["save", "reference", "data_type", "concept_type", "from"],
+        "mandatory_attributes": ["name", "label"],
+        "model": TriccNodePopulateRepeated,
     },
     # TriccNodeType.number: {
     #     "objects": ["UserObject", "object"],

tricc_oo/converters/tricc_to_xls_form.py

@@ -1,7 +1,7 @@
 import logging
 from tricc_oo.converters.utils import clean_name
 from tricc_oo.models.tricc import TriccNodeSelectOption, TRICC_TRUE_VALUE, TRICC_FALSE_VALUE, TriccNodeActivity
-from tricc_oo.models.calculate import TriccNodeInput
+from tricc_oo.models.calculate import TriccNodePopulateBase
 from tricc_oo.models.base import TriccNodeBaseModel, TriccStatic, TriccReference
 
 # from babel import _
@@ -73,12 +73,19 @@ def get_export_name(node, replace_dots=True):
             )
         elif isinstance(node, TriccNodeSelectOption):
             node.export_name = node.name
+        elif getattr(node, "tricc_type", None) == "repeated":
+            # repeated: always use mandatory "last." prefix per calculation expression builder rules
+            # (placed before last=False check to prevent versioned naming for repeated nodes per spec)
+            node.export_name = clean_name(
+                "last." + node.name, replace_dots=replace_dots
+            )
         elif node.last is False:
             node.export_name = clean_name(
                 node.name + VERSION_SEPARATOR + str(node.version),
                 replace_dots=replace_dots,
             )
-        elif isinstance(node, TriccNodeInput):
+        elif issubclass(node.__class__, TriccNodePopulateBase):
+            # persistent & active: load. prefix is optional/droppable in expression contexts per spec
             node.export_name = clean_name("load." + node.name, replace_dots=replace_dots)
         else:
             node.export_name = clean_name(node.name, replace_dots=replace_dots)

tricc_oo/converters/xml_to_tricc.py

@@ -25,7 +25,7 @@
     TriccNodeProposedDiagnosis,
     TriccNodeDiagnosis,
     TriccRhombusMixIn,
-    TriccNodeInput,
+    TriccNodePopulateBase,
 )
 from tricc_oo.models.tricc import (
     TriccNodeCalculateBase,
@@ -126,7 +126,7 @@ def get_activity_details(diagram, activity, project, media_path):
     nodes = get_nodes(diagram, activity)
     for n in nodes.values():
         if (
-            issubclass(n.__class__, (TriccNodeDisplayModel, TriccNodeDisplayCalculateBase, TriccNodeInput))
+            issubclass(n.__class__, (TriccNodeDisplayModel, TriccNodeDisplayCalculateBase, TriccNodePopulateBase))
             and not isinstance(n, (TriccRhombusMixIn, TriccNodeRhombus, TriccNodeDisplayBridge))
             and not n.name.startswith("label_")  # FIXME
         ):
@@ -535,6 +535,8 @@ def set_additional_attributes(attribute_names, elm, node):
                 attribute = int(attribute)
             elif attributename == "relevance":
                 attribute = remove_html(attribute.strip())
+            elif attributename == "from":
+                attributename = "from_"
             else:
                 attribute
             setattr(node, attributename, attribute)
@@ -563,7 +565,7 @@ def get_concept_type(node):
             TriccNodeSelectOne,
             TriccNodeSelectYesNo,
             TriccNodeSelectNotAvailable,
-            TriccNodeInput,
+            TriccNodePopulateBase,
         ),
     ):
         return "Symptom-Finding"

tricc_oo/models/base.py

@@ -3,7 +3,7 @@
 import logging
 from typing import Annotated, Dict, ForwardRef, List, Optional, Union
 
-from pydantic import BaseModel, StringConstraints
+from pydantic import BaseModel, StringConstraints, ConfigDict
 from strenum import StrEnum
 
 from tricc_oo.converters.utils import generate_id, get_rand_name
@@ -61,6 +61,9 @@ class TriccNodeType(StrEnum):
     diagnosis = "diagnosis"
     proposed_diagnosis = "proposed_diagnosis"
     input = "input"
+    persistent = "persistent"
+    active = "active"
+    repeated = "repeated"
     remote_reference = "remote_reference"
 
     def __iter__(self):
@@ -156,6 +159,10 @@ def __init__(self, **data):
         if "id" not in data:
             data["id"] = generate_id(str(data))
         super().__init__(**data)
+    model_config = ConfigDict(
+        use_enum_values=True,
+        arbitrary_types_allowed=True,   # <-- this fixes TriccFrom (and similar)
+    )
 
 
 class TriccEdge(TriccBaseModel):
@@ -219,8 +226,6 @@ class TriccNodeBaseModel(TriccBaseModel):
     ref_def: Optional[Union[int, str]] = None  # for medal creator
     is_sequence_defined: bool = False
 
-    class Config:
-        use_enum_values = True  # <--
 
     def __hash__(self):
         return hash(self.id)

tricc_oo/models/calculate.py

@@ -1,5 +1,9 @@
 from typing import List, Optional, Union
 import logging
+import re
+from pydantic import field_validator
+from dateutil.relativedelta import relativedelta
+
 from tricc_oo.models.base import (
     TriccBaseModel, TriccOperation, TriccStatic, TriccReference, Expression, TriccNodeType
 )
@@ -15,6 +19,63 @@
 ACTIVITY_END_NODE_FORMAT = "aend_{}"
 
 
+class TriccFrom:
+    """Object model for the 'from' attribute on active/repeated populate nodes.
+    Supports 'E'/'encounter', 'T'/'today', and ISO 8601 durations like P14D, P1M, P1Y.
+    Used in __init__/validation of from_ field.
+    """
+    def __init__(self, value: str = "E"):
+        self.raw = str(value).strip() if value else "E"
+        self.scope = None
+        self.delta = None
+        self._parse()
+
+    def _parse(self):
+        val = self.raw.upper()
+        if val in ("E", "ENCOUNTER"):
+            self.scope = "encounter"
+            self.delta = None
+        elif val in ("T", "TODAY"):
+            self.scope = "today"
+            self.delta = None
+        else:
+            self.scope = "duration"
+            self.delta = self._parse_iso_duration(val)
+
+    def _parse_iso_duration(self, s: str):
+        # Matches P1Y2M3W4D or P1Y2M3DT4H5M etc.
+        pattern = r'^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$'
+        match = re.match(pattern, s)
+        if match:
+            y, m, w, d, h, min_, sec = match.groups()
+            return relativedelta(
+                years=int(y or 0),
+                months=int(m or 0),
+                weeks=int(w or 0),
+                days=int(d or 0),
+                hours=int(h or 0),
+                minutes=int(min_ or 0),
+                seconds=int(sec or 0)
+            )
+        logger.warning(f"Could not parse ISO duration: {s}, treating as raw string")
+        return None
+
+    def __str__(self):
+        return self.raw
+
+    def __repr__(self):
+        return f"TriccFrom({self.raw}, scope={self.scope})"
+
+    def is_encounter(self):
+        return self.scope == "encounter"
+
+    def is_today(self):
+        return self.scope == "today"
+
+    def is_duration(self):
+        return self.scope == "duration"
+
+
 class TriccNodeDisplayCalculateBase(TriccNodeCalculateBase):
     save: Optional[str] = None  # contribute to another calculate
     hint: Optional[str] = None  # for diagnostic display
@@ -61,11 +122,48 @@ class TriccNodeProposedDiagnosis(TriccNodeDisplayCalculateBase):
 
 
 class TriccNodeFakeCalculateBase(TriccNodeCalculateBase):
-    ...
+    """Base for fake/calculate-only nodes that don't require display attributes."""
+    ... # is_sequence_defined: bool = False
+
+
+class TriccNodePopulateBase(TriccNodeFakeCalculateBase):
+    """Base for all populate/input node types with common attributes."""
+    data_type: Optional[str] = None
+    concept_type: Optional[str] = None
+    is_sequence_defined: bool = False
+
+
+class TriccNodePopulatePersistent(TriccNodePopulateBase):
+    tricc_type: TriccNodeType = TriccNodeType.persistent
+    context: str = "patient"  # patient, practitioner, facility, location - default patient per spec
+
+
+class TriccNodePopulateActive(TriccNodePopulateBase):
+    tricc_type: TriccNodeType = TriccNodeType.active
+    from_: Optional[Union[str, TriccFrom]] = "E"  # 'from' in spec/JSON, from_ in python; supports E,T,ISO via TriccFrom
+
+    @field_validator('from_', mode='before')
+    @classmethod
+    def validate_from(cls, v):
+        if isinstance(v, TriccFrom):
+            return v
+        if v is None:
+            return TriccFrom("E")
+        return TriccFrom(str(v))
+
 
+class TriccNodePopulateRepeated(TriccNodePopulateBase):
+    tricc_type: TriccNodeType = TriccNodeType.repeated
+    from_: Optional[Union[str, TriccFrom]] = "E"  # 'from' in spec/JSON, from_ in python
 
-class TriccNodeInput(TriccNodeFakeCalculateBase):
-    tricc_type: TriccNodeType = TriccNodeType.input
+    @field_validator('from_', mode='before')
+    @classmethod
+    def validate_from(cls, v):
+        if isinstance(v, TriccFrom):
+            return v
+        if v is None:
+            return TriccFrom("E")
+        return TriccFrom(str(v))
 
 
 class TriccNodeDisplayBridge(TriccNodeDisplayCalculateBase):
@@ -231,4 +329,4 @@ class TriccNodeQuantity(TriccNodeDisplayCalculateBase):
     tricc_type: TriccNodeType = TriccNodeType.quantity
 
 
-TriccNodeCalculate.update_forward_refs()
+TriccNodeCalculate.model_rebuild()

tricc_oo/models/tricc.py

@@ -27,9 +27,7 @@ class TriccNodeCalculateBase(TriccNodeBaseModel):
     datatype: str = "boolean"
     priority: Union[float, int, None] = None
 
-    # to use the enum value of the TriccNodeType
-    class Config:
-        use_enum_values = True  # <--
+
 
     def make_instance(self, instance_nb, activity, **kwargs):
         # shallow copy

tricc_oo/strategies/output/xlsform_cdss.py

@@ -1,6 +1,6 @@
 import logging
 from tricc_oo.models.tricc import TriccNodeActivity
-from tricc_oo.models.calculate import TriccNodeInput
+from tricc_oo.models.calculate import TriccNodePopulateActive, TriccNodePopulatePersistent, TriccNodePopulateRepeated
 from tricc_oo.strategies.output.xls_form import XLSFormStrategy
 from tricc_oo.models.lang import SingletonLangClass
 
@@ -19,7 +19,11 @@ def export_inputs(self, activity, inputs=[], **kwargs):
         for node in activity.nodes.values():
             if isinstance(node, TriccNodeActivity):
                 inputs = self.export_inputs(node, inputs, **kwargs)
-            if isinstance(node, TriccNodeInput):
+            if isinstance(node, (TriccNodePopulatePersistent)):
+                inputs.append(node)
+            elif isinstance(node, (TriccNodePopulateActive)):
+                inputs.append(node)
+            elif isinstance(node, (TriccNodePopulateRepeated)):
                 inputs.append(node)
         return inputs