ML_IMPLEMENTATION.md

# ML Implementation

MediFlow now has two NLP implementation paths:

1. `ml/hf_intent_demo.mjs` runs a Hugging Face Transformers.js zero-shot classifier.
2. `ml/mediflow_nlp.py` runs a lightweight local baseline using a Naive Bayes intent classifier plus rule-based department and FAQ routing.

The Hugging Face path is the profile-relevant implementation. The Python baseline is kept as a transparent fallback and testing harness.

## Hugging Face Demo

Install dependencies:

```powershell
npm install
```

Run model inference:

```powershell
npm run demo
```

The script downloads and runs `Xenova/all-MiniLM-L6-v2` through `@huggingface/transformers` for sentence embeddings. A nearest-centroid classifier is built from the labeled examples in `data/intent_dataset.jsonl`. It predicts:

- User intent: booking, cancellation, FAQ, feedback, or human handoff.
- Department for booking requests: Cardiology, Orthopedics, Dermatology, Pediatrics, or Internal Medicine.

Results are written to:

```text
output/hf-demo-results.json
```

Latest verified run:

```text
Model: Xenova/all-MiniLM-L6-v2
Task: feature-extraction
Classifier: nearest-centroid over labeled project examples
Evaluation: leave-one-out
Examples: 28
Accuracy: 0.8571
```

The first attempted zero-shot MNLI classifier over-routed examples to handoff, so it was replaced with the embedding retrieval approach above. That failure is useful evidence: the project now shows model selection, error analysis, and iteration instead of only a polished happy path.

## Why This Matters

This moves the project from "chatbot plan" to "implemented ML inference demo":

- Uses a real model from Hugging Face.
- Produces reproducible inference outputs.
- Separates model inference from UI state management.
- Includes a small labeled dataset and evaluation report.
- Shows an explicit model-selection iteration from weak zero-shot classification to embedding-based routing.
- Gives a clear upgrade path to a Hugging Face Space, Botpress Action, or API endpoint.

## Current Boundary

The current implementation is an inference demo, not a fine-tuned production model. A stronger ML engineering version would add:

- A larger labeled dataset.
- Fine-tuning or embedding-based retrieval.
- Evaluation split with precision, recall, F1, and confusion matrix.
- Model card with limitations and intended use.
- API endpoint consumed by the chatbot UI.
- Deployment as a Hugging Face Space.