@kortexya/reasoninglayer 0.20.0 → 0.22.0

package/dist/index.cjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "0.20.0";
+var SDK_VERSION = "0.22.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -957,11 +957,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
    */
@@ -7391,6 +7390,54 @@ var Scheduling = class {
   constructor(http) {
     this.http = http;
   }
+  /**
+   * No description
+   *
+   * @tags scheduling
+   * @name AddPin
+   * @summary `POST /api/v1/scheduling/problems/{id}/pins`
+   * @request POST:/api/v1/scheduling/problems/{problem_id}/pins
+   */
+  addPin = (problemId, data, params = {}) => this.http.request({
+    path: `/api/v1/scheduling/problems/${problemId}/pins`,
+    method: "POST",
+    body: data,
+    type: "application/json" /* Json */,
+    format: "json",
+    ...params
+  });
+  /**
+   * No description
+   *
+   * @tags scheduling
+   * @name AddPreference
+   * @summary `POST /api/v1/scheduling/problems/{id}/preferences`
+   * @request POST:/api/v1/scheduling/problems/{problem_id}/preferences
+   */
+  addPreference = (problemId, data, params = {}) => this.http.request({
+    path: `/api/v1/scheduling/problems/${problemId}/preferences`,
+    method: "POST",
+    body: data,
+    type: "application/json" /* Json */,
+    format: "json",
+    ...params
+  });
+  /**
+   * @description Freeze the inline scheduling inputs into a `scheduling.problem` Ψ-term snapshot stored in the application-layer scheduling store, and return its ID.  The endpoint does NOT solve — call `POST /api/v1/scheduling/problems/{id}/solve` to compute the optimum, then `GET /api/v1/scheduling/problems/{id}/assignments` to retrieve the per-cell trichotomy. Snapshot mode: subsequent re-solves read only the snapshot, not any source terms in the KB.  This keeps the optimum reproducible and auditable from the moment the problem is created.
+   *
+   * @tags scheduling
+   * @name CreateProblem
+   * @summary `POST /api/v1/scheduling/problems`
+   * @request POST:/api/v1/scheduling/problems
+   */
+  createProblem = (data, params = {}) => this.http.request({
+    path: `/api/v1/scheduling/problems`,
+    method: "POST",
+    body: data,
+    type: "application/json" /* Json */,
+    format: "json",
+    ...params
+  });
   /**
    * @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.
    *
@@ -7407,6 +7454,90 @@ var Scheduling = class {
     format: "json",
     ...params
   });
+  /**
+   * No description
+   *
+   * @tags scheduling
+   * @name GetProblem
+   * @summary `GET /api/v1/scheduling/problems/{id}` — read the current state.
+   * @request GET:/api/v1/scheduling/problems/{problem_id}
+   */
+  getProblem = (problemId, params = {}) => this.http.request({
+    path: `/api/v1/scheduling/problems/${problemId}`,
+    method: "GET",
+    format: "json",
+    ...params
+  });
+  /**
+   * @description Retrieve the derived `scheduling.assignment` Ψ-terms produced by the most recent solve.  Returns an empty list when the problem has never been solved, or when the problem ID isn't known for this tenant.  Includes `free` cells (per the materialise decision) so consumers can residuate on them.
+   *
+   * @tags scheduling
+   * @name ListAssignments
+   * @summary `GET /api/v1/scheduling/problems/{id}/assignments`
+   * @request GET:/api/v1/scheduling/problems/{problem_id}/assignments
+   */
+  listAssignments = (problemId, params = {}) => this.http.request({
+    path: `/api/v1/scheduling/problems/${problemId}/assignments`,
+    method: "GET",
+    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 structurally infeasible cells (agent has a day-off on the day, is restricted to a different shift, or otherwise cannot occupy the slot) are silently ignored — the preference cannot fire when the agent cannot be there.  Preferences targeting **pinned** cells DO contribute to `total_score`: pins force the agent into the cell, so the preference is realised by the chosen schedule.
+   *
+   * @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
+  });
+  /**
+   * No description
+   *
+   * @tags scheduling
+   * @name RemovePin
+   * @summary `DELETE /api/v1/scheduling/problems/{id}/pins/{pin_id}`
+   * @request DELETE:/api/v1/scheduling/problems/{problem_id}/pins/{pin_id}
+   */
+  removePin = (problemId, pinId, params = {}) => this.http.request({
+    path: `/api/v1/scheduling/problems/${problemId}/pins/${pinId}`,
+    method: "DELETE",
+    ...params
+  });
+  /**
+   * No description
+   *
+   * @tags scheduling
+   * @name RemovePreference
+   * @summary `DELETE /api/v1/scheduling/problems/{id}/preferences/{preference_id}`
+   * @request DELETE:/api/v1/scheduling/problems/{problem_id}/preferences/{preference_id}
+   */
+  removePreference = (problemId, preferenceId, params = {}) => this.http.request({
+    path: `/api/v1/scheduling/problems/${problemId}/preferences/${preferenceId}`,
+    method: "DELETE",
+    ...params
+  });
+  /**
+   * @description Re-solve the stored snapshot: project it back into a domain `SchedulingProblem`, run the optimizer, and lift the per-cell trichotomy into `scheduling.assignment` Ψ-terms (idempotent — previous derived assignments for this problem are replaced). Returns only `status` and `total_score`; fetch the per-cell trichotomy via `/assignments`.
+   *
+   * @tags scheduling
+   * @name SolveProblem
+   * @summary `POST /api/v1/scheduling/problems/{id}/solve`
+   * @request POST:/api/v1/scheduling/problems/{problem_id}/solve
+   */
+  solveProblem = (problemId, params = {}) => this.http.request({
+    path: `/api/v1/scheduling/problems/${problemId}/solve`,
+    method: "POST",
+    format: "json",
+    ...params
+  });
 };
 
 // src/api-spec/generated/Admin.ts
@@ -20536,6 +20667,135 @@ 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)
+  };
+}
+function CreateSchedulingProblemRequestFromFrontToApi(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 CreateSchedulingProblemResponseFromApiToFront(dto) {
+  return {
+    problemId: dto.problem_id
+  };
+}
+function SolveSchedulingProblemResponseFromApiToFront(dto) {
+  return {
+    status: dto.status,
+    totalScore: dto.total_score
+  };
+}
+function SchedulingAssignmentsResponseFromApiToFront(dto) {
+  return {
+    totalScore: dto.total_score,
+    assignments: dto.assignments.map(AssignmentFromApiToFront)
+  };
+}
+function AddPinRequestFromFrontToApi(request) {
+  const dto = {
+    agent_id: request.agentId,
+    day: request.day,
+    shift: request.shift
+  };
+  if (request.role !== void 0) {
+    dto.role = request.role;
+  }
+  return dto;
+}
+function AddPinResponseFromApiToFront(dto) {
+  return {
+    pinId: dto.pin_id,
+    version: dto.version
+  };
+}
+function AddPreferenceRequestFromFrontToApi(request) {
+  return {
+    agent_id: request.agentId,
+    day: request.day,
+    shift: request.shift,
+    score: request.score
+  };
+}
+function AddPreferenceResponseFromApiToFront(dto) {
+  return {
+    preferenceId: dto.preference_id,
+    version: dto.version
+  };
+}
+function PinEntryFromApiToFront(dto) {
+  const entry = {
+    pinId: dto.pin_id,
+    agentId: dto.agent_id,
+    day: dto.day,
+    shift: dto.shift
+  };
+  if (dto.role !== void 0 && dto.role !== null) {
+    entry.role = dto.role;
+  }
+  return entry;
+}
+function PreferenceEntryFromApiToFront(dto) {
+  return {
+    preferenceId: dto.preference_id,
+    agentId: dto.agent_id,
+    day: dto.day,
+    shift: dto.shift,
+    score: dto.score
+  };
+}
+function SchedulingProblemFromApiToFront(dto) {
+  const problem = {
+    problemId: dto.problem_id,
+    days: dto.days,
+    shiftsPerDay: dto.shifts_per_day,
+    version: dto.version,
+    pins: dto.pins.map(PinEntryFromApiToFront),
+    preferences: dto.preferences.map(PreferenceEntryFromApiToFront),
+    totalScore: dto.total_score
+  };
+  if (dto.latest_solve_status !== void 0 && dto.latest_solve_status !== null) {
+    problem.latestSolveStatus = dto.latest_solve_status;
+  }
+  return problem;
+}
 
 // src/resources/scheduling.ts
 var SchedulingClient = class {
@@ -20566,6 +20826,223 @@ 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);
+  }
+  // ── Snapshot-driven endpoints (POST /scheduling/problems/*) ───────
+  /**
+   * Freeze the inline scheduling inputs into a `scheduling.problem`
+   * Ψ-term snapshot stored under the caller's tenant, and return the
+   * snapshot's `problemId`.  The endpoint does NOT solve — call
+   * {@link SchedulingClient.solveProblem} afterwards to compute the
+   * optimum, then {@link SchedulingClient.listAssignments} to fetch
+   * the per-cell trichotomy.
+   *
+   * @param request - same inline shape as
+   *   {@link SchedulingClient.optimize}.
+   * @returns the snapshot ID, useful for subsequent re-solves and
+   *   provenance lookups.
+   * @throws HTTP 400 on malformed input (duplicate agent IDs,
+   *   ambiguous pin role, unknown pin or preference agent ID,
+   *   role minima exceeding total demand, etc.).
+   *
+   * @remarks
+   * Re-solves read only the snapshot, so the optimum is reproducible
+   * and auditable from the moment the problem is created.  The
+   * snapshot persists across solves — pin a problem once, re-solve
+   * many times.
+   *
+   * @example
+   * ```typescript
+   * const { problemId } = await client.scheduling.createProblem({
+   *   agents: [{ id: 'alice', roles: ['icu'], maxAssignments: 3 }],
+   *   days: 7,
+   *   shiftsPerDay: 3,
+   *   demands: [{ day: 0, shift: 0, total: 1, roleMinimums: { icu: 1 } }],
+   *   preferences: [{ agentId: 'alice', day: 0, shift: 0, score: 5 }],
+   * });
+   * await client.scheduling.solveProblem(problemId);
+   * const { totalScore, assignments } =
+   *   await client.scheduling.listAssignments(problemId);
+   * ```
+   */
+  async createProblem(request) {
+    const response = await this.api.createProblem(
+      CreateSchedulingProblemRequestFromFrontToApi(request)
+    );
+    return CreateSchedulingProblemResponseFromApiToFront(response.data);
+  }
+  /**
+   * Re-solve a previously-stored snapshot, lift the per-cell
+   * trichotomy into `scheduling.assignment` Ψ-terms (idempotent —
+   * previously lifted assignments are replaced), and return the
+   * optimum's `totalScore`.
+   *
+   * @param problemId - the ID returned by
+   *   {@link SchedulingClient.createProblem}.
+   * @throws HTTP 404 when the problem doesn't exist for the caller's
+   *   tenant.  HTTP 400 for malformed problem IDs.
+   *
+   * @remarks
+   * Returns only `status` and `totalScore`; fetch the per-cell
+   * trichotomy with {@link SchedulingClient.listAssignments}.
+   * Re-running this method on the same `problemId` is safe — the
+   * lifted assignment terms are replaced atomically.
+   */
+  async solveProblem(problemId) {
+    const response = await this.api.solveProblem(problemId);
+    return SolveSchedulingProblemResponseFromApiToFront(response.data);
+  }
+  /**
+   * Retrieve the lifted `scheduling.assignment` Ψ-terms produced by
+   * the most recent solve.
+   *
+   * @param problemId - the ID returned by
+   *   {@link SchedulingClient.createProblem}.
+   * @throws HTTP 404 when the problem doesn't exist for the caller's
+   *   tenant.  HTTP 400 for malformed problem IDs.
+   *
+   * @remarks
+   * Returns one entry per `(agent, day, shift)` cell — including
+   * `free` cells, so consumers can residuate on cells the optimizer
+   * is indifferent about.  `assignments` is empty when the problem
+   * exists but hasn't been solved yet.
+   *
+   * `totalScore` mirrors the most recent solve's optimum value, or
+   * `0` when the problem hasn't been solved.
+   */
+  async listAssignments(problemId) {
+    const response = await this.api.listAssignments(problemId);
+    return SchedulingAssignmentsResponseFromApiToFront(response.data);
+  }
+  // ── Mutation methods on the live problem ──────────────────────────
+  /**
+   * Read the current state of a stored problem — its pins,
+   * preferences, version counter, and latest-solve metadata.
+   *
+   * @remarks
+   * Pin and preference entries carry stable IDs (`pinId`,
+   * `preferenceId`) — pass those to {@link SchedulingClient.removePin}
+   * / {@link SchedulingClient.removePreference} to delete them.
+   *
+   * @throws HTTP 404 when the problem doesn't exist for the
+   *   caller's tenant.
+   */
+  async getProblem(problemId) {
+    const response = await this.api.getProblem(problemId);
+    return SchedulingProblemFromApiToFront(response.data);
+  }
+  /**
+   * Append a pin to a stored problem.  Returns the pin's stable
+   * ID and the problem's new version.  Multiple pins on the same
+   * `(agent, day, shift)` are not deduplicated server-side; if you
+   * want at-most-one-pin-per-cell semantics, enforce it on the
+   * client by checking the pin entries from
+   * {@link SchedulingClient.getProblem} first.
+   *
+   * @throws HTTP 400 when the agent isn't on the problem's roster
+   *   or the (day, shift) is outside the grid.  HTTP 404 when the
+   *   problem doesn't exist for the caller's tenant.
+   */
+  async addPin(problemId, request) {
+    const response = await this.api.addPin(
+      problemId,
+      AddPinRequestFromFrontToApi(request)
+    );
+    return AddPinResponseFromApiToFront(response.data);
+  }
+  /**
+   * Remove a pin previously added via
+   * {@link SchedulingClient.addPin}.
+   *
+   * @throws HTTP 404 when the problem doesn't exist for the
+   *   tenant or the `pinId` doesn't match any current pin
+   *   (already removed, stale ID).
+   */
+  async removePin(problemId, pinId) {
+    await this.api.removePin(problemId, pinId);
+  }
+  /**
+   * Append a preference to a stored problem.  Same return shape as
+   * {@link SchedulingClient.addPin} — `preferenceId` is the stable
+   * handle for removal.  Multiple preferences targeting the same
+   * cell sum on the next solve.
+   */
+  async addPreference(problemId, request) {
+    const response = await this.api.addPreference(
+      problemId,
+      AddPreferenceRequestFromFrontToApi(request)
+    );
+    return AddPreferenceResponseFromApiToFront(response.data);
+  }
+  /**
+   * Remove a preference previously added via
+   * {@link SchedulingClient.addPreference}.
+   */
+  async removePreference(problemId, preferenceId) {
+    await this.api.removePreference(problemId, preferenceId);
+  }
 };
 
 // src/normalizers/osfql.ts