@roarkanalytics/sdk 3.16.0 → 3.18.0

package/src/resources/simulation-run-plan.ts

@@ -138,6 +138,34 @@ export namespace SimulationRunPlanCreateResponse {
        */
       agentEndpoints: Array<RunPlan.AgentEndpoint>;
 
+      /**
+       * The value of `comparisonProperty` every other value is measured against, such as
+       * `NONE` for `BACKGROUND_NOISE`. `null` when no comparison is declared, or when
+       * the property has no obvious norm and none was chosen.
+       */
+      comparisonBaseline: string | null;
+
+      /**
+       * The property of the caller or their surroundings this plan investigates, such as
+       * `BACKGROUND_NOISE`. The run report compares the arms on it. `null` means the
+       * report works out for itself which property varies.
+       */
+      comparisonProperty:
+        | 'ACCENT'
+        | 'AGE'
+        | 'BACKGROUND_NOISE'
+        | 'BACKGROUND_NOISE_VOLUME'
+        | 'BASE_EMOTION'
+        | 'CONFIRMATION_STYLE'
+        | 'GENDER'
+        | 'INTENT_CLARITY'
+        | 'LANGUAGE'
+        | 'MEMORY_RELIABILITY'
+        | 'RESPONSE_TIMING'
+        | 'SPEECH_CLARITY'
+        | 'SPEECH_PACE'
+        | null;
+
       /**
        * When the run plan was created
        */
@@ -228,13 +256,6 @@ export namespace SimulationRunPlanCreateResponse {
        */
       personas: Array<RunPlan.Persona>;
 
-      /**
-       * The flow variant this plan's runs are measured against: the run report shows
-       * every other flow variant in the run as a difference from it. `null` means the
-       * plan declares no experiment.
-       */
-      referenceCustomerFlowVariantId: string | null;
-
       /**
        * @deprecated Deprecated: use `flows` instead. Scenarios included in this run
        * plan.
@@ -433,6 +454,34 @@ export namespace SimulationRunPlanUpdateResponse {
      */
     agentEndpoints: Array<Data.AgentEndpoint>;
 
+    /**
+     * The value of `comparisonProperty` every other value is measured against, such as
+     * `NONE` for `BACKGROUND_NOISE`. `null` when no comparison is declared, or when
+     * the property has no obvious norm and none was chosen.
+     */
+    comparisonBaseline: string | null;
+
+    /**
+     * The property of the caller or their surroundings this plan investigates, such as
+     * `BACKGROUND_NOISE`. The run report compares the arms on it. `null` means the
+     * report works out for itself which property varies.
+     */
+    comparisonProperty:
+      | 'ACCENT'
+      | 'AGE'
+      | 'BACKGROUND_NOISE'
+      | 'BACKGROUND_NOISE_VOLUME'
+      | 'BASE_EMOTION'
+      | 'CONFIRMATION_STYLE'
+      | 'GENDER'
+      | 'INTENT_CLARITY'
+      | 'LANGUAGE'
+      | 'MEMORY_RELIABILITY'
+      | 'RESPONSE_TIMING'
+      | 'SPEECH_CLARITY'
+      | 'SPEECH_PACE'
+      | null;
+
     /**
      * When the run plan was created
      */
@@ -523,13 +572,6 @@ export namespace SimulationRunPlanUpdateResponse {
      */
     personas: Array<Data.Persona>;
 
-    /**
-     * The flow variant this plan's runs are measured against: the run report shows
-     * every other flow variant in the run as a difference from it. `null` means the
-     * plan declares no experiment.
-     */
-    referenceCustomerFlowVariantId: string | null;
-
     /**
      * @deprecated Deprecated: use `flows` instead. Scenarios included in this run
      * plan.
@@ -692,6 +734,34 @@ export namespace SimulationRunPlanListResponse {
      */
     agentEndpoints: Array<Data.AgentEndpoint>;
 
+    /**
+     * The value of `comparisonProperty` every other value is measured against, such as
+     * `NONE` for `BACKGROUND_NOISE`. `null` when no comparison is declared, or when
+     * the property has no obvious norm and none was chosen.
+     */
+    comparisonBaseline: string | null;
+
+    /**
+     * The property of the caller or their surroundings this plan investigates, such as
+     * `BACKGROUND_NOISE`. The run report compares the arms on it. `null` means the
+     * report works out for itself which property varies.
+     */
+    comparisonProperty:
+      | 'ACCENT'
+      | 'AGE'
+      | 'BACKGROUND_NOISE'
+      | 'BACKGROUND_NOISE_VOLUME'
+      | 'BASE_EMOTION'
+      | 'CONFIRMATION_STYLE'
+      | 'GENDER'
+      | 'INTENT_CLARITY'
+      | 'LANGUAGE'
+      | 'MEMORY_RELIABILITY'
+      | 'RESPONSE_TIMING'
+      | 'SPEECH_CLARITY'
+      | 'SPEECH_PACE'
+      | null;
+
     /**
      * When the run plan was created
      */
@@ -782,13 +852,6 @@ export namespace SimulationRunPlanListResponse {
      */
     personas: Array<Data.Persona>;
 
-    /**
-     * The flow variant this plan's runs are measured against: the run report shows
-     * every other flow variant in the run as a difference from it. `null` means the
-     * plan declares no experiment.
-     */
-    referenceCustomerFlowVariantId: string | null;
-
     /**
      * @deprecated Deprecated: use `flows` instead. Scenarios included in this run
      * plan.
@@ -979,6 +1042,34 @@ export namespace SimulationRunPlanGetByIDResponse {
      */
     agentEndpoints: Array<Data.AgentEndpoint>;
 
+    /**
+     * The value of `comparisonProperty` every other value is measured against, such as
+     * `NONE` for `BACKGROUND_NOISE`. `null` when no comparison is declared, or when
+     * the property has no obvious norm and none was chosen.
+     */
+    comparisonBaseline: string | null;
+
+    /**
+     * The property of the caller or their surroundings this plan investigates, such as
+     * `BACKGROUND_NOISE`. The run report compares the arms on it. `null` means the
+     * report works out for itself which property varies.
+     */
+    comparisonProperty:
+      | 'ACCENT'
+      | 'AGE'
+      | 'BACKGROUND_NOISE'
+      | 'BACKGROUND_NOISE_VOLUME'
+      | 'BASE_EMOTION'
+      | 'CONFIRMATION_STYLE'
+      | 'GENDER'
+      | 'INTENT_CLARITY'
+      | 'LANGUAGE'
+      | 'MEMORY_RELIABILITY'
+      | 'RESPONSE_TIMING'
+      | 'SPEECH_CLARITY'
+      | 'SPEECH_PACE'
+      | null;
+
     /**
      * When the run plan was created
      */
@@ -1069,13 +1160,6 @@ export namespace SimulationRunPlanGetByIDResponse {
      */
     personas: Array<Data.Persona>;
 
-    /**
-     * The flow variant this plan's runs are measured against: the run report shows
-     * every other flow variant in the run as a difference from it. `null` means the
-     * plan declares no experiment.
-     */
-    referenceCustomerFlowVariantId: string | null;
-
     /**
      * @deprecated Deprecated: use `flows` instead. Scenarios included in this run
      * plan.
@@ -1248,6 +1332,60 @@ export interface SimulationRunPlanCreateParams {
    */
   autoRun?: boolean;
 
+  /**
+   * The value of `comparisonProperty` every other value is measured against, for
+   * example `NONE` for `BACKGROUND_NOISE` or `NORMAL` for `SPEECH_PACE`. Must be a
+   * value that property can take.
+   *
+   * Stored rather than assumed, so the report can say "compared against US accent"
+   * instead of implying Roark decided which value is normal. Most properties have an
+   * obvious baseline and the dashboard prefills it; `GENDER` has none, so choose the
+   * one you are testing against.
+   */
+  comparisonBaseline?: string | null;
+
+  /**
+   * The property this run plan investigates: the one thing its arms differ by.
+   *
+   * Set it and the run report compares the arms on that property, so a run answers
+   * "what did background noise cost" rather than just "what did each arm score".
+   * Every value is a field already recorded on each call, so the report can label an
+   * arm `CRYING_BABY` rather than repeating a flow variant's title.
+   *
+   * Omit it and the report still compares when it can: it detects which property
+   * varies across the arms. Setting it is what tells the written summary what you
+   * were trying to find out, which detection cannot infer.
+   */
+  comparisonProperty?:
+    | 'ACCENT'
+    | 'AGE'
+    | 'BACKGROUND_NOISE'
+    | 'BACKGROUND_NOISE_VOLUME'
+    | 'BASE_EMOTION'
+    | 'CONFIRMATION_STYLE'
+    | 'GENDER'
+    | 'INTENT_CLARITY'
+    | 'LANGUAGE'
+    | 'MEMORY_RELIABILITY'
+    | 'RESPONSE_TIMING'
+    | 'SPEECH_CLARITY'
+    | 'SPEECH_PACE'
+    | null;
+
+  /**
+   * Which values of `comparisonProperty` to run. This is what the plan costs: the
+   * flow is attached once per value, so ten values is ten times the calls of one.
+   *
+   * Omit it to run every value the property has, which for `ACCENT` is more than
+   * twenty. Send a subset to narrow the sweep, for example three accents you
+   * actually serve. A `comparisonBaseline` outside this set is rejected, because it
+   * would anchor every difference to an arm the run never made.
+   *
+   * Not stored as a field: the arms are the values. Reading the plan back returns
+   * them as its flow attachments.
+   */
+  comparisonValues?: Array<string>;
+
   /**
    * Description of the run plan
    */
@@ -1337,21 +1475,6 @@ export interface SimulationRunPlanCreateParams {
    */
   personas?: Array<SimulationRunPlanCreateParams.Persona>;
 
-  /**
-   * Name one flow variant as this run plan's REFERENCE arm.
-   *
-   * Every other flow variant the plan runs is then reported as a difference from
-   * this one, which is how a run answers "what did the change cost" rather than just
-   * "what did it score". The usual shape is one flow whose default variant is the
-   * control (say, a silent environment) plus one edge-case variant per condition
-   * under test.
-   *
-   * The variant must be one this plan actually runs: it has to belong to a flow in
-   * `flows`, and that flow's variant selection has to resolve to it. Omit or set
-   * null for a plan that is a general health check rather than an experiment.
-   */
-  referenceCustomerFlowVariantId?: string | null;
-
   /**
    * @deprecated Deprecated: use `flows` instead. Scenarios to include in this run
    * plan. The same scenario ID can appear multiple times with different variables.
@@ -1504,6 +1627,55 @@ export interface SimulationRunPlanUpdateParams {
    */
   agentEndpoints?: Array<SimulationRunPlanUpdateParams.AgentEndpoint>;
 
+  /**
+   * The value every other value is measured against. See `POST /v1/simulation/plan`.
+   *
+   * A real value cannot be sent on its own: the property it belongs to decides which
+   * values are legal, and an omitted property means "leave unchanged", which this
+   * endpoint cannot check a baseline against. Send `comparisonProperty` with it, or
+   * get a `400`.
+   *
+   * `null` on its own IS allowed, and clears just the baseline while leaving the
+   * property set. Nothing needs validating when clearing, and a property with no
+   * baseline is a real state: the report falls back to that property's own norm, and
+   * `GENDER` has no norm to fall back to.
+   */
+  comparisonBaseline?: string | null;
+
+  /**
+   * The property this plan investigates. Send `null` to clear the comparison; omit
+   * the field to leave it unchanged. See `POST /v1/simulation/plan`.
+   *
+   * The pair moves together. Sending `comparisonProperty` also sets
+   * `comparisonBaseline` to whatever this request carries, or to `null` if it
+   * carries none, because a baseline is a value of one specific property and keeping
+   * the old one would store a pair that is not valid.
+   */
+  comparisonProperty?:
+    | 'ACCENT'
+    | 'AGE'
+    | 'BACKGROUND_NOISE'
+    | 'BACKGROUND_NOISE_VOLUME'
+    | 'BASE_EMOTION'
+    | 'CONFIRMATION_STYLE'
+    | 'GENDER'
+    | 'INTENT_CLARITY'
+    | 'LANGUAGE'
+    | 'MEMORY_RELIABILITY'
+    | 'RESPONSE_TIMING'
+    | 'SPEECH_CLARITY'
+    | 'SPEECH_PACE'
+    | null;
+
+  /**
+   * Which values of `comparisonProperty` to run. See `POST /v1/simulation/plan`.
+   *
+   * Omitting it keeps the arms the plan already has, so an edit that only renames
+   * the plan never widens a sweep you deliberately narrowed, and never multiplies
+   * what it costs.
+   */
+  comparisonValues?: Array<string>;
+
   /**
    * Description of the run plan
    */
@@ -1594,13 +1766,6 @@ export interface SimulationRunPlanUpdateParams {
    */
   personas?: Array<SimulationRunPlanUpdateParams.Persona>;
 
-  /**
-   * The reference arm every other flow variant in a run is reported as a difference
-   * from. Send `null` to clear it; omit the field to leave it unchanged. See
-   * `POST /v1/simulation/plan`.
-   */
-  referenceCustomerFlowVariantId?: string | null;
-
   /**
    * @deprecated Deprecated: use `flows` instead. Replaces the scenarios on this run
    * plan. Omit to leave them unchanged; send an empty array to detach them all,

package/src/resources/simulation-template.ts

@@ -94,6 +94,20 @@ export namespace SimulationTemplateListResponse {
      */
     slug: string;
 
+    /**
+     * Set when this template is a property sweep: it runs ONE flow once per value of a
+     * single caller or environment property, and the report compares the values
+     * against `baseline`.
+     *
+     * This is what decides the size of the run. A sweep attaches the flow once per
+     * entry in `values`, so a plan built from it costs `values.length` times the calls
+     * a normal template would, before iterations. Read it before creating a plan you
+     * have to pay for.
+     *
+     * `null` for every other template.
+     */
+    sweep: Data.Sweep | null;
+
     /**
      * The Pass/Fail checks this template attaches alongside its metrics.
      */
@@ -182,6 +196,50 @@ export namespace SimulationTemplateListResponse {
       slug: string;
     }
 
+    /**
+     * Set when this template is a property sweep: it runs ONE flow once per value of a
+     * single caller or environment property, and the report compares the values
+     * against `baseline`.
+     *
+     * This is what decides the size of the run. A sweep attaches the flow once per
+     * entry in `values`, so a plan built from it costs `values.length` times the calls
+     * a normal template would, before iterations. Read it before creating a plan you
+     * have to pay for.
+     *
+     * `null` for every other template.
+     */
+    export interface Sweep {
+      /**
+       * The value the others are measured against, resolved to what a plan built from
+       * this template will actually record. `null` when the property has no obvious
+       * norm, and the report then compares against the best-performing value instead.
+       */
+      baseline: string | null;
+
+      /**
+       * The property this template varies across the flow it runs.
+       */
+      property:
+        | 'ACCENT'
+        | 'AGE'
+        | 'BACKGROUND_NOISE'
+        | 'BACKGROUND_NOISE_VOLUME'
+        | 'BASE_EMOTION'
+        | 'CONFIRMATION_STYLE'
+        | 'GENDER'
+        | 'INTENT_CLARITY'
+        | 'LANGUAGE'
+        | 'MEMORY_RELIABILITY'
+        | 'RESPONSE_TIMING'
+        | 'SPEECH_CLARITY'
+        | 'SPEECH_PACE';
+
+      /**
+       * Every value the template sweeps, in the order the plan attaches them.
+       */
+      values: Array<string>;
+    }
+
     export interface Threshold {
       /**
        * Metric definition ID

package/src/resources/simulation.ts

@@ -176,6 +176,60 @@ export declare namespace SimulationRunParams {
        */
       metrics: Array<Plan.Metric>;
 
+      /**
+       * The value of `comparisonProperty` every other value is measured against, for
+       * example `NONE` for `BACKGROUND_NOISE` or `NORMAL` for `SPEECH_PACE`. Must be a
+       * value that property can take.
+       *
+       * Stored rather than assumed, so the report can say "compared against US accent"
+       * instead of implying Roark decided which value is normal. Most properties have an
+       * obvious baseline and the dashboard prefills it; `GENDER` has none, so choose the
+       * one you are testing against.
+       */
+      comparisonBaseline?: string | null;
+
+      /**
+       * The property this run plan investigates: the one thing its arms differ by.
+       *
+       * Set it and the run report compares the arms on that property, so a run answers
+       * "what did background noise cost" rather than just "what did each arm score".
+       * Every value is a field already recorded on each call, so the report can label an
+       * arm `CRYING_BABY` rather than repeating a flow variant's title.
+       *
+       * Omit it and the report still compares when it can: it detects which property
+       * varies across the arms. Setting it is what tells the written summary what you
+       * were trying to find out, which detection cannot infer.
+       */
+      comparisonProperty?:
+        | 'ACCENT'
+        | 'AGE'
+        | 'BACKGROUND_NOISE'
+        | 'BACKGROUND_NOISE_VOLUME'
+        | 'BASE_EMOTION'
+        | 'CONFIRMATION_STYLE'
+        | 'GENDER'
+        | 'INTENT_CLARITY'
+        | 'LANGUAGE'
+        | 'MEMORY_RELIABILITY'
+        | 'RESPONSE_TIMING'
+        | 'SPEECH_CLARITY'
+        | 'SPEECH_PACE'
+        | null;
+
+      /**
+       * Which values of `comparisonProperty` to run. This is what the plan costs: the
+       * flow is attached once per value, so ten values is ten times the calls of one.
+       *
+       * Omit it to run every value the property has, which for `ACCENT` is more than
+       * twenty. Send a subset to narrow the sweep, for example three accents you
+       * actually serve. A `comparisonBaseline` outside this set is rejected, because it
+       * would anchor every difference to an arm the run never made.
+       *
+       * Not stored as a field: the arms are the values. Reading the plan back returns
+       * them as its flow attachments.
+       */
+      comparisonValues?: Array<string>;
+
       /**
        * Description of the run plan
        */
@@ -271,21 +325,6 @@ export declare namespace SimulationRunParams {
        */
       personas?: Array<Plan.Persona>;
 
-      /**
-       * Name one flow variant as this run plan's REFERENCE arm.
-       *
-       * Every other flow variant the plan runs is then reported as a difference from
-       * this one, which is how a run answers "what did the change cost" rather than just
-       * "what did it score". The usual shape is one flow whose default variant is the
-       * control (say, a silent environment) plus one edge-case variant per condition
-       * under test.
-       *
-       * The variant must be one this plan actually runs: it has to belong to a flow in
-       * `flows`, and that flow's variant selection has to resolve to it. Omit or set
-       * null for a plan that is a general health check rather than an experiment.
-       */
-      referenceCustomerFlowVariantId?: string | null;
-
       /**
        * @deprecated Deprecated: use `flows` instead. Scenarios to include in this run
        * plan. The same scenario ID can appear multiple times with different variables.

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '3.16.0'; // x-release-please-version
+export const VERSION = '3.18.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "3.16.0";
+export declare const VERSION = "3.18.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "3.16.0";
+export declare const VERSION = "3.18.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '3.16.0'; // x-release-please-version
+exports.VERSION = '3.18.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '3.16.0'; // x-release-please-version
+export const VERSION = '3.18.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map