ella-sdk 1.1.0

Medical Triage & Clinical RAG Engine

⭐ If Ella's RAG-based medical triage architecture gave you ideas — a star helps other health-AI builders find it. Takes 2 seconds.

ELLA

Medical Triage & Clinical RAG Engine

Ella is a production-grade Retrieval-Augmented Generation (RAG) system purpose-built for medical triage.
She ingests 90,000+ clinical text chunks, embeds them via NVIDIA NIM, stores them in Pinecone, and retrieves context-grounded answers through a multi-stage pipeline — eliminating hallucinations in healthcare workflows.

Key Features • Architecture • Live Demo • Python SDK • CLI

---

Key Features

• 90,000+ Clinical Chunks — Ingested from medical handbooks, symptom guides, and pharmacology references
• NVIDIA NIM Embeddings — nvidia/nv-embedqa-e5-v5 (1024-dim) via OpenAI-compatible API for semantic search
• Pinecone Vector DB — Serverless cloud storage with cosine similarity for instant retrieval
• Hybrid Search — Semantic (NIM) + BM25 keyword matching + CrossEncoder reranking
• 5-Class Intent Router — Emergency, Triage, Booking, General Info, Closing — validated via Pydantic schemas
• 96% Intent Accuracy — Benchmark-validated on 50 curated clinical queries
• Guardrail System — Emergency detection prevents life-threatening cases from being misrouted
• Multi-Turn State Awareness — Conversation history maintained across triage sessions

---

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        PATIENT INPUT                                │
└────────────────────────────┬────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│  INTENT ROUTER (Groq llama-3.1-8b-instant + Pydantic Schema)      │
│  Classifies: EMERGENCY │ TRIAGE │ BOOKING │ GENERAL_INFO │ CLOSING │
└────────────────────────────┬────────────────────────────────────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
      ┌──────────┐  ┌──────────────┐  ┌──────────┐
      │ EMERGENCY │  │    TRIAGE    │  │ BOOKING  │
      │ GUARDRAIL │  │  RAG SEARCH  │  │ HANDLER  │
      └──────────┘  └──────┬───────┘  └──────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    RETRIEVAL PIPELINE                               │
│                                                                     │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────────────────┐  │
│  │  NVIDIA NIM  │   │   BM25      │   │  CrossEncoder Reranker  │  │
│  │  Embeddings  │ + │  Keyword    │ → │  ms-marco-MiniLM-L-6   │  │
│  │  (Semantic)  │   │  Matching   │   │  (Top-10 → Top-3)      │  │
│  └──────┬──────┘   └──────┬──────┘   └───────────┬─────────────┘  │
│         │                 │                      │                  │
│         ▼                 ▼                      ▼                  │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │              PINECONE VECTOR DATABASE                       │   │
│  │         90,306 vectors • cosine • 1024 dimensions           │   │
│  └─────────────────────────────────────────────────────────────┘   │
└────────────────────────────┬────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│  SYNTHESIS (Groq llama-3.1-8b-instant)                             │
│  Grounded response + clinical justification + source attribution    │
└────────────────────────────┬────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       PATIENT RESPONSE                              │
└─────────────────────────────────────────────────────────────────────┘

---

Live Demo

→ Launch Ella on HuggingFace Spaces

Ella is deployed on HuggingFace Spaces with a custom dark medical UI. Type a medical question and see the full pipeline in action — intent classification, thought process, retrieved context, and grounded response.

---

Benchmark

Evaluation on 50 curated clinical queries (20 Triage, 10 Emergency, 10 Booking, 5 General Info, 5 Closing):

Metric	Value
Intent Accuracy	96.0%
Avg Latency	9.26s
Avg Retrieval Score	0.92
Records in DB	90,306

Intent Breakdown

Intent	Correct	Total	Accuracy
EMERGENCY	10	10	100%
TRIAGE	18	20	90%
BOOKING	10	10	100%
GENERAL_INFO	5	5	100%
CLOSING	5	5	100%

---

How It Works

1. Intent Routing

Every patient message passes through a State-Aware Router powered by Groq's llama-3.1-8b-instant. The router analyzes both the current input and conversation history, classifying intent into one of five streams: Emergency, Triage, Booking, General Info, or Closing. Outputs are validated via Pydantic schemas to guarantee structured responses.

2. Emergency Guardrail

Before any retrieval occurs, the system checks for life-threatening keywords and patterns. If detected, Ella immediately escalates to emergency protocol — bypassing the standard RAG pipeline to ensure patient safety.

3. Hybrid Retrieval

For clinical queries, Ella executes a three-stage retrieval pipeline:

• Stage 1 — Semantic Search: NVIDIA NIM embeddings (nv-embedqa-e5-v5) convert the query into a 1024-dimensional vector. Pinecone returns the top-15 candidates via cosine similarity.
• Stage 2 — BM25 Reranking: A keyword-based BM25 algorithm re-scores candidates to capture medical terminology that semantic search might miss.
• Stage 3 — CrossEncoder Precision: A ms-marco-MiniLM-L-6-v2 cross-encoder reranks the top-10 results, selecting the top-3 most relevant passages.

4. Grounded Synthesis

The LLM receives the patient query alongside the retrieved clinical context. Every response includes:

• Clinical justification — why this information applies
• Source attribution — which medical handbook the data came from
• Confidence scoring — retrieval similarity score for transparency

5. Multi-Turn State

Ella maintains conversation history across sessions. If a patient says "yes" after describing symptoms, the router understands the context and continues the triage flow — enabling natural, human-like clinical conversations.

---

Tech Stack

Layer	Technology	Purpose
Embeddings	NVIDIA NIM (nv-embedqa-e5-v5)	1024-dim semantic vectors
Vector DB	Pinecone (Serverless, AWS)	Cosine similarity search
LLM	Groq (llama-3.1-8b-instant)	Intent classification + response generation
Reranker	CrossEncoder (ms-marco-MiniLM-L-6-v2)	Precision reranking
Orchestration	LangChain + LangGraph	Agent pipeline
Validation	Pydantic	Schema-validated outputs
Data	SQLite + PDFs	90k clinical text chunks

---

CLI

Ella ships with a single command entry point:

# Install
pip install -e .

# Interactive triage session
ella

# Start API server (localhost:8000)
ella serve

---

Use via API

Ella is available as a Python SDK — just like OpenAI or Groq.

Install

pip install ella-medical

Quick Start

from ella_medical import Ella

client = Ella()
response = client.query("What are the symptoms of a heart attack?")

print(response.intent)         # "TRIAGE"
print(response.thought_process)
print(response.response)       # Grounded clinical response
print(response.retrieved_context)

With Conversation History

from ella_medical import Ella

client = Ella()

# First message
r1 = client.query("I have chest pain")

# Follow-up (pass history from previous response)
r2 = client.query(
    "What about treatment options?",
    history=f"Patient: I have chest pain\nElla: {r1.response}"
)

print(r2.response)

Local Server

# Start the FastAPI server
ella serve

# Connect with custom base URL
from ella_medical import Ella

client = Ella(base_url="http://localhost:8000")
response = client.query("What are the symptoms of a heart attack?")

Response Object

@dataclass
class QueryResponse:
    intent: str            # EMERGENCY | TRIAGE | BOOKING | GENERAL_INFO | CLOSING
    priority: str          # Priority level
    thought_process: str   # Router's reasoning
    justification: str     # Clinical justification
    response: str          # Ella's response
    retrieved_context: str # Retrieved medical documents

---

License

MIT License — see LICENSE for details.

---

Built with ❤️ for healthcare AI