How to Verify Your Semantica Installation Using `semantica doctor`

Run semantica doctor to execute a comprehensive health check that validates Python version, backend connectivity, API keys, and configuration files, returning a formatted table or JSON output with actionable remediation hints.

Verifying your Semantica installation ensures that all critical components—from the Python interpreter to graph database connections—are properly configured before running knowledge-graph workloads. The semantica doctor command, implemented in the semantica-agi/semantica repository, provides an automated health check that inspects dependencies, backend services, and environment variables in seconds.

Health Check Components

The doctor function in semantica/cli.py (starting at line 808) executes a series of inspections, each returning a label, status, note, and optional remediation hint. The command validates the following components:

Core Runtime Environment

• Python version: Confirms the interpreter meets the minimum requirement (≥ 3.8) by reading sys.version_info and comparing it to the required tuple. This check appears early in semantica/cli.py around line 37.
• Semantica library: Reads the __version__ constant defined in the package to confirm the installed version.
• Rich UI library: Verifies availability of the rich dependency by calling importlib.metadata.version("rich") (lines 46–50).

Backend Connectivity

• Graph store: Tests connectivity to the configured graph database (default Neo4j) by instantiating the store via _get_graph_store and calling ping() or connect(). This validation occurs at lines 52–58 in the CLI implementation.
• Vector store: Checks importability of the selected vector-store backend (default FAISS) by attempting to import faiss or the equivalent for other configured backends (lines 60–66).

Embedding Model Validation

When you pass the --deep-embeddings flag or set the SEMANTICA_DOCTOR_DEEP_EMBEDDINGS environment variable, the command performs additional validation:

• Sentence-transformers and FastEmbed: The command creates a TextEmbedder, loads the model, and runs a probe with the text "semantica doctor embedding probe". If the model loads successfully, the check reports ok; if loading fails after import, it raises a _DeepEmbeddingFailure with a specific remediation hint. This deep check executes lines 69–104 in semantica/cli.py.

Configuration and Credentials

• LLM provider keys: Checks for the presence of required API keys in environment variables: OPENAI_API_KEY, ANTHROPIC_API_KEY, and GROQ_API_KEY. Missing keys generate warnings with export hints (lines 21–28).
• Configuration file: Verifies whether a custom semantica.yaml (or the path supplied via --config) exists at cli_ctx.config_path (lines 30–37).
• Log directory: Confirms write permissions for the Semantica logs directory by calling _check_log_directory (line 38).

Running the Health Check

Basic Human-Readable Output

Execute the command without arguments to see a formatted table:

semantica doctor

The output displays a Rich table with columns for Check, Status, Note, and Hint:

╭─────────────────────┬───────┬─────────────────────┬──────────────────────────╮
│ Check               │ Status│ Note                │ Hint                     │
├─────────────────────┼───────┼─────────────────────┼──────────────────────────┤
│ Python              │ ok    │ 3.11.5              │                          │
│ semantica           │ ok    │ 0.3.2               │                          │
│ Graph store         │ ok    │ neo4j reachable     │                          │
│ Vector store        │ ok    │ faiss importable    │                          │
│ OpenAI              │ warn  │ OPENAI_API_KEY not  │ export OPENAI_API_KEY=…  │
│                     │       │ set                 │                          │
╰─────────────────────┴───────┴─────────────────────┴──────────────────────────╯

Machine-Readable JSON Output

For programmatic verification or CI/CD pipelines, use the --json flag:

semantica doctor --json

This emits a JSON array where each object contains check, status, note, and hint fields:

[
  {"check": "Python", "status": "ok", "note": "3.11.5", "hint": null},
  {"check": "semantica", "status": "ok", "note": "0.3.2", "hint": null},
  {"check": "OpenAI", "status": "warn", "note": "OPENAI_API_KEY not set", "hint": "export OPENAI_API_KEY=..."}
]

Deep Embedding Verification

To verify that embedding models can actually load into memory (not just import), enable deep probing:

semantica doctor --deep-embeddings

This flag triggers the TextEmbedder initialization and model loading test described in the embedding validation section above. If the probe fails, the hint column suggests installing optional dependencies like semantica[embeddings-local].

Scripting with Exit Codes

Use the JSON output in shell scripts to gate deployments:

#!/usr/bin/env bash
if semantica doctor --json | jq -e '.[] | select(.status=="fail")' >/dev/null; then
    echo "Semantica installation has problems – see doctor output."
    exit 1
fi
echo "All checks passed."

Interpreting Results

Each check returns one of three statuses: ok, warn, or fail. The Hint column provides concrete remediation steps specific to the failure mode:

• Missing dependencies: Hints suggest pip install commands with the appropriate extras (e.g., semantica[vectorstore-faiss]).
• Missing API keys: Hints display the exact export command needed for the environment variable.
• Graph store unreachable: Hints recommend running semantica store list to verify configuration.

All checks are collected internally as tuples of type Check = Tuple[str, str, str, Optional[str]] before rendering.

Summary

• semantica doctor provides a single-command verification of your entire Semantica environment.
• The command inspects Python version, package dependencies, graph and vector store connectivity, embedding model loading, API keys, and file system permissions.
• Use --json for machine-readable output suitable for automation and CI/CD pipelines.
• Enable --deep-embeddings to detect runtime model-loading failures that simple import checks miss.
• Remediation hints are built into the output, guiding you to install missing extras or configure environment variables.

Frequently Asked Questions

What does semantica doctor check by default?

By default, the command verifies the Python interpreter version (≥ 3.8), the presence of core dependencies (semantica, rich), graph store connectivity (Neo4j), vector store importability (FAISS), the existence of configuration files, and the presence of LLM API keys. It does not load embedding models unless the --deep-embeddings flag is provided.

How do I verify Semantica installation status programmatically?

Run semantica doctor --json and pipe the output to a JSON parser like jq. The command returns structured data with a status field for each component. You can check for any "fail" statuses to determine if the installation is healthy, or filter for specific checks like the graph store or vector store.

What is the deep embeddings check and when should I use it?

The deep embeddings check validates that embedding backends (sentence-transformers and fastembed) can not only be imported but can also successfully load a model into memory and run inference. Use this flag when you encounter runtime errors during knowledge graph construction or when verifying GPU/CPU compatibility for local embedding models.

How do I fix a failing graph store check?

A failing graph store check typically indicates that the Neo4j instance configured in semantica.yaml is unreachable. Verify that your database is running, network connectivity exists, and credentials are correct. The hint column will suggest running semantica store list to diagnose connection issues or checking your configuration file path.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}