diff --git a/README.md b/README.md index dd0e2abe..c1b2f68c 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ [![CI](https://github.com/Hawksight-AI/semantica/workflows/CI/badge.svg)](https://github.com/Hawksight-AI/semantica/actions) [![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?logo=discord&logoColor=white)](https://discord.gg/sV34vps5hH) [![X](https://img.shields.io/badge/X-Follow%20Semantica-black?logo=x&logoColor=white)](https://x.com/BuildSemantica) +[![OpenClaw](https://img.shields.io/badge/OpenClaw-Plugin-FF3B30?logo=github&logoColor=white)](https://openclaw.ai) ### โญ Give us a Star ยท ๐Ÿด Fork us ยท ๐Ÿ’ฌ Join our Discord ยท ๐Ÿฆ Follow on X @@ -55,39 +56,68 @@ pip install semantica ## ๐Ÿ”Œ Works With Every AI Tool -Semantica ships **native plugin bundles** for Claude Code, Cursor, and Codex, an **MCP server** (`python -m semantica.mcp_server`) for Windsurf, Cline, Continue, VS Code, and Claude Desktop, and a **REST API** (FastAPI, port 8000) for any other tool. +Semantica ships **native plugin bundles** for Claude Code, Cursor, and Codex, an **MCP server** (`python -m semantica.mcp_server`) for Windsurf, Cline, Continue, VS Code, Claude Desktop, and OpenClaw, and a **REST API** (FastAPI, port 8000) for any other tool. + + + + + + + + + + + + + + + + + - - - - - + + + + + + + +
๐Ÿ”Œ Native Plugin Bundleโšก MCP Server + Plugin
Claude Code
Claude Code
-Native plugin ยท 17 skills ยท 3 agents ยท hooks +17 skills ยท 3 agents ยท hooks 		Cursor
Cursor
-Native plugin ยท 17 skills ยท 3 agents +17 skills ยท 3 agents 		Codex CLI
Codex CLI
-Native plugin ยท 17 skills ยท 3 agents +17 skills ยท 3 agents 		Windsurf
Windsurf
-MCP server + plugin +plugin 		-Claude Desktop
-Claude Desktop
-MCP server +Cline
+Cline
+plugin +		 +Continue
+Continue
+plugin 		VS Code
VS Code
-MCP server + plugin +plugin +		 +OpenClaw
+OpenClaw
+MCP + plugin +
โ˜๏ธ MCP Server๐ŸŒ REST API
+Claude Desktop
+Claude Desktop
+MCP server 		GitHub Copilot
@@ -95,23 +125,11 @@ Semantica ships **native plugin bundles** for Claude Code, Cursor, and Codex, an REST API 		-Cline
-Cline
-MCP server + plugin -
Roo Code
Roo Code
REST API 		-Continue
-Continue
-MCP server + plugin -		 Goose
Goose
REST API @@ -136,12 +154,20 @@ Semantica ships **native plugin bundles** for Claude Code, Cursor, and Codex, an Zed
REST API 		+
๐Ÿ”ง Any Tool
REST API
Any agent
-REST API +109 REST endpoints ยท FastAPI ยท port 8000
### Plugin Bundles (Claude Code ยท Cursor ยท Codex) @@ -157,6 +183,7 @@ Native plugin bundles live under [`plugins/`](plugins/). Each directory contains | Cline | [`plugins/.cline-plugin/`](plugins/.cline-plugin/) | 17 skills ยท 3 agents ยท MCP config | | Continue | [`plugins/.continue-plugin/`](plugins/.continue-plugin/) | 17 skills ยท 3 agents ยท MCP config | | VS Code | [`plugins/.vscode-plugin/`](plugins/.vscode-plugin/) | 17 skills ยท 3 agents ยท MCP config | +| OpenClaw | [`plugins/.openclaw-plugin/`](plugins/.openclaw-plugin/) | 17 skills ยท 3 agents ยท MCP config | **17 domain skills:** diff --git a/integrations/openclaw/README.md b/integrations/openclaw/README.md new file mode 100644 index 00000000..2ec29d90 --- /dev/null +++ b/integrations/openclaw/README.md @@ -0,0 +1,137 @@ +# Semantica ร— OpenClaw Integration + +Connect [OpenClaw](https://openclaw.ai) โ€” the open-source personal AI agent โ€” to Semantica's full knowledge-graph and decision-intelligence stack. + +Two integration paths are available: + +| Path | When to use | +|---|---| +| **MCP (recommended)** | OpenClaw Gateway is running; zero extra code needed | +| **REST / native tool** | Embedding Semantica directly in a SOUL.md agent config | + +--- + +## Path 1 โ€” MCP Server (recommended) + +### 1. Start the Semantica MCP server + +```bash +python -m semantica.mcp_server +``` + +### 2. Add to `mcporter.json` + +```json +{ + "mcpServers": { + "semantica": { + "command": "python", + "args": ["-m", "semantica.mcp_server"], + "transport": "stdio" + } + } +} +``` + +### 3. Restart the OpenClaw Gateway + +```bash +openclaw gateway restart +``` + +All **12 Semantica tools** are now available to any OpenClaw agent: + +| Tool | What it does | +|---|---| +| `extract_entities` | Named entity recognition from text | +| `extract_relations` | Relation / triplet extraction from text | +| `record_decision` | Record a decision with causal links | +| `query_decisions` | Search recorded decisions | +| `find_precedents` | Find past decisions similar to a query | +| `get_causal_chain` | Trace cause-effect chains from a node | +| `add_entity` | Add a node to the knowledge graph | +| `add_relationship` | Add an edge between two nodes | +| `run_reasoning` | Forward-chain rules over facts | +| `get_graph_analytics` | Centrality, communities, topology stats | +| `export_graph` | Export graph (JSON, RDF, GraphML, โ€ฆ) | +| `get_graph_summary` | High-level graph overview | + +**3 resources** are also exposed: `semantica://graph/summary`, `semantica://decisions/list`, `semantica://schema/info`. + +--- + +## Path 2 โ€” Native Tool (REST) + +Use `OpenClawKGTool` when you prefer a direct Python integration without the MCP gateway. + +### Install + +```bash +pip install semantica[openclaw] # pulls in 'requests' +``` + +### Quick start + +```python +from integrations.openclaw import OpenClawKGTool + +tool = OpenClawKGTool(base_url="http://localhost:8000") + +# Extract knowledge from text +entities = tool.extract_entities("OpenClaw is an open-source AI agent built in Python.") +relations = tool.extract_relations("Alice manages the OpenClaw project at Hawksight.") + +# Record and query decisions +tool.record_decision("Deploy model v2 to production", context="latency improved by 40%") +precedents = tool.find_precedents("roll back production deployment") + +# Graph analytics +summary = tool.get_graph_summary() +analytics = tool.get_graph_analytics() + +# Export +ttl = tool.export_graph(fmt="ttl") +``` + +### Generate `mcporter.json` programmatically + +```python +from integrations.openclaw import OpenClawMCPConfig + +cfg = OpenClawMCPConfig() +print(cfg.to_json()) # โ†’ paste into mcporter.json +``` + +--- + +## SOUL.md agent snippet + +Add Semantica to any OpenClaw agent by referencing the tool in your `SOUL.md`: + +```markdown +## Tools + +- name: semantica_kg + description: > + Semantica knowledge-graph tool. Supports entity extraction, decision + recording, graph querying, causal chain analysis, reasoning, and + multi-format export. + endpoint: http://localhost:8000 + auth: none + +## Instructions + +You have access to `semantica_kg`. Use it to: +- Extract entities and relations from any text the user provides. +- Record important decisions and retrieve precedents before recommending actions. +- Run graph analytics and export results when the user asks for a summary. +``` + +--- + +## Requirements + +- Python 3.8+ +- `pip install semantica` (core) +- `pip install semantica[openclaw]` (adds `requests` for the REST path) +- OpenClaw โ‰ฅ latest โ€” [openclaw.ai](https://openclaw.ai) diff --git a/integrations/openclaw/__init__.py b/integrations/openclaw/__init__.py new file mode 100644 index 00000000..b1e55431 --- /dev/null +++ b/integrations/openclaw/__init__.py @@ -0,0 +1,57 @@ +""" +Semantica ร— OpenClaw Integration +================================== + +First-class integration between the Semantica semantic intelligence stack and +`OpenClaw `_ โ€” the open-source personal AI agent platform. + +OpenClaw connects to external tools via MCP (Model Context Protocol). This +integration exposes the full Semantica MCP surface (12 tools, 3 resources) to +any OpenClaw agent and also ships a lightweight ``OpenClawKGTool`` that can be +dropped directly into an OpenClaw SOUL.md tool-list as a native tool. + +Public surface +-------------- +OpenClawKGTool โ€” Thin wrapper around the Semantica REST API usable as an + OpenClaw native tool (no MCP gateway required) +OpenClawMCPConfig โ€” Helper that emits the ``mcporter.json`` snippet needed to + wire Semantica's MCP server into an OpenClaw gateway + +Quick start +----------- + pip install semantica + + >>> from integrations.openclaw import OpenClawKGTool, OpenClawMCPConfig + >>> print(OpenClawMCPConfig().to_json()) # paste into mcporter.json + >>> tool = OpenClawKGTool(base_url="http://localhost:8000") + >>> result = tool.extract("OpenClaw is an open-source AI agent framework.") + +MCP quick start +--------------- +Run the Semantica MCP server once:: + + python -m semantica.mcp_server + +Then add the printed config snippet to your OpenClaw ``mcporter.json`` and +restart the OpenClaw Gateway:: + + openclaw gateway restart + +All 12 Semantica tools are then available as native OpenClaw agent tools. + +Compatibility +------------- +Requires ``semantica >= 0.3.0``. The MCP path requires ``python >= 3.8`` and +a running ``semantica.mcp_server`` instance. The REST path requires a running +``semantica.server`` instance (``python -m semantica.server``, port 8000 by +default). +""" + +from .mcp_tool import OpenClawKGTool, OpenClawMCPConfig + +__all__ = [ + "OpenClawKGTool", + "OpenClawMCPConfig", +] + +__version__ = "0.1.0" diff --git a/integrations/openclaw/mcp_tool.py b/integrations/openclaw/mcp_tool.py new file mode 100644 index 00000000..dff6b6db --- /dev/null +++ b/integrations/openclaw/mcp_tool.py @@ -0,0 +1,253 @@ +""" +OpenClaw โ†” Semantica bridge +============================ + +Two integration paths: + +1. **MCP (recommended)** โ€” ``OpenClawMCPConfig`` emits the ``mcporter.json`` + snippet that wires Semantica's MCP server into the OpenClaw Gateway. + All 12 Semantica MCP tools become native OpenClaw agent tools with no + extra code. + +2. **REST** โ€” ``OpenClawKGTool`` is a plain Python class that calls the + Semantica REST API (port 8000) and can be registered as an OpenClaw + native tool via SOUL.md ``tools:`` entries. +""" + +from __future__ import annotations + +import json +from typing import Any, Dict, List, Optional + + +# --------------------------------------------------------------------------- +# MCP config helper +# --------------------------------------------------------------------------- + +class OpenClawMCPConfig: + """ + Generates the ``mcporter.json`` entry needed to connect Semantica's MCP + server to the OpenClaw Gateway. + + Parameters + ---------- + server_command: + Shell command used to launch the Semantica MCP server. + Defaults to ``"python -m semantica.mcp_server"``. + transport: + MCP transport protocol. OpenClaw supports ``"stdio"`` (default) + and ``"sse"``. + name: + Key used in ``mcporter.json``. Defaults to ``"semantica"``. + + Example + ------- + >>> cfg = OpenClawMCPConfig() + >>> print(cfg.to_json()) + # โ†’ paste into ~/.openclaw/mcporter.json, then: + # โ†’ openclaw gateway restart + """ + + def __init__( + self, + server_command: str = "python -m semantica.mcp_server", + transport: str = "stdio", + name: str = "semantica", + ) -> None: + self.server_command = server_command + self.transport = transport + self.name = name + + def to_dict(self) -> Dict[str, Any]: + """Return the config as a plain dict.""" + parts = self.server_command.split() + return { + "mcpServers": { + self.name: { + "command": parts[0], + "args": parts[1:], + "transport": self.transport, + } + } + } + + def to_json(self, indent: int = 2) -> str: + """Return the config as a JSON string.""" + return json.dumps(self.to_dict(), indent=indent) + + def __repr__(self) -> str: # pragma: no cover + return f"OpenClawMCPConfig(name={self.name!r}, transport={self.transport!r})" + + +# --------------------------------------------------------------------------- +# REST-based native tool +# --------------------------------------------------------------------------- + +class OpenClawKGTool: + """ + A Semantica knowledge-graph tool callable from an OpenClaw agent. + + Wraps the Semantica REST API so that an OpenClaw agent configured with + this tool (via SOUL.md ``tools:`` entries or programmatic registration) + can extract entities, record decisions, query the graph, and more โ€” + without requiring the MCP gateway. + + Parameters + ---------- + base_url: + Base URL of the running Semantica REST server. + Defaults to ``"http://localhost:8000"``. + timeout: + Request timeout in seconds. Defaults to ``30``. + + Notes + ----- + ``requests`` is used for HTTP calls. It is listed as an optional + dependency under ``semantica[openclaw]``; install it with:: + + pip install semantica[openclaw] + """ + + TOOL_NAME = "semantica_kg" + TOOL_DESCRIPTION = ( + "Semantica knowledge-graph tool. " + "Supports entity extraction, decision recording, graph querying, " + "causal chain analysis, reasoning, and multi-format export." + ) + + def __init__(self, base_url: str = "http://localhost:8000", timeout: int = 30) -> None: + self.base_url = base_url.rstrip("/") + self.timeout = timeout + self._session: Any = None + + # ------------------------------------------------------------------ + # Internal helpers + # ------------------------------------------------------------------ + + def _get_session(self) -> Any: + if self._session is None: + try: + import requests + self._session = requests.Session() + except ImportError as exc: + raise ImportError( + "The 'requests' package is required for OpenClawKGTool. " + "Install it with: pip install semantica[openclaw]" + ) from exc + return self._session + + def _post(self, endpoint: str, payload: Dict[str, Any]) -> Dict[str, Any]: + session = self._get_session() + url = f"{self.base_url}{endpoint}" + response = session.post(url, json=payload, timeout=self.timeout) + response.raise_for_status() + return response.json() + + def _get(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]: + session = self._get_session() + url = f"{self.base_url}{endpoint}" + response = session.get(url, params=params or {}, timeout=self.timeout) + response.raise_for_status() + return response.json() + + # ------------------------------------------------------------------ + # Extraction + # ------------------------------------------------------------------ + + def extract(self, text: str) -> Dict[str, Any]: + """Extract entities and relations from *text*.""" + return self._post("/extract", {"text": text}) + + def extract_entities(self, text: str) -> List[Dict[str, Any]]: + """Return only the entity list from *text*.""" + result = self.extract(text) + return result.get("entities", []) + + def extract_relations(self, text: str) -> List[Dict[str, Any]]: + """Return only the relation list from *text*.""" + result = self.extract(text) + return result.get("relations", []) + + # ------------------------------------------------------------------ + # Graph mutation + # ------------------------------------------------------------------ + + def add_entity(self, label: str, entity_type: str = "Entity", **properties: Any) -> Dict[str, Any]: + """Add a node to the knowledge graph.""" + return self._post("/entities", {"label": label, "type": entity_type, **properties}) + + def add_relationship( + self, + source: str, + target: str, + relation_type: str, + **properties: Any, + ) -> Dict[str, Any]: + """Add an edge between *source* and *target*.""" + return self._post( + "/relationships", + {"source": source, "target": target, "type": relation_type, **properties}, + ) + + # ------------------------------------------------------------------ + # Decisions + # ------------------------------------------------------------------ + + def record_decision( + self, + decision_text: str, + context: Optional[str] = None, + **metadata: Any, + ) -> Dict[str, Any]: + """Record a decision in the graph.""" + payload: Dict[str, Any] = {"decision": decision_text} + if context: + payload["context"] = context + payload.update(metadata) + return self._post("/decisions", payload) + + def query_decisions(self, query: str, limit: int = 10) -> List[Dict[str, Any]]: + """Search recorded decisions.""" + result = self._get("/decisions/search", {"q": query, "limit": limit}) + return result.get("decisions", []) + + def find_precedents(self, decision_text: str, top_k: int = 5) -> List[Dict[str, Any]]: + """Find past decisions similar to *decision_text*.""" + result = self._post("/decisions/precedents", {"decision": decision_text, "top_k": top_k}) + return result.get("precedents", []) + + # ------------------------------------------------------------------ + # Analytics & reasoning + # ------------------------------------------------------------------ + + def get_causal_chain(self, node_id: str, depth: int = 3) -> Dict[str, Any]: + """Retrieve the causal chain rooted at *node_id*.""" + return self._get("/causal-chain", {"node_id": node_id, "depth": depth}) + + def run_reasoning(self, rules: List[str], facts: List[str]) -> Dict[str, Any]: + """Run the Semantica forward-chaining reasoner.""" + return self._post("/reason", {"rules": rules, "facts": facts}) + + def get_graph_analytics(self) -> Dict[str, Any]: + """Return graph-level analytics (centrality, communities, etc.).""" + return self._get("/analytics") + + # ------------------------------------------------------------------ + # Export + # ------------------------------------------------------------------ + + def export_graph(self, fmt: str = "json") -> str: + """Export the graph in *fmt* (``json``, ``ttl``, ``graphml``, โ€ฆ).""" + result = self._get("/export", {"format": fmt}) + return result.get("data", "") + + # ------------------------------------------------------------------ + # Summary + # ------------------------------------------------------------------ + + def get_graph_summary(self) -> Dict[str, Any]: + """Return a high-level summary of the current graph.""" + return self._get("/graph/summary") + + def __repr__(self) -> str: # pragma: no cover + return f"OpenClawKGTool(base_url={self.base_url!r})" diff --git a/plugins/.openclaw-plugin/README.md b/plugins/.openclaw-plugin/README.md new file mode 100644 index 00000000..79ea7608 --- /dev/null +++ b/plugins/.openclaw-plugin/README.md @@ -0,0 +1,62 @@ +# 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. + +## MCP Server Setup (recommended) + +### 1. Start the Semantica MCP server + +```bash +python -m semantica.mcp_server +``` + +### 2. Add to `mcporter.json` + +Paste the following into your OpenClaw `mcporter.json` (usually `~/.openclaw/mcporter.json`): + +```json +{ + "mcpServers": { + "semantica": { + "command": "python", + "args": ["-m", "semantica.mcp_server"], + "transport": "stdio" + } + } +} +``` + +### 3. Restart the OpenClaw Gateway + +```bash +openclaw gateway restart +``` + +OpenClaw will automatically discover all 12 Semantica tools and 3 resources. + +## Skills + +All 17 skills under [`plugins/skills/`](../skills/) are available once the plugin is loaded: + +`extract` ยท `ingest` ยท `query` ยท `ontology` ยท `validate` ยท `deduplicate` ยท `embed` ยท `reason` ยท `decision` ยท `causal` ยท `temporal` ยท `provenance` ยท `policy` ยท `explain` ยท `export` ยท `change` ยท `visualize` + +## Native Tool (REST, no MCP gateway) + +For agents that cannot use the MCP gateway, use the `OpenClawKGTool` REST wrapper: + +```python +from integrations.openclaw import OpenClawKGTool + +tool = OpenClawKGTool(base_url="http://localhost:8000") +entities = tool.extract_entities("Alice manages the project.") +tool.record_decision("Deploy model v2 to production") +summary = tool.get_graph_summary() +``` + +See [`integrations/openclaw/README.md`](../../integrations/openclaw/README.md) for the full guide, including SOUL.md agent snippets. + +## Requirements + +- Python 3.8+ +- `pip install semantica` +- OpenClaw โ€” [openclaw.ai](https://openclaw.ai) diff --git a/plugins/.openclaw-plugin/marketplace.json b/plugins/.openclaw-plugin/marketplace.json new file mode 100644 index 00000000..93f5060b --- /dev/null +++ b/plugins/.openclaw-plugin/marketplace.json @@ -0,0 +1,18 @@ +{ + "name": "semantica-openclaw", + "plugins": [ + { + "name": "semantica", + "description": "Semantica plugin for OpenClaw: knowledge graph skills, decision intelligence, reasoning, extraction, and visualization.", + "source": "./", + "category": "Productivity", + "tags": [ + "knowledge-graph", + "reasoning", + "semantica", + "openclaw", + "mcp" + ] + } + ] +} diff --git a/plugins/.openclaw-plugin/plugin.json b/plugins/.openclaw-plugin/plugin.json new file mode 100644 index 00000000..0489b609 --- /dev/null +++ b/plugins/.openclaw-plugin/plugin.json @@ -0,0 +1,46 @@ +{ + "name": "semantica-openclaw", + "displayName": "Semantica OpenClaw Plugin", + "description": "Semantica plugin for OpenClaw: knowledge graph skills, decision intelligence, reasoning, extraction, and visualization via MCP and native REST tool.", + "version": "0.1.0", + "author": { + "name": "Semantica Contributors" + }, + "homepage": "https://github.com/Hawksight-AI/semantica", + "repository": "https://github.com/Hawksight-AI/semantica", + "license": "MIT", + "keywords": [ + "semantica", + "knowledge graph", + "openclaw", + "context graphs", + "decision intelligence", + "explainability", + "causal analysis", + "provenance", + "ontology", + "graph analytics", + "semantic extraction", + "visualization", + "reasoning", + "mcp" + ], + "skills": "../skills", + "agents": "../agents", + "hooks": "../hooks/hooks.json", + "mcp": { + "server": "python -m semantica.mcp_server", + "transport": "stdio" + }, + "openclaw": { + "mcporter": { + "mcpServers": { + "semantica": { + "command": "python", + "args": ["-m", "semantica.mcp_server"], + "transport": "stdio" + } + } + } + } +}