Merge pull request #49 from PhenoML/fern-bot/2026-01-29T02-36Z

feat: add citation support and rename text search method

Author: kerbearasaurus

changelog.md

@@ -1,3 +1,15 @@
+## 3.1.0 - 2026-01-29
+* feat: add citation support and rename text search method
+* Adds source text citation functionality to code extraction and renames the text search method for better clarity. Citations provide exact text spans with character offsets showing where each code was found in the source text, enabling precise traceability.
+* Key changes:
+* Add Citation interface with text spans and character offsets
+* Add include_citations option to ExtractRequestConfig for sentence-based chunking
+* Add is_ancestor and citations fields to ExtractedCodeResult
+* Rename textSearchKeywordBased to terminologyServerTextSearch for clarity
+* Add CPT usage disclaimers and paid plan requirements to documentation
+* Add BadGatewayError (502) error handling to FHIR client methods
+* 🌿 Generated with Fern
+
 ## 3.0.0 - 2026-01-21
 * feat: make provider parameter required for agent operations
 * This change makes the provider parameter required for agent create and update operations,

package.json

@@ -1,6 +1,6 @@
 {
     "name": "phenoml",
-    "version": "3.0.0",
+    "version": "3.1.0",
     "private": false,
     "repository": "github:PhenoML/phenoml-ts-sdk",
     "type": "commonjs",

reference.md

@@ -1153,7 +1153,7 @@ await client.cohort.analyze({
 <dl>
 <dd>
 
-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!)
 </dd>
@@ -1223,7 +1223,9 @@ await client.construe.uploadCodeSystem({
 <dl>
 <dd>
 
-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.
 </dd>
 </dl>
 </dd>
@@ -1288,7 +1290,7 @@ await client.construe.extractCodes({
 <dl>
 <dd>
 
-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.
 </dd>
 </dl>
 </dd>
@@ -1343,7 +1345,9 @@ await client.construe.listAvailableCodeSystems();
 <dl>
 <dd>
 
-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.
 </dd>
 </dl>
 </dd>
@@ -1418,7 +1422,9 @@ await client.construe.listCodesInACodeSystem("ICD-10-CM", {
 <dl>
 <dd>
 
-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.
 </dd>
 </dl>
 </dd>
@@ -1514,6 +1520,8 @@ not just keywords.
 conceptually similar results that keyword search would miss.
 
 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.
 </dd>
 </dl>
 </dd>
@@ -1576,7 +1584,7 @@ await client.construe.semanticSearchEmbeddingBased("ICD-10-CM", {
 </dl>
 </details>
 
-<details><summary><code>client.construe.<a href="/src/api/resources/construe/client/Client.ts">textSearchKeywordBased</a>(codesystem, { ...params }) -> phenoml.TextSearchResponse</code></summary>
+<details><summary><code>client.construe.<a href="/src/api/resources/construe/client/Client.ts">terminologyServerTextSearch</a>(codesystem, { ...params }) -> phenoml.TextSearchResponse</code></summary>
 <dl>
 <dd>
 
@@ -1606,6 +1614,8 @@ the code ID or specific keywords. Fast response times suitable for typeahead int
 Won't find conceptually related codes with different terminology.
 
 See also: `/search/semantic` for finding conceptually similar codes.
+
+Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
 </dd>
 </dl>
 </dd>
@@ -1620,7 +1630,7 @@ See also: `/search/semantic` for finding conceptually similar codes.
 <dd>
 
 ```typescript
-await client.construe.textSearchKeywordBased("ICD-10-CM", {
+await client.construe.terminologyServerTextSearch("ICD-10-CM", {
     q: "E11.65",
     version: "version",
     limit: 1

src/Client.ts

@@ -40,8 +40,8 @@ export class phenomlClient {
                 {
                     "X-Fern-Language": "JavaScript",
                     "X-Fern-SDK-Name": "phenoml",
-                    "X-Fern-SDK-Version": "3.0.0",
-                    "User-Agent": "phenoml/3.0.0",
+                    "X-Fern-SDK-Version": "3.1.0",
+                    "User-Agent": "phenoml/3.1.0",
                     "X-Fern-Runtime": core.RUNTIME.type,
                     "X-Fern-Runtime-Version": core.RUNTIME.version,
                 },

src/api/resources/construe/client/Client.ts

@@ -21,7 +21,7 @@ export class Construe {
     }
 
     /**
-     * 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!)
      *
@@ -130,7 +130,9 @@ export class Construe {
     }
 
     /**
-     * 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.
      *
      * @param {phenoml.construe.ExtractRequest} request
      * @param {Construe.RequestOptions} requestOptions - Request-specific configuration.
@@ -228,7 +230,7 @@ export class Construe {
     }
 
     /**
-     * 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.
      *
      * @param {Construe.RequestOptions} requestOptions - Request-specific configuration.
      *
@@ -312,7 +314,9 @@ export class Construe {
     }
 
     /**
-     * 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.
      *
      * @param {string} codesystem - Code system name (e.g., "ICD-10-CM", "SNOMED_CT_US_LITE")
      * @param {phenoml.construe.GetConstrueCodesCodesystemRequest} request
@@ -423,7 +427,9 @@ export class Construe {
     }
 
     /**
-     * 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.
      *
      * @param {string} codesystem - Code system name
      * @param {string} codeId - The code identifier
@@ -547,6 +553,8 @@ export class Construe {
      *
      * 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.
+     *
      * @param {string} codesystem - Code system name
      * @param {phenoml.construe.GetConstrueCodesCodesystemSearchSemanticRequest} request
      * @param {Construe.RequestOptions} requestOptions - Request-specific configuration.
@@ -679,6 +687,8 @@ export class Construe {
      *
      * See also: `/search/semantic` for finding conceptually similar codes.
      *
+     * Usage of CPT is subject to AMA requirements: see PhenoML Terms of Service.
+     *
      * @param {string} codesystem - Code system name
      * @param {phenoml.construe.GetConstrueCodesCodesystemSearchTextRequest} request
      * @param {Construe.RequestOptions} requestOptions - Request-specific configuration.
@@ -691,21 +701,23 @@ export class Construe {
      * @throws {@link phenoml.construe.ServiceUnavailableError}
      *
      * @example
-     *     await client.construe.textSearchKeywordBased("ICD-10-CM", {
+     *     await client.construe.terminologyServerTextSearch("ICD-10-CM", {
      *         q: "E11.65",
      *         version: "version",
      *         limit: 1
      *     })
      */
-    public textSearchKeywordBased(
+    public terminologyServerTextSearch(
         codesystem: string,
         request: phenoml.construe.GetConstrueCodesCodesystemSearchTextRequest,
         requestOptions?: Construe.RequestOptions,
     ): core.HttpResponsePromise<phenoml.construe.TextSearchResponse> {
-        return core.HttpResponsePromise.fromPromise(this.__textSearchKeywordBased(codesystem, request, requestOptions));
+        return core.HttpResponsePromise.fromPromise(
+            this.__terminologyServerTextSearch(codesystem, request, requestOptions),
+        );
     }
 
-    private async __textSearchKeywordBased(
+    private async __terminologyServerTextSearch(
         codesystem: string,
         request: phenoml.construe.GetConstrueCodesCodesystemSearchTextRequest,
         requestOptions?: Construe.RequestOptions,

src/api/resources/construe/types/Citation.ts

@@ -0,0 +1,13 @@
+// This file was auto-generated by Fern from our API Definition.
+
+/**
+ * A reference to source text that led to a code extraction
+ */
+export interface Citation {
+    /** The exact text span containing evidence for the code */
+    text: string;
+    /** Starting byte offset in the original input text (0-indexed) */
+    begin_offset: number;
+    /** Ending byte offset (exclusive), such that input[begin_offset:end_offset] == text */
+    end_offset: number;
+}

src/api/resources/construe/types/ExtractRequestConfig.ts

@@ -25,6 +25,14 @@ export interface ExtractRequestConfig {
     include_ancestors?: boolean;
     /** Whether to include codes that failed validation in the results */
     include_invalid?: boolean;
+    /**
+     * 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.
+     */
+    include_citations?: boolean;
 }
 
 export namespace ExtractRequestConfig {

src/api/resources/construe/types/ExtractRequestSystem.ts

@@ -14,7 +14,9 @@ export interface ExtractRequestSystem {
      * * 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.
      */
     name?: string;
     /** Code system version. Must match the version available in your environment. */

src/api/resources/construe/types/ExtractedCodeResult.ts

@@ -1,5 +1,7 @@
 // This file was auto-generated by Fern from our API Definition.
 
+import type * as phenoml from "../../../index.js";
+
 export interface ExtractedCodeResult {
     /** The extracted code */
     code: string;
@@ -11,4 +13,15 @@ export interface ExtractedCodeResult {
     longDescription?: string;
     /** Explanation for why this code was extracted (if include_rationale is true) */
     rationale?: string;
+    /**
+     * Whether this code is an ancestor (parent) of an extracted code rather than directly extracted.
+     * Only present when include_ancestors is true.
+     */
+    is_ancestor?: boolean;
+    /**
+     * 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.
+     */
+    citations?: phenoml.construe.Citation[];
 }

src/api/resources/construe/types/index.ts

@@ -1,3 +1,4 @@
+export * from "./Citation.js";
 export * from "./CodeResponse.js";
 export * from "./CodeSystemDetails.js";
 export * from "./CodeSystemInfo.js";