s3dgraphy 1.6.0.dev10__tar.gz → 1.6.0.dev12__tar.gz

{s3dgraphy-1.6.0.dev10 → s3dgraphy-1.6.0.dev12}/MANIFEST.in

@@ -6,3 +6,4 @@ recursive-include src/s3dgraphy/JSON_config/src *
 recursive-include src/s3dgraphy/mappings *.json
 recursive-include src/s3dgraphy/data *
 recursive-include src/s3dgraphy/templates *
+recursive-include src/s3dgraphy/authorities/snapshots *

{s3dgraphy-1.6.0.dev10/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev10
+Version: 1.6.0.dev12
 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>
@@ -47,6 +47,10 @@ Provides-Extra: sync
 Requires-Dist: sqlalchemy>=2.0; extra == "sync"
 Provides-Extra: postgres
 Requires-Dist: psycopg2-binary>=2.9; extra == "postgres"
+Provides-Extra: minio
+Requires-Dist: minio>=7.0; extra == "minio"
+Provides-Extra: geo
+Requires-Dist: pyproj>=3.4; extra == "geo"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -61,7 +65,7 @@ Requires-Dist: sphinx>=5.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme; extra == "docs"
 Requires-Dist: myst-parser; extra == "docs"
 Provides-Extra: full
-Requires-Dist: s3dgraphy[rdf-embedded,sync,visualization]; extra == "full"
+Requires-Dist: s3dgraphy[geo,minio,rdf-embedded,sync,visualization]; extra == "full"
 Provides-Extra: all
 Requires-Dist: s3dgraphy[dev,docs,full,postgres]; extra == "all"
 Dynamic: license-file

{s3dgraphy-1.6.0.dev10 → s3dgraphy-1.6.0.dev12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "s3dgraphy"
-version = "1.6.0.dev10"
+version = "1.6.0.dev12"
 description = "3D Stratigraphic Graph Management Library for archaeological and heritage applications"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -81,7 +81,8 @@ rdf = [
 ]
 rdf-embedded = [
     # RDF export + embedded SPARQL store (no separate server required).
-    # Planned for s3dgraphy v1.6.3+ (SPARQL endpoint read/write workflow).
+    # Kept available for later (embedded read/write workflow); Phase 1 uses the
+    # TTL projection (→ Virtuoso later), so this extra is not pursued yet.
     "rdflib>=7.0",
     "pyoxigraph>=0.4",
 ]
@@ -106,6 +107,25 @@ postgres = [
     # the PG path of PyArchInitImporter when that lands.
     "psycopg2-binary>=2.9",
 ]
+minio = [
+    # MinIO / S3 object-storage backend for the Resource layer
+    # (s3dgraphy.resources.minio_backend, R2). Without this extra, constructing
+    # a client / ingesting raises MissingDependency (like rdflib for TTL);
+    # resolve()/manifest work dep-free on an already-populated index.
+    "minio>=7.0",
+]
+geo = [
+    # Coordinate reprojection for api.reproject / api.georeference_scene (G1).
+    # Excavation coordinates are normally PROJECTED (UTM, national grids) with
+    # an EPSG code, and a map needs WGS84: that conversion needs PROJ.
+    #
+    # pyproj and not GDAL on purpose: the pyproj wheels BUNDLE PROJ, so this
+    # extra installs with pip alone — no system binaries, no GDAL build. That
+    # is exactly the fragile pipe this avoids. Without the extra, reprojection
+    # raises MissingDependency (like rdflib for TTL) and every caller degrades:
+    # the library imports, the graph loads, only the conversion is unavailable.
+    "pyproj>=3.4",
+]
 dev = [
     "pytest>=7.0",
     "pytest-cov",
@@ -125,7 +145,7 @@ docs = [
 # without the dev/docs tooling. The dev/docs/test stacks stay separate
 # so CI-style installs don't pull editor/QA deps.
 full = [
-    "s3dgraphy[rdf-embedded,visualization,sync]",
+    "s3dgraphy[rdf-embedded,visualization,sync,minio,geo]",
 ]
 all = [
     "s3dgraphy[full,dev,docs,postgres]",
@@ -148,6 +168,11 @@ s3dgraphy = [
     "mappings/*",
     "mappings/*.json",
 ]
+# authorities snapshots (P1-D) are DATA files in a subpackage — ship them in the
+# wheel so the offline resolver works when installed (e.g. bundled into Blender).
+"s3dgraphy.authorities" = [
+    "snapshots/*",
+]
 
 [tool.black]
 line-length = 88

s3dgraphy-1.6.0.dev12/src/s3dgraphy/JSON_config/acquisition_descriptor.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://w3id.org/em/acquisition-descriptor/0",
+  "title": "AcquisitionDescriptor",
+  "description": "The versioned acquisition seam (design note §4): a stable JSON descriptor an acquisition front-end (OpenShelf, a museum API, the DosCo, a local FS scan) EMITS and s3Dgraphy CONSUMES. The canonical schema lives here in JSON_config; emitters depend only on the published schema, never on s3Dgraphy internals. Tier 0 (opaque source) = payload_graph ABSENT (no inherited genesis/interpretation). schema_version is the contract version.",
+  "type": "object",
+  "required": ["schema_version", "asset"],
+  "additionalProperties": true,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Contract version. This schema is v0; the major must match the consumer's SCHEMA_VERSION."
+    },
+    "asset": {
+      "type": "object",
+      "description": "The digital object being acquired. Exactly one locator (bytes_ref | url | local_path) identifies it; the resource layer (R0–R2) resolves it.",
+      "properties": {
+        "ref": {"type": "string", "description": "Locator: a local path, a file://, s3:// or http(s) URL. (Generic single-field form of bytes_ref|url|local_path.)"},
+        "media_type": {"type": "string", "description": "MIME type, e.g. image/jpeg, model/gltf-binary."},
+        "name": {"type": "string", "description": "Optional human label for the asset (e.g. the source record title)."}
+      }
+    },
+    "source": {
+      "type": "object",
+      "description": "The catalog/repo the asset came from + its capability flags.",
+      "properties": {
+        "repo_id": {"type": "string"},
+        "capabilities": {
+          "type": "array",
+          "items": {"type": "string", "enum": ["genesis", "interpretation"]},
+          "description": "What the source can provide beyond flat metadata. Tier 0 = [] (opaque)."
+        },
+        "record_id": {"type": "string"},
+        "record_url": {"type": "string"}
+      }
+    },
+    "rights": {
+      "type": "object",
+      "description": "Literal-first rights (design §7): license + optional holder/url captured as provenance literals; ODRL/HDTO formalization deferred.",
+      "properties": {
+        "license": {"type": "string"},
+        "holder": {"type": "string"},
+        "url": {"type": "string"}
+      }
+    },
+    "acquisition": {
+      "type": "object",
+      "description": "The acquisition event itself (retrieval): when, by which tool, how. Modelled as a distinct DTC event (crmdig:D12_Data_Transfer_Event).",
+      "properties": {
+        "retrieved_at": {"type": "string", "description": "ISO-8601 timestamp of retrieval."},
+        "agent": {"type": "string", "description": "The acquiring tool as '<tool>@<version>'."},
+        "method": {"type": "string", "description": "Acquisition method — maps to the DTC 'acquisition' kind (download / ingest / local_import) when recognized."}
+      }
+    },
+    "attribution": {
+      "type": "object",
+      "description": "Present when the payload carries interpretation (Tier 2): who asserts the imported study. Absent in Tier 0.",
+      "properties": {
+        "study_id": {"type": "string"},
+        "author": {"type": "string"},
+        "of_record_ref": {"type": "string"}
+      }
+    },
+    "payload_graph": {
+      "type": "object",
+      "description": "Inherited sub-graph (Tier 1 genesis / Tier 2 interpretation). ABSENT in Tier 0. Node-type-agnostic; scope declares what it carries. Consumed by a later session — not by the Tier-0 hook.",
+      "properties": {
+        "scope": {"type": "string", "enum": ["genesis", "interpretation", "full_study"]},
+        "subgraph": {"description": "Inline nodes+edges (UUID-keyed) — materialize."},
+        "ref_url": {"type": "string", "description": "Lazy reference to the source graph — reference."},
+        "resources": {"type": "array", "description": "Transitive resources referenced by the payload."}
+      }
+    }
+  }
+}

s3dgraphy-1.6.0.dev12/src/s3dgraphy/JSON_config/acquisition_mappings/ercolano.json

@@ -0,0 +1,24 @@
+{
+  "mapping_version": "0",
+  "source": "ercolano",
+  "tier": 0,
+  "_comment": "Per-source acquisition mapping (design decision E.D. 2026-07-30): translate a raw ERCOLANO record into an AcquisitionDescriptor, the way the xlsx-import mappings translate spreadsheet rows. Ercolano is a Tier-0 OPAQUE repo (flat metadata, no genesis/interpretation) → source.capabilities = [] and no payload_graph. Add a sibling <repo>.json for each future source; the generic loader (s3dgraphy.acquisition.mapping.apply_mapping) applies any of them. 'descriptor_defaults' are the constants for this source; 'field_map' maps a dotted descriptor path <- a key in the raw record (record value wins when present).",
+  "descriptor_defaults": {
+    "schema_version": "0",
+    "source": {"repo_id": "ercolano", "capabilities": []},
+    "acquisition": {"agent": "openshelf@0", "method": "download"},
+    "rights": {"license": "unknown"}
+  },
+  "field_map": {
+    "asset.ref": "url",
+    "asset.media_type": "media_type",
+    "asset.name": "title",
+    "source.record_id": "record_id",
+    "source.record_url": "record_url",
+    "rights.license": "license",
+    "rights.holder": "rights_holder",
+    "rights.url": "rights_url",
+    "acquisition.retrieved_at": "retrieved_at",
+    "acquisition.method": "method"
+  }
+}

s3dgraphy-1.6.0.dev12/src/s3dgraphy/JSON_config/acquisition_mappings/fs.json

@@ -0,0 +1,20 @@
+{
+  "mapping_version": "0",
+  "source": "fs",
+  "tier": 0,
+  "_comment": "Per-source acquisition mapping for the LOCAL FILE SYSTEM (project-folder search) — the local analog of a remote Tier-0 repo (design §3: 'same shape, source = the disk'). Opaque Tier 0 → source.capabilities = [] and no payload_graph. Build the raw record with s3dgraphy.acquisition.fs_record(path) (filename/path/size/ext/media_type/record_id/record_url), then apply_mapping('fs', record). Mirrors ercolano.json; the generic loader applies either. The UI reflects exactly these mapping fields (name/media_type/size/…) per E.D.",
+  "descriptor_defaults": {
+    "schema_version": "0",
+    "source": {"repo_id": "filesystem", "capabilities": []},
+    "acquisition": {"agent": "emtools-shelf@0", "method": "local_import"},
+    "rights": {"license": "unknown"}
+  },
+  "field_map": {
+    "asset.ref": "path",
+    "asset.name": "filename",
+    "asset.media_type": "media_type",
+    "asset.size": "size",
+    "source.record_id": "record_id",
+    "source.record_url": "record_url"
+  }
+}

{s3dgraphy-1.6.0.dev10 → s3dgraphy-1.6.0.dev12}/src/s3dgraphy/JSON_config/em.ttl

@@ -199,8 +199,8 @@ em:SeriesOfNonStructuralVirtualSU
 em:StratigraphicEvent
     a owl:Class ;
     rdfs:label "Stratigraphic Event (SE)"@en ;
-    rdfs:subClassOf crm:E5_Event ;
-    rdfs:comment "An event that creates, modifies, or destroys a stratigraphic unit (e.g. an earthquake causing a plaster collapse, an act of demolition). More general than crmarchaeo:A4 (Genesis: formation only) or A5 (Modification only): the EM concept spans formation, modification and destruction. May be enriched by a 3D simulation (em:RepresentationModel) of the event itself. Maps to: Python StratigraphicEventNode (node_type='SE')."@en .
+    rdfs:subClassOf crmarchaeo:A5_Stratigraphic_Modification ;
+    rdfs:comment "An event that creates, modifies, or destroys a stratigraphic unit (e.g. an earthquake causing a plaster collapse, an act of demolition). Re-anchored 2026-07-11 from generic crm:E5_Event to crmarchaeo:A5_Stratigraphic_Modification: formation is A4 (subclass of A5), modification is A5, destruction is A5-as-disturbance (AP8) plus A4 genesis of the resulting A3 interface; E5 remains reachable transitively via A5 < S18 < E5. Cf. Guillem et al. 2024 (SWODCH). May be enriched by a 3D simulation (em:RepresentationModel) of the event itself. Maps to: Python StratigraphicEventNode (node_type='SE')."@en .
 
 em:TransformationSU
     a owl:Class ;
@@ -438,5 +438,42 @@ em:physicallyEquals
 
 
 # ============================================================================
-# End of em.ttl v1.6.0
+# v1.6.1 additions (2026-07-10) — serialisation-completeness pass
+# (WP3 coverage analysis, sections 10 / B.1 / B.2). New edge subproperties;
+# no class changes.
+# ============================================================================
+
+em:hasVisualReference
+    a owl:ObjectProperty ;
+    rdfs:label "has visual reference"@en ;
+    rdfs:subPropertyOf crm:P138i_has_representation ;
+    rdfs:domain em:Paradata ;
+    rdfs:range crm:E36_Visual_Item ;
+    rdfs:comment "The paradata node (property / extractor / combiner) is visually illustrated or anchored by a visual document (plate, photograph, annotated image). Distinct from em: extraction sourcing (P67/J7): a visual reference shows, an extraction source justifies. The RDF exporter co-types the target document as E36_Visual_Item. Maps to: connections_datamodel edge 'has_visual_reference'."@en .
+
+em:survivesInEpoch
+    a owl:ObjectProperty ;
+    rdfs:subPropertyOf crm:P132_spatiotemporally_overlaps_with ;
+    rdfs:label "survives in epoch"@en ;
+    rdfs:domain crmarchaeo:A8_Stratigraphic_Unit ;
+    rdfs:range crm:E4_Period ;
+    rdfs:comment "The unit's spacetime volume (via P196_defines) overlaps the epoch's: survival through (part of) an epoch is overlap, not containment. Epoch attribution is an interpretive act; its justification travels in the epoch's and edge's paradata chain. Maps to: connections_datamodel edge 'survive_in_epoch'."@en .
+
+em:firstAttestedInEpoch
+    a owl:ObjectProperty ;
+    rdfs:subPropertyOf crm:P10_falls_within ;
+    rdfs:label "first attested in epoch"@en ;
+    rdfs:domain crmarchaeo:A8_Stratigraphic_Unit ;
+    rdfs:range crm:E4_Period ;
+    rdfs:comment "Documented shortcut: the unit was brought into existence (P92i, genesis event / SE node) during the epoch (event P10_falls_within epoch; crmarchaeo:AP25_occurs_during where an SE node is present). Declared subPropertyOf P10 on the unit's defining spacetime volume (P196). Maps to: connections_datamodel edge 'has_first_epoch'."@en .
+
+em:hasAuthor
+    a owl:ObjectProperty ;
+    rdfs:subPropertyOf prov:wasAttributedTo ;
+    rdfs:label "has author"@en ;
+    rdfs:range em:Author ;
+    rdfs:comment "Domain-neutral authorship attribution (any graph entity to a human or AI author). Replaces the earlier P94_has_created reading (invalid domain/range for physical units) and L10_had_input (digital machine events, not authorship). Maps to: connections_datamodel edge 'has_author'."@en .
+
+# ============================================================================
+# End of em.ttl v1.6.1
 # ============================================================================

{s3dgraphy-1.6.0.dev10 → s3dgraphy-1.6.0.dev12}/src/s3dgraphy/JSON_config/em_qualia_types.json

@@ -1,10 +1,10 @@
 {
     "metadata": {
-      "version": "4.1",
-      "last_updated": "2026-06-18",
+      "version": "1.6.0",
+      "last_updated": "2026-07-15",
       "maintainers": ["Emanuel Demetrescu"],
       "license": "CC-BY-4.0",
-      "changelog": "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.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": [
       {
@@ -571,7 +571,9 @@
                   "cidoc_crm": "E52_Time-Span"
                 },
                 "data_type": "date",
-                "format": "YYYY-MM-DD"
+                "format": "YYYY-MM-DD",
+                "rationale": "The earliest calendar date at which the element's time-span begins (the begin-of-the-begin). Anchors an epoch or unit on the absolute timeline; pair it with Absolute Time — End to bound the span. Negative years = BCE.",
+                "example": "-27 — start of the Augustan phase of the sanctuary (27 BCE)."
               },
               {
                 "id": "absolute_time_end",
@@ -581,7 +583,9 @@
                   "cidoc_crm": "E52_Time-Span"
                 },
                 "data_type": "date",
-                "format": "YYYY-MM-DD"
+                "format": "YYYY-MM-DD",
+                "rationale": "The latest calendar date at which the element's time-span ends (the end-of-the-end). Together with the start it delimits the absolute chronology of an epoch or unit. Negative years = BCE.",
+                "example": "476 — end of the Late Antique phase (fall of the Western Roman Empire)."
               },
               {
                 "id": "dating_method",
@@ -601,7 +605,9 @@
                   "historical_sources",
                   "stylistic_analysis"
                 ],
-                "expected_extractors": ["dating_analysis", "laboratory_analysis"]
+                "expected_extractors": ["dating_analysis", "laboratory_analysis"],
+                "rationale": "How the chronology was established — records the reliability and paradata behind a date so the reasoning can be judged.",
+                "example": "c14 for a hearth dated by radiocarbon; stratigraphy for a wall dated by its position in the sequence."
               },
               {
                 "id": "duration",
@@ -1002,6 +1008,13 @@
         "subcategories": {
           "administrative": {
             "name": "Administrative Qualia",
+            "description": "TODO E.D. — proposal 1, to confirm or replace: Legal, inventory and curatorial record of the element",
+            "_description_proposals": [
+              "Legal, inventory and curatorial record of the element",
+              "Legal status, inventory identity and curatorial history of the element. The record a holding institution keeps, as distinct from ownership, which is the chain of who has held it.",
+              "Legal and inventory record keeping"
+            ],
+            "_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": "inventory_number",
@@ -1151,9 +1164,9 @@
               {
                 "id": "confidence_level",
                 "name": "Confidence Level",
-                "description": "Numerical confidence in the assertion (0-100%). The EM-canonical scalar for paradata-supported claims.",
+                "description": "Numerical confidence in the assertion (0-100%). The EM-canonical scalar for paradata-supported claims. CRM mapping changed 2026-07-10: was E54_Dimension; a confidence is the value a belief is held with, i.e. crminf:I6_Belief_Value (see WP3 coverage analysis G5 / Appendix C). The RDF exporter's qualia-precedence rule types the PropertyNode accordingly.",
                 "mappings": {
-                  "cidoc_crm": "E54_Dimension"
+                  "cidoc_crm": "crminf:I6_Belief_Value"
                 },
                 "data_type": "percentage",
                 "range": [0, 100],