Explorer Setup - Semantica

semantica-explorer is an interactive browser dashboard for knowledge graph exploration. You give it a graph file, it starts a local server, and opens a browser tab where you can search nodes, find paths, inspect provenance, and run analytics: no code required after launch. This page covers everything needed to go from zero to a running Explorer. For the full REST API reference and endpoint catalogue, see Explorer Reference.

Prerequisites

The Explorer depends on FastAPI and uvicorn, which are not included in the base install:

pip install semantica[explorer]

pip install semantica alone is not sufficient. Running semantica-explorer without the [explorer] extra immediately prints an error and exits with code 1.

Verify:

semantica-explorer --help

You should see the usage message with the four available flags. If you see command not found, activate your virtual environment first. See CLI Setup for PATH help.

Minimal End-to-End Example

The following four steps are everything needed to get Explorer running:

from semantica.context import ContextGraph

# 1. Create a graph
graph = ContextGraph()

# 2. Add a node
graph.add_node("python", "language", content="Python programming language")

# 3. Save to disk
graph.save_to_file("my_graph.json")

# 4. Launch Explorer
semantica-explorer --graph my_graph.json

The browser opens at http://127.0.0.1:8000. The health endpoint confirms the server is up:

curl http://127.0.0.1:8000/api/health
# {"status": "ok"}

Step 1: Build and Save a ContextGraph

Explorer loads a graph from a JSON file on disk. You need to create that file first.

Build a graph

from semantica.context import ContextGraph

graph = ContextGraph()

# add_node(node_id, node_type, content=None, **properties)
graph.add_node("python",  "language",  content="Python programming language")
graph.add_node("fastapi", "framework", content="FastAPI web framework")
graph.add_node("guido",   "person",    content="Guido van Rossum")

# add_edge(source_id, target_id, edge_type="related_to", weight=1.0, **properties)
graph.add_edge("python",  "fastapi", "enables")
graph.add_edge("guido",   "python",  "created")

Save to a JSON file

graph.save_to_file("my_graph.json")

save_to_file writes a JSON object with graph_id, nodes, edges, and links to the specified path.

Verify the file loads (optional sanity check)

from semantica.context import ContextGraph

check = ContextGraph()
check.load_from_file("my_graph.json")
print(check.stats())
# {
#   "node_count": 3,
#   "edge_count": 2,
#   "node_types": {"language": 1, "framework": 1, "person": 1},
#   "edge_types": {"enables": 1, "created": 1},
#   "density": ...
# }

If this runs without error, Explorer will load the file successfully.

Already have a graph from a pipeline run? Skip straight to Step 2. The only requirement is that the file was saved with ContextGraph.save_to_file().

Step 2: Launch Explorer

semantica-explorer --graph my_graph.json

The startup sequence prints:

✓ Graph loaded: 3 nodes, 2 edges
╭─ Semantica Explorer · http://127.0.0.1:8000 ─╮
│  API docs  http://127.0.0.1:8000/docs         │
│  Health    http://127.0.0.1:8000/api/health   │
╰───────────────────────────────────────────────╯

The browser opens automatically at http://127.0.0.1:8000 shortly after the server starts.

CLI Flags

semantica-explorer accepts exactly four flags:

Flag	Short	Default	Description
`--graph`	`-g`	(required)	Path to a ContextGraph JSON file
`--port`	`-p`	`8000`	Port to bind the server
`--host`	:	`127.0.0.1`	Host to bind the server
`--no-browser`	:	off	Do not open a browser tab automatically

There are no flags for authentication, log level, or TLS. Those are not implemented in the CLI.

Examples

# Minimal: local only, port 8000, browser opens automatically
semantica-explorer --graph my_graph.json

# Short flags
semantica-explorer -g my_graph.json -p 8080

# Expose on the network so other machines can connect
semantica-explorer --graph my_graph.json --host 0.0.0.0 --port 8080

# Headless: skip the auto-open and navigate manually
semantica-explorer --graph my_graph.json --no-browser

--host 0.0.0.0 makes Explorer reachable on every network interface. The server has no built-in authentication. Only use this on a trusted private network.

Browser Access

Once the server is running:

URL	What you get
`http://127.0.0.1:8000`	Interactive dashboard
`http://127.0.0.1:8000/docs`	Swagger UI: every REST endpoint, interactive
`http://127.0.0.1:8000/api/health`	Health check: `{"status": "ok"}`

The browser tab opens shortly after startup. If it does not open, navigate to the URL manually or pass --no-browser and open it yourself.

Running as a Python Module

If semantica-explorer is not on PATH, use the module form:

python -m semantica.explorer --graph my_graph.json --port 8080

Common Startup Errors

Error: graph file not found

The path passed to --graph must point to an existing file. The CLI checks with os.path.isfile() before loading anything.

# Confirm the file exists
ls my_graph.json                                          # Linux / Mac
dir my_graph.json                                         # Windows

# Use the full path if needed
semantica-explorer --graph /absolute/path/to/my_graph.json

Error: uvicorn is required

The [explorer] extra was not installed alongside the base package:

pip install semantica[explorer]

Explorer launches but shows zero nodes

The file loaded but contains no nodes. Verify with Python:

from semantica.context import ContextGraph
g = ContextGraph()
g.load_from_file("my_graph.json")
print(g.stats())  # check node_count

A node_count of 0 means the graph was saved before any nodes were added. Make sure you called add_node() before save_to_file().

Connection refused from another machine

The default --host 127.0.0.1 only accepts connections from the same machine. To allow remote access:

semantica-explorer --graph my_graph.json --host 0.0.0.0

Browser tab does not open

Expected in headless, SSH, and container environments. Pass --no-browser to suppress the warning, then open http://127.0.0.1:8000 in a browser that has network access to the server.

What Explorer Gives You

Once running, Explorer exposes a REST API and dashboard for:

Node and edge search: indexed search across all nodes by ID, type, and content
Neighborhood expansion: inspect neighbors up to configurable hop depth
Path finding: BFS shortest path between any two nodes
Graph analytics: centrality, community detection, connectivity
Decisions and provenance: query recorded decisions and their causal chains
Import / export: upload JSON or CSV to extend the graph; download the current state

The full endpoint catalogue is documented in the Swagger UI at /docs and in the reference page below.

Explorer Reference — Every REST endpoint, WebSocket events, analytics, and all supported flags.
CLI Setup — All five Semantica executables and when to use each one.
Context Module — Full documentation for ContextGraph: build, query, save, and load.
Quickstart — End-to-end pipeline: ingest → extract → build graph → export.

​Prerequisites

​Minimal End-to-End Example

​Step 1: Build and Save a ContextGraph

​Step 2: Launch Explorer

​CLI Flags

​Examples

​Browser Access

​Running as a Python Module

​Common Startup Errors

​What Explorer Gives You

Prerequisites

Minimal End-to-End Example

Step 1: Build and Save a ContextGraph

Step 2: Launch Explorer

CLI Flags

Examples

Browser Access

Running as a Python Module

Common Startup Errors

What Explorer Gives You