@kortexya/reasoninglayer 0.21.0 → 0.22.1

package/dist/index.cjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "0.21.0";
+var SDK_VERSION = "0.22.1";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -7390,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,7 +7455,35 @@ var Scheduling = class {
     ...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.
+   * 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
@@ -7422,6 +7498,46 @@ var Scheduling = class {
     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
@@ -20581,6 +20697,122 @@ function SchedulingOptimizeResponseFromApiToFront(dto) {
     assignments: dto.assignments.map(AssignmentFromApiToFront)
   };
 }
+function CreateSchedulingProblemRequestFromFrontToApi(request) {
+  const hasInline = request.agents !== void 0;
+  const hasRefs = request.agentIds !== void 0;
+  if (hasInline && hasRefs) {
+    throw new Error(
+      "CreateSchedulingProblemRequest: supply exactly one of `agents` (inline) or `agentIds` (TermId refs), not both"
+    );
+  }
+  if (!hasInline && !hasRefs) {
+    throw new Error(
+      "CreateSchedulingProblemRequest: must supply either `agents` (inline) or `agentIds` (TermId refs)"
+    );
+  }
+  const dto = {
+    days: request.days,
+    shifts_per_day: request.shiftsPerDay,
+    demands: request.demands.map(ShiftDemandFromFrontToApi)
+  };
+  if (request.agents !== void 0) {
+    dto.agents = request.agents.map(AgentSpecFromFrontToApi);
+  }
+  if (request.agentIds !== void 0) {
+    dto.agent_ids = request.agentIds;
+  }
+  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 {
@@ -20675,6 +20907,159 @@ var SchedulingClient = class {
     );
     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