@kortexya/reasoninglayer 0.20.0 → 0.21.0

package/dist/index.d.cts

@@ -109,7 +109,7 @@ type JsonValue$1 = string | number | boolean | null | JsonValue$1[] | object;
  * This is the single source of truth for the version constant.
  * The `scripts/release.sh` script updates this value alongside `package.json`.
  */
-declare const SDK_VERSION = "0.20.0";
+declare const SDK_VERSION = "0.21.0";
 /**
  * Configuration for the Reasoning Layer client.
  *
@@ -11812,6 +11812,31 @@ interface PreferenceDto$1 {
     /** Preference value. */
     value: string;
 }
+/**
+ * A soft preference: bias the optimizer toward (or against) assigning
+ * `agent_id` to cell `(day, shift)`.
+ *
+ * `score` contributes to the objective when the cell is assigned in
+ * the chosen schedule.  Positive values pull the optimizer toward
+ * the cell; negative values push it away.  Preferences targeting a
+ * pinned cell, an agent with a day-off on `day`, or an agent
+ * otherwise blocked from the slot are silently ignored — the
+ * corresponding decision edge does not exist in the reduced flow
+ * graph.
+ */
+interface PreferenceInput {
+    agent_id: string;
+    /** @min 0 */
+    day: number;
+    /**
+     * Score contributed by this assignment to the optimizer's
+     * objective.  Positive = preferred, negative = avoided.
+     * @format int64
+     */
+    score: number;
+    /** @min 0 */
+    shift: number;
+}
 /** Prediction result for a single term */
 interface PreferencePrediction$1 {
     /** @format double */
@@ -13741,6 +13766,56 @@ interface SchedulingFeasibilityResponse$1 {
     /** Top-level request status. */
     status: SchedulingStatusDto;
 }
+/**
+ * Request body for `POST /api/v1/scheduling/optimize`.
+ *
+ * Same hard-constraint shape as
+ * [`SchedulingFeasibilityRequest`], plus a list of soft
+ * `preferences`.  The engine returns the per-cell envelope across
+ * the space of **optimal** schedules under the supplied
+ * preferences.
+ */
+interface SchedulingOptimizeRequest$1 {
+    agents: AgentInput[];
+    /** @min 0 */
+    days: number;
+    demands: ShiftDemandInput[];
+    pins?: PinInput[];
+    /**
+     * Soft preferences applied to the objective.  Empty = unweighted
+     * (every feasible schedule is "optimal").
+     */
+    preferences?: PreferenceInput[];
+    /** @min 0 */
+    shifts_per_day: number;
+}
+/**
+ * Response to [`SchedulingOptimizeRequest`].
+ *
+ * The per-cell `assignments` trichotomy classifies each cell over
+ * the space of **optimal** schedules — strictly stronger than the
+ * feasibility-only trichotomy returned by
+ * `/api/v1/scheduling/feasibility`.  When the un-pinned reduced
+ * problem is infeasible, `status = "infeasible"`, `assignments` is
+ * empty, and `total_score` is `0`.
+ */
+interface SchedulingOptimizeResponse$1 {
+    /**
+     * Empty when `status` is `infeasible`; otherwise one entry per
+     * `(agent, day, shift)` triple in the input grid, with
+     * trichotomy taken across the space of optimal schedules.
+     */
+    assignments: AssignmentDto[];
+    /** Top-level request status. */
+    status: SchedulingStatusDto;
+    /**
+     * Sum of [`PreferenceInput::score`] over assigned cells in the
+     * optimum.  `0` when no preferences were supplied or the
+     * problem is infeasible.
+     * @format int64
+     */
+    total_score: number;
+}
 /** Top-level request status. */
 type SchedulingStatusDto = "feasible" | "infeasible";
 /** Request to search communities */
@@ -16927,11 +17002,10 @@ declare class Sorts<SecurityDataType = unknown> {
      */
     getSortSimilarity: (data: GetSortSimilarityRequest$1, params?: RequestParams) => Promise<HttpResponse<GetSortSimilarityResponse$1, any>>;
     /**
-     * @description This enables semantic search over sort names for NER label pre-filtering. Must be called after bulk sort creation (e.g., after ontology hydration) to make sorts searchable via embedding similarity. Returns the number of sorts indexed.
+     * No description
      *
      * @tags sorts
      * @name IndexSorts
-     * @summary Index all sorts for a tenant into the vector store (Qdrant).
      * @request POST:/api/v1/sorts/index
      * @secure
      */
@@ -16988,6 +17062,12 @@ declare class Sorts<SecurityDataType = unknown> {
         limit?: number | null;
         /** Filter to only show LLM-extracted sorts */
         llm_extracted?: boolean | null;
+        /**
+         * Filter to sorts whose name starts with this prefix.
+         * Supports comma-separated multiple prefixes (e.g. "drug_,target_,pathway_,disease_").
+         * Server-side filtering avoids transferring millions of irrelevant sorts.
+         */
+        name_prefix?: string | null;
         /** Filter to only show sorts needing review */
         needs_review?: boolean | null;
         /**
@@ -39298,6 +39378,15 @@ declare class Scheduling<SecurityDataType = unknown> {
      * @request POST:/api/v1/scheduling/feasibility
      */
     feasibility: (data: SchedulingFeasibilityRequest$1, params?: RequestParams) => Promise<HttpResponse<SchedulingFeasibilityResponse$1, void>>;
+    /**
+     * @description Same hard constraints as `/scheduling/feasibility` plus a list of soft `preferences` (each a per-cell score added to the optimizer's objective).  Returns the per-cell trichotomy across the space of **optimal** schedules, plus `total_score` (sum of preference scores at chosen cells in the optimum). `confirmed_true` / `confirmed_false` here are stronger than in `/feasibility`: they hold across every optimum, not every feasible schedule.  Cells with status `free` indicate ties — multiple optima exist and the cell varies between them. Preferences targeting cells that are already pinned, blocked by a day-off, restricted-to-shift, or otherwise structurally fixed are silently ignored — those cells are not the optimizer's choice to make.
+     *
+     * @tags scheduling
+     * @name Optimize
+     * @summary `POST /api/v1/scheduling/optimize`
+     * @request POST:/api/v1/scheduling/optimize
+     */
+    optimize: (data: SchedulingOptimizeRequest$1, params?: RequestParams) => Promise<HttpResponse<SchedulingOptimizeResponse$1, void>>;
 }
 
 /**
@@ -39456,18 +39545,106 @@ interface SchedulingFeasibilityResponse {
     status: SchedulingStatus;
     assignments: Assignment[];
 }
+/**
+ * A soft preference: bias the optimizer toward (or against) assigning
+ * `agentId` to cell `(day, shift)`.
+ *
+ * @remarks
+ * `score` contributes to the optimizer's objective when the cell is
+ * assigned in the chosen schedule.  Positive values pull the optimizer
+ * toward the cell; negative values push it away.
+ *
+ * Preferences targeting a cell that is already pinned, blocked by a
+ * day-off, restricted-to-shift, or otherwise structurally fixed are
+ * silently ignored — those cells are not the optimizer's choice to
+ * make.
+ *
+ * Common encodings:
+ *   - "Aisha prefers morning shifts" → `score = +5` on every
+ *     `(aisha, day, morning)` pair
+ *   - "Avoid weekend assignments" → `score = -3` on every
+ *     `(*, sat|sun, *)` pair
+ *   - "Honor day-off requests" → `score = -100` on
+ *     `(agent, requested_off_day, *)` (large negative penalty —
+ *     respects the request when feasible, lets the engine decide
+ *     when not)
+ */
+interface Preference {
+    agentId: string;
+    day: number;
+    shift: number;
+    /**
+     * Score added to the objective when this cell is assigned in the
+     * chosen schedule.  Positive = preferred, negative = avoided.
+     */
+    score: number;
+}
+/**
+ * Input to {@link SchedulingClient.optimize}.
+ *
+ * @remarks
+ * Same hard-constraint shape as {@link SchedulingFeasibilityRequest}
+ * plus a list of soft `preferences`.  The engine returns the per-cell
+ * envelope across the space of **optimal** schedules under the
+ * supplied preferences.
+ */
+interface SchedulingOptimizeRequest {
+    agents: AgentSpec[];
+    days: number;
+    shiftsPerDay: number;
+    demands: ShiftDemand[];
+    /** Pre-assigned `(agent, day, shift)` triples.  Defaults to empty. */
+    pins?: Pin[];
+    /**
+     * Soft preferences applied to the objective.  Empty (or omitted) =
+     * unweighted: every feasible schedule is "optimal" and the result
+     * coincides with {@link SchedulingClient.feasibility}.
+     */
+    preferences?: Preference[];
+}
+/**
+ * Response from {@link SchedulingClient.optimize}.
+ *
+ * @remarks
+ * The per-cell `assignments` trichotomy classifies each cell over the
+ * space of **optimal** schedules — strictly stronger than the
+ * feasibility-only trichotomy from
+ * {@link SchedulingClient.feasibility}:
+ *
+ *   - `"confirmed_true"` — assigned in *every* optimal schedule.
+ *   - `"confirmed_false"` — assigned in *no* optimal schedule.
+ *   - `"free"` — varies across the (possibly multiple) optimal
+ *     schedules; the optimizer is indifferent.
+ *
+ * `totalScore` is the sum of {@link Preference.score} over assigned
+ * cells in the optimum.  It is `0` when no preferences were supplied
+ * or the problem is infeasible.
+ */
+interface SchedulingOptimizeResponse {
+    status: SchedulingStatus;
+    /** Sum of preference scores at chosen cells in the optimum. */
+    totalScore: number;
+    /**
+     * Empty when `status === "infeasible"`; otherwise one entry per
+     * `(agent, day, shift)` triple in the input grid.
+     */
+    assignments: Assignment[];
+}
 
 declare const scheduling_ANY_ROLE: typeof ANY_ROLE;
 type scheduling_AgentSpec = AgentSpec;
 type scheduling_Assignment = Assignment;
 type scheduling_AssignmentStatus = AssignmentStatus;
 type scheduling_Pin = Pin;
+type scheduling_Preference = Preference;
 type scheduling_SchedulingFeasibilityRequest = SchedulingFeasibilityRequest;
 type scheduling_SchedulingFeasibilityResponse = SchedulingFeasibilityResponse;
+type scheduling_SchedulingOptimizeRequest = SchedulingOptimizeRequest;
+type scheduling_SchedulingOptimizeResponse = SchedulingOptimizeResponse;
 type scheduling_SchedulingStatus = SchedulingStatus;
 type scheduling_ShiftDemand = ShiftDemand;
 declare namespace scheduling {
-  export { scheduling_ANY_ROLE as ANY_ROLE, type scheduling_AgentSpec as AgentSpec, type scheduling_Assignment as Assignment, type scheduling_AssignmentStatus as AssignmentStatus, type scheduling_Pin as Pin, type scheduling_SchedulingFeasibilityRequest as SchedulingFeasibilityRequest, type scheduling_SchedulingFeasibilityResponse as SchedulingFeasibilityResponse, type scheduling_SchedulingStatus as SchedulingStatus, type scheduling_ShiftDemand as ShiftDemand };
+  export { scheduling_ANY_ROLE as ANY_ROLE, type scheduling_AgentSpec as AgentSpec, type scheduling_Assignment as Assignment, type scheduling_AssignmentStatus as AssignmentStatus, type scheduling_Pin as Pin, type scheduling_Preference as Preference, type scheduling_SchedulingFeasibilityRequest as SchedulingFeasibilityRequest, type scheduling_SchedulingFeasibilityResponse as SchedulingFeasibilityResponse, type scheduling_SchedulingOptimizeRequest as SchedulingOptimizeRequest, type scheduling_SchedulingOptimizeResponse as SchedulingOptimizeResponse, type scheduling_SchedulingStatus as SchedulingStatus, type scheduling_ShiftDemand as ShiftDemand };
 }
 
 /**
@@ -39539,6 +39716,65 @@ declare class SchedulingClient {
      * raises.
      */
     feasibility(request: SchedulingFeasibilityRequest): Promise<SchedulingFeasibilityResponse>;
+    /**
+     * Solve the scheduling problem with **soft preferences** and
+     * return the per-cell envelope across the space of *optimal*
+     * schedules.
+     *
+     * @param request - the scheduling problem plus optional
+     *   `preferences` (per-cell scores added to the optimizer's
+     *   objective).  Same hard-constraint shape as
+     *   {@link SchedulingClient.feasibility}.
+     * @returns a {@link SchedulingOptimizeResponse} with `totalScore`
+     *   and per-cell trichotomy across optimal schedules.
+     *
+     * @throws HTTP 400 errors are surfaced when the input is malformed
+     *   (duplicate agent IDs, pins or preferences referencing unknown
+     *   agents, ambiguous pin role on multi-role agents, role minima
+     *   exceeding total demand, etc.).
+     *
+     * @remarks
+     * The trichotomy returned here is **strictly stronger** than the
+     * one from {@link SchedulingClient.feasibility}:
+     *
+     *   - `"confirmed_true"` — assigned in *every* optimum.
+     *   - `"confirmed_false"` — assigned in *no* optimum.
+     *   - `"free"` — varies across the optima; the optimizer is indifferent
+     *     between equally-good choices.
+     *
+     * `totalScore` is the sum of {@link Preference.score} over assigned
+     * cells in the optimum (`0` when no preferences are supplied or
+     * the problem is infeasible).
+     *
+     * Preferences targeting structurally-fixed cells (pinned cells,
+     * day-off / shift-only restricted cells, agents not in the grid)
+     * are silently ignored — the optimizer has no choice to make there.
+     *
+     * Empty `preferences` is equivalent to calling
+     * {@link SchedulingClient.feasibility} (every feasible schedule
+     * is optimal under a zero objective), but slower; prefer
+     * `feasibility()` when you only need the feasibility envelope.
+     *
+     * @example Score Aisha as a strong preference for emergency cover
+     * ```typescript
+     * const report = await client.scheduling.optimize({
+     *   agents: [
+     *     { id: 'aisha', roles: ['icu', 'emergency'], maxAssignments: 5 },
+     *     { id: 'bob',   roles: ['general'],          maxAssignments: 5 },
+     *   ],
+     *   days: 7,
+     *   shiftsPerDay: 3,
+     *   demands: [{ day: 0, shift: 0, total: 2, roleMinimums: { icu: 1 } }],
+     *   preferences: [
+     *     { agentId: 'aisha', day: 0, shift: 0, score: 10 },
+     *   ],
+     * });
+     *
+     * console.log(report.totalScore);   // 10 if Aisha is in the optimum
+     * console.log(report.status);       // 'feasible' | 'infeasible'
+     * ```
+     */
+    optimize(request: SchedulingOptimizeRequest): Promise<SchedulingOptimizeResponse>;
 }
 
 declare class Osfql<SecurityDataType = unknown> {

package/dist/index.d.ts

@@ -109,7 +109,7 @@ type JsonValue$1 = string | number | boolean | null | JsonValue$1[] | object;
  * This is the single source of truth for the version constant.
  * The `scripts/release.sh` script updates this value alongside `package.json`.
  */
-declare const SDK_VERSION = "0.20.0";
+declare const SDK_VERSION = "0.21.0";
 /**
  * Configuration for the Reasoning Layer client.
  *
@@ -11812,6 +11812,31 @@ interface PreferenceDto$1 {
     /** Preference value. */
     value: string;
 }
+/**
+ * A soft preference: bias the optimizer toward (or against) assigning
+ * `agent_id` to cell `(day, shift)`.
+ *
+ * `score` contributes to the objective when the cell is assigned in
+ * the chosen schedule.  Positive values pull the optimizer toward
+ * the cell; negative values push it away.  Preferences targeting a
+ * pinned cell, an agent with a day-off on `day`, or an agent
+ * otherwise blocked from the slot are silently ignored — the
+ * corresponding decision edge does not exist in the reduced flow
+ * graph.
+ */
+interface PreferenceInput {
+    agent_id: string;
+    /** @min 0 */
+    day: number;
+    /**
+     * Score contributed by this assignment to the optimizer's
+     * objective.  Positive = preferred, negative = avoided.
+     * @format int64
+     */
+    score: number;
+    /** @min 0 */
+    shift: number;
+}
 /** Prediction result for a single term */
 interface PreferencePrediction$1 {
     /** @format double */
@@ -13741,6 +13766,56 @@ interface SchedulingFeasibilityResponse$1 {
     /** Top-level request status. */
     status: SchedulingStatusDto;
 }
+/**
+ * Request body for `POST /api/v1/scheduling/optimize`.
+ *
+ * Same hard-constraint shape as
+ * [`SchedulingFeasibilityRequest`], plus a list of soft
+ * `preferences`.  The engine returns the per-cell envelope across
+ * the space of **optimal** schedules under the supplied
+ * preferences.
+ */
+interface SchedulingOptimizeRequest$1 {
+    agents: AgentInput[];
+    /** @min 0 */
+    days: number;
+    demands: ShiftDemandInput[];
+    pins?: PinInput[];
+    /**
+     * Soft preferences applied to the objective.  Empty = unweighted
+     * (every feasible schedule is "optimal").
+     */
+    preferences?: PreferenceInput[];
+    /** @min 0 */
+    shifts_per_day: number;
+}
+/**
+ * Response to [`SchedulingOptimizeRequest`].
+ *
+ * The per-cell `assignments` trichotomy classifies each cell over
+ * the space of **optimal** schedules — strictly stronger than the
+ * feasibility-only trichotomy returned by
+ * `/api/v1/scheduling/feasibility`.  When the un-pinned reduced
+ * problem is infeasible, `status = "infeasible"`, `assignments` is
+ * empty, and `total_score` is `0`.
+ */
+interface SchedulingOptimizeResponse$1 {
+    /**
+     * Empty when `status` is `infeasible`; otherwise one entry per
+     * `(agent, day, shift)` triple in the input grid, with
+     * trichotomy taken across the space of optimal schedules.
+     */
+    assignments: AssignmentDto[];
+    /** Top-level request status. */
+    status: SchedulingStatusDto;
+    /**
+     * Sum of [`PreferenceInput::score`] over assigned cells in the
+     * optimum.  `0` when no preferences were supplied or the
+     * problem is infeasible.
+     * @format int64
+     */
+    total_score: number;
+}
 /** Top-level request status. */
 type SchedulingStatusDto = "feasible" | "infeasible";
 /** Request to search communities */
@@ -16927,11 +17002,10 @@ declare class Sorts<SecurityDataType = unknown> {
      */
     getSortSimilarity: (data: GetSortSimilarityRequest$1, params?: RequestParams) => Promise<HttpResponse<GetSortSimilarityResponse$1, any>>;
     /**
-     * @description This enables semantic search over sort names for NER label pre-filtering. Must be called after bulk sort creation (e.g., after ontology hydration) to make sorts searchable via embedding similarity. Returns the number of sorts indexed.
+     * No description
      *
      * @tags sorts
      * @name IndexSorts
-     * @summary Index all sorts for a tenant into the vector store (Qdrant).
      * @request POST:/api/v1/sorts/index
      * @secure
      */
@@ -16988,6 +17062,12 @@ declare class Sorts<SecurityDataType = unknown> {
         limit?: number | null;
         /** Filter to only show LLM-extracted sorts */
         llm_extracted?: boolean | null;
+        /**
+         * Filter to sorts whose name starts with this prefix.
+         * Supports comma-separated multiple prefixes (e.g. "drug_,target_,pathway_,disease_").
+         * Server-side filtering avoids transferring millions of irrelevant sorts.
+         */
+        name_prefix?: string | null;
         /** Filter to only show sorts needing review */
         needs_review?: boolean | null;
         /**
@@ -39298,6 +39378,15 @@ declare class Scheduling<SecurityDataType = unknown> {
      * @request POST:/api/v1/scheduling/feasibility
      */
     feasibility: (data: SchedulingFeasibilityRequest$1, params?: RequestParams) => Promise<HttpResponse<SchedulingFeasibilityResponse$1, void>>;
+    /**
+     * @description Same hard constraints as `/scheduling/feasibility` plus a list of soft `preferences` (each a per-cell score added to the optimizer's objective).  Returns the per-cell trichotomy across the space of **optimal** schedules, plus `total_score` (sum of preference scores at chosen cells in the optimum). `confirmed_true` / `confirmed_false` here are stronger than in `/feasibility`: they hold across every optimum, not every feasible schedule.  Cells with status `free` indicate ties — multiple optima exist and the cell varies between them. Preferences targeting cells that are already pinned, blocked by a day-off, restricted-to-shift, or otherwise structurally fixed are silently ignored — those cells are not the optimizer's choice to make.
+     *
+     * @tags scheduling
+     * @name Optimize
+     * @summary `POST /api/v1/scheduling/optimize`
+     * @request POST:/api/v1/scheduling/optimize
+     */
+    optimize: (data: SchedulingOptimizeRequest$1, params?: RequestParams) => Promise<HttpResponse<SchedulingOptimizeResponse$1, void>>;
 }
 
 /**
@@ -39456,18 +39545,106 @@ interface SchedulingFeasibilityResponse {
     status: SchedulingStatus;
     assignments: Assignment[];
 }
+/**
+ * A soft preference: bias the optimizer toward (or against) assigning
+ * `agentId` to cell `(day, shift)`.
+ *
+ * @remarks
+ * `score` contributes to the optimizer's objective when the cell is
+ * assigned in the chosen schedule.  Positive values pull the optimizer
+ * toward the cell; negative values push it away.
+ *
+ * Preferences targeting a cell that is already pinned, blocked by a
+ * day-off, restricted-to-shift, or otherwise structurally fixed are
+ * silently ignored — those cells are not the optimizer's choice to
+ * make.
+ *
+ * Common encodings:
+ *   - "Aisha prefers morning shifts" → `score = +5` on every
+ *     `(aisha, day, morning)` pair
+ *   - "Avoid weekend assignments" → `score = -3` on every
+ *     `(*, sat|sun, *)` pair
+ *   - "Honor day-off requests" → `score = -100` on
+ *     `(agent, requested_off_day, *)` (large negative penalty —
+ *     respects the request when feasible, lets the engine decide
+ *     when not)
+ */
+interface Preference {
+    agentId: string;
+    day: number;
+    shift: number;
+    /**
+     * Score added to the objective when this cell is assigned in the
+     * chosen schedule.  Positive = preferred, negative = avoided.
+     */
+    score: number;
+}
+/**
+ * Input to {@link SchedulingClient.optimize}.
+ *
+ * @remarks
+ * Same hard-constraint shape as {@link SchedulingFeasibilityRequest}
+ * plus a list of soft `preferences`.  The engine returns the per-cell
+ * envelope across the space of **optimal** schedules under the
+ * supplied preferences.
+ */
+interface SchedulingOptimizeRequest {
+    agents: AgentSpec[];
+    days: number;
+    shiftsPerDay: number;
+    demands: ShiftDemand[];
+    /** Pre-assigned `(agent, day, shift)` triples.  Defaults to empty. */
+    pins?: Pin[];
+    /**
+     * Soft preferences applied to the objective.  Empty (or omitted) =
+     * unweighted: every feasible schedule is "optimal" and the result
+     * coincides with {@link SchedulingClient.feasibility}.
+     */
+    preferences?: Preference[];
+}
+/**
+ * Response from {@link SchedulingClient.optimize}.
+ *
+ * @remarks
+ * The per-cell `assignments` trichotomy classifies each cell over the
+ * space of **optimal** schedules — strictly stronger than the
+ * feasibility-only trichotomy from
+ * {@link SchedulingClient.feasibility}:
+ *
+ *   - `"confirmed_true"` — assigned in *every* optimal schedule.
+ *   - `"confirmed_false"` — assigned in *no* optimal schedule.
+ *   - `"free"` — varies across the (possibly multiple) optimal
+ *     schedules; the optimizer is indifferent.
+ *
+ * `totalScore` is the sum of {@link Preference.score} over assigned
+ * cells in the optimum.  It is `0` when no preferences were supplied
+ * or the problem is infeasible.
+ */
+interface SchedulingOptimizeResponse {
+    status: SchedulingStatus;
+    /** Sum of preference scores at chosen cells in the optimum. */
+    totalScore: number;
+    /**
+     * Empty when `status === "infeasible"`; otherwise one entry per
+     * `(agent, day, shift)` triple in the input grid.
+     */
+    assignments: Assignment[];
+}
 
 declare const scheduling_ANY_ROLE: typeof ANY_ROLE;
 type scheduling_AgentSpec = AgentSpec;
 type scheduling_Assignment = Assignment;
 type scheduling_AssignmentStatus = AssignmentStatus;
 type scheduling_Pin = Pin;
+type scheduling_Preference = Preference;
 type scheduling_SchedulingFeasibilityRequest = SchedulingFeasibilityRequest;
 type scheduling_SchedulingFeasibilityResponse = SchedulingFeasibilityResponse;
+type scheduling_SchedulingOptimizeRequest = SchedulingOptimizeRequest;
+type scheduling_SchedulingOptimizeResponse = SchedulingOptimizeResponse;
 type scheduling_SchedulingStatus = SchedulingStatus;
 type scheduling_ShiftDemand = ShiftDemand;
 declare namespace scheduling {
-  export { scheduling_ANY_ROLE as ANY_ROLE, type scheduling_AgentSpec as AgentSpec, type scheduling_Assignment as Assignment, type scheduling_AssignmentStatus as AssignmentStatus, type scheduling_Pin as Pin, type scheduling_SchedulingFeasibilityRequest as SchedulingFeasibilityRequest, type scheduling_SchedulingFeasibilityResponse as SchedulingFeasibilityResponse, type scheduling_SchedulingStatus as SchedulingStatus, type scheduling_ShiftDemand as ShiftDemand };
+  export { scheduling_ANY_ROLE as ANY_ROLE, type scheduling_AgentSpec as AgentSpec, type scheduling_Assignment as Assignment, type scheduling_AssignmentStatus as AssignmentStatus, type scheduling_Pin as Pin, type scheduling_Preference as Preference, type scheduling_SchedulingFeasibilityRequest as SchedulingFeasibilityRequest, type scheduling_SchedulingFeasibilityResponse as SchedulingFeasibilityResponse, type scheduling_SchedulingOptimizeRequest as SchedulingOptimizeRequest, type scheduling_SchedulingOptimizeResponse as SchedulingOptimizeResponse, type scheduling_SchedulingStatus as SchedulingStatus, type scheduling_ShiftDemand as ShiftDemand };
 }
 
 /**
@@ -39539,6 +39716,65 @@ declare class SchedulingClient {
      * raises.
      */
     feasibility(request: SchedulingFeasibilityRequest): Promise<SchedulingFeasibilityResponse>;
+    /**
+     * Solve the scheduling problem with **soft preferences** and
+     * return the per-cell envelope across the space of *optimal*
+     * schedules.
+     *
+     * @param request - the scheduling problem plus optional
+     *   `preferences` (per-cell scores added to the optimizer's
+     *   objective).  Same hard-constraint shape as
+     *   {@link SchedulingClient.feasibility}.
+     * @returns a {@link SchedulingOptimizeResponse} with `totalScore`
+     *   and per-cell trichotomy across optimal schedules.
+     *
+     * @throws HTTP 400 errors are surfaced when the input is malformed
+     *   (duplicate agent IDs, pins or preferences referencing unknown
+     *   agents, ambiguous pin role on multi-role agents, role minima
+     *   exceeding total demand, etc.).
+     *
+     * @remarks
+     * The trichotomy returned here is **strictly stronger** than the
+     * one from {@link SchedulingClient.feasibility}:
+     *
+     *   - `"confirmed_true"` — assigned in *every* optimum.
+     *   - `"confirmed_false"` — assigned in *no* optimum.
+     *   - `"free"` — varies across the optima; the optimizer is indifferent
+     *     between equally-good choices.
+     *
+     * `totalScore` is the sum of {@link Preference.score} over assigned
+     * cells in the optimum (`0` when no preferences are supplied or
+     * the problem is infeasible).
+     *
+     * Preferences targeting structurally-fixed cells (pinned cells,
+     * day-off / shift-only restricted cells, agents not in the grid)
+     * are silently ignored — the optimizer has no choice to make there.
+     *
+     * Empty `preferences` is equivalent to calling
+     * {@link SchedulingClient.feasibility} (every feasible schedule
+     * is optimal under a zero objective), but slower; prefer
+     * `feasibility()` when you only need the feasibility envelope.
+     *
+     * @example Score Aisha as a strong preference for emergency cover
+     * ```typescript
+     * const report = await client.scheduling.optimize({
+     *   agents: [
+     *     { id: 'aisha', roles: ['icu', 'emergency'], maxAssignments: 5 },
+     *     { id: 'bob',   roles: ['general'],          maxAssignments: 5 },
+     *   ],
+     *   days: 7,
+     *   shiftsPerDay: 3,
+     *   demands: [{ day: 0, shift: 0, total: 2, roleMinimums: { icu: 1 } }],
+     *   preferences: [
+     *     { agentId: 'aisha', day: 0, shift: 0, score: 10 },
+     *   ],
+     * });
+     *
+     * console.log(report.totalScore);   // 10 if Aisha is in the optimum
+     * console.log(report.status);       // 'feasible' | 'infeasible'
+     * ```
+     */
+    optimize(request: SchedulingOptimizeRequest): Promise<SchedulingOptimizeResponse>;
 }
 
 declare class Osfql<SecurityDataType = unknown> {