Package com.tnsai.llm.observability

Record Class ToolSurface

java.lang.Object

java.lang.Record

com.tnsai.llm.observability.ToolSurface

public record ToolSurface(List<String> toolNames, List<String> toolSchemas, String surfaceHash)
extends Record

Snapshot of the tool set advertised to the LLM on one call (issue #79).

surfaceHash is a stable SHA-256 fingerprint derived from sorted tool names + their schemas. Two calls with the same tool set (same names, same JSON schemas, any order) produce the same hash — letting operators spot prompt-caching opportunities (Anthropic charges less for cached prompt prefixes, and the tool-surface portion of the prompt is often the longest stable prefix).

Since:

0.5.0 (issue #79)

Constructor Summary

Constructors

Constructor	Description
ToolSurface(List<String> toolNames, List<String> toolSchemas, String surfaceHash)	Creates an instance of a ToolSurface record class.

Method Summary

Modifier and Type	Method	Description
static ToolSurface	empty()	An empty tool surface — the LLM call advertised no tools.
final boolean	equals(Object o)	Indicates whether some other object is "equal to" this one.
final int	hashCode()	Returns a hash code value for this object.
static ToolSurface	of(List<String> names, List<String> schemas)	Build a tool surface from parallel names and schemas lists.
String	surfaceHash()	Returns the value of the surfaceHash record component.
List<String>	toolNames()	Returns the value of the toolNames record component.
List<String>	toolSchemas()	Returns the value of the toolSchemas record component.
final String	toString()	Returns a string representation of this record class.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Details

ToolSurface

public ToolSurface(List<String> toolNames,
 List<String> toolSchemas,
 String surfaceHash)

Creates an instance of a ToolSurface record class.

Parameters:

toolNames - the value for the toolNames record component

toolSchemas - the value for the toolSchemas record component

surfaceHash - the value for the surfaceHash record component

Method Details

empty

public static ToolSurface empty()

An empty tool surface — the LLM call advertised no tools.

of

public static ToolSurface of(List<String> names,
 List<String> schemas)

Build a tool surface from parallel names and schemas lists. The hash is derived from the (name, schema) pairs sorted by name — order-independent.

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.

toolNames

public List<String> toolNames()

Returns the value of the toolNames record component.

Returns:

the value of the toolNames record component

toolSchemas

public List<String> toolSchemas()

Returns the value of the toolSchemas record component.

Returns:

the value of the toolSchemas record component

surfaceHash

public String surfaceHash()

Returns the value of the surfaceHash record component.

Returns:

the value of the surfaceHash record component