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
      Prefix that identifies a first-level Markdown episode heading.
      See Also:

    • logger

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

    • episodePrompts

      private List<String> episodePrompts
      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
      Processor that receives the result produced by each completed episode.

  • Constructor Details

    • Episodes

      public Episodes(ActProcessor actProcessor)
      Creates an episode collection whose execution results are recorded by the supplied processor.
      Parameters:
      actProcessor - processor that receives completed episode results

  • 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)
      Finds the 1-based identifier of the episode with the supplied heading.
      Parameters:
      episodeName - heading name to locate
      Returns:
      the matching 1-based episode identifier
      Throws:
      EpisodeNotFoundException - if no episode has the requested heading

    • getEpisodeName

      private String getEpisodeName(int episodeId)
      Extracts an episode's first-level Markdown heading, excluding optional YAML-style front matter.
      Parameters:
      episodeId - 1-based identifier of the episode to inspect
      Returns:
      the normalized heading text, or null when no heading exists
      Throws:
      IndexOutOfBoundsException - if the identifier does not address an episode

    • 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
      Throws:
      IndexOutOfBoundsException - if a requested episode index is invalid

    • executeRegularEpisodes

      private Integer executeRegularEpisodes(int startEpisodeId, BiFunction<Integer,String,String> func)
      Executes consecutive episodes until completion or a move request changes the next episode to execute.
      Parameters:
      startEpisodeId - 1-based identifier at which execution begins
      func - callback used to execute each episode
      Returns:
      the requested destination after a move, or null on completion
      Throws:
      IndexOutOfBoundsException - if an episode identifier is invalid
      EpisodeNotFoundException - if a named move destination does not exist

    • 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, or 0 when none are selected
      Throws:
      IndexOutOfBoundsException - if a selected episode identifier is invalid

    • executeEpisodeWithRepeats

      private void executeEpisodeWithRepeats(int episodeId, BiFunction<Integer,String,String> func)
      Executes an episode repeatedly until its callback completes without asking for another iteration.
      Parameters:
      episodeId - 1-based identifier of the episode to execute
      func - callback used to execute the episode
      Throws:
      IndexOutOfBoundsException - if the identifier does not address an episode

    • executeEpisode

      private boolean executeEpisode(int episodeId, int iteration, BiFunction<Integer,String,String> func)
      Runs one iteration of an episode and records its result when completed.
      Parameters:
      episodeId - 1-based identifier of the episode to execute
      iteration - current execution iteration, starting at 1
      func - callback used to execute the episode
      Returns:
      true when the iteration completed, or false when it requested a repeat
      Throws:
      IndexOutOfBoundsException - if the identifier does not address an episode

    • logResult

      private void logResult(String perform)
      Logs a nonblank execution result using the standard output prefix.
      Parameters:
      perform - result returned by an episode callback

    • getEpisodeId

      public Integer getEpisodeId(Integer requestedEpisodeId, MoveToEpisodeException exception)
      Resolves the next episode index from a move request exception.
      Parameters:
      requestedEpisodeId - current fallback episode index
      exception - exception describing the requested move
      Returns:
      resolved 1-based episode index
      Throws:
      EpisodeNotFoundException - if the requested episode name does not exist

    • logEpisodeHeader

      private void logEpisodeHeader(int episodeId, int iteration, String msg)
      Logs a visual boundary around an episode execution when episode or iteration information is useful.
      Parameters:
      episodeId - 1-based identifier of the episode being logged
      iteration - current execution iteration
      msg - boundary label, such as Start or End
      Throws:
      IndexOutOfBoundsException - if the identifier does not address an episode

    • setEpisodes

      public void setEpisodes(List<String> episodes)
      Replaces the ordered prompts available for execution.
      Parameters:
      episodes - ordered list of episode prompts

    • getEpisodes

      public List<String> getEpisodes()
      Returns the ordered episode prompts.
      Returns:
      ordered list of episode prompts

    • isRegularOrder

      public boolean isRegularOrder()
      Determines whether all episodes should execute in their natural order.
      Returns:
      true if no explicit episode selection exists; otherwise false

    • size

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

    • getActInformation

      public Map<String,Object> getActInformation(int episodeId)
      Builds metadata describing every configured episode and the current episode.
      Parameters:
      episodeId - 1-based identifier of the current episode
      Returns:
      map containing episode metadata and the current episode identifier

    • getName

      public String getName()
      Returns the logical name associated with this act.
      Returns:
      act name, or null when no name has been assigned

    • setName

      public void setName(String name)
      Assigns the logical name associated with this act.
      Parameters:
      name - act name to assign