mosaicx 2.0.0

DIGIT-X Lab · LMU Munich
Turn unstructured medical documents into validated, machine-readable JSON.
Runs locally — no PHI leaves your machine.

How It Works

flowchart LR
    A["PDF / Image / Text"] --> B["Dual-Engine OCR"]
    B --> C["DSPy Pipeline"]
    C --> D["Validated JSON"]

    style A fill:#B5A89A,stroke:#8a7e72,color:#fff
    style B fill:#E87461,stroke:#c25a49,color:#fff
    style C fill:#E87461,stroke:#c25a49,color:#fff
    style D fill:#B5A89A,stroke:#8a7e72,color:#fff

MOSAICX ships with specialized pipelines for radiology and pathology reports, a generic extraction mode that adapts to any document, plus de-identification and patient timeline summarization. Every pipeline is a DSPy module -- meaning it can be optimized with labeled data for your specific use case.

Why MOSAICX? -- Fully local (no PHI leaves your machine), schema-driven (define exactly what to extract), dual-engine OCR (handles scans and handwriting), and DSPy-optimizable (improve accuracy with your own labeled data). One CLI for radiology, pathology, de-identification, and summarization.

Quick Start

One-line install (Mac or Linux):

curl -fsSL https://raw.githubusercontent.com/DIGIT-X-Lab/MOSAICX/master/scripts/setup.sh | bash

Or install manually and let the setup wizard configure everything:

pip install mosaicx
mosaicx setup

Then extract structured data from a report:

mosaicx extract --document report.pdf --mode radiology

Check health anytime with mosaicx doctor. See the full Quickstart guide for details.

Install Extras

pip install 'mosaicx[mcp]'       # + MCP server for AI agents
pip install 'mosaicx[query]'     # + fast tabular query stack (duckdb + polars)
pip install 'mosaicx[all]'       # everything

Developer Fast Loop (Mac + vLLM-MLX, 120B)

# 1) serve your local model (already downloaded)
vllm-mlx serve mlx-community/gpt-oss-120b-4bit --port 8000

# 2) point MOSAICX to that server
export MOSAICX_LM=openai/mlx-community/gpt-oss-120b-4bit
export MOSAICX_API_BASE=http://127.0.0.1:8000/v1
export MOSAICX_API_KEY=dummy

# 3) verify the endpoint
curl -sS --max-time 5 http://127.0.0.1:8000/v1/models

# 4) run extraction + claim verify + query
mosaicx extract --document report.pdf --mode radiology -o output.json
mosaicx verify --document report.pdf --claim "patient BP is 128/82" --level thorough
mosaicx query --document report.pdf --chat --trace

[!TIP] Not on Apple Silicon? Use Ollama, vLLM, or any OpenAI-compatible server. See the Getting Started guide for all backend options.

[!TIP] Want the fastest first success? Follow docs/quickstart.md to run extract, verify, and query end-to-end in ~10 minutes.

What You Can Do

Run any command with --help for full options. Complete reference: docs/cli-reference.md

Recipes

# Radiology report -> structured JSON
mosaicx extract --document ct_chest.pdf --mode radiology

# Template-driven extraction (define your own fields)
mosaicx template create --describe "echo report with LVEF, valve grades, impression"
mosaicx extract --document echo.pdf --template EchoReport

# Batch-process a folder of reports
mosaicx extract --dir ./reports --output-dir ./structured --mode radiology --format jsonl

# De-identify a clinical note
mosaicx deidentify --document note.txt

# Patient timeline from multiple reports
mosaicx summarize --dir ./patient_001/ --patient P001

See the full CLI Reference for every flag and option.

Privacy

[!IMPORTANT] Data stays on your machine. MOSAICX runs against a local inference server by default -- no external API calls, no cloud uploads. For HIPAA/GDPR compliance guidance and cloud backend caveats, see Configuration.

LLM Backends

MOSAICX talks to any OpenAI-compatible endpoint via DSPy + litellm. Pick the backend that fits your hardware -- override with env vars.

export MOSAICX_LM=openai/gpt-oss:120b
export MOSAICX_API_BASE=http://localhost:8000/v1   # point at your server
export MOSAICX_API_KEY=dummy                       # or your real key for cloud APIs

SSH tunneling, vLLM-MLX setup, batch tuning, and benchmarking: docs/configuration.md

OCR Engines

By default both engines run in parallel, score each page, and pick the best result. Override with MOSAICX_OCR_ENGINE=surya or chandra.

Configuration

# Essential vars -- point at your local server
export MOSAICX_LM=openai/mlx-community/gpt-oss-20b-MXFP4-Q8   # model name
export MOSAICX_API_BASE=http://localhost:8000/v1                # server URL
export MOSAICX_API_KEY=dummy                                    # or real key for cloud

# View active config
mosaicx config show

Full variable reference, .env file setup, and backend scenarios: docs/configuration.md

Documentation

Development

git clone https://github.com/DIGIT-X-Lab/MOSAICX.git
cd MOSAICX
pip install -e ".[dev]"          # or: uv sync --group dev
pytest tests/ -q

See Developer Guide for custom pipelines and the Python SDK.

Citation

@software{mosaicx2025,
  title   = {MOSAICX: Medical cOmputational Suite for Advanced Intelligent eXtraction},
  author  = {Sundar, Lalith Kumar Shiyam and DIGIT-X Lab},
  year    = {2025},
  url     = {https://github.com/DIGIT-X-Lab/MOSAICX},
  doi     = {10.5281/zenodo.17601890}
}

License

Apache 2.0 -- see LICENSE.

Contact

Research: lalith.shiyam@med.uni-muenchen.de | Commercial: lalith@zenta.solutions | Issues: github.com/DIGIT-X-Lab/MOSAICX/issues