Package org.freeplane.api.ai

Class AiRequestOptions.Builder

java.lang.Object
org.freeplane.api.ai.AiRequestOptions.Builder
Enclosing class:
AiRequestOptions
public static class AiRequestOptions.Builder extends Object
Mutable builder for AiRequestOptions.

The builder records requested overrides only. It does not validate saved prompt names, profile names, provider names, or model availability; those are resolved when the request starts.

  • Constructor Details

    • Builder

      public Builder()

  • Method Details

    • timeout

      public AiRequestOptions.Builder timeout(Duration timeout)
      Sets the maximum request duration.
      Parameters:
      timeout - positive timeout; must not be null
      Returns:
      this builder

    • mode

      public AiRequestOptions.Builder mode(AiRequestMode mode)
      Sets the request execution mode.

      This is mandatory for askAi. If omitted for runAiPrompt, the saved prompt decides whether the request is shown in chat or hidden.

      Parameters:
      mode - requested execution mode, or null to leave it unset
      Returns:
      this builder

    • modelConfiguration

      public AiRequestOptions.Builder modelConfiguration(AiModelConfiguration modelConfiguration)
      Sets model-configuration overrides.

      Unset fields inside the configuration inherit independently. For a saved prompt, inherited fields come from the saved prompt; otherwise they come from the current model defaults. Use AiModelSelection.defaultModel() to explicitly request the default model instead of a saved prompt's model.

      Parameters:
      modelConfiguration - model overrides, or null to inherit all
      Returns:
      this builder

    • toolAvailability

      public AiRequestOptions.Builder toolAvailability(AiToolAvailability toolAvailability)
      Sets the AI tool availability requested for this call.
      Parameters:
      toolAvailability - requested availability, or null to inherit
      Returns:
      this builder

    • selectionOverride

      public AiRequestOptions.Builder selectionOverride(AiSelectionOverride selectionOverride)
      Sets the Freeplane map selection injected into the first prompt message.

      This changes only prompt composition. It does not change the user's UI selection and does not affect later tool results.

      Parameters:
      selectionOverride - selection override, or null to use the current selection
      Returns:
      this builder

    • systemMessage

      public AiRequestOptions.Builder systemMessage(String systemMessage)
      Sets a base system-message override while preserving Freeplane guidance.

      The value is trimmed when build() is called. Passing null clears the override and makes the request use the configured Freeplane AI system message. Passing a blank string stores "", which suppresses the configured base message but still lets Freeplane append generated guidance for the active tool level and other applicable chat context, such as map-selection handling, profile control, response format, or code-host use.

      This method clears the exact-system-message flag set by exactSystemMessage(String); the last system-message builder call wins.

      Parameters:
      systemMessage - base system message override, blank to suppress the configured base message, or null to inherit it
      Returns:
      this builder

    • exactSystemMessage

      public AiRequestOptions.Builder exactSystemMessage(String systemMessage)
      Sets the complete system message exactly as supplied by the caller.

      The value is trimmed when build() is called. When non-null, Freeplane treats the trimmed value, including "", as the complete system instruction and does not append generated guidance. The caller is then responsible for including any required instructions that Freeplane would normally add, such as tool-calling, map-selection, profile-control, response-format, or code-host instructions.

      Passing null clears the system-message override and clears the exact flag. systemMessage(String) also clears the exact flag; the last system-message builder call wins.

      Parameters:
      systemMessage - complete system message, blank for an empty exact system instruction, or null to inherit the configured Freeplane system message
      Returns:
      this builder

    • profile

      public AiRequestOptions.Builder profile(String name)
      Requests a saved assistant profile by name.

      The name is trimmed when build() is called. The profile is looked up when the request starts; missing, blank, or ambiguous names complete the request with a configuration error.

      Parameters:
      name - saved profile name
      Returns:
      this builder

    • profile

      public AiRequestOptions.Builder profile(String name, String message)
      Requests an inline assistant profile instruction.

      This overload does not look up a saved profile. The name and message are trimmed when build() is called. If the message is blank and the name is non-blank, Freeplane sends a profile marker for that name. If both are blank, no profile instruction is sent.

      Parameters:
      name - profile name to display in the instruction; null is treated as blank
      message - inline profile instruction; must not be null
      Returns:
      this builder

    • build

      public AiRequestOptions build()
      Builds immutable request options.
      Returns:
      immutable options
      Throws:
      NullPointerException - if timeout is unset
      IllegalArgumentException - if timeout is zero or negative