feat: Enhance IOType mapping and documentation for arctrl integration

Author: Zalfsten

.agents/skills/arctrl/SKILL.md

@@ -18,6 +18,33 @@ but some internals are Fable runtime types.
 
 ## Package & Imports
 
+arctrl ships no type stubs and no `py.typed` marker. Mypy will report
+`[import-untyped]` for every `arctrl.*` import unless you suppress it.
+
+**Preferred: project-level override in `pyproject.toml`** (no per-import
+comments needed, covers all submodules):
+
+```toml
+[[tool.mypy.overrides]]
+module = ["arctrl", "arctrl.*"]
+ignore_missing_imports = true
+```
+
+The `arctrl.*` glob is required because the Fable-transpiled internals are
+exposed under `arctrl.py.*` subpackages (e.g.
+`arctrl.py.Core.Table.composite_cell`), which are a different dotted path
+from the bare `arctrl` package.
+
+**Alternative: per-import suppression** (only needed when the project-level
+override is not in place):
+
+```python
+from arctrl.py.fable_modules.fable_library.async_ import start_as_task  # type: ignore[import-untyped]
+from arctrl.py.Core.Table.composite_cell import Data  # type: ignore[import-untyped]
+```
+
+---
+
 ```python
 from arctrl import (
     ARC,
@@ -33,7 +60,7 @@ from arctrl import (
     Publication,
 )
 
-# Async write helper (Fable internal — untyped, needs type: ignore)
+# Async write helper lives in the Fable internals:
 from arctrl.py.fable_modules.fable_library.async_ import start_as_task  # type: ignore[import-untyped]
 ```
 
@@ -194,9 +221,13 @@ header_date = CompositeHeader.date  # property, not callable
 # Fallback for unknown/simple header names:
 header_any = CompositeHeader.OfHeaderString("SomeColumnName")
 
-# IOType known strings (IOType.of_string):
-# "source_name", "sample_name", "raw_data_file", "derived_data_file",
-# "image_file", "material"
+# IOType canonical strings recognised by IOType.of_string() (maps to named tags 0-3):
+# "Source Name" / "Source"  → tag 0 (Source)
+# "Sample Name" / "Sample"  → tag 1 (Sample)
+# "Data" / "RawDataFile" / "Raw Data File" / "DerivedDataFile" /
+# "Derived Data File" / "ImageFile" / "Image File"  → tag 2 (Data)
+# "Material"                → tag 3 (Material)
+# Any other string          → tag 4 (FreeType — avoid for ISA compliance)
 
 # Build cells
 cell_text = CompositeCell.free_text("some value")

middleware/sql_to_arc/src/middleware/sql_to_arc/builder.py

@@ -16,6 +16,7 @@
     IOType,
     OntologyAnnotation,
 )
+from arctrl.py.Core.Table.composite_cell import Data
 
 from middleware.sql_to_arc.context import ArcBuildData
 from middleware.sql_to_arc.mapper import (
@@ -156,6 +157,16 @@ def _add_publications_to_arc(
             study.Publications.append(map_publication(p_row))
 
 
+# Maps DB schema column_io_type values (snake_case DB contract) to the canonical
+# strings recognised by IOType.of_string() (ARCitect display names).
+_IO_TYPE_MAP: dict[str, str] = {
+    "source_name": "Source Name",
+    "sample_name": "Sample Name",
+    "data": "Data",
+    "material_name": "Material",
+}
+
+
 def _get_column_key(r: AnnotationTableRow) -> tuple[Any, ...]:
     """Extract a unique key for a column definition."""
     return (
@@ -176,7 +187,7 @@ def _build_header(key: tuple[Any, ...]) -> CompositeHeader | None:
         oa = OntologyAnnotation(c_ann_term or "", c_ann_uri or "", c_ann_ver or "")
 
         if c_type in {"input", "output"} and not c_io:
-            default_io = "source_name" if c_type == "input" else "sample_name"
+            default_io = "Source Name" if c_type == "input" else "Sample Name"
             logger.warning(
                 "column_io_type missing for column_type '%s'; defaulting to '%s'",
                 c_type,
@@ -185,8 +196,12 @@ def _build_header(key: tuple[Any, ...]) -> CompositeHeader | None:
 
         # Dispatch table for different header types
         handlers = {
-            "input": lambda: CompositeHeader.input(IOType.of_string(c_io or "source_name")),
-            "output": lambda: CompositeHeader.output(IOType.of_string(c_io or "sample_name")),
+            "input": lambda: CompositeHeader.input(
+                IOType.of_string(_IO_TYPE_MAP.get(c_io or "", c_io or "Source Name"))
+            ),
+            "output": lambda: CompositeHeader.output(
+                IOType.of_string(_IO_TYPE_MAP.get(c_io or "", c_io or "Sample Name"))
+            ),
             "characteristic": lambda: CompositeHeader.characteristic(oa),
             "factor": lambda: CompositeHeader.factor(oa),
             "parameter": lambda: CompositeHeader.parameter(oa),
@@ -222,6 +237,10 @@ def _build_single_cell(cell_row: AnnotationTableRow, header: CompositeHeader) ->
     if cat is not None:
         return CompositeCell.term(OntologyAnnotation(cat, cau, cav))
 
+    # Data cell (file path) — required when header is a Data-type IO column
+    if header.IsDataColumn:
+        return CompositeCell.data(Data(name=str(cv)) if cv is not None else Data())
+
     # Text value? (either from new schema 'cell_value' or fallback 'value')
     val_to_use = cv
     if val_to_use is not None:

middleware/sql_to_arc/tests/unit/test_builder.py

@@ -4,10 +4,12 @@
 from typing import Any
 
 import pytest
+from arctrl import CompositeHeader, IOType
 
-from middleware.sql_to_arc.builder import build_single_arc_task
+from middleware.sql_to_arc.builder import _IO_TYPE_MAP, _build_header, _build_single_cell, build_single_arc_task
 from middleware.sql_to_arc.context import ArcBuildData
 from middleware.sql_to_arc.models import (
+    AnnotationTableRow,
     AssayRow,
     ContactRow,
     InvestigationRow,
@@ -197,3 +199,155 @@ def test_build_ignores_irrelevant_data(sample_investigation: dict[str, Any]) ->
     # Check that styX is NOT in the graph
     sty_x = next((item for item in graph if item.get("@id") == "styX" or item.get("identifier") == "styX"), None)
     assert sty_x is None
+
+
+# ---------------------------------------------------------------------------
+# Helpers to build minimal AnnotationTableRow dicts
+# ---------------------------------------------------------------------------
+
+
+def _ann_row(**overrides: Any) -> dict[str, Any]:
+    """Return a minimal AnnotationTableRow dict, optionally overriding any field."""
+    base: dict[str, Any] = {
+        "investigation_ref": "inv1",
+        "target_type": "study",
+        "target_ref": "sty1",
+        "table_name": "T",
+        "column_type": "input",
+        "row_index": 0,
+        "column_io_type": None,
+        "cell_value": None,
+        "cell_annotation_term": None,
+        "cell_annotation_uri": None,
+        "cell_annotation_version": None,
+        "column_annotation_term": None,
+        "column_annotation_uri": None,
+        "column_annotation_version": None,
+        "column_value": None,
+    }
+    base.update(overrides)
+    return base
+
+
+def _row(data: dict[str, Any]) -> AnnotationTableRow:
+    """Validate a dict into an AnnotationTableRow."""
+    return AnnotationTableRow.model_validate(data)
+
+
+# ---------------------------------------------------------------------------
+# IOType mapping tests
+# ---------------------------------------------------------------------------
+
+
+class TestIOTypeMapping:
+    """_IO_TYPE_MAP translates snake_case DB values to canonical ARCitect strings."""
+
+    @staticmethod
+    @pytest.mark.parametrize(
+        ("db_value", "canonical"),
+        [
+            ("source_name", "Source Name"),
+            ("sample_name", "Sample Name"),
+            ("data", "Data"),
+            ("material_name", "Material"),
+        ],
+    )
+    def test_map_covers_all_db_values(db_value: str, canonical: str) -> None:
+        """Each DB snake_case value maps to the expected canonical ARCitect string."""
+        assert _IO_TYPE_MAP[db_value] == canonical
+
+    @staticmethod
+    @pytest.mark.parametrize(
+        ("db_value", "expected_tag"),
+        [
+            ("source_name", 0),  # IOType.Source
+            ("sample_name", 1),  # IOType.Sample
+            ("data", 2),  # IOType.Data
+            ("material_name", 3),  # IOType.Material
+        ],
+    )
+    def test_build_header_input_uses_named_iotype(db_value: str, expected_tag: int) -> None:
+        """DB values must produce a named IOType (tag 0–3), never FreeType (tag 4)."""
+        key = ("input", db_value, None, None, None, None, None)
+        header = _build_header(key)
+        assert header is not None
+        assert header.is_input
+        assert header.fields[0].tag == expected_tag
+
+    @staticmethod
+    @pytest.mark.parametrize(
+        ("db_value", "expected_tag"),
+        [
+            ("sample_name", 1),
+            ("data", 2),
+            ("material_name", 3),
+        ],
+    )
+    def test_build_header_output_uses_named_iotype(db_value: str, expected_tag: int) -> None:
+        """DB output values must also produce a named IOType, never FreeType."""
+        key = ("output", db_value, None, None, None, None, None)
+        header = _build_header(key)
+        assert header is not None
+        assert header.is_output
+        assert header.fields[0].tag == expected_tag
+
+    @staticmethod
+    def test_missing_io_type_defaults_to_source_name_for_input() -> None:
+        """Missing column_io_type falls back to 'Source Name' (tag 0) for input."""
+        key = ("input", None, None, None, None, None, None)
+        header = _build_header(key)
+        assert header is not None
+        assert header.is_input
+        assert header.fields[0].tag == 0
+
+    @staticmethod
+    def test_missing_io_type_defaults_to_sample_name_for_output() -> None:
+        """Missing column_io_type falls back to 'Sample Name' (tag 1) for output."""
+        key = ("output", None, None, None, None, None, None)
+        header = _build_header(key)
+        assert header is not None
+        assert header.is_output
+        assert header.fields[0].tag == 1
+
+
+# ---------------------------------------------------------------------------
+# Data cell tests
+# ---------------------------------------------------------------------------
+
+
+class TestDataCellBuilding:
+    """_build_single_cell must emit CompositeCell.data() for data-typed IO columns."""
+
+    @staticmethod
+    def test_data_cell_has_correct_file_path() -> None:
+        """A data-typed output column must produce a DataCell with the file path set."""
+        header = CompositeHeader.output(IOType.of_string("Data"))
+        row = _row(_ann_row(column_type="output", column_io_type="data", cell_value="raw.fastq.gz"))
+        cell = _build_single_cell(row, header)
+        assert cell.is_data
+        assert cell.AsData.FilePath == "raw.fastq.gz"
+
+    @staticmethod
+    def test_data_cell_empty_when_no_cell_value() -> None:
+        """A data-typed column with no cell_value must produce an empty DataCell, not a crash."""
+        header = CompositeHeader.output(IOType.of_string("Data"))
+        row = _row(_ann_row(column_type="output", column_io_type="data", cell_value=None))
+        cell = _build_single_cell(row, header)
+        assert cell.is_data
+        assert cell.AsData.FilePath is None
+
+    @staticmethod
+    def test_source_name_column_emits_free_text() -> None:
+        """A source_name input column must produce a free-text cell, not a DataCell."""
+        header = CompositeHeader.input(IOType.of_string("Source Name"))
+        row = _row(_ann_row(column_type="input", column_io_type="source_name", cell_value="SourceA"))
+        cell = _build_single_cell(row, header)
+        assert cell.is_free_text
+
+    @staticmethod
+    def test_sample_name_column_emits_free_text() -> None:
+        """A sample_name output column must produce a free-text cell, not a DataCell."""
+        header = CompositeHeader.output(IOType.of_string("Sample Name"))
+        row = _row(_ann_row(column_type="output", column_io_type="sample_name", cell_value="SampleB"))
+        cell = _build_single_cell(row, header)
+        assert cell.is_free_text

pyproject.toml

@@ -131,16 +131,10 @@ exclude = [
   ".ruff_cache",
 ]
 
-# [[tool.mypy.overrides]]
-# module = [
-#     "middleware.api_client.*",
-#     "middleware.shared.*",
-# ]
-# ignore_missing_imports = true
-
-# arctrl has no type stubs and no py.typed marker — suppress the resulting noise
+# arctrl has no type stubs and no py.typed marker — suppress the resulting noise.
+# The Fable-transpiled internals live under arctrl.py.* so both patterns are needed.
 [[tool.mypy.overrides]]
-module = ["arctrl"]
+module = ["arctrl", "arctrl.*"]
 ignore_missing_imports = true
 
 # Docstring-Regeln aktivieren, damit es wie pylint C0114/15/16 meckert