m4-setup

M4 Setup And Repair

Use this skill when the M4 environment looks incomplete, a dataset is missing, skills are stale, or vitrine is unavailable.

When to Use This Skill

• from m4 import ... fails or the wrong Python environment is active
• list_datasets() or m4 status --all does not show expected datasets
• M4 skills are missing, stale, or inconsistent across tools
• DuckDB/BigQuery backend configuration is wrong
• vitrine imports fail or the display server is not reachable

Fast Diagnostics

Run commands from the M4 repo root unless the user is intentionally working elsewhere.

pwd
uv run python - <<'PY'
from m4 import list_datasets
print("datasets:", list_datasets())
PY
uv run m4 status --all
uv run m4 agent-env --dataset mimic-iv-demo --json
uv run m4 skills --list
uv run vitrine status

If plain python cannot import m4, use uv run python; M4 is usually installed in the project virtual environment.

Dataset Checks

Expected built-in datasets:

Dataset	Notes
mimic-iv-demo	Local demo tabular dataset
mimic-iv	MIMIC-IV tabular data and derived tables
mimic-iv-note	MIMIC-IV notes
eicu	eICU tabular data

Custom datasets live under the M4 data directory in datasets/*.json and should appear in m4 status --all. By default the data directory is m4_data; if M4_DATA_DIR is set, it must point directly at the data directory.

Common checks:

uv run m4 agent-env --json
M4_CONFIG_DIR="${M4_HOME:-${M4_DATA_DIR:-m4_data}}"
cat "$M4_CONFIG_DIR/config.json"
find "${M4_DATA_DIR:-m4_data}/databases" -maxdepth 1 -type f -name '*.duckdb' -print
find "${M4_DATA_DIR:-m4_data}/datasets" -maxdepth 1 -type f -name '*.json' -print

Pass dataset="name" when querying, then inspect schema with get_schema(dataset=...) and get_table_info(..., dataset=...).

Skill Installation Repair

The canonical bundled skills are under src/m4/skills. Installed tool directories are generated copies.