ZeroNinerOne commited on
Commit
7287ea8
Β·
verified Β·
1 Parent(s): cf336b5

Upload agent.py

Browse files
Files changed (1) hide show
  1. api/agent.py +261 -442
api/agent.py CHANGED
@@ -1,353 +1,129 @@
1
  """
2
- NeuroCheck Agentic AI β€” LangGraph Agent
3
- Multi-turn clinical MS reasoning agent powered by Llama 3.1 via Ollama.
4
-
5
  Architecture:
6
- LangGraph StateGraph
7
- β”œβ”€β”€ route_node β†’ decides: greet / ask_more / classify / respond
8
- β”œβ”€β”€ classify_node β†’ runs NeuroCheck classifier (existing engine)
9
- β”œβ”€β”€ rag_node β†’ retrieves relevant MS knowledge chunks
10
- └── respond_node β†’ LLM generates final clinical response
11
-
12
- Tools available to the agent:
13
- β€’ classify_symptoms β€” runs the existing regex+NegEx MS classifier
14
- β€’ search_knowledge β€” queries ChromaDB RAG for clinical context
15
- β€’ get_workup β€” returns tier-specific workup recommendations
16
- β€’ check_emergency β€” checks for emergency patterns
17
  """
18
  from __future__ import annotations
19
 
20
  import json
21
  import os
22
  import re
23
- from typing import Any, Dict, List, TypedDict, Annotated
24
  from loguru import logger
25
 
26
  from langchain_ollama import ChatOllama
27
  from langchain_huggingface import HuggingFaceEndpoint, ChatHuggingFace
28
- from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
29
- from langchain_core.tools import tool
30
- from langgraph.graph import StateGraph, END
31
- from langgraph.prebuilt import ToolNode
32
- from langgraph.graph.message import add_messages
33
 
34
  # ── LLM Setup ─────────────────────────────────────────────────────────────────
35
- LLM_MODEL = "llama3.1:8b"
36
- # ── LLM backend: HuggingFace hosted or local Ollama ──────────────────────────
37
  _HF_TOKEN = os.environ.get("HF_TOKEN", "")
38
  _USE_HF = bool(_HF_TOKEN) and _HF_TOKEN not in ("", "none", "local")
 
39
 
40
  if _USE_HF:
41
  logger.info("[NeuroCheck] Using HuggingFace Inference API ({})", LLM_MODEL)
42
  _hf_endpoint = HuggingFaceEndpoint(
43
- repo_id=os.environ.get("HF_MODEL", "meta-llama/Llama-3.1-8B-Instruct"),
44
  huggingfacehub_api_token=_HF_TOKEN,
45
  temperature=0.1,
46
  max_new_tokens=1024,
47
  )
48
  llm = ChatHuggingFace(llm=_hf_endpoint)
49
  else:
50
- logger.info("[NeuroCheck] Using local Ollama ({})", LLM_MODEL)
51
- llm = ChatOllama(model=LLM_MODEL, temperature=0.1, num_predict=1024)
52
 
53
  # ── System Prompt ─────────────────────────────────────────────────────────────
54
- SYSTEM_PROMPT = """You are NeuroCheck, an advanced clinical decision support AI specializing in Multiple Sclerosis (MS) symptom analysis. You were designed by Dr. Avasarala (MD PhD, University of Kentucky) and Dr. Kadambari (PhD, NIT Warangal).
55
 
56
  YOUR ROLE:
57
  - Conduct a structured clinical interview to gather neurological symptoms
58
- - Identify patterns consistent with MS, NMOSD, MOGAD, or mimics
59
- - Always recommend the standard MS workup when MS is suspected
60
- - Ask focused follow-up questions to clarify key diagnostic anchors
61
  - Never diagnose β€” you provide clinical decision support only
62
 
63
- KEY MS ANCHOR SYMPTOMS to probe for:
64
- 1. Visual: Monocular blurring/dimming, pain on eye movement, colour fading (especially red), double vision, eye jiggling
65
- 2. Sensory: Electric shock down spine on neck bending (Lhermitte's), numbness/tingling in limbs, burning feet, dead limb feeling
66
- 3. Motor: Weakness in limbs, grip failure, foot drop, spasticity, tremor, gait unsteadiness
67
- 4. Brainstem: Diplopia, dizziness/vertigo, swallowing difficulty, facial pain/numbness
68
  5. Autonomic: Bladder urgency, bowel dysfunction
69
- 6. Heat sensitivity (Uhthoff's): Symptoms worsen in heat, after hot shower, during exercise
70
- 7. Tight band sensation around chest/trunk (MS Hug)
71
- 8. Prior episodes that resolved spontaneously (Clinically Isolated Syndrome pattern)
72
 
73
- STANDARD MS WORKUP (always recommend when MS is suspected):
74
- - MRI Orbits with/without contrast (if optic nerve involvement suspected)
75
  - MRI Brain and Spinal Cord with/without contrast
76
- - Lumbar Puncture: CSF for oligoclonal bands (>2 exclusive to CSF), IgG index, kappa free light chains
77
- - Serum Cell-Based Assay: NMO (AQP4-IgG) and MOGAD (MOG-IgG)
78
- - Mimic Screen: Sarcoidosis, Lupus, Vasculitis, B12 deficiency, Cervical Myelopathy
79
-
80
- EMERGENCY FLAGS (respond immediately):
81
- - Sudden face droop + arm weakness + slurred speech β†’ Possible Stroke (999/911)
82
- - Fever + neck stiffness + photophobia β†’ Possible Meningitis (999/911)
83
- - Sudden worst-ever thunderclap headache β†’ Possible Subarachnoid Haemorrhage (999/911)
84
- - Ascending bilateral leg weakness spreading to arms β†’ Possible GBS (999/911)
85
-
86
- TONE: Professional, empathetic, clear. Ask ONE focused follow-up question at a time.
87
-
88
- STRICT RESPONSE RULES β€” follow these exactly:
89
- - NEVER end a response with "Would you like me to guide you through the next steps?"
90
- - NEVER end with "Would you like more information on what to expect?"
91
- - NEVER end with "Would you like to know more about X?"
92
- - NEVER end with "Do you have any questions?" or "Feel free to ask if you have questions."
93
- - NEVER end with "I'm here to support you throughout this process."
94
- - NEVER repeat the same closing question twice in a conversation.
95
- - If you have already asked a follow-up question in a previous turn, do NOT ask the same one again.
96
- - After delivering clinical findings and recommendations, STOP. Do not append generic offers to help.
97
- - If the patient answers "yes" to your follow-up question, move forward with the next clinical step β€” do NOT re-ask the same question.
98
- - If the patient answers "no" to your follow-up question, acknowledge it briefly and move to a DIFFERENT follow-up question β€” do NOT repeat the same question or give the same response again.
99
- - NEVER give the exact same response twice in a conversation under any circumstances.
100
- - NEVER mention other diseases by name (e.g. Trigeminal Neuralgia, NMOSD, MOGAD, Lupus, Sarcoidosis, Vasculitis, NMO, AQP4, MOG-IgG) in the chat response. Focus only on MS. If mimics must be excluded, say "we will run tests to rule out other conditions" β€” do not name them.
101
- - Do NOT say "based on the search results" or "I've searched the clinical knowledge base" β€” respond as a clinician, not a search engine.
102
- - Do NOT say "the tool output suggests", "according to the tool", "the search results highlight" β€” integrate findings naturally.
103
- - Each response must move the clinical conversation FORWARD. Never stay in the same place.
104
- - MAXIMUM 5 follow-up questions per conversation. After 5 "no" answers with no MS symptoms found, conclude clearly that the symptoms described are NOT consistent with MS and suggest the patient see a general practitioner for their actual complaint.
105
- - If the patient describes ONLY non-neurological symptoms (fever, cough, cold, stomach pain, headache alone, nausea, vomiting, diarrhoea, rash, etc.) with NO neurological component, respond immediately: acknowledge their symptom, explain NeuroCheck specialises in MS and neurological symptoms only, and advise them to consult a general practitioner. Do NOT keep asking MS-specific follow-up questions.
106
- - Non-neurological symptoms that should trigger immediate GP redirect: fever, cough, cold, flu, nausea, vomiting, diarrhoea, stomach pain, chest infection, sore throat, skin rash, ear pain, toothache, back pain without neurological features.
107
-
108
- GREETING BEHAVIOUR:
109
- - If the user sends a greeting (hi, hello, hey, thanks, ok, yes, no, good morning, etc.) with NO symptom content, DO NOT call any tools.
110
- - Instead respond warmly, introduce yourself briefly, and ask what symptoms brought them here today.
111
- - Example: "Hello! I'm NeuroCheck, your MS clinical assistant. I'm here to help evaluate neurological symptoms. Could you describe what you've been experiencing?"
112
- - Only call classify_symptoms or search_knowledge when the user has actually described a symptom.
113
- """
114
-
115
- # ── Agent State ───────────────────────────────────────────────────────────────
116
- class AgentState(TypedDict):
117
- messages: Annotated[List, add_messages]
118
- session_id: str
119
- classification: Dict[str, Any] | None
120
- rag_context: str
121
- turn_count: int
122
-
123
-
124
- # ── Tools ─────────────────────────────────────────────────────────────────────
125
- @tool
126
- def classify_symptoms(symptom_text: str) -> str:
127
- """
128
- Run the NeuroCheck MS symptom classifier on the provided text.
129
- Returns tier, detected features, and recommended action.
130
- Use this after gathering sufficient symptom information.
131
- """
132
- try:
133
- # Import here to avoid circular imports
134
- from api.main import classify as _classify
135
- result = _classify(symptom_text)
136
- return json.dumps({
137
- "tier": result.tier,
138
- "tier_label": result.tier_label,
139
- "action": result.action,
140
- "features": [{"label": f.label, "priority": f.priority} for f in result.features],
141
- "temporal_notes": result.temporal_notes,
142
- "workup": result.workup,
143
- }, indent=2)
144
- except Exception as e:
145
- return f"Classifier error: {e}"
146
-
147
-
148
- @tool
149
- def search_knowledge(query: str) -> str:
150
- """
151
- Search the MS clinical knowledge base (150 validated cases + guidelines).
152
- Use this to find relevant case examples or clinical context for the patient's symptoms.
153
- """
154
- try:
155
- from api.rag import query as _query
156
- results = _query(query, n_results=3)
157
- if not results:
158
- return "No relevant knowledge found."
159
- out = []
160
- for r in results:
161
- out.append(f"[{r['source']} | relevance: {r['score']}]\n{r['text']}")
162
- return "\n\n---\n\n".join(out)
163
- except Exception as e:
164
- return f"Knowledge search error: {e}"
165
-
166
-
167
- @tool
168
- def get_workup_recommendations(tier: str) -> str:
169
- """
170
- Get specific workup recommendations for a given MS risk tier.
171
- Tier options: HIGH, MODERATE, WATCH, LOW, CRITICAL_EMERGENCY
172
- """
173
- workup_map = {
174
- "CRITICAL_EMERGENCY": "Call emergency services immediately (999/911). Do not wait.",
175
- "HIGH": (
176
- "Urgent MS Workup Required:\n"
177
- "1. MRI Orbits with/without contrast β€” screen for optic nerve involvement\n"
178
- "2. MRI Brain and Spinal Cord with/without contrast\n"
179
- "3. Lumbar Puncture β€” CSF for oligoclonal bands (>2 exclusive to CSF), IgG index, kappa free light chains\n"
180
- "4. Serum Cell-Based Assay β€” NMO (AQP4-IgG) and MOGAD (MOG-IgG)\n"
181
- "5. Mimic Screen β€” Sarcoidosis, Lupus, Vasculitis, B12 deficiency, Cervical Myelopathy\n"
182
- "6. Urgent Neurology Referral"
183
- ),
184
- "MODERATE": (
185
- "Clinical Review Recommended:\n"
186
- "1. Neurology referral for assessment\n"
187
- "2. Basic blood panel β€” FBC, B12, folate, thyroid, ESR, CRP, ANA\n"
188
- "3. Consider MRI Brain if symptoms persist\n"
189
- "4. Ophthalmology review if visual symptoms present\n"
190
- "5. Symptom diary β€” track onset, duration, triggers"
191
- ),
192
- "WATCH": (
193
- "Monitoring Advised:\n"
194
- "1. Document symptoms β€” dates, frequency, new neurological signs\n"
195
- "2. GP/Family physician review\n"
196
- "3. Seek neurology referral if visual change, numbness, weakness, or coordination problems develop\n"
197
- "4. Re-assess in 4-8 weeks"
198
- ),
199
- "LOW": (
200
- "No Specific MS Features:\n"
201
- "1. Continue monitoring\n"
202
- "2. Keep symptom diary\n"
203
- "3. Seek medical review if new neurological symptoms develop"
204
- ),
205
- }
206
- return workup_map.get(tier.upper(), workup_map["LOW"])
207
-
208
-
209
- TOOLS = [classify_symptoms, search_knowledge, get_workup_recommendations]
210
- tool_node = ToolNode(TOOLS)
211
- llm_with_tools = llm.bind_tools(TOOLS)
212
-
213
-
214
- # ── Graph Nodes ───────────────────────────────────────────────────────────────
215
- def agent_node(state: AgentState) -> AgentState:
216
- """Main reasoning node β€” LLM decides what to do next."""
217
- messages = state["messages"]
218
- turn = state.get("turn_count", 0)
219
-
220
- # Inject RAG context if available
221
- rag_ctx = state.get("rag_context", "")
222
- system_content = SYSTEM_PROMPT
223
- if rag_ctx:
224
- system_content += f"\n\nRELEVANT CLINICAL CONTEXT:\n{rag_ctx}"
225
-
226
- full_messages = [SystemMessage(content=system_content)] + messages
227
- response = llm_with_tools.invoke(full_messages)
228
-
229
- return {
230
- **state,
231
- "messages": [response],
232
- "turn_count": turn + 1,
233
- }
234
-
235
-
236
- def should_continue(state: AgentState) -> str:
237
- """Router: if the LLM called a tool, run tools; else end."""
238
- last = state["messages"][-1]
239
- if hasattr(last, "tool_calls") and last.tool_calls:
240
- return "tools"
241
- return END
242
-
243
-
244
- def rag_prefetch_node(state: AgentState) -> AgentState:
245
- """Pre-fetch RAG context based on the latest user message."""
246
- try:
247
- from api.rag import query as _query
248
- # Get the last human message
249
- last_human = ""
250
- for m in reversed(state["messages"]):
251
- if isinstance(m, HumanMessage):
252
- last_human = m.content
253
- break
254
- if last_human:
255
- results = _query(last_human, n_results=3)
256
- ctx = "\n".join(f"- {r['text']}" for r in results if r["score"] > 0.3)
257
- return {**state, "rag_context": ctx}
258
- except Exception:
259
- pass
260
- return state
261
-
262
-
263
- # ── Build Graph ───────────────────────────────────────────────────────────────
264
- def build_graph() -> StateGraph:
265
- graph = StateGraph(AgentState)
266
-
267
- graph.add_node("rag_prefetch", rag_prefetch_node)
268
- graph.add_node("agent", agent_node)
269
- graph.add_node("tools", tool_node)
270
-
271
- graph.set_entry_point("rag_prefetch")
272
- graph.add_edge("rag_prefetch", "agent")
273
- graph.add_conditional_edges("agent", should_continue, {"tools": "tools", END: END})
274
- graph.add_edge("tools", "agent")
275
-
276
- return graph.compile()
277
-
278
-
279
- # ── Public API ─────────────────────────────────────────────────────────────────
280
- _graph = None
281
-
282
-
283
- def get_graph():
284
- global _graph
285
- if _graph is None:
286
- _graph = build_graph()
287
- return _graph
288
-
289
-
290
- # Greetings / filler words that carry no symptom content
291
- # ── Non-symptom messages that should never hit the classifier ─────────────────
292
  _GREETINGS = {
293
- # Basic greetings
294
  "hi","hey","hello","hiya","howdy","greetings","sup","yo","hai",
295
  "good morning","good afternoon","good evening","good night","good day",
296
  "morning","afternoon","evening",
297
-
298
- # Acknowledgements / filler
299
  "ok","okay","k","kk","sure","alright","got it","understood","i see",
300
- "noted","makes sense","that makes sense","i understand","understood",
301
  "oh i see","oh okay","oh ok","ah ok","ah i see","i get it",
302
-
303
- # Agreements / affirmations
304
  "yes","yeah","yep","yup","yah","ye","yea","correct","exactly","right",
305
  "absolutely","definitely","of course","certainly","indeed","true",
306
  "that's right","thats right","that is right","sounds right",
307
-
308
- # Disagreements / negations (without symptoms)
309
  "no","nope","nah","not really","not sure","i don't know","idk","hmm",
310
  "not yet","maybe","possibly","i think so","i guess","i suppose",
311
-
312
- # Thanks / appreciation
313
  "thanks","thank you","thank you so much","thanks a lot","thank u",
314
  "ty","thnx","thx","many thanks","much appreciated","appreciate it",
315
  "appreciate that","that's helpful","thats helpful","very helpful",
316
  "that helped","that was helpful","that was very helpful",
317
-
318
- # Compliments / positive reactions
319
  "great","awesome","amazing","wonderful","excellent","fantastic","nice",
320
  "good","very good","cool","perfect","brilliant","superb","impressive",
321
  "wow","oh wow","that's great","thats great","that's amazing",
322
  "that's good","thats good","good to know","interesting",
323
-
324
- # Requests to continue / encouragement
325
  "please continue","go on","continue","go ahead","please go on",
326
  "tell me more","and then","and","what else","ok go on","okay go on",
327
-
328
- # Farewells
329
  "bye","goodbye","good bye","see you","see ya","take care","later",
330
  "talk later","ttyl","cya","have a good day","have a nice day",
331
  "farewell","until next time",
332
-
333
- # Meta / about the bot
334
  "who are you","what are you","what is neurocheck","what's neurocheck",
335
  "whats neurocheck","what can you do","how does this work",
336
  "how do you work","what do you do","tell me about yourself",
337
  "are you a doctor","are you an ai","are you real","are you human",
338
-
339
- # Confusion / unclear short inputs
340
  "what","huh","sorry","pardon","can you repeat","come again",
341
  "i didn't understand","i don't understand","please repeat",
342
  "say that again","what do you mean","what does that mean",
343
-
344
- # Common Indian English conversational starters
345
  "hello ji","hi ji","namaste","namaskar","jai hind",
346
  "haan","haan ji","nahi","theek hai","theek","bilkul","accha",
347
  "thoda","shukriya","dhanyawad",
348
  }
349
 
350
- # Regex patterns for non-symptom messages (applied after set lookup)
351
  _GREETING_PATTERNS = [
352
  r"^(hi|hey|hello|good[\s]\w+)[!. ]*$",
353
  r"^(thanks?( you)?[\w ]*)$",
@@ -355,194 +131,237 @@ _GREETING_PATTERNS = [
355
  r"^(yes|no|yeah|nope|yep|nah)[!., ]*$",
356
  r"^(that.s (helpful|great|good|amazing|clear))[!. ]*$",
357
  r"^(how are you|how.s it going)[?!. ]*$",
358
- r"^(nice to meet you|pleased to meet you)[!. ]*$",
359
  r"^(can you help me|i need help)[?!. ]*$",
360
- r"^(what should i do|what do i do|what now)[?!. ]*$",
361
  ]
362
 
 
 
 
 
 
 
 
 
 
363
  def _is_greeting(text: str) -> bool:
364
- """Return True if the message has no symptom content and is conversational filler."""
365
  cleaned = text.strip().lower().rstrip("!.,? ")
366
- # Direct set match
367
  if cleaned in _GREETINGS:
368
  return True
369
- # Regex pattern match
370
  for pat in _GREETING_PATTERNS:
371
  if re.match(pat, cleaned):
372
  return True
373
- # Very short (1-2 words) and in set
374
- if len(cleaned.split()) <= 3 and cleaned in _GREETINGS:
375
- return True
376
  return False
377
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
378
 
379
- def chat(session_id: str, user_message: str, history: List[Dict]) -> str:
380
- """
381
- Process a single user message and return the agent's response.
382
- history: list of {"role": "human"/"assistant", "content": "..."}
383
- """
384
- from langchain_core.messages import HumanMessage as HM, AIMessage as AM
 
 
 
 
385
 
386
- # Fast-path: greetings & conversational inputs bypass the tool-calling graph
387
- # IMPORTANT: only intercept on first turn OR pure openers (hi/hello/hey).
388
- # Mid-conversation short replies like "no", "yes", "ok", "sure" must reach the LLM
389
- # so they are interpreted in context (e.g. answering a clinical follow-up question).
390
- human_turns = len([m for m in history if m["role"] == "human"])
391
- is_first_turn = human_turns <= 1
392
 
393
- # These words are ONLY intercepted on the very first turn β€” they carry
394
- # meaning mid-conversation so must pass through to the LLM after turn 1.
395
- _CONTEXT_DEPENDENT = {
396
- "yes","yeah","yep","yup","yah","ye","yea","no","nope","nah",
397
- "ok","okay","k","kk","sure","alright","got it","understood",
398
- "correct","exactly","right","true","not really","maybe",
399
- "possibly","i think so","i guess","i suppose","i don't know","idk",
400
- "not sure","not yet","hmm","huh","what","go on","continue",
401
- "please continue","go ahead","and","and then","what else",
402
- "good","great","nice","cool","interesting","i see","oh i see",
403
- "makes sense","that makes sense","noted","that's right","thats right",
404
- }
405
 
406
- msg = user_message.strip().lower().rstrip("!.,? ")
407
- if _is_greeting(user_message) and (is_first_turn or msg not in _CONTEXT_DEPENDENT):
 
 
 
 
408
 
409
- # "Who are you / what are you / what is neurocheck"
410
- if any(x in msg for x in ["who are you","what are you","what is neurocheck",
411
- "whats neurocheck","what can you do","tell me about",
412
- "how does this work","how do you work","what do you do"]):
413
- return (
414
- "I'm NeuroCheck, an AI-powered clinical decision support assistant "
415
- "specialising in Multiple Sclerosis (MS) and related neurological conditions.\n\n"
416
- "I was designed by Dr. Avasarala (MD PhD, University of Kentucky) and "
417
- "Dr. Kadambari (PhD, NIT Warangal).\n\n"
418
- "I can help you:\n"
419
- "β€’ Analyse neurological symptoms for MS-related patterns\n"
420
- "β€’ Identify red-flag emergency signs\n"
421
- "β€’ Recommend the appropriate clinical workup (MRI, lumbar puncture, blood tests)\n"
422
- "β€’ Provide clinical context using our MS knowledge base\n\n"
423
- "Please describe your symptoms and I'll begin a structured clinical assessment."
424
- )
 
 
 
 
 
425
 
426
- # "Are you a doctor / are you an AI / are you human"
427
- if any(x in msg for x in ["are you a doctor","are you an ai","are you real",
428
- "are you human","are you a robot"]):
429
- return (
430
- "I'm an AI assistant β€” not a doctor. I provide clinical decision support "
431
- "to help identify patterns that may be consistent with MS or related conditions, "
432
- "but I cannot diagnose.\n\n"
433
- "Now, could you tell me what symptoms you've been experiencing?"
434
- )
435
 
436
- # "Can you help me / I need help"
437
- if any(x in msg for x in ["can you help","i need help","help me","need some help"]):
438
- return (
439
- "Absolutely, I'm here to help. Please describe your neurological symptoms "
440
- "in as much detail as you can β€” what you're feeling, where it is, when it "
441
- "started, and whether it has happened before. I'll conduct a structured "
442
- "clinical assessment from there."
443
- )
 
444
 
445
- # "Sorry / I didn't understand / what do you mean"
446
- if any(x in msg for x in ["sorry","didn't understand","don't understand",
447
- "what do you mean","what does that mean","confused",
448
- "can you repeat","say that again","pardon","huh","what"]):
449
- return (
450
- "No problem! Let me know which part was unclear and I'll explain it "
451
- "differently. Or if you'd like to start fresh, just describe your symptoms "
452
- "and I'll begin the assessment."
453
- )
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
454
 
455
- # Farewell
456
- if any(x in msg for x in ["bye","goodbye","good bye","see you","take care",
457
- "farewell","talk later","ttyl","have a good day",
458
- "have a nice day"]):
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
459
  return (
460
- "Take care! If your symptoms change or new ones develop, don't hesitate "
461
- "to return. Wishing you good health."
 
462
  )
 
 
 
 
 
463
 
464
- # Thanks / appreciation
465
- if any(x in msg for x in ["thank","thanks","ty","thnx","appreciate",
466
- "helpful","that helped","very helpful"]):
467
- return (
468
- "You're welcome! If you have more symptoms to discuss or any follow-up "
469
- "questions, I'm here. Is there anything else you'd like me to assess?"
470
- )
471
 
472
- # Default greeting / filler (first turn vs returning)
473
- if is_first_turn:
474
- return (
475
- "Hello! I'm NeuroCheck, your MS clinical decision support assistant.\n\n"
476
- "I'm here to help evaluate neurological symptoms that may be related to "
477
- "Multiple Sclerosis or similar conditions. Could you describe what you've "
478
- "been experiencing? Please include when it started, which part of the body "
479
- "is affected, and whether it has happened before."
480
- )
481
- else:
482
- return (
483
- "Of course! Please go ahead and describe your symptoms. "
484
- "Include when they started, which part of the body is affected, "
485
- "and whether anything makes them better or worse."
486
- )
487
 
488
- # Rebuild message history for LangGraph
489
- lc_history = []
490
- for m in history[:-1]: # exclude the latest (just added)
491
- if m["role"] == "human":
492
- lc_history.append(HM(content=m["content"]))
493
- else:
494
- lc_history.append(AM(content=m["content"]))
495
-
496
- lc_history.append(HM(content=user_message))
497
-
498
- state: AgentState = {
499
- "messages": lc_history,
500
- "session_id": session_id,
501
- "classification": None,
502
- "rag_context": "",
503
- "turn_count": len(history),
504
- }
505
-
506
- g = get_graph()
507
- result = g.invoke(state)
508
-
509
- # Extract final text response
510
- # Handle both native tool_calls (Ollama) and text-embedded JSON (HF Inference API)
511
- final_msg = result["messages"][-1]
512
- content = final_msg.content if hasattr(final_msg, "content") else str(final_msg)
513
-
514
- # If HF returned a raw tool-call JSON block instead of prose, execute it and re-invoke
515
- import json as _json, re as _re
516
- tool_json_match = _re.search(
517
- r'[{]"type"\s*:\s*"function".*?"arguments"\s*:\s*([{].*?[}])\s*[}]',
518
- content, _re.DOTALL
519
  )
520
- if tool_json_match:
521
- try:
522
- outer = _json.loads(tool_json_match.group(0))
523
- tool_name = outer.get("name", "")
524
- args = outer.get("arguments", {})
525
- # Execute the tool directly
526
- tool_result = ""
527
- if tool_name == "classify_symptoms":
528
- tool_result = classify_symptoms.invoke(args)
529
- elif tool_name == "search_knowledge":
530
- tool_result = search_knowledge.invoke(args)
531
- elif tool_name == "get_workup_recommendations":
532
- tool_result = get_workup_recommendations.invoke(args)
533
-
534
- if tool_result:
535
- # Re-invoke LLM with the tool result so it generates a proper response
536
- from langchain_core.messages import ToolMessage
537
- followup_messages = (
538
- [SystemMessage(content=SYSTEM_PROMPT)]
539
- + lc_history
540
- + [AM(content=content)]
541
- + [HM(content="Clinical data:\n" + str(tool_result) + "\n\nRespond as a clinician. Rules: (1) Do NOT say based on search results or I searched the knowledge base. (2) Do NOT name any diseases other than MS. (3) If symptoms are non-neurological like fever or cough, immediately tell the patient NeuroCheck specialises in MS and refer them to a GP. (4) If no MS features found after thorough questioning, conclude clearly. (5) Move assessment forward β€” never repeat the same question.")]
542
- )
543
- final_response = llm.invoke(followup_messages)
544
- return final_response.content if hasattr(final_response, "content") else str(final_response)
545
- except Exception as e:
546
- logger.warning("[agent] Tool JSON fallback failed: {}", e)
547
-
548
- return content
 
1
  """
2
+ NeuroCheck Agentic AI β€” Direct Architecture (no tool-calling)
3
+ =============================================================
 
4
  Architecture:
5
+ Every user message with symptom content is ALWAYS classified by Python directly.
6
+ The LLM NEVER calls tools β€” it only generates clinical prose.
7
+
8
+ Flow:
9
+ 1. Greeting check β†’ fast-path response (no LLM)
10
+ 2. Python runs classifier + RAG directly
11
+ 3. Results injected into LLM prompt as structured context
12
+ 4. LLM generates ONLY the clinical conversation response
13
+ 5. Response returned β€” guaranteed no JSON ever
 
 
14
  """
15
  from __future__ import annotations
16
 
17
  import json
18
  import os
19
  import re
20
+ from typing import Any, Dict, List
21
  from loguru import logger
22
 
23
  from langchain_ollama import ChatOllama
24
  from langchain_huggingface import HuggingFaceEndpoint, ChatHuggingFace
25
+ from langchain_core.messages import HumanMessage as HM, AIMessage as AM, SystemMessage
 
 
 
 
26
 
27
  # ── LLM Setup ─────────────────────────────────────────────────────────────────
 
 
28
  _HF_TOKEN = os.environ.get("HF_TOKEN", "")
29
  _USE_HF = bool(_HF_TOKEN) and _HF_TOKEN not in ("", "none", "local")
30
+ LLM_MODEL = os.environ.get("HF_MODEL", "mistralai/Mistral-7B-Instruct-v0.3")
31
 
32
  if _USE_HF:
33
  logger.info("[NeuroCheck] Using HuggingFace Inference API ({})", LLM_MODEL)
34
  _hf_endpoint = HuggingFaceEndpoint(
35
+ repo_id=LLM_MODEL,
36
  huggingfacehub_api_token=_HF_TOKEN,
37
  temperature=0.1,
38
  max_new_tokens=1024,
39
  )
40
  llm = ChatHuggingFace(llm=_hf_endpoint)
41
  else:
42
+ logger.info("[NeuroCheck] Using local Ollama (llama3.1:8b)")
43
+ llm = ChatOllama(model="llama3.1:8b", temperature=0.1, num_predict=1024)
44
 
45
  # ── System Prompt ─────────────────────────────────────────────────────────────
46
+ SYSTEM_PROMPT = """You are NeuroCheck, a clinical decision support AI specialising in Multiple Sclerosis (MS). Designed by Dr. Avasarala (MD PhD, University of Kentucky) and Dr. Kadambari (PhD, NIT Warangal).
47
 
48
  YOUR ROLE:
49
  - Conduct a structured clinical interview to gather neurological symptoms
50
+ - Use the CLASSIFIER RESULT and RAG CONTEXT provided to you to guide your response
51
+ - Ask focused follow-up questions to clarify key MS diagnostic anchors
 
52
  - Never diagnose β€” you provide clinical decision support only
53
 
54
+ KEY MS ANCHOR SYMPTOMS to probe:
55
+ 1. Visual: Monocular blurring/dimming, pain on eye movement, colour fading, double vision
56
+ 2. Sensory: Electric shock down spine on neck bending (Lhermitte's), numbness/tingling, burning
57
+ 3. Motor: Limb weakness, grip failure, foot drop, spasticity, tremor, gait unsteadiness
58
+ 4. Brainstem: Diplopia, dizziness/vertigo, facial pain/numbness, swallowing difficulty
59
  5. Autonomic: Bladder urgency, bowel dysfunction
60
+ 6. Heat sensitivity (Uhthoff): Symptoms worse in heat, hot showers, exercise
61
+ 7. Tight band around chest/trunk (MS Hug)
62
+ 8. Prior episodes that resolved spontaneously (CIS pattern)
63
 
64
+ STANDARD MS WORKUP (recommend when MS suspected):
65
+ - MRI Orbits with/without contrast (optic nerve)
66
  - MRI Brain and Spinal Cord with/without contrast
67
+ - Lumbar Puncture: oligoclonal bands (>2 exclusive to CSF), IgG index, kappa free light chains
68
+ - Serum assay for NMO and MOGAD
69
+ - Mimic screen: run tests to rule out other conditions
70
+
71
+ EMERGENCY FLAGS β€” respond immediately:
72
+ - Sudden face droop + arm weakness + slurred speech β†’ Possible Stroke (call 999/911)
73
+ - Fever + neck stiffness + photophobia β†’ Possible Meningitis (call 999/911)
74
+ - Thunderclap worst-ever headache β†’ Possible Subarachnoid Haemorrhage (call 999/911)
75
+ - Ascending bilateral leg weakness β†’ Possible GBS (call 999/911)
76
+
77
+ STRICT RULES β€” NEVER BREAK THESE:
78
+ - NEVER output JSON, tool calls, function calls, or code of any kind
79
+ - NEVER say "based on search results", "I searched", "the tool says", "classifier output"
80
+ - NEVER name other diseases (NMOSD, MOGAD, Lupus, Sarcoidosis, NMO, AQP4, MOG-IgG, Vasculitis) β€” say "we will test to rule out other conditions"
81
+ - NEVER repeat the same response or question twice
82
+ - NEVER end with "Would you like to know more?" or "Do you have any questions?"
83
+ - NEVER keep asking MS questions if patient has ONLY non-neurological symptoms (fever, cough, cold, nausea, stomach pain) β€” redirect to GP immediately
84
+ - MAXIMUM 5 follow-up questions β€” after 5 "no" answers with no MS features, conclude clearly
85
+ - Each response MUST move the conversation forward
86
+ - Ask only ONE follow-up question per response
87
+ - Respond ONLY in plain conversational English prose"""
88
+
89
+ # ── Non-symptom fast-path ─────────────────────────────────────────────────────
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
90
  _GREETINGS = {
 
91
  "hi","hey","hello","hiya","howdy","greetings","sup","yo","hai",
92
  "good morning","good afternoon","good evening","good night","good day",
93
  "morning","afternoon","evening",
 
 
94
  "ok","okay","k","kk","sure","alright","got it","understood","i see",
95
+ "noted","makes sense","that makes sense","i understand",
96
  "oh i see","oh okay","oh ok","ah ok","ah i see","i get it",
 
 
97
  "yes","yeah","yep","yup","yah","ye","yea","correct","exactly","right",
98
  "absolutely","definitely","of course","certainly","indeed","true",
99
  "that's right","thats right","that is right","sounds right",
 
 
100
  "no","nope","nah","not really","not sure","i don't know","idk","hmm",
101
  "not yet","maybe","possibly","i think so","i guess","i suppose",
 
 
102
  "thanks","thank you","thank you so much","thanks a lot","thank u",
103
  "ty","thnx","thx","many thanks","much appreciated","appreciate it",
104
  "appreciate that","that's helpful","thats helpful","very helpful",
105
  "that helped","that was helpful","that was very helpful",
 
 
106
  "great","awesome","amazing","wonderful","excellent","fantastic","nice",
107
  "good","very good","cool","perfect","brilliant","superb","impressive",
108
  "wow","oh wow","that's great","thats great","that's amazing",
109
  "that's good","thats good","good to know","interesting",
 
 
110
  "please continue","go on","continue","go ahead","please go on",
111
  "tell me more","and then","and","what else","ok go on","okay go on",
 
 
112
  "bye","goodbye","good bye","see you","see ya","take care","later",
113
  "talk later","ttyl","cya","have a good day","have a nice day",
114
  "farewell","until next time",
 
 
115
  "who are you","what are you","what is neurocheck","what's neurocheck",
116
  "whats neurocheck","what can you do","how does this work",
117
  "how do you work","what do you do","tell me about yourself",
118
  "are you a doctor","are you an ai","are you real","are you human",
 
 
119
  "what","huh","sorry","pardon","can you repeat","come again",
120
  "i didn't understand","i don't understand","please repeat",
121
  "say that again","what do you mean","what does that mean",
 
 
122
  "hello ji","hi ji","namaste","namaskar","jai hind",
123
  "haan","haan ji","nahi","theek hai","theek","bilkul","accha",
124
  "thoda","shukriya","dhanyawad",
125
  }
126
 
 
127
  _GREETING_PATTERNS = [
128
  r"^(hi|hey|hello|good[\s]\w+)[!. ]*$",
129
  r"^(thanks?( you)?[\w ]*)$",
 
131
  r"^(yes|no|yeah|nope|yep|nah)[!., ]*$",
132
  r"^(that.s (helpful|great|good|amazing|clear))[!. ]*$",
133
  r"^(how are you|how.s it going)[?!. ]*$",
 
134
  r"^(can you help me|i need help)[?!. ]*$",
 
135
  ]
136
 
137
+ _CONTEXT_DEPENDENT = {
138
+ "yes","yeah","yep","yup","no","nope","nah","ok","okay","sure",
139
+ "alright","got it","understood","correct","exactly","right","true",
140
+ "not really","maybe","possibly","i think so","i guess","hmm","huh",
141
+ "what","go on","continue","please continue","go ahead","and","good",
142
+ "great","nice","cool","interesting","i see","oh i see","makes sense",
143
+ "noted","that's right","thats right","i don't know","idk","not sure",
144
+ }
145
+
146
  def _is_greeting(text: str) -> bool:
 
147
  cleaned = text.strip().lower().rstrip("!.,? ")
 
148
  if cleaned in _GREETINGS:
149
  return True
 
150
  for pat in _GREETING_PATTERNS:
151
  if re.match(pat, cleaned):
152
  return True
 
 
 
153
  return False
154
 
155
+ def _greeting_response(msg: str, is_first_turn: bool) -> str | None:
156
+ if any(x in msg for x in ["who are you","what are you","what is neurocheck",
157
+ "whats neurocheck","what can you do","tell me about",
158
+ "how does this work","how do you work","what do you do"]):
159
+ return (
160
+ "I'm NeuroCheck, an AI-powered clinical decision support assistant "
161
+ "specialising in Multiple Sclerosis (MS) and related neurological conditions.\n\n"
162
+ "I was designed by Dr. Avasarala (MD PhD, University of Kentucky) and "
163
+ "Dr. Kadambari (PhD, NIT Warangal).\n\n"
164
+ "I can help you:\n"
165
+ "β€’ Analyse neurological symptoms for MS-related patterns\n"
166
+ "β€’ Identify red-flag emergency signs\n"
167
+ "β€’ Recommend the appropriate clinical workup\n\n"
168
+ "Please describe your symptoms and I'll begin a structured clinical assessment."
169
+ )
170
+ if any(x in msg for x in ["are you a doctor","are you an ai","are you real","are you human","are you a robot"]):
171
+ return (
172
+ "I'm an AI assistant β€” not a doctor. I provide clinical decision support "
173
+ "to help identify patterns consistent with MS, but I cannot diagnose.\n\n"
174
+ "Could you tell me what symptoms you've been experiencing?"
175
+ )
176
+ if any(x in msg for x in ["can you help","i need help","help me","need some help"]):
177
+ return (
178
+ "Absolutely, I'm here to help. Please describe your neurological symptoms "
179
+ "in as much detail as you can β€” what you're feeling, where it is, when it "
180
+ "started, and whether it has happened before."
181
+ )
182
+ if any(x in msg for x in ["sorry","didn't understand","don't understand",
183
+ "what do you mean","can you repeat","say that again","pardon"]):
184
+ return (
185
+ "No problem! Let me know which part was unclear and I'll explain differently. "
186
+ "Or just describe your symptoms and I'll start a fresh assessment."
187
+ )
188
+ if any(x in msg for x in ["bye","goodbye","good bye","see you","take care","farewell","ttyl"]):
189
+ return "Take care! If your symptoms change or new ones develop, don't hesitate to return. Wishing you good health."
190
+ if any(x in msg for x in ["thank","thanks","ty","thnx","appreciate","helpful","that helped"]):
191
+ return "You're welcome! Is there anything else you'd like me to assess?"
192
+ if is_first_turn:
193
+ return (
194
+ "Hello! I'm NeuroCheck, your MS clinical decision support assistant.\n\n"
195
+ "I'm here to help evaluate neurological symptoms that may be related to "
196
+ "Multiple Sclerosis. Could you describe what you've been experiencing? "
197
+ "Please include when it started, which part of the body is affected, "
198
+ "and whether it has happened before."
199
+ )
200
+ return None
201
+
202
+
203
+ # ── Python-side classification and RAG ───────────────────────────────────────
204
+ def _run_classifier(text: str) -> dict:
205
+ """Run the MS classifier directly in Python. Never fails β€” returns empty dict on error."""
206
+ try:
207
+ from api.main import classify as _classify
208
+ result = _classify(text)
209
+ return {
210
+ "tier": result.tier,
211
+ "tier_label": result.tier_label,
212
+ "action": result.action,
213
+ "features": [f.label for f in result.features],
214
+ "workup": result.workup[:5],
215
+ }
216
+ except Exception as e:
217
+ logger.warning("[agent] Classifier error: {}", e)
218
+ return {}
219
+
220
 
221
+ def _run_rag(text: str) -> str:
222
+ """Query the RAG knowledge base. Returns empty string on error."""
223
+ try:
224
+ from api.rag import query as _query
225
+ results = _query(text, n_results=3)
226
+ chunks = [r["text"] for r in results if r.get("score", 0) > 0.3]
227
+ return "\n\n".join(chunks[:3])
228
+ except Exception as e:
229
+ logger.warning("[agent] RAG error: {}", e)
230
+ return ""
231
 
 
 
 
 
 
 
232
 
233
+ # ── Build LLM prompt ──────────────────────────────────────────────────────────
234
+ def _build_context_block(cls: dict, rag: str) -> str:
235
+ """Build a structured context block injected into the LLM prompt."""
236
+ parts = []
 
 
 
 
 
 
 
 
237
 
238
+ if cls:
239
+ tier = cls.get("tier", "LOW")
240
+ label = cls.get("tier_label", "")
241
+ action = cls.get("action", "")
242
+ feats = cls.get("features", [])
243
+ workup = cls.get("workup", [])
244
 
245
+ parts.append(f"CLASSIFIER RESULT:\n Risk tier: {tier} β€” {label}")
246
+ if feats:
247
+ parts.append(" Detected MS features: " + ", ".join(feats))
248
+ else:
249
+ parts.append(" Detected MS features: none identified yet")
250
+ if action:
251
+ parts.append(f" Recommended action: {action}")
252
+ if workup and tier not in ("LOW",):
253
+ parts.append(" Workup steps:\n" + "\n".join(f" - {w}" for w in workup))
254
+
255
+ if rag:
256
+ parts.append(f"CLINICAL KNOWLEDGE CONTEXT:\n{rag}")
257
+
258
+ if not parts:
259
+ return ""
260
+
261
+ return (
262
+ "\n\n--- CLINICAL DATA (use this to guide your response, do NOT quote it directly) ---\n"
263
+ + "\n\n".join(parts)
264
+ + "\n--- END CLINICAL DATA ---"
265
+ )
266
 
 
 
 
 
 
 
 
 
 
267
 
268
+ # ── Main chat function ────────────────────────────────────────────────────────
269
+ def chat(session_id: str, user_message: str, history: List[Dict]) -> str:
270
+ """
271
+ Process a user message and return the agent's clinical response.
272
+ Always returns clean prose β€” never JSON, never tool call text.
273
+ """
274
+ human_turns = len([m for m in history if m["role"] == "human"])
275
+ is_first_turn = human_turns <= 1
276
+ msg = user_message.strip().lower().rstrip("!.,? ")
277
 
278
+ # ── Fast-path: greetings ──────────────────────────────────────────────────
279
+ if _is_greeting(user_message) and (is_first_turn or msg not in _CONTEXT_DEPENDENT):
280
+ response = _greeting_response(msg, is_first_turn)
281
+ if response:
282
+ return response
283
+
284
+ # ── Step 1: Run classifier + RAG directly in Python ───────────────────────
285
+ # Accumulate all human messages for richer classification context
286
+ all_human_text = " ".join(
287
+ m["content"] for m in history if m["role"] == "human"
288
+ ) + " " + user_message
289
+
290
+ cls_result = _run_classifier(all_human_text.strip())
291
+ rag_context = _run_rag(user_message)
292
+
293
+ # ── Step 2: Build prompt with injected context ────────────────────────────
294
+ context_block = _build_context_block(cls_result, rag_context)
295
+ system_with_context = SYSTEM_PROMPT + context_block
296
+
297
+ # Rebuild conversation history for LLM
298
+ lc_messages = [SystemMessage(content=system_with_context)]
299
+ for m in history[:-1]:
300
+ if m["role"] == "human":
301
+ lc_messages.append(HM(content=m["content"]))
302
+ else:
303
+ lc_messages.append(AM(content=m["content"]))
304
+ lc_messages.append(HM(content=user_message))
305
 
306
+ # ── Step 3: LLM generates ONLY prose ─────────────────────────────────────
307
+ try:
308
+ response = llm.invoke(lc_messages)
309
+ content = response.content if hasattr(response, "content") else str(response)
310
+ except Exception as e:
311
+ logger.error("[agent] LLM error: {}", e)
312
+ return (
313
+ "I'm having trouble connecting to the AI service right now. "
314
+ "Please try again in a moment."
315
+ )
316
+
317
+ # ── Step 4: Safety net β€” strip any JSON that slipped through ─────────────
318
+ content = _strip_all_json(content)
319
+ content = content.strip()
320
+
321
+ if not content:
322
+ # LLM returned nothing useful β€” give a sensible fallback based on classifier
323
+ tier = cls_result.get("tier", "LOW")
324
+ if tier in ("HIGH", "CRITICAL_EMERGENCY", "MODERATE"):
325
+ feats = cls_result.get("features", [])
326
+ feat_str = ", ".join(feats) if feats else "the symptoms you described"
327
  return (
328
+ f"Based on {feat_str}, there are features that warrant a neurological assessment. "
329
+ "Could you tell me more about when these symptoms first appeared and "
330
+ "whether you've had any similar episodes in the past?"
331
  )
332
+ return (
333
+ "Thank you for sharing that. Could you tell me more about your symptoms β€” "
334
+ "when they started, which part of the body is affected, and whether "
335
+ "anything makes them better or worse?"
336
+ )
337
 
338
+ return content
 
 
 
 
 
 
339
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
340
 
341
+ def _strip_all_json(text: str) -> str:
342
+ """
343
+ Aggressively remove any JSON or tool-call content from LLM output.
344
+ Handles all known HF Inference API formats.
345
+ """
346
+ # Remove {"type": "function", ...} blocks
347
+ text = re.sub(
348
+ r'\{[^{}]*"type"\s*:\s*"function"[^{}]*(?:\{[^{}]*\}[^{}]*)?\}',
349
+ "", text, flags=re.DOTALL
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
350
  )
351
+ # Remove any remaining {...} blocks that look like tool calls
352
+ text = re.sub(
353
+ r'\{[^{}]*"name"\s*:\s*"[a-z_]+"[^{}]*\}',
354
+ "", text, flags=re.DOTALL
355
+ )
356
+ # Remove [{"type": ...}] array wrappers
357
+ text = re.sub(
358
+ r'\[\s*\{[^[\]]*"(?:type|name)"[^[\]]*\}\s*\]',
359
+ "", text, flags=re.DOTALL
360
+ )
361
+ # Remove <tool_call>...</tool_call> XML style
362
+ text = re.sub(r'<tool_call>[\s\S]*?</tool_call>', "", text)
363
+ # Remove ```json ... ``` code blocks
364
+ text = re.sub(r'```(?:json)?[\s\S]*?```', "", text)
365
+ # Clean up extra blank lines left behind
366
+ text = re.sub(r'\n{3,}', '\n\n', text)
367
+ return text.strip()