From 47764c303310bbcb58b8612ada6c3abfc21c6600 Mon Sep 17 00:00:00 2001 From: Mohd Kaif <98801504+KaifAhmad1@users.noreply.github.com> Date: Tue, 14 Apr 2026 20:32:04 +0530 Subject: [PATCH] Utils Explorer Welcome Message, Version Bump & Plugin README Overhaul (#462) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 * 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 * docs: add PR description for utils → main Co-Authored-By: Claude Sonnet 4.6 * chore: remove PR_DESCRIPTION.md Co-Authored-By: Claude Sonnet 4.6 --------- Co-authored-by: Claude Sonnet 4.6 --- explorer/package-lock.json | 4 +- plugins/.claude-plugin/README.md | 338 +++++++++++++++-------------- plugins/.cline-plugin/README.md | 14 +- plugins/.continue-plugin/README.md | 14 +- plugins/.openclaw-plugin/README.md | 6 +- plugins/.vscode-plugin/README.md | 16 +- plugins/.windsurf-plugin/README.md | 18 +- semantica/__init__.py | 2 +- semantica/explorer/app.py | 9 + 9 files changed, 236 insertions(+), 185 deletions(-) diff --git a/explorer/package-lock.json b/explorer/package-lock.json index 8bab8f57..52a29c1f 100644 --- a/explorer/package-lock.json +++ b/explorer/package-lock.json @@ -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", diff --git a/plugins/.claude-plugin/README.md b/plugins/.claude-plugin/README.md index 2b6beaad..bdf90fcb 100644 --- a/plugins/.claude-plugin/README.md +++ b/plugins/.claude-plugin/README.md @@ -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 /semantica ``` - -Install Semantica from that marketplace: - -```bash -/plugin install semantica@ -``` - -### Verify in Claude - -Run one of these in chat: - -```text /semantica:decision list /semantica:explain decision ``` -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 --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 "" "" ` -2. `/semantica:decision list` -3. `/semantica:causal chain --subject --depth 3` -4. `/semantica:explain decision ` -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 "" "" +/semantica:decision list +/semantica:causal chain --subject --depth 3 +/semantica:explain decision +/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. diff --git a/plugins/.cline-plugin/README.md b/plugins/.cline-plugin/README.md index c097b82b..5d7a17ea 100644 --- a/plugins/.cline-plugin/README.md +++ b/plugins/.cline-plugin/README.md @@ -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` diff --git a/plugins/.continue-plugin/README.md b/plugins/.continue-plugin/README.md index b1a4ca2d..ed288d0a 100644 --- a/plugins/.continue-plugin/README.md +++ b/plugins/.continue-plugin/README.md @@ -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` diff --git a/plugins/.openclaw-plugin/README.md b/plugins/.openclaw-plugin/README.md index 79ea7608..a43d2cd3 100644 --- a/plugins/.openclaw-plugin/README.md +++ b/plugins/.openclaw-plugin/README.md @@ -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) diff --git a/plugins/.vscode-plugin/README.md b/plugins/.vscode-plugin/README.md index 5a0b7531..56526018 100644 --- a/plugins/.vscode-plugin/README.md +++ b/plugins/.vscode-plugin/README.md @@ -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` diff --git a/plugins/.windsurf-plugin/README.md b/plugins/.windsurf-plugin/README.md index 4718e807..2dff4ea9 100644 --- a/plugins/.windsurf-plugin/README.md +++ b/plugins/.windsurf-plugin/README.md @@ -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` diff --git a/semantica/__init__.py b/semantica/__init__.py index 0d6a5eba..1bb20a40 100644 --- a/semantica/__init__.py +++ b/semantica/__init__.py @@ -10,7 +10,7 @@ Main exports: - Config: Configuration management """ -__version__ = "0.3.0" +__version__ = "0.4.0" __author__ = "Semantica Contributors" __license__ = "MIT" diff --git a/semantica/explorer/app.py b/semantica/explorer/app.py index a9fa25ec..93674e8f 100644 --- a/semantica/explorer/app.py +++ b/semantica/explorer/app.py @@ -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"}