Function findRelevantDocumentsWithLLM

Parameters

• options: {
      additionalInstructions?: string | null;
      auditQuestionId?: AuditQuestionId;
      enableClassifyRetrievalMode?: boolean;
      enableDocumentCatalogue?: boolean;
      enableMetadataAwareGate?: boolean;
      enableTimeFilteringInChartReview?: boolean;
      expandedSteps?: string;
      model: ChatOpenAI;
      patientCharts?: {
          circle_metadata:
              | {
                  admittedAt: string
                  | null;
                  capturedAt: string;
                  dischargedAt: string | null;
                  entityId: number;
                  episodeEnd?: string | null;
                  episodeStart?: string | null;
                  levelOfCareName?: string | null;
                  patientId: PatientId;
                  patientName: string;
                  programEnd?: string | null;
                  programName?: string | null;
                  programStart?: string | null;
                  proxy?: {
                      attachmentFailedAttempts?: number;
                      attachmentId: string | null;
                      attachmentRetryAfter?: string;
                      attachmentSkipReason?:
                          | "not_pdf"
                          | "hash_mismatch"
                          | "metadata_invalid"
                          | "too_large"
                          | "extraction_failed_repeatedly"
                          | "not_listed"
                          | "vendor_rejected"
                          | null;
                      businessId: string
                      | null;
                      connector: string;
                      contentHash: string | null;
                      contentHashStoredAt?: string | null;
                      embedFailedAt?: string;
                      embedFailedAttempts?: number;
                      label: string | null;
                      schemaVersion: string;
                      sourceEpisodeId?: string | null;
                      table: string;
                  };
                  urLevelOfCareName?: string
                  | null;
              }
              | null;
          created_at: DbDate;
          created_by: string & { __brand: "UserId" }
          | null;
          embedding_count: string | null;
          embedding_err_msg: string | null;
          embedding_status:
              | "parse"
              | "pending"
              | "completed"
              | "processing"
              | "failed"
              | "extract"
              | null;
          entity_id: number & { __brand: "EntityId" }
          | null;
          extend_content_hash: string | null;
          extend_run_id: string & { __brand: "ExtendRunId" } | null;
          extend_source: "proxy" | "insync-rpa" | "v2-patient-charts" | null;
          extended_at: string & { __brand: "DbDate" } | null;
          external_document_created_at: string & { __brand: "DbDate" } | null;
          external_document_id: string | null;
          external_document_type:
              | "kipu_evaluation"
              | "kipu_consent_form"
              | "kipu_ciwa_ar"
              | "kipu_ciwa_b"
              | "kipu_group_session"
              | "lightningstep_formdata"
              | "lightningstep_txplan"
              | "kipu_vital_signs"
              | "kipu_orthostatic_vital_signs"
              | "kipu_patient_orders"
              | "kipu_glucose_logs"
              | "kipu_program_history"
              | "kipu_diagnosis_history"
              | "kipu_appointment"
              | "lightningstep_admissions"
              | "kipu_episode_outcome"
              | "sunwave_form"
              | "sunwave_diagnosis"
              | "sunwave_group_note"
              | "sunwave_program"
              | "sunwave_lab_result"
              | "sunwave_assessment"
              | "emr_insurance_information"
              | "insync_episode_summary"
              | "insync_condition"
              | "insync_vital_signs"
              | "insync_lab_result"
              | "insync_observation"
              | "insync_allergy"
              | "insync_immunization"
              | "insync_medication_request"
              | "insync_diagnostic_report"
              | "insync_procedure"
              | "insync_rpa_locadtr"
              | "insync_rpa_treatment_plan"
              | "insync_rpa_biopsychosocial"
              | "synthetic_biopsychosocial"
              | "synthetic_asam"
              | "synthetic_consent"
              | "synthetic_nursing_intake"
              | "synthetic_diagnosis"
              | "synthetic_treatment_plan"
              | "synthetic_group_note"
              | "synthetic_progress_note"
              | "synthetic_ur_review"
              | "synthetic_discharge_summary"
              | "insync_rpa_encounter_note"
              | "insync_rpa_consent_form"
              | "insync_rpa_lab_result"
              | "insync_rpa_insurance"
              | "insync_rpa_document"
              | null;
          external_document_updated_at: string & { __brand: "DbDate" }
          | null;
          file_name: string | null;
          file_type: "patient_chart" | "generated_form" | "emr_document" | null;
          file_url: string | null;
          id: PatientChartId;
          integration_id: string & { __brand: "IntegrationId" } | null;
          is_ready: boolean | null;
          packet_role: "standalone" | "packet" | "piece";
          packet_section_index: number | null;
          page_end: number | null;
          page_start: number | null;
          parent_patient_chart_id: string & { __brand: "PatientChartId" } | null;
          patient_id: string & { __brand: "PatientId" } | null;
          raw_document: unknown;
          run_id: string | null;
          sources: unknown;
          treatment_episode_id: string & { __brand: "TreatmentEpisodeId" } | null;
          updated_at: string & { __brand: "DbDate" } | null;
      }[];
      patientId: PatientId;
      question: string;
      questionType?: "pass_fail"
      | "summary";
      referenceInstant?: Date;
      retrievalFloor?: Date;
      reviewCriteriaInstructions?: string | null;
      searchHints?: string[] | null;
      timeZone?: string | null;
      treatmentEpisodeId?: TreatmentEpisodeId;
  }

  • OptionaladditionalInstructions?: string | null

  • OptionalauditQuestionId?: AuditQuestionId

  • OptionalenableClassifyRetrievalMode?: boolean

  • OptionalenableDocumentCatalogue?: boolean

    Render the candidates as a CATALOGUE — grouped by type, then by name, each name's documents indexed by week with its most recent named outright — instead of one line per document.

    A flat listing repeats every document's type and tags on every row, so a few hundred documents is mostly duplicated strings and the model still does its own counting. Off by default so the two can be compared on the same questions.

  • OptionalenableMetadataAwareGate?: boolean

    When set, enrich the document listing the LLM picks from with each chart's circle_metadata (level-of-care / program-stay window) so the model selects with clinical context in view. ENRICHMENT only — never a hard narrow: the candidate set is unchanged, so it can't starve retrieval of the document holding the answer.

  • OptionalenableTimeFilteringInChartReview?: boolean

  • OptionalexpandedSteps?: string

  • model: ChatOpenAI

  • OptionalpatientCharts?: {
        circle_metadata:
            | {
                admittedAt: string
                | null;
                capturedAt: string;
                dischargedAt: string | null;
                entityId: number;
                episodeEnd?: string | null;
                episodeStart?: string | null;
                levelOfCareName?: string | null;
                patientId: PatientId;
                patientName: string;
                programEnd?: string | null;
                programName?: string | null;
                programStart?: string | null;
                proxy?: {
                    attachmentFailedAttempts?: number;
                    attachmentId: string | null;
                    attachmentRetryAfter?: string;
                    attachmentSkipReason?:
                        | "not_pdf"
                        | "hash_mismatch"
                        | "metadata_invalid"
                        | "too_large"
                        | "extraction_failed_repeatedly"
                        | "not_listed"
                        | "vendor_rejected"
                        | null;
                    businessId: string
                    | null;
                    connector: string;
                    contentHash: string | null;
                    contentHashStoredAt?: string | null;
                    embedFailedAt?: string;
                    embedFailedAttempts?: number;
                    label: string | null;
                    schemaVersion: string;
                    sourceEpisodeId?: string | null;
                    table: string;
                };
                urLevelOfCareName?: string
                | null;
            }
            | null;
        created_at: DbDate;
        created_by: string & { __brand: "UserId" }
        | null;
        embedding_count: string | null;
        embedding_err_msg: string | null;
        embedding_status:
            | "parse"
            | "pending"
            | "completed"
            | "processing"
            | "failed"
            | "extract"
            | null;
        entity_id: number & { __brand: "EntityId" }
        | null;
        extend_content_hash: string | null;
        extend_run_id: string & { __brand: "ExtendRunId" } | null;
        extend_source: "proxy" | "insync-rpa" | "v2-patient-charts" | null;
        extended_at: string & { __brand: "DbDate" } | null;
        external_document_created_at: string & { __brand: "DbDate" } | null;
        external_document_id: string | null;
        external_document_type:
            | "kipu_evaluation"
            | "kipu_consent_form"
            | "kipu_ciwa_ar"
            | "kipu_ciwa_b"
            | "kipu_group_session"
            | "lightningstep_formdata"
            | "lightningstep_txplan"
            | "kipu_vital_signs"
            | "kipu_orthostatic_vital_signs"
            | "kipu_patient_orders"
            | "kipu_glucose_logs"
            | "kipu_program_history"
            | "kipu_diagnosis_history"
            | "kipu_appointment"
            | "lightningstep_admissions"
            | "kipu_episode_outcome"
            | "sunwave_form"
            | "sunwave_diagnosis"
            | "sunwave_group_note"
            | "sunwave_program"
            | "sunwave_lab_result"
            | "sunwave_assessment"
            | "emr_insurance_information"
            | "insync_episode_summary"
            | "insync_condition"
            | "insync_vital_signs"
            | "insync_lab_result"
            | "insync_observation"
            | "insync_allergy"
            | "insync_immunization"
            | "insync_medication_request"
            | "insync_diagnostic_report"
            | "insync_procedure"
            | "insync_rpa_locadtr"
            | "insync_rpa_treatment_plan"
            | "insync_rpa_biopsychosocial"
            | "synthetic_biopsychosocial"
            | "synthetic_asam"
            | "synthetic_consent"
            | "synthetic_nursing_intake"
            | "synthetic_diagnosis"
            | "synthetic_treatment_plan"
            | "synthetic_group_note"
            | "synthetic_progress_note"
            | "synthetic_ur_review"
            | "synthetic_discharge_summary"
            | "insync_rpa_encounter_note"
            | "insync_rpa_consent_form"
            | "insync_rpa_lab_result"
            | "insync_rpa_insurance"
            | "insync_rpa_document"
            | null;
        external_document_updated_at: string & { __brand: "DbDate" }
        | null;
        file_name: string | null;
        file_type: "patient_chart" | "generated_form" | "emr_document" | null;
        file_url: string | null;
        id: PatientChartId;
        integration_id: string & { __brand: "IntegrationId" } | null;
        is_ready: boolean | null;
        packet_role: "standalone" | "packet" | "piece";
        packet_section_index: number | null;
        page_end: number | null;
        page_start: number | null;
        parent_patient_chart_id: string & { __brand: "PatientChartId" } | null;
        patient_id: string & { __brand: "PatientId" } | null;
        raw_document: unknown;
        run_id: string | null;
        sources: unknown;
        treatment_episode_id: string & { __brand: "TreatmentEpisodeId" } | null;
        updated_at: string & { __brand: "DbDate" } | null;
    }[]

    Optional pre-fetched patient charts. When provided, skip the per-question DB fetch and filter in memory by the question's time filter. Caller is responsible for passing the full unfiltered set (or a superset covering the widest expected time window).

  • patientId: PatientId

  • question: string

  • OptionalquestionType?: "pass_fail" | "summary"

  • OptionalreferenceInstant?: Date

    The run's shared reference instant; anchors the time filter.

  • OptionalretrievalFloor?: Date

    Earliest day any criterion of a compound question needs. Only ever widens the cutoff.

  • OptionalreviewCriteriaInstructions?: string | null

    Template review criteria — appended to the prompt so the LLM selects documents that matter for the rubric.

  • OptionalsearchHints?: string[] | null

    Optional title/type synonyms from question decomposition.

  • OptionaltimeZone?: string | null

    Facility IANA zone for rendering document dates; resolved (with fallback) internally.

  • OptionaltreatmentEpisodeId?: TreatmentEpisodeId

    When set, the chart fetch is scoped to this treatment episode — the candidate set the LLM picks from contains ONLY that episode's charts, so cross-episode documents can never be considered. Re-applied in memory to a provided patientCharts set as well.