semantica/docs/explorer-setup.md

title, description, icon

title	description	icon
Explorer Setup	Install the Explorer extras, save a ContextGraph to JSON, and launch the interactive browser dashboard.	map

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.

```python 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")
```

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

```python 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. Since v0.6.5 the Explorer API requires `SEMANTICA_API_KEY` (sent as the `X-API-Key` header) and fails closed with `503` when unconfigured; unauthenticated access is only possible when `SEMANTICA_ALLOW_ANONYMOUS=true` is set explicitly. 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

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

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

pip install semantica[explorer]

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().

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

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.