MODEL_INTEGRATION_NOTES.md

# SentinelRx Model Integration Notes

Use this file when your teammate is ready to plug in the final models.

## Current placeholder functions

The app currently has two placeholder functions:

```python
def run_severity_model(text: str) -> Dict:
    ...

def run_medical_extraction_model(text: str) -> Dict:
    ...
```

## Expected severity model return format

The app expects the severity model function to return:

```python
{
    "label": "Mild" | "Moderate" | "Severe",
    "probability": 0.0 to 1.0,
    "drivers": ["important phrase 1", "important phrase 2"],
    "note": "short explanation"
}
```

## Expected extraction model return format

The app expects the extraction model function to return:

```python
{
    "medications": ["Risedronate"],
    "symptoms": ["nausea", "headache"],
    "timing": ["two days ago"],
    "patient_context": ["Osteoporosis"]
}
```

## Example: replacing the severity function with a Transformers pipeline

```python
from transformers import pipeline

severity_pipeline = pipeline(
    "text-classification",
    model="YOUR_TEAM/YOUR_SEVERITY_MODEL",
    return_all_scores=True
)

def run_severity_model(text: str) -> Dict:
    raw = severity_pipeline(text)[0]
    best = max(raw, key=lambda x: x["score"])

    label_map = {
        "LABEL_0": "Mild",
        "LABEL_1": "Severe"
    }

    return {
        "label": label_map.get(best["label"], best["label"]),
        "probability": float(best["score"]),
        "drivers": [],
        "note": "Output from trained severity model."
    }
```

## Example: replacing the extraction function with an NER pipeline

```python
from transformers import pipeline

ner_pipeline = pipeline(
    "token-classification",
    model="YOUR_NER_MODEL",
    aggregation_strategy="simple"
)

def run_medical_extraction_model(text: str) -> Dict:
    entities = ner_pipeline(text)

    medications = []
    symptoms = []
    timing = []
    patient_context = []

    for ent in entities:
        group = ent["entity_group"].lower()
        word = ent["word"]

        if "drug" in group or "medication" in group:
            medications.append(word)
        elif "symptom" in group or "disease" in group:
            symptoms.append(word)
        elif "date" in group or "time" in group:
            timing.append(word)
        else:
            patient_context.append(word)

    return {
        "medications": sorted(set(medications)) or ["Not detected"],
        "symptoms": sorted(set(symptoms)) or ["Not detected"],
        "timing": sorted(set(timing)) or ["Not detected"],
        "patient_context": sorted(set(patient_context)) or ["Not detected"]
    }
```

## Where the agentic part happens

The agent-like workflow is handled by:

```python
triage_agent(severity, extraction, case)
```

This function does not diagnose. It uses model outputs plus SentinelRx profile data to:

1. Prioritize the case
2. Summarize why it was prioritized
3. Identify missing fields
4. Recommend a next human review step
5. Prepare report content
```