Package com.tnsai.integration.scop

Record Class LLMOverrides

java.lang.Object
java.lang.Record
com.tnsai.integration.scop.LLMOverrides
public record LLMOverrides(Optional<String> provider, Optional<String> model, OptionalDouble temperature, OptionalInt maxTokens, Optional<String> endpoint, Optional<String> apiKeyEnv) extends Record
A field-level overlay onto an LLMConfiguration.

Every field is optional so that "not overridden" is distinguishable from "overridden to a falsy value". This matters: temperature = 0.0 and maxTokens = 0 are legitimate settings that a plain float or int cannot tell apart from "absent".

Overlays compose with overlay(LLMOverrides) (the argument wins, field by field) and are materialised onto a base configuration with applyTo(LLMConfiguration). Fields the overlay does not name keep the base value.

Since:
0.16.4

  • Constructor Details

    • LLMOverrides

      public LLMOverrides(Optional<String> provider, Optional<String> model, OptionalDouble temperature, OptionalInt maxTokens, Optional<String> endpoint, Optional<String> apiKeyEnv)
      Creates an instance of a LLMOverrides record class.
      Parameters:
      provider - the value for the provider record component
      model - the value for the model record component
      temperature - the value for the temperature record component
      maxTokens - the value for the maxTokens record component
      endpoint - the value for the endpoint record component
      apiKeyEnv - the value for the apiKeyEnv record component

  • Method Details

    • none

      public static LLMOverrides none()
      An overlay that names no field; applying it leaves a configuration untouched.

    • builder

      public static LLMOverrides.Builder builder()
      A builder, so that callers name each field instead of relying on the positional record constructor (four of whose six components are Optional<String>).

    • fromJson

      public static LLMOverrides fromJson(org.json.JSONObject json)
      Decodes a trusted flat configuration object using the existing field-presence and builder validation rules. Absent fields stay absent; explicit null, unknown fields and numeric strings are errors. This does not read files, environment variables or credentials, or grant configuration authority.
      Parameters:
      json - fields supplied by the deployment's trusted configuration adapter
      Returns:
      immutable partial settings, suitable for overlay(LLMOverrides)
      Throws:
      LLMConfigurationException - if a field or value is invalid
      Since:
      0.17.5

    • annotationDefaults

      public static LLMConfiguration annotationDefaults()
      The configuration an LLMSpec that declares nothing resolves to — that is, LLMSpec's own member defaults. This is the base every overlay is applied onto, so a resolution in which no tier and no external source names a field yields exactly the annotation defaults.

    • fromAnnotation

      public static LLMOverrides fromAnnotation(com.tnsai.annotations.LLMSpec spec)
      Reads the fields an LLMSpec actually declares.

      A member is treated as declared when its value differs from the default LLMSpec declares for it. This is the only way to tell the two apart: @AgentSpec.llm() and @RoleSpec.llm() both default to @LLMSpec(), so every annotated class carries a full set of member values whether or not its author wrote any of them.

      Known blind spot: a member explicitly set to the value it already defaults to (temperature = 0.7f, maxTokens = 4096, provider = OLLAMA) is indistinguishable from an undeclared one and is reported as absent.

      Parameters:
      spec - the annotation member to read; null yields none()

    • overlay

      public LLMOverrides overlay(LLMOverrides higher)
      Composes two overlays. Fields higher names win; fields it leaves absent fall through to this overlay.
      Parameters:
      higher - the higher-precedence overlay

    • applyTo

      public LLMConfiguration applyTo(LLMConfiguration base)
      Materialises this overlay onto base. Fields this overlay does not name keep their base value.

    • routing

      public LLMOverrides routing()
      The fields that decide where a request goes and under whose credential: provider, model, endpoint, apiKeyEnv.

      They are meaningful only as a set. A model belongs to a provider, an endpoint speaks one provider's wire format, and an API key is issued by one provider. Mixing them across authors produces a configuration nobody wrote — a local model name sent to a hosted endpoint under that host's key.

    • tuning

      public LLMOverrides tuning()
      The fields that only tune sampling: temperature and maxTokens. These carry no routing meaning, so they compose across authors safely.

    • hasRouting

      public boolean hasRouting()
      Whether this overlay names any routing() field.

    • isEmpty

      public boolean isEmpty()
      Whether this overlay names no field at all.

    • describe

      public String describe()
      The names of the fields this overlay carries, for logging which settings an external source actually contributed — e.g. {model, temperature}.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • provider

      public Optional<String> provider()
      Returns the value of the provider record component.
      Returns:
      the value of the provider record component

    • model

      public Optional<String> model()
      Returns the value of the model record component.
      Returns:
      the value of the model record component

    • temperature

      public OptionalDouble temperature()
      Returns the value of the temperature record component.
      Returns:
      the value of the temperature record component

    • maxTokens

      public OptionalInt maxTokens()
      Returns the value of the maxTokens record component.
      Returns:
      the value of the maxTokens record component

    • endpoint

      public Optional<String> endpoint()
      Returns the value of the endpoint record component.
      Returns:
      the value of the endpoint record component

    • apiKeyEnv

      public Optional<String> apiKeyEnv()
      Returns the value of the apiKeyEnv record component.
      Returns:
      the value of the apiKeyEnv record component