phenoml 12.4.0 → 13.0.0

package/dist/cjs/BaseClient.js

@@ -43,8 +43,8 @@ function normalizeClientOptions(options) {
     const headers = (0, headers_js_1.mergeHeaders)({
         "X-Fern-Language": "JavaScript",
         "X-Fern-SDK-Name": "phenoml",
-        "X-Fern-SDK-Version": "12.4.0",
-        "User-Agent": "phenoml/12.4.0",
+        "X-Fern-SDK-Version": "13.0.0",
+        "User-Agent": "phenoml/13.0.0",
         "X-Fern-Runtime": core.RUNTIME.type,
         "X-Fern-Runtime-Version": core.RUNTIME.version,
     }, options === null || options === void 0 ? void 0 : options.headers);

package/dist/cjs/api/resources/lang2Fhir/client/Client.d.ts

@@ -11,7 +11,9 @@ export declare class Lang2FhirClient {
     protected readonly _options: NormalizedClientOptionsWithAuth<Lang2FhirClient.Options>;
     constructor(options?: Lang2FhirClient.Options);
     /**
-     * Converts natural language text into a structured FHIR resource
+     * Converts natural language text into a structured FHIR resource.
+     *
+     * **Patient identifier handling.** When generating a `patient` (or `patient-canvas`) resource, US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
      *
      * @param {phenoml.lang2Fhir.CreateRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -34,6 +36,8 @@ export declare class Lang2FhirClient {
      * Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types from the text.
      * Resources are linked with proper references (e.g., Conditions reference the Patient).
      *
+     * **Patient identifier handling.** US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the bundle remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
+     *
      * @param {phenoml.lang2Fhir.CreateMultiRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
      *
@@ -101,7 +105,9 @@ export declare class Lang2FhirClient {
     uploadProfile(request: phenoml.lang2Fhir.ProfileUploadRequest, requestOptions?: Lang2FhirClient.RequestOptions): core.HttpResponsePromise<phenoml.lang2Fhir.Lang2FhirUploadProfileResponse>;
     private __uploadProfile;
     /**
-     * Extracts text from a document (PDF or image) and converts it into a structured FHIR resource
+     * Extracts text from a document (PDF or image) and converts it into a structured FHIR resource.
+     *
+     * **Patient identifier handling.** When generating a `patient` (or `patient-canvas`) resource, US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
      *
      * @param {phenoml.lang2Fhir.DocumentRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -125,6 +131,8 @@ export declare class Lang2FhirClient {
      * Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types.
      * Resources are linked with proper references (e.g., Conditions reference the Patient).
      *
+     * **Patient identifier handling.** US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the bundle remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
+     *
      * @param {phenoml.lang2Fhir.DocumentMultiRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
      *
@@ -139,6 +147,6 @@ export declare class Lang2FhirClient {
      *         content: "content"
      *     })
      */
-    extractMultipleFhirResourcesFromADocument(request: phenoml.lang2Fhir.DocumentMultiRequest, requestOptions?: Lang2FhirClient.RequestOptions): core.HttpResponsePromise<phenoml.lang2Fhir.CreateMultiResponse>;
+    extractMultipleFhirResourcesFromADocument(request: phenoml.lang2Fhir.DocumentMultiRequest, requestOptions?: Lang2FhirClient.RequestOptions): core.HttpResponsePromise<phenoml.lang2Fhir.DocumentMultiResponse>;
     private __extractMultipleFhirResourcesFromADocument;
 }

package/dist/cjs/api/resources/lang2Fhir/client/Client.js

@@ -56,7 +56,9 @@ class Lang2FhirClient {
         this._options = (0, BaseClient_js_1.normalizeClientOptionsWithAuth)(options);
     }
     /**
-     * Converts natural language text into a structured FHIR resource
+     * Converts natural language text into a structured FHIR resource.
+     *
+     * **Patient identifier handling.** When generating a `patient` (or `patient-canvas`) resource, US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
      *
      * @param {phenoml.lang2Fhir.CreateRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -121,6 +123,8 @@ class Lang2FhirClient {
      * Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types from the text.
      * Resources are linked with proper references (e.g., Conditions reference the Patient).
      *
+     * **Patient identifier handling.** US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the bundle remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
+     *
      * @param {phenoml.lang2Fhir.CreateMultiRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
      *
@@ -324,7 +328,9 @@ class Lang2FhirClient {
         });
     }
     /**
-     * Extracts text from a document (PDF or image) and converts it into a structured FHIR resource
+     * Extracts text from a document (PDF or image) and converts it into a structured FHIR resource.
+     *
+     * **Patient identifier handling.** When generating a `patient` (or `patient-canvas`) resource, US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
      *
      * @param {phenoml.lang2Fhir.DocumentRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -390,6 +396,8 @@ class Lang2FhirClient {
      * Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types.
      * Resources are linked with proper references (e.g., Conditions reference the Patient).
      *
+     * **Patient identifier handling.** US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the bundle remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
+     *
      * @param {phenoml.lang2Fhir.DocumentMultiRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
      *

package/dist/cjs/api/resources/lang2Fhir/client/requests/CreateMultiRequest.d.ts

@@ -15,6 +15,8 @@ export interface CreateMultiRequest {
     implementation_guide?: string;
     /** Detection effort. 'standard' runs detection once, 'deep' runs detection multiple times for higher recall. */
     detection_effort?: CreateMultiRequest.DetectionEffort;
+    /** FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips. */
+    validation_method?: CreateMultiRequest.ValidationMethod;
 }
 export declare namespace CreateMultiRequest {
     /** Detection effort. 'standard' runs detection once, 'deep' runs detection multiple times for higher recall. */
@@ -23,4 +25,11 @@ export declare namespace CreateMultiRequest {
         readonly Deep: "deep";
     };
     type DetectionEffort = (typeof DetectionEffort)[keyof typeof DetectionEffort];
+    /** FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips. */
+    const ValidationMethod: {
+        readonly None: "none";
+        readonly Check: "check";
+        readonly Fix: "fix";
+    };
+    type ValidationMethod = (typeof ValidationMethod)[keyof typeof ValidationMethod];
 }

package/dist/cjs/api/resources/lang2Fhir/client/requests/CreateMultiRequest.js

@@ -9,4 +9,10 @@ var CreateMultiRequest;
         Standard: "standard",
         Deep: "deep",
     };
+    /** FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips. */
+    CreateMultiRequest.ValidationMethod = {
+        None: "none",
+        Check: "check",
+        Fix: "fix",
+    };
 })(CreateMultiRequest || (exports.CreateMultiRequest = CreateMultiRequest = {}));

package/dist/cjs/api/resources/lang2Fhir/client/requests/DocumentMultiRequest.d.ts

@@ -1,3 +1,4 @@
+import type * as phenoml from "../../../../index.js";
 /**
  * @example
  *     {
@@ -20,6 +21,9 @@ export interface DocumentMultiRequest {
     implementation_guide?: string;
     /** Detection effort. 'standard' runs detection once, 'deep' runs detection multiple times for higher recall. */
     detection_effort?: DocumentMultiRequest.DetectionEffort;
+    /** FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips. */
+    validation_method?: DocumentMultiRequest.ValidationMethod;
+    config?: phenoml.lang2Fhir.DocumentConfig;
 }
 export declare namespace DocumentMultiRequest {
     /** Detection effort. 'standard' runs detection once, 'deep' runs detection multiple times for higher recall. */
@@ -28,4 +32,11 @@ export declare namespace DocumentMultiRequest {
         readonly Deep: "deep";
     };
     type DetectionEffort = (typeof DetectionEffort)[keyof typeof DetectionEffort];
+    /** FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips. */
+    const ValidationMethod: {
+        readonly None: "none";
+        readonly Check: "check";
+        readonly Fix: "fix";
+    };
+    type ValidationMethod = (typeof ValidationMethod)[keyof typeof ValidationMethod];
 }

package/dist/cjs/api/resources/lang2Fhir/client/requests/DocumentMultiRequest.js

@@ -9,4 +9,10 @@ var DocumentMultiRequest;
         Standard: "standard",
         Deep: "deep",
     };
+    /** FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips. */
+    DocumentMultiRequest.ValidationMethod = {
+        None: "none",
+        Check: "check",
+        Fix: "fix",
+    };
 })(DocumentMultiRequest || (exports.DocumentMultiRequest = DocumentMultiRequest = {}));

package/dist/cjs/api/resources/lang2Fhir/client/requests/DocumentRequest.d.ts

@@ -1,3 +1,4 @@
+import type * as phenoml from "../../../../index.js";
 /**
  * @example
  *     {
@@ -17,4 +18,5 @@ export interface DocumentRequest {
      * File type is auto-detected from content magic bytes.
      */
     content: string;
+    config?: phenoml.lang2Fhir.DocumentConfig;
 }

package/dist/cjs/api/resources/lang2Fhir/types/CreateMultiResponse.d.ts

@@ -7,6 +7,8 @@ export interface CreateMultiResponse {
     bundle?: CreateMultiResponse.Bundle | undefined;
     /** Summary of extracted resources */
     resources?: CreateMultiResponse.Resources.Item[] | undefined;
+    /** FHIR validation results. Present when validation_method is 'check' or 'fix'. Contains results from each validation pass. For 'check', there is one pass. For 'fix', there may be up to 3 passes as the system attempts auto-correction. */
+    validation?: CreateMultiResponse.Validation | undefined;
 }
 export declare namespace CreateMultiResponse {
     /**
@@ -40,8 +42,71 @@ export declare namespace CreateMultiResponse {
             tempId?: string | undefined;
             /** FHIR resource type */
             resourceType?: string | undefined;
-            /** Text excerpt this resource was extracted from */
+            /** Context-enriched rewritten text excerpt for this resource */
             description?: string | undefined;
+            /** Verbatim text excerpt from the original clinical document */
+            originalText?: string | undefined;
+        }
+    }
+    /**
+     * FHIR validation results. Present when validation_method is 'check' or 'fix'. Contains results from each validation pass. For 'check', there is one pass. For 'fix', there may be up to 3 passes as the system attempts auto-correction.
+     */
+    interface Validation {
+        /** Results from each validation pass, in chronological order */
+        passes?: Validation.Passes.Item[] | undefined;
+        /** Whether validation errors were successfully fixed by the LLM. Always false for 'check' mode. For 'fix' mode, true if errors were resolved and the returned bundle is the corrected version. */
+        fixed?: boolean | undefined;
+        /** Total number of validation passes run (1 for check, 1-3 for fix) */
+        attempts?: number | undefined;
+        /** Human-readable summary of the validation outcome */
+        summary?: string | undefined;
+    }
+    namespace Validation {
+        type Passes = Passes.Item[];
+        namespace Passes {
+            interface Item {
+                /** Validation issues found in this pass */
+                issues?: Item.Issues.Item[] | undefined;
+                /** Validation statistics for this pass */
+                stats?: Item.Stats | undefined;
+            }
+            namespace Item {
+                type Issues = Issues.Item[];
+                namespace Issues {
+                    interface Item {
+                        /** Issue severity level */
+                        severity?: Item.Severity | undefined;
+                        /** Issue type code */
+                        code?: string | undefined;
+                        /** Human-readable description of the issue */
+                        diagnostics?: string | undefined;
+                        /** FHIRPath expression(s) pointing to the issue location */
+                        expression?: string[] | undefined;
+                        /** Validation phase that generated this issue */
+                        source?: string | undefined;
+                    }
+                    namespace Item {
+                        /** Issue severity level */
+                        const Severity: {
+                            readonly Fatal: "fatal";
+                            readonly Error: "error";
+                            readonly Warning: "warning";
+                            readonly Information: "information";
+                        };
+                        type Severity = (typeof Severity)[keyof typeof Severity];
+                    }
+                }
+                /**
+                 * Validation statistics for this pass
+                 */
+                interface Stats {
+                    resource_type?: string | undefined;
+                    profile_url?: string | undefined;
+                    is_custom_profile?: boolean | undefined;
+                    /** Validation duration in milliseconds */
+                    duration_ms?: number | undefined;
+                }
+            }
         }
     }
 }

package/dist/cjs/api/resources/lang2Fhir/types/CreateMultiResponse.js

@@ -1,3 +1,29 @@
 "use strict";
 // This file was auto-generated by Fern from our API Definition.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateMultiResponse = void 0;
+var CreateMultiResponse;
+(function (CreateMultiResponse) {
+    let Validation;
+    (function (Validation) {
+        let Passes;
+        (function (Passes) {
+            let Item;
+            (function (Item_1) {
+                let Issues;
+                (function (Issues) {
+                    let Item;
+                    (function (Item) {
+                        /** Issue severity level */
+                        Item.Severity = {
+                            Fatal: "fatal",
+                            Error: "error",
+                            Warning: "warning",
+                            Information: "information",
+                        };
+                    })(Item = Issues.Item || (Issues.Item = {}));
+                })(Issues = Item_1.Issues || (Item_1.Issues = {}));
+            })(Item = Passes.Item || (Passes.Item = {}));
+        })(Passes = Validation.Passes || (Validation.Passes = {}));
+    })(Validation = CreateMultiResponse.Validation || (CreateMultiResponse.Validation = {}));
+})(CreateMultiResponse || (exports.CreateMultiResponse = CreateMultiResponse = {}));

package/dist/cjs/api/resources/lang2Fhir/types/DocumentConfig.d.ts

@@ -0,0 +1,7 @@
+import type * as phenoml from "../../../index.js";
+/**
+ * Optional processing configuration shared across document endpoints.
+ */
+export interface DocumentConfig {
+    page_filter?: phenoml.lang2Fhir.PageFilter | undefined;
+}

package/dist/cjs/api/resources/lang2Fhir/types/DocumentConfig.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/resources/lang2Fhir/types/DocumentMultiResponse.d.ts

@@ -0,0 +1,5 @@
+import type * as phenoml from "../../../index.js";
+export interface DocumentMultiResponse extends phenoml.lang2Fhir.CreateMultiResponse {
+    /** Per-page classifier decisions. Populated only when a page_filter was supplied in the request. Contains one entry per input page, including both kept and dropped pages. */
+    page_classifications?: phenoml.lang2Fhir.PageClassification[] | undefined;
+}

package/dist/cjs/api/resources/lang2Fhir/types/DocumentMultiResponse.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/resources/lang2Fhir/types/PageClassification.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The classifier's decision for a single page of the input document.
+ */
+export interface PageClassification {
+    /** 1-indexed page number. */
+    page_number?: number | undefined;
+    /** Whether the page was kept (true) or dropped (false) from FHIR extraction. */
+    include?: boolean | undefined;
+    /** Short LLM-generated explanation of the decision. */
+    reason?: string | undefined;
+}

package/dist/cjs/api/resources/lang2Fhir/types/PageClassification.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/resources/lang2Fhir/types/PageFilter.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Configures per-page pre-extraction filtering. When set, each page of text extracted from the document is classified by an LLM, and pages classified as irrelevant to the supplied context are dropped before FHIR extraction.
+ */
+export interface PageFilter {
+    /** Natural-language description of what IS relevant to the extraction goal. Pages that do not match are dropped from downstream FHIR extraction. */
+    context: string;
+}

package/dist/cjs/api/resources/lang2Fhir/types/PageFilter.js

@@ -0,0 +1,3 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/api/resources/lang2Fhir/types/index.d.ts

@@ -1,4 +1,8 @@
 export * from "./CreateMultiResponse.js";
+export * from "./DocumentConfig.js";
+export * from "./DocumentMultiResponse.js";
 export * from "./FhirResource.js";
 export * from "./Lang2FhirUploadProfileResponse.js";
+export * from "./PageClassification.js";
+export * from "./PageFilter.js";
 export * from "./SearchResponse.js";

package/dist/cjs/api/resources/lang2Fhir/types/index.js

@@ -15,6 +15,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./CreateMultiResponse.js"), exports);
+__exportStar(require("./DocumentConfig.js"), exports);
+__exportStar(require("./DocumentMultiResponse.js"), exports);
 __exportStar(require("./FhirResource.js"), exports);
 __exportStar(require("./Lang2FhirUploadProfileResponse.js"), exports);
+__exportStar(require("./PageClassification.js"), exports);
+__exportStar(require("./PageFilter.js"), exports);
 __exportStar(require("./SearchResponse.js"), exports);

package/dist/cjs/api/resources/tools/client/requests/Lang2FhirAndSearchRequest.d.ts

@@ -21,8 +21,6 @@ export interface Lang2FhirAndSearchRequest {
     text: string;
     /** Patient ID to filter results */
     patient_id?: string;
-    /** Practitioner ID to filter results */
-    practitioner_id?: string;
     /** Maximum number of results to return */
     count?: number;
     /** FHIR provider ID - must be a valid UUID from existing FHIR providers. also supports provider by name (e.g. medplum) */

package/dist/cjs/version.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "12.4.0";
+export declare const SDK_VERSION = "13.0.0";

package/dist/cjs/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_VERSION = void 0;
-exports.SDK_VERSION = "12.4.0";
+exports.SDK_VERSION = "13.0.0";

package/dist/esm/BaseClient.mjs

@@ -6,8 +6,8 @@ export function normalizeClientOptions(options) {
     const headers = mergeHeaders({
         "X-Fern-Language": "JavaScript",
         "X-Fern-SDK-Name": "phenoml",
-        "X-Fern-SDK-Version": "12.4.0",
-        "User-Agent": "phenoml/12.4.0",
+        "X-Fern-SDK-Version": "13.0.0",
+        "User-Agent": "phenoml/13.0.0",
         "X-Fern-Runtime": core.RUNTIME.type,
         "X-Fern-Runtime-Version": core.RUNTIME.version,
     }, options === null || options === void 0 ? void 0 : options.headers);

package/dist/esm/api/resources/lang2Fhir/client/Client.d.mts

@@ -11,7 +11,9 @@ export declare class Lang2FhirClient {
     protected readonly _options: NormalizedClientOptionsWithAuth<Lang2FhirClient.Options>;
     constructor(options?: Lang2FhirClient.Options);
     /**
-     * Converts natural language text into a structured FHIR resource
+     * Converts natural language text into a structured FHIR resource.
+     *
+     * **Patient identifier handling.** When generating a `patient` (or `patient-canvas`) resource, US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
      *
      * @param {phenoml.lang2Fhir.CreateRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -34,6 +36,8 @@ export declare class Lang2FhirClient {
      * Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types from the text.
      * Resources are linked with proper references (e.g., Conditions reference the Patient).
      *
+     * **Patient identifier handling.** US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the bundle remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
+     *
      * @param {phenoml.lang2Fhir.CreateMultiRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
      *
@@ -101,7 +105,9 @@ export declare class Lang2FhirClient {
     uploadProfile(request: phenoml.lang2Fhir.ProfileUploadRequest, requestOptions?: Lang2FhirClient.RequestOptions): core.HttpResponsePromise<phenoml.lang2Fhir.Lang2FhirUploadProfileResponse>;
     private __uploadProfile;
     /**
-     * Extracts text from a document (PDF or image) and converts it into a structured FHIR resource
+     * Extracts text from a document (PDF or image) and converts it into a structured FHIR resource.
+     *
+     * **Patient identifier handling.** When generating a `patient` (or `patient-canvas`) resource, US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
      *
      * @param {phenoml.lang2Fhir.DocumentRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -125,6 +131,8 @@ export declare class Lang2FhirClient {
      * Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types.
      * Resources are linked with proper references (e.g., Conditions reference the Patient).
      *
+     * **Patient identifier handling.** US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the bundle remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
+     *
      * @param {phenoml.lang2Fhir.DocumentMultiRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
      *
@@ -139,6 +147,6 @@ export declare class Lang2FhirClient {
      *         content: "content"
      *     })
      */
-    extractMultipleFhirResourcesFromADocument(request: phenoml.lang2Fhir.DocumentMultiRequest, requestOptions?: Lang2FhirClient.RequestOptions): core.HttpResponsePromise<phenoml.lang2Fhir.CreateMultiResponse>;
+    extractMultipleFhirResourcesFromADocument(request: phenoml.lang2Fhir.DocumentMultiRequest, requestOptions?: Lang2FhirClient.RequestOptions): core.HttpResponsePromise<phenoml.lang2Fhir.DocumentMultiResponse>;
     private __extractMultipleFhirResourcesFromADocument;
 }

package/dist/esm/api/resources/lang2Fhir/client/Client.mjs

@@ -20,7 +20,9 @@ export class Lang2FhirClient {
         this._options = normalizeClientOptionsWithAuth(options);
     }
     /**
-     * Converts natural language text into a structured FHIR resource
+     * Converts natural language text into a structured FHIR resource.
+     *
+     * **Patient identifier handling.** When generating a `patient` (or `patient-canvas`) resource, US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
      *
      * @param {phenoml.lang2Fhir.CreateRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -85,6 +87,8 @@ export class Lang2FhirClient {
      * Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types from the text.
      * Resources are linked with proper references (e.g., Conditions reference the Patient).
      *
+     * **Patient identifier handling.** US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the bundle remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
+     *
      * @param {phenoml.lang2Fhir.CreateMultiRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
      *
@@ -288,7 +292,9 @@ export class Lang2FhirClient {
         });
     }
     /**
-     * Extracts text from a document (PDF or image) and converts it into a structured FHIR resource
+     * Extracts text from a document (PDF or image) and converts it into a structured FHIR resource.
+     *
+     * **Patient identifier handling.** When generating a `patient` (or `patient-canvas`) resource, US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
      *
      * @param {phenoml.lang2Fhir.DocumentRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -354,6 +360,8 @@ export class Lang2FhirClient {
      * Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types.
      * Resources are linked with proper references (e.g., Conditions reference the Patient).
      *
+     * **Patient identifier handling.** US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the bundle remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
+     *
      * @param {phenoml.lang2Fhir.DocumentMultiRequest} request
      * @param {Lang2FhirClient.RequestOptions} requestOptions - Request-specific configuration.
      *

package/dist/esm/api/resources/lang2Fhir/client/requests/CreateMultiRequest.d.mts

@@ -15,6 +15,8 @@ export interface CreateMultiRequest {
     implementation_guide?: string;
     /** Detection effort. 'standard' runs detection once, 'deep' runs detection multiple times for higher recall. */
     detection_effort?: CreateMultiRequest.DetectionEffort;
+    /** FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips. */
+    validation_method?: CreateMultiRequest.ValidationMethod;
 }
 export declare namespace CreateMultiRequest {
     /** Detection effort. 'standard' runs detection once, 'deep' runs detection multiple times for higher recall. */
@@ -23,4 +25,11 @@ export declare namespace CreateMultiRequest {
         readonly Deep: "deep";
     };
     type DetectionEffort = (typeof DetectionEffort)[keyof typeof DetectionEffort];
+    /** FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips. */
+    const ValidationMethod: {
+        readonly None: "none";
+        readonly Check: "check";
+        readonly Fix: "fix";
+    };
+    type ValidationMethod = (typeof ValidationMethod)[keyof typeof ValidationMethod];
 }

package/dist/esm/api/resources/lang2Fhir/client/requests/CreateMultiRequest.mjs

@@ -6,4 +6,10 @@ export var CreateMultiRequest;
         Standard: "standard",
         Deep: "deep",
     };
+    /** FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips. */
+    CreateMultiRequest.ValidationMethod = {
+        None: "none",
+        Check: "check",
+        Fix: "fix",
+    };
 })(CreateMultiRequest || (CreateMultiRequest = {}));

package/dist/esm/api/resources/lang2Fhir/client/requests/DocumentMultiRequest.d.mts

@@ -1,3 +1,4 @@
+import type * as phenoml from "../../../../index.mjs";
 /**
  * @example
  *     {
@@ -20,6 +21,9 @@ export interface DocumentMultiRequest {
     implementation_guide?: string;
     /** Detection effort. 'standard' runs detection once, 'deep' runs detection multiple times for higher recall. */
     detection_effort?: DocumentMultiRequest.DetectionEffort;
+    /** FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips. */
+    validation_method?: DocumentMultiRequest.ValidationMethod;
+    config?: phenoml.lang2Fhir.DocumentConfig;
 }
 export declare namespace DocumentMultiRequest {
     /** Detection effort. 'standard' runs detection once, 'deep' runs detection multiple times for higher recall. */
@@ -28,4 +32,11 @@ export declare namespace DocumentMultiRequest {
         readonly Deep: "deep";
     };
     type DetectionEffort = (typeof DetectionEffort)[keyof typeof DetectionEffort];
+    /** FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips. */
+    const ValidationMethod: {
+        readonly None: "none";
+        readonly Check: "check";
+        readonly Fix: "fix";
+    };
+    type ValidationMethod = (typeof ValidationMethod)[keyof typeof ValidationMethod];
 }

package/dist/esm/api/resources/lang2Fhir/client/requests/DocumentMultiRequest.mjs

@@ -6,4 +6,10 @@ export var DocumentMultiRequest;
         Standard: "standard",
         Deep: "deep",
     };
+    /** FHIR validation method to apply to the generated bundle. 'none' skips validation (default). 'check' runs the bundle through a FHIR structure validator and includes the results in the response. 'fix' runs validation and attempts to auto-correct errors using an LLM (up to 3 validation passes). The response includes results from each pass. Warning: 'fix' can significantly increase latency due to multiple LLM and validation round-trips. */
+    DocumentMultiRequest.ValidationMethod = {
+        None: "none",
+        Check: "check",
+        Fix: "fix",
+    };
 })(DocumentMultiRequest || (DocumentMultiRequest = {}));

package/dist/esm/api/resources/lang2Fhir/client/requests/DocumentRequest.d.mts

@@ -1,3 +1,4 @@
+import type * as phenoml from "../../../../index.mjs";
 /**
  * @example
  *     {
@@ -17,4 +18,5 @@ export interface DocumentRequest {
      * File type is auto-detected from content magic bytes.
      */
     content: string;
+    config?: phenoml.lang2Fhir.DocumentConfig;
 }

package/dist/esm/api/resources/lang2Fhir/types/CreateMultiResponse.d.mts

@@ -7,6 +7,8 @@ export interface CreateMultiResponse {
     bundle?: CreateMultiResponse.Bundle | undefined;
     /** Summary of extracted resources */
     resources?: CreateMultiResponse.Resources.Item[] | undefined;
+    /** FHIR validation results. Present when validation_method is 'check' or 'fix'. Contains results from each validation pass. For 'check', there is one pass. For 'fix', there may be up to 3 passes as the system attempts auto-correction. */
+    validation?: CreateMultiResponse.Validation | undefined;
 }
 export declare namespace CreateMultiResponse {
     /**
@@ -40,8 +42,71 @@ export declare namespace CreateMultiResponse {
             tempId?: string | undefined;
             /** FHIR resource type */
             resourceType?: string | undefined;
-            /** Text excerpt this resource was extracted from */
+            /** Context-enriched rewritten text excerpt for this resource */
             description?: string | undefined;
+            /** Verbatim text excerpt from the original clinical document */
+            originalText?: string | undefined;
+        }
+    }
+    /**
+     * FHIR validation results. Present when validation_method is 'check' or 'fix'. Contains results from each validation pass. For 'check', there is one pass. For 'fix', there may be up to 3 passes as the system attempts auto-correction.
+     */
+    interface Validation {
+        /** Results from each validation pass, in chronological order */
+        passes?: Validation.Passes.Item[] | undefined;
+        /** Whether validation errors were successfully fixed by the LLM. Always false for 'check' mode. For 'fix' mode, true if errors were resolved and the returned bundle is the corrected version. */
+        fixed?: boolean | undefined;
+        /** Total number of validation passes run (1 for check, 1-3 for fix) */
+        attempts?: number | undefined;
+        /** Human-readable summary of the validation outcome */
+        summary?: string | undefined;
+    }
+    namespace Validation {
+        type Passes = Passes.Item[];
+        namespace Passes {
+            interface Item {
+                /** Validation issues found in this pass */
+                issues?: Item.Issues.Item[] | undefined;
+                /** Validation statistics for this pass */
+                stats?: Item.Stats | undefined;
+            }
+            namespace Item {
+                type Issues = Issues.Item[];
+                namespace Issues {
+                    interface Item {
+                        /** Issue severity level */
+                        severity?: Item.Severity | undefined;
+                        /** Issue type code */
+                        code?: string | undefined;
+                        /** Human-readable description of the issue */
+                        diagnostics?: string | undefined;
+                        /** FHIRPath expression(s) pointing to the issue location */
+                        expression?: string[] | undefined;
+                        /** Validation phase that generated this issue */
+                        source?: string | undefined;
+                    }
+                    namespace Item {
+                        /** Issue severity level */
+                        const Severity: {
+                            readonly Fatal: "fatal";
+                            readonly Error: "error";
+                            readonly Warning: "warning";
+                            readonly Information: "information";
+                        };
+                        type Severity = (typeof Severity)[keyof typeof Severity];
+                    }
+                }
+                /**
+                 * Validation statistics for this pass
+                 */
+                interface Stats {
+                    resource_type?: string | undefined;
+                    profile_url?: string | undefined;
+                    is_custom_profile?: boolean | undefined;
+                    /** Validation duration in milliseconds */
+                    duration_ms?: number | undefined;
+                }
+            }
         }
     }
 }

package/dist/esm/api/resources/lang2Fhir/types/CreateMultiResponse.mjs

@@ -1,2 +1,26 @@
 // This file was auto-generated by Fern from our API Definition.
-export {};
+export var CreateMultiResponse;
+(function (CreateMultiResponse) {
+    let Validation;
+    (function (Validation) {
+        let Passes;
+        (function (Passes) {
+            let Item;
+            (function (Item_1) {
+                let Issues;
+                (function (Issues) {
+                    let Item;
+                    (function (Item) {
+                        /** Issue severity level */
+                        Item.Severity = {
+                            Fatal: "fatal",
+                            Error: "error",
+                            Warning: "warning",
+                            Information: "information",
+                        };
+                    })(Item = Issues.Item || (Issues.Item = {}));
+                })(Issues = Item_1.Issues || (Item_1.Issues = {}));
+            })(Item = Passes.Item || (Passes.Item = {}));
+        })(Passes = Validation.Passes || (Validation.Passes = {}));
+    })(Validation = CreateMultiResponse.Validation || (CreateMultiResponse.Validation = {}));
+})(CreateMultiResponse || (CreateMultiResponse = {}));

package/dist/esm/api/resources/lang2Fhir/types/DocumentConfig.d.mts

@@ -0,0 +1,7 @@
+import type * as phenoml from "../../../index.mjs";
+/**
+ * Optional processing configuration shared across document endpoints.
+ */
+export interface DocumentConfig {
+    page_filter?: phenoml.lang2Fhir.PageFilter | undefined;
+}

package/dist/esm/api/resources/lang2Fhir/types/DocumentConfig.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/lang2Fhir/types/DocumentMultiResponse.d.mts

@@ -0,0 +1,5 @@
+import type * as phenoml from "../../../index.mjs";
+export interface DocumentMultiResponse extends phenoml.lang2Fhir.CreateMultiResponse {
+    /** Per-page classifier decisions. Populated only when a page_filter was supplied in the request. Contains one entry per input page, including both kept and dropped pages. */
+    page_classifications?: phenoml.lang2Fhir.PageClassification[] | undefined;
+}

package/dist/esm/api/resources/lang2Fhir/types/DocumentMultiResponse.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/lang2Fhir/types/PageClassification.d.mts

@@ -0,0 +1,11 @@
+/**
+ * The classifier's decision for a single page of the input document.
+ */
+export interface PageClassification {
+    /** 1-indexed page number. */
+    page_number?: number | undefined;
+    /** Whether the page was kept (true) or dropped (false) from FHIR extraction. */
+    include?: boolean | undefined;
+    /** Short LLM-generated explanation of the decision. */
+    reason?: string | undefined;
+}

package/dist/esm/api/resources/lang2Fhir/types/PageClassification.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/lang2Fhir/types/PageFilter.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Configures per-page pre-extraction filtering. When set, each page of text extracted from the document is classified by an LLM, and pages classified as irrelevant to the supplied context are dropped before FHIR extraction.
+ */
+export interface PageFilter {
+    /** Natural-language description of what IS relevant to the extraction goal. Pages that do not match are dropped from downstream FHIR extraction. */
+    context: string;
+}

package/dist/esm/api/resources/lang2Fhir/types/PageFilter.mjs

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/esm/api/resources/lang2Fhir/types/index.d.mts

@@ -1,4 +1,8 @@
 export * from "./CreateMultiResponse.mjs";
+export * from "./DocumentConfig.mjs";
+export * from "./DocumentMultiResponse.mjs";
 export * from "./FhirResource.mjs";
 export * from "./Lang2FhirUploadProfileResponse.mjs";
+export * from "./PageClassification.mjs";
+export * from "./PageFilter.mjs";
 export * from "./SearchResponse.mjs";

package/dist/esm/api/resources/lang2Fhir/types/index.mjs

@@ -1,4 +1,8 @@
 export * from "./CreateMultiResponse.mjs";
+export * from "./DocumentConfig.mjs";
+export * from "./DocumentMultiResponse.mjs";
 export * from "./FhirResource.mjs";
 export * from "./Lang2FhirUploadProfileResponse.mjs";
+export * from "./PageClassification.mjs";
+export * from "./PageFilter.mjs";
 export * from "./SearchResponse.mjs";

package/dist/esm/api/resources/tools/client/requests/Lang2FhirAndSearchRequest.d.mts

@@ -21,8 +21,6 @@ export interface Lang2FhirAndSearchRequest {
     text: string;
     /** Patient ID to filter results */
     patient_id?: string;
-    /** Practitioner ID to filter results */
-    practitioner_id?: string;
     /** Maximum number of results to return */
     count?: number;
     /** FHIR provider ID - must be a valid UUID from existing FHIR providers. also supports provider by name (e.g. medplum) */

package/dist/esm/version.d.mts

@@ -1 +1 @@
-export declare const SDK_VERSION = "12.4.0";
+export declare const SDK_VERSION = "13.0.0";

package/dist/esm/version.mjs

@@ -1 +1 @@
-export const SDK_VERSION = "12.4.0";
+export const SDK_VERSION = "13.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "phenoml",
-    "version": "12.4.0",
+    "version": "13.0.0",
     "private": false,
     "repository": {
         "type": "git",

package/reference.md

@@ -3171,7 +3171,9 @@ await client.fhirProvider.removeAuthConfig("1716d214-de93-43a4-aa6b-a878d864e2ad
 <dl>
 <dd>
 
-Converts natural language text into a structured FHIR resource
+Converts natural language text into a structured FHIR resource.
+
+**Patient identifier handling.** When generating a `patient` (or `patient-canvas`) resource, US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
 </dd>
 </dl>
 </dd>
@@ -3241,6 +3243,8 @@ await client.lang2Fhir.create({
 Analyzes natural language text and extracts multiple FHIR resources, returning them as a transaction Bundle.
 Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types from the text.
 Resources are linked with proper references (e.g., Conditions reference the Patient).
+
+**Patient identifier handling.** US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the bundle remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
 </dd>
 </dl>
 </dd>
@@ -3451,7 +3455,9 @@ await client.lang2Fhir.uploadProfile({
 <dl>
 <dd>
 
-Extracts text from a document (PDF or image) and converts it into a structured FHIR resource
+Extracts text from a document (PDF or image) and converts it into a structured FHIR resource.
+
+**Patient identifier handling.** When generating a `patient` (or `patient-canvas`) resource, US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the resource remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
 </dd>
 </dl>
 </dd>
@@ -3506,7 +3512,7 @@ await client.lang2Fhir.document({
 </dl>
 </details>
 
-<details><summary><code>client.lang2Fhir.<a href="/src/api/resources/lang2Fhir/client/Client.ts">extractMultipleFhirResourcesFromADocument</a>({ ...params }) -> phenoml.CreateMultiResponse</code></summary>
+<details><summary><code>client.lang2Fhir.<a href="/src/api/resources/lang2Fhir/client/Client.ts">extractMultipleFhirResourcesFromADocument</a>({ ...params }) -> phenoml.DocumentMultiResponse</code></summary>
 <dl>
 <dd>
 
@@ -3522,6 +3528,8 @@ Extracts text from a document (PDF or image) and converts it into multiple FHIR
 returned as a transaction Bundle. Combines document text extraction with multi-resource detection.
 Automatically detects Patient, Condition, MedicationRequest, Observation, and other resource types.
 Resources are linked with proper references (e.g., Conditions reference the Patient).
+
+**Patient identifier handling.** US Core requires `Patient.identifier` (a business identifier such as an MRN). When the source text contains an identifier, it is extracted with an appropriate URI system. When the source text does not contain a detectable identifier, a synthetic one is generated with `system: "urn:phenoml:lang2fhir-generated-id"` and a UUID `value` so the bundle remains FHIR-valid and US Core conformant. Callers who need a tenant-specific namespace should rewrite the synthetic system after extraction.
 </dd>
 </dl>
 </dd>