feat(041): add prompt field for data collection instructions

Data elements now carry a `prompt` field — the instruction or question
presented to the person/process filling the field. This captures
semantic meaning beyond the description:

- openMINDS: _instruction → prompt (e.g., "Enter the physical pixel
  size for this grid image (in x,y order)")
- ReproSchema: activity preamble + item question → prompt (combined
  context for what is being asked)
- Stored as LinkML annotation, extracted into semantic["prompt"]
- Included in embedding text computation for alignment — elements
  with similar prompts across sources will align better

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: satra

library/src/undata_library/adapters/linkml.py

@@ -222,6 +222,8 @@ def _extract_via_schemaview(
                     val = ann_val.value if hasattr(ann_val, "value") else str(ann_val)
                     if ann_key == "unit":
                         sem["unit"] = val
+                    elif ann_key == "prompt":
+                        sem["prompt"] = val
 
             # Aliases stored for downstream alignment
             if slot_def.aliases:

library/src/undata_library/adapters/linkml_builder.py

@@ -45,6 +45,7 @@ def add_slot(
     aliases: list[str] | None = None,
     minimum_value: float | None = None,
     maximum_value: float | None = None,
+    prompt: str | None = None,
 ) -> None:
     """Add a slot to the schema if not already present.
 
@@ -53,6 +54,11 @@ def add_slot(
                  to resolve alias-based lookups to the canonical slot.
         minimum_value: Minimum numeric value constraint.
         maximum_value: Maximum numeric value constraint.
+        prompt: Data collection prompt — the instruction or question presented
+                to the person/process filling this field. Carries semantic meaning
+                beyond the description (e.g., "Enter the physical pixel size for
+                this grid image (in x,y order)"). Stored as a LinkML annotation
+                and included in embedding computation for alignment.
     """
     from linkml_runtime.linkml_model import SlotDefinition
 
@@ -83,6 +89,8 @@ def add_slot(
         slot.minimum_value = minimum_value
     if maximum_value is not None:
         slot.maximum_value = maximum_value
+    if prompt:
+        slot.annotations["prompt"] = prompt
     schema.slots[name] = slot
 
 

library/src/undata_library/adapters/openminds.py

@@ -169,17 +169,15 @@ def _add_schema_to_linkml(self, ld: Any, data: dict, lb: Any) -> None:
                 prop_def.get("_linkedTypes") and len(prop_def.get("_linkedTypes", [])) > 1
             )
 
-            desc = (
-                prop_def.get("description")
-                or prop_def.get("_instruction")
-                or ""
-            )[:500] or None
+            desc = (prop_def.get("description") or "")[:500] or None
+            instruction = (prop_def.get("_instruction") or "")[:500] or None
             lb.add_slot(
                 ld,
                 name,
                 range=rng,
-                description=desc,
+                description=desc or instruction,
                 multivalued=multivalued,
+                prompt=instruction,
             )
             slot_names.append(name)
             if prop_key in required_fields:

library/src/undata_library/adapters/reproschema.py

@@ -201,12 +201,22 @@ def to_linkml(self, source_path: Path, **options: Any) -> Any:
                     description = _extract_label(
                         item_data.get(
                             "description",
-                            item_data.get(
-                                "schema:description",
-                                item_data.get("question", item_data.get("schema:question", "")),
-                            ),
+                            item_data.get("schema:description", ""),
                         )
                     )
+                    question = _extract_label(
+                        item_data.get(
+                            "question",
+                            item_data.get("schema:question", ""),
+                        )
+                    )
+                    # Build prompt: activity preamble + item question
+                    prompt_parts = []
+                    if activity_desc:
+                        prompt_parts.append(activity_desc)
+                    if question:
+                        prompt_parts.append(question)
+                    item_prompt = " — ".join(prompt_parts) if prompt_parts else None
 
                     response_options, resolved_ro = _parse_response_options(item_data, items_dir)
                     data_type = _infer_type_from_response(resolved_ro)
@@ -243,9 +253,12 @@ def to_linkml(self, source_path: Path, **options: Any) -> Any:
                         schema,
                         item_name,
                         range=linkml_range,
-                        description=description[:500] if description else None,
+                        description=(description or question)[:500]
+                        if (description or question)
+                        else None,
                         minimum_value=min_val,
                         maximum_value=max_val,
+                        prompt=item_prompt[:500] if item_prompt else None,
                     )
                     slot_names.append(item_name)
 

library/src/undata_library/embeddings.py

@@ -211,7 +211,11 @@ def _build_element_text(element_data: dict) -> str:
         # ValueSets
         parts.append(semantic["name"])
 
-    # 2. Type information
+    # 2. Data collection prompt (instruction/question — carries semantic meaning)
+    if semantic.get("prompt"):
+        parts.append(f"prompt: {semantic['prompt']}")
+
+    # 3. Type information
     type_parts = []
     if semantic.get("data_type"):
         type_parts.append(f"type={semantic['data_type']}")