Package org.machanism.machai.gw.processor

Class Episodes

java.lang.Object
org.machanism.machai.gw.processor.Episodes
public class Episodes extends Object
Maintains an ordered collection of act episode prompts and provides execution helpers that support several playback strategies.

Supported functionality:

Example: regular order execution 

 Episodes episodes = new Episodes(actProcessor);
 episodes.setName("demo-act");
 episodes.setEpisodes(List.of(
                "# Introduction\nWelcome to the show!",
                "# Recap\nLast time on our show..."));

 episodes.regularOrder(1, (id, prompt) -> executor.run(id, prompt));

Example: executing only a selected subset 

 episodes.setSelectedEpisodes(List.of(2));
 if (!episodes.isRegularOrder()) {
        episodes.requestedOrder((id, prompt) -> executor.run(id, prompt));
 }

  • Field Details

    • HEADER_MARKER

      private static final String HEADER_MARKER
      See Also:

    • logger

      private static final org.slf4j.Logger logger
      Logger for documentation input processing events.

    • episodes

      private List<String> episodes
      Ordered list of act episode prompts to execute.

    • selectedEpisodes

      private List<Integer> selectedEpisodes
      Explicitly selected 1-based episode identifiers.

    • name

      private String name
      Logical act name associated with the episodes.

    • actProcessor

      private ActProcessor actProcessor

  • Constructor Details

  • Method Details

    • setSelectedEpisodes

      public void setSelectedEpisodes(List<Integer> selectedEpisodeIds)
      Sets the list of explicitly requested episode identifiers.
      Parameters:
      selectedEpisodeIds - 1-based episode identifiers to execute
      Throws:
      IllegalArgumentException - if any identifier is outside the available episode range

    • getEpisodeIdByName

      private int getEpisodeIdByName(String episodeName)
      Returns the 1-based index of the episode whose prompt text contains a heading that matches the specified episode name.

      Scans each episode's prompt text, extracts the first line that appears between the heading marker "# " and the next newline character, trims any leading or trailing whitespace, and compares it to the provided episodeName. If a match is found, the corresponding episode index is returned.

      Example: 

       episodes.get(0): "# Introduction\nWelcome to the show!"
 episodes.get(1): "# Recap\nLast time on our show..."

 lookup for "Recap" returns 2
 lookup for "Introduction" returns 1
      Parameters:
      episodeName - the heading text to match (e.g., "Recap")
      Returns:
      the 1-based index of the matching episode
      Throws:
      EpisodeNotFoundException - if no episode with the specified heading exists

    • getEpisodeName

      private String getEpisodeName(int episodeId)
      Extracts and returns the episode name (heading) from the prompt text of the episode at the specified index.

      Retrieves the episode prompt at index episodeId, extracts the substring between the first occurrence of the heading marker "#" and the next newline character, and trims any leading or trailing whitespace. If the extracted heading is empty after trimming, null is returned.

      Example: 

       episodes.get(0): "# Introduction\nWelcome to the show!"
 lookup for episode id 1 returns "Introduction"
      Parameters:
      episodeId - the 1-based index of the episode
      Returns:
      the trimmed episode name, or null if no heading is found or the heading is empty

    • regularOrder

      public void regularOrder(Integer startEpisodeId, BiFunction<Integer,String,String> func)
      Executes episodes in regular order starting from the supplied 1-based index while honoring repeat and move requests.
      Parameters:
      startEpisodeId - starting 1-based episode index
      func - callback used to execute an episode

    • requestedOrder

      public int requestedOrder(BiFunction<Integer,String,String> func)
      Executes only the explicitly selected episodes in their requested order.
      Parameters:
      func - callback used to execute an episode
      Returns:
      the last processed episode identifier

    • getEpisodeId

      public Integer getEpisodeId(Integer requestedEpisodeId, MoveToEpisodeException e)
      Resolves the next episode index from a move request exception.
      Parameters:
      requestedEpisodeId - current fallback episode index
      e - exception describing the requested move
      Returns:
      resolved 1-based episode index

    • logEpisodeHeader

      private void logEpisodeHeader(int episodeId, int iteration, String msg)
      Logs a formatted episode banner for the current execution step.
      Parameters:
      episodeId - 1-based episode index
      iteration - current iteration number for the same episode
      msg - banner prefix (for example "Start" or "End")

    • setEpisodes

      public void setEpisodes(List<String> episodes)
      Replaces the current ordered episode list.
      Parameters:
      episodes - episode prompts to execute

    • getEpisodes

      public List<String> getEpisodes()
      Returns the configured episode prompts.
      Returns:
      configured episode prompt list

    • isRegularOrder

      public boolean isRegularOrder()
      Returns whether no explicit episode subset has been selected.
      Returns:
      true when regular order should be used

    • size

      public int size()
      Returns the number of configured episodes.
      Returns:
      episode count

    • getActInformation

      public Map<String,Object> getActInformation(int episodeId)
      Returns episode information as a map suitable for serialization.
      • ACT_NAME: The name of the act.
      • EPISODES: An array of episode objects, each with ID and EPISODE_NAME.
      • CURRENT_EPISODE_ID: The currently selected episode ID.
      Parameters:
      episodeId - the ID of the current episode
      Returns:
      a Map containing act and episode information; it may be converted to a JsonNode by callers when required

    • getName

      public String getName()
      Returns the act name associated with these episodes.
      Returns:
      act name

    • setName

      public void setName(String name)
      Sets the act name associated with these episodes.
      Parameters:
      name - act name