s3dgraphy 1.6.0.dev12__tar.gz → 1.6.0.dev14__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev12
+Version: 1.6.0.dev14
 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>
@@ -51,6 +51,10 @@ 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"
@@ -258,26 +262,67 @@ match exactly and case-sensitively. The same flow applies to
 - **[Examples](https://github.com/zalmoxes-laran/s3dgraphy/tree/main/examples)** - Code examples and tutorials
 - **[Extended Matrix](https://www.extendedmatrix.org)** - Framework overview
 
+## Where this sits
+
+s3Dgraphy is the **language** of the StratiGraph ecosystem, and its only
+authority on meaning: it defines the `em.json` format, merges two versions of a
+study, and produces every projection (RDF/CIDOC-CRM, GraphML, IIIF, the Heriverse
+payload, LaTeX/DOCX). Everything else — the editor, the Blender addon, the
+services — speaks through it and does not re-derive it.
+
+The rule the other repos inherit, in one line: *if an endpoint needs to compute
+something about a graph, that something belongs here.* This library has no web
+framework and no socket on purpose — what it does can be proved on a table.
+
+**The whole map:** [`ARCHITECTURE-SYSTEM.md`](../em-server/docs/ARCHITECTURE-SYSTEM.md).
+
+---
+
 ## 🔧 Development
 
 ### Setting up Development Environment
 
 ```bash
-# Clone the repository
 git clone https://github.com/zalmoxes-laran/s3dgraphy.git
 cd s3dgraphy
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
 
-# Install in development mode
-pip install -e .[dev]
+Run the tests — from the repo root, with `src/` on the path:
 
-# Run tests
-pytest
+```bash
+PYTHONPATH=src .venv/bin/python -m pytest tests -q
+```
+
+> **About the failures you will see.** The suite is **~1250 passing and 25
+> failing**, and those 25 are a *known baseline*, not a broken checkout: they are
+> long-standing round-trip gaps, tracked separately. What matters when you change
+> something is that **the LIST does not change** — compare the names, not the
+> count:
+>
+> ```bash
+> PYTHONPATH=src .venv/bin/python -m pytest tests -q 2>&1 | grep '^FAILED' | sort > /tmp/after.txt
+> diff /tmp/baseline.txt /tmp/after.txt
+> ```
+>
+> A new name in that diff is your regression; the same 25 names are the weather.
+
+### The CLI — the fastest way to see what the library does
 
-# Run linting
-black src/
-flake8 src/
+Every operation on the access surface is also a subcommand, with no web
+dependency. Given any `.em.json`:
+
+```bash
+PYTHONPATH=src .venv/bin/python -m s3dgraphy.api open      study.em.json   # {"nodes": 3, "edges": 1}
+PYTHONPATH=src .venv/bin/python -m s3dgraphy.api validate  study.em.json   # {"ok": true, …}
+PYTHONPATH=src .venv/bin/python -m s3dgraphy.api project-ttl study.em.json # Turtle on stdout
+PYTHONPATH=src .venv/bin/python -m s3dgraphy.api graphml   study.em.json   # GraphML for yEd
 ```
 
+`--help` lists the rest (GraphML import and conversion, narrative export to
+LaTeX/DOCX, authority resolution, the resource shelf, acquisition).
+
 ### Release Process
 
 ```bash
@@ -292,7 +337,10 @@ git push --follow-tags
 
 ## 🤝 Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+We welcome contributions. Open an issue or a pull request on
+[GitHub](https://github.com/zalmoxes-laran/s3dgraphy) — and see the
+[Development](#-development) section above for how to run the suite and read its
+known baseline.
 
 ### Areas for Contribution
 - **New Node Types**: Archaeological contexts, dating methods

{s3dgraphy-1.6.0.dev12 → s3dgraphy-1.6.0.dev14}/README.md

@@ -186,26 +186,67 @@ match exactly and case-sensitively. The same flow applies to
 - **[Examples](https://github.com/zalmoxes-laran/s3dgraphy/tree/main/examples)** - Code examples and tutorials
 - **[Extended Matrix](https://www.extendedmatrix.org)** - Framework overview
 
+## Where this sits
+
+s3Dgraphy is the **language** of the StratiGraph ecosystem, and its only
+authority on meaning: it defines the `em.json` format, merges two versions of a
+study, and produces every projection (RDF/CIDOC-CRM, GraphML, IIIF, the Heriverse
+payload, LaTeX/DOCX). Everything else — the editor, the Blender addon, the
+services — speaks through it and does not re-derive it.
+
+The rule the other repos inherit, in one line: *if an endpoint needs to compute
+something about a graph, that something belongs here.* This library has no web
+framework and no socket on purpose — what it does can be proved on a table.
+
+**The whole map:** [`ARCHITECTURE-SYSTEM.md`](../em-server/docs/ARCHITECTURE-SYSTEM.md).
+
+---
+
 ## 🔧 Development
 
 ### Setting up Development Environment
 
 ```bash
-# Clone the repository
 git clone https://github.com/zalmoxes-laran/s3dgraphy.git
 cd s3dgraphy
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
 
-# Install in development mode
-pip install -e .[dev]
+Run the tests — from the repo root, with `src/` on the path:
 
-# Run tests
-pytest
+```bash
+PYTHONPATH=src .venv/bin/python -m pytest tests -q
+```
+
+> **About the failures you will see.** The suite is **~1250 passing and 25
+> failing**, and those 25 are a *known baseline*, not a broken checkout: they are
+> long-standing round-trip gaps, tracked separately. What matters when you change
+> something is that **the LIST does not change** — compare the names, not the
+> count:
+>
+> ```bash
+> PYTHONPATH=src .venv/bin/python -m pytest tests -q 2>&1 | grep '^FAILED' | sort > /tmp/after.txt
+> diff /tmp/baseline.txt /tmp/after.txt
+> ```
+>
+> A new name in that diff is your regression; the same 25 names are the weather.
+
+### The CLI — the fastest way to see what the library does
 
-# Run linting
-black src/
-flake8 src/
+Every operation on the access surface is also a subcommand, with no web
+dependency. Given any `.em.json`:
+
+```bash
+PYTHONPATH=src .venv/bin/python -m s3dgraphy.api open      study.em.json   # {"nodes": 3, "edges": 1}
+PYTHONPATH=src .venv/bin/python -m s3dgraphy.api validate  study.em.json   # {"ok": true, …}
+PYTHONPATH=src .venv/bin/python -m s3dgraphy.api project-ttl study.em.json # Turtle on stdout
+PYTHONPATH=src .venv/bin/python -m s3dgraphy.api graphml   study.em.json   # GraphML for yEd
 ```
 
+`--help` lists the rest (GraphML import and conversion, narrative export to
+LaTeX/DOCX, authority resolution, the resource shelf, acquisition).
+
 ### Release Process
 
 ```bash
@@ -220,7 +261,10 @@ git push --follow-tags
 
 ## 🤝 Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+We welcome contributions. Open an issue or a pull request on
+[GitHub](https://github.com/zalmoxes-laran/s3dgraphy) — and see the
+[Development](#-development) section above for how to run the suite and read its
+known baseline.
 
 ### Areas for Contribution
 - **New Node Types**: Archaeological contexts, dating methods

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "s3dgraphy"
-version = "1.6.0.dev12"
+version = "1.6.0.dev14"
 description = "3D Stratigraphic Graph Management Library for archaeological and heritage applications"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -126,6 +126,33 @@ geo = [
     # 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",