@kortexya/reasoninglayer 0.19.0 → 0.21.0

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.19.0";
+declare const SDK_VERSION = "0.21.0";
 /**
  * Configuration for the Reasoning Layer client.
  *
@@ -1043,6 +1043,20 @@ interface AssignmentDto {
     agent_id: string;
     /** @min 0 */
     day: number;
+    /**
+     * Roles the agent can or must fill at this cell.
+     *
+     * - When `status = confirmed_true`: the role(s) the agent
+     *   must fill at this cell.  Usually a single entry.
+     * - When `status = free`: the set of roles the agent could
+     *   fill across valid schedules that place them here.
+     * - When `status = confirmed_false`: always empty.
+     *
+     * The reserved string `"any"` denotes routing through the
+     * unroled sub-slot pool (i.e. the agent is "just there",
+     * not counting toward any role minimum at this slot).
+     */
+    roles: string[];
     /** @min 0 */
     shift: number;
     /**
@@ -11473,11 +11487,30 @@ interface PendingReviewEntityDto {
     /** Original text span that was extracted */
     source_text?: string | null;
 }
-/** A pre-assigned `(agent, day, shift)` triple. */
+/**
+ * A pre-assigned `(agent, day, shift)` triple, optionally naming
+ * which role the pin covers.
+ *
+ * When the agent has **multiple roles that each match a role
+ * minimum** at the target slot, the caller MUST set [`PinInput::role`]
+ * to disambiguate.  Otherwise the engine returns HTTP 400 — the
+ * silent greedy-match that used to happen here could pick the
+ * "wrong" role and produce spurious infeasibility.
+ *
+ * Role semantics:
+ *   * `None` — caller hasn't chosen.  Valid only if the agent has at
+ *     most one role matching this slot's role_mins.
+ *   * `Some("any")` — explicit request to route through the
+ *     unroled pool; no role minimum is decremented.
+ *   * `Some(role)` — force the pin to cover this role.  Must be a
+ *     role the agent possesses (HTTP 400 otherwise).
+ */
 interface PinInput {
     agent_id: string;
     /** @min 0 */
     day: number;
+    /** Role the pin covers.  See struct-level docs for the cases. */
+    role?: string | null;
     /** @min 0 */
     shift: number;
 }
@@ -11779,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 */
@@ -13708,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 */
@@ -16894,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
      */
@@ -16955,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;
         /**
@@ -39257,7 +39370,7 @@ declare class Scheduling<SecurityDataType = unknown> {
     http: HttpClient<SecurityDataType>;
     constructor(http: HttpClient<SecurityDataType>);
     /**
-     * @description Classify every `(agent, day, shift)` cell in the input grid as confirmed-true, confirmed-false, or free. Input validation errors (duplicate agent IDs, out-of-range pins, role minima exceeding total demand, etc.) return HTTP 400. Infeasibility of a well-formed problem is a valid answer and returns HTTP 200 with `status = "infeasible"` and an empty `assignments` list.
+     * @description Classify every `(agent, day, shift)` cell in the input grid as confirmed-true, confirmed-false, or free, and list the role(s) each cell could cover. Input validation errors (duplicate agent IDs, out-of-range pins, role minima exceeding total demand, pin role the agent doesn't have, pin on a multi-role agent where the role is ambiguous, etc.) return HTTP 400. Infeasibility of a well-formed problem is a valid answer and returns HTTP 200 with `status = "infeasible"` and an empty `assignments` list.
      *
      * @tags scheduling
      * @name Feasibility
@@ -39265,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>>;
 }
 
 /**
@@ -39334,14 +39456,38 @@ interface ShiftDemand {
      */
     roleMinimums?: Record<string, number>;
 }
+/**
+ * Reserved role-name for the unroled ("any") sub-slot pool.
+ *
+ * Use this value for {@link Pin.role} when you want the pin to NOT
+ * decrement any role minimum (agent fills the "any" slack).  Also
+ * appears in {@link Assignment.roles} when the agent routes through
+ * that pool.
+ */
+declare const ANY_ROLE = "any";
 /**
  * A pre-assigned `(agent, day, shift)` triple.  The engine treats the
  * pin as confirmed-true and reduces the slot's remaining demand.
+ *
+ * When the agent has **multiple roles that each match a role
+ * minimum** at the target slot, the caller MUST set {@link Pin.role}
+ * to disambiguate.  Otherwise the backend returns HTTP 400 with an
+ * "ambiguous pin role" error listing the candidate roles.
+ *
+ * Role semantics:
+ *   - `undefined` — no role specified.  Valid only when the agent has
+ *     at most one role matching this slot's role minimums.
+ *   - `"any"` (see {@link ANY_ROLE}) — route through the unroled pool;
+ *     no role minimum is decremented.
+ *   - `"<role>"` — force the pin to cover this role.  Must be a role
+ *     the agent possesses (HTTP 400 otherwise).
  */
 interface Pin {
     agentId: string;
     day: number;
     shift: number;
+    /** Role the pin covers.  See docs above for the cases. */
+    role?: string;
 }
 /**
  * Input to {@link SchedulingClient.feasibility}.
@@ -39372,6 +39518,19 @@ interface Assignment {
     day: number;
     shift: number;
     status: AssignmentStatus;
+    /**
+     * Roles the agent can or must fill at this cell.
+     *
+     * - When `status === 'confirmed_true'`: the role(s) the agent must
+     *   fill at this cell.  Usually a single entry.
+     * - When `status === 'free'`: the set of roles the agent could fill
+     *   across valid schedules that place them here.
+     * - When `status === 'confirmed_false'`: always empty.
+     *
+     * The reserved string {@link ANY_ROLE} (`"any"`) denotes routing
+     * through the unroled sub-slot pool.
+     */
+    roles: string[];
 }
 /**
  * Response from {@link SchedulingClient.feasibility}.
@@ -39386,17 +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 type { scheduling_AgentSpec as AgentSpec, scheduling_Assignment as Assignment, scheduling_AssignmentStatus as AssignmentStatus, scheduling_Pin as Pin, scheduling_SchedulingFeasibilityRequest as SchedulingFeasibilityRequest, scheduling_SchedulingFeasibilityResponse as SchedulingFeasibilityResponse, scheduling_SchedulingStatus as SchedulingStatus, 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 };
 }
 
 /**
@@ -39468,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> {
@@ -42334,4 +42641,4 @@ declare function toUntaggedFeatures(features: PlainFeatureMap): Record<string, F
  */
 declare function toTermInputDto(input: PsiTermInput | TermInputDto): TermInputDto;
 
-export { actionReviews as ActionReviews, type AddFactRequest, type AddFactResponse, type AddRuleRequest, type AddRuleResponse, admin as Admin, type AiGroup, analysis as Analysis, type AnalysisGroup, ApiError, type ApiResponse, AuthenticationError, type BackwardChainRequest, type BackwardChainResponse, BadRequestError, type BulkAddTermsRequest, type BulkAddTermsResponse, type BulkCreateSortsRequest, type BulkCreateSortsResponse, cdl as CDL, causal as Causal, type ClearTermsResponse, type ClientConfig, cognitive as Cognitive, collections as Collections, communities as Communities, type ConstrainedPlainVar, ConstraintViolationError, constraints as Constraints, control as Control, conversation as Conversation, type ConversationMessageRequest, type ConversationMessageResponse, type ConversationSummaryDto, type ConversationTurnsResponse, type CoreGroup, type CreateResearchSessionRequest, type CreateResearchSessionResponse, type CreateSortRequest, type CreateTermRequest, type DataGroup, discovery as Discovery, type ErrorResponse$1 as ErrorResponse, execution as Execution, extract as Extract, type FeatureInputValueDto, type FeatureValueDto, ForbiddenError, type ForwardChainRequest, type ForwardChainResponse, functions as Functions, fuzzy as Fuzzy, FuzzyShape, type FuzzyShapeDto, generation as Generation, type GlbRequest, type GlbResponse, health as Health, homoiconic as Homoiconic, ilp as ILP, imageExtraction as ImageExtraction, inference as Inference, type IngestPaperRequest, type IngestPaperResponse, ingestion as Ingestion, IngestionFailedError, IngestionSession, type IngestionSyncOptions, type Interceptor, InternalServerError, type JsonValue$1 as JsonValue, LP, type ListConversationsResponse, type LubRequest, type LubResponse, namespaces as Namespaces, NetworkError, neuroSymbolic as NeuroSymbolic, NotFoundError, ontology as Ontology, optimize as Optimize, type OsfSearchRequest, type OsfSearchResponse, osfql as Osfql, type OsfqlRequest, type OsfqlResponse, type OsfqlValue, oversight as Oversight, type PaginationParams, type PaperMetadataDto, type PaperSource, type PlainFeatureMap, type PlainFeatureValue, plainValues as PlainValues, preferences as Preferences, proofEngine as ProofEngine, type PsiTermDto, type PsiTermInput, query as Query, rag as RAG, RateLimitError, type RateLimitInfo, reasoning as Reasoning, type ReasoningGroup, ReasoningLayerClient, ReasoningLayerError, type RequestOptions, research as Research, type ResearchContradictionsResponse, type ResearchCycleResponse, type ResearchFindingsResponse, type ResearchGapsResponse, type ResearchReportResponse, type ResearchSessionResponse, reviews as Reviews, row as Row, SDK_VERSION, scenarios as Scenarios, scheduling as Scheduling, type SearchPapersRequest, type SearchPapersResponse, SortBuilder, type SortDto, type SortInfoDto, sorts as Sorts, sources as Sources, spaces as Spaces, statistical as Statistical, synthetic as Synthetic, type SystemGroup, type TermDto, type TermInputArg, type TermInputDto, type TermListResponse, type TermPatternDto, type TermResponse, terms as Terms, TimeoutError, type TurnDto, type UpdateTermRequest, utilities as Utilities, ValidationError, Value, type ValueDto, values as Values, type VerifyClaimRequest, type VerifyClaimResponse, visualization as Visualization, WebSocketClient, WebSocketConnection, webhookActions as WebhookActions, type WorkflowGroup, allen, constrained, discriminateFeatureValue, guard, isConstrainedPlainVar, isPsiTermInput, isTaggedValueDto, isUuid, psi, toTaggedFeatures, toTaggedValue, toTermInputDto, toUntaggedFeatures, toUntaggedValue };
+export { ANY_ROLE, actionReviews as ActionReviews, type AddFactRequest, type AddFactResponse, type AddRuleRequest, type AddRuleResponse, admin as Admin, type AiGroup, analysis as Analysis, type AnalysisGroup, ApiError, type ApiResponse, AuthenticationError, type BackwardChainRequest, type BackwardChainResponse, BadRequestError, type BulkAddTermsRequest, type BulkAddTermsResponse, type BulkCreateSortsRequest, type BulkCreateSortsResponse, cdl as CDL, causal as Causal, type ClearTermsResponse, type ClientConfig, cognitive as Cognitive, collections as Collections, communities as Communities, type ConstrainedPlainVar, ConstraintViolationError, constraints as Constraints, control as Control, conversation as Conversation, type ConversationMessageRequest, type ConversationMessageResponse, type ConversationSummaryDto, type ConversationTurnsResponse, type CoreGroup, type CreateResearchSessionRequest, type CreateResearchSessionResponse, type CreateSortRequest, type CreateTermRequest, type DataGroup, discovery as Discovery, type ErrorResponse$1 as ErrorResponse, execution as Execution, extract as Extract, type FeatureInputValueDto, type FeatureValueDto, ForbiddenError, type ForwardChainRequest, type ForwardChainResponse, functions as Functions, fuzzy as Fuzzy, FuzzyShape, type FuzzyShapeDto, generation as Generation, type GlbRequest, type GlbResponse, health as Health, homoiconic as Homoiconic, ilp as ILP, imageExtraction as ImageExtraction, inference as Inference, type IngestPaperRequest, type IngestPaperResponse, ingestion as Ingestion, IngestionFailedError, IngestionSession, type IngestionSyncOptions, type Interceptor, InternalServerError, type JsonValue$1 as JsonValue, LP, type ListConversationsResponse, type LubRequest, type LubResponse, namespaces as Namespaces, NetworkError, neuroSymbolic as NeuroSymbolic, NotFoundError, ontology as Ontology, optimize as Optimize, type OsfSearchRequest, type OsfSearchResponse, osfql as Osfql, type OsfqlRequest, type OsfqlResponse, type OsfqlValue, oversight as Oversight, type PaginationParams, type PaperMetadataDto, type PaperSource, type PlainFeatureMap, type PlainFeatureValue, plainValues as PlainValues, preferences as Preferences, proofEngine as ProofEngine, type PsiTermDto, type PsiTermInput, query as Query, rag as RAG, RateLimitError, type RateLimitInfo, reasoning as Reasoning, type ReasoningGroup, ReasoningLayerClient, ReasoningLayerError, type RequestOptions, research as Research, type ResearchContradictionsResponse, type ResearchCycleResponse, type ResearchFindingsResponse, type ResearchGapsResponse, type ResearchReportResponse, type ResearchSessionResponse, reviews as Reviews, row as Row, SDK_VERSION, scenarios as Scenarios, scheduling as Scheduling, type SearchPapersRequest, type SearchPapersResponse, SortBuilder, type SortDto, type SortInfoDto, sorts as Sorts, sources as Sources, spaces as Spaces, statistical as Statistical, synthetic as Synthetic, type SystemGroup, type TermDto, type TermInputArg, type TermInputDto, type TermListResponse, type TermPatternDto, type TermResponse, terms as Terms, TimeoutError, type TurnDto, type UpdateTermRequest, utilities as Utilities, ValidationError, Value, type ValueDto, values as Values, type VerifyClaimRequest, type VerifyClaimResponse, visualization as Visualization, WebSocketClient, WebSocketConnection, webhookActions as WebhookActions, type WorkflowGroup, allen, constrained, discriminateFeatureValue, guard, isConstrainedPlainVar, isPsiTermInput, isTaggedValueDto, isUuid, psi, toTaggedFeatures, toTaggedValue, toTermInputDto, toUntaggedFeatures, toUntaggedValue };

package/dist/index.js

@@ -1,5 +1,11 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
 // src/config.ts
-var SDK_VERSION = "0.19.0";
+var SDK_VERSION = "0.21.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -949,11 +955,10 @@ var Sorts = class {
     ...params
   });
   /**
-   * @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
    */
@@ -7384,7 +7389,7 @@ var Scheduling = class {
     this.http = http;
   }
   /**
-   * @description Classify every `(agent, day, shift)` cell in the input grid as confirmed-true, confirmed-false, or free. Input validation errors (duplicate agent IDs, out-of-range pins, role minima exceeding total demand, etc.) return HTTP 400. Infeasibility of a well-formed problem is a valid answer and returns HTTP 200 with `status = "infeasible"` and an empty `assignments` list.
+   * @description Classify every `(agent, day, shift)` cell in the input grid as confirmed-true, confirmed-false, or free, and list the role(s) each cell could cover. Input validation errors (duplicate agent IDs, out-of-range pins, role minima exceeding total demand, pin role the agent doesn't have, pin on a multi-role agent where the role is ambiguous, etc.) return HTTP 400. Infeasibility of a well-formed problem is a valid answer and returns HTTP 200 with `status = "infeasible"` and an empty `assignments` list.
    *
    * @tags scheduling
    * @name Feasibility
@@ -7399,6 +7404,22 @@ var Scheduling = class {
     format: "json",
     ...params
   });
+  /**
+   * @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, params = {}) => this.http.request({
+    path: `/api/v1/scheduling/optimize`,
+    method: "POST",
+    body: data,
+    type: "application/json" /* Json */,
+    format: "json",
+    ...params
+  });
 };
 
 // src/api-spec/generated/Admin.ts
@@ -20491,11 +20512,15 @@ function ShiftDemandFromFrontToApi(demand) {
   return dto;
 }
 function PinFromFrontToApi(pin) {
-  return {
+  const dto = {
     agent_id: pin.agentId,
     day: pin.day,
     shift: pin.shift
   };
+  if (pin.role !== void 0) {
+    dto.role = pin.role;
+  }
+  return dto;
 }
 function SchedulingFeasibilityRequestFromFrontToApi(request) {
   const dto = {
@@ -20514,7 +20539,8 @@ function AssignmentFromApiToFront(dto) {
     agentId: dto.agent_id,
     day: dto.day,
     shift: dto.shift,
-    status: dto.status
+    status: dto.status,
+    roles: dto.roles ?? []
   };
 }
 function SchedulingFeasibilityResponseFromApiToFront(dto) {
@@ -20523,6 +20549,36 @@ function SchedulingFeasibilityResponseFromApiToFront(dto) {
     assignments: dto.assignments.map(AssignmentFromApiToFront)
   };
 }
+function PreferenceFromFrontToApi(pref) {
+  return {
+    agent_id: pref.agentId,
+    day: pref.day,
+    shift: pref.shift,
+    score: pref.score
+  };
+}
+function SchedulingOptimizeRequestFromFrontToApi(request) {
+  const dto = {
+    agents: request.agents.map(AgentSpecFromFrontToApi),
+    days: request.days,
+    shifts_per_day: request.shiftsPerDay,
+    demands: request.demands.map(ShiftDemandFromFrontToApi)
+  };
+  if (request.pins !== void 0) {
+    dto.pins = request.pins.map(PinFromFrontToApi);
+  }
+  if (request.preferences !== void 0) {
+    dto.preferences = request.preferences.map(PreferenceFromFrontToApi);
+  }
+  return dto;
+}
+function SchedulingOptimizeResponseFromApiToFront(dto) {
+  return {
+    status: dto.status,
+    totalScore: dto.total_score,
+    assignments: dto.assignments.map(AssignmentFromApiToFront)
+  };
+}
 
 // src/resources/scheduling.ts
 var SchedulingClient = class {
@@ -20553,6 +20609,70 @@ var SchedulingClient = class {
     );
     return SchedulingFeasibilityResponseFromApiToFront(response.data);
   }
+  /**
+   * 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'
+   * ```
+   */
+  async optimize(request) {
+    const response = await this.api.optimize(
+      SchedulingOptimizeRequestFromFrontToApi(request)
+    );
+    return SchedulingOptimizeResponseFromApiToFront(response.data);
+  }
 };
 
 // src/normalizers/osfql.ts
@@ -22088,6 +22208,10 @@ var optimize_exports = {};
 
 // src/types/scheduling.ts
 var scheduling_exports = {};
+__export(scheduling_exports, {
+  ANY_ROLE: () => ANY_ROLE
+});
+var ANY_ROLE = "any";
 
 // src/types/ilp.ts
 var ilp_exports = {};
@@ -22778,6 +22902,6 @@ function discriminateFeatureValue(value) {
   );
 }
 
-export { action_reviews_exports as ActionReviews, admin_exports as Admin, analysis_exports as Analysis, ApiError, AuthenticationError, BadRequestError, cdl_exports as CDL, causal_exports as Causal, cognitive_exports as Cognitive, collections_exports as Collections, communities_exports as Communities, ConstraintViolationError, constraints_exports as Constraints, control_exports as Control, conversation_exports as Conversation, discovery_exports as Discovery, execution_exports as Execution, extract_exports as Extract, ForbiddenError, functions_exports as Functions, fuzzy_exports as Fuzzy, FuzzyShape, generation_exports as Generation, health_exports as Health, homoiconic_exports as Homoiconic, ilp_exports as ILP, image_extraction_exports as ImageExtraction, inference_exports as Inference, ingestion_exports as Ingestion, IngestionFailedError, IngestionSession, InternalServerError, LP, namespaces_exports as Namespaces, NetworkError, neuro_symbolic_exports as NeuroSymbolic, NotFoundError, ontology_exports as Ontology, optimize_exports as Optimize, osfql_exports as Osfql, oversight_exports as Oversight, plain_values_exports as PlainValues, preferences_exports as Preferences, proof_engine_exports as ProofEngine, query_exports as Query, rag_exports as RAG, RateLimitError, reasoning_exports as Reasoning, ReasoningLayerClient, ReasoningLayerError, research_exports as Research, reviews_exports as Reviews, row_exports as Row, SDK_VERSION, scenarios_exports as Scenarios, scheduling_exports as Scheduling, SortBuilder, sorts_exports as Sorts, sources_exports as Sources, spaces_exports as Spaces, statistical_exports as Statistical, synthetic_exports as Synthetic, terms_exports as Terms, TimeoutError, utilities_exports as Utilities, ValidationError, Value, values_exports as Values, visualization_exports as Visualization, WebSocketClient, WebSocketConnection, webhook_actions_exports as WebhookActions, allen, constrained, discriminateFeatureValue, guard, isConstrainedPlainVar, isPsiTermInput, isTaggedValueDto, isUuid, psi, toTaggedFeatures, toTaggedValue, toTermInputDto, toUntaggedFeatures, toUntaggedValue };
+export { ANY_ROLE, action_reviews_exports as ActionReviews, admin_exports as Admin, analysis_exports as Analysis, ApiError, AuthenticationError, BadRequestError, cdl_exports as CDL, causal_exports as Causal, cognitive_exports as Cognitive, collections_exports as Collections, communities_exports as Communities, ConstraintViolationError, constraints_exports as Constraints, control_exports as Control, conversation_exports as Conversation, discovery_exports as Discovery, execution_exports as Execution, extract_exports as Extract, ForbiddenError, functions_exports as Functions, fuzzy_exports as Fuzzy, FuzzyShape, generation_exports as Generation, health_exports as Health, homoiconic_exports as Homoiconic, ilp_exports as ILP, image_extraction_exports as ImageExtraction, inference_exports as Inference, ingestion_exports as Ingestion, IngestionFailedError, IngestionSession, InternalServerError, LP, namespaces_exports as Namespaces, NetworkError, neuro_symbolic_exports as NeuroSymbolic, NotFoundError, ontology_exports as Ontology, optimize_exports as Optimize, osfql_exports as Osfql, oversight_exports as Oversight, plain_values_exports as PlainValues, preferences_exports as Preferences, proof_engine_exports as ProofEngine, query_exports as Query, rag_exports as RAG, RateLimitError, reasoning_exports as Reasoning, ReasoningLayerClient, ReasoningLayerError, research_exports as Research, reviews_exports as Reviews, row_exports as Row, SDK_VERSION, scenarios_exports as Scenarios, scheduling_exports as Scheduling, SortBuilder, sorts_exports as Sorts, sources_exports as Sources, spaces_exports as Spaces, statistical_exports as Statistical, synthetic_exports as Synthetic, terms_exports as Terms, TimeoutError, utilities_exports as Utilities, ValidationError, Value, values_exports as Values, visualization_exports as Visualization, WebSocketClient, WebSocketConnection, webhook_actions_exports as WebhookActions, allen, constrained, discriminateFeatureValue, guard, isConstrainedPlainVar, isPsiTermInput, isTaggedValueDto, isUuid, psi, toTaggedFeatures, toTaggedValue, toTermInputDto, toUntaggedFeatures, toUntaggedValue };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map