Package com.tnsai.integration.scop

Record Class AgentConfiguration

java.lang.Object
java.lang.Record
com.tnsai.integration.scop.AgentConfiguration
public record AgentConfiguration(LLMOverrides shared, Map<String,AgentConfiguration.AgentSettings> agents) extends Record
Immutable trusted configuration fragment containing shared LLM settings and Agents entries keyed by actual Java type. It does not own instance names, files, class loading, role binding or filesystem permissions.

The host captures this snapshot and validates all type keys against its complete registered run types before any LLM call, source ingestion or action. A simple key must identify exactly one registered type; a qualified key must match its binary name. A simple key that names both an agent class and a role class, one with RoleSpec and no AgentSpec, selects the agent class, as in ClassConfig; a key that names only a role class selects it, as in 0.18.1. Two keys selecting the same class are rejected. Registration must be complete before validation, not assembled incrementally while agents execute.

Each Agents entry takes the shape of an agent's @Config file: llm, knowledge and roles. parse(org.json.JSONObject) checks that shape and decodes the llm; the host passes the section's text to ClassConfig.useBaseDirectory(ClassConfig.RunFile), which checks the contents of all three and applies them over the class's own configuration. validate(JSONObject, Collection) runs the same check on the host's sections, so a host can refuse an edited section before saving it.

The bridge then resolves, lowest first: the annotations, the shared() settings the host registers with SCOPBridge.llmConfigurationSource(LLMConfigurationSource), as name -> Optional.of(configuration.shared()), the class configuration files, the run file's type section and its roles section. The host registers shared(), not resolve(java.lang.Class<?>, java.util.Collection<java.lang.Class<?>>) .llm(), so the type's llm applies once, at the run level. resolve(java.lang.Class<?>, java.util.Collection<java.lang.Class<?>>) reads llm only: it gives neither knowledge nor roles, which reach an agent only through the section passed to ClassConfig.

Until 0.18.1 a host overlaid its own instance, file and explicit run layers on resolve(java.lang.Class<?>, java.util.Collection<java.lang.Class<?>>) .llm(), so they won over the type's entry. The LLMConfigurationSource a host registers now sits below the class configuration files and the run file's type section, so such layers no longer win over the type's llm; a setting that must win goes in the run file's section.

Since:
0.17.5

  • Constructor Details

    • AgentConfiguration

      public AgentConfiguration(LLMOverrides shared, Map<String,AgentConfiguration.AgentSettings> agents)
      Creates an instance of a AgentConfiguration record class.
      Parameters:
      shared - the value for the shared record component
      agents - the value for the agents record component

  • Method Details

    • parse

      public static AgentConfiguration parse(org.json.JSONObject sections)
      Parses only the optional LLM/Agents fragment. A generic host configuration adapter extracts those subtrees without interpreting their fields. Explicit null or a wrong subtree type is invalid, rather than an absent setting. Each Agents entry takes llm, knowledge and roles, each optional and an object; only llm is decoded here, and ClassConfig checks the contents of knowledge and roles.
      Parameters:
      sections - the fragment, with at most the LLM and Agents sections
      Returns:
      the parsed configuration
      Throws:
      IllegalArgumentException - if the fragment has another section, a section or entry is not an object, a type key is blank or padded, or an entry has another field or a field that is not an object; the error names the entry by its type, and one that gives an LLM setting such as temperature flat is told to move the setting under llm
      LLMConfigurationException - if the LLM section or an entry's llm holds an unknown or invalid field
      Since:
      0.17.5

    • validate

      public static void validate(org.json.JSONObject sections, Collection<Class<?>> knownTypes)
      Parses a host's sections and checks them against the complete registered types of its run. It checks the Agents section as ClassConfig.checkAgents(ClassConfig.RunFile) does, so a key naming a role class fails and the field names inside knowledge and inside each roles entry are checked; a misspelt role name is not, since a roles key is checked when the agent binds the roles it plays. It checks each roles entry's llm as parse(org.json.JSONObject) checks an entry's own llm, and then the type keys as validate(Collection) checks them. A host calls it with the sections it gave parse(org.json.JSONObject) once its run's types are complete, before the run starts, and with edited sections before it saves them. It neither starts a run nor changes the current one.
      Parameters:
      sections - the fragment, as parse(org.json.JSONObject) takes it
      knownTypes - the complete registered run types; a class that is not an agent type, such as the run's own class, may be among them
      Throws:
      IllegalArgumentException - if parse(org.json.JSONObject) refuses the fragment, if ClassConfig.checkAgents(ClassConfig.RunFile) refuses the Agents section, with its message, or if the type keys fail as validate(Collection) describes; a field of a roles entry's llm that is unknown, null or not of its JSON kind fails here
      LLMConfigurationException - as parse(org.json.JSONObject) throws it, or if a roles entry's llm holds a value of the right JSON kind that LLMOverrides.fromJson(org.json.JSONObject) refuses: a temperature outside 0 to 2, a maxTokens that is not a non-negative whole number within int range, a blank text field or an unknown or unroutable provider; the error names the entry and the role
      Since:
      0.18.2

    • validate

      public void validate(Collection<Class<?>> knownTypes)
      Validates every configured type key, including when the complete registry is empty. It checks the keys only; validate(JSONObject, Collection) checks the whole Agents section.
      Parameters:
      knownTypes - the complete registered run types
      Throws:
      IllegalArgumentException - if a key matches no registered type, a simple key matches more than one, unless exactly one of them is not a role class, or two keys select the same type
      Since:
      0.17.5

    • resolve

      public AgentConfiguration.AgentSettings resolve(Class<?> actualType, Collection<Class<?>> knownTypes)
      Resolves a registered actual type, independent of its instance name or construction order. All configured keys are validated even when they target another class. It reads llm only: an entry's knowledge and roles are neither checked nor given here, and reach an agent only through the section a host passes to ClassConfig.useBaseDirectory(ClassConfig.RunFile).
      Parameters:
      actualType - the agent's actual class
      knownTypes - the complete registered run types
      Returns:
      the shared LLM settings with the type's llm over them
      Throws:
      IllegalArgumentException - if actualType is not registered, or the keys fail as validate(Collection) describes
      Since:
      0.17.5

    • 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.

    • shared

      public LLMOverrides shared()
      Returns the value of the shared record component.
      Returns:
      the value of the shared record component

    • agents

      public Map<String,AgentConfiguration.AgentSettings> agents()
      Returns the value of the agents record component.
      Returns:
      the value of the agents record component