Skip to content

[Feature] Semantica Knowledge Explorer — Interactive Dashboard for Ontology & KG Exploration #376

Description

@KaifAhmad1

Summary

Add an interactive, browser-based Knowledge Explorer dashboard that lets users visually explore,
query, filter, enrich, and govern knowledge graphs built with Semantica — without writing code.


Problem Statement

Semantica has world-class APIs for building, querying, and reasoning over knowledge graphs,
ontologies, and decision networks. However, all exploration today requires Python code. Users —
especially domain experts such as doctors, lawyers, data stewards, and compliance officers — cannot
inspect, filter, or validate the knowledge structures they depend on without developer help.

This creates a real bottleneck:

  • Knowledge enrichment requires a developer loop between the domain expert and the engineer
  • Debugging a malformed KG or incorrect ontology mapping is opaque without visual tooling
  • Auditing decision chains or provenance for compliance requires custom scripting every time
  • Onboarding new contributors takes longer when the graph can only be explored via a REPL

Semantica already has KGVisualizer, OntologyVisualizer, TemporalVisualizer, DecisionQuery,
CausalChainAnalyzer, ProvenanceTracker, and many more powerful classes. The gap is a unified
interactive surface that wires them together for end users.


Proposed Solution

Ship semantica[explorer] — an optional installable add-on that starts a local FastAPI server
serving a React dashboard. Users run one command and get a full Knowledge Explorer in the browser.

pip install semantica[explorer]
semantica-explorer --graph my_graph.json --port 8000

Browser opens at http://localhost:8000 with the full dashboard loaded.


Feature Breakdown

1. Graph Canvas — Interactive Network Explorer

An interactive force-directed graph canvas as the main workspace.

Capabilities:

  • Pan / zoom / drag nodes; force-directed, hierarchical, and circular layout modes
  • Node coloring by entity type; edge thickness/color by relationship type and weight
  • Click any node → right-side property panel (id, type, label, properties, confidence, temporal validity)
  • Right-click context menu: Expand neighbors · Find paths · Pin/hide node · Open provenance
  • Minimap for large graphs; toggle node labels on/off; search-and-focus
  • Supports ContextGraph, GraphBuilder output, FalkorDB, and Neo4j backends

Semantica APIs:

  • ContextGraph.find_nodes(), ContextGraph.get_neighbors()
  • GraphBuilder.build(), GraphAnalyzer
  • PathFinder — Dijkstra, BFS, A*, K-shortest
  • visualize_kg()fig.to_json() for Plotly embedding

2. Ontology Browser

Hierarchical viewer for OWL and RDF ontologies.

Capabilities:

  • Collapsible class tree with superclass / subclass nesting
  • Class-property matrix: which properties belong to which classes
  • Hover a class → tooltip with description, domain/range constraints, cardinality rules
  • Import ontology via file upload (Turtle .ttl, OWL/XML .owl, JSON-LD .jsonld)
  • Diff two ontology versions side-by-side (added / removed classes and properties highlighted)

Semantica APIs:

  • OntologyVisualizer, OWLExporter, RDFExporter
  • visualize_ontology()
  • RDFValidator, NamespaceManager

3. Decision & Causal Chain Viewer

Full lifecycle view for decisions recorded with AgentContext or ContextGraph.

Capabilities:

  • Chronological timeline of all decisions with confidence score badges
  • Expand any decision → full causal chain rendered as a tree
  • "Find Precedents" button → semantic similarity cards ranked by score
  • Policy compliance indicator: green ✓ / red ✗ badge per active policy
  • Side-by-side decision comparison panel (select two decisions)
  • Filter by category, date range, confidence threshold, policy

Semantica APIs:

  • DecisionQuery, CausalChainAnalyzer
  • ContextGraph.trace_decision_chain(), find_precedents(), analyze_decision_impact()
  • PolicyEngine.check_decision_rules()
  • AgentContext.record_decision()

4. Analytics Dashboard

Graph metrics and structural analysis at a glance.

Capabilities:

  • Centrality rankings table — PageRank, betweenness, closeness, eigenvector — sortable + bar chart
  • Community structure view — Louvain/Leiden detected clusters, each colored uniquely
  • Degree distribution histogram
  • Connectivity summary: density, bridges, articulation points, isolated nodes
  • "Top influencers" card: top-10 nodes by PageRank with entity labels

Semantica APIs:

  • CentralityCalculator, CommunityDetector, ConnectivityAnalyzer
  • GraphAnalyzer
  • visualize_analytics(), visualize_kg()

5. Semantic Search & Faceted Filter

Unified search bar with vector + keyword hybrid retrieval.

Capabilities:

  • Type a query → hybrid search (semantic vector + keyword BM25) over all nodes
  • Filter panel: entity type · date range (valid_from / valid_until) · confidence ≥ threshold · tags
  • Search results shown as entity cards AND simultaneously highlighted in the graph canvas
  • "Similar to this node" button on any selected node (nearest-neighbor lookup)
  • Saved filter presets

Semantica APIs:

  • VectorStore.hybrid_search() (FAISS, Pinecone, Qdrant, PgVector backends)
  • ContextGraph.find_nodes(node_type=, label=)
  • TemporalGraphQuery
  • SimilarityCalculator.cosine_similarity(v1, v2)

6. Temporal Graph Timeline

Time-travel through graph evolution.

Capabilities:

  • Horizontal scrubber slider → renders the graph as it existed at that timestamp
  • Play/pause animated evolution replay at configurable speed
  • Diff view: select two points in time → green added nodes/edges, red removed
  • Temporal pattern cards: detected trends, cycles, anomalies surfaced by TemporalPatternDetector
  • "Validity window" overlay on selected node (shows valid_from / valid_until on timeline)

Semantica APIs:

  • TemporalVersionManager, TemporalGraphQuery, TemporalPatternDetector
  • ContextGraph.find_active_nodes()
  • visualize_temporal()

7. Knowledge Enrichment Panel

Enrich the graph directly from within the dashboard.

Capabilities:

  • Paste or type free text → run entity + relation extraction → preview entities before adding
  • Link prediction: select a node → top-N candidate new edges with confidence scores, one-click accept
  • Deduplication review: run dedup scan → queue of flagged pairs, review + merge with one click
  • "Add entity" / "Add relationship" forms with type autocomplete from existing schema
  • Bulk import from pasted CSV or JSON

Semantica APIs:

  • semantic_extract.extract_entities(), extract_relations(), extract_triplets()
  • LinkPredictor.score_link(graph, n1, n2, method=)
  • DuplicateDetector.detect_duplicates(entities, threshold=)
  • EntityResolver

8. Export & Share

Get data out in any format, share views with teammates.

Capabilities:

  • Download current graph: RDF Turtle, JSON-LD, N-Triples, OWL/XML, CSV, GraphML, GEXF, Parquet
  • Export current Plotly visualization: PNG, SVG, HTML (interactive), PDF
  • Share graph state via URL — serializes current filter + graph camera position as query params
  • "Copy Cypher" — generates LPG Cypher INSERT statements for Neo4j import
  • "Copy AQL" — generates ArangoDB AQL INSERT for vertices/edges

Semantica APIs:

  • RDFExporter, CSVExporter, GraphExporter, ParquetExporter, JSONExporter
  • OWLExporter, LPGExporter, ArangoAQLExporter
  • export_rdf(), export_graph(), export_csv(), export_parquet()

9. SPARQL Query Editor

Write and run SPARQL directly against the knowledge graph.

Capabilities:

  • Monaco-based editor with SPARQL syntax highlighting, autocomplete, and error markers
  • Run query → results in sortable/filterable table below the editor
  • Results simultaneously highlighted on the graph canvas
  • Save named queries to local query library; share via permalink
  • Query history panel with re-run and result diff
  • Fallback to ContextGraph.find_nodes() when no SPARQL backend is configured

Semantica APIs:

  • TripletStore SPARQL endpoint wrapper
  • Reasoner for SPARQL-compatible rule patterns
  • ContextGraph.find_nodes() as fallback

10. Rule-Based Reasoning Playground

Interactively build and test inference rules.

Capabilities:

  • Side-by-side layout: rule editor (left) + live inference results (right)
  • Rules written in Reasoner IF/THEN format with inline examples and validation
  • Add a rule → graph canvas shows inferred new facts as a color-coded overlay (dashed edges)
  • Supports forward-chaining, Rete, deductive, and abductive reasoning modes
  • Export derived facts as new graph nodes or RDF assertions

Semantica APIs:

  • Reasoner.infer_facts(facts, rules)
  • ReteEngine
  • DeductiveReasoner, AbductiveReasoner

11. Provenance & Lineage Viewer

Full W3C PROV-O lineage for any entity in the graph.

Capabilities:

  • Select any node → W3C PROV-O style swimlane diagram renders in side panel
  • Swimlane shows: source documents → ingestion → extraction → transformation → current node state
  • Each step annotated with: timestamp, agent/process name, confidence score, source URL
  • Click any step → jump to that intermediate node in the graph canvas
  • Export lineage as PROV-N text or JSON-LD provenance report

Semantica APIs:

  • ProvenanceTracker.track_entity(), AlgorithmTrackerWithProvenance
  • GraphBuilderWithProvenance
  • export_rdf() with "json-ld" format for PROV-O export

12. Conflict Detection & Resolution Panel

Review and resolve multi-source data conflicts.

Capabilities:

  • "Scan for Conflicts" button → detects entities with conflicting property values across sources
  • Conflicts surfaced as a prioritized review queue with severity scores
  • Each conflict shows: conflicting values side-by-side, source A vs source B, confidence per source
  • Actions: Accept A · Accept B · Merge (custom value) · Defer
  • Conflict resolution audit log with timestamp and resolver identity
  • Filter queue by entity type, property name, or severity

Semantica APIs:

  • semantica.conflicts — multi-source conflict detection classes
  • EntityResolver with fuzzy/exact/semantic strategies
  • ProvenanceTracker for source attribution during resolution

13. Node Embeddings Explorer

Explore the semantic space of the knowledge graph.

Capabilities:

  • 2D and 3D scatter plot of all node embeddings via UMAP, t-SNE, or PCA (toggle between)
  • Each point colored by entity type; hover shows node label + top properties
  • Click any point → jump to that node in the graph canvas
  • Lasso-select a cluster → inspect entity breakdown panel (what semantic group is this?)
  • Animated transition when switching between dimensionality reduction algorithms
  • Nearest-neighbor cards: for selected node, show top-10 semantically similar nodes

Semantica APIs:

  • NodeEmbedder.compute_embeddings(graph, node_labels, relationship_types)
  • EmbeddingVisualizervisualize_embeddings()
  • SimilarityCalculator.cosine_similarity(v1, v2)

14. Schema & Validation Report

Validate the graph structure against schema rules.

Capabilities:

  • One-click "Validate Graph" → runs all validators and shows pass/fail summary
  • Results: errors table (blocking) + warnings table (advisory) + pass rate gauge
  • Click any error or warning row → corresponding node or edge highlighted on canvas
  • Validation history: compare current report vs last run (new errors vs resolved)
  • Download report as JSON, Markdown, or HTML
  • Custom rule input: add project-specific validation constraints

Semantica APIs:

  • GraphValidator
  • PipelineValidator.validate(builder)ValidationResult(valid, errors, warnings)
  • OntologyVisualizer for schema structure reference

15. Import Wizard & Pipeline Monitor

Bring data in from any source with guided configuration.

Capabilities:

  • Drag-and-drop file upload: PDF, DOCX, TXT, CSV, JSON-LD, Turtle, OWL/XML, XLSX
  • Field-mapping UI: configure how source columns / properties map to entity types and relations
  • Live pipeline progress: step-by-step status bar (Parse → Extract → Resolve → Build → Validate)
  • Per-step log panel: expandable logs, error counts, retry button per failed step
  • Background processing — import runs without blocking graph exploration
  • Web URL ingest: paste a URL → ingest and extract entities from web content

Semantica APIs:

  • semantica.ingest — file, web, database ingestion
  • semantica.parse — PDF, DOCX, HTML parsing
  • semantica.pipelinePipelineValidator, FailureHandler, RetryPolicy, RetryStrategy
  • FastAPI BackgroundTasks + WebSocket for live progress events

16. Change Management & Audit Trail

Git-like version history for the knowledge graph.

Capabilities:

  • Commit log: every mutation (node added/removed/modified, edge added/removed) as a timestamped entry
  • Browse to any historical commit → restore that snapshot with one click
  • Per-node change log: full history of edits to a specific node with author and diff
  • Diff viewer between any two commits: green = added, red = removed, orange = modified
  • Tag commits as named versions (e.g., v1.0-approved, pre-audit-2026)
  • Rollback protection: confirmation dialog before restoring historical state

Semantica APIs:

  • semantica.change_management — version control and audit trail classes
  • TemporalVersionManager — snapshot management
  • ContextGraph.save_to_file() / load_from_file() — checkpoint persistence

17. Entity Comparison & Merge Tool

Side-by-side deduplication and merge workflow.

Capabilities:

  • Select any two nodes in the canvas → opens side-by-side property diff panel
  • Shared properties shown with diff highlighting; unique properties clearly marked
  • "Merged preview" pane: review what the merged entity will look like before committing
  • Deduplication batch queue: "Run Dedup Scan" → all flagged pairs listed with match scores
  • Per-pair badges showing: why it was flagged (name fuzzy match / semantic similarity / property overlap)
  • Process entire queue with keyboard shortcuts for fast review

Semantica APIs:

  • DuplicateDetector.detect_duplicates(entities, threshold=)
  • EntityResolver with configurable matching strategies
  • SimilarityCalculator for per-property similarity scores

18. Collaborative Annotations

Add context and commentary directly to graph elements.

Capabilities:

  • Add sticky-note style annotations to any node or edge via right-click menu
  • Tags and labels system: custom color-coded tags with graph-wide filter support
  • Thread-style comment discussions on a node (reply, resolve, reopen)
  • Annotation visibility: public (shared with all viewers) or private (current user only)
  • Export all annotations as JSON-LD (attached to entities as metadata properties)
  • Annotations survive graph reloads and are searchable via Semantic Search

Integration approach: Annotations stored as extra properties on ContextNode / ContextEdge
via REST API using ContextGraph.add_node() with annotation metadata. No changes to Semantica core.


Recommended Tech Stack

Backend — extend semantica/server.py

Layer Choice Reason
API Framework FastAPI (already used) Async, Pydantic, OpenAPI auto-docs, WebSocket built-in
WebSocket FastAPI WebSocket Real-time graph updates, pipeline progress events
Background jobs FastAPI BackgroundTasks Long-running imports and dedup scans
Auth (optional) python-jose + OAuth2 JWT for multi-user or team deployments
Serialization Pydantic v2 Already a dependency; fast validation
Static files fastapi.staticfiles Serve React bundle from semantica/static/

Frontend

Layer Library Reason
Framework React 18 + TypeScript Largest ecosystem, type safety, mature tooling
Build Vite Sub-second HMR, lightweight production bundles
Graph Canvas Cytoscape.js + react-cytoscapejs Purpose-built for network graphs; 100k+ nodes; rich layout algorithms (CoSE, Dagre, Klay, Concentric)
3D Graph (optional) react-force-graph-3d WebGL rendering via Three.js for very large or aesthetically rich graphs
Charts Plotly.js + react-plotly.js Semantica already emits fig.to_json() — zero additional integration code
Query Editor Monaco Editor (@monaco-editor/react) SPARQL/Cypher syntax highlighting, autocomplete, error markers
UI Components Shadcn/UI + Tailwind CSS Accessible, composable, no runtime CSS-in-JS overhead
Data Fetching TanStack Query v5 Server state, background refetch, optimistic updates
Global UI State Zustand Minimal boilerplate, fine-grained subscriptions
Tables TanStack Table v8 Sortable, filterable, virtualized entity tables
Ontology Tree react-arborist Virtualized tree component; handles large OWL hierarchies
Timeline vis-timeline Robust temporal scrubber used in production graph tools
Provenance Diagram ReactFlow Node-based swimlane diagrams for PROV-O lineage
Embeddings 3D react-three-fiber + @react-three/drei WebGL 3D scatter for embedding explorer
File Upload react-dropzone Drag-and-drop import with MIME type validation

Deployment Tiers

Tier 1 — Quick Prototype (Python-only, 1-day effort)

pip install semantica[explorer-lite]

Uses streamlit + streamlit-agraph (Cytoscape.js wrapper for Streamlit).
Embeds visualize_kg() Plotly figures directly.
Best for: internal demos, Jupyter-adjacent teams, rapid iteration.
Limitation: Streamlit layout constraints; not suitable for production.

Tier 2 — Production Dashboard (recommended)

pip install semantica[explorer]
semantica-explorer --graph my_graph.json

React + FastAPI. semantica-explorer/ directory in the repo.
CI build copies React bundle to semantica/static/.
FastAPI serves the bundle at / and the API at /api/.

Tier 3 — Hosted SaaS (future roadmap)
Deploy Tier 2 on Render / Railway / Fly.io.
Multi-tenant with per-user graph namespaces and SSO.


Integration Architecture

┌──────────────────────────────────────────────────────────────┐
│                     React Dashboard (Vite)                   │
│                                                              │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐  │
│  │Graph Canvas│ │OWL Browser │ │Decision    │ │SPARQL    │  │
│  │Cytoscape.js│ │react-arbor │ │vis-timeline│ │Monaco    │  │
│  └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └────┬─────┘  │
│        │              │              │              │        │
│  ┌─────┴──────────────┴──────────────┴──────────────┴─────┐  │
│  │              TanStack Query  +  Zustand                 │  │
│  │         (REST polling + WebSocket subscriptions)        │  │
│  └──────────────────────────────────────┬─────────────────┘  │
└─────────────────────────────────────────┼────────────────────┘
                                          │  HTTP / WebSocket
┌─────────────────────────────────────────┼────────────────────┐
│                   FastAPI Server         │                    │
│  ┌───────────────────────────────────────┴──────────────┐    │
│  │  GET  /api/graph/nodes        GET  /api/graph/edges   │    │
│  │  GET  /api/graph/node/{id}/neighbors                  │    │
│  │  POST /api/graph/search       GET  /api/analytics     │    │
│  │  GET  /api/decisions          GET  /api/decisions/... │    │
│  │  GET  /api/temporal/snapshot  POST /api/enrich/...    │    │
│  │  POST /api/export             POST /api/validate      │    │
│  │  POST /api/import             WS   /ws/graph-updates  │    │
│  └───────────────────────────────────────────────────────┘    │
│                                                               │
│  ┌───────────┐  ┌──────────────┐  ┌────────────┐  ┌───────┐  │
│  │ContextGraph│  │ DecisionQuery │  │KGVisualizer│  │Vector │  │
│  │GraphBuilder│  │CausalChainAna│  │ Reasoner   │  │Store  │  │
│  │PathFinder  │  │ PolicyEngine  │  │ProvenanceTr│  │Dedup  │  │
│  └───────────┘  └──────────────┘  └────────────┘  └───────┘  │
└───────────────────────────────────────────────────────────────┘

New REST API Endpoints Required

Extend semantica/server.py:

# Graph Exploration
GET  /api/graph/nodes                  ?type=&limit=&offset=&search=
GET  /api/graph/edges                  ?source=&target=&type=
GET  /api/graph/node/{id}
GET  /api/graph/node/{id}/neighbors    ?depth=
GET  /api/graph/node/{id}/path         ?target=&algorithm=
GET  /api/graph/node/{id}/provenance
GET  /api/graph/node/{id}/history

# Search & Analytics
POST /api/graph/search                 { query, filters, limit }
GET  /api/graph/analytics              ?metrics=centrality,community,connectivity
GET  /api/graph/validation

# Decisions
GET  /api/decisions                    ?limit=&offset=&category=
GET  /api/decisions/{id}
GET  /api/decisions/{id}/chain
GET  /api/decisions/{id}/precedents
GET  /api/decisions/{id}/compliance

# Temporal
GET  /api/temporal/snapshot            ?at=<iso-datetime>
GET  /api/temporal/diff                ?from=&to=
GET  /api/temporal/patterns

# Enrichment
POST /api/enrich/extract               { text }
POST /api/enrich/links                 { node_id, top_n }
POST /api/enrich/dedup                 { threshold }
POST /api/reason                       { facts, rules, mode }

# Import / Export
POST /api/import                       multipart/form-data
POST /api/export                       { format, node_ids? }

# Annotations
GET  /api/annotations                  ?node_id=
POST /api/annotations
DELETE /api/annotations/{id}

# WebSocket
WS   /ws/graph-updates                 (import progress, graph mutations)

Pydantic schemas: NodeResponse, EdgeResponse, DecisionResponse,
AnalyticsResponse, ValidationResult, ProvenanceReport, AnnotationResponse


Files to Create / Modify

Path Action Description
semantica/server.py Modify Add all REST endpoints + WebSocket handler
semantica/kg/__init__.py Verify Ensure all analytics classes are exported
semantica/context/__init__.py Verify Ensure DecisionQuery, CausalChainAnalyzer exported
pyproject.toml Modify Add [explorer] and [explorer-lite] optional dep groups + semantica-explorer entry point
semantica/explorer/__init__.py Create Entry point: parse args, start uvicorn, open browser
semantica/explorer/routes/graph.py Create Graph node/edge/path/search endpoints
semantica/explorer/routes/decisions.py Create Decision + causal chain endpoints
semantica/explorer/routes/analytics.py Create Centrality, community, validation endpoints
semantica/explorer/routes/enrich.py Create Extract, link prediction, dedup endpoints
semantica/explorer/routes/temporal.py Create Snapshot, diff, pattern endpoints
semantica/explorer/routes/export.py Create Multi-format export endpoint
semantica/explorer/routes/annotations.py Create CRUD for collaborative annotations
semantica/explorer/schemas.py Create All Pydantic request/response models
semantica/explorer/ws.py Create WebSocket connection manager + event broadcaster
semantica-explorer/ Create Vite + React frontend project
semantica-explorer/src/components/GraphCanvas.tsx Create Cytoscape.js canvas component
semantica-explorer/src/components/OntologyTree.tsx Create react-arborist OWL tree
semantica-explorer/src/components/DecisionPanel.tsx Create Timeline + causal chain viewer
semantica-explorer/src/components/SPARQLEditor.tsx Create Monaco SPARQL editor
semantica-explorer/src/components/EmbeddingsPlot.tsx Create Plotly 2D/3D scatter
semantica/static/ Create Built React bundle served by FastAPI
tests/explorer/ Create Integration tests for all new API endpoints

Acceptance Criteria

  • pip install semantica[explorer] completes without errors on Python 3.9+
  • semantica-explorer CLI starts server and opens browser at localhost:8000
  • Graph canvas renders nodes and edges from a ContextGraph loaded via --graph arg
  • Clicking a node opens the property panel with correct data
  • Semantic search returns results highlighted in the canvas
  • Temporal scrubber renders correct graph state at a past timestamp
  • SPARQL query executes and results appear in table + canvas highlight
  • Decision timeline renders; expanding a decision shows the causal chain tree
  • Export as Turtle → file validates via rdflib.Graph().parse()
  • Import wizard accepts a CSV file and adds extracted entities to the graph
  • Validation report shows errors/warnings and clicking a row highlights the node
  • Embeddings explorer renders a 2D UMAP scatter with correct entity labels
  • All 18 panels render without JavaScript console errors
  • All new FastAPI endpoints return 200 responses with valid Pydantic schemas
  • WebSocket /ws/graph-updates broadcasts mutation events in real time
  • tests/explorer/ passes with 0 failures

Out of Scope (for this issue)

  • Real-time multi-user collaborative editing (separate issue — requires CRDT or OT)
  • Mobile / tablet responsive layout (can be added as follow-up)
  • Hosted cloud version (Tier 3 SaaS — separate roadmap item)
  • Graph database write-back to FalkorDB / Neo4j (read-only explorer first)

Related Issues / References


Opened by: @Hawksight-AI — Semantica v0.3.0 stable

Metadata

Metadata

Labels

deep-workLarge or complex change requiring deep contextenhancementNew feature or requesthelp wantedExtra attention is needed

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions