phenoml 0.0.18__py3-none-any.whl → 0.0.19__py3-none-any.whl

phenoml/fhir_provider/raw_client.py

@@ -21,7 +21,6 @@ from .types.fhir_provider_delete_response import FhirProviderDeleteResponse
 from .types.fhir_provider_list_response import FhirProviderListResponse
 from .types.fhir_provider_remove_auth_config_response import FhirProviderRemoveAuthConfigResponse
 from .types.fhir_provider_response import FhirProviderResponse
-from .types.fhir_provider_set_active_auth_config_response import FhirProviderSetActiveAuthConfigResponse
 from .types.provider import Provider
 from .types.role import Role
 from .types.service_account_key import ServiceAccountKey
@@ -50,7 +49,9 @@ class RawFhirProviderClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[FhirProviderResponse]:
         """
-        Creates a new FHIR provider configuration with authentication credentials
+        Creates a new FHIR provider configuration with authentication credentials.
+
+        Note: The "sandbox" provider type cannot be created via this API - it is managed internally.
 
         Parameters
         ----------
@@ -174,7 +175,10 @@ class RawFhirProviderClient:
         self, *, request_options: typing.Optional[RequestOptions] = None
     ) -> HttpResponse[FhirProviderListResponse]:
         """
-        Retrieves a list of all active FHIR providers for the authenticated user
+        Retrieves a list of all active FHIR providers for the authenticated user.
+
+        On shared instances, only sandbox providers are returned.
+        Sandbox providers return FhirProviderSandboxInfo.
 
         Parameters
         ----------
@@ -212,17 +216,6 @@ class RawFhirProviderClient:
                         ),
                     ),
                 )
-            if _response.status_code == 403:
-                raise ForbiddenError(
-                    headers=dict(_response.headers),
-                    body=typing.cast(
-                        typing.Optional[typing.Any],
-                        parse_obj_as(
-                            type_=typing.Optional[typing.Any],  # type: ignore
-                            object_=_response.json(),
-                        ),
-                    ),
-                )
             if _response.status_code == 500:
                 raise InternalServerError(
                     headers=dict(_response.headers),
@@ -243,7 +236,10 @@ class RawFhirProviderClient:
         self, fhir_provider_id: str, *, request_options: typing.Optional[RequestOptions] = None
     ) -> HttpResponse[FhirProviderResponse]:
         """
-        Retrieves a specific FHIR provider configuration by its ID
+        Retrieves a specific FHIR provider configuration by its ID.
+
+        Sandbox providers return FhirProviderSandboxInfo.
+        On shared instances, only sandbox providers can be accessed.
 
         Parameters
         ----------
@@ -326,7 +322,9 @@ class RawFhirProviderClient:
         self, fhir_provider_id: str, *, request_options: typing.Optional[RequestOptions] = None
     ) -> HttpResponse[FhirProviderDeleteResponse]:
         """
-        Soft deletes a FHIR provider by setting is_active to false
+        Soft deletes a FHIR provider by setting is_active to false.
+
+        Note: Sandbox providers cannot be deleted.
 
         Parameters
         ----------
@@ -418,7 +416,10 @@ class RawFhirProviderClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[FhirProviderResponse]:
         """
-        Adds a new authentication configuration to an existing FHIR provider. This enables key rotation and multiple auth configurations per provider.
+        Adds a new authentication configuration to an existing FHIR provider.
+        This enables key rotation and multiple auth configurations per provider.
+
+        Note: Sandbox providers cannot be modified.
 
         Parameters
         ----------
@@ -539,9 +540,15 @@ class RawFhirProviderClient:
 
     def set_active_auth_config(
         self, fhir_provider_id: str, *, auth_config_id: str, request_options: typing.Optional[RequestOptions] = None
-    ) -> HttpResponse[FhirProviderSetActiveAuthConfigResponse]:
+    ) -> HttpResponse[FhirProviderResponse]:
         """
-        Sets which authentication configuration should be active for a FHIR provider. Only one auth config can be active at a time.
+        Sets which authentication configuration should be active for a FHIR provider.
+        Only one auth config can be active at a time.
+
+        If the specified auth config is already active, the request succeeds without
+        making any changes and returns a message indicating the config is already active.
+
+        Note: Sandbox providers cannot be modified.
 
         Parameters
         ----------
@@ -556,8 +563,9 @@ class RawFhirProviderClient:
 
         Returns
         -------
-        HttpResponse[FhirProviderSetActiveAuthConfigResponse]
-            Active auth configuration set successfully
+        HttpResponse[FhirProviderResponse]
+            Active auth configuration set successfully, or the config was already active.
+            Check the message field to determine which case occurred.
         """
         _response = self._client_wrapper.httpx_client.request(
             f"fhir-provider/{jsonable_encoder(fhir_provider_id)}/set-active-auth-config",
@@ -574,9 +582,9 @@ class RawFhirProviderClient:
         try:
             if 200 <= _response.status_code < 300:
                 _data = typing.cast(
-                    FhirProviderSetActiveAuthConfigResponse,
+                    FhirProviderResponse,
                     parse_obj_as(
-                        type_=FhirProviderSetActiveAuthConfigResponse,  # type: ignore
+                        type_=FhirProviderResponse,  # type: ignore
                         object_=_response.json(),
                     ),
                 )
@@ -645,7 +653,10 @@ class RawFhirProviderClient:
         self, fhir_provider_id: str, *, auth_config_id: str, request_options: typing.Optional[RequestOptions] = None
     ) -> HttpResponse[FhirProviderRemoveAuthConfigResponse]:
         """
-        Removes an authentication configuration from a FHIR provider. Cannot remove the currently active auth configuration.
+        Removes an authentication configuration from a FHIR provider.
+        Cannot remove the currently active auth configuration.
+
+        Note: Sandbox providers cannot be modified.
 
         Parameters
         ----------
@@ -766,7 +777,9 @@ class AsyncRawFhirProviderClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[FhirProviderResponse]:
         """
-        Creates a new FHIR provider configuration with authentication credentials
+        Creates a new FHIR provider configuration with authentication credentials.
+
+        Note: The "sandbox" provider type cannot be created via this API - it is managed internally.
 
         Parameters
         ----------
@@ -890,7 +903,10 @@ class AsyncRawFhirProviderClient:
         self, *, request_options: typing.Optional[RequestOptions] = None
     ) -> AsyncHttpResponse[FhirProviderListResponse]:
         """
-        Retrieves a list of all active FHIR providers for the authenticated user
+        Retrieves a list of all active FHIR providers for the authenticated user.
+
+        On shared instances, only sandbox providers are returned.
+        Sandbox providers return FhirProviderSandboxInfo.
 
         Parameters
         ----------
@@ -928,17 +944,6 @@ class AsyncRawFhirProviderClient:
                         ),
                     ),
                 )
-            if _response.status_code == 403:
-                raise ForbiddenError(
-                    headers=dict(_response.headers),
-                    body=typing.cast(
-                        typing.Optional[typing.Any],
-                        parse_obj_as(
-                            type_=typing.Optional[typing.Any],  # type: ignore
-                            object_=_response.json(),
-                        ),
-                    ),
-                )
             if _response.status_code == 500:
                 raise InternalServerError(
                     headers=dict(_response.headers),
@@ -959,7 +964,10 @@ class AsyncRawFhirProviderClient:
         self, fhir_provider_id: str, *, request_options: typing.Optional[RequestOptions] = None
     ) -> AsyncHttpResponse[FhirProviderResponse]:
         """
-        Retrieves a specific FHIR provider configuration by its ID
+        Retrieves a specific FHIR provider configuration by its ID.
+
+        Sandbox providers return FhirProviderSandboxInfo.
+        On shared instances, only sandbox providers can be accessed.
 
         Parameters
         ----------
@@ -1042,7 +1050,9 @@ class AsyncRawFhirProviderClient:
         self, fhir_provider_id: str, *, request_options: typing.Optional[RequestOptions] = None
     ) -> AsyncHttpResponse[FhirProviderDeleteResponse]:
         """
-        Soft deletes a FHIR provider by setting is_active to false
+        Soft deletes a FHIR provider by setting is_active to false.
+
+        Note: Sandbox providers cannot be deleted.
 
         Parameters
         ----------
@@ -1134,7 +1144,10 @@ class AsyncRawFhirProviderClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[FhirProviderResponse]:
         """
-        Adds a new authentication configuration to an existing FHIR provider. This enables key rotation and multiple auth configurations per provider.
+        Adds a new authentication configuration to an existing FHIR provider.
+        This enables key rotation and multiple auth configurations per provider.
+
+        Note: Sandbox providers cannot be modified.
 
         Parameters
         ----------
@@ -1255,9 +1268,15 @@ class AsyncRawFhirProviderClient:
 
     async def set_active_auth_config(
         self, fhir_provider_id: str, *, auth_config_id: str, request_options: typing.Optional[RequestOptions] = None
-    ) -> AsyncHttpResponse[FhirProviderSetActiveAuthConfigResponse]:
+    ) -> AsyncHttpResponse[FhirProviderResponse]:
         """
-        Sets which authentication configuration should be active for a FHIR provider. Only one auth config can be active at a time.
+        Sets which authentication configuration should be active for a FHIR provider.
+        Only one auth config can be active at a time.
+
+        If the specified auth config is already active, the request succeeds without
+        making any changes and returns a message indicating the config is already active.
+
+        Note: Sandbox providers cannot be modified.
 
         Parameters
         ----------
@@ -1272,8 +1291,9 @@ class AsyncRawFhirProviderClient:
 
         Returns
         -------
-        AsyncHttpResponse[FhirProviderSetActiveAuthConfigResponse]
-            Active auth configuration set successfully
+        AsyncHttpResponse[FhirProviderResponse]
+            Active auth configuration set successfully, or the config was already active.
+            Check the message field to determine which case occurred.
         """
         _response = await self._client_wrapper.httpx_client.request(
             f"fhir-provider/{jsonable_encoder(fhir_provider_id)}/set-active-auth-config",
@@ -1290,9 +1310,9 @@ class AsyncRawFhirProviderClient:
         try:
             if 200 <= _response.status_code < 300:
                 _data = typing.cast(
-                    FhirProviderSetActiveAuthConfigResponse,
+                    FhirProviderResponse,
                     parse_obj_as(
-                        type_=FhirProviderSetActiveAuthConfigResponse,  # type: ignore
+                        type_=FhirProviderResponse,  # type: ignore
                         object_=_response.json(),
                     ),
                 )
@@ -1361,7 +1381,10 @@ class AsyncRawFhirProviderClient:
         self, fhir_provider_id: str, *, auth_config_id: str, request_options: typing.Optional[RequestOptions] = None
     ) -> AsyncHttpResponse[FhirProviderRemoveAuthConfigResponse]:
         """
-        Removes an authentication configuration from a FHIR provider. Cannot remove the currently active auth configuration.
+        Removes an authentication configuration from a FHIR provider.
+        Cannot remove the currently active auth configuration.
+
+        Note: Sandbox providers cannot be modified.
 
         Parameters
         ----------

phenoml/fhir_provider/types/__init__.py

@@ -6,9 +6,11 @@ from .auth_method import AuthMethod
 from .fhir_provider_auth_config import FhirProviderAuthConfig
 from .fhir_provider_delete_response import FhirProviderDeleteResponse
 from .fhir_provider_list_response import FhirProviderListResponse
+from .fhir_provider_list_response_fhir_providers_item import FhirProviderListResponseFhirProvidersItem
 from .fhir_provider_remove_auth_config_response import FhirProviderRemoveAuthConfigResponse
 from .fhir_provider_response import FhirProviderResponse
-from .fhir_provider_set_active_auth_config_response import FhirProviderSetActiveAuthConfigResponse
+from .fhir_provider_response_data import FhirProviderResponseData
+from .fhir_provider_sandbox_info import FhirProviderSandboxInfo
 from .fhir_provider_template import FhirProviderTemplate
 from .fhir_query_response import FhirQueryResponse
 from .fhir_query_response_data import FhirQueryResponseData
@@ -16,6 +18,7 @@ from .json_web_key import JsonWebKey
 from .provider import Provider
 from .role import Role
 from .service_account_key import ServiceAccountKey
+from .service_account_metadata import ServiceAccountMetadata
 from .smart_configuration import SmartConfiguration
 
 __all__ = [
@@ -23,9 +26,11 @@ __all__ = [
     "FhirProviderAuthConfig",
     "FhirProviderDeleteResponse",
     "FhirProviderListResponse",
+    "FhirProviderListResponseFhirProvidersItem",
     "FhirProviderRemoveAuthConfigResponse",
     "FhirProviderResponse",
-    "FhirProviderSetActiveAuthConfigResponse",
+    "FhirProviderResponseData",
+    "FhirProviderSandboxInfo",
     "FhirProviderTemplate",
     "FhirQueryResponse",
     "FhirQueryResponseData",
@@ -33,5 +38,6 @@ __all__ = [
     "Provider",
     "Role",
     "ServiceAccountKey",
+    "ServiceAccountMetadata",
     "SmartConfiguration",
 ]

phenoml/fhir_provider/types/fhir_provider_auth_config.py

@@ -7,6 +7,7 @@ import pydantic
 from ...core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
 from .auth_method import AuthMethod
 from .json_web_key import JsonWebKey
+from .service_account_metadata import ServiceAccountMetadata
 from .smart_configuration import SmartConfiguration
 
 
@@ -26,6 +27,16 @@ class FhirProviderAuthConfig(UniversalBaseModel):
     Whether this auth configuration is currently active
     """
 
+    created_at: typing.Optional[dt.datetime] = pydantic.Field(default=None)
+    """
+    Timestamp when this auth configuration was created
+    """
+
+    updated_at: typing.Optional[dt.datetime] = pydantic.Field(default=None)
+    """
+    Timestamp when this auth configuration was last updated
+    """
+
     public_key_cert_pem: typing.Optional[str] = pydantic.Field(default=None)
     """
     Public key certificate in PEM format (visible for JWT auth)
@@ -38,6 +49,7 @@ class FhirProviderAuthConfig(UniversalBaseModel):
     """
 
     smart_configuration: typing.Optional[SmartConfiguration] = None
+    service_account_metadata: typing.Optional[ServiceAccountMetadata] = None
     scopes: typing.Optional[str] = pydantic.Field(default=None)
     """
     OAuth scopes

phenoml/fhir_provider/types/fhir_provider_list_response.py

@@ -4,13 +4,25 @@ import typing
 
 import pydantic
 from ...core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
-from .fhir_provider_template import FhirProviderTemplate
+from .fhir_provider_list_response_fhir_providers_item import FhirProviderListResponseFhirProvidersItem
 
 
 class FhirProviderListResponse(UniversalBaseModel):
+    """
+    Response payload for listing FHIR Providers.
+    On shared instances, only sandbox providers are returned (as FhirProviderSandboxInfo).
+    On dedicated instances, full provider details are returned (as FhirProviderTemplate).
+    """
+
     success: typing.Optional[bool] = None
     message: typing.Optional[str] = None
-    fhir_providers: typing.Optional[typing.List[FhirProviderTemplate]] = None
+    fhir_providers: typing.Optional[typing.List[FhirProviderListResponseFhirProvidersItem]] = pydantic.Field(
+        default=None
+    )
+    """
+    List of FHIR providers. Sandbox providers return FhirProviderSandboxInfo,
+    other providers return FhirProviderTemplate.
+    """
 
     if IS_PYDANTIC_V2:
         model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2

phenoml/fhir_provider/types/fhir_provider_list_response_fhir_providers_item.py

@@ -0,0 +1,8 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from .fhir_provider_sandbox_info import FhirProviderSandboxInfo
+from .fhir_provider_template import FhirProviderTemplate
+
+FhirProviderListResponseFhirProvidersItem = typing.Union[FhirProviderTemplate, FhirProviderSandboxInfo]

phenoml/fhir_provider/types/fhir_provider_response.py

@@ -4,13 +4,20 @@ import typing
 
 import pydantic
 from ...core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
-from .fhir_provider_template import FhirProviderTemplate
+from .fhir_provider_response_data import FhirProviderResponseData
 
 
 class FhirProviderResponse(UniversalBaseModel):
+    """
+    Response payload for a single FHIR Provider operation.
+    """
+
     success: typing.Optional[bool] = None
     message: typing.Optional[str] = None
-    data: typing.Optional[FhirProviderTemplate] = None
+    data: typing.Optional[FhirProviderResponseData] = pydantic.Field(default=None)
+    """
+    Provider details. Sandbox providers return FhirProviderSandboxInfo.
+    """
 
     if IS_PYDANTIC_V2:
         model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2

phenoml/fhir_provider/types/fhir_provider_response_data.py

@@ -0,0 +1,8 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from .fhir_provider_sandbox_info import FhirProviderSandboxInfo
+from .fhir_provider_template import FhirProviderTemplate
+
+FhirProviderResponseData = typing.Union[FhirProviderTemplate, FhirProviderSandboxInfo]

phenoml/fhir_provider/types/fhir_provider_sandbox_info.py

@@ -0,0 +1,46 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ...core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+
+
+class FhirProviderSandboxInfo(UniversalBaseModel):
+    """
+    Information returned for sandbox FHIR providers.
+    """
+
+    id: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Unique identifier for the FHIR provider
+    """
+
+    name: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Display name for the FHIR provider
+    """
+
+    description: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Optional description of the FHIR provider
+    """
+
+    provider: typing.Optional[typing.Literal["sandbox"]] = pydantic.Field(default=None)
+    """
+    Provider type (always "sandbox" for this schema)
+    """
+
+    is_active: typing.Optional[bool] = pydantic.Field(default=None)
+    """
+    Whether the FHIR provider is active
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

phenoml/fhir_provider/types/provider.py

@@ -3,6 +3,8 @@
 import typing
 
 Provider = typing.Union[
-    typing.Literal["athenahealth", "canvas", "cerner", "elation", "epic", "google_healthcare", "hapi", "medplum"],
+    typing.Literal[
+        "athenahealth", "canvas", "cerner", "elation", "epic", "google_healthcare", "hapi", "medplum", "sandbox"
+    ],
     typing.Any,
 ]

phenoml/fhir_provider/types/service_account_metadata.py

@@ -0,0 +1,41 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ...core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
+
+
+class ServiceAccountMetadata(UniversalBaseModel):
+    """
+    Non-sensitive metadata from a Google Cloud Service Account, exposed in API responses to help identify auth configurations without revealing sensitive credentials.
+    """
+
+    type: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Account type (always "service_account")
+    """
+
+    project_id: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Google Cloud project ID
+    """
+
+    client_email: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Service account email address
+    """
+
+    client_id: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Service account client ID
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

phenoml/lang2fhir/__init__.py

@@ -14,6 +14,7 @@ from .types import (
     FhirResource,
     Lang2FhirUploadProfileResponse,
     SearchResponse,
+    SearchResponseResourceType,
 )
 from .errors import BadRequestError, FailedDependencyError, ForbiddenError, InternalServerError, UnauthorizedError
 
@@ -33,5 +34,6 @@ __all__ = [
     "InternalServerError",
     "Lang2FhirUploadProfileResponse",
     "SearchResponse",
+    "SearchResponseResourceType",
     "UnauthorizedError",
 ]

phenoml/lang2fhir/client.py

@@ -130,12 +130,27 @@ class Lang2FhirClient:
 
     def search(self, *, text: str, request_options: typing.Optional[RequestOptions] = None) -> SearchResponse:
         """
-        Converts natural language text into FHIR search parameters
+        Converts natural language text into FHIR search parameters.
+        Automatically identifies the appropriate FHIR resource type and generates valid search query parameters.
+
+        Supported resource types include: AllergyIntolerance, Appointment, CarePlan, CareTeam, Condition,
+        Coverage, Device, DiagnosticReport, DocumentReference, Encounter, Goal, Immunization, Location,
+        Medication, MedicationRequest, Observation, Organization, Patient, PlanDefinition, Practitioner,
+        PractitionerRole, Procedure, Provenance, Questionnaire, QuestionnaireResponse, RelatedPerson,
+        Schedule, ServiceRequest, Slot, and Specimen.
 
         Parameters
         ----------
         text : str
-            Natural language text to convert into FHIR search parameters
+            Natural language text to convert into FHIR search parameters.
+            The system will automatically identify the appropriate resource type and generate valid search parameters.
+
+            Examples:
+            - "Appointments between March 2-9, 2025" → Appointment search with date range
+            - "Patients with diabetes" → Condition search with code parameter
+            - "Active medication requests for metformin" → MedicationRequest search
+            - "Lab results for creatinine" → DiagnosticReport search
+            - "Dr. Smith's schedule" → Practitioner or Schedule search
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -385,12 +400,27 @@ class AsyncLang2FhirClient:
 
     async def search(self, *, text: str, request_options: typing.Optional[RequestOptions] = None) -> SearchResponse:
         """
-        Converts natural language text into FHIR search parameters
+        Converts natural language text into FHIR search parameters.
+        Automatically identifies the appropriate FHIR resource type and generates valid search query parameters.
+
+        Supported resource types include: AllergyIntolerance, Appointment, CarePlan, CareTeam, Condition,
+        Coverage, Device, DiagnosticReport, DocumentReference, Encounter, Goal, Immunization, Location,
+        Medication, MedicationRequest, Observation, Organization, Patient, PlanDefinition, Practitioner,
+        PractitionerRole, Procedure, Provenance, Questionnaire, QuestionnaireResponse, RelatedPerson,
+        Schedule, ServiceRequest, Slot, and Specimen.
 
         Parameters
         ----------
         text : str
-            Natural language text to convert into FHIR search parameters
+            Natural language text to convert into FHIR search parameters.
+            The system will automatically identify the appropriate resource type and generate valid search parameters.
+
+            Examples:
+            - "Appointments between March 2-9, 2025" → Appointment search with date range
+            - "Patients with diabetes" → Condition search with code parameter
+            - "Active medication requests for metformin" → MedicationRequest search
+            - "Lab results for creatinine" → DiagnosticReport search
+            - "Dr. Smith's schedule" → Practitioner or Schedule search
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.

phenoml/lang2fhir/raw_client.py

@@ -219,12 +219,27 @@ class RawLang2FhirClient:
         self, *, text: str, request_options: typing.Optional[RequestOptions] = None
     ) -> HttpResponse[SearchResponse]:
         """
-        Converts natural language text into FHIR search parameters
+        Converts natural language text into FHIR search parameters.
+        Automatically identifies the appropriate FHIR resource type and generates valid search query parameters.
+
+        Supported resource types include: AllergyIntolerance, Appointment, CarePlan, CareTeam, Condition,
+        Coverage, Device, DiagnosticReport, DocumentReference, Encounter, Goal, Immunization, Location,
+        Medication, MedicationRequest, Observation, Organization, Patient, PlanDefinition, Practitioner,
+        PractitionerRole, Procedure, Provenance, Questionnaire, QuestionnaireResponse, RelatedPerson,
+        Schedule, ServiceRequest, Slot, and Specimen.
 
         Parameters
         ----------
         text : str
-            Natural language text to convert into FHIR search parameters
+            Natural language text to convert into FHIR search parameters.
+            The system will automatically identify the appropriate resource type and generate valid search parameters.
+
+            Examples:
+            - "Appointments between March 2-9, 2025" → Appointment search with date range
+            - "Patients with diabetes" → Condition search with code parameter
+            - "Active medication requests for metformin" → MedicationRequest search
+            - "Lab results for creatinine" → DiagnosticReport search
+            - "Dr. Smith's schedule" → Practitioner or Schedule search
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -695,12 +710,27 @@ class AsyncRawLang2FhirClient:
         self, *, text: str, request_options: typing.Optional[RequestOptions] = None
     ) -> AsyncHttpResponse[SearchResponse]:
         """
-        Converts natural language text into FHIR search parameters
+        Converts natural language text into FHIR search parameters.
+        Automatically identifies the appropriate FHIR resource type and generates valid search query parameters.
+
+        Supported resource types include: AllergyIntolerance, Appointment, CarePlan, CareTeam, Condition,
+        Coverage, Device, DiagnosticReport, DocumentReference, Encounter, Goal, Immunization, Location,
+        Medication, MedicationRequest, Observation, Organization, Patient, PlanDefinition, Practitioner,
+        PractitionerRole, Procedure, Provenance, Questionnaire, QuestionnaireResponse, RelatedPerson,
+        Schedule, ServiceRequest, Slot, and Specimen.
 
         Parameters
         ----------
         text : str
-            Natural language text to convert into FHIR search parameters
+            Natural language text to convert into FHIR search parameters.
+            The system will automatically identify the appropriate resource type and generate valid search parameters.
+
+            Examples:
+            - "Appointments between March 2-9, 2025" → Appointment search with date range
+            - "Patients with diabetes" → Condition search with code parameter
+            - "Active medication requests for metformin" → MedicationRequest search
+            - "Lab results for creatinine" → DiagnosticReport search
+            - "Dr. Smith's schedule" → Practitioner or Schedule search
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.

phenoml/lang2fhir/types/__init__.py

@@ -13,6 +13,7 @@ from .document_request_resource import DocumentRequestResource
 from .fhir_resource import FhirResource
 from .lang2fhir_upload_profile_response import Lang2FhirUploadProfileResponse
 from .search_response import SearchResponse
+from .search_response_resource_type import SearchResponseResourceType
 
 __all__ = [
     "CreateMultiResponse",
@@ -26,4 +27,5 @@ __all__ = [
     "FhirResource",
     "Lang2FhirUploadProfileResponse",
     "SearchResponse",
+    "SearchResponseResourceType",
 ]