Medical GraphRAG Assistant

# Medical GraphRAG Assistant - System Status **Last Updated**: November 22, 2025 **Version**: v2.12.0 ## System Health: ✅ OPERATIONAL All core systems are functioning and deployed to production. --- ## Production Environment (AWS) ### Infrastructure - **Status**: ✅ Running - **Instance**: EC2 g5.xlarge (i-0432eba10b98c4949) - **Public IP**: 3.84.250.46 - **Region**: us-east-1 - **GPU**: NVIDIA A10G (available) - **OS**: Ubuntu 24.04 LTS ### InterSystems IRIS Database - **Status**: ✅ Healthy - **Container**: iris-vector-db - **Ports**: 1972 (SQL), 52773 (Management Portal) - **Namespace**: %SYS (active), SQLUser (tables) - **Connection**: Remote access working via Python client **Database Tables:** | Table | Records | Status | Description | |-------|---------|--------|-------------| | SQLUser.ClinicalNoteVectors | 51 | ✅ | FHIR documents with 1024-dim NV-CLIP embeddings | | VectorSearch.MIMICCXRImages | 50 | ✅ | Medical images with 1024-dim NV-CLIP embeddings | | SQLUser.Entities | 83 | ✅ | GraphRAG entities (temporal, symptoms, conditions, etc.) | | SQLUser.EntityRelationships | 540 | ✅ | Entity relationships (CO_OCCURS_WITH) | | SQLUser.AgentMemoryVectors | ~5 | ✅ | Agent memories with semantic embeddings | ### NVIDIA NIM Services - **Status**: ✅ Running - **Service**: NV-CLIP (nvidia/nvclip) - **Port**: 8002 - **Endpoint**: http://localhost:8002/v1 - **Embeddings**: 1024-dimensional multimodal (text + image) - **Performance**: ~38 img/sec ingestion, <100ms query ### AWS Bedrock - **Status**: ✅ Available - **Model**: Claude Sonnet 4.5 (global.anthropic.claude-sonnet-4-5-20250929-v1:0) - **API**: Converse API via AWS CLI - **Authentication**: AWS_PROFILE configured --- ## Local Development Environment ### Streamlit UI - **Status**: ✅ Running - **URL**: http://localhost:8501 - **Process**: streamlit run (PID varies) - **Version**: v2.12.0 with Agent Memory Editor ### SSH Tunnel - **Status**: ✅ Active - **Purpose**: Local access to AWS NIM (port 8002) - **Command**: `ssh -f -N -L 8002:localhost:8002 -i ~/.ssh/medical-graphrag-key.pem ubuntu@3.84.250.46` - **Note**: Required for local NV-CLIP embeddings ### Python Environment - **Status**: ✅ Configured - **Python**: 3.10+ - **Key Packages**: - intersystems-irispython (IRIS client) - boto3 (AWS SDK) - streamlit (UI) - pydicom (medical imaging) - mcp SDK --- ## Feature Status ### Core Features ✅ - [x] FHIR document search (full-text + vector) - [x] GraphRAG knowledge graph (entities + relationships) - [x] Medical image search (NV-CLIP semantic search) - [x] Agent memory system (semantic recall) - [x] Hybrid search with RRF fusion - [x] Interactive visualizations (charts + networks) - [x] MCP server with 10+ tools - [x] Streamlit chat interface ### Recent Fixes (v2.12.0) ✅ - [x] Real NV-CLIP embeddings for images (fixed from mock vectors) - [x] Real NV-CLIP embeddings for memories (fixed from mock vectors) - [x] Memory search UI session state persistence - [x] Empty search string support (browse all memories) - [x] Type conversion for similarity scores (IRIS string→float) ### Known Limitations - Medical images: Limited to 50 MIMIC-CXR samples (awaiting full dataset) - Agent memories: Small dataset (~5 memories currently) - GraphRAG entities: Extracted from 51 documents only - IRIS namespace: Using %SYS workaround (DEMO has access restrictions) --- ## Configuration ### Active Config Files - **AWS Production**: `config/fhir_graphrag_config.aws.yaml` - **Local Development**: `config/fhir_graphrag_config.yaml` - **Infrastructure**: `config/aws-config.yaml` ### Environment Variables (Required) ```bash # AWS export AWS_PROFILE=122293094970_PowerUserPlusAccess # IRIS Database export IRIS_HOST=3.84.250.46 export IRIS_PORT=1972 export IRIS_NAMESPACE=%SYS export IRIS_USERNAME=_SYSTEM export IRIS_PASSWORD=*** # NV-CLIP export NVCLIP_BASE_URL=http://localhost:8002/v1 # via SSH tunnel ``` --- ## Performance Metrics ### Query Performance (Measured) - **Vector search**: 1.038s (30 results) - **Text search**: 0.018s (23 results with hex decoding) - **Graph search**: 0.014s (9 entity matches) - **Full multi-modal**: 0.242s (vector + text + graph fusion) - **Fast query**: 0.006s (text + graph only, 40x faster) ### Data Scale - **FHIR documents**: 51 clinical notes vectorized - **Medical images**: 50 chest X-rays vectorized - **GraphRAG entities**: 83 entities extracted - **Relationships**: 540 entity co-occurrences - **Agent memories**: ~5 semantic memories - **Total vector records**: ~150 ### Resource Utilization (AWS) - **RAM**: 8.5 GB / 63.7 GB (13% - healthy) - **GPU**: NVIDIA A10G available - **Disk**: <1 GB vector data --- ## Testing Status ### Integration Tests ✅ - **Suite**: tests/test_integration.py - **Results**: 13/13 passing (100%) - **Coverage**: - Database schema validation - FHIR data integrity - Vector search functionality - Text search with hex decoding - Graph entity search - RRF fusion - Patient filtering - Edge case handling - Performance benchmarks ### Entity Quality ✅ - **Extraction**: 100% high confidence - **No exceptions**: All tests passed - **Graceful errors**: Edge cases handled --- ## Deployment History ### Latest Deployment: v2.12.0 (November 22, 2025) - Agent memory system with pure IRIS vectors - Medical image search with NV-CLIP - Memory editor UI in Streamlit sidebar - Embeddings fixes (real vectors, not mocks) ### Previous Major Releases - **v2.10.0**: GraphRAG multi-modal search - **v2.0.0**: AWS deployment with NVIDIA NIM - **v1.0.0**: Initial FHIR + vector search --- ## Current Priorities ### Immediate (In Progress) - Documentation review and cleanup ✅ (this session) - Root directory organization ✅ (completed) ### Short-term (Next) - Ingest full MIMIC-CXR dataset (377K images) - Expand agent memory usage in conversations - Production monitoring and alerting ### Long-term (Planned) - Enhanced entity extraction with NIM LLM - Multi-hop reasoning in GraphRAG - Clinical decision support interface --- ## Troubleshooting Quick Reference ### Common Issues **1. "NV-CLIP embeddings returning zeros"** - Check: `NVCLIP_BASE_URL` set correctly - Verify: SSH tunnel active (port 8002) - Test: `curl http://localhost:8002/v1/embeddings` **2. "IRIS connection refused"** - Check: `IRIS_HOST` and credentials - Verify: AWS EC2 instance running - Test: `python -c "from src.db.connection import get_connection; print(get_connection())"` **3. "Memory search not displaying results"** - Check: Session state persistence in Streamlit - Verify: Embeddings magnitude > 0 (not mock) - Test: Search with empty query (browse all) **4. "Medical images not found"** - Check: Image paths relative to project root - Verify: DICOM files exist in expected location - Test: `python -c "import os; print(os.path.exists('path/to/image'))"` --- ## Monitoring Commands ### Check Database Health ```bash python -c " from src.db.connection import get_connection conn = get_connection() cursor = conn.cursor() cursor.execute('SELECT COUNT(*) FROM VectorSearch.MIMICCXRImages') print(f'Images: {cursor.fetchone()[0]}') cursor.execute('SELECT COUNT(*) FROM SQLUser.Entities') print(f'Entities: {cursor.fetchone()[0]}') " ``` ### Verify Embeddings Quality ```bash python -c " from src.db.connection import get_connection conn = get_connection() cursor = conn.cursor() cursor.execute('SELECT TOP 3 ImageID, VECTOR_DOT_PRODUCT(Vector, Vector) as magnitude FROM VectorSearch.MIMICCXRImages') for row in cursor.fetchall(): status = '✅ REAL' if row[1] > 0 else '❌ MOCK' print(f'{row[0][:30]}: {row[1]:.4f} {status}') " ``` ### Check Streamlit Process ```bash ps aux | grep streamlit # Expected: python -m streamlit run streamlit_app.py --server.port 8501 ``` ### Test SSH Tunnel ```bash curl -X POST http://localhost:8002/v1/embeddings \ -H 'Content-Type: application/json' \ -d '{"input": ["test"], "model": "nvidia/nvclip"}' # Expected: JSON response with 1024-dim embedding ``` --- ## Contact & Support - **Documentation**: See README.md, PROGRESS.md, archive/docs/ - **Troubleshooting**: See docs/troubleshooting.md - **Architecture**: See docs/architecture.md - **Deployment**: See docs/deployment-guide.md **System Status**: All systems operational ✅