m4 - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #react #llm #go #deep-learning #macos #windows #awesome #cli #vue #security #pytorch #openai

m4

(★ 40)

Give your AI agents clinical database access, research automation, and clinician-reviewed domain knowledge for MIMIC-IV, eICU, and more.

m4 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# M4: Infrastructure for AI-Assisted Clinical Research

Give your AI agents clinical intelligence & access to MIMIC-IV, eICU, and more

M4 is infrastructure for AI-assisted clinical research. Initialize MIMIC-IV, eICU, or custom datasets as fast local databases (with optional BigQuery for cloud access). Your AI agents get specialized tools (MCP, Python API) and clinical knowledge (agent skills) to query and analyze them.

[Usage example – M4 MCP](https://claude.ai/share/93f26832-f298-4d1d-96e3-5608d7f0d7ad) | [Usage example – Code Execution](docs/M4_Code_Execution_Example.pdf)

> M4 builds on the [M3](https://github.com/rafiattrach/m3) project. Please [cite](#citation) their work when using M4!

## Why M4?

Clinical research shouldn't require mastering database schemas. Whether you're screening a hypothesis, characterizing a cohort, or running a multi-step survival analysis—you should be able to describe what you want and get clinically meaningful results.

M4 makes this possible by giving AI agents deep clinical knowledge:

**Understand clinical semantics.**
LLMs can write SQL, but have a harder time with (dataset-specific) clinical semantics. M4's comprehensive agent skills encode validated clinical concepts—so "find sepsis patients" produces clinically correct queries on any supported dataset.

**Work across modalities.**
Clinical research with M4 spans structured data, clinical notes, and (soon) waveforms and imaging. M4 dynamically selects tools based on what each dataset contains—query labs in MIMIC-IV, search discharge summaries in MIMIC-IV-Note, all through the same interface.

**Go beyond chat.**
Data exploration and simple research questions work great via MCP. But real research requires iteration: explore a cohort, compute statistics, visualize distributions, refine criteria. M4's Python API returns DataFrames that integrate with pandas, scipy, and matplotlib—turning your AI assistant into a research partner that can execute complete analysis workflows.

**Cross-dataset research.**
You should be able to ask for multi-dataset queries or cross-dataset comparisons. M4 makes this easier than ever as the AI can switch between your initialized datasets on its own, allowing it to do cross-dataset tasks for you.

**Interactive exploration.**
Some research tasks—like cohort definition—benefit from real-time visual feedback rather than iterative text queries. M4 Apps embed purpose-built UIs directly in your AI client, letting you drag sliders, toggle filters, and see instant results without leaving your workflow.

## Quickstart (3 steps)

### 1. Install uv

**macOS/Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### 2. Initialize M4

```bash
mkdir my-research && cd my-research
uv init && uv add m4-infra
source .venv/bin/activate  # Windows: .venv\Scripts\activate
m4 init mimic-iv-demo
```

This downloads the free MIMIC-IV demo dataset (~16MB) and sets up a local DuckDB database.

### 3. Connect your AI client

**Claude Desktop:**
```bash
m4 config claude --quick
```

**Other clients (Cursor, LibreChat, etc.):**
```bash
m4 config --quick
```

Copy the generated JSON into your client's MCP settings, restart, and start asking questions!

<details>
<summary>Different setup options</summary>

* If you don't want to use uv, you can just run pip install m4-infra

* If you want to use Docker, look at <a href="docs/DEVELOPMENT.md">docs/DEVELOPMENT.md</a>
</details>

## Code Execution

For complex analysis that goes beyond simple queries, M4 provides a Python API that returns Python data types instead of formatted strings (e.g. pd.DataFrame for SQL queries). This transforms M4 from a query tool into a complete clinical data analysis environment.

```python
from m4 import execute_query, get_schema

dataset = "mimic-iv"

# Get schema as a dict
schema = get_schema(dataset=dataset)
print(schema['tables'])  # ['mimiciv_hosp.admissions', 'mimiciv_hosp.diagnoses_icd', ...]

# Query returns a pandas DataFrame
df = execute_query("""
    SELECT icd_code, COUNT(*) as n
    FROM mimiciv_hosp.diagnoses_icd
    GROUP BY icd_code
    ORDER BY n DESC
    LIMIT 10
""", dataset=dataset)

# Use full pandas power: filter, join, compute statistics
df[df['n'] > 100].plot(kind='bar')
```

The API uses the same tools as the MCP server, so behavior is consistent. But instead of parsing text, you get DataFrames you can immediately analyze, visualize, or feed into downstream pipelines.

**When to use code execution:**
- Multi-step analyses where each query informs the next
- Large result sets (thousands of rows) that shouldn't flood your context
- Statistical computations, survival analysis, cohort characterization
- Building reproducible analysis notebooks

See [Code Execution Guide](docs/CODE_EXECUTION.md) for the full API reference and [this example session](docs/M4_Code_Execution_Example.pdf) for a walkthrough.

## Agent Skills

M4 ships with a set of skills that teach AI coding assistants clinical research patterns. Skills activate automatically when relevant—ask about "SOFA scores" or "sepsis cohorts" and Claude uses validated SQL from MIT-LCP repositories.

For the canonical list of bundled skills, see `src/m4/skills/SKILLS_INDEX.md`.

**Clinical skills:**
- **Severity Scores**: SOFA, APACHE III, SAPS-II, OASIS, LODS, SIRS
- **Sepsis**: Sepsis-3 cohort identification, suspected infection
- **Organ Failure**: KDIGO AKI staging
- **Measurements**: GCS calculation, baseline creatinine, vasopressor equivalents
- **Cohort Selection**: First ICU stay identification
- **Research Methodology**: Common research pitfalls and how to avoid them

**System skills:**
- **M4 Framework**: Python API usage, research workflow, setup repair, vitrine display, skill creation guide
- **Data Structure**: MIMIC-IV table relationships, MIMIC-eICU mapping

**Supported tools:** Claude Code, Cursor, Cline, Codex CLI, Gemini CLI, GitHub Copilot

```bash
m4 skills                                    # Interactive tool and skill selection
m4 skills --tools claude,cursor              # Install all skills for specific tools
m4 skills --tools claude --tier validated     # Only validated skills
m4 skills --tools claude --category clinical  # Only clinical skills
m4 skills --tools claude --skills sofa-score,m4-api  # Specific skills by name
m4 skills --list                             # Show installed skills with metadata
```

See [Skills Guide](docs/SKILLS.md) for the full list and how to create custom skills.

## M4 Apps

M4 Apps bring interactivity to clinical research. Instead of text-only responses, apps render interactive UIs directly in your AI client—ideal for tasks that benefit from real-time visual feedback.

**Cohort Builder**: Define patient cohorts with live filtering. Adjust age ranges, add diagnosis codes, and toggle clinical criteria while watching counts update instantly.

```
User: Help me build a cohort of elderly diabetic patients
Claude: [Launches Cohort Builder UI with interactive filters]
```

M4 Apps require a host that supports the MCP Apps protocol (like Claude Desktop). In other clients, you'll get text-based results instead.

See [M4 Apps Guide](docs/M4_APPS.md) for details on available apps and how they work.

## Example Questions

Once connected, try asking:

**Tabular data (mimic-iv, eicu):**
- *"What tables are available in the database?"*
- *"Show me the race distribution in hospital admissions"*
- *"Find all ICU stays longer than 7 days"*
- *"What are the most common lab tests?"*

**Derived concept tables (mimic-iv, after `m4 init-derived`):**
- *"What are the average SOFA scores for patients with sepsis?"*
- *"Show KDIGO AKI staging distribution across ICU stays"*
- *"Find patients on norepinephrine with SOFA > 10"*
- *"What is the 30-day mortality for patients with Charlson index > 5?"*

**Clinical notes (mimic-iv-note):**
- *"Search for notes mentioning diabetes"*
- *"List all notes for patient 10000032"*
- *"Get the full discharge summary for this patient"*

## Supported Datasets

| Dataset | Modality | Size | Access | Local | BigQuery | Derived Tables |
|---------|----------|------|--------|-------|----------|----------------|
| **mimic-iv-demo** | Tabular | 100 patients | Free | Yes | No | No |
| **mimic-iv** | Tabular | 365k patients | [PhysioNet credentialed](https://physionet.org/content/mimiciv/) | Yes | Yes | Yes |
| **mimic-iv-note** | Notes | 331k notes | [PhysioNet credentialed](https://physionet.org/content/mimic-iv-note/) | Yes | Yes | No |
| **eicu** | Tabular | 200k+ patients | [PhysioNet credentialed](https://physionet.org/content/eicu-crd/) | Yes | Yes | No |

These datasets are supported out of the box. However, it is possible to add any other custom dataset by following [these instructions](docs/CUSTOM_DATASETS.md).

Choose datasets explicitly at each call site and switch the saved backend anytime:
```bash
m4 backend bigquery # Switch to BigQuery (or duckdb)
m4 capabilities     # Show available interfaces, datasets, tools, and policies
m4 doctor           # Diagnose local, BigQuery, and MCP setup
m4 status --dataset mimic-iv # Show dataset and backend status
m4 status --all     # List all available datasets
m4 status --dataset mimic-iv --derived # Show per-table derived materialization status
```

For automation and external agents, M4 also provides non-interactive JSON
commands that use request-scoped dataset and backend options:

```bash
m4 agent-env --dataset mimic-iv --backend duckdb --json
m4 capabilities --json
m4 doctor --json
m4 download mimic-iv --json
m4 list-datasets --json --no-interactive
m4 schema --dataset mimic-iv --backend duckdb --json --no-interactive
m4 describe-table mimiciv_hosp.patients --dataset mimic-iv --json --no-interactive
m4 query --dataset mimic-iv --sql "SELECT COUNT(*) AS n FROM mimiciv_hosp.patients" --json --no-interactive
m4 provenance export --json
```

Machine-facing status and backend metadata hide local filesystem paths by
default. Use `--paths` or `M4_PATH_DISCLOSURE=1` only when the caller is allowed
to see raw local paths.

Long-running dataset setup can emit newline-delimited JSON progress events:

```bash
m4 init mimic-iv --json --events ndjson --no-interactive --download \
  --physionet-credentials-file /path/to/physionet-credentials.json
m4 init-derived mimic-iv --json --events ndjson
```

When `--events ndjson` is used, stdout is an NDJSON stream instead of a single
JSON object. The final result is emitted as `operation_completed.result`; setup
failures are emitted as `operation_failed.error`.

**Derived concept tables** (MIMIC-IV only):
```bash
m4 init-derived mimic-iv         # Materialize derived tables (SOFA, sepsis3, KDIGO, etc.)
m4 init-derived mimic-iv --list  # List available derived tables without materializing
```

After running `m4 init mimic-iv`, you are prompted whether to materialize derived tables. You can also run `m4 init-derived` separately at any time. Derived tables are created in the `mimiciv_derived` schema (e.g., `mimiciv_derived.sofa`) and are immediately queryable. The SQL is vendored from the [mimic-code](https://github.com/MIT-LCP/mimic-code) repository -- production-tested and DuckDB-compatible. BigQuery users already have these tables available via `physionet-data.mimiciv_derived` and do not need to run `init-derived`.

<details>
<summary>Setting up MIMIC-IV or eICU (credentialed datasets)</summary>

1. **Get PhysioNet credentials:** Complete the [credentialing process](https://physionet.org/settings/credentialing/) and sign the data use agreement for the dataset.

2. **Download the data with M4:**
 ```bash
 cat > physionet-credentials.json <<'JSON'
 {
 "username": "YOUR_USERNAME",
 "password": "YOUR_PASSWORD"
 }
 JSON

m4 init mimic-iv --download --physionet-credentials-file physionet-credentials.json
   ```

Do not pass PhysioNet passwords as command-line flags. Use a scoped
   credentials file with restrictive permissions and delete it after setup.

M4 implements the same recursive, resumable pattern PhysioNet documents for
 `wget -r -N -c -np` against `/files/...` dataset URLs, while preserving the
 expected raw layout under `m4_data/raw_files/<dataset>/`.

You can still download manually if needed:
   ```bash
   m4 download mimic-iv
   ```

For credentialed datasets, `m4 download` validates the expected local layout
   and prints a dataset-specific resumable `wget` command.

```bash
   # For MIMIC-IV
   wget -r -N -c -np --cut-dirs=3 -nH --user YOUR_USERNAME --ask-password \
     https://physionet.org/files/mimiciv/3.1/ \
     -P m4_data/raw_files/mimic-iv

# For eICU
 wget -r -N -c -np --cut-dirs=3 -nH --user YOUR_USERNAME --ask-password \
 https://physionet.org/files/eicu-crd/2.0/ \
 -P m4_data/raw_files/eicu
 ```
 The `--cut-dirs=3 -nH` flags remove the PhysioNet `files/<dataset>/<version>/` prefix so CSV files land under `m4_data/raw_files/<dataset>/` with only dataset-internal folders preserved.

3. **Initialize after a manual download:**
   ```bash
   m4 init mimic-iv   # or: m4 init eicu
   ```

This converts the CSV files to Parquet format and creates a local DuckDB database.
</details>

## Available Tools

M4 exposes these tools to your AI client. Data tools are checked against the explicit dataset selected for that call.

**Dataset Management:**
| Tool | Description |
|------|-------------|
| `list_datasets` | List available datasets and their status |
| `set_dataset` | Removed migration aid; pass `dataset` to data tools |

**Tabular Data Tools** (mimic-iv, mimic-iv-demo, eicu):
| Tool | Description |
|------|-------------|
| `get_database_schema` | List all available tables |
| `get_table_info` | Get column details and sample data |
| `execute_query` | Run SQL SELECT queries |

**Clinical Notes Tools** (mimic-iv-note):
| Tool | Description |
|------|-------------|
| `search_notes` | Full-text search with snippets |
| `get_note` | Retrieve a single note by ID |
| `list_patient_notes` | List notes for a patient (metadata only) |

## More Documentation

| Guide | Description |
|-------|-------------|
| [Architecture](docs/ARCHITECTURE.md) | Design philosophy, system overview, clinical semantics |
| [Code Execution](docs/CODE_EXECUTION.md) | Python API for programmatic access |
| [M4 Apps](docs/M4_APPS.md) | Interactive UIs for clinical research tasks |
| [Skills](docs/SKILLS.md) | Clinical and system skills for AI-assisted research |
| [Tools Reference](docs/TOOLS.md) | MCP tool documentation |
| [BigQuery Setup](docs/BIGQUERY.md) | Google Cloud for full datasets |
| [Custom Datasets](docs/CUSTOM_DATASETS.md) | Add your own PhysioNet datasets |
| [M4Bench Reproducibility](benchmark/REPRODUCIBILITY.md) | Reviewer workflow for MIMIC-IV/eICU initialization and benchmark reruns |
| [Development](docs/DEVELOPMENT.md) | Contributing, testing, code style |
| [OAuth2 Authentication](docs/OAUTH2_AUTHENTICATION.md) | Enterprise security setup |

## Roadmap

M4 is infrastructure for AI-assisted clinical research. Current priorities:

- **Clinical Semantics**
  - More concept mappings (comorbidity indices, medication classes)
  - Semantic search over clinical notes (beyond keyword matching)
  - More agent skills that provide meaningful clinical knowledge

- **New Modalities**
  - Waveforms (ECG, arterial blood pressure)
  - Imaging (chest X-rays)

- **Clinical Research Agents**
  - Skills and guardrails that enforce scientific integrity and best practices (documentation, etc.)
  - Query logging and session export
  - Result fingerprints for audit trails

## Troubleshooting

**"Parquet not found" error:**
```bash
m4 init mimic-iv-demo --force
```

**MCP client won't connect:**
Check client logs (Claude Desktop: Help → View Logs) and ensure the config JSON is valid.

**`m4` command opens GNU M4 instead of the CLI:**
On macOS/Linux, `m4` is a built-in system utility. Make sure your virtual environment is activated (`source .venv/bin/activate`) so that the correct `m4` binary is found first. Alternatively, use `uv run m4 [command]` to run within the project environment without activating it.

**Need to reconfigure:**
```bash
m4 config claude --quick   # Regenerate Claude Desktop config
m4 config --quick          # Regenerate generic config
```

## Citation

M4 builds on the M3 project. Please cite:

```bibtex
@article{attrach2025conversational,
  title={Conversational LLMs Simplify Secure Clinical Data Access, Understanding, and Analysis},
  author={Attrach, Rafi Al and Moreira, Pedro and Fani, Rajna and Umeton, Renato and Celi, Leo Anthony},
  journal={arXiv preprint arXiv:2507.01053},
  year={2025}
}
```

---

<a href="https://github.com/hannesill/m4/issues">Report an Issue</a> ·
 <a href="docs/DEVELOPMENT.md">Contribute</a>

m4

m4 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

m4

m4 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README