Doctor

The doctor command verifies you have the minimum needed dependencies for your installation mode. You can run it with:

ctxsift doctor

Doctor is the fastest way to check whether your chosen runtime path is actually usable.

What is doctor

Doctor reports required and optional runtime conditions, including:

• Python and platform support
• workspace initialization
• optional remote dependencies
• local inference prerequisites
• CUDA availability when relevant
• configured model and backend paths

Doctor should not be treated as a cosmetic step. It is the fastest way to catch a bad local model path, a missing optional package, or an incomplete remote setup before you start using compress and recall in a real workflow.

Typical workflow

ctxsift configure
ctxsift doctor

If doctor fails, fix the dependency or configuration issue first.

---

What doctor checks

ctxsift doctor resolves your effective config for the current directory (same resolution behavior as runtime), then runs a set of probes that are:

1. Always-on core checks
2. Mode-aware checks (local vs remote)
3. Feature-aware checks (quantization, GGUF, optional packages)

Doctor is read-mostly, but it may initialize/validate your workspace database path to confirm schema health and extension availability.

---

How to read doctor output

Each line is rendered as:

[severity] check_name: status - detail

Status logic:

• required + failing status means a hard blocker for normal operation.
• warning + failing status means degraded behavior or misconfiguration risk.
• optional + failing status means a capability is unavailable, but CtxSift may still run via fallback paths.

---

Check reference

Check name	When it appears	Why it matters	If it fails
database	Always	Verifies DB path can initialize and schema is usable	CtxSift storage cannot operate reliably
git_workspace	Always	Detects git metadata support in current cwd	Compression/recall still work, but git-aware context is reduced
remote_config	Always	Ensures remote settings are coherent when remote mode is enabled	Remote mode may be partially configured and unusable
sqlite_core	Always	Confirms core SQLite availability	Hard blocker for storage
sqlite_fts5	Always	Confirms FTS5 virtual table support	Recall text search path is broken
sqlite_vec	Always (or skipped detail after DB failure)	Confirms vector extension + embedding-model compatibility	Recall may fall back to FTS5-only
cuda	Optional	Indicates whether torch CUDA path is usable	Local CUDA acceleration unavailable
onnxruntime	Optional	Enables faster CPU embeddings path in supported setups	Embeddings can still run via torch fallback
flashattention	Optional	Extra attention backend for supported CUDA stacks	Usually safe to ignore unless you expect this backend
litellm	Remote mode only	Required adapter package for remote providers	Remote compression will not run
local_runtime	Local mode only	Validates local runtime backend can resolve from config	Local compression backend unusable until fixed
llama_cpp	Local CPU (llama.cpp) path	Confirms CPU local runtime package availability	CPU local compression unavailable
gguf_artifact	Local CPU (llama.cpp) path	Verifies configured GGUF file resolution/cache state	Wrong GGUF config blocks CPU local compression
accelerate	Local CUDA with quantization enabled	Required support package for quantized transformer loading	Quantized load path may fail
bitsandbytes	Local CUDA with bnb-* quantization modes	Required for BnB quantization	BnB quantized path will fail

---

Mode-specific interpretation

Local CPU (llama.cpp)

Prioritize these checks:

1. database, sqlite_core, sqlite_fts5
2. local_runtime, llama_cpp, gguf_artifact
3. sqlite_vec

If gguf_artifact says “not cached locally yet,” that is not necessarily an error. First run may download it.

Local CUDA

Prioritize these checks:

1. database, sqlite_core, sqlite_fts5
2. local_runtime, cuda
3. accelerate and bitsandbytes (only if quantization is enabled)

flashattention is performance-oriented, not a strict requirement for most environments.

Remote compression

Prioritize these checks:

1. remote_config (base URL + model name coherence)
2. litellm
3. Core storage checks (database, sqlite_core, sqlite_fts5, sqlite_vec)

Even in remote compression mode, embeddings/recall are still local checks.

---

Common failure patterns and fixes

remote_config warns about missing model name

Cause: remote.base_url is set but remote.model_name is empty.

Fix:

ctxsift config set remote.model_name <provider-model>

litellm missing in remote mode

Cause: remote extras not installed.

Fix:

uv tool install "ctxsift[remote]"

llama_cpp missing in local CPU mode

Cause: base local CPU runtime dependency unavailable.

Fix:

1. Reinstall or upgrade CtxSift base package.
2. Ensure your platform build prerequisites are present (compiler toolchain).

bitsandbytes fails with bnb-* quantization

Cause: quantization mode selected, but package/runtime compatibility missing.

Fix:

uv tool install "ctxsift[gpu,quant]"

Then re-run doctor.

sqlite_vec model mismatch warning

Cause: vector index in DB was built with a different embedding model than current config.

Impact: recall degrades to FTS5-only until alignment is restored.

Fix options:

1. Revert embedding model to the prior value.
2. Rebuild/reinitialize workspace DB to regenerate vector index with the current embedding model.

---

Recommended usage cadence

Run doctor:

1. Right after ctxsift configure
2. After changing local/remote backend settings
3. After changing embedding model or quantization mode
4. After upgrading Python, CUDA, PyTorch, or optional runtime packages

For most teams, this catches setup drift before it shows up as compression failures or degraded recall quality.

---

After doctor passes

Read Compress and Recall to understand the two core operations.