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

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.

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.

Prepare Your Knowledge Graph

The Explorer loads a JSON-serialized ContextGraph. Create and persist one as shown in semantica/context.py:

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:

semantica-explorer --graph my_graph.json

What happens:

• The FastAPI application initializes and loads 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, 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, 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:

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:

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 — Package entry point providing the semantica-explorer CLI and FastAPI app factory
• docs/explorer-setup.md — Official setup guide covering installation, graph preparation, and launch flags
• docs/reference/ontology.md — Ontology Hub API reference and visual editor documentation
• explorer/README.md — Feature overview for the Knowledge Explorer UI
• 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}