phenoml 2.0.0__tar.gz → 3.0.0__tar.gz

{phenoml-2.0.0 → phenoml-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: phenoml
-Version: 2.0.0
+Version: 3.0.0
 Summary: 
 Requires-Python: >=3.8,<4.0
 Classifier: Intended Audience :: Developers

{phenoml-2.0.0 → phenoml-3.0.0}/pyproject.toml

@@ -3,7 +3,7 @@ name = "phenoml"
 
 [tool.poetry]
 name = "phenoml"
-version = "2.0.0"
+version = "3.0.0"
 description = ""
 readme = "README.md"
 authors = []

{phenoml-2.0.0 → phenoml-3.0.0}/src/phenoml/construe/__init__.py

@@ -3,6 +3,7 @@
 # isort: skip_file
 
 from .types import (
+    Citation,
     CodeResponse,
     CodeSystemDetails,
     CodeSystemInfo,
@@ -35,6 +36,7 @@ from .errors import (
 
 __all__ = [
     "BadRequestError",
+    "Citation",
     "CodeResponse",
     "CodeSystemDetails",
     "CodeSystemInfo",

{phenoml-2.0.0 → phenoml-3.0.0}/src/phenoml/construe/client.py

@@ -49,7 +49,7 @@ class ConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> ConstrueUploadCodeSystemResponse:
         """
-        Upload a custom medical code system with codes and descriptions for use in code extraction.
+        Upload a custom medical code system with codes and descriptions for use in code extraction. Requires a paid plan.
         Upon upload, construe generates embeddings for all of the codes in the code system and stores them in the vector database so you can
         subsequently use the code system for construe/extract and lang2fhir/create (coming soon!)
 
@@ -123,7 +123,9 @@ class ConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> ExtractCodesResult:
         """
-        Converts natural language text into structured medical codes
+        Converts natural language text into structured medical codes.
+
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
 
         Parameters
         ----------
@@ -162,7 +164,7 @@ class ConstrueClient:
         self, *, request_options: typing.Optional[RequestOptions] = None
     ) -> ListCodeSystemsResponse:
         """
-        Returns metadata about all available code systems including built-in and custom systems.
+        Returns the terminology server's catalog of available code systems, including both built-in standard terminologies and custom uploaded systems.
 
         Parameters
         ----------
@@ -196,7 +198,9 @@ class ConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> ListCodesResponse:
         """
-        Returns a paginated list of all codes in the specified code system.
+        Returns a paginated list of all codes in the specified code system from the terminology server.
+
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
 
         Parameters
         ----------
@@ -248,7 +252,9 @@ class ConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> GetCodeResponse:
         """
-        Returns details for a specific code within a code system.
+        Looks up a specific code in the terminology server and returns its details.
+
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
 
         Parameters
         ----------
@@ -313,6 +319,8 @@ class ConstrueClient:
 
         See also: `/search/text` for faster keyword-based lookup with typo tolerance.
 
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
+
         Parameters
         ----------
         codesystem : str
@@ -354,7 +362,7 @@ class ConstrueClient:
         )
         return _response.data
 
-    def text_search_keyword_based(
+    def terminology_server_text_search(
         self,
         codesystem: str,
         *,
@@ -383,6 +391,8 @@ class ConstrueClient:
 
         See also: `/search/semantic` for finding conceptually similar codes.
 
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
+
         Parameters
         ----------
         codesystem : str
@@ -412,14 +422,14 @@ class ConstrueClient:
         client = phenoml(
             token="YOUR_TOKEN",
         )
-        client.construe.text_search_keyword_based(
+        client.construe.terminology_server_text_search(
             codesystem="ICD-10-CM",
             q="E11.65",
             version="version",
             limit=1,
         )
         """
-        _response = self._raw_client.text_search_keyword_based(
+        _response = self._raw_client.terminology_server_text_search(
             codesystem, q=q, version=version, limit=limit, request_options=request_options
         )
         return _response.data
@@ -454,7 +464,7 @@ class AsyncConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> ConstrueUploadCodeSystemResponse:
         """
-        Upload a custom medical code system with codes and descriptions for use in code extraction.
+        Upload a custom medical code system with codes and descriptions for use in code extraction. Requires a paid plan.
         Upon upload, construe generates embeddings for all of the codes in the code system and stores them in the vector database so you can
         subsequently use the code system for construe/extract and lang2fhir/create (coming soon!)
 
@@ -536,7 +546,9 @@ class AsyncConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> ExtractCodesResult:
         """
-        Converts natural language text into structured medical codes
+        Converts natural language text into structured medical codes.
+
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
 
         Parameters
         ----------
@@ -583,7 +595,7 @@ class AsyncConstrueClient:
         self, *, request_options: typing.Optional[RequestOptions] = None
     ) -> ListCodeSystemsResponse:
         """
-        Returns metadata about all available code systems including built-in and custom systems.
+        Returns the terminology server's catalog of available code systems, including both built-in standard terminologies and custom uploaded systems.
 
         Parameters
         ----------
@@ -625,7 +637,9 @@ class AsyncConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> ListCodesResponse:
         """
-        Returns a paginated list of all codes in the specified code system.
+        Returns a paginated list of all codes in the specified code system from the terminology server.
+
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
 
         Parameters
         ----------
@@ -685,7 +699,9 @@ class AsyncConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> GetCodeResponse:
         """
-        Returns details for a specific code within a code system.
+        Looks up a specific code in the terminology server and returns its details.
+
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
 
         Parameters
         ----------
@@ -758,6 +774,8 @@ class AsyncConstrueClient:
 
         See also: `/search/text` for faster keyword-based lookup with typo tolerance.
 
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
+
         Parameters
         ----------
         codesystem : str
@@ -807,7 +825,7 @@ class AsyncConstrueClient:
         )
         return _response.data
 
-    async def text_search_keyword_based(
+    async def terminology_server_text_search(
         self,
         codesystem: str,
         *,
@@ -836,6 +854,8 @@ class AsyncConstrueClient:
 
         See also: `/search/semantic` for finding conceptually similar codes.
 
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
+
         Parameters
         ----------
         codesystem : str
@@ -870,7 +890,7 @@ class AsyncConstrueClient:
 
 
         async def main() -> None:
-            await client.construe.text_search_keyword_based(
+            await client.construe.terminology_server_text_search(
                 codesystem="ICD-10-CM",
                 q="E11.65",
                 version="version",
@@ -880,7 +900,7 @@ class AsyncConstrueClient:
 
         asyncio.run(main())
         """
-        _response = await self._raw_client.text_search_keyword_based(
+        _response = await self._raw_client.terminology_server_text_search(
             codesystem, q=q, version=version, limit=limit, request_options=request_options
         )
         return _response.data

{phenoml-2.0.0 → phenoml-3.0.0}/src/phenoml/construe/raw_client.py

@@ -51,7 +51,7 @@ class RawConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[ConstrueUploadCodeSystemResponse]:
         """
-        Upload a custom medical code system with codes and descriptions for use in code extraction.
+        Upload a custom medical code system with codes and descriptions for use in code extraction. Requires a paid plan.
         Upon upload, construe generates embeddings for all of the codes in the code system and stores them in the vector database so you can
         subsequently use the code system for construe/extract and lang2fhir/create (coming soon!)
 
@@ -187,7 +187,9 @@ class RawConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[ExtractCodesResult]:
         """
-        Converts natural language text into structured medical codes
+        Converts natural language text into structured medical codes.
+
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
 
         Parameters
         ----------
@@ -287,7 +289,7 @@ class RawConstrueClient:
         self, *, request_options: typing.Optional[RequestOptions] = None
     ) -> HttpResponse[ListCodeSystemsResponse]:
         """
-        Returns metadata about all available code systems including built-in and custom systems.
+        Returns the terminology server's catalog of available code systems, including both built-in standard terminologies and custom uploaded systems.
 
         Parameters
         ----------
@@ -351,7 +353,9 @@ class RawConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[ListCodesResponse]:
         """
-        Returns a paginated list of all codes in the specified code system.
+        Returns a paginated list of all codes in the specified code system from the terminology server.
+
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
 
         Parameters
         ----------
@@ -453,7 +457,9 @@ class RawConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> HttpResponse[GetCodeResponse]:
         """
-        Returns details for a specific code within a code system.
+        Looks up a specific code in the terminology server and returns its details.
+
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
 
         Parameters
         ----------
@@ -567,6 +573,8 @@ class RawConstrueClient:
 
         See also: `/search/text` for faster keyword-based lookup with typo tolerance.
 
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
+
         Parameters
         ----------
         codesystem : str
@@ -658,7 +666,7 @@ class RawConstrueClient:
             raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
         raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
 
-    def text_search_keyword_based(
+    def terminology_server_text_search(
         self,
         codesystem: str,
         *,
@@ -687,6 +695,8 @@ class RawConstrueClient:
 
         See also: `/search/semantic` for finding conceptually similar codes.
 
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
+
         Parameters
         ----------
         codesystem : str
@@ -819,7 +829,7 @@ class AsyncRawConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[ConstrueUploadCodeSystemResponse]:
         """
-        Upload a custom medical code system with codes and descriptions for use in code extraction.
+        Upload a custom medical code system with codes and descriptions for use in code extraction. Requires a paid plan.
         Upon upload, construe generates embeddings for all of the codes in the code system and stores them in the vector database so you can
         subsequently use the code system for construe/extract and lang2fhir/create (coming soon!)
 
@@ -955,7 +965,9 @@ class AsyncRawConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[ExtractCodesResult]:
         """
-        Converts natural language text into structured medical codes
+        Converts natural language text into structured medical codes.
+
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
 
         Parameters
         ----------
@@ -1055,7 +1067,7 @@ class AsyncRawConstrueClient:
         self, *, request_options: typing.Optional[RequestOptions] = None
     ) -> AsyncHttpResponse[ListCodeSystemsResponse]:
         """
-        Returns metadata about all available code systems including built-in and custom systems.
+        Returns the terminology server's catalog of available code systems, including both built-in standard terminologies and custom uploaded systems.
 
         Parameters
         ----------
@@ -1119,7 +1131,9 @@ class AsyncRawConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[ListCodesResponse]:
         """
-        Returns a paginated list of all codes in the specified code system.
+        Returns a paginated list of all codes in the specified code system from the terminology server.
+
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
 
         Parameters
         ----------
@@ -1221,7 +1235,9 @@ class AsyncRawConstrueClient:
         request_options: typing.Optional[RequestOptions] = None,
     ) -> AsyncHttpResponse[GetCodeResponse]:
         """
-        Returns details for a specific code within a code system.
+        Looks up a specific code in the terminology server and returns its details.
+
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
 
         Parameters
         ----------
@@ -1335,6 +1351,8 @@ class AsyncRawConstrueClient:
 
         See also: `/search/text` for faster keyword-based lookup with typo tolerance.
 
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
+
         Parameters
         ----------
         codesystem : str
@@ -1426,7 +1444,7 @@ class AsyncRawConstrueClient:
             raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
         raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
 
-    async def text_search_keyword_based(
+    async def terminology_server_text_search(
         self,
         codesystem: str,
         *,
@@ -1455,6 +1473,8 @@ class AsyncRawConstrueClient:
 
         See also: `/search/semantic` for finding conceptually similar codes.
 
+        Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
+
         Parameters
         ----------
         codesystem : str

{phenoml-2.0.0 → phenoml-3.0.0}/src/phenoml/construe/types/__init__.py

@@ -2,6 +2,7 @@
 
 # isort: skip_file
 
+from .citation import Citation
 from .code_response import CodeResponse
 from .code_system_details import CodeSystemDetails
 from .code_system_info import CodeSystemInfo
@@ -22,6 +23,7 @@ from .text_search_result import TextSearchResult
 from .upload_request_format import UploadRequestFormat
 
 __all__ = [
+    "Citation",
     "CodeResponse",
     "CodeSystemDetails",
     "CodeSystemInfo",

phenoml-3.0.0/src/phenoml/construe/types/citation.py

@@ -0,0 +1,36 @@
+# 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 Citation(UniversalBaseModel):
+    """
+    A reference to source text that led to a code extraction
+    """
+
+    text: str = pydantic.Field()
+    """
+    The exact text span containing evidence for the code
+    """
+
+    begin_offset: int = pydantic.Field()
+    """
+    Starting byte offset in the original input text (0-indexed)
+    """
+
+    end_offset: int = pydantic.Field()
+    """
+    Ending byte offset (exclusive), such that input[begin_offset:end_offset] == text
+    """
+
+    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-2.0.0 → phenoml-3.0.0}/src/phenoml/construe/types/extract_request_config.py

@@ -50,6 +50,15 @@ class ExtractRequestConfig(UniversalBaseModel):
     Whether to include codes that failed validation in the results
     """
 
+    include_citations: typing.Optional[bool] = pydantic.Field(default=None)
+    """
+    Whether to include source text citations for each extracted code.
+    Citations show the exact text spans (with character offsets) that led to each code.
+    Only available when using chunking_method: "sentences".
+    The "none" method returns full text as one chunk (not useful for citations).
+    LLM-based chunking (paragraphs, topics) does not support citations.
+    """
+
     if IS_PYDANTIC_V2:
         model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
     else:

{phenoml-2.0.0 → phenoml-3.0.0}/src/phenoml/construe/types/extract_request_system.py

@@ -21,7 +21,9 @@ class ExtractRequestSystem(UniversalBaseModel):
     * CPT - version 2025
     
     Custom systems:
-    * Any valid system name configured in your environment. Must have self-hosted construe module.
+    * Any valid system name uploaded via /construe/upload. Requires a paid plan.
+    
+    Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
     """
 
     version: typing.Optional[str] = pydantic.Field(default=None)

{phenoml-2.0.0 → phenoml-3.0.0}/src/phenoml/construe/types/extracted_code_result.py

@@ -6,6 +6,7 @@ import pydantic
 import typing_extensions
 from ...core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel
 from ...core.serialization import FieldMetadata
+from .citation import Citation
 
 
 class ExtractedCodeResult(UniversalBaseModel):
@@ -36,6 +37,19 @@ class ExtractedCodeResult(UniversalBaseModel):
     Explanation for why this code was extracted (if include_rationale is true)
     """
 
+    is_ancestor: typing.Optional[bool] = pydantic.Field(default=None)
+    """
+    Whether this code is an ancestor (parent) of an extracted code rather than directly extracted.
+    Only present when include_ancestors is true.
+    """
+
+    citations: typing.Optional[typing.List[Citation]] = pydantic.Field(default=None)
+    """
+    Source text references showing where this code was found in the input.
+    Only present when include_citations is true and chunking method supports it.
+    Ancestor codes do not receive citations.
+    """
+
     if IS_PYDANTIC_V2:
         model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
     else:

{phenoml-2.0.0 → phenoml-3.0.0}/src/phenoml/core/client_wrapper.py

@@ -22,10 +22,10 @@ class BaseClientWrapper:
 
     def get_headers(self) -> typing.Dict[str, str]:
         headers: typing.Dict[str, str] = {
-            "User-Agent": "phenoml/2.0.0",
+            "User-Agent": "phenoml/3.0.0",
             "X-Fern-Language": "Python",
             "X-Fern-SDK-Name": "phenoml",
-            "X-Fern-SDK-Version": "2.0.0",
+            "X-Fern-SDK-Version": "3.0.0",
             **(self.get_custom_headers() or {}),
         }
         headers["Authorization"] = f"Bearer {self._get_token()}"

{phenoml-2.0.0 → phenoml-3.0.0}/src/phenoml/fhir/__init__.py

@@ -15,9 +15,10 @@ from .types import (
     FhirResourceMeta,
     FhirSearchResponse,
 )
-from .errors import BadRequestError, InternalServerError, NotFoundError, UnauthorizedError
+from .errors import BadGatewayError, BadRequestError, InternalServerError, NotFoundError, UnauthorizedError
 
 __all__ = [
+    "BadGatewayError",
     "BadRequestError",
     "ErrorResponse",
     "FhirBundle",

{phenoml-2.0.0 → phenoml-3.0.0}/src/phenoml/fhir/errors/__init__.py

@@ -2,9 +2,10 @@
 
 # isort: skip_file
 
+from .bad_gateway_error import BadGatewayError
 from .bad_request_error import BadRequestError
 from .internal_server_error import InternalServerError
 from .not_found_error import NotFoundError
 from .unauthorized_error import UnauthorizedError
 
-__all__ = ["BadRequestError", "InternalServerError", "NotFoundError", "UnauthorizedError"]
+__all__ = ["BadGatewayError", "BadRequestError", "InternalServerError", "NotFoundError", "UnauthorizedError"]

phenoml-3.0.0/src/phenoml/fhir/errors/bad_gateway_error.py

@@ -0,0 +1,11 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ...core.api_error import ApiError
+from ..types.error_response import ErrorResponse
+
+
+class BadGatewayError(ApiError):
+    def __init__(self, body: ErrorResponse, headers: typing.Optional[typing.Dict[str, str]] = None):
+        super().__init__(status_code=502, headers=headers, body=body)