Class ClassToolProvider

java.lang.Object
ai.redouble.nucleo.tools.registry.ClassToolProvider
All Implemented Interfaces:
ToolProvider
public final class ClassToolProvider extends Object implements ToolProvider
ToolProvider that wraps a Class<? extends Tool>. Reads ToolName, ToolDescription, DisplayName, ToolWeight annotations. Schema is generated once via PojoResponseHandler and cached.

Equality is by wrapped class identity, so registering the same class twice produces the same provider key, supporting ToolRegistry's upsert-on-same-identity policy.

Since:
0.1 (2026-05-08)
Author:
Andrey Santrosyan

  • Method Details

    • of

      public static ClassToolProvider of(Class<? extends Tool> toolClass)
      Wraps a tool class. Constructs a fresh provider each call; the schema generation it pays for happens once per instance, and ToolRegistry's same-identity upsert keeps repeated registrations from stacking.

    • name

      public String name()
      Description copied from interface: ToolProvider
      Unique name within a registry. Used for LLM-facing tool identity.
      Specified by:
      name in interface ToolProvider

    • description

      public String description()
      Description copied from interface: ToolProvider
      Human/LLM readable description; truncation is the implementation's choice.
      Specified by:
      description in interface ToolProvider

    • schemaJson

      public String schemaJson()
      Description copied from interface: ToolProvider
      JSON-Schema bytes that go into the ToolDefinitionBlock schema field.
      Specified by:
      schemaJson in interface ToolProvider

    • weight

      public ToolWeight weight()
      Description copied from interface: ToolProvider
      Effective weight metadata.
      Specified by:
      weight in interface ToolProvider

    • displayName

      public String displayName()
      Description copied from interface: ToolProvider
      Display name (human-facing UI). Falls back to ToolProvider.name() when no override.
      Specified by:
      displayName in interface ToolProvider

    • actionVerb

      public String actionVerb()
      Description copied from interface: ToolProvider
      Action verb for status surfacing (e.g. "Searching"). Empty string when unset.
      Specified by:
      actionVerb in interface ToolProvider

    • readOnly

      public boolean readOnly()
      Description copied from interface: ToolProvider
      Whether invoking this tool leaves the environment unchanged. Mirrors ToolDescription.readOnly() for class-backed providers.

      The default is false because that is the correct answer for a provider that cannot know: an MCP server describes no such property, and request_tools admits arbitrary tools by construction. Both are genuinely mutating as far as the framework can establish, so the default is the truth rather than a compatibility fallback. A provider returns true only where something asserted it.

      Consumed by ReadOnlyPalette to bound a read-only thinker's palette structurally.

      Specified by:
      readOnly in interface ToolProvider

    • inputType

      public Class<?> inputType()
      Description copied from interface: ToolProvider
      Input POJO type, used for input-guardrail typing (instanceof matching).
      Specified by:
      inputType in interface ToolProvider

    • outputType

      public Class<?> outputType()
      Description copied from interface: ToolProvider
      Output POJO type, or null when the provider cannot know it. A class-backed provider reads it off Tool<I,O>; an MCP-bound provider wraps someone else's tool and has no Java output type, so it answers null.

      Only the published-schema path consumes this. Nothing model-facing does: a model is told what a tool takes, never what shape comes back, because the answer arrives as a tool result it reads directly.

      Specified by:
      outputType in interface ToolProvider

    • outputSchemaJson

      public String outputSchemaJson()
      Description copied from interface: ToolProvider
      JSON Schema of ToolProvider.outputType(), or null when there is no output type. Published as the MCP tool's outputSchema so a consumer knows what it is receiving.
      Specified by:
      outputSchemaJson in interface ToolProvider

    • toolClass

      public Class<? extends Tool> toolClass()
      Description copied from interface: ToolProvider
      Concrete Tool class produced by ToolProvider.create(Identifiable). Used by admission predicates and guardrail registries to test class-assignability without having to instantiate the tool. ClassToolProvider returns the wrapped class; MCP-bound providers return GenericMCPToolAdapter.class.
      Specified by:
      toolClass in interface ToolProvider

    • parseInput

      public Object parseInput(com.fasterxml.jackson.databind.JsonNode raw) throws CorrectableLLMException
      Description copied from interface: ToolProvider
      Parses LLM-emitted input (already converted to JsonNode upstream by ThinkingResponseHandler) into the typed input the tool's execute expects. Class-based providers convert via the framework JSON serializer; MCP-bound providers wrap the tree as an MCP input envelope without translation.
      Specified by:
      parseInput in interface ToolProvider
      Throws:
      CorrectableLLMException - when the LLM produced input the provider cannot parse; the LLM can correct and retry.

    • create

      public Tool<?,?> create(Identifiable parent) throws LLMReadableCheckedException
      Description copied from interface: ToolProvider
      Builds the Tool instance for execution. May throw when the underlying resource (e.g. an MCP client) cannot be obtained right now.
      Specified by:
      create in interface ToolProvider
      Throws:
      LLMReadableCheckedException

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object