Package org.mockserver.client

Class LlmConversationBuilder

java.lang.Object
org.mockserver.client.LlmConversationBuilder
public class LlmConversationBuilder extends Object
Builder for multi-turn LLM conversation mocks with optional per-session isolation.

Each turn() block produces one Expectation with scenario-based state advancement. On applyTo(MockServerClient), all turn expectations are registered as a group sharing a single auto-generated scenario name.

Example: 

 conversation()
     .withPath("/v1/messages")
     .withProvider(Provider.ANTHROPIC)
     .isolateBy(IsolationSource.header("x-session-id"))
     .turn()
         .whenTurnIndex(0)
         .respondingWith(completion().withToolCall(toolUse("search").withArguments("{}")))
     .andThen()
     .turn()
         .whenContainsToolResultFor("search")
         .respondingWith(completion().withText("The answer is 42."))
     .applyTo(mockServerClient);

  • Method Details

    • conversation

      public static LlmConversationBuilder conversation()
      Entry point for building a multi-turn LLM conversation mock.
      Returns:
      a new LlmConversationBuilder

    • withPath

      public LlmConversationBuilder withPath(String path)

    • withProvider

      public LlmConversationBuilder withProvider(Provider provider)

    • withModel

      public LlmConversationBuilder withModel(String model)

    • isolateBy

      public LlmConversationBuilder isolateBy(IsolationSource source)
      Set isolation source for per-session state. When set, the isolation key is extracted from each inbound request (header, query parameter, or cookie) and used to maintain independent scenario state per value.
      Parameters:
      source - the isolation source descriptor
      Returns:
      this builder

    • turn

      public TurnBuilder turn()
      Start defining a new turn in the conversation.
      Returns:
      a TurnBuilder for configuring this turn's match predicates and response

    • applyTo

      public Expectation[] applyTo(MockServerClient client)
      Build all turn expectations and register them with the MockServerClient.
      Parameters:
      client - the MockServerClient to register with
      Returns:
      the created expectations

    • build

      public Expectation[] build()
      Build all turn expectations without registering them.
      Returns:
      the array of expectations, one per turn

    • decodeIsolationSource

      public static IsolationSource decodeIsolationSource(String scenarioName)
      Decode the isolation source from a scenario name that contains the isolation marker. Delegates to LlmScenarioNames.decodeIsolationSource(String).

    • baseScenarioName

      public static String baseScenarioName(String scenarioName)
      Extract the base scenario name (without isolation marker suffix) from a full scenario name. Delegates to LlmScenarioNames.baseScenarioName(String).