mengzhx/semantica
1
0
Fork 0
mirror of https://github.com/semantica-agi/semantica.git synced 2026-08-29 04:26:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add CLI and Explorer setup guides

Browse Source
This commit is contained in:
Sameer6305
2026-06-16 19:22:42 +05:30
parent fc22805e44
commit f608b1f75f
3 changed files with 494 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli-setup.md
+235
View File
@@ -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 |
<Note>
`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.
</Note>
## 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
<CardGroup cols={2}>
<Card title="semantica" icon="terminal">
The general-purpose CLI. Use it for one-off pipeline runs, entity extraction, and graph operations from a shell script or CI job.
</Card>
<Card title="semantica-server" icon="server">
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.
</Card>
<Card title="semantica-worker" icon="gears">
Background worker process entry point for Semantica deployments. Use alongside `semantica-server` for async task processing.
</Card>
<Card title="semantica-explorer" icon="map">
Launches the browser dashboard. Requires `pip install semantica[explorer]`. Use this to explore a saved knowledge graph interactively. See [Explorer Setup](explorer-setup).
</Card>
<Card title="semantica-mcp" icon="plug">
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).
</Card>
</CardGroup>
## Usage Examples
<Tabs>
<Tab title="REST server">
```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`.
</Tab>
<Tab title="Worker">
```bash
semantica-worker
```
The worker exits cleanly on `SIGINT` (Ctrl-C) or `SIGTERM`.
</Tab>
<Tab title="MCP client config">
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.
</Tab>
<Tab title="Explorer">
```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.
</Tab>
<Tab title="Python module form">
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
```
</Tab>
</Tabs>
## 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
<CardGroup cols={2}>
<Card title="Explorer Setup" icon="map" href="explorer-setup">
Build a graph, save it, and launch the browser dashboard.
</Card>
<Card title="MCP Server" icon="plug" href="reference/mcp_server">
All 12 tools and 3 resources exposed over the MCP protocol.
</Card>
<Card title="Installation" icon="download" href="installation">
Virtual environments, optional extras, and platform-specific notes.
</Card>
<Card title="Quickstart" icon="rocket" href="quickstart">
End-to-end pipeline walkthrough with working code.
</Card>
</CardGroup>
docs/docs.json
+2
View File
@@ -103,6 +103,8 @@
"group": "Get Started",
"pages": [
"installation",
"cli-setup",
"explorer-setup",
"quickstart",
"getting-started"
]
docs/explorer-setup.md
+257
View File
@@ -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]
```
<Note>
`pip install semantica` alone is not sufficient. Running `semantica-explorer` without the `[explorer]` extra immediately prints an error and exits with code 1.
</Note>
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.
<Steps>
<Step title="Build a graph">
```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")
```
</Step>
<Step title="Save to a JSON file">
```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.
</Step>
<Step title="Verify the file loads (optional sanity check)">
```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.
</Step>
</Steps>
<Tip>
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()`.
</Tip>
## 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
```
<Warning>
`--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.
</Warning>
## 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.
<CardGroup cols={2}>
<Card title="Explorer Reference" icon="book-open" href="reference/explorer">
Every REST endpoint, WebSocket events, analytics, and all supported flags.
</Card>
<Card title="CLI Setup" icon="terminal" href="cli-setup">
All five Semantica executables and when to use each one.
</Card>
<Card title="Context Module" icon="brain" href="reference/context">
Full documentation for ContextGraph — build, query, save, and load.
</Card>
<Card title="Quickstart" icon="rocket" href="quickstart">
End-to-end pipeline: ingest → extract → build graph → export.
</Card>
</CardGroup>