# How to Verify Your Semantica Installation Using `semantica doctor`

> Verify your Semantica installation with `semantica doctor`. This tool performs a health check on your Python version, backend, API keys, and config for actionable insights.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-09-12

---

**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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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:

```bash
semantica doctor

```

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

```text
╭─────────────────────┬───────┬─────────────────────┬──────────────────────────╮
│ 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:

```bash
semantica doctor --json

```

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

```json
[
  {"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:

```bash
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:

```bash
#!/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`](https://github.com/semantica-agi/semantica/blob/main/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.