Graph-Native Infrastructure for Context and Accountable AI Systems
Python agent-memoryaiai-governanceai-infrastructureartificial-intelligencecontext-engineeringcontext-graphsdata-engineeringdecision-intelligencedeveloper-toolsexplainable-aigenerative-aigraph-ragknowledge-graphllmontologyprovenancepythonreasoningsemantic-search
docs: add CLI and Explorer setup guides
Sameer6305f608b1f75f24
diff --git a/docs/cli-setup.md b/docs/cli-setup.mdnew file mode 100644index 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 |++<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>diff --git a/docs/docs.json b/docs/docs.jsonindex 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.mdnew file mode 100644index 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]+```++<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>