Metadata-Version: 2.5
Name: evoontology-explorer
Version: 0.4.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`.

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:

```bash
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

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

| Route | Returns |
|---|---|
| `GET /api/workspaces` | title and the workspaces (`id`, `label`) |
| `GET /api/w/{w}` | the active version and the versions of a workspace with their kind (`candidate` for `-cN` trial versions, otherwise `published`); `GET /api/workspace` is the first workspace's |
| `GET /api/w/{w}/versions/{v}` | counts, warnings, term and satellite counts |
| `GET /api/w/{w}/versions/{v}/graph` | the term layer: term nodes and relation edges |
| `GET /api/w/{w}/versions/{v}/terms/{id}/satellites` | one term's mappings, constraints and evidence with their reference edges |
| `GET /api/w/{w}/versions/{v}/satellites` | every satellite of the version |
| `GET /api/w/{w}/versions/{v}/elements/{id}` | the detail rows of a node or edge, with links to the records it names; for a term also its relations (type, direction, the term at the other end) |
| `GET /api/w/{w}/versions/{v}/search?q=` | nodes matching a substring |
| `GET /api/schema`, `GET /api/w/{w}/versions/{v}/tools`, `GET /api/w/{w}/versions/{v}/experience` | the Schema, Tool and Results views |
| `GET /api/w/{w}/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 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

```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.
