Package com.tnsai.context.decision

Class DecisionTrace

java.lang.Object
com.tnsai.context.decision.DecisionTrace
public final class DecisionTrace extends Object
Complete record of a decision for auditing and explanation.

DecisionTrace captures the full lifecycle of a decision:

  • What triggered it (DecisionTrigger)
  • What was considered (DecisionInput)
  • What rules applied (DecisionPolicy)
  • How the decision was made (DecisionReasoning)
  • What action was taken
  • What happened (DecisionOutcome)

This follows the Foundation Capital Context Graphs model where decisions are first-class entities that can be queried, explained, and used as precedents.

Usage Example


 DecisionTrace trace = DecisionTrace.builder()
     .agentId("discount-approval-agent")
     .contextSnapshot(contextManager.createSnapshot(SnapshotTrigger.PRE_DECISION))
     .trigger(DecisionTrigger.userRequest("Approve discount", "user-123"))
     .input(inputBuilder.build())
     .policy(policyBuilder.build())
     .reasoning(reasoningBuilder.build())
     .action("APPROVE_DISCOUNT")
     .outcome(outcomeBuilder.build())
     .build();

 // Explain the decision
 String explanation = trace.explainWhy();

  • Method Details

    • builder

      public static DecisionTrace.Builder builder()
      Creates a new builder.

    • getTraceId

      public String getTraceId()

    • getAgentId

      public String getAgentId()

    • getTimestamp

      public Instant getTimestamp()

    • getContextSnapshot

      public Optional<ContextSnapshot> getContextSnapshot()

    • getTrigger

      public Optional<DecisionTrigger> getTrigger()

    • getInput

      public Optional<DecisionInput> getInput()

    • getPolicy

      public Optional<DecisionPolicy> getPolicy()

    • getReasoning

      public Optional<DecisionReasoning> getReasoning()

    • getAction

      public Optional<String> getAction()

    • getOutcome

      public Optional<DecisionOutcome> getOutcome()

    • getSpec

      public Map<String,Object> getSpec()

    • getTags

      public List<String> getTags()

    • getConversationId

      public Optional<String> getConversationId()

    • getParentTraceId

      public Optional<String> getParentTraceId()

    • isSuccessful

      public boolean isSuccessful()
      Returns true if the decision was successful.

    • isFailed

      public boolean isFailed()
      Returns true if the decision failed.

    • hasContextSnapshot

      public boolean hasContextSnapshot()
      Returns true if this trace has a context snapshot.

    • isChildDecision

      public boolean isChildDecision()
      Returns true if this is a child decision.

    • getExecutionDuration

      public Optional<Duration> getExecutionDuration()
      Gets the execution duration if outcome has execution time.
      Returns:
      Optional containing the duration

    • getConfidence

      public double getConfidence()
      Gets the confidence level from reasoning.
      Returns:
      confidence level or 0.0 if no reasoning

    • hasTag

      public boolean hasTag(String tag)
      Checks if the trace has a specific tag.
      Parameters:
      tag - tag to check
      Returns:
      true if tag is present

    • explainWhy

      public String explainWhy()
      Generates a human-readable explanation of why this decision was made.
      Returns:
      explanation string

    • summarize

      public String summarize()
      Generates a concise one-line summary.
      Returns:
      summary string

    • 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