Timefold Solver Feasibility Gate

id: timefold-solver-feasibility-gate
namespace: company.team
description: |
  Submit an optimization dataset to the Timefold Platform on a
  schedule, wait for the solver to finish, classify the returned score
  as FEASIBLE, INFEASIBLE, or UNREACHABLE by checking for hard
  constraint violations, log clean solves, and alert Slack the moment
  a solution breaks a hard constraint or the platform cannot be
  reached.

inputs:
  - id: model_type
    type: SELECT
    defaults: "EMPLOYEE_SCHEDULING"
    values:
      - "EMPLOYEE_SCHEDULING"
      - "FIELD_SERVICE_ROUTING"
    displayName: "Timefold Model"
    description: "Which Timefold Platform model to solve with; determines the REST
      resource the dataset is submitted to."
  - id: model_input_json
    type: STRING
    defaults: '{"employees":[{"id":"Alice","skills":[{"id":"nursing"}]}],"shifts":[{"id":"SHIFT-001","start":"2027-02-01T08:00:00Z","end":"2027-02-01T16:00:00Z","requiredSkills":["nursing"]}]}'
    displayName: "Model Input (JSON)"
    description: "JSON string for the modelInput dataset, following the selected
      model's schema (employees/shifts for EMPLOYEE_SCHEDULING, vehicles/visits
      for FIELD_SERVICE_ROUTING)."
  - id: solve_duration
    type: STRING
    defaults: "PT15S"
    displayName: "Solve Duration"
    description: "ISO-8601 duration the platform solver spends on this dataset
      before returning."

triggers:
  - id: timefold_feasibility_gate_schedule
    type: io.kestra.plugin.core.trigger.Schedule
    description: "Resolve and classify a fresh solve every 6 hours."
    cron: "0 */6 * * *"
    disabled: true
    inputs:
      model_type: "EMPLOYEE_SCHEDULING"
      solve_duration: "PT15S"

tasks:
  - id: submit_and_solve
    type: io.kestra.plugin.timefold.Solve
    description: "Submit the dataset to the Timefold Platform and wait for the
      solver to finish, returning solverStatus and score. fetchType is NONE
      since this gate only needs the score, not the full modelOutput."
    apiKey: "{{ secret('TIMEFOLD_API_KEY') }}"
    model: "{{ inputs.model_type }}"
    modelInput: "{{ inputs.model_input_json }}"
    solveDuration: "{{ inputs.solve_duration }}"
    wait: true
    fetchType: NONE
    allowFailure: true

  - id: classify_solution_feasibility
    type: io.kestra.plugin.core.debug.Return
    description: "Classify UNREACHABLE when no score was returned, INFEASIBLE when
      the score reports any hard constraint violations, otherwise FEASIBLE.
      Timefold formats score as e.g. 0hard/0medium/-3603soft, so a feasible
      solution always starts with 0hard."
    format: "{{ outputs.submit_and_solve.score is defined ?
      (outputs.submit_and_solve.score starts with '0hard' ? 'FEASIBLE' :
      'INFEASIBLE') : 'UNREACHABLE' }}"

  - id: route_by_feasibility
    type: io.kestra.plugin.core.flow.Switch
    description: "Log a quiet confirmation when the solution is feasible, page Slack
      when a hard constraint is broken, or page Slack when the platform could
      not be reached."
    value: "{{ outputs.classify_solution_feasibility.value }}"
    cases:
      "FEASIBLE":
        - id: log_feasible
          type: io.kestra.plugin.core.log.Log
          message: "Timefold solve for {{ inputs.model_type }} is feasible, score {{
            outputs.submit_and_solve.score }}."
      "INFEASIBLE":
        - id: alert_infeasible
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {
              "text": "Timefold sentinel INFEASIBLE: solve for model {{ inputs.model_type }} (job {{ outputs.submit_and_solve.jobId }}) returned score {{ outputs.submit_and_solve.score }}, which reports at least one hard constraint violation. Execution {{ execution.id }}."
            }
      "UNREACHABLE":
        - id: alert_unreachable
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          url: "{{ secret('SLACK_WEBHOOK_URL') }}"
          payload: |
            {
              "text": "Timefold sentinel UNREACHABLE: no score was returned for model {{ inputs.model_type }} (invalid API key, platform outage, or solve timed out before requestTimeout). Execution {{ execution.id }}."
            }
    defaults:
      - id: log_unclassified
        type: io.kestra.plugin.core.log.Log
        message: "Completed Timefold feasibility check for {{ inputs.model_type }} with
          status: {{ outputs.classify_solution_feasibility.value }}"

  - id: log_audit_status
    type: io.kestra.plugin.core.log.Log
    description: "Post-audit status line recorded on every run regardless of branch,
      for a continuous feasibility trend in the execution history."
    message: "Timefold feasibility audit: model={{ inputs.model_type }}, jobId={{
      outputs.submit_and_solve.jobId }}, status={{
      outputs.classify_solution_feasibility.value }}, execution={{ execution.id
      }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: "Alert Slack when the gate flow itself fails, so a broken check
      never silently stops auditing solver feasibility."
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {
        "text": "Timefold feasibility gate flow {{ flow.id }} FAILED (execution {{ execution.id }}). Feasibility status for model {{ inputs.model_type }} is now unknown; check the task logs and the Timefold Platform manually."
      }

outputs:
  - id: status
    type: STRING
    value: "{{ outputs.classify_solution_feasibility.value }}"