sdcreader 4.2.0__tar.gz → 4.3.0__tar.gz

{sdcreader-4.2.0 → sdcreader-4.3.0}/NOTICE

@@ -7,3 +7,8 @@ The test fixture under samples/nhanes-participant/ is the published package of t
 FAIR Data Demo (https://github.com/SemanticDataCharter/FAIR_Data_Demo), fetched from SDCStudio's public catalog, a
 Semantic Data Charter model of National Health and Nutrition Examination Survey (CDC) variables; it is used as
 evidence, unchanged.
+
+The test fixture under samples/halvorsen-credit-note/ is the published package of the Credit Note model of the
+business documents library and one Credit Note record generated by HalvorsenDemo
+(https://github.com/SemanticDataCharter/HalvorsenDemo, Apache 2.0), whose companies and documents are fictitious; it
+is used as evidence, unchanged.

{sdcreader-4.2.0/src/sdcreader.egg-info → sdcreader-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdcreader
-Version: 4.2.0
+Version: 4.3.0
 Summary: Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP); MCP server included.
 Author: Axius SDC, Inc.
 License: Apache-2.0
@@ -89,6 +89,25 @@ which is complete.
 - Constants: the leaf, numeric and quantified types; the predicate IRIs `IDENTIFIER`, `SOURCE`, `PUBLISHER`, `EXACT`,
   `CLOSE`, `SEE_ALSO`, `HAS_UNIT`; `DC_DEFAULTS`.
 
+## Reading a record (4.3.0)
+
+`read_record(source, model)` reads a Governed Data Record, the XML instance, and joins each value to the component
+that defines it. `source` is the record's bytes, its text or a path; a record of another model is refused
+(`RecordError`), as is anything that is not an `sdc4:dm-<ct_id>` record.
+
+- **`Record`**: `attributes` (`instance_id`, `instance_version`, `creation_timestamp`, `current-state`, ...),
+  `values` in document order, and `exceptional`, the values that carry an Exceptional Value.
+- **`RecordValue`**: the `component`, its `path` of clusters (root first), an `occurrence` index for a component
+  repeated under the same path, its `position`, its `elements` as the record holds them (a quantity's units nested:
+  `{"xdquantity-value": "1", "xdquantity-units": {"label": "Trade Units", "xdstring-value": "EA"}}`), and its
+  `context` (`act`, `vtb`, `vte`, `tr`, `modified`, `latitude`, `longitude`).
+- **`ExceptionalValue`**: the ISO 21090 null flavor (`code`, `name`) and its `origin`: `source` when it stands in
+  place of the value, `recovery` when sdcvalidator's recovery inserted it beside a value that failed its constraint.
+  For `recovery`, `RecordValue.rejected` is that value, kept so a person can see it.
+
+Cluster members sit inside adapter elements that are not components of the model; the reader passes through them.
+It does not type, validate or interpret values: that is the caller's work (a mapper, an exporter, a checker).
+
 ## MCP server
 
 `sdcreader` is also an MCP server, registered as `io.github.SemanticDataCharter/sdcreader`, so an assistant can read a
@@ -107,8 +126,9 @@ uvx sdcreader --host https://your-sdcstudio.example   # a sovereign SDCStudio's
 | `list_leaves` | the leaves in document order with path, type, constraints, code count and identity links, paged |
 | `list_codes` | one component's enumerated values with IRI, definition and code system |
 | `check_package` | the reader's integrity check on a package directory |
+| `read_record` | a Governed Data Record on disk read against its model: attributes, then each value with its component, path, elements, context and Exceptional Value, paged; the model is the one the record names unless a source is given |
 
-Each tool takes a `ct_id` (fetched from the host the server was started with) or a package `directory` on disk.
+Each model tool takes a `ct_id` (fetched from the host the server was started with) or a package `directory` on disk.
 No tool takes a URL: the host is fixed at start, so a caller cannot point the server elsewhere. Every tool calls the
 same functions as the library; the two interfaces describe one model the same way.
 

{sdcreader-4.2.0 → sdcreader-4.3.0}/README.md

@@ -64,6 +64,25 @@ which is complete.
 - Constants: the leaf, numeric and quantified types; the predicate IRIs `IDENTIFIER`, `SOURCE`, `PUBLISHER`, `EXACT`,
   `CLOSE`, `SEE_ALSO`, `HAS_UNIT`; `DC_DEFAULTS`.
 
+## Reading a record (4.3.0)
+
+`read_record(source, model)` reads a Governed Data Record, the XML instance, and joins each value to the component
+that defines it. `source` is the record's bytes, its text or a path; a record of another model is refused
+(`RecordError`), as is anything that is not an `sdc4:dm-<ct_id>` record.
+
+- **`Record`**: `attributes` (`instance_id`, `instance_version`, `creation_timestamp`, `current-state`, ...),
+  `values` in document order, and `exceptional`, the values that carry an Exceptional Value.
+- **`RecordValue`**: the `component`, its `path` of clusters (root first), an `occurrence` index for a component
+  repeated under the same path, its `position`, its `elements` as the record holds them (a quantity's units nested:
+  `{"xdquantity-value": "1", "xdquantity-units": {"label": "Trade Units", "xdstring-value": "EA"}}`), and its
+  `context` (`act`, `vtb`, `vte`, `tr`, `modified`, `latitude`, `longitude`).
+- **`ExceptionalValue`**: the ISO 21090 null flavor (`code`, `name`) and its `origin`: `source` when it stands in
+  place of the value, `recovery` when sdcvalidator's recovery inserted it beside a value that failed its constraint.
+  For `recovery`, `RecordValue.rejected` is that value, kept so a person can see it.
+
+Cluster members sit inside adapter elements that are not components of the model; the reader passes through them.
+It does not type, validate or interpret values: that is the caller's work (a mapper, an exporter, a checker).
+
 ## MCP server
 
 `sdcreader` is also an MCP server, registered as `io.github.SemanticDataCharter/sdcreader`, so an assistant can read a
@@ -82,8 +101,9 @@ uvx sdcreader --host https://your-sdcstudio.example   # a sovereign SDCStudio's
 | `list_leaves` | the leaves in document order with path, type, constraints, code count and identity links, paged |
 | `list_codes` | one component's enumerated values with IRI, definition and code system |
 | `check_package` | the reader's integrity check on a package directory |
+| `read_record` | a Governed Data Record on disk read against its model: attributes, then each value with its component, path, elements, context and Exceptional Value, paged; the model is the one the record names unless a source is given |
 
-Each tool takes a `ct_id` (fetched from the host the server was started with) or a package `directory` on disk.
+Each model tool takes a `ct_id` (fetched from the host the server was started with) or a package `directory` on disk.
 No tool takes a URL: the host is fixed at start, so a caller cannot point the server elsewhere. Every tool calls the
 same functions as the library; the two interfaces describe one model the same way.
 

{sdcreader-4.2.0 → sdcreader-4.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sdcreader"
-version = "4.2.0"
+version = "4.3.0"
 description = "Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP); MCP server included."
 readme = "README.md"
 requires-python = ">=3.10"

{sdcreader-4.2.0 → sdcreader-4.3.0}/src/sdcreader/__init__.py

@@ -7,12 +7,17 @@ versions. This package loads or fetches that evidence and reads it into one shap
 record tree, its leaves in document order, the enumerated values with the codes the schema annotates them with,
 and the model's own Dublin Core with SDCStudio's field defaults read as unset. It knows nothing about any
 projection.
+
+Since 4.3.0 it also reads a Governed Data Record itself (`read_record`): the record's attributes and each value joined
+to the component that defines it, Exceptional Values included, for record-level mappers.
 """
 from .model import (CLOSE, DC_DEFAULTS, EXACT, HAS_UNIT, IDENTIFIER, LEAF_TYPES, NUMERIC_TYPES, PUBLISHER, QUANTIFIED_TYPES, SEE_ALSO,
                     SOURCE, Code, Component, Leaf, Model, enumeration_iri, read_header, read_model)
 from .package import DEFAULT_HOST, ModelPackage, PackageError, fetch_package, load_package
+from .record import CONTEXT_ELEMENTS, EXCEPTIONAL_VALUES, RECORD_ATTRIBUTES, ExceptionalValue, Record, RecordError, RecordValue, read_record
 
-__version__ = "4.2.0"
+__version__ = "4.3.0"
 __all__ = ["ModelPackage", "PackageError", "DEFAULT_HOST", "load_package", "fetch_package", "read_model", "read_header", "enumeration_iri",
            "Model", "Component", "Leaf", "Code", "LEAF_TYPES", "NUMERIC_TYPES", "QUANTIFIED_TYPES", "DC_DEFAULTS", "IDENTIFIER", "SOURCE",
-           "PUBLISHER", "EXACT", "CLOSE", "SEE_ALSO", "HAS_UNIT", "__version__"]
+           "PUBLISHER", "EXACT", "CLOSE", "SEE_ALSO", "HAS_UNIT", "read_record", "Record", "RecordValue", "RecordError", "ExceptionalValue",
+           "EXCEPTIONAL_VALUES", "RECORD_ATTRIBUTES", "CONTEXT_ELEMENTS", "__version__"]

{sdcreader-4.2.0 → sdcreader-4.3.0}/src/sdcreader/mcp_server.py

@@ -12,11 +12,13 @@ published model in the public catalog, read its record structure, its
 enumerated values with their codes and definitions, its Dublin Core as the
 modeler wrote it, and the pinned schema URL, with no account anywhere.
 
-**Five tools, read-only.** `find_models` searches the public catalog.
+**Six tools, read-only.** `find_models` searches the public catalog.
 `describe_model` summarizes one model. `list_leaves` walks its leaves in
 document order, paged, because a model can have more than a thousand.
 `list_codes` gives one component's enumerated values. `check_package` runs the
-reader's integrity check on a package directory.
+reader's integrity check on a package directory. `read_record` (4.3.0) reads a
+Governed Data Record on disk against its model: the record's attributes and
+each value with its component, paged, Exceptional Values included.
 
 **No tool takes a URL.** The catalog host is fixed when the server starts
 (`--host`, default SDCStudio's public catalog), so a caller cannot point this
@@ -123,6 +125,27 @@ TOOLS = [
             "additionalProperties": False,
         },
     },
+    {
+        "name": "read_record",
+        "description": (
+            "Read a Governed Data Record (an XML file on disk) against its model: the record's attributes and each "
+            "value in document order with its component, path of clusters, elements, context and any Exceptional "
+            "Value (ISO 21090 code, name, and whether it was written at the source or inserted by recovery beside a "
+            "rejected value). The model is the one the record names, fetched by its identifier unless ct_id or "
+            "directory is given. Paged. Does not validate the record."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "record": {"type": "string", "description": "Path to the record's XML file on disk."},
+                **source_properties(),
+                "offset": {"type": "integer", "minimum": 0, "default": 0},
+                "limit": {"type": "integer", "minimum": 1, "maximum": MAX_PAGE, "default": DEFAULT_PAGE},
+            },
+            "required": ["record"],
+            "additionalProperties": False,
+        },
+    },
     {
         "name": "check_package",
         "description": (
@@ -258,6 +281,49 @@ def _handle_list_codes(args: dict[str, Any]) -> Any:
     }
 
 
+def _handle_read_record(args: dict[str, Any]) -> Any:
+    import re
+    from pathlib import Path
+
+    from sdcreader.record import RecordError, read_record
+
+    path = args.get("record")
+    if not isinstance(path, str) or not path:
+        raise ToolError("`record` must be a path to the record's XML file.")
+    try:
+        data = Path(path).read_bytes()
+    except OSError as exc:
+        raise ToolError(f"Could not read the record: {exc}") from exc
+    source = {k: args[k] for k in ("ct_id", "directory") if args.get(k)}
+    if not source:
+        m = re.search(rb"<[A-Za-z0-9_]+:dm-([a-z0-9]{24})[\s>]", data[:4000])
+        if not m:
+            raise ToolError("The record does not name a model (no sdc4:dm-<ct_id> root); give ct_id or directory.")
+        source = {"ct_id": m.group(1).decode()}
+    pkg, model = _cache().one(source)
+    try:
+        record = read_record(data, model)
+    except RecordError as exc:
+        raise ToolError(str(exc)) from exc
+    offset = int_arg(args, "offset", 0, 0, 10_000_000)
+    limit = int_arg(args, "limit", DEFAULT_PAGE, 1, MAX_PAGE)
+    page = record.values[offset : offset + limit]
+    values = [
+        {
+            "position": v.position, "ct_id": v.component.ct_id, "label": v.component.label, "sdc_type": v.component.sdc_type,
+            "path": [p.label for p in v.path], "occurrence": v.occurrence, "elements": v.elements, "context": v.context,
+            "exceptional": ({"code": v.exceptional.code, "name": v.exceptional.name, "origin": v.exceptional.origin}
+                            if v.exceptional else None),
+        }
+        for v in page
+    ]
+    return {
+        "ct_id": model.ct_id, "title": model.title, "schema_sha256": pkg.sha256, "attributes": record.attributes,
+        "total": len(record.values), "exceptional": len(record.exceptional), "offset": offset, "limit": limit,
+        "returned": len(values), "next_offset": offset + limit if offset + limit < len(record.values) else None, "values": values,
+    }
+
+
 def _handle_check_package(args: dict[str, Any]) -> Any:
     from sdcreader.package import PackageError, load_package
 
@@ -283,6 +349,7 @@ TOOL_HANDLERS = {
     "list_leaves": _handle_list_leaves,
     "list_codes": _handle_list_codes,
     "check_package": _handle_check_package,
+    "read_record": _handle_read_record,
 }
 
 
@@ -293,7 +360,8 @@ def _server() -> Server:
             "Read published Semantic Data Charter models. `find_models` searches "
             f"the public catalog at {_HOST}; `describe_model`, `list_leaves` and "
             "`list_codes` read one model by its ct_id from that host or from a "
-            "package directory on disk; `check_package` verifies a directory. "
+            "package directory on disk; `check_package` verifies a directory; "
+            "`read_record` reads a Governed Data Record on disk against its model. "
             "All tools are read-only and need no account. No tool takes a URL."
         ),
     )

sdcreader-4.3.0/src/sdcreader/record.py

@@ -0,0 +1,180 @@
+"""Read a Governed Data Record (the XML instance) and join each value to the model component that defines it.
+
+A record's root is `sdc4:dm-<ct_id>`, carrying the record's own attributes (`instance_id`, `instance_version`,
+`creation_timestamp`, `current-state`, ...). Below it, every component appears as an `sdc4:ms-<ct_id>` element. A
+cluster's members sit inside adapter elements, also named `sdc4:ms-<ct_id>` but not components of the model; the
+reader passes through them. A data-bearing component holds its label, its per-value context (`act`, `vtb`, `vte`, `tr`,
+`modified`, `latitude`, `longitude`), its value elements (`xdstring-value`, `xdquantity-value` with
+`xdquantity-units`, `xdtemporal-datetime`, ...) and, where the value is missing or unusable, an Exceptional Value: an
+`sdc4:<code>` element with the ISO 21090 null flavor code (`sdc4:ASKR`, `sdc4:INV`, ...) and its `ev-name`.
+
+An Exceptional Value written where the record was made stands in place of the value. One inserted by recovery
+(sdcvalidator's `validate_with_recovery`, which tags the record `valid_with_ev`) stands beside the value that failed
+its constraint, which stays in the record; the reader keeps that value, marked as rejected.
+
+The reader keeps every value element's text as the record holds it. It does not type values, validate them or know
+any target; that is the reader's caller's work.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from lxml import etree
+
+from .model import LEAF_TYPES, SDC4, Component, Model
+
+#: ISO 21090 null flavors, as the SDC4 reference model names its Exceptional Value elements.
+EXCEPTIONAL_VALUES = {
+    "INV": "Invalid", "OTH": "Other", "UNC": "Unencoded", "NI": "No Information", "NA": "Not Applicable",
+    "UNK": "Unknown", "ASKU": "Asked but Unknown", "ASKR": "Asked and Refused", "NASK": "Not Asked",
+    "NAV": "Not Available", "MSK": "Masked", "DER": "Derived", "PINF": "Positive Infinity",
+    "NINF": "Negative Infinity", "TRC": "Trace", "QS": "Sufficient Quantity",
+}
+
+#: The record attributes a Governed Data Record carries under its root, by element name.
+RECORD_ATTRIBUTES = ("dm-label", "dm-language", "dm-encoding", "creation_timestamp", "instance_id", "instance_version",
+                     "source_instance_id", "source_version_id", "current-state")
+
+#: Per-value context elements: what the record says about a value rather than the value itself.
+CONTEXT_ELEMENTS = ("act", "vtb", "vte", "tr", "modified", "latitude", "longitude")
+
+
+class RecordError(Exception):
+    pass
+
+
+@dataclass
+class ExceptionalValue:
+    code: str              # "ASKR"
+    name: str              # "Asked and Refused"
+    origin: str            # "source": in place of the value; "recovery": beside a value that failed its constraint
+
+
+@dataclass
+class RecordValue:
+    component: Component
+    path: list[Component]          # the clusters above it, root first
+    occurrence: int                # 0 for the first time this component appears under this path, 1 for the next, ...
+    position: int                  # document order among the record's values, 0-based
+    elements: dict                 # the value elements as the record holds them: name -> text, or name -> dict for a
+                                   # nested element (a quantity's units: {"label": "Trade Units", "xdstring-value": "EA"})
+    context: dict[str, str]        # act, vtb, vte, tr, modified, latitude, longitude, where present
+    exceptional: ExceptionalValue | None = None
+
+    @property
+    def rejected(self) -> dict:
+        """The value elements a recovery Exceptional Value stands beside: the value that failed its constraint."""
+        return self.elements if self.exceptional and self.exceptional.origin == "recovery" else {}
+
+
+@dataclass
+class Record:
+    model: Model
+    attributes: dict[str, str]
+    values: list[RecordValue] = field(default_factory=list)
+
+    @property
+    def instance_id(self) -> str:
+        return self.attributes.get("instance_id", "")
+
+    @property
+    def exceptional(self) -> list[RecordValue]:
+        return [v for v in self.values if v.exceptional]
+
+
+def _local(tag) -> str:
+    return tag.split("}", 1)[1] if isinstance(tag, str) and "}" in tag else (tag if isinstance(tag, str) else "")
+
+
+def _is_sdc4(el) -> bool:
+    return isinstance(el.tag, str) and el.tag.startswith(f"{{{SDC4}}}")
+
+
+def _text(el) -> str:
+    return (el.text or "").strip()
+
+
+def _nested(el) -> dict | str:
+    """An element's content: its text if it has no element children, else a dict of its children's content."""
+    kids = [c for c in el if isinstance(c.tag, str)]
+    if not kids:
+        return _text(el)
+    return {_local(c.tag): _nested(c) for c in kids}
+
+
+def read_record(source: bytes | str | Path, model: Model) -> Record:
+    """Read a Governed Data Record (XML) and join it to the model it names.
+
+    `source` is the record's bytes, its text, or a path to it. The record's root must be `sdc4:dm-<ct_id>` for the
+    model's ct_id; a record of another model is refused rather than read against the wrong definitions.
+    """
+    if isinstance(source, Path) or (isinstance(source, str) and not source.lstrip().startswith("<")):
+        data = Path(source).read_bytes()
+    else:
+        data = source.encode("utf-8") if isinstance(source, str) else source
+    try:
+        root = etree.fromstring(data, parser=etree.XMLParser(resolve_entities=False, no_network=True))
+    except etree.XMLSyntaxError as e:
+        raise RecordError(f"the record is not well-formed XML: {e}") from e
+
+    name = _local(root.tag)
+    if not (_is_sdc4(root) and name.startswith("dm-")):
+        raise RecordError(f"the record's root is {root.tag!r}, not an sdc4:dm-<ct_id> element")
+    if name[3:] != model.ct_id:
+        raise RecordError(f"the record is of model {name[3:]}, not {model.ct_id}")
+
+    attributes = {}
+    for el in root:
+        n = _local(el.tag)
+        if n in RECORD_ATTRIBUTES:
+            attributes[n] = _text(el)
+
+    record = Record(model=model, attributes=attributes)
+    seen: dict[tuple, int] = {}
+
+    def walk(el, path: list[Component]):
+        for child in el:
+            if not _is_sdc4(child):
+                continue
+            n = _local(child.tag)
+            if not n.startswith("ms-"):
+                continue
+            comp = model.components.get(n[3:])
+            if comp is None:                     # an adapter: pass through to the component inside
+                walk(child, path)
+            elif comp.sdc_type == "Cluster" or comp.sdc_type not in LEAF_TYPES:
+                walk(child, path + [comp])       # a cluster, or a structural component (audit, party, ...) holding values
+            else:
+                key = (comp.ct_id, tuple(c.ct_id for c in path))
+                occurrence = seen.get(key, 0)
+                seen[key] = occurrence + 1
+                record.values.append(_value(child, comp, path, occurrence, len(record.values)))
+
+    walk(root, [])
+    return record
+
+
+def _value(el, comp: Component, path: list[Component], occurrence: int, position: int) -> RecordValue:
+    elements: dict = {}
+    context: dict[str, str] = {}
+    ev_code = None
+    for c in el:
+        if not isinstance(c.tag, str):
+            continue
+        n = _local(c.tag)
+        if _is_sdc4(c) and n in EXCEPTIONAL_VALUES:
+            ev_code = n
+        elif n == "label":
+            continue
+        elif n in CONTEXT_ELEMENTS:
+            context[n] = _text(c)
+        else:
+            elements[n] = _nested(c)
+    exceptional = None
+    if ev_code:
+        value_present = any(k.endswith("-value") or k.startswith("xdtemporal-") for k in elements)
+        exceptional = ExceptionalValue(code=ev_code, name=EXCEPTIONAL_VALUES[ev_code],
+                                       origin="recovery" if value_present else "source")
+    return RecordValue(component=comp, path=path, occurrence=occurrence, position=position, elements=elements,
+                       context=context, exceptional=exceptional)

{sdcreader-4.2.0 → sdcreader-4.3.0/src/sdcreader.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdcreader
-Version: 4.2.0
+Version: 4.3.0
 Summary: Read a published Semantic Data Charter model's package for projection into other standards (CDIF, DCAT-US, DCAT-AP, HealthDCAT-AP); MCP server included.
 Author: Axius SDC, Inc.
 License: Apache-2.0
@@ -89,6 +89,25 @@ which is complete.
 - Constants: the leaf, numeric and quantified types; the predicate IRIs `IDENTIFIER`, `SOURCE`, `PUBLISHER`, `EXACT`,
   `CLOSE`, `SEE_ALSO`, `HAS_UNIT`; `DC_DEFAULTS`.
 
+## Reading a record (4.3.0)
+
+`read_record(source, model)` reads a Governed Data Record, the XML instance, and joins each value to the component
+that defines it. `source` is the record's bytes, its text or a path; a record of another model is refused
+(`RecordError`), as is anything that is not an `sdc4:dm-<ct_id>` record.
+
+- **`Record`**: `attributes` (`instance_id`, `instance_version`, `creation_timestamp`, `current-state`, ...),
+  `values` in document order, and `exceptional`, the values that carry an Exceptional Value.
+- **`RecordValue`**: the `component`, its `path` of clusters (root first), an `occurrence` index for a component
+  repeated under the same path, its `position`, its `elements` as the record holds them (a quantity's units nested:
+  `{"xdquantity-value": "1", "xdquantity-units": {"label": "Trade Units", "xdstring-value": "EA"}}`), and its
+  `context` (`act`, `vtb`, `vte`, `tr`, `modified`, `latitude`, `longitude`).
+- **`ExceptionalValue`**: the ISO 21090 null flavor (`code`, `name`) and its `origin`: `source` when it stands in
+  place of the value, `recovery` when sdcvalidator's recovery inserted it beside a value that failed its constraint.
+  For `recovery`, `RecordValue.rejected` is that value, kept so a person can see it.
+
+Cluster members sit inside adapter elements that are not components of the model; the reader passes through them.
+It does not type, validate or interpret values: that is the caller's work (a mapper, an exporter, a checker).
+
 ## MCP server
 
 `sdcreader` is also an MCP server, registered as `io.github.SemanticDataCharter/sdcreader`, so an assistant can read a
@@ -107,8 +126,9 @@ uvx sdcreader --host https://your-sdcstudio.example   # a sovereign SDCStudio's
 | `list_leaves` | the leaves in document order with path, type, constraints, code count and identity links, paged |
 | `list_codes` | one component's enumerated values with IRI, definition and code system |
 | `check_package` | the reader's integrity check on a package directory |
+| `read_record` | a Governed Data Record on disk read against its model: attributes, then each value with its component, path, elements, context and Exceptional Value, paged; the model is the one the record names unless a source is given |
 
-Each tool takes a `ct_id` (fetched from the host the server was started with) or a package `directory` on disk.
+Each model tool takes a `ct_id` (fetched from the host the server was started with) or a package `directory` on disk.
 No tool takes a URL: the host is fixed at start, so a caller cannot point the server elsewhere. Every tool calls the
 same functions as the library; the two interfaces describe one model the same way.
 

{sdcreader-4.2.0 → sdcreader-4.3.0}/src/sdcreader.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ src/sdcreader/mcp.py
 src/sdcreader/mcp_server.py
 src/sdcreader/model.py
 src/sdcreader/package.py
+src/sdcreader/record.py
 src/sdcreader.egg-info/PKG-INFO
 src/sdcreader.egg-info/SOURCES.txt
 src/sdcreader.egg-info/dependency_links.txt
@@ -15,4 +16,5 @@ src/sdcreader.egg-info/requires.txt
 src/sdcreader.egg-info/top_level.txt
 tests/test_mcp_scaffold.py
 tests/test_mcp_server.py
-tests/test_reader.py
+tests/test_reader.py
+tests/test_record.py

{sdcreader-4.2.0 → sdcreader-4.3.0}/tests/test_mcp_server.py

@@ -1,4 +1,4 @@
-"""The MCP server: JSON-RPC 2.0 handling and the five read-only tools, offline against the NHANES fixture."""
+"""The MCP server: JSON-RPC 2.0 handling and the six read-only tools, offline against the NHANES and Halvorsen fixtures."""
 import json
 from pathlib import Path
 
@@ -60,9 +60,10 @@ class TestProtocol:
     def test_initialized_notification_has_no_response(self):
         assert _handle_request({"jsonrpc": "2.0", "method": "notifications/initialized"}) is None
 
-    def test_tools_list_names_the_five_tools_with_schemas(self):
+    def test_tools_list_names_the_six_tools_with_schemas(self):
         tools = rpc("tools/list", {})["result"]["tools"]
-        assert {t["name"] for t in tools} == {"find_models", "describe_model", "list_leaves", "list_codes", "check_package"}
+        assert {t["name"] for t in tools} == {"find_models", "describe_model", "list_leaves", "list_codes", "check_package",
+                                             "read_record"}
         assert set(TOOL_HANDLERS) == {t["name"] for t in TOOLS}
         for t in tools:
             assert t["inputSchema"]["type"] == "object"
@@ -174,3 +175,31 @@ class TestTools:
 def test_find_models_against_production():
     r = call_ok("find_models", {"project": "FAIR Data Demo", "page_size": 3})
     assert r["count"] >= 1 and r["models"][0]["project"] == "FAIR Data Demo"
+
+
+HALVORSEN = Path(__file__).resolve().parents[1] / "samples" / "halvorsen-credit-note"
+HALVORSEN_CT = "jkuyr38hydqaiwlq5vhp2rjr"
+
+
+class TestReadRecord:
+    def test_reads_a_record_against_a_package_directory(self):
+        out = call_ok("read_record", {"record": str(HALVORSEN / "record.xml"), "directory": str(HALVORSEN), "limit": 5})
+        assert out["ct_id"] == HALVORSEN_CT and out["attributes"]["dm-label"] == "Credit Note"
+        assert out["returned"] == 5 and out["total"] > 5 and out["next_offset"] == 5 and out["exceptional"] == 0
+        v = out["values"][0]
+        assert v["path"][0] == "Credit Note Governed Record" and v["elements"] and v["exceptional"] is None
+
+    def test_the_model_comes_from_the_record_when_no_source_is_given(self, monkeypatch):
+        from sdcreader.package import load_package
+        asked = []
+        monkeypatch.setattr(srv, "fetch_package", lambda ct_id, host=None: asked.append(ct_id) or load_package(HALVORSEN, ct_id))
+        monkeypatch.setattr(srv, "_CACHE", {})
+        out = call_ok("read_record", {"record": str(HALVORSEN / "record.xml"), "limit": 1})
+        assert asked == [HALVORSEN_CT] and out["ct_id"] == HALVORSEN_CT
+
+    def test_a_record_of_another_model_is_a_tool_error(self):
+        text = call_err("read_record", {"record": str(HALVORSEN / "record.xml"), "directory": str(SAMPLE)})
+        assert "not " + CT in text
+
+    def test_a_missing_file_is_a_tool_error(self, tmp_path):
+        assert "Could not read the record" in call_err("read_record", {"record": str(tmp_path / "none.xml")})

sdcreader-4.3.0/tests/test_record.py

@@ -0,0 +1,130 @@
+"""The record reader: a Governed Data Record (XML) read and joined to its model.
+
+Fixture: a Credit Note record from HalvorsenDemo and the published package of its model (samples/halvorsen-credit-note).
+"""
+from pathlib import Path
+
+import pytest
+from lxml import etree
+
+from sdcreader import load_package, read_model
+from sdcreader.model import SDC4
+from sdcreader.record import EXCEPTIONAL_VALUES, RecordError, read_record
+
+SAMPLE = Path(__file__).resolve().parents[1] / "samples" / "halvorsen-credit-note"
+CT = "jkuyr38hydqaiwlq5vhp2rjr"
+RECORD = SAMPLE / "record.xml"
+
+
+@pytest.fixture(scope="module")
+def model():
+    return read_model(load_package(SAMPLE, CT))
+
+
+def _first_string(tree):
+    """The first XdString value element in the record, and its component element."""
+    value = tree.find(".//xdstring-value")
+    return value, value.getparent()
+
+
+def test_attributes_and_values(model):
+    r = read_record(RECORD, model)
+    assert r.attributes["dm-label"] == "Credit Note"
+    assert r.instance_id == r.attributes["instance_id"] and len(r.instance_id) == 24
+    assert r.attributes["instance_version"] == "1"
+    assert r.values and all(v.elements or v.exceptional for v in r.values)
+    assert [v.position for v in r.values] == list(range(len(r.values)))
+    assert all(v.path and v.path[0] is model.root for v in r.values)
+
+
+def test_every_value_is_a_component_of_the_model_and_adapters_are_passed_through(model):
+    r = read_record(RECORD, model)
+    assert {v.component.ct_id for v in r.values} <= set(model.components)
+    adapters = {el.tag.split("ms-", 1)[1] for el in etree.parse(str(RECORD)).iter(f"{{{SDC4}}}*")
+                if el.tag.split("}", 1)[1].startswith("ms-") and el.tag.split("ms-", 1)[1] not in model.components}
+    assert adapters, "the fixture should contain adapter elements"
+    assert not adapters & {c.ct_id for v in r.values for c in [v.component, *v.path]}
+
+
+def test_a_quantity_keeps_its_units_nested(model):
+    r = read_record(RECORD, model)
+    q = next(v for v in r.values if v.component.sdc_type == "XdQuantity")
+    assert "xdquantity-value" in q.elements
+    units = q.elements["xdquantity-units"]
+    assert isinstance(units, dict) and units["xdstring-value"]
+
+
+def test_the_same_record_as_text_and_bytes(model):
+    a = read_record(RECORD, model)
+    b = read_record(RECORD.read_bytes(), model)
+    c = read_record(RECORD.read_text(encoding="utf-8"), model)
+    assert [v.elements for v in a.values] == [v.elements for v in b.values] == [v.elements for v in c.values]
+
+
+def test_a_record_of_another_model_is_refused(model):
+    other = RECORD.read_text(encoding="utf-8").replace(f"dm-{CT}", "dm-" + "a" * 24)
+    with pytest.raises(RecordError, match="not " + CT):
+        read_record(other, model)
+
+
+@pytest.mark.parametrize("text, match", [
+    ("<notarecord/>", "not an sdc4:dm-"),
+    ("<sdc4:dm-x", "not well-formed"),
+])
+def test_what_is_not_a_record_is_refused(model, text, match):
+    with pytest.raises(RecordError, match=match):
+        read_record(text, model)
+
+
+def test_an_exceptional_value_written_at_the_source_stands_in_place_of_the_value(model):
+    tree = etree.parse(str(RECORD))
+    value, comp = _first_string(tree)
+    comp.remove(value)
+    ev = etree.SubElement(comp, f"{{{SDC4}}}ASKR")
+    etree.SubElement(ev, "ev-name").text = "Asked and Refused"
+    comp.insert(1, ev)
+    r = read_record(etree.tostring(tree), model)
+    v = next(v for v in r.values if v.exceptional)
+    assert (v.exceptional.code, v.exceptional.name, v.exceptional.origin) == ("ASKR", "Asked and Refused", "source")
+    assert "xdstring-value" not in v.elements and v.rejected == {}
+    assert r.exceptional == [v]
+
+
+def test_an_exceptional_value_from_recovery_stands_beside_the_rejected_value(model):
+    tree = etree.parse(str(RECORD))
+    value, comp = _first_string(tree)
+    ev = etree.Element(f"{{{SDC4}}}INV")
+    etree.SubElement(ev, "ev-name").text = "Invalid"
+    comp.insert(1, ev)
+    r = read_record(etree.tostring(tree), model)
+    v = next(v for v in r.values if v.exceptional)
+    assert (v.exceptional.code, v.exceptional.origin) == ("INV", "recovery")
+    assert v.rejected == {"xdstring-value": value.text}
+
+
+def test_every_iso_21090_code_is_known():
+    assert set(EXCEPTIONAL_VALUES) == {"INV", "OTH", "UNC", "NI", "NA", "UNK", "ASKU", "ASKR", "NASK", "NAV", "MSK",
+                                       "DER", "PINF", "NINF", "TRC", "QS"}
+
+
+def test_a_repeated_component_is_numbered_in_document_order(model):
+    tree = etree.parse(str(RECORD))
+    _, comp = _first_string(tree)
+    twin = etree.fromstring(etree.tostring(comp))
+    twin.find("xdstring-value").text = "second"
+    comp.addnext(twin)
+    r = read_record(etree.tostring(tree), model)
+    pair = [v for v in r.values if v.component.ct_id == comp.tag.split("ms-", 1)[1]]
+    assert [v.occurrence for v in pair[:2]] == [0, 1]
+    assert pair[1].elements["xdstring-value"] == "second"
+
+
+def test_context_elements_are_kept_apart_from_the_value(model):
+    tree = etree.parse(str(RECORD))
+    value, comp = _first_string(tree)
+    vtb = etree.Element("vtb")
+    vtb.text = "2026-01-01T00:00:00"
+    value.addprevious(vtb)
+    r = read_record(etree.tostring(tree), model)
+    v = next(v for v in r.values if v.context)
+    assert v.context == {"vtb": "2026-01-01T00:00:00"} and "vtb" not in v.elements