Package com.tnsai.annotations

Annotation Interface Config

@Documented @Retention(RUNTIME) @Target({}) public @interface Config
Points an agent or role class at its configuration file.

@Config is never placed on its own; it is the AgentSpec.config() or the RoleSpec.config() member: 


 @AgentSpec(config = @Config(path = "config/answerer.json"),
            knowledge = @Knowledge(name = "identity", path = "knowledge/bob.md"))
 public class AnswererAgent extends Agent { ... }

The file mirrors the @AgentSpec tree. Each level may carry llm and knowledge; roles sit under roles, keyed by their RoleSpec.name(): 


 {
   "llm": {"model": "llama3.1"},
   "knowledge": {"identity": {"path": "knowledge/bob-v2.md"}},
   "roles": {
     "AnswererRole": {
       "llm": {"temperature": 0.2},
       "knowledge": {"manual": {"path": "knowledge/manual.md",
                                "use": "DIRECT", "maxTokens": 4000}}
     }
   }
 }

A role's own file carries only llm and knowledge, at its top level.

Precedence

The most specific scope wins: an action's knowledge, then its role's, then its agent's. For a role, each field is taken from the first of: the role's own file, the roles section of its agent's file, the @RoleSpec annotation. A role class takes one roles section per run, the process unless ClassConfig.useBaseDirectory(java.nio.file.Path) starts runs: two agents giving the same role class different sections fail at agent initialization, naming both. An agent whose file has no section for a role it plays gives that role an empty section, so it conflicts with an agent that gives one.

A run file's Agents section, passed to ClassConfig.useBaseDirectory(java.nio.file.Path, String, String), keys an agent type by its simple or binary name and gives it this file's agent shape: llm, knowledge and roles. It sits above the class files, so the chain, lowest first, is: the agent's file, its roles section, the role's own file, the run file's agent section, that section's roles. It is read once per run: an edit applies at the next run. A role class takes one run file roles section per run, checked as the agent file's section is.

knowledge

An object keyed by knowledge name. Each entry takes the members of Knowledge other than name, with search as an object of Search members. Enum values are given by constant name.

  • A name a layer below declares is overridden member by member, search included: what the file gives wins, what it leaves out keeps the value of the layer below. The layers below a role's own file are the annotation and the roles section of its agent's file, so a name only that section gives is overridden the same way. An entry that changes use keeps a maxTokens or search from the layer below only when the new use applies to it, so a value a lower layer dropped does not come back.
  • A name no layer below declares is a full declaration. It follows the entries below, in name order.
  • Every entry is validated as an annotation entry is.

A relative FILE path an entry gives resolves against the base directory ClassConfig.useBaseDirectory(java.nio.file.Path) set, or against the working directory when none is set. An entry that leaves path out keeps the path of the layer below as that layer gave it: an annotation path stays relative to the working directory, and a path a lower file gave keeps the resolution that file applied. URL, blank and absolute paths are kept as written.

llm

The fields of the SCOP run file's LLM section: provider, model, temperature, maxTokens, endpoint, apiKeyEnv. Where a runtime resolves the LLM from these layers, each named field wins over the annotation and over the bridge's LLMConfigurationSource; the agent's file is overridden by its roles section, that by the role's own file, and the class files by the run file's Agents section in the chain above. A file sets fields and cannot clear one: an explicit null fails, so a field the annotation sets is kept unless the file gives another value.

Strictness

An unknown field, an explicit null, a name inside a knowledge entry, a missing file or a file that does not parse fails at agent initialization. A field left out is unset.

Trust

The file is trusted like the annotation: its paths are not confined to a root, and an apiKeyEnv it names is read from the environment. It is read once per class, again after ClassConfig.useBaseDirectory(java.nio.file.Path) starts a new run, and never shown to the model.

Since:
0.18.0
See Also:

  • Element Details

    • path

      String path
      The file. A relative path resolves against the base directory ClassConfig.useBaseDirectory(java.nio.file.Path) set, or against the working directory when none is set. Blank means the class has no configuration file.
      Returns:
      the file path
      Default:
      ""

    • select

      String select
      The part of the file this class reads, as a structural path in the grammar Knowledge.select() uses: the root is $ for JSON and $document[n] for YAML, counted from 1; .name, or ['name'] for a key that is not an identifier, steps into an object, [n] into an array, counted from 0. The selector names one node exactly: $.agents.AnswererAgent or $document[2].agents.AnswererAgent.

      Blank reads the whole file, and fails for a YAML file that holds more than one document. A selector that matches nothing fails at agent initialization.

      Returns:
      the selector, blank for the whole file
      Default:
      ""

    • format

      DocumentFormat format
      The file format: DocumentFormat.JSON, DocumentFormat.YAML, or DocumentFormat.AUTO to tell them apart by extension (.yaml and .yml read as YAML, anything else as JSON). Any other format fails at agent initialization.
      Returns:
      the format
      Default:
      AUTO