Package com.tnsai.context.decision

Interface DecisionTraceStore

public interface DecisionTraceStore
Interface for storing and retrieving decision traces.

DecisionTraceStore provides persistence for decision traces, enabling:

  • Decision auditing and compliance
  • Explaining past decisions
  • Finding precedents for similar situations
  • Learning from decision outcomes

Usage Example


 DecisionTraceStore store = new InMemoryDecisionTraceStore();

 // Store trace
 DecisionTrace trace = traceBuilder.build();
 store.save(trace);

 // Retrieve by ID
 Optional<DecisionTrace> retrieved = store.findById(trace.getTraceId());

 // Query by outcome
 List<DecisionTrace> successful = store.findByOutcome(OutcomeStatus.SUCCESS);

 // Find similar decisions (precedents)
 List<DecisionTrace> precedents = store.findSimilar(trace, 0.8);

  • Method Details

    • save

      void save(DecisionTrace trace)
      Saves a decision trace.
      Parameters:
      trace - trace to save

    • findById

      Optional<DecisionTrace> findById(String traceId)
      Finds a trace by ID.
      Parameters:
      traceId - trace identifier
      Returns:
      Optional containing the trace if found

    • findByAgent

      List<DecisionTrace> findByAgent(String agentId)
      Finds all traces for an agent.
      Parameters:
      agentId - agent identifier
      Returns:
      list of traces, ordered by timestamp descending

    • findRecentByAgent

      List<DecisionTrace> findRecentByAgent(String agentId, int limit)
      Finds recent traces for an agent.
      Parameters:
      agentId - agent identifier
      limit - maximum number of traces to return
      Returns:
      list of recent traces

    • findByAction

      List<DecisionTrace> findByAction(String action)
      Finds traces by action.
      Parameters:
      action - action name
      Returns:
      list of traces with that action

    • findByOutcome

      List<DecisionTrace> findByOutcome(DecisionOutcome.OutcomeStatus status)
      Finds traces by outcome status.
      Parameters:
      status - outcome status
      Returns:
      list of traces with that status

    • findByTriggerType

      List<DecisionTrace> findByTriggerType(DecisionTrigger.TriggerType triggerType)
      Finds traces by trigger type.
      Parameters:
      triggerType - trigger type
      Returns:
      list of traces with that trigger type

    • findByTimeRange

      List<DecisionTrace> findByTimeRange(Instant start, Instant end)
      Finds traces within a time range.
      Parameters:
      start - start of time range (inclusive)
      end - end of time range (inclusive)
      Returns:
      list of traces in the time range

    • findByConversation

      List<DecisionTrace> findByConversation(String conversationId)
      Finds traces for a conversation.
      Parameters:
      conversationId - conversation identifier
      Returns:
      list of traces for the conversation

    • findByTag

      List<DecisionTrace> findByTag(String tag)
      Finds traces with a specific tag.
      Parameters:
      tag - tag to search for
      Returns:
      list of traces with that tag

    • findChildren

      List<DecisionTrace> findChildren(String parentTraceId)
      Finds child traces of a parent trace.
      Parameters:
      parentTraceId - parent trace identifier
      Returns:
      list of child traces

    • findSimilar

      List<DecisionTrace> findSimilar(DecisionTrace trace, double threshold)
      Finds similar traces (precedents) based on input similarity.

      This is a simple implementation that matches on action and trigger type. More sophisticated implementations could use embedding similarity.

      Parameters:
      trace - reference trace
      threshold - similarity threshold (0.0-1.0)
      Returns:
      list of similar traces

    • delete

      boolean delete(String traceId)
      Deletes a trace by ID.
      Parameters:
      traceId - trace identifier
      Returns:
      true if trace was deleted

    • deleteByAgent

      int deleteByAgent(String agentId)
      Deletes all traces for an agent.
      Parameters:
      agentId - agent identifier
      Returns:
      number of deleted traces

    • deleteOlderThan

      int deleteOlderThan(Instant before)
      Deletes traces older than a specified time.
      Parameters:
      before - delete traces before this time
      Returns:
      number of deleted traces

    • count

      int count()
      Counts total traces in the store.
      Returns:
      trace count

    • countByAgent

      int countByAgent(String agentId)
      Counts traces for an agent.
      Parameters:
      agentId - agent identifier
      Returns:
      trace count for the agent

    • getStatistics

      DecisionTraceStore.DecisionTraceStatistics getStatistics()
      Gets store statistics.
      Returns:
      store statistics