Metadata-Version: 2.4
Name: orionbelt-ontology-builder
Version: 1.15.1
Summary: A Streamlit application for building, editing, and managing OWL ontologies
Author-email: "Ralf Becher, RALFORION d.o.o." <info@ralforion.com>
License: BSL-1.1
Project-URL: Homepage, https://github.com/ralforion/orionbelt-ontology-builder
Project-URL: Repository, https://github.com/ralforion/orionbelt-ontology-builder
Project-URL: Issues, https://github.com/ralforion/orionbelt-ontology-builder/issues
Project-URL: Demo, https://orionbelt.streamlit.app
Keywords: ontology,owl,rdf,rdflib,streamlit,semantic-web,knowledge-graph
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: streamlit==1.49.1
Requires-Dist: rdflib>=7.0.0
Requires-Dist: owlrl>=6.0.2
Requires-Dist: networkx>=3.0
Requires-Dist: pyvis>=0.3.2
Requires-Dist: streamlit-local-storage>=0.0.25
Provides-Extra: desktop
Requires-Dist: streamlit-desktop-app>=0.3.3; extra == "desktop"
Requires-Dist: pywebview[pyside6]; sys_platform != "darwin" and extra == "desktop"
Requires-Dist: darkdetect>=0.8.0; extra == "desktop"
Provides-Extra: qt
Requires-Dist: streamlit-desktop-app>=0.3.3; extra == "qt"
Requires-Dist: pywebview[pyside6]; sys_platform != "darwin" and extra == "qt"
Requires-Dist: darkdetect>=0.8.0; extra == "qt"
Provides-Extra: gtk
Requires-Dist: streamlit-desktop-app>=0.3.3; extra == "gtk"
Requires-Dist: pywebview[gtk]; sys_platform == "linux" and extra == "gtk"
Requires-Dist: darkdetect>=0.8.0; extra == "gtk"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff==0.15.19; extra == "dev"
Requires-Dist: mypy==1.18.2; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/ralforion/orionbelt-ontology-builder/main/orionbelt_ontology_builder/assets/ORIONBELT_Logo.png" alt="OrionBelt Logo" width="400">
</p>

<h1 align="center">OrionBelt Ontology Builder</h1>

<p align="center"><strong>A browser-based ontology workbench built with Streamlit and rdflib</strong></p>

[![GitHub stars](https://img.shields.io/github/stars/ralforion/orionbelt-ontology-builder?style=social)](https://github.com/ralforion/orionbelt-ontology-builder)
[![Version 1.15.1](https://img.shields.io/badge/version-1.15.1-purple.svg)](https://github.com/ralforion/orionbelt-ontology-builder/releases)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: BSL 1.1](https://img.shields.io/badge/License-BSL_1.1-orange.svg)](https://github.com/ralforion/orionbelt-ontology-builder/blob/main/LICENSE)

[![Streamlit](https://img.shields.io/badge/Streamlit-1.28+-FF4B4B.svg?logo=streamlit&logoColor=white)](https://streamlit.io)
[![rdflib](https://img.shields.io/badge/rdflib-7.0+-2E86C1.svg)](https://rdflib.readthedocs.io)
[![OWL-RL](https://img.shields.io/badge/OWL--RL-reasoning-green.svg)](https://owl-rl.readthedocs.io)
[![vis-network](https://img.shields.io/badge/vis--network-9.1-97C2FC.svg)](https://visjs.github.io/vis-network/docs/network/)

[![Docker Hub](https://img.shields.io/docker/v/ralforion/orionbelt-ontology-builder?logo=docker&logoColor=white&label=Docker%20Hub&color=2496ED&sort=semver)](https://hub.docker.com/r/ralforion/orionbelt-ontology-builder/tags)
[![Docker pulls](https://img.shields.io/docker/pulls/ralforion/orionbelt-ontology-builder?logo=docker&logoColor=white&color=2496ED)](https://hub.docker.com/r/ralforion/orionbelt-ontology-builder)
[![Image size](https://img.shields.io/docker/image-size/ralforion/orionbelt-ontology-builder/latest?logo=docker&logoColor=white&color=2496ED)](https://hub.docker.com/r/ralforion/orionbelt-ontology-builder/tags)

**Try it now:** [orionbelt.streamlit.app](https://orionbelt.streamlit.app/)

<p align="center">
  <img src="https://raw.githubusercontent.com/ralforion/orionbelt-ontology-builder/main/orionbelt_ontology_builder/assets/OrionBelt_Ontology_Builder.png" alt="OrionBelt Ontology Builder Screenshot" width="800">
</p>

---

## What is this?

OrionBelt lets you build, edit, and maintain OWL ontologies and SKOS vocabularies in your browser. No Java, no desktop install - just `pip install` and go.

It works with **OWL ontologies** (classes as `owl:Class`, properties as `owl:ObjectProperty` / `owl:DatatypeProperty`). Pure RDFS vocabularies like schema.org that use `rdfs:Class` and `rdf:Property` are not currently surfaced in the Classes / Properties panels.

It's not trying to be Protégé. It's meant for people who want something lighter: a workbench that's easy to pick up, hard to break things with, and good enough for real ontology work.

## What it's good at

**Not losing your work.** Every change creates an undo checkpoint. Deletes show you what will break before you confirm. Imports show a diff so you can review before applying.

**Keeping your ontology clean.** Validation catches orphan classes, duplicate labels, domain/range mismatches, missing annotations, and SKOS-specific issues like broader/narrower cycles. Not just "you have warnings" but "here's what's wrong and where."

**Moving fast in large ontologies.** Global search across everything. Usage/backlink views for any resource. Click a node in the graph and jump straight to the editor. Bulk add/edit/delete so you're not filling out forms one entity at a time.

**Working with others.** Merge-aware imports with three strategies (replace, merge, merge-overwrite). Conflict detection. Prefix reconciliation. Change reports you can download. You can actually review what an import would do before committing it.

---

## Features

### Ontology editing

Full CRUD for classes, object/data properties, individuals, restrictions, relations, and annotations. Hierarchy management, rename with reference updates, and tabbed editing per entity type.

### Bulk operations

Every entity page has a Bulk Operations tab:

- **Add** - paste names (one per line) or CSV with headers like `Name, Label, Parent`
- **Edit** - spreadsheet view of all entities with editable labels, comments, parents
- **Delete** - multi-select and remove in one go

Annotations have their own bulk editor with per-row add/delete actions.

### SKOS vocabularies

A dedicated page for building controlled vocabularies:

- Concept schemes with concept counts
- Concepts with prefLabel, definition, broader/narrower (inverses auto-managed)
- Hierarchy tree view, filterable by scheme
- Full SKOS relation support (broader, narrower, related, all match types)
- SKOS validation: missing prefLabels, orphans, duplicate labels, cycles

### Templates

Five starter templates you can merge into or replace your current ontology: Organization, Product Catalog, Event, Person/Contact, and SKOS Thesaurus. Each is a valid Turtle snippet with a preview before you apply it.

### Upper Ontologies

Start from a professionally built upper ontology instead of redefining foundational concepts for every project. Two options ship in the box:

- [**gist**](https://www.semanticarts.com/gist/) by Semantic Arts — a minimalist upper ontology covering ~100 classes (Event, Person, Organization, Agreement, Specification, etc.) and ~100 properties. Select which modules to load (Core, RDFS Annotations, SubClass Assertions, Media Types) and merge or replace your current ontology.
- [**gUFO**](https://nemo-ufes.github.io/gufo/) (gentle UFO) — a lightweight OWL implementation of the Unified Foundational Ontology, suitable for OntoUML-style conceptual modeling with kinds, roles, phases, events, situations, qualities, and relators.

### Reference Ontologies

A separate tab for importing widely-used domain and reference vocabularies. The loader supports both bundled vocabularies (instant) and on-demand downloads (verified against a pinned SHA256 and cached on disk). Currently ships with [**PROV-O**](https://www.w3.org/TR/prov-o/), [**FOAF**](http://xmlns.com/foaf/spec/), and [**GoodRelations**](http://www.heppnetz.de/ontologies/goodrelations/) — all bundled.

### Import & export

| Format    | Extension  | Import | Export |
| --------- | ---------- | ------ | ------ |
| Turtle    | .ttl       | ✅     | ✅     |
| RDF/XML   | .owl, .rdf | ✅     | ✅     |
| N-Triples | .nt        | ✅     | ✅     |
| N3        | .n3        | ✅     | ✅     |
| JSON-LD   | .jsonld    | ✅     | ✅     |

Imports on an empty ontology go straight through. Otherwise you get a review panel: diff summary, conflict table, prefix changes, import mode selector, and a downloadable change report.

### Validation & reasoning

- Missing labels, domains, ranges
- Orphan classes, duplicate labels, domain/range mismatches
- Untyped individuals
- SKOS checks (see above)
- RDFS and OWL-RL reasoning via owlrl

### Visualization

Interactive vis-network graph with class filtering, configurable node limits, click-to-navigate into the editor, Ctrl/Cmd-click a node to add it to the "Focus on one node" selection (narrowing the graph to its neighbourhood), hierarchy tree view, and statistics charts.

### Safety

- Full undo/redo with labeled checkpoints
- Delete impact analysis before confirmation
- Bulk operations create a single undo point
- Namespace prefix management from the Dashboard

---

## Quick Start

```bash
# Clone and install
git clone https://github.com/ralforion/orionbelt-ontology-builder.git
cd orionbelt-ontology-builder
pip install -r requirements.txt

# Or install from PyPI
pip install orionbelt-ontology-builder

# Run
streamlit run app.py
```

Open http://localhost:8501

### Run as a command

Installing the package also provides an `orionbelt-ontology-builder` command that
launches the app for you, so there is no need to call `streamlit run` yourself:

```bash
# Install as an isolated tool and run it (uv or pipx)
uv tool install orionbelt-ontology-builder
orionbelt-ontology-builder            # boots the app, opens the browser

# Or run it one-off without installing
uvx orionbelt-ontology-builder
pipx run orionbelt-ontology-builder
```

Any extra arguments are forwarded to Streamlit, e.g.
`orionbelt-ontology-builder --server.port 8502`.

### Run as a native desktop app

Prefer a native window over a browser tab? Install the optional `desktop` extra
and use the `orionbelt-ontology-builder-desktop` command. It runs the app in a
native window (via [`streamlit-desktop-app`](https://pypi.org/project/streamlit-desktop-app/),
pywebview + a real Streamlit server), so there is no browser tab to manage and no
manual start/stop of the server:

```bash
pip install "orionbelt-ontology-builder[desktop]"
orionbelt-ontology-builder-desktop    # opens a native window
```

On Linux and Windows the extra also installs PySide6 and qtpy to give pywebview a
native Qt rendering backend (macOS uses the system WebKit backend, so they are
not needed there).

The desktop window follows your OS light/dark appearance by default. Once you
pick a specific theme in the toolbar's Settings menu, that choice is remembered
across launches. To go back to following the system, clear the stored setting
(delete `theme_base` from `~/.orionbelt_ontology_builder/config.json`).

#### Choosing a rendering backend

The `desktop` extra uses the Qt backend, which works out of the box. On Linux you
can use GTK instead with the `gtk` extra (`qt` is an explicit alias for the Qt
default):

```bash
pip install "orionbelt-ontology-builder[gtk]"
```

GTK needs system packages that pip cannot install. On Debian/Ubuntu:

```bash
sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-webkit2-4.1 \
    libgirepository1.0-dev
```

The launcher auto-selects whichever backend is installed; set `PYWEBVIEW_GUI=qt`
or `PYWEBVIEW_GUI=gtk` to override.

This is fully opt-in: the plain install and the `orionbelt-ontology-builder`
command above are unchanged.

### Local file storage

When you launch the app locally (the `orionbelt-ontology-builder` command or the
native desktop window), it persists to disk instead of browser storage:

- **Crash recovery.** With no linked file set, your working ontology is saved to
  a recovery file under `~/.orionbelt_ontology_builder/` on every change, so an
  unexpected close (crash, freeze) is recovered automatically on the next launch.
  When a linked file is set it becomes the store (below), and the recovery file
  is only written as a fallback if a linked-file write fails — so each change is
  one write, not two.
- **Linked working file.** Use the sidebar's "Linked working file" control to
  point the app at any file path. If the file already exists, you choose whether
  to **load it** into the workspace (the default, so pointing at an existing
  ontology opens it) or **overwrite** it with the current ontology; a new path is
  created from your current work. Once linked, the file tracks your working
  ontology and is loaded again on startup. Point it at a synced folder
  (Nextcloud, Dropbox, ...) for fully automatic off-machine backups. The format
  follows the file extension (`.ttl`, `.owl`/`.rdf`, `.nt`, `.n3`, `.jsonld`;
  Turtle if unknown).

Autosave is gated on actual edits and debounced, so normal clicking around does
no work even for large ontologies — the graph is serialized straight to a temp
file and atomically swapped in only after edits settle (and immediately after an
import or a new-ontology action). The sidebar shows "Saved to disk" only once
that write completes, so a crash can lose at most the last second or two of
edits. If a linked or recovery file can't be read or parsed on startup, disk
autosave is paused (with a sidebar notice) so the unreadable file is never
overwritten. The hosted demo on Streamlit Cloud has no local filesystem, so it
keeps using per-browser autosave instead — which shares the same dirty/debounced
scheduling and disables itself (until the graph shrinks) when an ontology exceeds
the browser storage quota.

### Run with Docker

A prebuilt image is published to Docker Hub. No local Python setup required:

```bash
docker run --rm -p 8501:8501 ralforion/orionbelt-ontology-builder
```

Then open http://localhost:8501. Use `:1.15.1` to pin a specific version instead of `latest`.

To build the image yourself from a checkout:

```bash
docker build -t ralforion/orionbelt-ontology-builder .
docker run --rm -p 8501:8501 ralforion/orionbelt-ontology-builder
```

The container runs Streamlit headless on `0.0.0.0:8501` as a non-root user.

### Upload size limit

Imported files are capped at **200 MB** by default (Streamlit's `maxUploadSize`).
To import larger ontologies, raise the limit in `.streamlit/config.toml`:

```toml
[server]
maxUploadSize = 1000   # MB
```

or pass it at launch:

```bash
streamlit run app.py --server.maxUploadSize 1000
```

Parsing happens in memory, so the practical ceiling is the host machine's
available RAM rather than this setting. The hosted demo is RAM-limited and keeps
the 200 MB default; raise the value only when self-hosting with enough memory.

---

## Pages

| Page                | What it does                                                   |
| ------------------- | -------------------------------------------------------------- |
| **Dashboard**       | Metadata, base URI, statistics, prefix management, validation  |
| **Classes**         | Class hierarchy, CRUD, bulk operations                         |
| **Properties**      | Object & data properties, CRUD, bulk operations                |
| **Individuals**     | Instance management, property assertions, bulk operations      |
| **Relations**       | Class, property, and individual relations                      |
| **Restrictions**    | OWL restrictions and cardinality constraints                   |
| **Advanced**        | Advanced OWL features                                          |
| **Annotations**     | RDFS, SKOS, Dublin Core annotations with bulk editing          |
| **SKOS Vocabulary** | Concept schemes, concepts, hierarchy, SKOS validation          |
| **Import / Export** | File import with merge review, export, new ontology, templates |
| **Source**          | Live Turtle source view of the ontology                        |
| **Validation**      | Ontology validation and OWL reasoning                          |
| **Visualization**   | Interactive graph (OWL + SKOS), hierarchy tree, statistics     |

## Project structure

```
orionbelt-ontology-builder/
├── app.py                              # Streamlit Cloud entry point (delegates to package)
├── ontology_manager.py                 # Backward-compat shim
├── templates.py                        # Backward-compat shim
├── orionbelt_ontology_builder/         # The actual installable package
│   ├── app.py                          # Streamlit UI
│   ├── ontology_manager.py             # Core OWL/SKOS engine (rdflib)
│   ├── templates.py                    # Built-in templates / upper / reference ontologies
│   ├── samples/                        # Bundled gist, gUFO, FOAF, PROV-O, GoodRelations, …
│   ├── lib/                            # Frontend libraries (vis-network, Tom Select)
│   ├── assets/                         # Logos and screenshots
│   └── favicon.png
├── pyproject.toml                      # Project metadata
└── tests/                              # pytest suite
```

Dependencies: streamlit, rdflib, owlrl, networkx, pyvis.

---

## Companion Project

### [OrionBelt Analytics](https://github.com/ralfbecher/orionbelt-analytics)

An ontology-based MCP server that analyzes relational database schemas (PostgreSQL, Snowflake, Dremio) and generates RDF/OWL ontologies with embedded SQL mappings. Together with the Ontology Builder, they form a toolkit for ontology-driven data modeling.

## License

Copyright 2025–2026 [RALFORION d.o.o.](https://ralforion.com)

Licensed under the [Business Source License 1.1](LICENSE). The Licensed Work will convert to Apache License 2.0 on 2030-03-30.

By contributing to this project, you agree to the [Contributor License Agreement](CLA.md).

---

<p align="center">
  <a href="https://ralforion.com">
    <img src="https://raw.githubusercontent.com/ralforion/orionbelt-ontology-builder/main/orionbelt_ontology_builder/assets/RALFORION_doo_Logo.png" alt="RALFORION d.o.o." width="200">
  </a>
</p>
