evoontology-explorer

A server-backed explorer for 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

pip install evoontology-explorer                # local directories
pip install "evoontology-explorer[databricks]"  # Unity Catalog volumes
pip install "evoontology-explorer[s3]"          # S3 prefixes

Run

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.

Several workspaces can be served by one page, with a workspace picker next to the version picker. Repeat --workspace, or separate the entries of EVOONTOLOGY_WORKSPACE with ;. A location ending in /* serves every child directory, relisted at most once a minute, so workspaces added later appear without a restart:

evoontology-explorer --workspace ./snapshots/business --workspace "./snapshots/employees/*"
EVOONTOLOGY_WORKSPACE="/Volumes/<catalog>/<schema>/<volume>/business;/Volumes/<catalog>/<schema>/<volume>/employees/*"

A workspace's id is the last component of its path (business, e1); its label keeps the parent (employees/e1), or is the name of the workspace's project.json when it has one. Duplicate ids get a numeric suffix. ?workspace=<id>&version=<name> opens the page on one.

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

# app.yaml
command: ["python", "-m", "evoontology_explorer"]
env:
  - name: EVOONTOLOGY_WORKSPACE
    value: /Volumes/<catalog>/<schema>/<volume>/code

# 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. Workspaces are addressed by id (w), versions by name.

Node ids are <family>:<record id>; relation edges are rel:<record id>.

Library use

from evoontology_explorer import WorkspaceSet, create_app, open_workspace

app = create_app(open_workspace("./workspace"), title="My ontology")
app = create_app(WorkspaceSet(["./snapshots/business", "./snapshots/employees/*"]), title="Snapshots")

Development

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.