Full implementation of the Maker-Checker-Refiner RAG pipeline described in the README. Copy each code block into a single .py file (or a Colab notebook cell per section) in the order shown.
pip install groq chromadb sentence-transformers numpyimport re
import uuid
import numpy as np
from datetime import datetime
from typing import List, Dict, Any
import chromadb
from chromadb.utils import embedding_functions
from sentence_transformers import SentenceTransformer
from groq import Groq
# Set your Groq API key as an environment variable before running:
# export GROQ_API_KEY="your_key_here"
import os
GROQ_API_KEY = os.environ.get("GROQ_API_KEY", "")
MODEL_NAME = "llama-3.3-70b-versatile"
EMBEDDING_MODEL = "all-MiniLM-L6-v2"MEDICAL_KNOWLEDGE = [
{
"id": "diabetes_001",
"content": "Type 2 diabetes management includes lifestyle modifications "
"(diet and exercise), oral medications (metformin as first-line), "
"GLP-1 receptor agonists, SGLT2 inhibitors, and insulin therapy when needed. "
"Regular monitoring of blood glucose and HbA1c is essential.",
"topic": "diabetes",
"source": "ADA Clinical Practice Guidelines 2024",
"reliability": 0.95
},
{
"id": "hypertension_001",
"content": "Hypertension treatment typically starts with lifestyle changes such as "
"reduced sodium intake, regular exercise, and weight management. "
"First-line medications include ACE inhibitors, ARBs, calcium channel "
"blockers, and thiazide diuretics.",
"topic": "hypertension",
"source": "AHA/ACC Hypertension Guidelines 2024",
"reliability": 0.95
},
{
"id": "covid_001",
"content": "COVID-19 symptoms range from mild to severe and include fever, cough, "
"fatigue, and loss of taste or smell. Vaccination remains the most "
"effective way to prevent severe illness and hospitalization.",
"topic": "covid",
"source": "CDC Guidelines 2024",
"reliability": 0.93
},
{
"id": "antibiotics_001",
"content": "Antibiotics should only be used for bacterial infections, not viral "
"infections like colds or flu. Completing the full prescribed course "
"helps prevent antibiotic resistance.",
"topic": "antibiotics",
"source": "WHO Antimicrobial Stewardship Guidelines 2024",
"reliability": 0.94
},
{
"id": "cancer_screening_001",
"content": "Routine cancer screening recommendations vary by age, sex, and risk "
"factors. Common screenings include mammography, colonoscopy, Pap smears, "
"and low-dose CT for lung cancer in high-risk individuals.",
"topic": "cancer_screening",
"source": "USPSTF Screening Guidelines 2024",
"reliability": 0.94
},
{
"id": "mental_health_001",
"content": "Common mental health conditions include anxiety and depressive disorders. "
"Treatment options include psychotherapy (CBT), medication management, and "
"lifestyle interventions. Early intervention improves outcomes significantly.",
"topic": "mental_health",
"source": "APA Clinical Guidelines 2024",
"reliability": 0.92
},
{
"id": "nutrition_001",
"content": "A balanced diet includes a variety of fruits, vegetables, whole grains, "
"lean proteins, and healthy fats. Limiting processed foods, added sugars, "
"and excess sodium supports long-term health.",
"topic": "nutrition",
"source": "USDA Dietary Guidelines 2024",
"reliability": 0.90
},
{
"id": "vaccination_001",
"content": "Vaccination schedules vary by age and health status. Routine adult "
"vaccinations include influenza, Tdap, shingles, and pneumococcal vaccines, "
"in addition to any required boosters.",
"topic": "vaccination",
"source": "CDC Immunization Schedule 2024",
"reliability": 0.95
},
]class InputValidator:
"""Sanitizes input and blocks malicious or unsafe patterns."""
MALICIOUS_PATTERNS = [
r"<script.*?>.*?</script>", # XSS
r"(union|select|drop|insert|delete)\s+.*\s+(from|table)", # SQL injection
r"\.\./", # path traversal
r"(eval|exec)\s*\(", # code injection
]
CRISIS_KEYWORDS = [
"suicide", "kill myself", "end my life", "self harm", "hurt myself"
]
HARMFUL_KEYWORDS = [
"how to make a bomb", "synthesize drug", "overdose amount to die"
]
def validate(self, query: str) -> Dict[str, Any]:
result = {"is_safe": True, "reason": None, "crisis_detected": False}
for pattern in self.MALICIOUS_PATTERNS:
if re.search(pattern, query, re.IGNORECASE):
result["is_safe"] = False
result["reason"] = "malicious_pattern_detected"
return result
lowered = query.lower()
if any(keyword in lowered for keyword in self.CRISIS_KEYWORDS):
result["crisis_detected"] = True
result["reason"] = "crisis_language_detected"
return result
if any(keyword in lowered for keyword in self.HARMFUL_KEYWORDS):
result["is_safe"] = False
result["reason"] = "harmful_content_request"
return result
return result
def sanitize(self, query: str) -> str:
query = re.sub(r"[<>{}\[\]]", "", query)
return query.strip()[:1000]class VectorStore:
"""Handles document embedding and semantic retrieval."""
def __init__(self, knowledge_base: List[Dict]):
self.client = chromadb.Client()
self.embedder = SentenceTransformer(EMBEDDING_MODEL)
self.collection = self.client.create_collection(
name=f"medical_kb_{uuid.uuid4().hex[:8]}"
)
self._index_documents(knowledge_base)
def _index_documents(self, knowledge_base: List[Dict]):
contents = [doc["content"] for doc in knowledge_base]
embeddings = self.embedder.encode(contents).tolist()
self.collection.add(
ids=[doc["id"] for doc in knowledge_base],
embeddings=embeddings,
documents=contents,
metadatas=[
{
"topic": doc["topic"],
"source": doc["source"],
"reliability": doc["reliability"],
}
for doc in knowledge_base
],
)
def retrieve(self, query: str, top_k: int = 3) -> List[Dict]:
query_embedding = self.embedder.encode([query]).tolist()
results = self.collection.query(
query_embeddings=query_embedding,
n_results=top_k,
)
retrieved = []
for i in range(len(results["ids"][0])):
retrieved.append({
"content": results["documents"][0][i],
"source": results["metadatas"][0][i]["source"],
"reliability": results["metadatas"][0][i]["reliability"],
"distance": results["distances"][0][i],
})
return retrievedclass MakerAgent:
"""Generates the initial response using retrieved context and Groq's LLM."""
def __init__(self, client: Groq):
self.client = client
def generate(self, query: str, retrieved_docs: List[Dict]) -> str:
context = "\n\n".join(
f"[Source: {doc['source']}]\n{doc['content']}" for doc in retrieved_docs
)
system_prompt = (
"You are a medical information assistant. Answer using ONLY the "
"provided context. Do not diagnose. Do not prescribe medication doses. "
"Cite the sources you used. Always include a disclaimer recommending "
"the user consult a licensed healthcare provider."
)
user_prompt = f"Context:\n{context}\n\nQuestion: {query}\n\nAnswer:"
response = self.client.chat.completions.create(
model=MODEL_NAME,
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_prompt},
],
temperature=0.3,
max_tokens=600,
)
return response.choices[0].message.contentclass CheckerAgent:
"""Validates the maker's response against six safety and quality checks."""
DIAGNOSIS_PHRASES = [
"you have", "you are diagnosed with", "this confirms you", "you definitely have"
]
def check(self, response: str, retrieved_docs: List[Dict]) -> Dict[str, Any]:
checks = {
"has_disclaimer": self._has_disclaimer(response),
"no_diagnosis_language": self._no_diagnosis(response),
"has_citations": self._has_citations(response, retrieved_docs),
"appropriate_length": 50 <= len(response.split()) <= 400,
"no_harmful_content": self._no_harmful_content(response),
"reasonable_confidence": self._confidence_score(retrieved_docs) >= 0.5,
}
passed = all(checks.values())
confidence = self._confidence_score(retrieved_docs)
return {
"passed": passed,
"checks": checks,
"confidence": round(confidence, 2),
"failed_checks": [k for k, v in checks.items() if not v],
}
def _has_disclaimer(self, text: str) -> bool:
markers = ["consult", "healthcare provider", "medical advice", "qualified"]
lowered = text.lower()
return any(marker in lowered for marker in markers)
def _no_diagnosis(self, text: str) -> bool:
lowered = text.lower()
return not any(phrase in lowered for phrase in self.DIAGNOSIS_PHRASES)
def _has_citations(self, text: str, retrieved_docs: List[Dict]) -> bool:
sources = [doc["source"].split()[0] for doc in retrieved_docs]
return any(source.lower() in text.lower() for source in sources) or "source" in text.lower()
def _no_harmful_content(self, text: str) -> bool:
harmful = ["overdose", "lethal dose", "how to harm"]
lowered = text.lower()
return not any(phrase in lowered for phrase in harmful)
def _confidence_score(self, retrieved_docs: List[Dict]) -> float:
if not retrieved_docs:
return 0.0
reliabilities = [doc["reliability"] for doc in retrieved_docs]
avg_reliability = sum(reliabilities) / len(reliabilities)
avg_distance = sum(doc["distance"] for doc in retrieved_docs) / len(retrieved_docs)
relevance = max(0, 1 - avg_distance)
return (avg_reliability * 0.6) + (relevance * 0.4)class RefinerAgent:
"""Rewrites the response when the checker flags issues."""
def __init__(self, client: Groq):
self.client = client
def refine(self, query: str, original_response: str, failed_checks: List[str],
retrieved_docs: List[Dict]) -> str:
context = "\n\n".join(
f"[Source: {doc['source']}]\n{doc['content']}" for doc in retrieved_docs
)
issues = ", ".join(failed_checks)
system_prompt = (
"You are revising a medical assistant response to fix specific issues. "
"Keep everything that already works. Only fix the listed problems. "
"Do not diagnose. Do not prescribe doses. Always end with a disclaimer "
"recommending the user consult a licensed healthcare provider."
)
user_prompt = (
f"Original question: {query}\n\n"
f"Context:\n{context}\n\n"
f"Original response:\n{original_response}\n\n"
f"Issues to fix: {issues}\n\n"
"Provide the corrected response:"
)
response = self.client.chat.completions.create(
model=MODEL_NAME,
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_prompt},
],
temperature=0.3,
max_tokens=600,
)
return response.choices[0].message.contentclass AgenticRAGSystem:
"""Ties together validation, retrieval, and the maker-checker-refiner loop."""
CRISIS_MESSAGE = (
"It sounds like you might be going through something very difficult right now. "
"You deserve support. Please reach out to a crisis line right away, such as the "
"988 Suicide and Crisis Lifeline (call or text 988 in the US), or contact local "
"emergency services. You do not have to go through this alone."
)
def __init__(self, max_refine_attempts: int = 2):
self.validator = InputValidator()
self.vector_store = VectorStore(MEDICAL_KNOWLEDGE)
self.groq_client = Groq(api_key=GROQ_API_KEY)
self.maker = MakerAgent(self.groq_client)
self.checker = CheckerAgent()
self.refiner = RefinerAgent(self.groq_client)
self.max_refine_attempts = max_refine_attempts
def process_query(self, query: str) -> Dict[str, Any]:
timestamp = datetime.utcnow().isoformat()
# Step 1: Input validation
validation = self.validator.validate(query)
if validation["crisis_detected"]:
return {
"answer": self.CRISIS_MESSAGE,
"confidence": None,
"sources": [],
"flagged": "crisis",
"timestamp": timestamp,
}
if not validation["is_safe"]:
return {
"answer": "I can't help with that request.",
"confidence": None,
"sources": [],
"flagged": validation["reason"],
"timestamp": timestamp,
}
clean_query = self.validator.sanitize(query)
# Step 2: Retrieval
retrieved_docs = self.vector_store.retrieve(clean_query, top_k=3)
if not retrieved_docs:
return {
"answer": "I don't have relevant information on that topic in my "
"knowledge base. Please consult a healthcare provider directly.",
"confidence": 0.0,
"sources": [],
"flagged": "no_context_found",
"timestamp": timestamp,
}
# Step 3: Maker generates the initial answer
response = self.maker.generate(clean_query, retrieved_docs)
# Step 4/5: Checker validates, Refiner loops until it passes or attempts run out
attempt = 0
check_result = self.checker.check(response, retrieved_docs)
while not check_result["passed"] and attempt < self.max_refine_attempts:
response = self.refiner.refine(
clean_query, response, check_result["failed_checks"], retrieved_docs
)
check_result = self.checker.check(response, retrieved_docs)
attempt += 1
return {
"answer": response,
"confidence": check_result["confidence"],
"sources": [
f"{doc['source']} (Reliability: {int(doc['reliability'] * 100)}%)"
for doc in retrieved_docs
],
"flagged": None if check_result["passed"] else "unresolved_checks",
"refine_attempts": attempt,
"timestamp": timestamp,
}if __name__ == "__main__":
rag_system = AgenticRAGSystem()
result = rag_system.process_query("What are treatment options for type 2 diabetes?")
print(result["answer"])
print(f"\nConfidence: {result['confidence']}")
print("Sources:")
for source in result["sources"]:
print(f" - {source}")def add_document(rag_system: AgenticRAGSystem, doc: Dict[str, Any]):
"""Adds a new document to the existing vector store at runtime."""
embedding = rag_system.vector_store.embedder.encode([doc["content"]]).tolist()
rag_system.vector_store.collection.add(
ids=[doc["id"]],
embeddings=embedding,
documents=[doc["content"]],
metadatas=[{
"topic": doc["topic"],
"source": doc["source"],
"reliability": doc["reliability"],
}],
)
# Example
add_document(rag_system, {
"id": "custom_001",
"content": "Your medical content here...",
"topic": "topic_name",
"source": "Source Name 2024",
"reliability": 0.95,
})- Set
GROQ_API_KEYas an environment variable before running, don't hardcode it in the file. - The crisis keyword list and harmful keyword list are minimal starting points. For production use, expand them and consider a dedicated classifier instead of substring matching.
- The
max_refine_attemptsparameter caps how many times the refiner loop runs, so a query that keeps failing checks won't loop forever. - This system is for education and general health information only, not a diagnostic or prescribing tool.