From f608b1f75f24948e9580cd15c2aced6f3dfa5abb Mon Sep 17 00:00:00 2001 From: Sameer6305 Date: Tue, 16 Jun 2026 19:22:42 +0530 Subject: [PATCH] docs: add CLI and Explorer setup guides --- docs/cli-setup.md | 235 +++++++++++++++++++++++++++++++++++++ docs/docs.json | 2 + docs/explorer-setup.md | 257 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 494 insertions(+) create mode 100644 docs/cli-setup.md create mode 100644 docs/explorer-setup.md diff --git a/docs/cli-setup.md b/docs/cli-setup.md new file mode 100644 index 00000000..70dce7ae --- /dev/null +++ b/docs/cli-setup.md @@ -0,0 +1,235 @@ +--- +title: "CLI Setup" +description: "The five Semantica executables — what each one does, when to use it, and how to confirm it is working." +icon: "terminal" +--- + +Installing the base package registers five executables on your `PATH`. Each serves a distinct purpose. This page explains what they are, how to verify they are available, and which one to reach for in each situation. + +## Installed Commands + +```bash +pip install semantica +``` + +After installation the following commands are available: + +| Command | Entry point | What it does | +| ------- | ----------- | ------------ | +| `semantica` | `semantica.cli:main` | General-purpose CLI for pipeline runs, extraction, and graph operations | +| `semantica-server` | `semantica.server:main` | FastAPI/uvicorn REST API server bound to `0.0.0.0:8000` | +| `semantica-worker` | `semantica.worker:main` | Background worker process entry point for Semantica deployments | +| `semantica-explorer` | `semantica.explorer:main` | Interactive browser dashboard for knowledge graph exploration | +| `semantica-mcp` | `semantica.mcp_server:main` | MCP server (stdio) for Claude Desktop, Cursor, Windsurf, and other MCP clients | + + + `semantica-explorer` requires `pip install semantica[explorer]`. Running it without that extra will immediately print an error and exit. See [Explorer Setup](explorer-setup) for the full walkthrough. + + +## Verify the Installation + +Confirm each command is reachable and prints its usage: + +```bash +semantica --help +semantica-server --help +semantica-worker --help +semantica-explorer --help +semantica-mcp --help +``` + +Confirm the package version: + +```bash +python -c "import semantica; print(semantica.__version__)" +``` + +## When to Use Each Command + + + + The general-purpose CLI. Use it for one-off pipeline runs, entity extraction, and graph operations from a shell script or CI job. + + + Starts the REST API server. Binds to `0.0.0.0:8000`. Use this when another service or application needs programmatic access to Semantica over HTTP. + + + Background worker process entry point for Semantica deployments. Use alongside `semantica-server` for async task processing. + + + Launches the browser dashboard. Requires `pip install semantica[explorer]`. Use this to explore a saved knowledge graph interactively. See [Explorer Setup](explorer-setup). + + + Runs the MCP server over stdio. Configure it in your MCP client's settings file to expose all 12 tools and 3 resources to Claude Desktop, Cursor, Windsurf, or any MCP-aware client. See [MCP Server](reference/mcp_server). + + + +## Usage Examples + + + + ```bash + # Starts FastAPI + uvicorn on 0.0.0.0:8000 + semantica-server + ``` + + Once running, check it with: + + ```bash + curl http://localhost:8000/health + # {"status": "healthy"} + + curl http://localhost:8000/api/info + # {"name": "Semantica API", "version": "...", "status": "active"} + ``` + + The interactive API docs are at `http://localhost:8000/docs`. + + + ```bash + semantica-worker + ``` + + The worker exits cleanly on `SIGINT` (Ctrl-C) or `SIGTERM`. + + + Add to your MCP client's settings file: + + ```json + { + "mcpServers": { + "semantica": { + "command": "semantica-mcp" + } + } + } + ``` + + Or use the Python module form if the command is not on `PATH`: + + ```json + { + "mcpServers": { + "semantica": { + "command": "python", + "args": ["-m", "semantica.mcp_server"] + } + } + } + ``` + + Test it directly before configuring your client: + + ```bash + echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | semantica-mcp + ``` + + You should receive a JSON-RPC response. See [MCP Server](reference/mcp_server) for the full list of tools and resources. + + + ```bash + pip install semantica[explorer] + semantica-explorer --graph my_graph.json + ``` + + See [Explorer Setup](explorer-setup) for the full walkthrough including how to build and save a graph file. + + + Every command also runs as a Python module — useful when the script directory is not on `PATH`: + + ```bash + python -m semantica.mcp_server + python -m semantica.explorer --graph my_graph.json + ``` + + + +## Environment Variables + +`semantica-mcp` reads two environment variables: + +| Variable | Default | Description | +| -------- | ------- | ----------- | +| `SEMANTICA_KG_PATH` | *(none)* | Path to a saved graph file to load on startup | +| `SEMANTICA_LOG_LEVEL` | `WARNING` | Log verbosity: `DEBUG`, `INFO`, `WARNING` | + +`semantica-server` reads one: + +| Variable | Default | Description | +| -------- | ------- | ----------- | +| `SEMANTICA_CORS_ORIGINS` | `http://localhost:5173,http://127.0.0.1:5173` | Comma-separated list of allowed CORS origins | + +No other environment variables are read by these commands. + +## Troubleshooting + +### `command not found` + +The executables are placed in the `bin/` (Linux/Mac) or `Scripts/` (Windows) directory of the active Python environment. If the command is not found, that directory is likely not on `PATH`. + +Activate your virtual environment first: + +```bash +source venv/bin/activate # Linux / Mac +venv\Scripts\activate # Windows +semantica --help +``` + +Find where pip placed the scripts: + +```bash +python -m site --user-scripts # user-level install +pip show -f semantica # shows installed files +``` + +### Command found but crashes on import + +```bash +pip install --upgrade semantica +python -c "import semantica; print(semantica.__version__)" +``` + +If you have multiple Python environments, make sure you are installing into the same one the shell resolves: + +```bash +python -m pip install semantica +``` + +### `semantica-explorer` — "uvicorn is required" + +The Explorer extras are not included in the base install: + +```bash +pip install semantica[explorer] +``` + +### `semantica-mcp` silent failure in a MCP client + +The MCP server communicates over stdio. Test it directly from the shell first: + +```bash +echo '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}' | semantica-mcp +``` + +A response of `{"jsonrpc":"2.0","id":1,"result":{}}` confirms the server is working. If you see nothing, check that the command is on `PATH` and the base package is installed. + +### Windows: DLL errors on startup + +Install the [Microsoft Visual C++ Redistributable](https://aka.ms/vs/17/release/vc_redist.x64.exe). This is a Windows system dependency required by PyTorch and related packages, not a Semantica bug. + +## Next Steps + + + + Build a graph, save it, and launch the browser dashboard. + + + All 12 tools and 3 resources exposed over the MCP protocol. + + + Virtual environments, optional extras, and platform-specific notes. + + + End-to-end pipeline walkthrough with working code. + + diff --git a/docs/docs.json b/docs/docs.json index c2ffe747..2ba492b4 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -103,6 +103,8 @@ "group": "Get Started", "pages": [ "installation", + "cli-setup", + "explorer-setup", "quickstart", "getting-started" ] diff --git a/docs/explorer-setup.md b/docs/explorer-setup.md new file mode 100644 index 00000000..bdf9e43e --- /dev/null +++ b/docs/explorer-setup.md @@ -0,0 +1,257 @@ +--- +title: "Explorer Setup" +description: "Install the Explorer extras, save a ContextGraph to JSON, and launch the interactive browser dashboard." +icon: "map" +--- + +`semantica-explorer` is an interactive browser dashboard for knowledge graph exploration. You give it a graph file, it starts a local server, and opens a browser tab where you can search nodes, find paths, inspect provenance, and run analytics — no code required after launch. + +This page covers everything needed to go from zero to a running Explorer. For the full REST API reference and endpoint catalogue, see [Explorer Reference](reference/explorer). + +## Prerequisites + +The Explorer depends on FastAPI and uvicorn, which are not included in the base install: + +```bash +pip install semantica[explorer] +``` + + + `pip install semantica` alone is not sufficient. Running `semantica-explorer` without the `[explorer]` extra immediately prints an error and exits with code 1. + + +Verify: + +```bash +semantica-explorer --help +``` + +You should see the usage message with the four available flags. If you see `command not found`, activate your virtual environment first. See [CLI Setup](cli-setup#troubleshooting) for PATH help. + +## Minimal End-to-End Example + +The following four steps are everything needed to get Explorer running: + +```python +from semantica.context import ContextGraph + +# 1. Create a graph +graph = ContextGraph() + +# 2. Add a node +graph.add_node("python", "language", content="Python programming language") + +# 3. Save to disk +graph.save_to_file("my_graph.json") +``` + +```bash +# 4. Launch Explorer +semantica-explorer --graph my_graph.json +``` + +The browser opens at `http://127.0.0.1:8000`. The health endpoint confirms the server is up: + +```bash +curl http://127.0.0.1:8000/api/health +# {"status": "healthy"} +``` + +## Step 1 — Build and Save a ContextGraph + +Explorer loads a graph from a JSON file on disk. You need to create that file first. + + + + ```python + from semantica.context import ContextGraph + + graph = ContextGraph() + + # add_node(node_id, node_type, content=None, **properties) + graph.add_node("python", "language", content="Python programming language") + graph.add_node("fastapi", "framework", content="FastAPI web framework") + graph.add_node("guido", "person", content="Guido van Rossum") + + # add_edge(source_id, target_id, edge_type="related_to", weight=1.0, **properties) + graph.add_edge("python", "fastapi", "enables") + graph.add_edge("guido", "python", "created") + ``` + + + ```python + graph.save_to_file("my_graph.json") + ``` + + `save_to_file` writes a JSON object with `graph_id`, `nodes`, `edges`, and `links` to the specified path. + + + ```python + from semantica.context import ContextGraph + + check = ContextGraph() + check.load_from_file("my_graph.json") + print(check.stats()) + # { + # "node_count": 3, + # "edge_count": 2, + # "node_types": {"language": 1, "framework": 1, "person": 1}, + # "edge_types": {"enables": 1, "created": 1}, + # "density": ... + # } + ``` + + If this runs without error, Explorer will load the file successfully. + + + + + Already have a graph from a pipeline run? Skip straight to Step 2. The only requirement is that the file was saved with `ContextGraph.save_to_file()`. + + +## Step 2 — Launch Explorer + +```bash +semantica-explorer --graph my_graph.json +``` + +The startup sequence prints: + +``` +✓ Graph loaded — 3 nodes, 2 edges +╭─ Semantica Explorer · http://127.0.0.1:8000 ─╮ +│ API docs http://127.0.0.1:8000/docs │ +│ Health http://127.0.0.1:8000/api/health │ +╰───────────────────────────────────────────────╯ +``` + +The browser opens automatically at `http://127.0.0.1:8000` approximately 1.5 seconds after the server starts. + +## CLI Flags + +`semantica-explorer` accepts exactly four flags: + +| Flag | Short | Default | Description | +| ---- | ----- | ------- | ----------- | +| `--graph` | `-g` | *(required)* | Path to a ContextGraph JSON file | +| `--port` | `-p` | `8000` | Port to bind the server | +| `--host` | — | `127.0.0.1` | Host to bind the server | +| `--no-browser` | — | off | Do not open a browser tab automatically | + +There are no flags for authentication, log level, or TLS. Those are not implemented in the CLI. + +### Examples + +```bash +# Minimal — local only, port 8000, browser opens automatically +semantica-explorer --graph my_graph.json + +# Short flags +semantica-explorer -g my_graph.json -p 8080 + +# Expose on the network so other machines can connect +semantica-explorer --graph my_graph.json --host 0.0.0.0 --port 8080 + +# Headless — skip the auto-open and navigate manually +semantica-explorer --graph my_graph.json --no-browser +``` + + + `--host 0.0.0.0` makes Explorer reachable on every network interface. The server has no built-in authentication. Only use this on a trusted private network. + + +## Browser Access + +Once the server is running: + +| URL | What you get | +| --- | ------------ | +| `http://127.0.0.1:8000` | Interactive dashboard | +| `http://127.0.0.1:8000/docs` | Swagger UI — every REST endpoint, interactive | +| `http://127.0.0.1:8000/api/health` | Health check — `{"status": "healthy"}` | + +The browser tab opens 1.5 seconds after startup. If it does not open, navigate to the URL manually or pass `--no-browser` and open it yourself. + +## Running as a Python Module + +If `semantica-explorer` is not on `PATH`, use the module form: + +```bash +python -m semantica.explorer --graph my_graph.json --port 8080 +``` + +## Common Startup Errors + +**`Error: graph file not found: my_graph.json`** + +The path passed to `--graph` must point to an existing file. The CLI checks with `os.path.isfile()` before attempting to load anything. + +```bash +# Confirm the file exists +ls my_graph.json # Linux / Mac +dir my_graph.json # Windows + +# Use the full path if needed +semantica-explorer --graph /absolute/path/to/my_graph.json +``` + +**`Error: uvicorn is required`** + +The `[explorer]` extra was not installed: + +```bash +pip install semantica[explorer] +``` + +**Explorer launches but shows zero nodes** + +The file loaded but contains no nodes. Verify with Python: + +```python +from semantica.context import ContextGraph +g = ContextGraph() +g.load_from_file("my_graph.json") +print(g.stats()) # check node_count +``` + +A `node_count` of `0` means the file was saved empty or the nodes key is absent. Make sure you called `add_node` before `save_to_file`. + +**`Connection refused` from another machine** + +The default `--host 127.0.0.1` only accepts connections from the same machine. To allow remote access: + +```bash +semantica-explorer --graph my_graph.json --host 0.0.0.0 +``` + +**Browser tab does not open** + +This is expected in headless, SSH, and container environments. Add `--no-browser` to suppress the warning and open `http://127.0.0.1:8000` in a browser that has network access to the server. + +## What Explorer Gives You + +Once running, Explorer exposes a REST API and dashboard for: + +- **Node and edge search** — indexed search across all nodes by ID, type, and content +- **Neighborhood expansion** — inspect neighbors up to configurable hop depth +- **Path finding** — BFS shortest path between any two nodes +- **Graph analytics** — centrality, community detection, connectivity +- **Decisions and provenance** — query recorded decisions and their causal chains +- **Import / export** — upload JSON or CSV to extend the graph; download the current state + +The full endpoint catalogue is documented in the Swagger UI at `/docs` and in the reference page below. + + + + Every REST endpoint, WebSocket events, analytics, and all supported flags. + + + All five Semantica executables and when to use each one. + + + Full documentation for ContextGraph — build, query, save, and load. + + + End-to-end pipeline: ingest → extract → build graph → export. + +