Package net.thevpc.naru.ext.models

Class NaruModelProtocolBase

java.lang.Object
net.thevpc.naru.ext.models.NaruModelProtocolBase
All Implemented Interfaces:
NaruModelProtocol
Direct Known Subclasses:
NaruModelProtocolAnthropicCompat, NaruModelProtocolGeminiNative, NaruModelProtocolOllamaNative, NaruModelProtocolOllamaOpenApiCompat, NaruModelProtocolOpenAICompat
public class NaruModelProtocolBase extends Object implements NaruModelProtocol

  • Field Details

  • Constructor Details

  • Method Details

    • provider

      public NaruModelProvider provider()

    • apiKey

      protected String apiKey(NaruTask task)

    • apiKeyConfigKey

      protected String apiKeyConfigKey()

    • parseXmlLikeToolCall

      public static NaruToolCall parseXmlLikeToolCall(String input)

    • url

      protected String url(NaruTask task, Map<String,net.thevpc.nuts.elem.NElement> env)

    • chatPath

      protected String chatPath(NaruTask task, Map<String,net.thevpc.nuts.elem.NElement> env)
      The endpoint to POST to, relative to the base url.

      Overridable because some wire formats put the model in the path (models/gemini-2.5-pro:generateContent) rather than in the body, which a fixed path cannot express.

    • connectTimeout

      protected net.thevpc.nuts.time.NDuration connectTimeout(NaruTask task, Map<String,net.thevpc.nuts.elem.NElement> env)

    • readTimeout

      protected net.thevpc.nuts.time.NDuration readTimeout(NaruTask task, Map<String,net.thevpc.nuts.elem.NElement> env)

    • preprocessRequest

      protected NaruModelRequest preprocessRequest(NaruModelRequest mrequest, NaruTask task)

    • classifyStatus

      protected String classifyStatus(net.thevpc.nuts.net.NHttpResponse response, AtomicReference<net.thevpc.nuts.time.NDuration> dynamicRetryAfter)
      Classifies a response status into "proceed" or "this attempt failed".

      Shared by the batched and the streamed path so that a 401, a 429 and a retryable 503 mean the same thing either way. Duplicating this is how a streaming client ends up retrying a 400 forever, or ignoring a 429 that the batched path honours.

      On a 5xx failFast is called so a retry does not have to drain an error page before reusing the connection.

      Parameters:
      dynamicRetryAfter - collects a server-sent Retry-After when one is present, so the retry policy can honour it
      Returns:
      null when the response should be read normally, otherwise the error body for the caller to log and report

    • prepareRequest

      protected void prepareRequest(net.thevpc.nuts.net.NHttpRequest request, net.thevpc.nuts.elem.NElement body, NaruTask task)

    • serialize

      protected net.thevpc.nuts.elem.NElement serialize(NaruModelRequest request, NaruCachePlanView plan, NaruTask task)
      Serialise with the cache plan when the provider's serializer understands one, and otherwise fall back to the plain three-argument call.

      Degrading silently rather than throwing is deliberate: a provider can declare caching support while reusing a shared serializer that predates it, and a user should get uncached-but-working behaviour instead of an error. NaruCachePlanView.none() keeps the emitted body identical to what a non-segmented request always produced.

    • serialize

      protected net.thevpc.nuts.elem.NElement serialize(NaruModelRequest request, NaruCachePlanView plan, NaruTask task, boolean stream)
      Serialise, adding the streaming flag when the body is going to be read incrementally.

    • onResponseReceived

      protected void onResponseReceived(net.thevpc.nuts.net.NHttpResponse response, NaruTask task)

    • maxRetries

      protected int maxRetries(NaruTask task, Map<String,net.thevpc.nuts.elem.NElement> env)

    • retryPeriod

      protected net.thevpc.nuts.time.NDuration retryPeriod(NaruTask task, Map<String,net.thevpc.nuts.elem.NElement> env)

    • chat

      public NaruResponse chat(NaruModelRequest mrequest, NaruTask task)
      Specified by:
      chat in interface NaruModelProtocol

    • providerName

      public String providerName()
      Specified by:
      providerName in interface NaruModelProtocol

    • streamChat

      protected NaruResponse streamChat(NaruModelRequest mrequest, NaruTask task, NaruStreamResponseParser parser)
      Runs a streamed call, retrying only while nothing has been delivered.

      Retrying a stream that has already emitted tokens would deliver them twice: the renderer has already drawn them and the transcript has already recorded them, and there is no way to un-send bytes to a third party. So a retry is allowed only while the attempt produced no chunk at all, which is exactly the case a retry fixes -- a connection refused, a 503 before the first token. Once anything has been delivered, the failure is reported.

      Parameters:
      parser - consumes events in order and assembles the response

    • commitCacheState

      protected void commitCacheState(NaruModelRequest request, NaruCachePlanView plan, NaruCachingMode mode, NaruTask task)
      Remember the prefix this turn actually sent.

      Overridable so a provider with a stateful cache can record the server's resource id instead. Any failure here is swallowed: losing a cache hint costs tokens, and must never cost the response the user is waiting for.

    • parseResponse

      protected NaruResponse parseResponse(String json)

    • getCapabilities

      public NaruModelCapabilities getCapabilities()
      Specified by:
      getCapabilities in interface NaruModelProtocol