Utils Explorer Welcome Message, Version Bump & Plugin README Overhaul (#462)

* Clarify plugin README install and usage steps

* feat(explorer): add welcome message to root endpoint and bump version to 0.4.0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(plugins): update all plugin READMEs for v0.4.0 with full platform list

- Rewrite main community guide with platform table (8 plugins), skills/agents
  inventory, Knowledge Explorer section, and per-platform install steps
- Add v0.4.0 badge and Knowledge Explorer section to VS Code, Cline,
  Continue, Windsurf, and OpenClaw READMEs
- Fix inconsistent tool count (12 → 17) across all READMEs
- Bump Python requirement from 3.8+ to 3.10+ across all plugins

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: add PR description for utils → main

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore: remove PR_DESCRIPTION.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Mohd Kaif
2026-04-14 20:32:04 +05:30
committed by GitHub
co-authored by Claude Sonnet 4.6
parent 055d2fd98d
commit 47764c3033
9 changed files with 236 additions and 185 deletions
+2 -2
View File
@@ -1,11 +1,11 @@
{
"name": "semantica-explorer",
"name": "semantica-knowledge-explorer",
"version": "0.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "semantica-explorer",
"name": "semantica-knowledge-explorer",
"version": "0.0.0",
"dependencies": {
"@monaco-editor/react": "^4.7.0",
+171 -167
View File
@@ -1,195 +1,171 @@
# Semantica Plugins (Community Guide)
Semantica ships a shared plugin bundle under `plugins/` with skills, agents, and hooks for knowledge graphs, context graphs, decision intelligence, reasoning, explainability, provenance, ontology, and export workflows.
> **v0.4.0** — 17 domain skills · 3 agents · 8 platform plugins · Knowledge Explorer UI
This README covers installation across every supported platform.
Semantica ships a shared plugin bundle under `plugins/` that works across every major AI coding assistant. Connect any supported platform to Semantica's knowledge graph engine for semantic extraction, decision intelligence, reasoning, provenance, ontology, and export workflows.
## Supported Platforms
---
| Platform | Method | Config file |
|---|---|---|
| Claude Code | Native plugin bundle | `plugins/.claude-plugin/plugin.json` |
| Cursor | Native plugin bundle | `plugins/.cursor-plugin/plugin.json` |
| Codex CLI | Native plugin bundle | `plugins/.codex-plugin/plugin.json` |
| Windsurf | MCP server + plugin bundle | `plugins/.windsurf-plugin/plugin.json` |
| Cline (VS Code) | MCP server + plugin bundle | `plugins/.cline-plugin/plugin.json` |
| Continue | MCP server | `plugins/.continue-plugin/plugin.json` |
| VS Code | MCP server | `plugins/.vscode-plugin/plugin.json` |
| Claude Desktop | MCP server | — (see MCP section below) |
| Any MCP client | MCP server | `python -m semantica.mcp_server` |
## Platform Plugins
Semantica provides a dedicated plugin for each platform. Every plugin shares the same `skills/`, `agents/`, and `hooks/` bundle — only the manifest format differs.
| # | Platform | Plugin Folder | Setup |
|---|----------|--------------|-------|
| 1 | **Claude Code** | `.claude-plugin/` | `claude --plugin-dir ./plugins` |
| 2 | **Cursor** | `.cursor-plugin/` | Cursor Marketplace → refresh |
| 3 | **Codex** | `.codex-plugin/` | Marketplace UI → install |
| 4 | **Cline** | `.cline-plugin/` | Cline MCP settings |
| 5 | **Windsurf** | `.windsurf-plugin/` | `mcp_config.json` |
| 6 | **Continue** | `.continue-plugin/` | `~/.continue/config.json` |
| 7 | **OpenClaw** | `.openclaw-plugin/` | `mcporter.json` |
| 8 | **VS Code** | `.vscode-plugin/` | `settings.json` MCP entry |
---
## What's Included
```
plugins/
├── skills/ # 17 domain skills (slash commands)
├── agents/ # 3 specialized agents
├── hooks/ # hooks.json
├── .claude-plugin/ # Claude Code manifest + marketplace
├── .cursor-plugin/ # Cursor manifest + marketplace
├── .codex-plugin/ # Codex manifest + marketplace
├── .cline-plugin/ # Cline manifest + marketplace
├── .windsurf-plugin/ # Windsurf manifest + marketplace
├── .continue-plugin/ # Continue manifest + marketplace
├── .openclaw-plugin/ # OpenClaw manifest + marketplace
└── .vscode-plugin/ # VS Code manifest + marketplace
```
### Skills (17)
`extract` · `ingest` · `query` · `ontology` · `validate` · `deduplicate` · `embed` · `reason` · `decision` · `causal` · `temporal` · `provenance` · `policy` · `explain` · `export` · `change` · `visualize`
### Agents (3)
`decision-advisor` · `explainability` · `kg-assistant`
---
## Prerequisites
1. Clone the repository:
```bash
git clone https://github.com/Hawksight-AI/semantica.git
cd semantica
pip install semantica # Python 3.10+
```
2. Ensure the plugin bundle exists at:
---
```text
plugins/
skills/ ← 17 domain skills
agents/ ← 3 specialized agents
hooks/ ← hooks.json
.claude-plugin/ ← Claude Code manifest
.cursor-plugin/ ← Cursor manifest
.codex-plugin/ ← Codex CLI manifest
.windsurf-plugin/← Windsurf manifest + MCP config
.cline-plugin/ ← Cline manifest + MCP config
.continue-plugin/← Continue manifest + MCP config
.vscode-plugin/ ← VS Code manifest + MCP config
## Knowledge Explorer (v0.4.0)
Launch the interactive graph dashboard:
```bash
semantica-explorer --graph my_graph.json --port 8000
```
## Plugin Contents
Open **http://localhost:5174** to explore:
- `skills/`: 17 domain skills (`causal`, `decision`, `explain`, `reason`, `temporal`, etc.)
- `agents/`: specialized agents (`decision-advisor`, `explainability`, `kg-assistant`)
- `hooks/hooks.json`: plugin hook configuration
- `.claude-plugin/plugin.json`: Claude manifest
- `.cursor-plugin/plugin.json`: Cursor manifest
- `.codex-plugin/plugin.json`: Codex manifest
- `*/marketplace.json`: local marketplace definitions
- **Graph** — interactive canvas with ForceAtlas2 layout, path highlight, community coloring
- **Decisions** — causal chains and outcome analysis
- **Reasoning** — run deductive / abductive rules
- **SPARQL** — Monaco editor for graph queries
- **Vocabulary** — ontology concept tree
- **Lineage** — provenance lineage diagram
- **Import / Export** — JSON, RDF, Parquet, GraphML
## Install and Use in Claude Code
---
### Local install (fastest)
## Installation by Platform
From the repository root:
### Claude Code
```bash
claude --plugin-dir ./plugins
```
If your Claude setup uses plugin commands in-session, use:
Or inside a session:
```bash
/plugin install ./plugins
```
### Install from a GitHub marketplace
Verify:
Add a marketplace hosted in git:
```bash
/plugin marketplace add <owner>/semantica
```
Install Semantica from that marketplace:
```bash
/plugin install semantica@<marketplace-name>
```
### Verify in Claude
Run one of these in chat:
```text
/semantica:decision list
/semantica:explain decision <decision_id>
```
If the plugin is installed correctly, Claude should recognize the `/semantica:*` skills.
---
## Install and Use in Codex
### Cursor
Cursor reads `.cursor-plugin/plugin.json` and `.cursor-plugin/marketplace.json` automatically. Publish the `plugins/` directory and refresh in Cursor Marketplace to pick up updates.
Verify:
```
/semantica:visualize topology
/semantica:reason deductive "IF Person(x) THEN Mortal(x)"
```
---
### Codex
1. Ensure your repo marketplace exists at `.agents/plugins/marketplace.json`.
2. Point the plugin entry `source.path` to `./plugins` (or your chosen plugin directory).
2. Set `source.path` to `./plugins` in the plugin entry.
3. Restart Codex and install from the marketplace UI.
Codex manifest used by this bundle:
Verify:
- `.codex-plugin/plugin.json`
### Verify in Codex
After install, run a Semantica skill command in chat, for example:
```text
```
/semantica:causal chain --subject <decision_id> --depth 3
```
## Install and Use in Cursor
---
Cursor reads plugin metadata from:
### Cline
- `.cursor-plugin/plugin.json`
- `.cursor-plugin/marketplace.json`
If you maintain a team/community plugin repo, publish this `plugins/` directory and refresh/reinstall in Cursor Marketplace to pick up updates.
### Verify in Cursor
Try one of these commands:
```text
/semantica:reason deductive "IF Person(x) THEN Mortal(x)"
/semantica:visualize topology
```
## First Commands to Try
After installing on any platform, these are good smoke tests:
1. `/semantica:decision record <category> "<scenario>" "<reasoning>" <outcome> <confidence>`
2. `/semantica:decision list`
3. `/semantica:causal chain --subject <decision_id> --depth 3`
4. `/semantica:explain decision <decision_id>`
5. `/semantica:validate graph`
## MCP Server (Windsurf · Cline · Continue · VS Code · Claude Desktop · Any tool)
Semantica includes a full MCP server (`semantica/mcp_server.py`) that exposes 12 tools and 3 resources over stdio — compatible with any MCP-aware tool.
### Start the server
```bash
python -m semantica.mcp_server
```
### Configure in your tool
**Claude Desktop**`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"semantica": {
"command": "python",
"args": ["-m", "semantica.mcp_server"]
}
}
}
```
**Windsurf**`~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"semantica": {
"command": "python",
"args": ["-m", "semantica.mcp_server"]
}
}
}
```
**Cline** — Cline MCP settings panel → Add server:
In Cline MCP settings, add:
```json
{
"semantica": {
"command": "python",
"args": ["-m", "semantica.mcp_server"]
"args": ["-m", "semantica.mcp_server"],
"env": {}
}
}
```
**Continue**`~/.continue/config.json`:
---
### Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"semantica": {
"command": "python",
"args": ["-m", "semantica.mcp_server"]
}
}
}
```
---
### Continue
Add to `~/.continue/config.json`:
```json
{
@@ -203,7 +179,50 @@ python -m semantica.mcp_server
}
```
**VS Code** `settings.json`:
All 17 Semantica skills appear in the `@semantica` context provider dropdown.
---
### OpenClaw
Add to `~/.openclaw/mcporter.json`:
```json
{
"mcpServers": {
"semantica": {
"command": "python",
"args": ["-m", "semantica.mcp_server"],
"transport": "stdio"
}
}
}
```
Then restart the gateway:
```bash
openclaw gateway restart
```
---
### VS Code
Add to `settings.json` (GitHub Copilot Chat):
```json
{
"github.copilot.chat.mcp.servers": {
"semantica": {
"command": "python",
"args": ["-m", "semantica.mcp_server"]
}
}
}
```
Or for the VS Code MCP extension:
```json
{
@@ -216,40 +235,25 @@ python -m semantica.mcp_server
}
```
### Available MCP tools
---
| Tool | Description |
|---|---|
| `extract_entities` | Named entity recognition from text |
| `extract_relations` | Relation and triplet extraction from text |
| `record_decision` | Record a decision with full context and metadata |
| `query_decisions` | Query recorded decisions by natural language or category |
| `find_precedents` | Find past decisions similar to a scenario |
| `get_causal_chain` | Trace upstream/downstream causal chain from a decision |
| `add_entity` | Add a node/entity to the knowledge graph |
| `add_relationship` | Add a directed edge between two entities |
| `run_reasoning` | Run IF/THEN rules over facts to derive new facts |
| `get_graph_analytics` | PageRank centrality and community detection |
| `export_graph` | Export graph as Turtle, JSON-LD, N-Triples, or JSON |
| `get_graph_summary` | Node count, decision count, graph status |
## First Commands to Try
### Available MCP resources
After installing on any platform:
| URI | Description |
|---|---|
| `semantica://graph/summary` | High-level graph statistics |
| `semantica://decisions/list` | All recorded decisions |
| `semantica://schema/info` | Server info and capability list |
```
/semantica:decision record <category> "<scenario>" "<reasoning>" <outcome> <confidence>
/semantica:decision list
/semantica:causal chain --subject <decision_id> --depth 3
/semantica:explain decision <decision_id>
/semantica:validate graph
/semantica:visualize topology
```
### Environment variables
| Variable | Description |
|---|---|
| `SEMANTICA_KG_PATH` | Path to a persisted graph to load on start |
| `SEMANTICA_LOG_LEVEL` | Log level: DEBUG, INFO, WARNING (default: WARNING) |
---
## Community Notes
- Keep plugin name/version/keywords updated in each manifest before publishing.
- Keep skill frontmatter consistent (`name` + `description`) for reliable discovery.
- For open-source sharing, include this folder as-is so skills, agents, and hooks remain bundled.
- Keep `name` / `version` / `keywords` updated in each manifest before publishing.
- Keep skill frontmatter (`name` + `description`) consistent for reliable discovery.
- Include `plugins/` as-is when sharing — skills, agents, and hooks must stay bundled.
+11 -3
View File
@@ -1,6 +1,6 @@
# Semantica — Cline Plugin
Adds all 17 Semantica skills, 3 agents, and hook configuration to Cline (VS Code extension).
> **v0.4.0** — Adds all 17 Semantica skills, 3 agents, and hook configuration to Cline (VS Code extension).
## MCP Server Setup (recommended)
@@ -16,9 +16,17 @@ In Cline settings, add a new MCP server:
}
```
Cline will discover all 12 Semantica tools automatically on connection.
Cline will discover all 17 Semantica skills and 3 agents automatically on connection.
## Knowledge Explorer
```bash
semantica-explorer --graph my_graph.json --port 8000
```
Open `http://localhost:5174` for the interactive dashboard.
## Requirements
- Python 3.8+
- Python 3.10+
- `pip install semantica`
+11 -3
View File
@@ -1,6 +1,6 @@
# Semantica — Continue Plugin
Adds Semantica as an MCP server and context provider to [Continue.dev](https://continue.dev).
> **v0.4.0** — Adds Semantica as an MCP server and context provider to [Continue.dev](https://continue.dev).
## MCP Server Setup
@@ -18,9 +18,17 @@ Add to `~/.continue/config.json`:
}
```
Continue will show all Semantica tools in the `@semantica` context provider dropdown.
Continue will show all 17 Semantica skills in the `@semantica` context provider dropdown.
## Knowledge Explorer
```bash
semantica-explorer --graph my_graph.json --port 8000
```
Open `http://localhost:5174` for the interactive graph dashboard.
## Requirements
- Python 3.8+
- Python 3.10+
- `pip install semantica`
+3 -3
View File
@@ -1,6 +1,6 @@
# Semantica — OpenClaw Plugin
Adds all 17 Semantica skills, 3 agents, and the full MCP integration to [OpenClaw](https://openclaw.ai) — the open-source personal AI agent platform.
> **v0.4.0** — Adds all 17 Semantica skills, 3 agents, and the full MCP integration to [OpenClaw](https://openclaw.ai) — the open-source personal AI agent platform.
## MCP Server Setup (recommended)
@@ -32,7 +32,7 @@ Paste the following into your OpenClaw `mcporter.json` (usually `~/.openclaw/mcp
openclaw gateway restart
```
OpenClaw will automatically discover all 12 Semantica tools and 3 resources.
OpenClaw will automatically discover all 17 Semantica tools and 3 agents.
## Skills
@@ -57,6 +57,6 @@ See [`integrations/openclaw/README.md`](../../integrations/openclaw/README.md) f
## Requirements
- Python 3.8+
- Python 3.10+
- `pip install semantica`
- OpenClaw — [openclaw.ai](https://openclaw.ai)
+14 -2
View File
@@ -1,6 +1,6 @@
# Semantica — VS Code Plugin
Adds Semantica as an MCP server to VS Code (via GitHub Copilot Chat or any MCP-aware extension).
> **v0.4.0** — Adds Semantica as an MCP server to VS Code (via GitHub Copilot Chat or any MCP-aware extension).
## MCP Server Setup
@@ -30,7 +30,19 @@ Or if using the VS Code MCP extension directly:
}
```
VS Code will discover all 17 Semantica skills and 3 agents automatically on connection.
## Knowledge Explorer
Launch the interactive graph dashboard from the terminal:
```bash
semantica-explorer --graph my_graph.json --port 8000
```
Open `http://localhost:5174` to explore nodes, edges, decisions, SPARQL, lineage, and more.
## Requirements
- Python 3.8+
- Python 3.10+
- `pip install semantica`
+14 -4
View File
@@ -1,6 +1,6 @@
# Semantica — Windsurf Plugin
Adds all 17 Semantica skills, 3 agents, and hook configuration to Windsurf.
> **v0.4.0** — Adds all 17 Semantica skills, 3 agents, and hook configuration to Windsurf.
## MCP Server Setup (recommended)
@@ -17,13 +17,23 @@ Add to your Windsurf MCP config (`~/.codeium/windsurf/mcp_config.json`):
}
```
Windsurf will then have access to all 12 Semantica tools (extract, record_decision, query_decisions, find_precedents, get_causal_chain, add_entity, add_relationship, run_reasoning, get_graph_analytics, export_graph, and more) directly in the AI panel.
Windsurf will have access to all 17 Semantica skills (`extract`, `record_decision`, `query_decisions`, `find_precedents`, `get_causal_chain`, `add_entity`, `add_relationship`, `run_reasoning`, `get_graph_analytics`, `export_graph`, and more) directly in the AI panel.
## Skills
All 17 skills under `plugins/skills/` are available as slash commands once the plugin is loaded.
All 17 skills under `plugins/skills/` are available as slash commands once the plugin is loaded:
`extract` · `ingest` · `query` · `ontology` · `validate` · `deduplicate` · `embed` · `reason` · `decision` · `causal` · `temporal` · `provenance` · `policy` · `explain` · `export` · `change` · `visualize`
## Knowledge Explorer
```bash
semantica-explorer --graph my_graph.json --port 8000
```
Open `http://localhost:5174` for the interactive graph dashboard.
## Requirements
- Python 3.8+
- Python 3.10+
- `pip install semantica`
+1 -1
View File
@@ -10,7 +10,7 @@ Main exports:
- Config: Configuration management
"""
__version__ = "0.3.0"
__version__ = "0.4.0"
__author__ = "Semantica Contributors"
__license__ = "MIT"
+9
View File
@@ -127,6 +127,15 @@ def create_app(session: Optional[GraphSession] = None) -> FastAPI:
except WebSocketDisconnect:
manager.disconnect(websocket)
@app.get("/", include_in_schema=False)
async def root():
return {
"message": "Welcome to Semantica Knowledge Explorer",
"version": __version__,
"ui": "http://localhost:5174",
"docs": "http://localhost:8000/docs",
}
@app.get("/api/health")
async def health():
return {"status": "healthy"}