Class ArtifactResponse<R extends Reasoning>

java.lang.Object
ai.redouble.nucleo.harness.schema.ReasonablePojo<R>
ai.redouble.nucleo.harness.artifacts.ArtifactResponse<R>
Type Parameters:
R - the type of reasoning for this response
Direct Known Subclasses:
ThinkerOutput
public abstract class ArtifactResponse<R extends Reasoning> extends ReasonablePojo<R>
Base class for agent responses that can reference preserved artifacts.

Extends ReasonablePojo to include reasoning capabilities, and adds the artifactRefs field for tracking which artifacts should be propagated to parent contexts.

The refs are canonical by construction: the model's parsed list enters through a package-private Jackson setter and canonicalizeArtifactRefs(String) replaces it with the normalized, deduplicated form right after parse, while programmatic additions go through addArtifactRef(String), which normalizes each ref - so no caller outside this package can plant a variant spelling.

The artifactRefs field is curated propagation: the responder decides what its parent needs.

  • Include ALL artifact references the parent needs to understand the response
  • Can filter out irrelevant artifacts from child tools
  • Can aggregate artifacts from multiple sources
  • Acts as the single source of truth for what propagates upward

Example usage: 

public class AnalysisResponse extends ArtifactResponse<ChainOfThoughtReasoning> {
    private String analysis;
    // artifactRefs inherited - contains refs in canonical format: «artifact:link:cite~a1b2c3»
}
Since:
0.1 (2025-11-13)
Author:
Andrey Santrosyan

  • Constructor Details

    • ArtifactResponse

      public ArtifactResponse()
      Creates a new ArtifactResponse with an empty artifactRefs list.

  • Method Details

    • getArtifactRefs

      public List<String> getArtifactRefs()
      Gets the list of artifact references to propagate to the parent context. References are in canonical format: «artifact:type~uuid».
      Returns:
      list of artifact references in canonical format

    • canonicalizeArtifactRefs

      public void canonicalizeArtifactRefs(String answerText)
      The single canonicalization gate for a parsed response: normalizes every declared reference, unions the «artifact:...» mentions found in the answer's text (ArtifactRegistry.refsMentionedIn(String)), deduplicates across spellings, and replaces the list - declared order first, then first-mention order. The response handler runs it after every parse, so a response leaving the thinking loop carries canonical refs by construction and a text-mentioned artifact can never hide behind a declared duplicate.

    • addArtifactRef

      public void addArtifactRef(String artifactRef)
      Adds a single artifact reference to the propagation list. The reference is normalized to canonical format: «artifact:type~uuid».
      Parameters:
      artifactRef - the artifact reference in any format

    • hasArtifactRefs

      public boolean hasArtifactRefs()
      Checks if this response references any artifacts.
      Returns:
      true if artifactRefs contains at least one reference