Skip to content

Commit 1f833fb

Browse files
Yuan325Quarz0
Yuan325
and
Quarz0
authored
feat(healthcare): add support for healthcare source, tool and prebuilt config (googleapis#1853)
## Description Add support for healthcare source, tool and prebuilt config. This branch consist of all previously approved PRs. 🛠️ Fixes googleapis#1648 --------- Co-authored-by: Marwan Tammam <15021613+Quarz0@users.noreply.github.com>
1 parent 22c0b46 commit 1f833fb

57 files changed

Lines changed: 8205 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.ci/integration.cloudbuild.yaml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -214,6 +214,29 @@ steps:
214214
dataform \
215215
dataform
216216
217+
- id: "cloud-healthcare"
218+
name: golang:1
219+
waitFor: ["compile-test-binary"]
220+
entrypoint: /bin/bash
221+
env:
222+
- "GOPATH=/gopath"
223+
- "HEALTHCARE_PROJECT=$PROJECT_ID"
224+
- "SERVICE_ACCOUNT_EMAIL=$SERVICE_ACCOUNT_EMAIL"
225+
- "HEALTHCARE_REGION=$_REGION"
226+
- "HEALTHCARE_DATASET=$_HEALTHCARE_DATASET"
227+
- "HEALTHCARE_PREPOPULATED_DICOM_STORE=$_HEALTHCARE_PREPOPULATED_DICOM_STORE"
228+
secretEnv: ["CLIENT_ID"]
229+
volumes:
230+
- name: "go"
231+
path: "/gopath"
232+
args:
233+
- -c
234+
- |
235+
.ci/test_with_coverage.sh \
236+
"Cloud Healthcare API" \
237+
cloudhealthcare \
238+
cloudhealthcare
239+
217240
- id: "postgres"
218241
name: golang:1
219242
waitFor: ["compile-test-binary"]
@@ -937,6 +960,8 @@ substitutions:
937960
_ALLOYDB_AI_NL_CLUSTER: "alloydb-ai-nl-testing"
938961
_ALLOYDB_AI_NL_INSTANCE: "alloydb-ai-nl-testing-instance"
939962
_BIGTABLE_INSTANCE: "bigtable-testing-instance"
963+
_HEALTHCARE_DATASET: "test-dataset"
964+
_HEALTHCARE_PREPOPULATED_DICOM_STORE: "prepopulated-test-dicom-store"
940965
_POSTGRES_HOST: 127.0.0.1
941966
_POSTGRES_PORT: "5432"
942967
_SPANNER_INSTANCE: "spanner-testing"

‎cmd/root.go‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,21 @@ import (
6969
_ "github.com/googleapis/genai-toolbox/internal/tools/clickhouse/clickhouselistdatabases"
7070
_ "github.com/googleapis/genai-toolbox/internal/tools/clickhouse/clickhouselisttables"
7171
_ "github.com/googleapis/genai-toolbox/internal/tools/clickhouse/clickhousesql"
72+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcarefhirfetchpage"
73+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcarefhirpatienteverything"
74+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcarefhirpatientsearch"
75+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaregetdataset"
76+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaregetdicomstore"
77+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaregetdicomstoremetrics"
78+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaregetfhirresource"
79+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaregetfhirstore"
80+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaregetfhirstoremetrics"
81+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcarelistdicomstores"
82+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcarelistfhirstores"
83+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcareretrieverendereddicominstance"
84+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaresearchdicominstances"
85+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaresearchdicomseries"
86+
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudhealthcare/cloudhealthcaresearchdicomstudies"
7287
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudmonitoring"
7388
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudsql/cloudsqlcreatedatabase"
7489
_ "github.com/googleapis/genai-toolbox/internal/tools/cloudsql/cloudsqlcreateusers"
@@ -192,6 +207,7 @@ import (
192207
_ "github.com/googleapis/genai-toolbox/internal/sources/bigtable"
193208
_ "github.com/googleapis/genai-toolbox/internal/sources/cassandra"
194209
_ "github.com/googleapis/genai-toolbox/internal/sources/clickhouse"
210+
_ "github.com/googleapis/genai-toolbox/internal/sources/cloudhealthcare"
195211
_ "github.com/googleapis/genai-toolbox/internal/sources/cloudmonitoring"
196212
_ "github.com/googleapis/genai-toolbox/internal/sources/cloudsqladmin"
197213
_ "github.com/googleapis/genai-toolbox/internal/sources/cloudsqlmssql"

‎cmd/root_test.go‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1256,6 +1256,7 @@ func TestPrebuiltTools(t *testing.T) {
12561256
cloudsqlmysqlobsvconfig, _ := prebuiltconfigs.Get("cloud-sql-mysql-observability")
12571257
cloudsqlmssqlobsvconfig, _ := prebuiltconfigs.Get("cloud-sql-mssql-observability")
12581258
serverless_spark_config, _ := prebuiltconfigs.Get("serverless-spark")
1259+
cloudhealthcare_config, _ := prebuiltconfigs.Get("cloud-healthcare")
12591260

12601261
// Set environment variables
12611262
t.Setenv("API_KEY", "your_api_key")
@@ -1349,6 +1350,10 @@ func TestPrebuiltTools(t *testing.T) {
13491350
t.Setenv("NEO4J_USERNAME", "your_neo4j_user")
13501351
t.Setenv("NEO4J_PASSWORD", "your_neo4j_password")
13511352

1353+
t.Setenv("CLOUD_HEALTHCARE_PROJECT", "your_gcp_project_id")
1354+
t.Setenv("CLOUD_HEALTHCARE_REGION", "your_gcp_region")
1355+
t.Setenv("CLOUD_HEALTHCARE_DATASET", "your_healthcare_dataset")
1356+
13521357
ctx, err := testutils.ContextWithNewLogger()
13531358
if err != nil {
13541359
t.Fatalf("unexpected error: %s", err)
@@ -1628,6 +1633,24 @@ func TestPrebuiltTools(t *testing.T) {
16281633
},
16291634
},
16301635
},
1636+
{
1637+
name: "cloud healthcare prebuilt tools",
1638+
in: cloudhealthcare_config,
1639+
wantToolset: server.ToolsetConfigs{
1640+
"cloud_healthcare_dataset_tools": tools.ToolsetConfig{
1641+
Name: "cloud_healthcare_dataset_tools",
1642+
ToolNames: []string{"get_dataset", "list_dicom_stores", "list_fhir_stores"},
1643+
},
1644+
"cloud_healthcare_fhir_tools": tools.ToolsetConfig{
1645+
Name: "cloud_healthcare_fhir_tools",
1646+
ToolNames: []string{"get_fhir_store", "get_fhir_store_metrics", "get_fhir_resource", "fhir_patient_search", "fhir_patient_everything", "fhir_fetch_page"},
1647+
},
1648+
"cloud_healthcare_dicom_tools": tools.ToolsetConfig{
1649+
Name: "cloud_healthcare_dicom_tools",
1650+
ToolNames: []string{"get_dicom_store", "get_dicom_store_metrics", "search_dicom_studies", "search_dicom_series", "search_dicom_instances", "retrieve_rendered_dicom_instance"},
1651+
},
1652+
},
1653+
},
16311654
}
16321655

16331656
for _, tc := range tcs {

‎docs/en/reference/prebuilt-tools.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -590,3 +590,33 @@ details on how to connect your AI tools (IDEs) to databases via Toolbox and MCP.
590590
* **Tools:**
591591
* `execute_cypher`: Executes a Cypher query.
592592
* `get_schema`: Retrieves the schema of the Neo4j database.
593+
594+
## Google Cloud Healthcare API
595+
* `--prebuilt` value: `cloud-healthcare`
596+
* **Environment Variables:**
597+
* `CLOUD_HEALTHCARE_PROJECT`: The GCP project ID.
598+
* `CLOUD_HEALTHCARE_REGION`: The Cloud Healthcare API dataset region.
599+
* `CLOUD_HEALTHCARE_DATASET`: The Cloud Healthcare API dataset ID.
600+
* `CLOUD_HEALTHCARE_USE_CLIENT_OAUTH`: (Optional) If `true`, forwards the client's
601+
OAuth access token for authentication. Defaults to `false`.
602+
* **Permissions:**
603+
* **Healthcare FHIR Resource Reader** (`roles/healthcare.fhirResourceReader`) to read an
604+
search FHIR resources.
605+
* **Healthcare DICOM Viewer** (`roles/healthcare.dicomViewer`) to retrieve DICOM images from a
606+
DICOM store.
607+
* **Tools:**
608+
* `get_dataset`: Gets information about a Cloud Healthcare API dataset.
609+
* `list_dicom_stores`: Lists DICOM stores in a Cloud Healthcare API dataset.
610+
* `list_fhir_stores`: Lists FHIR stores in a Cloud Healthcare API dataset.
611+
* `get_fhir_store`: Gets information about a FHIR store.
612+
* `get_fhir_store_metrics`: Gets metrics for a FHIR store.
613+
* `get_fhir_resource`: Gets a FHIR resource from a FHIR store.
614+
* `fhir_patient_search`: Searches for patient resource(s) based on a set of criteria.
615+
* `fhir_patient_everything`: Retrieves resources related to a given patient.
616+
* `fhir_fetch_page`: Fetches a page of FHIR resources.
617+
* `get_dicom_store`: Gets information about a DICOM store.
618+
* `get_dicom_store_metrics`: Gets metrics for a DICOM store.
619+
* `search_dicom_studies`: Searches for DICOM studies.
620+
* `search_dicom_series`: Searches for DICOM series.
621+
* `search_dicom_instances`: Searches for DICOM instances.
622+
* `retrieve_rendered_dicom_instance`: Retrieves a rendered DICOM instance.

‎docs/en/resources/sources/cloud-healthcare.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
title: "Cloud Healthcare API"
3+
linkTitle: "Cloud Healthcare"
4+
type: docs
5+
weight: 1
6+
description: >
7+
The Cloud Healthcare API provides a managed solution for storing and
8+
accessing healthcare data in Google Cloud, providing a critical bridge
9+
between existing care systems and applications hosted on Google Cloud.
10+
---
11+
12+
## About
13+
14+
The [Cloud Healthcare API][healthcare-docs] provides a managed solution
15+
for storing and accessing healthcare data in Google Cloud, providing a
16+
critical bridge between existing care systems and applications hosted on
17+
Google Cloud. It supports healthcare data standards such as HL7® FHIR®,
18+
HL7® v2, and DICOM®. It provides a fully managed, highly scalable,
19+
enterprise-grade development environment for building clinical and analytics
20+
solutions securely on Google Cloud.
21+
22+
A dataset is a container in your Google Cloud project that holds modality-specific
23+
healthcare data. Datasets contain other data stores, such as FHIR stores and DICOM
24+
stores, which in turn hold their own types of healthcare data.
25+
26+
A single dataset can contain one or many data stores, and those stores can all service
27+
the same modality or different modalities as application needs dictate. Using multiple
28+
stores in the same dataset might be appropriate in various situations.
29+
30+
If you are new to the Cloud Healthcare API, you can try to
31+
[create and view datasets and stores using curl][healthcare-quickstart-curl].
32+
33+
[healthcare-docs]: https://cloud.google.com/healthcare/docs
34+
[healthcare-quickstart-curl]:
35+
https://cloud.google.com/healthcare-api/docs/store-healthcare-data-rest
36+
37+
## Available Tools
38+
39+
- [`cloud-healthcare-get-dataset`](../tools/cloudhealthcare/cloud-healthcare-get-dataset.md)
40+
Retrieves a dataset’s details.
41+
42+
- [`cloud-healthcare-list-fhir-stores`](../tools/cloudhealthcare/cloud-healthcare-list-fhir-stores.md)
43+
Lists the available FHIR stores in the healthcare dataset.
44+
45+
- [`cloud-healthcare-list-dicom-stores`](../tools/cloudhealthcare/cloud-healthcare-list-dicom-stores.md)
46+
Lists the available DICOM stores in the healthcare dataset.
47+
48+
- [`cloud-healthcare-get-fhir-store`](../tools/cloudhealthcare/cloud-healthcare-get-fhir-store.md)
49+
Retrieves information about a FHIR store.
50+
51+
- [`cloud-healthcare-get-fhir-store-metrics`](../tools/cloudhealthcare/cloud-healthcare-get-fhir-store-metrics.md)
52+
Retrieves metrics for a FHIR store.
53+
54+
- [`cloud-healthcare-get-fhir-resource`](../tools/cloudhealthcare/cloud-healthcare-get-fhir-resource.md)
55+
Retrieves a specific FHIR resource from a FHIR store.
56+
57+
- [`cloud-healthcare-fhir-patient-search`](../tools/cloudhealthcare/cloud-healthcare-fhir-patient-search.md)
58+
Searches for patients in a FHIR store based on a set of criteria.
59+
60+
- [`cloud-healthcare-fhir-patient-everything`](../tools/cloudhealthcare/cloud-healthcare-fhir-patient-everything.md)
61+
Retrieves all information for a given patient.
62+
63+
- [`cloud-healthcare-fhir-fetch-page`](../tools/cloudhealthcare/cloud-healthcare-fhir-fetch-page.md)
64+
Fetches a page of FHIR resources from a given URL.
65+
66+
- [`cloud-healthcare-get-dicom-store`](../tools/cloudhealthcare/cloud-healthcare-get-dicom-store.md)
67+
Retrieves information about a DICOM store.
68+
69+
- [`cloud-healthcare-get-dicom-store-metrics`](../tools/cloudhealthcare/cloud-healthcare-get-dicom-store-metrics.md)
70+
Retrieves metrics for a DICOM store.
71+
72+
- [`cloud-healthcare-search-dicom-studies`](../tools/cloudhealthcare/cloud-healthcare-search-dicom-studies.md)
73+
Searches for DICOM studies in a DICOM store.
74+
75+
- [`cloud-healthcare-search-dicom-series`](../tools/cloudhealthcare/cloud-healthcare-search-dicom-series.md)
76+
Searches for DICOM series in a DICOM store.
77+
78+
- [`cloud-healthcare-search-dicom-instances`](../tools/cloudhealthcare/cloud-healthcare-search-dicom-instances.md)
79+
Searches for DICOM instances in a DICOM store.
80+
81+
- [`cloud-healthcare-retrieve-rendered-dicom-instance`](../tools/cloudhealthcare/cloud-healthcare-retrieve-rendered-dicom-instance.md)
82+
Retrieves a rendered DICOM instance from a DICOM store.
83+
84+
## Requirements
85+
86+
### IAM Permissions
87+
88+
The Cloud Healthcare API uses [Identity and Access Management (IAM)][iam-overview] to control
89+
user and group access to Cloud Healthcare resources like projects, datasets, and stores.
90+
91+
### Authentication via Application Default Credentials (ADC)
92+
93+
By **default**, Toolbox will use your [Application Default Credentials
94+
(ADC)][adc] to authorize and authenticate when interacting with the
95+
[Cloud Healthcare API][healthcare-docs].
96+
97+
When using this method, you need to ensure the IAM identity associated with your
98+
ADC (such as a service account) has the correct permissions for the queries you
99+
intend to run. Common roles include `roles/healthcare.fhirResourceReader` (which includes
100+
permissions to read and search for FHIR resources) or `roles/healthcare.dicomViewer` (for
101+
retrieving DICOM images).
102+
Follow this [guide][set-adc] to set up your ADC.
103+
104+
### Authentication via User's OAuth Access Token
105+
106+
If the `useClientOAuth` parameter is set to `true`, Toolbox will instead use the
107+
OAuth access token for authentication. This token is parsed from the
108+
`Authorization` header passed in with the tool invocation request. This method
109+
allows Toolbox to make queries to the [Cloud Healthcare API][healthcare-docs] on behalf of the
110+
client or the end-user.
111+
112+
When using this on-behalf-of authentication, you must ensure that the
113+
identity used has been granted the correct IAM permissions.
114+
115+
[iam-overview]: <https://cloud.google.com/healthcare/docs/access-control>
116+
[adc]: <https://cloud.google.com/docs/authentication#adc>
117+
[set-adc]: <https://cloud.google.com/docs/authentication/provide-credentials-adc>
118+
119+
## Example
120+
121+
Initialize a Cloud Healthcare API source that uses ADC:
122+
123+
```yaml
124+
sources:
125+
my-healthcare-source:
126+
kind: "cloud-healthcare"
127+
project: "my-project-id"
128+
region: "us-central1"
129+
dataset: "my-healthcare-dataset-id"
130+
# allowedFhirStores: # Optional: Restricts tool access to a specific list of FHIR store IDs.
131+
# - "my_fhir_store_1"
132+
# allowedDicomStores: # Optional: Restricts tool access to a specific list of DICOM store IDs.
133+
# - "my_dicom_store_1"
134+
# - "my_dicom_store_2"
135+
```
136+
137+
Initialize a Cloud Healthcare API source that uses the client's access token:
138+
139+
```yaml
140+
sources:
141+
my-healthcare-client-auth-source:
142+
kind: "cloud-healthcare"
143+
project: "my-project-id"
144+
region: "us-central1"
145+
dataset: "my-healthcare-dataset-id"
146+
useClientOAuth: true
147+
# allowedFhirStores: # Optional: Restricts tool access to a specific list of FHIR store IDs.
148+
# - "my_fhir_store_1"
149+
# allowedDicomStores: # Optional: Restricts tool access to a specific list of DICOM store IDs.
150+
# - "my_dicom_store_1"
151+
# - "my_dicom_store_2"
152+
```
153+
154+
## Reference
155+
156+
| **field** | **type** | **required** | **description** |
157+
|--------------------|:--------:|:------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
158+
| kind | string | true | Must be "cloud-healthcare". |
159+
| project | string | true | ID of the GCP project that the dataset lives in. |
160+
| region | string | true | Specifies the region (e.g., 'us', 'asia-northeast1') of the healthcare dataset. [Learn More](https://cloud.google.com/healthcare-api/docs/regions) |
161+
| dataset | string | true | ID of the healthcare dataset. |
162+
| allowedFhirStores | []string | false | An optional list of FHIR store IDs that tools using this source are allowed to access. If provided, any tool operation attempting to access a store not in this list will be rejected. If a single store is provided, it will be treated as the default for prebuilt tools. |
163+
| allowedDicomStores | []string | false | An optional list of DICOM store IDs that tools using this source are allowed to access. If provided, any tool operation attempting to access a store not in this list will be rejected. If a single store is provided, it will be treated as the default for prebuilt tools. |
164+
| useClientOAuth | bool | false | If true, forwards the client's OAuth access token from the "Authorization" header to downstream queries. |

‎docs/en/resources/tools/cloudhealthcare/_index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: "Cloud Healthcare API"
3+
linkTitle: "Cloud Healthcare"
4+
type: docs
5+
weight: 1
6+
description: >
7+
Tools that work with Cloud Healthcare Sources.
8+
---

‎docs/en/resources/tools/cloudhealthcare/cloud-healthcare-fhir-fetch-page.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: "cloud-healthcare-fhir-fetch-page"
3+
type: docs
4+
weight: 1
5+
description: >
6+
A "cloud-healthcare-fhir-fetch-page" tool fetches a page of FHIR resources from a given URL.
7+
aliases:
8+
- /resources/tools/cloud-healthcare-fhir-fetch-page
9+
---
10+
11+
## About
12+
13+
A `cloud-healthcare-fhir-fetch-page` tool fetches a page of FHIR resources from a given URL. It's
14+
compatible with the following sources:
15+
16+
- [cloud-healthcare](../../sources/cloud-healthcare.md)
17+
18+
`cloud-healthcare-fhir-fetch-page` can be used for pagination when a previous tool call (like
19+
`cloud-healthcare-fhir-patient-search` or `cloud-healthcare-fhir-patient-everything`) returns a 'next' link in the response bundle.
20+
21+
## Example
22+
23+
```yaml
24+
tools:
25+
get_fhir_store:
26+
kind: cloud-healthcare-fhir-fetch-page
27+
source: my-healthcare-source
28+
description: Use this tool to fetch a page of FHIR resources from a FHIR Bundle's entry.link.url
29+
```
30+
31+
## Reference
32+
33+
| **field** | **type** | **required** | **description** |
34+
|-------------|:--------:|:------------:|----------------------------------------------------|
35+
| kind | string | true | Must be "cloud-healthcare-fhir-fetch-page". |
36+
| source | string | true | Name of the healthcare source. |
37+
| description | string | true | Description of the tool that is passed to the LLM. |
38+
39+
### Parameters
40+
41+
| **field** | **type** | **required** | **description** |
42+
|-----------|:--------:|:------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
43+
| pageURL | string | true | The full URL of the FHIR page to fetch. This would usually be the value of `Bundle.entry.link.url` field within the response returned from FHIR search or FHIR patient everything operations. |

0 commit comments

Comments
 (0)