s3dgraphy 1.6.0.dev36__tar.gz → 1.6.0.dev38__tar.gz

{s3dgraphy-1.6.0.dev36/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev36
+Version: 1.6.0.dev38
 Summary: 3D Stratigraphic Graph Management Library for archaeological and heritage applications
 Author-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
 Maintainer-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>

{s3dgraphy-1.6.0.dev36 → s3dgraphy-1.6.0.dev38}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "s3dgraphy"
-version = "1.6.0.dev36"
+version = "1.6.0.dev38"
 description = "3D Stratigraphic Graph Management Library for archaeological and heritage applications"
 readme = "README.md"
 requires-python = ">=3.9"

{s3dgraphy-1.6.0.dev36 → s3dgraphy-1.6.0.dev38}/src/s3dgraphy/JSON_config/datamodel_translations.json

@@ -2324,6 +2324,27 @@
     "de": "Ästhetischer Wert"
    }
   },
+  "alternative_label": {
+   "label": {
+    "en": "Alternative Label",
+    "validated_it": false,
+    "validated_el": false,
+    "validated_he": false,
+    "validated_es": false,
+    "validated_pl": false,
+    "validated_ro": false,
+    "validated_fr": false,
+    "validated_de": false,
+    "it": "Etichetta alternativa",
+    "el": "Εναλλακτική ετικέτα",
+    "he": "תווית חלופית",
+    "es": "Etiqueta alternativa",
+    "pl": "Etykieta alternatywna",
+    "ro": "Etichetă alternativă",
+    "fr": "Libellé alternatif",
+    "de": "Alternative Bezeichnung"
+   }
+  },
   "area": {
    "label": {
     "en": "Area",

{s3dgraphy-1.6.0.dev36 → s3dgraphy-1.6.0.dev38}/src/s3dgraphy/JSON_config/em_qualia_types.json

@@ -1,11 +1,11 @@
 {
     "metadata": {
-      "version": "1.6.6",
-      "last_updated": "2026-10-01",
+      "version": "1.6.7",
+      "last_updated": "2026-10-05",
       "maintainers": ["Emanuel Demetrescu"],
       "license": "CC-BY-SA-4.0",
       "license_note": "Share-alike per allinearsi agli strumenti terminologici da cui questo datamodel prende gli ancoraggi (ICCD CC BY-SA 3.0 IT) e perche' una derivazione resti aperta. Gli identificatori AAT/CIDOC citati nei `mappings` sono RIFERIMENTI, non contenuto incorporato: lo share-alike non si propaga ai vocabolari altrui, che mantengono i propri termini.",
-      "changelog": "v1.6.6 (dev27, 2026-10-31, decided by E.D. 2026-10-01): cultural_interpretive.semantic.attribution gains an optional `note` in its schema and `natural_language_fields: [\"note\"]` — the object is not text, its note is, and only the note carries a language tag (rdf_exporter._Datamodel.natural_language_fields). v1.6.5 (MICRO le traduzioni, 2026-10-29, decided by E.D. 2026-10-01, domanda 3): the doubtful qualia, MEASURED. contextual.administrative.intervention_history is prose (a history of conservation interventions) and gains `natural_language: true`. provenance_history, exhibition_history, publication_history and contextual.ownership.ownership_chain are `object_chain` WITHOUT a schema: no field of theirs is declared and no code reads a structure, so what a PropertyNode stores is ONE string (the chain as written) — the whole string is marked. cultural_interpretive.semantic.attribution is an `object` WITH separate fields (attributed_to: an E39 Actor reference, attribution_type: a closed list, confidence: a float): none of them is a note, so nothing is marked — the rule is to mark only the note, and this object has none. Its value today travels as one string (\"attributed to Phidias\") and leaves untagged; marking it would need a `note` field in its schema, which is E.D.'s to add. inventory_number stays a code. v1.6.4 (MICRO la lingua dei dati, 2026-10-27, decided by E.D. 2026-09-28): cultural_interpretive.iconographic.narrative_content gains `natural_language: true` — its value is prose and leaves in RDF with its language tag (crm:P90_has_value \"la guerra di Troia\"@it), the language coming from the property node's data.lang, else the study's working language. data_type alone does not say it: inventory_number is a string too, and it is a CODE, so it is not marked and never tagged. No other quale marked: the ones whose value may be prose (intervention_history, attribution, the *_history and ownership_chain object chains) are waiting for E.D. v1.6.3 (MICRO em.ttl nel datamodel, 2026-10-26, decided by E.D. 2026-10-01 — every em: term of em.ttl is cited by a datamodel): epistemic.confidence.confidence_level.mappings gains specialised_alternative 'em:confidenceLevel', the em.ttl literal form of the same scalar, declared and NOT emitted (the exporter keeps crminf:I6_Belief_Value via J5). Mapping text only, no quale changed. v1.6.2: added two descriptive qualia of the stratigraphic unit asked for by the DAI record (iDAI.field Layer, D7/D8) — proposte da Cowork per E.D., 28 set 2026, dalla scheda DAI: `feature_shape` (spatial; the shape in plan or section named with a term, AAT 300056273, E55_Type) and `boundary_distinctness` (material; how sharp the limits are: abrupt / clear / gradual / diffuse, E55_Type, no AAT evident). Both controlled vocabularies with indicative seed values; templates declare their own. v1.6.1: added the spatial qualia `geometry` — the PROXY as a quale. The geometry-without-material of a unit becomes a PropertyNode whose payload is a SemanticShapeNode (has_semantic_shape), so the proxy inherits the paradata chain a lone node could not have, and one proxy can be synthesised from several sources. CIDOC default crmgeo:SP5_Geometric_Place_Expression, flagged `confirm_with: Felicetti` (E36 is the alternative, to be decided together with em:AnnotationRegion). v1.6.0: version realigned to the EM language version (EM 1.6) — supersedes the standalone 4.x line (last was 4.2), so all EM JSON config files now share the 1.6.x scheme. Added optional `rationale` + `example` fields to qualia entries (a plain-language why + a concrete case), shown by the EMStudio vocabulary picker when creating a PropertyNode. Seeded for the temporal qualia (absolute_time_start / absolute_time_end / dating_method); to be filled in for the rest incrementally. Prior (4.x) history: v4.2 added rationale/example scaffolding; v4.1: expanded spatial elevation qualia for pyArchInit us_table quote (all E54_Dimension): elevation_relative, elevation_min_absolute, elevation_max_absolute, elevation_min_relative, elevation_max_relative, elevation_min_usm, elevation_max_usm (the generic 'elevation' = absolute MASL, used by quota_abs). Each pyArchInit quota column maps to its own qualia id so they don't collide on the single-PropertyNode-per-property_name rule. v4.0: verified all v3.0 CIDOC-CRM mappings (correct). Expanded with: volume, area, circumference in dimensional; color, texture, finish, patina, hardness, porosity in material; damage_type, fragility, completeness in state; tool_marks, joining_technique in technical; bounding_box, footprint_area in spatial; duration, terminus_post_quem, terminus_ante_quem, relative_chronology in temporal; ceremonial_function, ritual_function, defensive_function, domestic_function, symbolic_function in telic; school, workshop, period_attribution in stylistic. NEW subcategories: iconographic + semantic under cultural_interpretive (iconographic_subject, narrative_content, iconographic_program, aesthetic_value, religious_significance, monumental_status, attribution). Added provenance_history, exhibition_history, publication_history under administrative; NEW ownership subcategory (current_custodian, ownership_chain). NEW CATEGORY epistemic — meta-qualia central to EM paradata model (confidence_level, certainty_level, uncertainty_factors, methodology_used, validation_method, source_quality, primary_contributor, review_status, last_modified)."
+      "changelog": "v1.6.7 (MICRO le decisioni della sera, 2026-10-05, asked by E.D. 2026-10-04): contextual.administrative gains `alternative_label` — another label of the element in a source (a numbering of another excavation, of a thesis), analogous to skos:altLabel, projected as crm:P1_is_identified_by → E41_Appellation. The first quale declared `repeatable: true`: one PropertyNode per label, never a list in one value, and the merger keys it with its value (two labels are two claims). Its source is the ordinary paradata chain (property has_data_provenance → extractor extracted_from → document); an optional data.scheme names the numbering. The element's own label (area.settore.tipoNumero) is unchanged. s3dgraphy.labels writes and reads them. v1.6.6 (dev27, 2026-10-31, decided by E.D. 2026-10-01): cultural_interpretive.semantic.attribution gains an optional `note` in its schema and `natural_language_fields: [\"note\"]` — the object is not text, its note is, and only the note carries a language tag (rdf_exporter._Datamodel.natural_language_fields). v1.6.5 (MICRO le traduzioni, 2026-10-29, decided by E.D. 2026-10-01, domanda 3): the doubtful qualia, MEASURED. contextual.administrative.intervention_history is prose (a history of conservation interventions) and gains `natural_language: true`. provenance_history, exhibition_history, publication_history and contextual.ownership.ownership_chain are `object_chain` WITHOUT a schema: no field of theirs is declared and no code reads a structure, so what a PropertyNode stores is ONE string (the chain as written) — the whole string is marked. cultural_interpretive.semantic.attribution is an `object` WITH separate fields (attributed_to: an E39 Actor reference, attribution_type: a closed list, confidence: a float): none of them is a note, so nothing is marked — the rule is to mark only the note, and this object has none. Its value today travels as one string (\"attributed to Phidias\") and leaves untagged; marking it would need a `note` field in its schema, which is E.D.'s to add. inventory_number stays a code. v1.6.4 (MICRO la lingua dei dati, 2026-10-27, decided by E.D. 2026-09-28): cultural_interpretive.iconographic.narrative_content gains `natural_language: true` — its value is prose and leaves in RDF with its language tag (crm:P90_has_value \"la guerra di Troia\"@it), the language coming from the property node's data.lang, else the study's working language. data_type alone does not say it: inventory_number is a string too, and it is a CODE, so it is not marked and never tagged. No other quale marked: the ones whose value may be prose (intervention_history, attribution, the *_history and ownership_chain object chains) are waiting for E.D. v1.6.3 (MICRO em.ttl nel datamodel, 2026-10-26, decided by E.D. 2026-10-01 — every em: term of em.ttl is cited by a datamodel): epistemic.confidence.confidence_level.mappings gains specialised_alternative 'em:confidenceLevel', the em.ttl literal form of the same scalar, declared and NOT emitted (the exporter keeps crminf:I6_Belief_Value via J5). Mapping text only, no quale changed. v1.6.2: added two descriptive qualia of the stratigraphic unit asked for by the DAI record (iDAI.field Layer, D7/D8) — proposte da Cowork per E.D., 28 set 2026, dalla scheda DAI: `feature_shape` (spatial; the shape in plan or section named with a term, AAT 300056273, E55_Type) and `boundary_distinctness` (material; how sharp the limits are: abrupt / clear / gradual / diffuse, E55_Type, no AAT evident). Both controlled vocabularies with indicative seed values; templates declare their own. v1.6.1: added the spatial qualia `geometry` — the PROXY as a quale. The geometry-without-material of a unit becomes a PropertyNode whose payload is a SemanticShapeNode (has_semantic_shape), so the proxy inherits the paradata chain a lone node could not have, and one proxy can be synthesised from several sources. CIDOC default crmgeo:SP5_Geometric_Place_Expression, flagged `confirm_with: Felicetti` (E36 is the alternative, to be decided together with em:AnnotationRegion). v1.6.0: version realigned to the EM language version (EM 1.6) — supersedes the standalone 4.x line (last was 4.2), so all EM JSON config files now share the 1.6.x scheme. Added optional `rationale` + `example` fields to qualia entries (a plain-language why + a concrete case), shown by the EMStudio vocabulary picker when creating a PropertyNode. Seeded for the temporal qualia (absolute_time_start / absolute_time_end / dating_method); to be filled in for the rest incrementally. Prior (4.x) history: v4.2 added rationale/example scaffolding; v4.1: expanded spatial elevation qualia for pyArchInit us_table quote (all E54_Dimension): elevation_relative, elevation_min_absolute, elevation_max_absolute, elevation_min_relative, elevation_max_relative, elevation_min_usm, elevation_max_usm (the generic 'elevation' = absolute MASL, used by quota_abs). Each pyArchInit quota column maps to its own qualia id so they don't collide on the single-PropertyNode-per-property_name rule. v4.0: verified all v3.0 CIDOC-CRM mappings (correct). Expanded with: volume, area, circumference in dimensional; color, texture, finish, patina, hardness, porosity in material; damage_type, fragility, completeness in state; tool_marks, joining_technique in technical; bounding_box, footprint_area in spatial; duration, terminus_post_quem, terminus_ante_quem, relative_chronology in temporal; ceremonial_function, ritual_function, defensive_function, domestic_function, symbolic_function in telic; school, workshop, period_attribution in stylistic. NEW subcategories: iconographic + semantic under cultural_interpretive (iconographic_subject, narrative_content, iconographic_program, aesthetic_value, religious_significance, monumental_status, attribution). Added provenance_history, exhibition_history, publication_history under administrative; NEW ownership subcategory (current_custodian, ownership_chain). NEW CATEGORY epistemic — meta-qualia central to EM paradata model (confidence_level, certainty_level, uncertainty_factors, methodology_used, validation_method, source_quality, primary_contributor, review_status, last_modified)."
     },
     "qualia_categories": [
       {
@@ -1071,6 +1071,29 @@
             ],
             "_description_todo": "This subcategory shipped with no description, so its tooltip was empty in the EMStudio vocabulary picker (the only one of 17). The three proposals above match the register of the sibling subcategories — short noun phrase; the longer one mirrors `ownership`, which already defines itself AGAINST this one ('distinct from administrative qualia which cover legal/inventory aspects'). Pick one, move it into `description`, and delete these two keys.",
             "qualia": [
+              {
+                "id": "alternative_label",
+                "name": "Alternative Label",
+                "description": "Another label by which the element is known in a source — a numbering of another excavation, of a thesis, of an archive — with that source as paradata. Repeatable: one property per label. The element's own label (the rule area.settore.tipoNumero) does not change.",
+                "mappings": {
+                  "cidoc_crm": "E41_Appellation",
+                  "unit_predicate": "crm:P1_is_identified_by",
+                  "skos": "skos:altLabel",
+                  "mapping_note": "The label is an appellation of the unit (E41, reached with P1_is_identified_by), the same relation skos:altLabel states for a concept; its source is the ordinary paradata chain (has_data_provenance → extractor → extracted_from → the document that uses the label), so it is cited like every other assertion. A numbering it belongs to is data.scheme."
+                },
+                "data_type": "string",
+                "repeatable": true,
+                "schema": {
+                  "label": "string",
+                  "scheme": "string"
+                },
+                "rationale": "Units of one site are often named differently by the people who dug and studied it: the oldest excavation names them without numbers, a later one numbers them, a thesis numbers them again where the official numbering is missing (E.D., Templu Mare). Keeping every such label, each with the source that uses it, is what lets a reader of any of those publications find the unit — and the search finds them.",
+                "example": "1.US10 is «US 1004» in the 2013 excavation report (scheme «scavo 2013») and «A.12» in Demetrescu's thesis (scheme «tesi Demetrescu»): two alternative_label properties, each with an extractor from its document.",
+                "expected_extractors": [
+                  "archival_research",
+                  "bibliographic_research"
+                ]
+              },
               {
                 "id": "inventory_number",
                 "name": "Inventory Number",

{s3dgraphy-1.6.0.dev36 → s3dgraphy-1.6.0.dev38}/src/s3dgraphy/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.6.0.dev36"
+__version__ = "1.6.0.dev38"
 __datamodel_version__ = "1.5.5"  # s3Dgraphy connections datamodel version
 
 # s3Dgraphy/__init__.py

{s3dgraphy-1.6.0.dev36 → s3dgraphy-1.6.0.dev38}/src/s3dgraphy/api.py

@@ -284,6 +284,41 @@ def shared_properties(graph: Graph) -> List[Dict[str, Any]]:
     return _shared(graph)
 
 
+# ── A1 · the alternative labels of a unit, each with its source ─────────────
+def add_alternative_label(graph: Graph, unit_id: str, label: str, *,
+                          sources: Optional[Sequence[str]] = None,
+                          scheme: Optional[str] = None,
+                          author: Optional[str] = None) -> Dict[str, Any]:
+    """Another label of ``unit_id`` (quale ``alternative_label``, like
+    skos:altLabel): ONE PropertyNode per label, its sources as paradata
+    (property → extractor → the document that uses the label), an optional
+    ``scheme`` (the numbering it belongs to). The unit's own label does not
+    change. Same label, unit and scheme again → the same nodes.
+    See :mod:`s3dgraphy.labels`."""
+    from .labels import add_alternative_label as _add
+    return _add(graph, unit_id, label, sources=sources, scheme=scheme, author=author)
+
+
+def alternative_labels(graph: Graph, unit_id: str) -> List[Dict[str, Any]]:
+    """``[{property_id, label, scheme, sources: [{id, name, extractor_id}]}]``."""
+    from .labels import alternative_labels as _labels
+    return _labels(graph, unit_id)
+
+
+def remove_alternative_label(graph: Graph, unit_id: str, property_id: str) -> bool:
+    """Take one alternative label off a unit (its extractors stay)."""
+    from .labels import remove_alternative_label as _remove
+    return _remove(graph, unit_id, property_id)
+
+
+def find_by_label(graph: Graph, text: str, *, exact: bool = False) -> List[Dict[str, Any]]:
+    """The nodes whose label or one of whose alternative labels matches
+    ``text`` (case-insensitive, substring unless ``exact``): ``[{node_id,
+    name, matched, scheme}]``."""
+    from .labels import find_by_label as _find
+    return _find(graph, text, exact=exact)
+
+
 # ── human authorship with AI support, and its verification ──────────────────
 def unvalidated_ai(graph: Graph) -> List[Dict[str, Any]]:
     """Every node made with AI (``data.ai_assisted``) that no person has

{s3dgraphy-1.6.0.dev36 → s3dgraphy-1.6.0.dev38}/src/s3dgraphy/exporter/rdf_exporter.py

@@ -266,6 +266,7 @@ class _Datamodel:
         #: quale id → the fields of an OBJECT value that are natural language
         #: (dev27: attribution.note) — the object is not text, its note is
         self._qualia_natural_language_fields: Dict[str, Tuple[str, ...]] = {}
+        self._qualia_unit_predicates: Dict[str, Tuple[str, str]] = {}
         self._build_qualia_index(self.qualia_types)
 
         #: reverse edge name → canonical edge name. The connections datamodel
@@ -312,6 +313,14 @@ class _Datamodel:
                     if qid and isinstance(fields, list):
                         self._qualia_natural_language_fields[qid] = tuple(
                             str(f) for f in fields)
+                    # A1 · a quale that ALSO says something of its unit with a
+                    # predicate of its own (alternative_label: the unit is
+                    # identified by the label, P1, and the label is its
+                    # skos:altLabel)
+                    if qid and mappings.get("unit_predicate"):
+                        self._qualia_unit_predicates[qid] = (
+                            str(mappings["unit_predicate"]),
+                            str(mappings.get("skos") or ""))
 
     # ─── public lookups ─────────────────────────────────────────────────────
 
@@ -560,6 +569,13 @@ class _Datamodel:
                 return key
         return None
 
+    def unit_predicate_for(self, property_type: Optional[str]):
+        """``(unit_predicate, skos_predicate)`` of a quale that declares one
+        (``mappings.unit_predicate``), else None."""
+        if not property_type:
+            return None
+        return self._qualia_unit_predicates.get(property_type)
+
     def get_qualia_crm_iri(self, property_type: Optional[str]) -> Optional[URIRef]:
         """Resolve a property_type string to its CIDOC class IRI.
 
@@ -1052,6 +1068,26 @@ class RDFExporter:
                          EM.inheritsQualia,
                          self._node_iri(g.graph_id, edge.edge_target)))
 
+        # A1 · the qualia with a predicate of their own on the unit: an
+        # alternative_label leaves as <unit> crm:P1_is_identified_by <label>
+        # and <unit> skos:altLabel "the label" — beside em:hasQualia, so a
+        # reader that knows only CIDOC or only SKOS finds it too
+        for edge in g.edges:
+            if edge.edge_type != "has_property":
+                continue
+            pn = g.find_node_by_id(edge.edge_target)
+            ptype = getattr(pn, "property_type", None) or getattr(pn, "name", None)
+            pred = self.datamodel.unit_predicate_for(ptype)
+            if pn is None or pred is None:
+                continue
+            unit_iri = self._node_iri(g.graph_id, edge.edge_source)
+            if pred[0]:
+                ctx.add((unit_iri, _resolve_prefixed(pred[0]),
+                         self._node_iri(g.graph_id, pn.node_id)))
+            value = str(getattr(pn, "value", "") or "").strip()
+            if pred[1] and value:
+                ctx.add((unit_iri, _resolve_prefixed(pred[1]), Literal(value)))
+
         # CRMinf belief propositions (J4 → I17) — needs the full edge
         # topology, so it runs as a post-pass after nodes and edges.
         self._emit_belief_propositions(g, ctx)

{s3dgraphy-1.6.0.dev36 → s3dgraphy-1.6.0.dev38}/src/s3dgraphy/importer/import_graphml.py

@@ -3442,6 +3442,15 @@ class GraphMLImporter:
                 edge_type = "combines"
                 # print(f"Enhanced to combines: CombinerNode -> ExtractorNode")
 
+            # DocumentNode -> PropertyNode: the document's own property (its
+            # dating, `absolute_time_start` drawn beside a master document),
+            # the reading `_enrich_canonical_documents` already gives it.
+            # Measured on Templu Mare (4 Oct 2026): five of these came out
+            # generic_connection and reached the room that way.
+            elif (isinstance(source_node, DocumentNode)
+                  and isinstance(target_node, PropertyNode)):
+                edge_type = "has_property"
+
             # PropertyNode -> DocumentNode. BUGFIX-CONN3: this is read as
             # has_documentation (P70i_is_documented_in) — the honest shortcut
             # when a legacy yEd dashed connector links a property to a source

s3dgraphy-1.6.0.dev38/src/s3dgraphy/labels.py

@@ -0,0 +1,253 @@
+"""A1 · the alternative labels of a unit, each with its source.
+
+The case (E.D., Templu Mare): in the oldest excavation the units have a name
+and no number, in the 2013 one they are numbered, and for his doctoral thesis
+E.D. used a numbering of his own because the official one was missing. A unit
+must be able to carry several alternative labels, each with where it comes
+from.
+
+**The main label does not change.** It is the one of the rule
+``area.settore.tipoNumero`` (``1.US10``), unique in the graph — inside Blender
+two objects cannot have the same name. An alternative label is a PROPERTY of
+the unit, quale ``alternative_label`` (``em_qualia_types.json``, analogous to
+``skos:altLabel``, projected as ``crm:P1_is_identified_by`` → ``E41_Appellation``):
+
+* repeatable — ONE PropertyNode PER LABEL, never a list in one value;
+* its source is PARADATA, the ordinary chain: property ``has_data_provenance``
+  → extractor ``extracted_from`` → the document that uses that label (the 2013
+  excavation report, the thesis). So the source is citable like every other
+  assertion in EM, and a label read in two documents has two extractors and a
+  combiner, as any property does;
+* an optional ``scheme`` (``"scavo 2013"``, ``"tesi Demetrescu"``) names the
+  numbering it belongs to, for filtering.
+
+Ids are deterministic (``uuid5``), so writing the same label again for the same
+unit and scheme lands on the same nodes instead of piling up copies — the same
+discipline as ``geometry/proxy.py`` and ``annotation/paradata.py``.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Dict, List, Optional, Sequence
+
+from .graph import Graph
+from .nodes.combiner_node import CombinerNode
+from .nodes.extractor_node import ExtractorNode
+from .nodes.property_node import PropertyNode
+
+#: the quale, registered in em_qualia_types.json (contextual ▸ identification)
+ALTERNATIVE_LABEL = "alternative_label"
+
+_NS = uuid.uuid5(uuid.NAMESPACE_URL, "https://w3id.org/em/alternative-label")
+
+
+def _id(key: str) -> str:
+    return str(uuid.uuid5(_NS, key))
+
+
+def _norm(text: Any) -> str:
+    return " ".join(str(text or "").split())
+
+
+def property_id_for(unit_id: str, label: str, scheme: Optional[str] = None) -> str:
+    """The id of the PropertyNode carrying ``label`` (in ``scheme``) for a unit."""
+    return _id(f"altlabel|{unit_id}|{_norm(scheme).casefold()}|{_norm(label)}")
+
+
+def _edge(graph: Graph, source_id: str, target_id: str, edge_type: str,
+          out: Dict[str, Any]) -> None:
+    """One edge, or a warning — never a generic_connection."""
+    source = graph.find_node_by_id(source_id)
+    target = graph.find_node_by_id(target_id)
+    if source is None or target is None:
+        out["warnings"].append(f"alternative label: '{edge_type}' not created, an endpoint is missing")
+        return
+    if not graph.validate_connection(source.node_type, target.node_type, edge_type):
+        out["warnings"].append(
+            f"alternative label: '{edge_type}' is not allowed from "
+            f"{type(source).__name__} to {type(target).__name__}; NOT created")
+        return
+    edge_id = _id(f"edge|{source_id}|{edge_type}|{target_id}")
+    if graph.find_edge_by_id(edge_id) is None:
+        graph.add_edge(edge_id, source_id, target_id, edge_type)
+        out["created"] = True
+    out["edge_ids"].append(edge_id)
+
+
+def add_alternative_label(graph: Graph, unit_id: str, label: str, *,
+                          sources: Optional[Sequence[str]] = None,
+                          scheme: Optional[str] = None,
+                          author: Optional[str] = None) -> Dict[str, Any]:
+    """Give a unit an alternative label, with its sources.
+
+    Args:
+        unit_id: the node the label names (a stratigraphic unit, a document…:
+            whatever ``has_property`` admits as a source).
+        label: the label as the source writes it (``"US 1004"``, ``"Ambiente
+            B"``). Spaces are normalised; nothing else is changed.
+        sources: the ids of the documents (or annotation regions, or units)
+            that use this label. One source → one extractor; several → one
+            extractor each joined by a combiner.
+        scheme: the numbering the label belongs to (``"scavo 2013"``).
+        author: written as ``data.author`` on the created nodes.
+
+    Returns ``{property_id, extractor_ids, combiner_id, created, edge_ids,
+    warnings}``. Raises ValueError for an empty label.
+    """
+    text = _norm(label)
+    if not text:
+        raise ValueError("an alternative label needs a text")
+    out: Dict[str, Any] = {"property_id": property_id_for(unit_id, text, scheme),
+                           "extractor_ids": [], "combiner_id": None,
+                           "created": False, "edge_ids": [], "warnings": []}
+    unit = graph.find_node_by_id(unit_id)
+    if unit is None:
+        raise ValueError(f"no node '{unit_id}' in the graph")
+    if _norm(getattr(unit, "name", "")) == text:
+        out["warnings"].append(
+            f"alternative label: '{text}' is the unit's own label; written anyway")
+    pid = out["property_id"]
+    if graph.find_node_by_id(pid) is None:
+        prop = PropertyNode(node_id=pid, name=ALTERNATIVE_LABEL, value=text,
+                            property_type=ALTERNATIVE_LABEL)
+        if scheme:
+            prop.data["scheme"] = _norm(scheme)
+        if author:
+            prop.data["author"] = author
+        graph.add_node(prop)
+        out["created"] = True
+    _edge(graph, unit_id, pid, "has_property", out)
+
+    for source_id in [s for s in (sources or []) if s]:
+        src = graph.find_node_by_id(source_id)
+        if src is None:
+            out["warnings"].append(f"alternative label: source '{source_id}' is not in the graph")
+            continue
+        eid = _id(f"extractor|{pid}|{source_id}")
+        if graph.find_node_by_id(eid) is None:
+            ext = ExtractorNode(node_id=eid,
+                                name=f"{text} in {getattr(src, 'name', source_id)}",
+                                description=f"the label «{text}» as {getattr(src, 'name', source_id)} uses it")
+            if author:
+                ext.data["author"] = author
+            graph.add_node(ext)
+            out["created"] = True
+        _edge(graph, eid, source_id, "extracted_from", out)
+        out["extractor_ids"].append(eid)
+
+    if len(out["extractor_ids"]) > 1:
+        cid = _id(f"combiner|{pid}")
+        if graph.find_node_by_id(cid) is None:
+            comb = CombinerNode(node_id=cid, name=f"{text} · sources",
+                                description="the same label in several sources")
+            if author:
+                comb.data["author"] = author
+            graph.add_node(comb)
+            out["created"] = True
+        out["combiner_id"] = cid
+        for eid in out["extractor_ids"]:
+            _edge(graph, cid, eid, "combines", out)
+        _edge(graph, pid, cid, "has_data_provenance", out)
+    elif out["extractor_ids"]:
+        _edge(graph, pid, out["extractor_ids"][0], "has_data_provenance", out)
+    return out
+
+
+def _is_alt_label(node: Any) -> bool:
+    return (getattr(node, "node_type", "") == "property"
+            and (getattr(node, "property_type", None) == ALTERNATIVE_LABEL
+                 or getattr(node, "name", None) == ALTERNATIVE_LABEL))
+
+
+def _sources_of(graph: Graph, prop_id: str) -> List[Dict[str, str]]:
+    """The documents a property is read from, through its extractors (and a
+    combiner if there is one)."""
+    out: List[Dict[str, str]] = []
+    frontier = [e.edge_target for e in graph.edges
+                if e.edge_source == prop_id and e.edge_type == "has_data_provenance"]
+    seen = set()
+    while frontier:
+        nid = frontier.pop(0)
+        if nid in seen:
+            continue
+        seen.add(nid)
+        node = graph.find_node_by_id(nid)
+        nt = getattr(node, "node_type", "")
+        if nt == "combiner":
+            frontier += [e.edge_target for e in graph.edges
+                         if e.edge_source == nid and e.edge_type == "combines"]
+        elif nt == "extractor":
+            for e in graph.edges:
+                if e.edge_source == nid and e.edge_type == "extracted_from":
+                    doc = graph.find_node_by_id(e.edge_target)
+                    out.append({"id": e.edge_target, "name": str(getattr(doc, "name", "") or e.edge_target),
+                                "extractor_id": nid})
+    return out
+
+
+def alternative_labels(graph: Graph, unit_id: str) -> List[Dict[str, Any]]:
+    """The alternative labels of a unit: ``[{property_id, label, scheme,
+    sources: [{id, name, extractor_id}]}]``, in the order of the graph."""
+    out = []
+    for e in graph.edges:
+        if e.edge_source != unit_id or e.edge_type != "has_property":
+            continue
+        prop = graph.find_node_by_id(e.edge_target)
+        if prop is None or not _is_alt_label(prop):
+            continue
+        data = getattr(prop, "data", None) or {}
+        out.append({"property_id": prop.node_id, "label": str(getattr(prop, "value", "") or ""),
+                    "scheme": str(data.get("scheme") or ""),
+                    "sources": _sources_of(graph, prop.node_id)})
+    return out
+
+
+def remove_alternative_label(graph: Graph, unit_id: str, property_id: str) -> bool:
+    """Take a label off a unit: the edge goes, and the property with it when no
+    other node holds it (its extractors stay: they are readings of a source)."""
+    gone = [e for e in graph.edges if e.edge_source == unit_id
+            and e.edge_target == property_id and e.edge_type == "has_property"]
+    for e in gone:
+        graph.remove_edge(e.edge_id)
+    if gone and not any(e.edge_target == property_id and e.edge_type == "has_property"
+                        for e in graph.edges):
+        graph.remove_node(property_id)
+    return bool(gone)
+
+
+def find_by_label(graph: Graph, text: str, *, exact: bool = False) -> List[Dict[str, Any]]:
+    """The nodes whose label OR one of whose alternative labels matches
+    ``text`` (case-insensitive; a substring unless ``exact``):
+    ``[{node_id, name, matched, scheme}]`` — ``matched`` is the label that
+    answered, ``scheme`` its numbering (empty for the main label)."""
+    q = _norm(text).casefold()
+    if not q:
+        return []
+    hit = (lambda s: s.casefold() == q) if exact else (lambda s: q in s.casefold())
+    out: List[Dict[str, Any]] = []
+    seen = set()
+    for n in graph.nodes:
+        name = _norm(getattr(n, "name", ""))
+        # the paradata that carry a label in their own name (the extractor «US
+        # 1004 in D.2013…») are readings OF a label, not nodes it names
+        if getattr(n, "node_type", "") in ("property", "extractor", "combiner"):
+            continue
+        if name and hit(name):
+            out.append({"node_id": n.node_id, "name": name, "matched": name, "scheme": ""})
+            seen.add(n.node_id)
+    by_id = {n.node_id: n for n in graph.nodes}
+    for e in graph.edges:
+        if e.edge_type != "has_property" or e.edge_source in seen:
+            continue
+        prop = by_id.get(e.edge_target)
+        if prop is None or not _is_alt_label(prop):
+            continue
+        label = _norm(getattr(prop, "value", ""))
+        if label and hit(label):
+            owner = by_id.get(e.edge_source)
+            out.append({"node_id": e.edge_source, "name": _norm(getattr(owner, "name", "")),
+                        "matched": label,
+                        "scheme": str((getattr(prop, "data", None) or {}).get("scheme") or "")})
+            seen.add(e.edge_source)
+    return out

{s3dgraphy-1.6.0.dev36 → s3dgraphy-1.6.0.dev38}/src/s3dgraphy/merge/graph_merger.py

@@ -38,6 +38,10 @@ from ..edges.edge import Edge
 # spellings ``is_bonded_to`` / ``is_physically_equal_to`` (the datamodel's
 # ``spelling_of``) are still recognised, and COMPARED under the canonical name
 # (``_canonical_spelling``), so two spellings of one bond are not a conflict.
+#: The qualia a unit may carry more than once, one PropertyNode each
+#: (``repeatable: true`` in em_qualia_types.json).
+REPEATABLE_QUALIA = frozenset({"alternative_label"})
+
 STRATIGRAPHIC_EDGE_TYPES = {
     'overlies', 'is_overlain_by',
     'cuts', 'is_cut_by',
@@ -639,10 +643,7 @@ class GraphMerger:
                 cand = incoming.find_node_by_id(edge.edge_target)
                 if not isinstance(cand, PropertyNode):
                     continue
-                cand_type = cand.property_type
-                if not cand_type or cand_type == 'string':
-                    cand_type = cand.name
-                if cand_type == prop_type:
+                if self._qualia_key(cand) == prop_type:
                     inc_pn = cand
                     break
         if inc_pn is None:
@@ -784,10 +785,7 @@ class GraphMerger:
                 cand = graph.find_node_by_id(e.edge_target)
                 if not isinstance(cand, PropertyNode):
                     continue
-                cand_type = cand.property_type
-                if not cand_type or cand_type == 'string':
-                    cand_type = cand.name
-                if cand_type == prop_type:
+                if self._qualia_key(cand) == prop_type:
                     pn_to_remove = cand
                     break
         if pn_to_remove is None:
@@ -989,12 +987,26 @@ class GraphMerger:
             pn = graph.find_node_by_id(edge.edge_target)
             if not host_name or not isinstance(pn, PropertyNode):
                 continue
-            prop_type = pn.property_type
-            if not prop_type or prop_type == 'string':
-                prop_type = pn.name or 'definition'
-            out[(host_name, prop_type)] = pn
+            out[(host_name, self._qualia_key(pn))] = pn
         return out
 
+    @staticmethod
+    def _qualia_key(pn: PropertyNode) -> str:
+        """The quale a PropertyNode answers, as the maps key it: its
+        ``property_type`` (its name when the type is missing or the legacy
+        ``"string"``). A REPEATABLE quale (``alternative_label``: one
+        PropertyNode per label, A1 5 Oct 2026) is keyed with its value too —
+        two labels of one unit are two claims, so a label the table adds is
+        ``qualia_added`` and never a ``qualia_changed`` of the other one."""
+        prop_type = pn.property_type
+        if not prop_type or prop_type == 'string':
+            prop_type = pn.name or 'definition'
+        if prop_type in REPEATABLE_QUALIA:
+            value = " ".join(str(getattr(pn, "value", "") or "").split())
+            scheme = " ".join(str((getattr(pn, "data", None) or {}).get("scheme") or "").split())
+            return f"{prop_type}={value}" + (f" [{scheme}]" if scheme else "")
+        return prop_type
+
     @staticmethod
     def _pn_display_value(pn: PropertyNode) -> str:
         """Display value for a PropertyNode — falls back to

{s3dgraphy-1.6.0.dev36 → s3dgraphy-1.6.0.dev38/src/s3dgraphy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev36
+Version: 1.6.0.dev38
 Summary: 3D Stratigraphic Graph Management Library for archaeological and heritage applications
 Author-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
 Maintainer-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>

{s3dgraphy-1.6.0.dev36 → s3dgraphy-1.6.0.dev38}/src/s3dgraphy.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ src/s3dgraphy/editorial.py
 src/s3dgraphy/graph.py
 src/s3dgraphy/iiif.py
 src/s3dgraphy/indices.py
+src/s3dgraphy/labels.py
 src/s3dgraphy/language.py
 src/s3dgraphy/ownership.py
 src/s3dgraphy/project_tree.py
@@ -358,6 +359,7 @@ tests/test_acquisition.py
 tests/test_acquisition_fs.py
 tests/test_add_resource.py
 tests/test_ai_validation_nodes.py
+tests/test_alternative_labels.py
 tests/test_api_surface.py
 tests/test_asset_dtc_protocol.py
 tests/test_asset_versions.py