# How to Set Up the Semantica Knowledge Explorer Web Interface and Ontology Hub

> Easily set up the Semantica Knowledge Explorer and Ontology Hub. Install semantica[explorer], save your ContextGraph, and launch the FastAPI dashboard to visualize your knowledge graph.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Install `semantica[explorer]`, save your `ContextGraph` to JSON, and run `semantica-explorer --graph file.json` to launch the FastAPI-powered Knowledge Explorer dashboard with integrated Ontology Hub at `http://127.0.0.1:8000`.**

The Semantica Knowledge Explorer and Ontology Hub provide a unified, browser-based environment for navigating knowledge graphs and managing semantic schemas. According to the semantica-agi/semantica source code, this interactive interface runs on a FastAPI backend (`semantica.explorer` package) that serves both graph exploration tools and a visual ontology editor from the same local server. This guide walks through complete setup and configuration using the actual implementation details from the repository.

## Install the Explorer Dependencies

The Knowledge Explorer requires additional packages beyond the core semantica library. The `[explorer]` extra installs FastAPI, uvicorn, and all UI assets needed for both the dashboard and Ontology Hub.

```bash
pip install semantica[explorer]

```

**Critical note:** The `semantica-explorer` CLI aborts with an error if these extras are missing. The core `pip install semantica` alone does not include the web interface components, as documented in [`docs/explorer-setup.md`](https://github.com/semantica-agi/semantica/blob/main/docs/explorer-setup.md).

## Prepare Your Knowledge Graph

The Explorer loads a JSON-serialized `ContextGraph`. Create and persist one as shown in [`semantica/context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context.py):

```python
from semantica.context import ContextGraph

# Create an empty graph

g = ContextGraph()

# Add nodes with types and content

g.add_node("python", "language", content="Python programming language")
g.add_node("fastapi", "framework", content="FastAPI web framework")
g.add_edge("python", "fastapi", "enables")

# Persist to JSON — this is the file Explorer consumes

g.save_to_file("my_graph.json")

```

The `save_to_file()` method encodes the full graph structure, node metadata, and edge relationships to a JSON format that the FastAPI backend can index and serve.

## Launch the Knowledge Explorer

Start the web interface with a single command:

```bash
semantica-explorer --graph my_graph.json

```

**What happens:**
- The FastAPI application initializes and loads [`my_graph.json`](https://github.com/semantica-agi/semantica/blob/main/my_graph.json) into an enriched knowledge graph (EKG) service
- Uvicorn starts on `http://127.0.0.1:8000` by default
- Your default browser automatically opens to the dashboard
- REST endpoints mount at `/api/*`, with Swagger documentation at `/docs` and health check at `/api/health`

The entry point for this behavior is defined in [`semantica/explorer/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/explorer/__init__.py), which registers the `semantica-explorer` console script.

## Access and Use the Ontology Hub

The Ontology Hub is integrated into the same FastAPI application—no separate server required. Once the dashboard loads, click the **Ontology Hub** tab (top-right) to access:

| Capability | Function |
|------------|----------|
| **Visual ontology editor** | Drag-and-drop canvas for SKOS term editing and concept creation |
| **SHACL Studio** | Generate and refine SHACL shapes from your current ontology |
| **Ontology alignment** | Cross-ontology mapping and merging workflows |
| **Health dashboard** | Validation status, versioning, and provenance reports |

Per [`docs/reference/ontology.md`](https://github.com/semantica-agi/semantica/blob/main/docs/reference/ontology.md), all Ontology Hub changes persist through the same `/api/*` endpoints that power the Explorer UI. This unified architecture means graph navigation and schema management share a single backend state.

## Validate Graphs Against SHACL Shapes (Programmatically)

The `OntologyEngine` class validates `ContextGraph` instances against ontologies generated or edited in the Hub:

```python
from semantica.ontology import OntologyEngine
from semantica.context import ContextGraph

# Initialize engine with base URI

engine = OntologyEngine(base_uri="https://example.org/ontology/")

# Load or construct ontology (could come from Hub edits)

ontology = engine.from_data({
    "entities": entities,
    "relationships": relationships
})

# Load the same graph Explorer visualizes

kg = ContextGraph()
kg.load_from_file("my_graph.json")

# Run SHACL validation

report = engine.validate_graph(kg, ontology=ontology)

if not report.conforms:
    for v in report.violations:
        print(f"{v.severity}: {v.message} on {v.focus_node}")

```

This bridges the visual Ontology Hub workflow with programmatic quality gates in CI/CD pipelines.

## Deploy Headless or Network-Accessible

For Docker containers, remote servers, or CI environments, disable auto-browser and bind to all interfaces:

```bash
semantica-explorer --graph my_graph.json --no-browser --host 0.0.0.0 --port 8080

```

Remote browsers can now access the full Knowledge Explorer and Ontology Hub at `http://<host_ip>:8080`. The `--host 0.0.0.0` flag is essential for containerized deployments where `127.0.0.1` only exposes the service internally.

## Key Source Files and Architecture

The Explorer's implementation spans these repository locations:

- **[`semantica/explorer/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/explorer/__init__.py)** — Package entry point providing the `semantica-explorer` CLI and FastAPI app factory
- **[`docs/explorer-setup.md`](https://github.com/semantica-agi/semantica/blob/main/docs/explorer-setup.md)** — Official setup guide covering installation, graph preparation, and launch flags
- **[`docs/reference/ontology.md`](https://github.com/semantica-agi/semantica/blob/main/docs/reference/ontology.md)** — Ontology Hub API reference and visual editor documentation
- **[`explorer/README.md`](https://github.com/semantica-agi/semantica/blob/main/explorer/README.md)** — Feature overview for the Knowledge Explorer UI
- **[`ARCHITECTURE.md`](https://github.com/semantica-agi/semantica/blob/main/ARCHITECTURE.md)** — System diagram showing Explorer position in the services layer

As noted in `ARCHITECTURE.MD`, the Explorer sits at the presentation layer above the enriched knowledge graph (EKG) services, which provide indexed search, path-finding, analytics, and provenance queries to both the visualization frontend and the Ontology Hub backend.

## Summary

- **Install once:** `pip install semantica[explorer]` adds FastAPI, uvicorn, and UI assets required for both components
- **Prepare data:** Save any `ContextGraph` via `save_to_file()` to create the JSON input Explorer requires
- **Launch simply:** `semantica-explorer --graph file.json` starts the unified server at `http://127.0.0.1:8000`
- **Access both:** The Knowledge Explorer dashboard and Ontology Hub visual editor share the same FastAPI process and port
- **Deploy flexibly:** Use `--no-browser --host 0.0.0.0` for headless or networked installations
- **Validate programmatically:** `OntologyEngine.validate_graph()` applies SHACL shapes from Hub edits to any `ContextGraph`

## Frequently Asked Questions

### What is the difference between the Knowledge Explorer and the Ontology Hub?

The **Knowledge Explorer** is the interactive graph visualization interface for browsing `ContextGraph` nodes, edges, and paths in a browser. The **Ontology Hub** is a dedicated tab within the same web UI that provides visual editing for SKOS vocabularies, SHACL shape generation, and ontology alignment. Both run from the same FastAPI server—no separate installation or port configuration required.

### Why does `semantica-explorer` fail with a dependency error?

The CLI explicitly checks for the `[explorer]` extra and exits if FastAPI or uvicorn are missing. Run `pip install semantica[explorer]` rather than `pip install semantica`. The core library intentionally excludes these to keep base installations lightweight for headless graph processing pipelines.

### Can I use the Ontology Hub without launching the full Explorer?

No—the Ontology Hub is served as a route within the Explorer's FastAPI application (`semantica.explorer` package). However, you can launch Explorer with `--no-browser` and access only the Hub tab via API or direct URL if graph visualization is not needed. There is no standalone Ontology Hub server.

### How do I persist Ontology Hub edits back to my Python workflow?

The Hub persists changes through the same REST endpoints used by the UI. Load the modified ontology programmatically with `OntologyEngine.from_data()` or re-export from the Hub as JSON-LD/Turtle, then feed into `engine.validate_graph()` or other downstream `semantica` components.