AGENTS.md

تبيان الطبي — Agent System

Overview

The multi-agent pipeline in backend/services/agents/ processes each medical file through five sequential agents. Each agent reads from and writes to a shared AgentContext dataclass, making the full pipeline observable and independently testable.

---

Base Classes (agents/base.py)

AgentContext

Shared state object threaded through all agents. Key fields:

Field	Type	Set by
file_bytes	bytes	Coordinator
file_type	"pdf" | "image"	Coordinator
raw_text	str	OCRAgent
findings	list[dict]	ExtractionAgent
panel_code	str	ClassificationAgent
rag_context	str	MedicalReasoningAgent
report	dict	MedicalReasoningAgent
logs	list[AgentLogEntry]	All agents

AgentBase

Abstract base with:

• Retry logic: up to max_retries=2 attempts with 0.3 s × 2^attempt backoff
• _on_failure(ctx, exc): each subclass overrides to provide a safe fallback when all retries fail
• Timing: each run() call records duration_ms in AgentLogEntry

---

Agents

1. OCRAgent

File: agents/ocr_agent.py

Input: ctx.file_bytes, ctx.file_type Output: ctx.raw_text

Strategy:

• PDF: extracts text with PyMuPDF (fitz); falls back to EasyOCR page-by-page if text layer is empty
• Image: tries Google Cloud Vision first (higher accuracy for Arabic); falls back to EasyOCR with contrast/sharpness preprocessing

Failure mode: sets raw_text = "" — downstream agents handle empty text gracefully.

---

2. ExtractionAgent

File: agents/extraction_agent.py

Input: ctx.raw_text Output: ctx.findings (list of {name, value, unit, range, status})

Strategy:

1. Regex patterns matching common Arabic/English lab report formats
2. LLM extraction via Groq if regex yields < 2 findings
3. Physiological bounds filter (_validators.py) removes impossible values (e.g., hemoglobin = 400)
4. Deduplication by normalized test name

Failure mode: sets findings = [].

---

3. ClassificationAgent

File: agents/classification_agent.py

Input: ctx.findings, ctx.raw_text Output: ctx.panel_code, ctx.panel_confidence

Strategy: Uses services/classifier.py which scores text against panel-specific keyword sets. Falls back to detect_panel() heuristic if primary classifier returns low confidence.

Panels: cbc, thyroid, liver, kidney, lipid, diabetes, urine, mixed

Failure mode: sets panel_code = "mixed" (general analysis).

---

4. MedicalReasoningAgent

File: agents/reasoning_agent.py

Input: ctx.findings, ctx.panel_code, ctx.analysis_type Output: ctx.rag_context, ctx.report

Strategy:

1. Checks rag_cache (TTL 5 min) for identical query
2. Retrieves relevant medical knowledge via Retriever (BM25 + pgvector + Cohere rerank)
3. Selects panel-specific prompt template from prompts/
4. Calls Groq llama-3.3-70b-versatile with findings + RAG context
5. Parses JSON response into structured report

Failure mode: generates a fallback report from raw findings without LLM, appends disclaimer.

---

5. SafetyAgent

File: agents/safety_agent.py

Input: ctx.report Output: ctx.report (filtered in-place)

Strategy: Applies services/safety.filter_analysis_report() which:

• Removes diagnostic certainty claims ("you have diabetes")
• Adds standard medical disclaimer
• Detects emergency patterns (very high/low critical values) and prepends urgent notice

Failure mode: appends DISCLAIMER_AR manually to ensure minimum safety even if filter itself errors.

---

AgentCoordinator (agents/coordinator.py)

Instantiates all five agents and runs them in sequence. Returns CoordinatorResult:

@dataclass
class CoordinatorResult:
    findings:   list[dict]
    summary:    str
    report:     dict
    panel_code: str
    logs:       list[dict]   # exposed in dev mode via _agents field
    ok:         bool
    error:      str
    total_ms:   float

The coordinator is loaded once via @lru_cache and reused across requests. Agent instances are stateless — all state lives in the per-request AgentContext.

---

Adding a New Agent

1. Create agents/my_agent.py, subclass AgentBase
2. Implement _execute(self, ctx: AgentContext) -> AgentContext
3. Implement _on_failure(self, ctx, exc) with a safe fallback
4. Add new fields to AgentContext if needed
5. Register in AgentCoordinator.__init__() agent list at the correct position