Repository navigation
Releases: hastimal/gemini-healthcare-agentic-platform
Release list
v1.2.0 — Taking Gemini Healthcare Agents to Google Kubernetes Engine (GKE)
v1.2.0 — Taking Gemini Healthcare Agents to Google Kubernetes Engine (GKE)
v1.2.0 brings the Gemini Healthcare Agentic Platform from local and Docker execution to a cloud-native deployment on Google Kubernetes Engine (GKE).
This release demonstrates how a Gemini-powered, Google ADK multi-agent healthcare workflow can be containerized, deployed on Kubernetes, exposed on demand through GKE, and validated end to end through a Streamlit interface.
Highlights
- Gemini as the reasoning and synthesis layer
- Google ADK multi-agent orchestration
- MCP-backed healthcare tools
- NPPES provider retrieval
- PubMed scientific research
- Docker containerization
- Kubernetes deployment manifests
- Google Kubernetes Engine runtime
- Kubernetes readiness and liveness probes
- On-demand GKE LoadBalancer demo
- Enhanced Streamlit agent workflow visualization
- End-to-end Gemini UI validation
Google ADK Multi-Agent Workflow
The core workflow remains a three-agent architecture:
User Question
|
v
Search Planner Agent
|
v
Healthcare Research Agent
|
v
MCP Tools
/ \
NPPES PubMed
\ /
Evidence
|
v
Ranking & Selection
|
v
Evidence & Answer Agent
|
v
Gemini
|
v
Grounded Answer
+ Recommendations
+ Citations
+ Limitations
Evidence Ranking is a processing stage between retrieval and final synthesis rather than a separate agent.
Google Kubernetes Engine Deployment
The application is now deployable on GKE using Kubernetes resources for:
- Namespace
- ConfigMap
- Secret template
- Deployment
- Service
- CPU and memory requests and limits
- Readiness probe
- Liveness probe
The Streamlit application runs on port 8501.
Kubernetes health checks use:
/_stcore/health
Validated GKE runtime:
- Pod: 1/1 Running
- Restarts: 0
- Deployment: 1/1 Available
- Readiness probe: PASS
- Liveness probe: PASS
- External UI: PASS
- Google ADK workflow: PASS
- Gemini execution: PASS
Cloud-Native Runtime
Docker Image
|
v
Kubernetes
|
v
Google Kubernetes Engine
|
v
GKE LoadBalancer Service
|
v
Streamlit UI
|
v
Google ADK Agents
|
v
Gemini + MCP Healthcare Tools
This establishes a complete path from local development to a working cloud-native Gemini agent deployment.
On-Demand Public Demo
The project does not require a hard-coded external IP.
When a public demo is needed:
Need Demo
|
v
Enable LoadBalancer
|
v
GKE assigns dynamic external IP
|
v
Script discovers current IP
|
v
Open Streamlit demo
|
v
Run Gemini / ADK workflow
|
v
Demo complete
|
v
Return Service to ClusterIP
This allows the public LoadBalancer to be used only when needed for demos.
Demo helper scripts include:
- scripts/demo-up.sh
- scripts/demo-down.sh
- scripts/demo-k8s.sh
- scripts/demo-k8s-stop.sh
- scripts/demo-k8s-status.sh
Enhanced Agent Workflow UI
The Streamlit interface now makes the internal agentic workflow easier to understand during technical demos.
The UI visually exposes:
- Search Planner
- Healthcare Research
- Evidence Ranking
- Grounded Answer
It also exposes:
- Generated healthcare search queries
- Retrieved source counts
- Deduplicated evidence
- Selected evidence
- Provider recommendations
- Grounded answers
- Citations
- Limitations
- Search transparency
- Google ADK event trace
Demo Screenshot
A screenshot of the enhanced healthcare agentic UI is included at:
docs/images/healthcare-agentic-demo.png
This gives GitHub visitors a quick view of the working application and agent workflow.
End-to-End Validation
The Gemini Streamlit end-to-end acceptance suite completed successfully:
5 passed
Validation included:
- Python compilation: PASS
- Ruff linting: PASS
- Streamlit E2E: PASS
- Gemini workflow: PASS
- Google ADK workflow: PASS
- GKE Pod health: PASS
- Kubernetes Deployment: PASS
- Kubernetes Service routing: PASS
- Readiness probe: PASS
- Liveness probe: PASS
- External LoadBalancer access: PASS
Notes
Google ADK currently emits some upstream experimental and deprecation warnings. These warnings are non-blocking for v1.2.0.
PubMed may occasionally return HTTP 429 responses during repeated requests. Existing retry handling allows the workflow to continue.
v1.2 Milestone
v1.2 establishes an important Google cloud-native milestone for the project:
Gemini
|
v
Google ADK
|
v
MCP Healthcare Tools
|
v
Docker
|
v
Kubernetes
|
v
Google Kubernetes Engine
The project can now demonstrate the same Gemini-powered healthcare agentic workflow locally, in containers, and on GKE.
v1.1.0 — Evaluation Benchmark
v1.1 — Evaluation Benchmark
Purpose
v1.1 adds a reproducible evaluation layer around the existing Gemini Healthcare Agentic Platform.
The objective is not to produce a generic model leaderboard. The objective is to measure whether the same healthcare agent architecture preserves its workflow contracts, evidence boundaries, citations, grounding behavior, and explicit unsupported behavior when executed through different model/runtime paths.
The benchmark therefore separates application correctness from model/runtime variability.
Architecture Under Evaluation
User Query
-> Search Planner Agent
-> Healthcare Research Agent
-> MCP retrieval
-> NPPES
-> PubMed
-> FHIR R4
-> Evidence & Answer Agent
-> structured grounded answer
The benchmark sits outside production:
Frozen v1.1 Core Acceptance Set
| Evaluation workflow | Cases | Expected behavior |
|---|---|---|
| Provider discovery | 4 | Supported |
| Biomedical research | 2 | Supported |
| Health information | 1 | Supported |
| FHIR interoperability | 2 | Supported |
| Care program discovery | 1 | Explicitly unsupported |
| Clinical trials | 1 | Explicitly unsupported |
| Total | 11 |
The two unsupported cases are part of the benchmark because explicit failure is safer than silently routing a query to an unrelated retrieval source.
Dataset Design
The benchmark runner sends only the case query into the production workflow. Expected location or specialty metadata is not injected into production state, because doing so would hide planner failures.
The original Houston pediatric-dentist scenario remains one flagship acceptance case, not application configuration.
Evaluation Metrics
Provider discovery checks:
retrieval_presence
required_source_types
citation_presence
citation_reference_integrity
claim_support
provider_evidence_authority
fhir_provider_recommendation_boundary
candidate_count
forbidden_claim_flags
Biomedical, health-information, FHIR, and unsupported workflows receive only the metrics relevant to their contracts.
Expected unsupported workflows pass only when the workflow rejects the unsupported retrieval path explicitly.
Why Deterministic Evaluation First?
v1.1 intentionally does not use an LLM-as-judge.
The baseline is designed to be reproducible, inspectable, workflow-specific, and independent from a second model's subjective scoring.
Future semantic evaluation may supplement this layer, but should not replace deterministic source, citation, grounding, and safety checks.
Preserved First-Run Results
Model Summary
| Model path | Core cases | Passed | Supported completions | Expected unsupported passed | Pass rate | Median latency | Mean latency |
|---|---|---|---|---|---|---|---|
| Gemini 3.7 Flash | 11 | 11 | 9 / 9 | 2 / 2 | 1.0000 | 10.602 s | 9.442 s |
| Gemma 4 12B + local Ollama | 11 | 10 | 8 / 9 | 2 / 2 | 0.9091 | 167.415 s | 229.241 s |
These are acceptance outcomes for the frozen v1.1 dataset, not general healthcare-AI accuracy figures.
Workflow Comparison
| Workflow | Gemini | Gemma |
|---|---|---|
| Provider discovery | 4 / 4 | 4 / 4 |
| Biomedical research | 2 / 2 | 2 / 2 |
| Health information | 1 / 1 | 1 / 1 |
| FHIR interoperability | 2 / 2 | 1 / 2 |
| Expected unsupported | 2 / 2 | 2 / 2 |
Deterministic Metric Comparison
| Metric family | Gemini | Gemma |
|---|---|---|
| Candidate count | 4 / 4 | 4 / 4 |
| Citation presence | 9 / 9 | 8 / 8 |
| Citation reference integrity | 9 / 9 | 8 / 8 |
| Claim support | 4 / 4 | 4 / 4 |
| Explicit unsupported status | 2 / 2 | 2 / 2 |
| FHIR provider-recommendation boundary | 6 / 6 | 5 / 5 |
| Forbidden provider claim flags | 4 / 4 | 4 / 4 |
| Provider evidence authority | 4 / 4 | 4 / 4 |
| Required source types | 8 / 8 | 7 / 7 |
| Retrieval presence | 9 / 9 | 8 / 8 |
The execution_success metric appears only for a failed supported execution in the current reporting contract. Gemma records 0 / 1 for its one failed FHIR execution; Gemini has no corresponding applicable failure row.
Preserved Gemma Failure
The failed case was fhir_practitioner_role.
The local model path exceeded the configured 600-second timeout:
LiteLLM -> Ollama -> Gemma
Timeout passed = 600 seconds
This was an execution failure, not a grounding, citation, provider-evidence-authority, provider-safety, or FHIR recommendation-boundary failure.
The first measured failure is intentionally preserved rather than replaced with a retry. A later retry can be saved separately as a recovery/reliability experiment.
Runtime Context
Gemini:
Model: gemini-3.7-flash
Runtime: hosted Gemini API
Gemma:
Model: gemma4:12b
Adapter: LiteLLM
Runtime: Ollama
Host: Apple M3 Pro
Memory: 36 GB
These are materially different runtime environments. Latency is therefore operational diagnostic evidence, not a controlled model-superiority benchmark.
Reproduce
Gemini:
python -m evaluation.benchmark --provider geminiGemma:
python -m evaluation.benchmark --provider gemmaComparison:
python -m evaluation.comparisonResult Artifacts
evaluation/results/gemini/
evaluation/results/gemma/
evaluation/results/comparison/
The comparison is generated from stored benchmark evidence. Do not manually rewrite measured values after the run.
Healthcare Evidence Boundaries Preserved
NPPES supports provider identity, NPI, taxonomy, and reported location. It does not establish “best” status, board certification, active licensure, good standing, clinical quality, or requested service availability.
PubMed provides general scientific context and does not establish provider-specific quality claims.
Public HAPI FHIR data is used as interoperability evidence, not provider-quality evidence, and is excluded from provider recommendation selection.
Safety Interpretation
Both model paths passed all applicable deterministic provider-discovery safety checks on completed provider cases.
This does not mean either model or the platform is clinically validated, universally safe, HIPAA compliant, PHI-safe, or suitable for autonomous medical decision-making.
Limitations
The v1.1 Core Acceptance Benchmark:
- contains only 11 cases;
- is a software acceptance benchmark, not a statistically comprehensive healthcare evaluation;
- uses live external retrieval sources whose returned records can change;
- permits model planning variability;
- compares different runtime environments;
- preserves one full first-run benchmark per model path;
- does not use an LLM-as-judge;
- does not evaluate diagnosis quality, treatment quality, patient outcomes, or clinical efficacy.
Research Extension
A paper-oriented expansion should keep this 11-case release benchmark intact and add a separate frozen research dataset with 50–100+ stratified queries, repeated runs, environment/version metadata, failure taxonomy, controlled recovery experiments, and appropriate statistical reporting.
Potential framing:
Beyond RAG: A Reproducible Evaluation Framework for Evidence-Grounded Multi-Agent Healthcare Search Using Gemini, Gemma, Google ADK, and MCP
Candidate research questions:
RQ1. How reliably does the architecture preserve evidence-grounding contracts across heterogeneous healthcare sources?
RQ2. How effectively do deterministic provider-grounding rules prevent unsupported provider claims and citation failures?
RQ3. How does the same Google ADK multi-agent architecture behave under hosted Gemini and locally controlled Gemma paths?
RQ4. How does behavior differ across provider discovery, biomedical research, health information, and FHIR interoperability?
RQ5. What operational trade-offs appear across model/runtime configuration, latency, retrieval, completeness, grounding, and safety?
The research framing should evaluate architecture behavior and reproducibility, not declare one model universally better than another.
Next Milestone
v1.2 moves the accepted application and evaluation behavior toward Kubernetes / GKE deployment while preserving the v1.1 dataset and metrics for regression checking.
v1.0.0 — Dockerized Reproducible Demo Runtime
[v1.0.0] - 2026-09-06
Dockerized Reproducible Demo Runtime
Added
- Python 3.11 slim Docker application image
- Docker Compose runtime for the Streamlit healthcare application
- Streamlit container health check
./scripts/demo-docker.sh gemini./scripts/demo-docker.sh gemma./scripts/demo-docker-stop.sh.dockerignoreprotections for.env, virtual environments, caches, logs, and test artifacts- macOS Docker-to-host Ollama connectivity through
host.docker.internal:11434 DOCKER-DEMO-README.md
Preserved
- exactly three core Google ADK agents
- MCP-backed NPPES, PubMed, and FHIR retrieval
- deterministic provider-discovery grounding
- provider-scoped citations
- existing local Gemini and Gemma demo scripts
Runtime Architecture
Gemini:
Browser -> Dockerized Streamlit -> Google ADK -> Gemini API
Gemma on macOS:
Browser -> Dockerized Streamlit -> Google ADK -> LiteLLM
-> host.docker.internal:11434 -> native Ollama -> Gemma
Acceptance
Docker + Gemini: PASS
Docker + Gemma/native Ollama: PASS
Local + Gemma/native Ollama: PASS
Docker -> host Ollama: PASS
Streamlit container health: PASS
Deterministic tests: 85 passed, 5 skipped, 1 dependency warning
The OpenTelemetry dependency deprecation warning remains non-blocking. These checks are functional acceptance, not a performance benchmark.
Boundaries
Dockerization does not make the application HIPAA compliant, PHI-safe, clinically validated, secure, private, or production-ready by itself. Existing source-authority and grounding rules remain unchanged.
v0.9.0 — Generalized Query Planning + Dynamic Retrieval + GUI
v0.9 Acceptance
Goal
Prove that the platform is no longer configured around the Houston pediatric-dentist flagship and that one Streamlit application executes the generalized workflow through Gemini and Gemma/Ollama.
Results
Deterministic regression: 85 passed, 5 skipped, 1 dependency warning
Scenario Gemini Gemma
Dallas Cardiology PASS PASS
Austin Neurology PASS PASS
Biomedical research PASS PASS
FHIR PractitionerRole PASS PASS
Houston pediatric dentistry PASS PASS
5/5 5/5
Manual Streamlit checks also passed for both configured model paths.
Evidence boundaries
NPPES may support identity, NPI, taxonomy, and reported location. It is not proof of “best” status, board certification, active/current licensure, good standing, clinical quality, or requested service availability. PubMed supplies general scientific context, not provider-specific claims. Public HAPI FHIR data validates interoperability paths, not provider quality.
Gemma/Ollama was materially slower in observed local acceptance runs; those durations are diagnostics only, not benchmarks or performance guarantees.
CARE_PROGRAM_DISCOVERY and CLINICAL_TRIALS are not claimed as implemented retrieval paths in v0.9. Multi-source “best doctor” ranking is future work.
v0.8.0 — Gemini + Gemma / Ollama
v0.8.0 — Gemini + Gemma / Ollama
v0.8 introduces model portability to the Gemini Healthcare Agentic Platform.
The same Google ADK multi-agent healthcare architecture can now run with either:
- Gemini — hosted Google model path
- Gemma — locally operated through Ollama, integrated with Google ADK through LiteLLM
The goal is not to compare which model is better. The goal is to demonstrate that an agentic healthcare architecture can change its model runtime while preserving the same agents, MCP tools, healthcare retrieval pipeline, evidence ranking, grounding rules, citations, and safety boundaries.
One Google ADK agent architecture. Two model paths: Gemini in the cloud + Gemma locally with Ollama.
What Changed in v0.8
1. Gemini + Gemma Model Portability
A new model-provider abstraction allows the Google ADK agents to select their model through configuration.
MODEL_PROVIDER
│
┌────────────┴────────────┐
│ │
▼ ▼
Gemini Gemma
Hosted Model Local Model
│ │
│ LiteLLM
│ │
│ Ollama
│ │
└────────────┬────────────┘
▼
Google ADK
│
▼
Same 3 Agents
The healthcare application logic does not need to be duplicated for each model path.
2. Same Three-Agent Architecture
v0.8 preserves the existing three-agent design:
User Question
│
▼
Search Planner Agent
│
▼
Healthcare Research Agent
│
▼
Evidence & Answer Agent
│
▼
Grounded Answer + Citations
The model runtime can change without changing the responsibilities of these agents.
Search Planner Agent creates the structured research plan and query fan-out.
Healthcare Research Agent uses MCP tools to retrieve healthcare evidence from CMS NPPES, PubMed, and FHIR.
Evidence & Answer Agent ranks and selects evidence and produces the grounded answer under the platform's evidence and safety constraints.
3. Google ADK State-Based Agent Handoffs
v0.8 improves how structured information moves between agents.
Previously, an LLM could be asked to reconstruct a large structured object before calling the next tool.
v0.8 instead uses Google ADK workflow/session state as the authoritative handoff between agents.
Search Planner Agent
│
▼
planner_output
ADK State
│
▼
Healthcare Research Agent
│
▼
research_output
ADK State
│
▼
Evidence & Answer Agent
│
▼
answer_output
This reduces unnecessary model-dependent transformations and makes the architecture more portable across Gemini and Gemma.
4. MCP Tool Layer Remains Model-Independent
The MCP architecture introduced in v0.6 remains unchanged.
Gemini / Gemma
│
▼
Google ADK Agents
│
▼
MCP Tools
│
├── NPPES
├── PubMed
└── FHIR
The selected model does not directly implement healthcare retrieval. Both model paths use the same MCP-backed healthcare evidence pipeline.
5. Deterministic Provider-Discovery Grounding
One of the most important architectural changes in v0.8 is the separation between model reasoning and safety-critical provider claims.
For provider-discovery workflows:
Models reason and choose tools; deterministic code owns high-risk provider claims.
Gemini OR Gemma
│
▼
Google ADK Agents
│
▼
MCP Retrieval
│
▼
Evidence Ranking
│
▼
Deterministic Provider Grounding
│
▼
Citations + Limitations
Provider recommendations are assembled from selected evidence rather than allowing the final model to invent or expand provider-specific claims.
The existing rule remains:
No evidence → no claim.
6. Healthcare Evidence Boundaries Preserved
The platform continues to enforce source-specific evidence boundaries.
NPPES
Used for evidence such as:
- provider identity
- NPI
- taxonomy
- registry-reported location
NPPES is not treated as independent evidence of provider quality, board certification, current licensure, anxiety-specific services, sedation availability, or suitability.
PubMed
Used for general scientific and biomedical context.
PubMed research does not establish that an individual provider offers a particular service or has a particular quality.
FHIR
FHIR remains an interoperability and structured healthcare resource layer.
The public HAPI FHIR R4 endpoint used by the project is test/demo infrastructure and is not treated as authoritative real-world provider evidence.
7. Provider-Scoped Citations
Provider recommendation reasons remain tied to evidence for that specific provider.
Provider Candidate 1 → C1
Provider Candidate 2 → C2
Provider Candidate 3 → C3
Scientific Context → C4, C5
General PubMed evidence cannot be transformed into unsupported claims about an individual provider.
8. Model Configuration
The runtime can be selected through .env.
Gemini
MODEL_PROVIDER=gemini
GEMINI_API_KEY=YOUR_API_KEY
GEMINI_MODEL=YOUR_GEMINI_MODELGemma + Ollama
MODEL_PROVIDER=gemma
OLLAMA_BASE_URL=http://localhost:11434
GEMMA_MODEL=YOUR_GEMMA_MODELThe model factory selects the appropriate Google ADK model configuration.
9. Model-Aware Synthesis Layer
v0.8 introduces a synthesis abstraction for workflows that require configured model-based answer synthesis.
llm/
├── model_factory.py
└── synthesis/
├── base.py
├── factory.py
├── gemini.py
└── gemma.py
This prevents the architecture from silently routing a Gemma workflow back through Gemini for model synthesis.
Provider discovery uses the deterministic grounding path described above.
v0.8 Acceptance Validation
The flagship provider-discovery workflow was exercised through both model paths.
Gemini Path
Gemini
↓
Google ADK
↓
3 Agents
↓
MCP
↓
NPPES + PubMed + FHIR
↓
Evidence Ranking
↓
Deterministic Grounding
Observed diagnostic run:
- Search queries generated: 7
- Retrieved evidence: 19
- Deduplicated evidence: 19
- NPPES/provider results: 10
- PubMed results: 6
- FHIR results: 3
- Selected evidence: 5
Gemma + Ollama Path
Gemma
↓
Ollama
↓
LiteLLM
↓
Google ADK
↓
Same 3 Agents
↓
Same MCP + Retrieval + Grounding Pipeline
The flagship workflow also completed with Gemini credentials unavailable, demonstrating that this path was not silently falling back to Gemini.
Observed diagnostic run:
- Search queries generated: 7
- Retrieved evidence: 19
- Deduplicated evidence: 19
- NPPES/provider results: 10
- PubMed results: 6
- FHIR results: 3
- Selected evidence: 5
These are observed diagnostic results, not performance benchmarks or guaranteed retrieval counts.
Formal model benchmarking remains planned for v1.0.
Regression Validation
Final v0.8 regression:
53 passed, 1 warning
Additional validation:
ruff check . PASS
pytest -q PASS
git diff --check PASS
The remaining OpenTelemetry SelectableGroups deprecation warning is non-blocking and is not claimed as fixed in this release.
New Documentation
v0.8 adds:
docs/model-portability.mdexamples/v0.8-acceptance.md
The model portability documentation explains Gemini hosted execution, Gemma local execution, Ollama and LiteLLM responsibilities, Google ADK state handoffs, deterministic provider grounding, safety boundaries, acceptance scope, and current limitations.
Important Scope
v0.8 validates functional model portability for the flagship provider-discovery workflow.
It does not claim:
- Gemini and Gemma have identical runtime characteristics
- one model is better than the other
- all application intents have been benchmarked across both models
- local Gemma/Ollama deployment is automatically HIPAA-compliant
- local execution is automatically private or secure
- public FHIR test data represents authoritative provider information
Broader evaluation and benchmarking remain future work.
Why This Matters
Model portability in an agentic system is more than changing a model name.
A portable architecture must minimize unnecessary model-dependent transformations and keep retrieval, evidence handling, citations, safety constraints, and application logic stable across model runtimes.
v0.8 demonstrates this pattern using:
Gemini + Gemma + Google ADK + MCP
with Ollama and LiteLLM providing the supporting local-model runtime path.
Roadmap
v0.1 Gemini + Query Fan-Out
v0.2 Real Healthcare Retrieval
v0.3 Evidence Ranking
v0.4 Grounded Answers + Citations
v0.5 Google ADK Multi-Agent Architecture
v0.6 MCP Tool Layer
v0.7 FHIR Healthcare Interoperability
v0.8 Gemini + Gemma / Ollama ← CURRENT
v0.9 Docker
v1.0 Evaluation Benchmark
v1.1 Kubernetes / GKE
v1.2 OpenTelemetry
v1.3 Security
v2.0 Framework
Next: v0.9 — Docker
The next milestone will focus on packaging the platform into reproducible containerized runtime environments while preserving the same agent, MCP, retrieval, model portability, grounding, and safety architecture.
v0.7.0 - FHIR Healthcare Interoperability
v0.7.0 — FHIR Healthcare Interoperability
v0.7 adds FHIR R4 interoperability to the Gemini Healthcare Agentic Platform while preserving the existing three-agent architecture.
Highlights
- Added FHIR R4 connector support
- Added FHIR MCP server and async MCP client
- Added support for:
- Practitioner
- PractitionerRole
- Organization
- Location
- HealthcareService
- Added explicit FHIR/interoperability routing
- Added PractitionerRole specialty lookup with a safe development fallback
- Added shared FHIR normalization into
SearchResult - Added FHIR evidence scoring and provider-grounding safeguards
- Added defensive Google ADK Research Agent handoff normalization
- Added FHIR architecture, integration, and acceptance documentation
Evidence Model
The platform keeps evidence roles separate:
- NPPES — provider registry evidence
- PubMed — general biomedical evidence
- FHIR — healthcare interoperability evidence
Public HAPI FHIR test records are intentionally not treated as authoritative provider recommendation evidence.
Acceptance Validation
One successful end-to-end v0.7 acceptance run observed:
- 7 generated queries
- 19 retrieved sources
- 19 deduplicated sources
- 10 NPPES results
- 6 PubMed results
- 3 FHIR results
- 5 selected evidence records
- 3 NPPES
- 2 PubMed
- 0 FHIR
These are observed acceptance-run values, not benchmark guarantees.
Validation
- Ruff: all checks passed
- Pytest: 45 passed
- One non-blocking OpenTelemetry dependency deprecation warning remains
Core Principle
No evidence → no claim.
See:
README.mdCHANGELOG.mddocs/architecture.mddocs/fhir-integration.mdexamples/v0.7-acceptance.md
Next milestone: v0.8 — Gemini + Gemma / Ollama model portability.
v0.6.0 - MCP Tool Layer
v0.6.0 — MCP Tool Layer
v0.6 introduces the Model Context Protocol (MCP) as the standardized tool-access layer for healthcare retrieval in the Gemini Healthcare Agentic Platform.
The release preserves the existing healthcare connectors while exposing their capabilities through MCP servers that can be invoked by the Google ADK multi-agent workflow.
What Changed
Before v0.6:
Healthcare Research Agent
|
+--> direct Python --> NPPESProviderClient --> CMS NPPES
|
+--> direct Python --> PubMedClient --------> PubMed
After v0.6:
Healthcare Research Agent
|
v
MCPHealthcareRetrievalOrchestrator
|
+--> MCPProviderClient
| |
| v
| Search MCP Server
| |
| v
| find_healthcare_providers()
| |
| v
| NPPESProviderClient
| |
| v
| CMS NPPES
|
+--> MCPPubMedClient
|
v
Research MCP Server
|
v
search_biomedical_literature()
|
v
PubMedClient
|
v
PubMed
v0.6 does not replace the healthcare connectors. It exposes the existing tested capabilities as standardized MCP tools that agents can discover and invoke.
MCP Tools
Provider search:
find_healthcare_providers
Backed by:
NPPESProviderClient --> CMS NPPES
Biomedical research:
search_biomedical_literature
Backed by:
PubMedClient --> PubMed
Async Google ADK Integration
Google ADK executes tools inside an asyncio event loop, so v0.6 introduces an async-first MCP execution path:
Google ADK
|
v
async retrieve_healthcare_evidence()
|
v
await MCPHealthcareRetrievalOrchestrator.retrieve()
|
+--> await MCPProviderClient.search()
|
+--> await MCPPubMedClient.search()
The original synchronous retrieval orchestrator remains available for compatibility with earlier versions.
Existing Grounding Pipeline Preserved
MCP changes the tool boundary, not the evidence-grounding architecture.
MCP Retrieval
|
v
SearchResult[]
|
v
Evidence Scoring
|
v
Evidence Ranking
|
v
Deterministic Citations
|
v
Grounded Answer
The core rule remains:
No evidence → no claim.
Flagship Acceptance Run
Example query:
Find three pediatric dentists in Houston for a child who is scared of
going to the dentist. Compare them using trustworthy sources, provider
credentials, services, and location, and explain why you selected each one.
One successful v0.6 acceptance run produced:
6 generated queries
16 unique retrieved sources
5 selected evidence sources
3 provider candidates
C1-C5 deterministic citations
explicit evidence limitations
These values describe one acceptance run and are not fixed system guarantees.
Testing
v0.6 adds regression coverage for:
- Search MCP wrapper
- Research MCP wrapper
- async MCP provider client
- async MCP PubMed client
- MCP retrieval orchestration
- provider/research routing
Release checkpoint:
25 passed
Key Files
mcp_services/search_server/server.py
mcp_services/search_server/tools.py
mcp_services/research_server/server.py
mcp_services/research_server/tools.py
mcp_services/clients/healthcare.py
search/mcp_retrieval.py
agents/healthcare_research/tools.py
tests/unit/test_mcp_search.py
tests/unit/test_mcp_research.py
tests/unit/test_mcp_clients.py
tests/unit/test_mcp_retrieval.py
Documentation
See:
docs/mcp-architecture.md
for the full MCP architecture, async design, component mapping, evidence boundaries, and extension model.
Next
v0.7 will extend the healthcare connector layer with FHIR-oriented capabilities while preserving the same three-agent architecture.
v0.5.0 — Google ADK Multi-Agent Architecture
v0.5.0 — Google ADK Multi-Agent Architecture
v0.5 introduces a three-agent healthcare evidence workflow built with the Google Agent Development Kit (ADK).
This release keeps the validated retrieval, evidence ranking, grounding, and citation pipeline from earlier versions while adding explicit agent-to-agent orchestration.
Architecture
USER QUESTION
│
▼
Search Planner Agent
│
│ 6 generated queries
▼
Healthcare Research Agent
│
├── CMS NPPES ──► 10 provider records
│
└── PubMed ─────► 6 scientific articles
│
▼
16 UNIQUE SOURCES
│
▼
Evidence Ranking + Selection
│
├── C1 Provider
├── C2 Provider
├── C3 Provider
├── C4 PubMed
└── C5 PubMed
│
▼
Evidence & Answer Agent
│
├── 3 provider candidates
├── scientific context
├── deterministic citations
├── limitations
└── transparency
│
▼
GROUNDED ANSWER
The counts above are from the v0.5 acceptance run. They are example runtime results and may vary with the query and live source data.
What's New in v0.5
1. Search Planner Agent
The Search Planner Agent converts the user's healthcare question into a structured search plan.
It uses Gemini-powered query fan-out to generate focused searches for:
- local provider discovery
- anxiety/fear-related provider discovery
- professional-directory verification
- state-license verification
- PubMed behavior-guidance evidence
- PubMed sedation and nitrous-oxide evidence
Implementation:
agents/search_planner/agent.py
│
▼
agents/search_planner/tools.py
│
▼
search/query_fanout.py
│
▼
Gemini
2. Healthcare Research Agent
The Healthcare Research Agent receives the structured search plan and retrieves evidence from real healthcare data sources.
Healthcare Research Agent
│
├── CMS NPPES
│ ├── provider identity
│ ├── NPI
│ ├── reported location
│ └── specialty taxonomy
│
└── PubMed
├── biomedical literature
├── systematic reviews
└── clinical evidence
Implementation:
agents/healthcare_research/agent.py
│
▼
agents/healthcare_research/tools.py
│
▼
search/retrieval.py
│
├── connectors/provider_search/client.py
│ └── CMS NPPES
│
└── connectors/pubmed/client.py
└── PubMed
3. Evidence & Answer Agent
The Evidence & Answer Agent takes the retrieved evidence and reuses the validated v0.3/v0.4 ranking, citation, and grounding pipeline.
Retrieved Evidence
│
▼
Evidence Scoring
│
▼
Evidence Ranking
│
▼
Diverse Evidence Selection
│
├── Provider Evidence
└── Scientific Evidence
│
▼
Deterministic Citations
│
▼
Grounded Answer Validation
│
▼
Final Grounded Answer
Implementation:
agents/evidence_answer/agent.py
│
▼
agents/evidence_answer/tools.py
│
├── grounding/scoring.py
├── grounding/ranking.py
├── grounding/citations.py
└── grounding/answering.py
Google ADK Workflow
The three specialist agents are orchestrated using an ADK SequentialAgent.
agents/agent.py
│
▼
SequentialAgent
│
├── Search Planner Agent
│
├── Healthcare Research Agent
│
└── Evidence & Answer Agent
The workflow deliberately keeps the ADK layer thin.
Instead of rewriting the capabilities developed in v0.1–v0.4, each ADK agent wraps and reuses the existing tested implementation.
Structured Agent-to-Agent Handoffs
v0.5 also changes how state moves between agents.
The workflow passes structured Python/JSON-compatible objects rather than embedding serialized JSON strings inside another JSON response.
planner_output
├── user_query
└── search_plan
│
▼
research_output
├── user_query
├── search_plan
├── search_results
├── retrieved_sources
└── deduplicated_sources
│
▼
answer_output
├── grounded_answer
└── selected_evidence_count
The shared ADK contracts are defined in:
agents/adk/models.py
This design avoids nested JSON escaping problems and makes agent handoffs easier to validate.
End-to-End Code Flow
USER QUERY
│
▼
agents/search_planner/agent.py
│
├── agents/search_planner/tools.py
├── search/query_fanout.py
├── llm/gemini/client.py
└── models/query.py
│
▼
planner_output
│
├── user_query
└── search_plan
│
▼
agents/healthcare_research/agent.py
│
├── agents/healthcare_research/tools.py
├── search/retrieval.py
├── connectors/provider_search/client.py
└── connectors/pubmed/client.py
│
▼
research_output
│
├── user_query
├── search_plan
├── search_results
├── retrieved_sources
└── deduplicated_sources
│
▼
agents/evidence_answer/agent.py
│
├── agents/evidence_answer/tools.py
├── grounding/scoring.py
├── grounding/ranking.py
├── grounding/citations.py
└── grounding/answering.py
│
▼
GroundedAnswer
Grounding and Safety Boundaries
The multi-agent architecture preserves the grounding rules introduced in earlier releases.
- No evidence → no claim.
- Recommended providers must exist in selected provider evidence.
- Citations are constructed deterministically.
- NPPES supports provider identity, NPI, reported location, and taxonomy.
- NPPES does not establish clinical quality or patient satisfaction.
- NPPES information does not independently establish current active license standing.
- Provider-specific services such as nitrous oxide or sedation are not inferred from specialty taxonomy.
- PubMed evidence provides general scientific context rather than evidence about a specific provider.
- Unsupported credentials and services are not invented.
v0.5 Acceptance Run
The flagship test question was:
Find three pediatric dentists in Houston for a child who is scared of going to the dentist. Compare them using trustworthy sources, provider credentials, services, and location, and explain why you selected each one.
The successful end-to-end ADK run produced:
Generated queries 6
Healthcare retrieval:
├── NPPES providers 10
└── PubMed articles 6
Unique evidence 16
Selected evidence:
├── Provider sources 3
└── PubMed sources 2
Total selected 5
Final provider candidates 3
The final response maintained the distinction between provider registry evidence and general biomedical evidence.
It also explicitly reported that provider-specific anxiety-management services, sedation availability, clinical quality, and current state-license standing had not been independently verified.
Validation
Before release:
Ruff
└── PASS
Pytest
└── 20 / 20 PASS
Live Google ADK workflow
└── PASS
Structured agent handoff
└── PASS
NPPES + PubMed retrieval
└── PASS
Grounded citations
└── PASS
Version Progress
v0.1 Gemini Query Planning + Query Fan-Out
│
▼
v0.2 Real Healthcare Retrieval
PubMed + CMS NPPES
│
▼
v0.3 Evidence Ranking + Diverse Selection
│
▼
v0.4 Grounded Answers + Validated Citations
│
▼
v0.5 Google ADK Multi-Agent Architecture
What's Next
v0.6 MCP Tool Layer
v0.7 FHIR + Healthcare Connectors
v0.8 Gemini vs Gemma / Ollama
v0.9 Docker
v1.0 Evaluation Benchmark
v1.1 Kubernetes / GKE
v1.2 OpenTelemetry
v1.3 Security Testing
v0.5 establishes the multi-agent orchestration layer needed for the next stage: exposing healthcare search and retrieval capabilities as standardized MCP tools.
v0.4.0 — Grounded Answers & Validated Citations
v0.4.0 — Grounded Answers & Validated Citations
v0.4.0 introduces the grounding layer for the Beyond RAG: Gemini-Powered Agentic Healthcare Platform.
The system can now transform ranked healthcare evidence into a structured, evidence-grounded answer while keeping provider recommendations, factual claims, and citations tied to selected evidence.
The core principle of this release is:
No evidence → no claim
What's New
- Gemini-powered grounded answer synthesis
- Deterministic citation generation from selected evidence
- Structured
GroundedAnsweroutput - Provider recommendation allow-list validation
- Grouped citation support such as
[C1, C2, C3] - Invalid citation detection
- Evidence-aware provider recommendations
- Deterministic provider name and location
- Evidence-derived recommendation confidence score
- Semantic deduplication of limitations
- Explicit provider and scientific evidence boundaries
- License-status language safeguards
- Search transparency metrics
- Additional grounding and citation unit tests
Current Architecture
USER QUESTION
|
v
+--------------------+
| Gemini Planner |
| Search / Fan-Out |
+---------+----------+
|
v
+--------------------+
| Search Plan |
| Multiple Queries |
+---------+----------+
|
v
+-----------------------------+
| Multi-Source Healthcare |
| Retrieval |
+--------------+--------------+
|
+-----------------+-----------------+
| |
v v
+------------------+ +------------------+
| CMS NPPES | | PubMed |
| Provider Records | | Research Evidence|
+---------+--------+ +---------+--------+
| |
+-----------------+-----------------+
|
v
+----------------------+
| Evidence Pool |
| + Deduplication |
+----------+-----------+
|
v
+----------------------+
| Evidence Ranking |
|Relevance / Authority |
|Freshness / Specificity|
+----------+-----------+
|
v
+----------------------+
| Diverse Selection |
|3 Provider + 2 PubMed |
+----------+-----------+
|
v
+----------------------+
| Deterministic |
| Citations C1...C5 |
+----------+-----------+
|
v
+----------------------+
| Restricted Evidence |
| Context |
+----------+-----------+
|
v
+----------------------+
| Gemini Grounded |
| Synthesis |
+----------+-----------+
|
v
+--------------------------------+
| Validation Layer |
+----------+----------+----------+
| |
+---------+ +---------+
| |
v v
+-------------+ +-------------+
| Provider | | Citation |
| Allow-List | | Validation |
+------+------+ +------+------+
| |
+--------------+---------------+
|
v
+----------------------+
| GroundedAnswer |
+----------+-----------+
|
+--------------------+--------------------+
| | |
v v v
+-------------+ +-------------+ +-------------+
| Provider | | Citations | | Limitations |
| Options | | C1...C5 | | + Evidence |
+-------------+ +-------------+ | Transparency|
+-------------+
Grounding Principle
The central rule introduced in v0.4 is:
No evidence → no claim
Gemini does not receive unrestricted retrieval results.
Only selected evidence is placed into the grounding context used for final answer synthesis.
Provider names, locations, citation URLs, citation IDs, and recommendation confidence scores are derived from retrieved evidence rather than freely generated by the language model.
Deterministic Citations
Citations are created before grounded answer synthesis and mapped directly to selected evidence.
For example:
Selected Evidence #1 -> C1
Selected Evidence #2 -> C2
Selected Evidence #3 -> C3
Selected Evidence #4 -> C4
Selected Evidence #5 -> C5
The model may reference only these citation IDs.
Supported citation forms include:
[C1]
[C1, C2]
[C1, C2, C3]
Grouped citation references are validated individually.
For example:
[C1, C99]
is rejected when C99 does not correspond to selected evidence.
This prevents a valid citation from hiding an invalid or hallucinated citation inside a citation group.
Provider Recommendation Validation
Gemini cannot introduce arbitrary providers into the final recommendation list.
The grounding layer creates an allow-list from selected provider evidence:
Selected NPPES Evidence
|
v
Provider Allow-List
|
v
Gemini Recommendation
|
v
Validate Name
/ \
valid invalid
| |
v v
keep reject
If Gemini attempts to recommend a provider that was not present in the selected provider evidence, answer generation fails validation.
Duplicate provider recommendations are also removed.
If Gemini returns fewer than three provider recommendations, the system can safely backfill from already-selected provider evidence.
Provider Evidence Boundaries
CMS NPPES / NPI Registry data can support claims such as:
- Provider identity
- NPI
- Reported practice location
- Provider type
- Specialty/taxonomy
- Reported license information
NPPES alone does not establish:
- Clinical quality
- Patient satisfaction
- Board certification
- Active license standing
- Disciplinary history
- Anxiety-management capabilities
- Nitrous oxide availability
- Sedation services
- Whether a provider is the "best"
For this reason, v0.4 intentionally keeps:
credentials = []
services = []
unless appropriate provider-specific evidence exists.
An NPI is treated as an identifier, not a professional credential.
If NPPES contains a license number, the answer may describe it as:
NPPES-reported license number
or:
reported license information in NPPES
The system does not infer that the license is active, valid, verified, current, or in good standing.
Scientific Evidence Boundaries
PubMed provides supporting scientific and biomedical context.
For example, PubMed evidence may describe research involving:
- Pediatric dental anxiety
- Behavior-guidance techniques
- Non-pharmacological interventions
- Technology-enhanced distraction
- Pediatric dental sedation
- Sedation safety
However:
Scientific evidence
!=
Provider-specific evidence
A PubMed article discussing pediatric dental sedation does not establish that a particular Houston dentist offers sedation.
Similarly, research about anxiety-management techniques does not establish that a particular practice uses those techniques.
The final answer explicitly exposes this distinction.
Evidence Diversity
Provider discovery requires more than simply returning the highest-scoring records.
The current ranking strategy intentionally creates a diverse evidence set.
For the flagship provider-discovery workflow:
+-----------------------+
| Selected Evidence |
+-----------+-----------+
|
+-------+-------+
| |
v v
3 Provider 2 Scientific
Records Sources
| |
+-------+-------+
|
v
Grounded ...
v0.3.0 — Evidence Ranking & Diverse Evidence Selection
Beyond RAG — v0.3.0
This release introduces explainable evidence ranking and evidence-diverse selection for the Gemini Healthcare Agentic Platform.
The platform can now move beyond retrieval and determine which evidence should be prioritized for downstream grounding.
What's New
- Added deterministic evidence scoring
- Added relevance scoring
- Added source-authority scoring
- Added freshness scoring
- Added specificity scoring
- Added confidence scoring
- Added weighted evidence ranking
- Added evidence-aware Gemini query planning
- Added scientific-evidence query generation
- Added improved PubMed query routing
- Added query-leakage protection in relevance scoring
- Added provider/scientific evidence diversity
- Added 3-provider + 2-supporting-evidence selection policy
- Added selection backfilling when a source category has insufficient evidence
- Added PubMed throttling and retry handling
- Added tests for evidence diversity and ranking behavior
Architecture
User Question
│
▼
Gemini Planner
│
▼
SearchPlan
│
┌─────────┴─────────┐
│ │
▼ ▼
Provider Queries Scientific Queries
│ │
▼ ▼
NPPES PubMed
│ │
└─────────┬─────────┘
▼
Evidence Pool
│
▼
Evidence Scoring
┌────────────┼────────────┐
│ │ │
▼ ▼ ▼
Relevance Authority Freshness
│ │ │
└──────┬─────┴─────┬──────┘
▼ ▼
Specificity Confidence
│ │
└─────┬─────┘
▼
Weighted Ranking
│
▼
Evidence-Diverse Selection
┌────┴────┐
│ │
▼ ▼
3 Providers 2 Scientific
Evidence Items
Evidence Ranking
The v0.3 deterministic baseline uses:
- 35% relevance
- 30% authority
- 15% specificity
- 10% freshness
- 10% confidence
These weights are intentionally transparent baseline values and are not presented as universally optimal.
Future benchmark work can compare this approach with embedding-based, Gemini-assisted, and agentic reranking.
Query-Leakage Protection
Evidence relevance is calculated from the retrieved document itself.
The search query that retrieved the document is intentionally excluded from relevance scoring so unrelated documents cannot appear relevant merely because the retrieval query contained matching keywords.
Evidence Diversity
For provider-discovery workflows, top_k=5 currently reserves approximately:
- 3 provider evidence items
- 2 supporting scientific evidence items
If one category has insufficient evidence, remaining slots are filled using the strongest available evidence.
This prevents large provider-result sets from crowding scientific evidence out of the grounding context.
Flagship Demo
Current reference query:
Find three pediatric dentists in Houston for a child who is anxious about dental visits. Compare them using trustworthy sources, provider credentials, services, and location, and explain why you selected each one.
The current system retrieves provider candidates from NPPES and scientific evidence from PubMed.
Provider ranking at this stage should not be interpreted as a claim that the selected providers are the "best." Additional provider-specific evidence and grounded synthesis are introduced in later releases.
Milestone
The platform now supports:
Question → Query Planning → Multi-Source Retrieval → Deduplication → Evidence Scoring → Ranking → Diverse Evidence Selection
Next — v0.4.0
Grounded Answers + Citations
Planned capabilities:
- evidence-to-claim mapping
- grounded answer generation
- citation generation
- citation validation
- provider recommendation structure
- transparent explanation of why evidence was selected
- limitations and unsupported-claim handling