evoontology-explorer 0.1.0__tar.gz

evoontology_explorer-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+.env
+.env.*
+*.log
+/workspace/
+/workspace*/
+visualizations/
+.evoontology/
+node_modules/

evoontology_explorer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukasz Wardzala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

evoontology_explorer-0.1.0/NOTICE

@@ -0,0 +1,11 @@
+evoontology-explorer
+
+This project is derived from the visualization of EvoOntology
+(https://github.com/ruc-datalab/EvoOntology), Copyright (c) 2026 Meiduo Chong,
+MIT License: the explorer page (markup, styles, interaction and layout code),
+the graph element builders and the experience report builder were ported from
+it and modified to load data on demand from a server.
+
+It bundles Cytoscape.js 3.30.2 (https://js.cytoscape.org),
+Copyright (c) 2016-2024, The Cytoscape Consortium, MIT License, as
+src/evoontology_explorer/static/cytoscape.min.js.

evoontology_explorer-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: evoontology-explorer
+Version: 0.1.0
+Summary: Server-backed explorer for EvoOntology workspaces: the ontology layer explorer page, loading versions, terms and evidence on demand.
+Project-URL: Homepage, https://github.com/lwardzala/evoontology-explorer
+Project-URL: Repository, https://github.com/lwardzala/evoontology-explorer
+Project-URL: Issues, https://github.com/lwardzala/evoontology-explorer/issues
+Author: Lukasz Wardzala
+License: MIT License
+        
+        Copyright (c) 2026 Lukasz Wardzala
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+License-File: NOTICE
+Keywords: cytoscape,evoontology,fastapi,ontology,visualization
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: databricks
+Requires-Dist: databricks-sdk>=0.40; extra == 'databricks'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == 's3'
+Description-Content-Type: text/markdown
+
+# evoontology-explorer
+
+A server-backed explorer for [EvoOntology](https://github.com/ruc-datalab/EvoOntology) workspaces. It serves the same *Ontology Layer Explorer* page as the EvoOntology plugin, with the same Cytoscape graph, panels and version comparison, but the browser loads only what it shows: the term layer of one version first, a term's mappings, constraints and evidence when that term is expanded, details on click, search and version diffs from the server. Switching versions releases the previous one. Workspaces with many versions or large graphs stay usable where the single-file page would not.
+
+## Install
+
+```bash
+pip install evoontology-explorer                # local directories
+pip install "evoontology-explorer[databricks]"  # Unity Catalog volumes
+pip install "evoontology-explorer[s3]"          # S3 prefixes
+```
+
+## Run
+
+```bash
+evoontology-explorer --workspace ./workspace --port 8000
+evoontology-explorer --workspace /Volumes/<catalog>/<schema>/<volume>/code
+evoontology-explorer --workspace s3://my-bucket/ontology/code
+```
+
+The workspace is the EvoOntology directory that holds `active.json` and `versions/<version>/` (usually a project's `.evoontology/`). Environment variables replace the flags: `EVOONTOLOGY_WORKSPACE`, `EVOONTOLOGY_TITLE` (the page title), `DATABRICKS_APP_PORT` or `PORT`.
+
+Credentials come from the usual places: AWS SDK credentials for S3, Databricks SDK unified authentication for volumes (inside a Databricks App the app's own principal is used; it needs `READ VOLUME` on the volume and `USE SCHEMA` and `USE CATALOG` above it).
+
+## Deploy as a Databricks App
+
+```yaml
+# app.yaml
+command: ["python", "-m", "evoontology_explorer"]
+env:
+  - name: EVOONTOLOGY_WORKSPACE
+    value: /Volumes/<catalog>/<schema>/<volume>/code
+```
+
+```text
+# requirements.txt
+evoontology-explorer[databricks]==0.1.0
+```
+
+Databricks Apps sign viewers in and admit the principals with `CAN_USE` on the app.
+
+## API
+
+All responses are JSON. Versions are addressed by name.
+
+| Route | Returns |
+|---|---|
+| `GET /api/workspace` | title, active version, versions with their kind (`published` for `MAJOR.MINOR.PATCH`, otherwise `candidate`) |
+| `GET /api/versions/{v}` | counts, warnings, term and satellite counts |
+| `GET /api/versions/{v}/graph` | the term layer: term nodes and relation edges |
+| `GET /api/versions/{v}/terms/{id}/satellites` | one term's mappings, constraints and evidence with their reference edges |
+| `GET /api/versions/{v}/satellites` | every satellite of the version |
+| `GET /api/versions/{v}/elements/{id}` | the detail rows of a node or edge, with links to the records it names |
+| `GET /api/versions/{v}/search?q=` | nodes matching a substring |
+| `GET /api/schema`, `GET /api/versions/{v}/tools`, `GET /api/versions/{v}/experience` | the Schema, Tool and Results views |
+| `GET /api/compare?left=&right=` | added, removed and changed records between two versions |
+| `GET /health` | `ok` |
+
+Node ids are `<family>:<record id>`; relation edges are `rel:<record id>`.
+
+## Library use
+
+```python
+from evoontology_explorer import create_app, open_workspace
+
+app = create_app(open_workspace("./workspace"), title="My ontology")
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+The tests run on a synthetic workspace under `tests/fixtures`. `tests/test_no_private_data.py` fails the build when the tree contains anything that looks like a private deployment (email addresses, account ids, bucket or volume paths, hostnames, tokens); keep examples to the placeholders above.
+
+## Licence
+
+MIT. See `NOTICE` for the EvoOntology and Cytoscape.js attributions.

evoontology_explorer-0.1.0/README.md

@@ -0,0 +1,80 @@
+# evoontology-explorer
+
+A server-backed explorer for [EvoOntology](https://github.com/ruc-datalab/EvoOntology) workspaces. It serves the same *Ontology Layer Explorer* page as the EvoOntology plugin, with the same Cytoscape graph, panels and version comparison, but the browser loads only what it shows: the term layer of one version first, a term's mappings, constraints and evidence when that term is expanded, details on click, search and version diffs from the server. Switching versions releases the previous one. Workspaces with many versions or large graphs stay usable where the single-file page would not.
+
+## Install
+
+```bash
+pip install evoontology-explorer                # local directories
+pip install "evoontology-explorer[databricks]"  # Unity Catalog volumes
+pip install "evoontology-explorer[s3]"          # S3 prefixes
+```
+
+## Run
+
+```bash
+evoontology-explorer --workspace ./workspace --port 8000
+evoontology-explorer --workspace /Volumes/<catalog>/<schema>/<volume>/code
+evoontology-explorer --workspace s3://my-bucket/ontology/code
+```
+
+The workspace is the EvoOntology directory that holds `active.json` and `versions/<version>/` (usually a project's `.evoontology/`). Environment variables replace the flags: `EVOONTOLOGY_WORKSPACE`, `EVOONTOLOGY_TITLE` (the page title), `DATABRICKS_APP_PORT` or `PORT`.
+
+Credentials come from the usual places: AWS SDK credentials for S3, Databricks SDK unified authentication for volumes (inside a Databricks App the app's own principal is used; it needs `READ VOLUME` on the volume and `USE SCHEMA` and `USE CATALOG` above it).
+
+## Deploy as a Databricks App
+
+```yaml
+# app.yaml
+command: ["python", "-m", "evoontology_explorer"]
+env:
+  - name: EVOONTOLOGY_WORKSPACE
+    value: /Volumes/<catalog>/<schema>/<volume>/code
+```
+
+```text
+# requirements.txt
+evoontology-explorer[databricks]==0.1.0
+```
+
+Databricks Apps sign viewers in and admit the principals with `CAN_USE` on the app.
+
+## API
+
+All responses are JSON. Versions are addressed by name.
+
+| Route | Returns |
+|---|---|
+| `GET /api/workspace` | title, active version, versions with their kind (`published` for `MAJOR.MINOR.PATCH`, otherwise `candidate`) |
+| `GET /api/versions/{v}` | counts, warnings, term and satellite counts |
+| `GET /api/versions/{v}/graph` | the term layer: term nodes and relation edges |
+| `GET /api/versions/{v}/terms/{id}/satellites` | one term's mappings, constraints and evidence with their reference edges |
+| `GET /api/versions/{v}/satellites` | every satellite of the version |
+| `GET /api/versions/{v}/elements/{id}` | the detail rows of a node or edge, with links to the records it names |
+| `GET /api/versions/{v}/search?q=` | nodes matching a substring |
+| `GET /api/schema`, `GET /api/versions/{v}/tools`, `GET /api/versions/{v}/experience` | the Schema, Tool and Results views |
+| `GET /api/compare?left=&right=` | added, removed and changed records between two versions |
+| `GET /health` | `ok` |
+
+Node ids are `<family>:<record id>`; relation edges are `rel:<record id>`.
+
+## Library use
+
+```python
+from evoontology_explorer import create_app, open_workspace
+
+app = create_app(open_workspace("./workspace"), title="My ontology")
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+The tests run on a synthetic workspace under `tests/fixtures`. `tests/test_no_private_data.py` fails the build when the tree contains anything that looks like a private deployment (email addresses, account ids, bucket or volume paths, hostnames, tokens); keep examples to the placeholders above.
+
+## Licence
+
+MIT. See `NOTICE` for the EvoOntology and Cytoscape.js attributions.

evoontology_explorer-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "evoontology-explorer"
+version = "0.1.0"
+description = "Server-backed explorer for EvoOntology workspaces: the ontology layer explorer page, loading versions, terms and evidence on demand."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Lukasz Wardzala" }]
+requires-python = ">=3.11"
+keywords = ["ontology", "evoontology", "visualization", "cytoscape", "fastapi"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Framework :: FastAPI",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = [
+    "fastapi>=0.115,<1",
+    "uvicorn>=0.30",
+]
+
+[project.optional-dependencies]
+databricks = ["databricks-sdk>=0.40"]
+s3 = ["boto3>=1.34"]
+dev = ["pytest>=8", "httpx>=0.27"]
+
+[project.scripts]
+evoontology-explorer = "evoontology_explorer.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/lwardzala/evoontology-explorer"
+Repository = "https://github.com/lwardzala/evoontology-explorer"
+Issues = "https://github.com/lwardzala/evoontology-explorer/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/evoontology_explorer"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "NOTICE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

evoontology_explorer-0.1.0/src/evoontology_explorer/__init__.py

@@ -0,0 +1,14 @@
+"""Server-backed explorer for EvoOntology workspaces."""
+
+from .api import create_app
+from .workspace import DatabricksVolumeWorkspace, LocalWorkspace, S3Workspace, Workspace, open_workspace
+
+__all__ = [
+    "create_app",
+    "open_workspace",
+    "Workspace",
+    "LocalWorkspace",
+    "DatabricksVolumeWorkspace",
+    "S3Workspace",
+]
+__version__ = "0.1.0"

evoontology_explorer-0.1.0/src/evoontology_explorer/__main__.py

@@ -0,0 +1,35 @@
+"""Command line: serve a workspace."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from .api import create_app
+from .workspace import open_workspace
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="evoontology-explorer", description=__doc__)
+    parser.add_argument("--workspace", default=os.environ.get("EVOONTOLOGY_WORKSPACE"),
+                        help="a directory, a /Volumes/... path or an s3:// URI holding active.json and versions/ "
+                             "(default: $EVOONTOLOGY_WORKSPACE)")
+    parser.add_argument("--title", default=os.environ.get("EVOONTOLOGY_TITLE", "Ontology Layer Explorer"))
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--port", type=int,
+                        default=int(os.environ.get("DATABRICKS_APP_PORT") or os.environ.get("PORT") or 8000))
+    parser.add_argument("--max-graphs", type=int, default=4, help="versions kept built in memory")
+    args = parser.parse_args(argv)
+    if not args.workspace:
+        parser.error("--workspace or EVOONTOLOGY_WORKSPACE is required")
+    import uvicorn
+
+    app = create_app(open_workspace(args.workspace), title=args.title, max_graphs=args.max_graphs)
+    print(f"serving {args.workspace} on http://{args.host}:{args.port}", flush=True)
+    uvicorn.run(app, host=args.host, port=args.port, log_level="info")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

evoontology_explorer-0.1.0/src/evoontology_explorer/api.py

@@ -0,0 +1,100 @@
+"""The HTTP API and the page."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import FileResponse, PlainTextResponse
+from fastapi.staticfiles import StaticFiles
+
+from .cache import Catalog
+from .diff import compare
+from .schema import schema_view
+from .tools import tool_view
+from .workspace import Workspace, WorkspaceError
+
+STATIC = Path(__file__).resolve().parent / "static"
+NO_STORE = {"Cache-Control": "no-store"}
+
+
+def create_app(workspace: Workspace, title: str = "Ontology Layer Explorer", max_graphs: int = 4,
+               warm: bool = True) -> FastAPI:
+    catalog = Catalog(workspace, title=title, max_graphs=max_graphs)
+    app = FastAPI(title=title, docs_url=None, redoc_url=None, openapi_url=None)
+    app.state.catalog = catalog
+    app.mount("/static", StaticFiles(directory=str(STATIC)), name="static")
+
+    def graph_of(version: str):
+        try:
+            return catalog.graph(version)
+        except KeyError:
+            raise HTTPException(404, f"unknown version {version!r}")
+        except WorkspaceError as exc:
+            raise HTTPException(503, str(exc))
+
+    @app.get("/health", response_class=PlainTextResponse)
+    def health():
+        return "ok"
+
+    @app.get("/")
+    def index():
+        return FileResponse(STATIC / "index.html", media_type="text/html; charset=utf-8", headers=NO_STORE)
+
+    @app.get("/api/workspace")
+    def workspace_view():
+        return catalog.workspace_view()
+
+    @app.get("/api/schema")
+    def schema():
+        return schema_view()
+
+    @app.get("/api/compare")
+    def compare_versions(left: str = Query(...), right: str = Query(...)):
+        return compare(graph_of(left), graph_of(right))
+
+    @app.get("/api/versions/{version}")
+    def version_summary(version: str):
+        return graph_of(version).summary(active=version == catalog.active())
+
+    @app.get("/api/versions/{version}/graph")
+    def term_layer(version: str):
+        return graph_of(version).term_layer()
+
+    @app.get("/api/versions/{version}/satellites")
+    def all_satellites(version: str):
+        return graph_of(version).all_satellites()
+
+    @app.get("/api/versions/{version}/terms/{term_id}/satellites")
+    def term_satellites(version: str, term_id: str):
+        try:
+            return graph_of(version).satellites_for(term_id)
+        except KeyError:
+            raise HTTPException(404, f"unknown term {term_id!r}")
+
+    @app.get("/api/versions/{version}/elements/{element_id:path}")
+    def element(version: str, element_id: str):
+        try:
+            return graph_of(version).element(element_id)
+        except KeyError:
+            raise HTTPException(404, f"unknown element {element_id!r}")
+
+    @app.get("/api/versions/{version}/search")
+    def search(version: str, q: str = Query(""), limit: int = Query(12, ge=1, le=50)):
+        return graph_of(version).search(q, limit)
+
+    @app.get("/api/versions/{version}/tools")
+    def tools(version: str):
+        return tool_view(graph_of(version))
+
+    @app.get("/api/versions/{version}/experience")
+    def experience(version: str):
+        graph_of(version)
+        try:
+            return catalog.experience(version)
+        except ValueError:
+            raise HTTPException(404, f"unknown version {version!r}")
+
+    if warm:
+        catalog.warm()
+    return app

evoontology_explorer-0.1.0/src/evoontology_explorer/cache.py

@@ -0,0 +1,130 @@
+"""The versions of one workspace: a bounded cache of built graphs, and pointers re-read at most once a minute."""
+
+from __future__ import annotations
+
+import re
+import threading
+import time
+from collections import OrderedDict
+from datetime import datetime, timezone
+
+from .experience import ExperienceBuilder
+from .graph import VersionGraph
+from .workspace import Workspace, active_version, list_versions, version_records
+
+POINTER_TTL = 60.0
+SEMVER = re.compile(r"^(\d+)\.(\d+)\.(\d+)(?:-c(\d+))?$")
+
+
+def version_kind(name: str) -> str:
+    match = SEMVER.match(name)
+    return "published" if match and match.group(4) is None else "candidate"
+
+
+def version_key(name: str) -> tuple:
+    match = SEMVER.match(name)
+    if match:
+        major, minor, patch, candidate = match.groups()
+        return (0, -int(major), -int(minor), -int(patch), 1 if candidate else 0, -int(candidate or 0), name)
+    return (1, 0, 0, 0, 0, 0, name)
+
+
+class Catalog:
+    def __init__(self, workspace: Workspace, title: str = "Ontology Layer Explorer", max_graphs: int = 4,
+                 ttl: float = POINTER_TTL, clock=time.monotonic):
+        self.workspace, self.title, self.max_graphs, self.ttl, self.clock = workspace, title, max_graphs, ttl, clock
+        self.started_at = datetime.now(timezone.utc).isoformat(timespec="seconds")
+        self.experience_builder = ExperienceBuilder(workspace, clock)
+        self._lock = threading.Lock()
+        self._pointer_at: float | None = None
+        self._versions: list[str] = []
+        self._active: str | None = None
+        self._graphs: OrderedDict[str, VersionGraph] = OrderedDict()
+        self._loading: dict[str, threading.Lock] = {}
+        self._experience: dict[str, tuple[float, dict]] = {}
+
+    # ---- pointers ----
+
+    def _refresh(self, force: bool = False) -> None:
+        now = self.clock()
+        if not force and self._pointer_at is not None and now - self._pointer_at < self.ttl:
+            return
+        self._versions = sorted(list_versions(self.workspace), key=version_key)
+        self._active = active_version(self.workspace)
+        self._pointer_at = now
+
+    def versions(self) -> list[str]:
+        with self._lock:
+            self._refresh()
+            return list(self._versions)
+
+    def active(self) -> str | None:
+        with self._lock:
+            self._refresh()
+            return self._active
+
+    def workspace_view(self) -> dict:
+        with self._lock:
+            self._refresh()
+            versions, active = list(self._versions), self._active
+        return {"title": self.title, "active_version": active, "generated_at": self.started_at,
+                "versions": [{"name": v, "kind": version_kind(v), "active": v == active} for v in versions]}
+
+    def knows(self, version: str) -> bool:
+        with self._lock:
+            self._refresh()
+            if version in self._versions:
+                return True
+            self._refresh(force=True)
+            return version in self._versions
+
+    # ---- graphs ----
+
+    def graph(self, version: str) -> VersionGraph:
+        """The built graph of a version; loads once per version even under concurrent requests."""
+        with self._lock:
+            if version in self._graphs:
+                self._graphs.move_to_end(version)
+                return self._graphs[version]
+            lock = self._loading.setdefault(version, threading.Lock())
+        with lock:
+            with self._lock:
+                if version in self._graphs:
+                    self._graphs.move_to_end(version)
+                    return self._graphs[version]
+            if not self.knows(version):
+                raise KeyError(version)
+            graph = VersionGraph(version, version_records(self.workspace, version))
+            with self._lock:
+                self._graphs[version] = graph
+                self._graphs.move_to_end(version)
+                while len(self._graphs) > self.max_graphs:
+                    self._graphs.popitem(last=False)
+                self._loading.pop(version, None)
+            return graph
+
+    def experience(self, version: str) -> dict:
+        now = self.clock()
+        with self._lock:
+            cached = self._experience.get(version)
+            if cached and now - cached[0] < self.ttl:
+                return cached[1]
+        report = self.experience_builder.build(version, self.graph(version))
+        with self._lock:
+            self._experience[version] = (now, report)
+        return report
+
+    def warm(self) -> threading.Thread:
+        """Load the active version and its report in the background so the first page is quick."""
+
+        def run() -> None:
+            try:
+                active = self.active()
+                if active:
+                    self.experience(active)
+            except Exception:  # a cold workspace is reported by the request that needs it
+                pass
+
+        thread = threading.Thread(target=run, name="evoontology-explorer-warm", daemon=True)
+        thread.start()
+        return thread

evoontology_explorer-0.1.0/src/evoontology_explorer/diff.py

@@ -0,0 +1,87 @@
+"""Version comparison over the canonical records, as the single-file page computed it in the browser."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .graph import VersionGraph
+
+
+def stable_normalize(value: Any) -> Any:
+    if isinstance(value, list):
+        return sorted((stable_normalize(v) for v in value), key=lambda v: json.dumps(v, ensure_ascii=False, sort_keys=True))
+    if isinstance(value, dict):
+        return {key: stable_normalize(value[key]) for key in sorted(value)}
+    return value
+
+
+def stable_stringify(value: Any) -> str:
+    return json.dumps(stable_normalize(value), ensure_ascii=False, separators=(",", ":"))
+
+
+def semantic_entries(graph: VersionGraph) -> dict[str, dict]:
+    """Nodes and relation edges by element id with a comparison signature; reference edges are derived, so skipped."""
+    entries: dict[str, dict] = {}
+    for node_id, data in graph.nodes.items():
+        entries[node_id] = {
+            "signature": stable_stringify(data["comparison"]), "fields": data["comparison"],
+            "family": data["family"], "title": data.get("label") or data["record_id"] or node_id,
+            "elementId": node_id, "owner_terms": [] if data["family"] == "term" else graph.owner_terms(node_id),
+        }
+    for edge_id, data in graph.edges.items():
+        if data["family"] != "relation":
+            continue
+        entries[edge_id] = {
+            "signature": stable_stringify(data["comparison"]), "fields": data["comparison"],
+            "family": "relation", "title": data.get("record_id") or data.get("label") or edge_id,
+            "elementId": edge_id, "owner_terms": [data["source"], data["target"]],
+        }
+    return entries
+
+
+def field_changes(before: dict | None, after: dict | None) -> list[dict]:
+    keys = sorted(set(before or {}) | set(after or {}))
+    changes = []
+    for key in keys:
+        left = (before or {}).get(key)
+        right = (after or {}).get(key)
+        if stable_stringify(left) != stable_stringify(right):
+            changes.append({"field": key, "before": left, "after": right})
+    return changes
+
+
+def _entry(status: str, key: str, item: dict) -> dict:
+    return {"key": key, "status": status, "family": item["family"], "title": item["title"],
+            "elementId": item["elementId"], "owner_terms": item["owner_terms"]}
+
+
+def signature_diff(left: dict[str, dict], right: dict[str, dict]) -> dict:
+    left_status: dict[str, str] = {}
+    right_status: dict[str, str] = {}
+    counts = {"added": 0, "removed": 0, "changed": 0}
+    entries: dict[str, list] = {"added": [], "removed": [], "changed": []}
+    for key, item in left.items():
+        if key not in right:
+            left_status[key] = "removed"
+            counts["removed"] += 1
+            entries["removed"].append(_entry("removed", key, item))
+        elif item["signature"] != right[key]["signature"]:
+            left_status[key] = right_status[key] = "changed"
+            counts["changed"] += 1
+            entries["changed"].append({**_entry("changed", key, item),
+                                       "changes": field_changes(item["fields"], right[key]["fields"])})
+        else:
+            left_status[key] = right_status[key] = "unchanged"
+    for key, item in right.items():
+        if key not in left:
+            right_status[key] = "added"
+            counts["added"] += 1
+            entries["added"].append(_entry("added", key, item))
+    return {"left_status": left_status, "right_status": right_status, "counts": counts, "entries": entries}
+
+
+def compare(left: VersionGraph, right: VersionGraph) -> dict:
+    result = signature_diff(semantic_entries(left), semantic_entries(right))
+    result["left_version"], result["right_version"] = left.version, right.version
+    return result