Gemini Summarization Proxy
Relevant source files
The following files were used as context for generating this wiki page:
The Gemini Summarization Proxy is a specialized backend service within the OpenMRS AI EHR ecosystem designed to handle Large Language Model (LLM) operations. Built using Python and the FastAPI framework, its primary purpose is to act as a secure intermediary between the EHR's internal services and Google's Gemini API. It facilitates complex clinical data processing, specifically focusing on generating patient summaries and performing structured extraction from medical documentation.
This service is a critical component of the "AI/ML Backend" layer, working alongside the main AI Backend to provide advanced natural language processing capabilities. While the main AI Backend handles transcription and general orchestration, the Gemini Proxy is dedicated to LLM-backed summarization and proxying requests that require high-level clinical reasoning or synthesis.
Sources: README.md:14-25, AGENTS.md:8-12, openMRS-main/gemini_proxy.py
System Architecture
The Gemini Summarization Proxy operates as a standalone containerized service, typically running on port 8001. It is integrated into the broader OpenMRS architecture via a Docker-based deployment strategy, where it interacts with the EHR Dashboard and the main OpenMRS backend.
Component Interaction
The following diagram illustrates how the Gemini Proxy fits into the clinical data workflow:
The Gemini Proxy serves as the bridge between the user-facing EHR Dashboard and external AI intelligence.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:33-43, AGENTS.md:18-21
Key Functionalities
The proxy is responsible for several high-value AI features that enhance the clinical workflow for doctors and nurses.
1. LLM-Backed Summarization
The service processes raw clinical data—such as patient history, vitals, and notes—and utilizes the Gemini model to produce concise, actionable patient overviews. This reduces the cognitive load on healthcare providers by synthesizing disparate data points into a single narrative.
Sources: README.md:20, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:12-20
2. Structured Extraction
The proxy supports the extraction of structured medical data from unstructured text. This includes identifying specific clinical concepts like chief complaints, diagnoses, and vitals from natural language documentation.
Sources: readmes/ARCHITECTURE_OVERVIEW.md, openMRS-main/main.py
3. Secure Proxying
By centralizing LLM interactions, the proxy ensures that sensitive GEMINI_API_KEY credentials remain server-side and are never exposed to the frontend (SPA) or the client browser.
Sources: AGENTS.md:38-42, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:79-84
Service Configuration
The Gemini Summarization Proxy requires specific environment variables and network settings to operate correctly within the production and development environments.
Environment Variables
| Variable | Description | Source |
|---|---|---|
GEMINI_API_KEY | Required key from Google AI Studio for LLM access. | README.md:65 |
OPENMRS_API_URL | The REST API endpoint for the core OpenMRS backend. | README.md:61 |
OPENMRS_USERNAME | Admin/Service account for metadata/data lookups. | README.md:62 |
OPENMRS_PASSWORD | Password for the OpenMRS service account. | README.md:62 |
Deployment Ports
| Environment | Port | Host |
|---|---|---|
| Development | 8001 | localhost |
| Production | 8001 | internal-network / server-ip |
Sources: AGENTS.md:18-21, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:130-140
Data Flow: Summarization Request
The sequence below outlines the standard request flow when a clinician accesses a patient overview in the EHR Dashboard.
The proxy orchestrates the transformation of raw clinical data into a synthesized summary using external AI.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:33-43, readmes/ARCHITECTURE_OVERVIEW.md
Development and Maintenance
Running the Service Locally
To start the Gemini Proxy for development purposes, navigate to the openMRS-main directory and use the uvicorn server:
cd openMRS-main
source venv/bin/activate
uvicorn gemini_proxy:app --host 0.0.0.0 --port 8001 --reload
Sources: README.md:95-100, AGENTS.md:20-21
Troubleshooting
- API Key Errors: If the
GEMINI_API_KEYis invalid or missing from the.envfile, the service will start, but endpoints will return 500 or provider-specific errors. - Connection Refused: Ensure the proxy is running on port
8001and that no firewall is blocking internal communication between the Dashboard and the Proxy. - Metadata Stability: The proxy relies on stable UUIDs for clinical concepts defined in
medical_documentation_config.json. Changes to metadata in OpenMRS must be reflected in the proxy's logic to maintain extraction accuracy.
Sources: README.md:155-170, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:175-185
Conclusion
The Gemini Summarization Proxy is a fundamental component of the OpenMRS AI EHR, enabling sophisticated clinical intelligence through Large Language Models. By providing a secure and specialized interface for the Gemini API, it empowers healthcare providers with automated summaries and structured data extraction, directly contributing to improved efficiency and patient care quality.