s3dgraphy 1.6.0.dev11__tar.gz → 1.6.0.dev13__tar.gz

{s3dgraphy-1.6.0.dev11 → s3dgraphy-1.6.0.dev13}/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.dev11/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev11
+Version: 1.6.0.dev13
 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,14 @@ 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: pdf
+Requires-Dist: pypdf>=4.0; extra == "pdf"
+Provides-Extra: docx
+Requires-Dist: python-docx>=1.1; extra == "docx"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -61,7 +69,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.dev11 → s3dgraphy-1.6.0.dev13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "s3dgraphy"
-version = "1.6.0.dev11"
+version = "1.6.0.dev13"
 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,52 @@ 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",
+]
+pdf = [
+    # Text extraction from PDF sources, for StratiMiner's Path A
+    # (api.source_text). Without it a PDF is listed by name and its text is not
+    # read — the honest degradation, not an error.
+    #
+    # pypdf and NOT PyMuPDF (E.D., 2026-08-03): PyMuPDF renders beautifully and
+    # weighs 21 MB, all of which the FROZEN em-bridge sidecar would carry in order
+    # to read some paragraphs. pypdf is ~350 KB, pure Python, no dependencies and
+    # no compiled extension — so it also installs next to Blender's interpreter
+    # without a build step. It reads the text LAYER; it does not do OCR, so a
+    # scanned PDF reports "no text layer" instead of returning an empty string
+    # that would read as an empty document.
+    "pypdf>=4.0",
+]
+docx = [
+    # .docx rendering of a baked narrative (BK1, api.export_narrative_docx).
+    # DocX is the format for the reader who will never see the graph — LaTeX
+    # serves the apparatus and Jupyter the analysis — so it is a first-class
+    # output, but not every consumer publishes: a Blender addon and the GraphML
+    # chain must not carry a Word writer.
+    #
+    # The PyPI package is `python-docx`; the import is `docx`. There is an
+    # unrelated `docx` on PyPI, which is why the MissingDependency message names
+    # both. Without the extra, api.bake_narrative still works — the bake is
+    # independent of every renderer — and only export_narrative_docx raises.
+    "python-docx>=1.1",
+]
 dev = [
     "pytest>=7.0",
     "pytest-cov",
@@ -125,7 +172,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 +195,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.dev13/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.dev13/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.dev13/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.dev11 → s3dgraphy-1.6.0.dev13}/src/s3dgraphy/JSON_config/em.ttl

@@ -447,9 +447,9 @@ em:hasVisualReference
     a owl:ObjectProperty ;
     rdfs:label "has visual reference"@en ;
     rdfs:subPropertyOf crm:P138i_has_representation ;
-    rdfs:domain em:Paradata ;
+    rdfs:domain em:Qualia ;
     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 .
+    rdfs:comment "A property (em:Qualia, an asserted quale) is visually illustrated or anchored by a VISUAL RESOURCE — the resource-layer image node (a LinkNode, E73 Information Object), not a source document. Revised 2026-08-05 (BUGFIX-CONN2): source narrowed to em:Qualia (was em:Paradata; only a property is illustrated), target moved from an E31 Document to the resource-layer image. The RDF exporter co-types the target LinkNode as E36_Visual_Item, which is range-consistent because E36 is a subclass of E73 (the LinkNode's base class). Distinct from em: extraction sourcing (P67/J7): a visual reference shows, an extraction source justifies. Maps to: connections_datamodel edge 'has_visual_reference' (source PropertyNode, target LinkNode)."@en .
 
 em:survivesInEpoch
     a owl:ObjectProperty ;

{s3dgraphy-1.6.0.dev11 → s3dgraphy-1.6.0.dev13}/src/s3dgraphy/JSON_config/em_qualia_types.json

@@ -1008,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",