mengzhx/semantica
1
0
Fork 0
mirror of https://github.com/semantica-agi/semantica.git synced 2026-08-29 04:26:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(explorer): resolve blank dashboard UI and ship frontend bundle in wheel (#638)

Browse Source 
* fix(explorer): resolve blank dashboard UI and ship frontend bundle in wheel

Fixes #631 — the Explorer server started successfully but the browser showed
a blank page because semantica/static/ was gitignored and never present after
a fresh install or clone.

Changes:
- ci.yml / release.yml: add Node 20 setup + npm ci && npm run build before
  python -m build so every wheel contains a CI-built frontend bundle
- pyproject.toml: add package-data patterns (static/*, static/assets/*) so
  setuptools includes the bundle in the wheel; add MANIFEST.in for sdist coverage
- app.py: replace silent empty-HTML fallback with a 200 page that clearly
  explains the missing bundle and links to /docs; fix CORS allow_credentials
  to default false, gated behind EXPLORER_CORS_CREDENTIALS env var to prevent
  credentialed cross-origin requests on unauthenticated endpoints
- __init__.py: warn at startup when --host is non-loopback (unauthenticated
  network exposure)
- explorer/README.md: full rewrite covering pip-install mode (primary path,
  no Node required) and dev-server mode (contributors), CLI flags, env vars,
  workspace table, troubleshooting for the blank-page symptom
- README.md: update Knowledge Explorer section with correct command and link
  to the new setup guide

* fix(explorer): set build.target esnext to fix esbuild CI failure

esbuild >=0.28 (forced via npm overrides) conflicts with Vite 6 defaults on
Linux CI — it tries to lower destructuring syntax for the implicit browser
target list but errors out. Explicit target: 'esnext' tells esbuild to emit
native syntax unchanged, bypassing the transpilation error entirely. Safe for
a developer tool that runs in modern browsers.

* test(explorer): verify packaged frontend bundle

---------

Co-authored-by: Zohaib Hassnain <109234410+ZohaibHassan16@users.noreply.github.com>
This commit is contained in:
Mohd Kaif
2026-06-16 14:38:24 +05:30
committed by GitHub
co-authored by Zohaib Hassnain
parent dfd96784a2
commit 46447d1f3f
10 changed files with 323 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files
explorer/README.md
+169 -93
View File
@@ -1,116 +1,153 @@
# Semantica Knowledge Explorer
A real-time visual interface for exploring knowledge graphs, decision intelligence, entity resolution, ontologies, and graph analytics built on top of the [Semantica](https://github.com/Hawksight-AI/semantica) library.
A browser-based graph workbench for the [Semantica](https://github.com/semantica-agi/semantica) platform. Pan and zoom live graphs, scrub the timeline, trace every decision's causal chain, resolve duplicates, and author your ontology visually. Built on React 19 + Sigma.js.
---
## Requirements
| Dependency | Minimum Version |
|---|---|
| Dependency | Minimum version |
| --- | --- |
| Python | 3.8+ |
| Node.js | 18.x or higher (20.x recommended) |
| npm | 9.x or higher |
| Python | 3.8+ |
| Semantica backend | running on `http://127.0.0.1:8000` |
Check your versions:
```bash
python --version
node --version
npm --version
python --version
```
---
## Quick Start (Local Development)
## Two ways to run the Explorer
### 1. Clone the repository
### Option A — pip install (recommended for users)
Install the package with the explorer extras. The pre-built frontend bundle is included in the wheel so no Node.js is required.
```bash
git clone https://github.com/Hawksight-AI/semantica.git
pip install "semantica[explorer]"
```
Launch the dashboard by pointing it at any graph JSON file:
```bash
semantica-explorer --graph my_graph.json
```
The server starts at `http://127.0.0.1:8000` and opens the dashboard in your default browser automatically.
CLI flags:
| Flag | Default | Description |
| --- | --- | --- |
| `--graph` / `-g` | *(required)* | Path to a ContextGraph JSON file |
| `--port` / `-p` | `8000` | Port to bind the server to |
| `--host` | `127.0.0.1` | Host to bind (use `127.0.0.1` for local-only; see security note below) |
| `--no-browser` | off | Skip opening the browser automatically |
Examples:
```bash
# Default — opens at http://127.0.0.1:8000
semantica-explorer --graph my_graph.json
# Custom port
semantica-explorer --graph my_graph.json --port 8080
# Suppress auto-open
semantica-explorer --graph my_graph.json --no-browser
# Equivalent using python -m
python -m semantica.explorer --graph my_graph.json
```
> **Security note:** The Explorer API has no built-in authentication. The default `--host 127.0.0.1` binds to localhost only, so it is not reachable from other machines on your network. If you bind to `0.0.0.0`, all graph data is readable and writable by any host that can reach the port. The CLI will print a warning in that case.
---
### Option B — run from source (for contributors / frontend development)
This mode runs the React dev server with hot module replacement, so frontend changes appear in the browser instantly without rebuilding.
#### Step 1 — Clone the repo
```bash
git clone https://github.com/semantica-agi/semantica.git
cd semantica
```
### 2. Install the Semantica Python package
#### Step 2 — Install the Python package
```bash
pip install semantica
pip install -e ".[explorer]"
```
Or install from source if you have the repo:
```bash
pip install -e .
```
### 3. Start the Semantica backend
The Explorer proxies all `/api` and `/ws` requests to `http://127.0.0.1:8000`. The backend must be running before you open the UI.
```bash
# From the repo root
python -m semantica.server
```
The backend starts on port **8000** by default. Keep this terminal open.
### 4. Install frontend dependencies
Open a second terminal:
#### Step 3 — Install frontend dependencies
```bash
cd explorer
npm install
npm ci
```
> **Note:** This project uses Vite 5 and requires **Node 18+**. If you are on Node 16 or earlier, upgrade first.
#### Step 4 — Start the Python backend
### 5. Start the dev server
Open a terminal in the repo root:
```bash
semantica-explorer --graph path/to/my_graph.json --no-browser
```
This starts the API on `http://127.0.0.1:8000`. Keep this terminal open.
#### Step 5 — Start the frontend dev server
Open a second terminal in `explorer/`:
```bash
npm run dev
```
Vite starts on **http://localhost:5173** by default. Open that URL in your browser.
Vite starts on **`http://localhost:5173`**. Open that URL in your browser. All `/api` and `/ws` requests are automatically proxied to the Python backend at `http://127.0.0.1:8000`.
---
## What you should see
## Building the production bundle
The Explorer opens with a persistent left sidebar and six workspace tabs:
If you need to serve the UI from the Python server directly (without the Vite dev server):
| Tab | What it shows |
|---|---|
| **Knowledge Graph** | Interactive Sigma.js canvas — nodes, edges, zoom, ForceAtlas2 layout |
| **Timeline** | Temporal event scrubber over the graph |
| **Decisions** | Causal chain viewer with outcome badges and decision filter |
| **Registry** | Live audit log of every graph mutation (add-node, add-edge, etc.) |
| **Entity Resolution** | Duplicate detection and entity merge workflow |
```bash
cd explorer
npm ci
npm run build
```
This writes the compiled assets to `../semantica/static/`. The Python server then serves the full dashboard at `http://127.0.0.1:8000` — no separate Vite process needed.
---
## Workspaces
| Workspace | What you can do |
| --- | --- |
| **Knowledge Graph** | Live Sigma.js canvas · ForceAtlas2 layout · Ego Mode · semantic distance heatmap · path highlighting |
| **Timeline** | Temporal event scrubber — watch the graph evolve across time |
| **Decisions** | Browse causal chains behind every recorded decision with outcome badges and confidence scores |
| **Registry** | Live audit log of every graph mutation (add-node, add-edge, delete, update) |
| **Entity Resolution** | Review and merge duplicate entities with blocking + semantic dedup |
| **KG Overview** | Aggregate stats, community breakdown, centrality heatmap |
| **Ontology** | SKOS/OWL vocabulary hierarchy and schema summary |
| **Ontology Hub** | SHACL Studio · visual drag-and-drop editor · cross-ontology alignments · SKOS browser |
| **Lineage** | W3C PROV-O provenance visualization for any entity |
---
## Project structure
## Environment variables
```
explorer/
├── src/
│ ├── App.tsx # Root layout, tab routing, workspace wiring
│ ├── index.css # Global resets, fonts, keyframe animations
│ ├── store/
│ │ └── registryStore.ts # Pub/sub audit registry (no external state lib)
│ └── workspaces/
│ ├── GraphWorkspace/ # Sigma.js graph canvas + inspector panel
│ ├── DecisionWorkspace/ # Causal flow diagram + decision list
│ ├── TimelineWorkspace/ # vis-timeline temporal scrubber
│ ├── ManageWorkspace/ # Registry, KG Overview, Ontology tabs
│ └── EnrichWorkspace/ # Entity resolution tab
├── index.html
├── vite.config.ts # Dev proxy → 127.0.0.1:8000, build → ../semantica/static
└── package.json
```
| Variable | Default | Description |
| --- | --- | --- |
| `EXPLORER_CORS_ORIGINS` | `http://localhost:5173,http://127.0.0.1:5173` | Comma-separated list of allowed CORS origins |
| `EXPLORER_CORS_CREDENTIALS` | `false` | Set to `true` to allow credentialed cross-origin requests (only needed behind an authenticating reverse proxy) |
---
@@ -122,7 +159,7 @@ Run these from inside the `explorer/` directory:
# Start the dev server with hot module replacement
npm run dev
# Type-check and build a production bundle into ../semantica/static
# Type-check and build the production bundle into ../semantica/static/
npm run build
# Preview the production build locally
@@ -133,65 +170,104 @@ npm run lint
# Run the graph store multi-edge unit tests
npm run test:graph-store
# Run the graph workspace display tests
npm run test:graph-workspace
```
---
## API & WebSocket proxy
## API & WebSocket proxy (dev mode only)
During development, Vite forwards requests automatically — no CORS configuration needed:
| Pattern | Forwarded to |
|---|---|
| --- | --- |
| `/api/*` | `http://127.0.0.1:8000/api/*` |
| `/ws` | `ws://127.0.0.1:8000/ws` |
| `/ws/*` | `ws://127.0.0.1:8000/ws/*` |
If you run the backend on a different port, update `server.proxy` in [vite.config.ts](vite.config.ts).
To run the backend on a different port, update `server.proxy` in [vite.config.ts](vite.config.ts).
---
## Production build
## Project structure
```bash
cd explorer
npm run build
```text
explorer/
├── src/
│ ├── App.tsx # Root layout, tab routing, workspace wiring
│ ├── index.css # Global resets, fonts, keyframe animations
│ ├── store/
│ │ ├── graphStore.ts # In-memory graph state
│ │ └── registryStore.ts # Pub/sub audit registry
│ └── workspaces/
│ ├── GraphWorkspace/ # Sigma.js canvas + inspector + behaviors
│ ├── DecisionWorkspace/ # Causal flow diagram + decision list
│ ├── DiffMergeWorkspace/ # Graph diff and merge view
│ ├── EnrichWorkspace/ # Entity resolution + registry tabs
│ ├── ImportExportWorkspace/ # Import CSV/JSON, export graph
│ ├── LineageWorkspace/ # W3C PROV-O lineage diagram
│ ├── ManageWorkspace/ # KG Overview + Ontology Summary
│ ├── OntologyWorkspace/ # SHACL Studio, visual editor, SKOS browser
│ ├── SparqlWorkspace/ # In-browser SPARQL query editor
│ └── VocabularyWorkspace/ # SKOS vocabulary manager
├── index.html
├── vite.config.ts # Dev proxy → 127.0.0.1:8000, build → ../semantica/static
└── package.json
```
The compiled assets are written to `../semantica/static/`. The Semantica Python server serves this folder automatically at its root URL — no separate web server needed.
---
## Troubleshooting
**Blank graph / no data loads**
- Make sure the Semantica backend is running (`python -m semantica.server`) before opening the UI.
- Check the browser console for failed `/api/graph` requests — the proxy target may need updating in `vite.config.ts`.
### Dashboard shows a blank white page or "UI not available" message
**`npm install` fails or hangs**
- Ensure you are using **Node 18 or 20**. Node 16 and Vite 5 are incompatible.
- Delete `node_modules/` and `package-lock.json`, then re-run `npm install`.
The frontend bundle is missing from the server's static directory. Fix options:
**Port 5173 already in use**
- Vite will automatically try the next available port and print it in the terminal. Use that URL instead.
- **If you installed via pip:** `pip install --upgrade "semantica[explorer]"` — the wheel includes the pre-built bundle.
- **If you installed from source:** run `cd explorer && npm ci && npm run build` from the repo root, then restart the server.
- **In dev mode:** use the Vite dev server at `http://localhost:5173` instead of the backend URL.
**WebSocket not connecting (real-time mutations not appearing)**
- Confirm the backend exposes a `/ws` WebSocket endpoint.
- Check browser DevTools → Network → WS tab for the connection status.
### Blank graph / no data loads in the browser
- Confirm the Python backend is running and check the terminal for errors.
- Open browser DevTools → Network tab and look for failed `/api/graph` requests.
- If the backend is on a different port, update `server.proxy` in `vite.config.ts`.
### `npm ci` fails or reports missing lockfile
The `package-lock.json` must be present. Run `npm install` once to generate it, commit it, then use `npm ci` going forward.
### `npm run dev` fails with Node version error
Vite 6 requires **Node 18 or higher**. Run `node --version` to check. If you're on Node 16, upgrade via [nvm](https://github.com/nvm-sh/nvm) or the official Node.js installer.
### Port 5173 already in use
Vite automatically tries the next available port and prints the actual URL in the terminal. Use the URL shown in the output.
### WebSocket not connecting (real-time mutations not appearing)
- Confirm the backend exposes the `/ws/graph-updates` WebSocket endpoint.
- Check DevTools → Network → WS tab for the connection status and error code.
- Ensure the backend version matches the frontend — mixing major versions can cause protocol mismatches.
---
## Tech stack
- **React 19** + TypeScript (strict `noUnusedLocals`)
- **Vite 5** with `babel-plugin-react-compiler`
- **Sigma.js 3** + **Graphology** — graph rendering and in-memory graph store
- **ForceAtlas2** — physics-based layout worker
- **@tanstack/react-query** — data fetching for ontology and vocab tabs
- **React 19** + TypeScript (strict mode)
- **Vite 6** with `babel-plugin-react-compiler`
- **Sigma.js 3** + **Graphology** — graph rendering and in-memory graph model
- **ForceAtlas2** — physics-based layout
- **@tanstack/react-query** — async data fetching for ontology and vocab tabs
- **vis-timeline** — temporal event visualization
- **@xyflow/react** — lineage diagram rendering
- **Monaco Editor** — in-browser SPARQL / SHACL editor
- **lucide-react** — icon set
---
## Contributing
See the root [CONTRIBUTING.md](../CONTRIBUTING.md) and open issues on the main [Semantica repository](https://github.com/Hawksight-AI/semantica).
See the root [CONTRIBUTING.md](../CONTRIBUTING.md) and open issues on the main [Semantica repository](https://github.com/semantica-agi/semantica).