Package org.freeplane.api.ai

Class AiRequestOptions

java.lang.Object
org.freeplane.api.ai.AiRequestOptions
public class AiRequestOptions extends Object
Immutable public options for script-facing AI requests.

The builder requires a positive timeout. All other options are request overrides. Leaving an option unset lets the request execution context choose its default; for saved prompts, unset fields inherit the saved prompt configuration where such a value exists.

askAi requires AiRequestOptions.Builder.mode(AiRequestMode). For runAiPrompt, a missing mode uses the saved prompt's visibility setting.

Since:
1.13.3

  • Method Details

    • builder

      public static AiRequestOptions.Builder builder()
      Creates a new request-options builder.
      Returns:
      a builder whose timeout must be set before AiRequestOptions.Builder.build() is called

    • getTimeout

      public Duration getTimeout()
      Returns the request timeout.

      The timeout is required and must be positive. If it expires before the request completes, the callback receives AiRequestStatus.TIMED_OUT.

      Returns:
      the positive timeout

    • getMode

      public AiRequestMode getMode()
      Returns the requested execution mode, or null when unset.

      askAi requires a non-null mode. runAiPrompt accepts null and derives the mode from the saved prompt.

      Returns:
      the requested mode, or null

    • getModelConfiguration

      public AiModelConfiguration getModelConfiguration()
      Returns model overrides, or null when all model fields are inherited.
      Returns:
      model-configuration overrides, or null

    • getToolAvailability

      public AiToolAvailability getToolAvailability()
      Returns the requested tool-availability level, or null when unset.

      For direct askAi requests, unset tool availability is treated as AiToolAvailability.CURRENT. Saved prompt requests inherit the saved prompt value when this option is unset.

      Returns:
      requested tool availability, or null

    • getSelectionOverride

      public AiSelectionOverride getSelectionOverride()
      Returns a prompt-time selection override, or null to use the current Freeplane selection.
      Returns:
      selection override, or null

    • getSystemMessage

      public String getSystemMessage()
      Returns the base system message override, or null to use the configured Freeplane AI system message.

      The builder trims this value. A blank but non-null value therefore becomes ""; this deliberately suppresses the configured base system message. Unless isSystemMessageExact() is true, Freeplane still appends generated system guidance for the active tool level and other applicable chat context, such as map-selection handling, profile control, response format, or code-host use.

      Returns:
      the trimmed base system message override, or null

    • isSystemMessageExact

      public boolean isSystemMessageExact()
      Returns whether getSystemMessage() is the complete system message.

      When this flag is true, Freeplane sends the trimmed system-message value as the full system instruction and does not append generated guidance. Use AiRequestOptions.Builder.exactSystemMessage(String) only when the caller supplies all required instruction text explicitly. A blank exact system message is allowed and produces an empty system instruction. Passing null to exactSystemMessage clears both the override and this flag.

      Returns:
      true when the system message is exact

    • getProfileName

      public String getProfileName()
      Returns the requested assistant profile name, or null when no profile request was configured.
      Returns:
      trimmed profile name, possibly empty, or null

    • getProfileMessage

      public String getProfileMessage()
      Returns the inline assistant profile instruction, or null when getProfileName() should be resolved as a saved profile name.
      Returns:
      trimmed inline profile instruction, possibly empty, or null