Package dev.agenor.core.dialogue

Interface CommitmentTracker

All Known Implementing Classes:
DefaultCommitmentTracker
public interface CommitmentTracker
Tracks and manages commitments across conversations.
Since:
0.5.0

  • Method Details

    • createFromMessage

      Commitment createFromMessage(DialogueMessage message)
      Creates a new commitment from a dialogue message.
      Parameters:
      message - the message that creates the commitment (e.g., REQUEST, AGREE)
      Returns:
      the created commitment

    • updateFromResponse

      void updateFromResponse(String commitmentId, DialogueMessage response)
      Updates a commitment based on a response message.
      Parameters:
      commitmentId - the commitment to update
      response - the response message (e.g., INFORM, FAILURE)

    • get

      Optional<Commitment> get(String commitmentId)
      Retrieves a commitment by ID.
      Parameters:
      commitmentId - the commitment ID
      Returns:
      the commitment if found

    • getByMessageId

      Optional<String> getByMessageId(String messageId)
      Retrieves the ID of the commitment created by a given message.

      Used to correlate an incoming reply with the commitment its original message created, so that the commitment can be advanced by updateFromResponse(String, DialogueMessage).

      Parameters:
      messageId - the ID of the message that created the commitment; may be null
      Returns:
      the commitment ID if that message created one
      Since:
      0.26.0

    • getActiveAsPerformer

      List<Commitment> getActiveAsPerformer(String agentId)
      Gets all active commitments where the agent is the performer.
      Parameters:
      agentId - the agent ID
      Returns:
      list of active commitments to fulfill

    • getActiveAsRequester

      List<Commitment> getActiveAsRequester(String agentId)
      Gets all active commitments where the agent is the requester.
      Parameters:
      agentId - the agent ID
      Returns:
      list of active commitments awaiting fulfillment

    • checkViolations

      List<Commitment> checkViolations()
      Checks for commitments that have exceeded their deadline.
      Returns:
      list of violated commitments

    • cancel

      void cancel(String commitmentId, String reason)
      Cancels a commitment (by debtor).
      Parameters:
      commitmentId - the commitment to cancel
      reason - optional reason for cancellation

    • release

      void release(String commitmentId)
      Releases a commitment (by creditor).
      Parameters:
      commitmentId - the commitment to release

    • cleanup

      default int cleanup(Duration olderThan)
      Removes commitments that have reached a terminal state and are older than the given duration.

      Commitments outlive the message exchange that created them so that they remain observable after the fact; without a periodic sweep they accumulate for the whole lifetime of the agent. Implementations backed by a store with its own expiry may leave this as the default no-op.

      Parameters:
      olderThan - retention window measured from the commitment's creation time; Duration.ZERO removes every terminated commitment
      Returns:
      the number of commitments removed
      Since:
      0.26.0