Reasoning

To run one of the first four inside an agent's chat, see Use a strategy in agent chat.

ReAct

ReActExecutor asks the model for a thought and either an action or a final answer. It passes each action to your ActionHandler and feeds the result back as the observation.

import com.tnsai.reasoning.react.ReActExecutor;
import com.tnsai.reasoning.react.ReActResult;
import com.tnsai.reasoning.react.ReActStep;
import com.tnsai.reasoning.react.StopCondition;
import java.time.Duration;
import java.util.Optional;

ReActExecutor react = ReActExecutor.builder()
    .llm(client)
    .actionHandler((name, input) -> switch (name) {
        case "search" -> Optional.of(searchService.search(input));
        default -> Optional.empty();
    })
    .availableActions("search: look up a fact on the web")
    .maxSteps(8)
    .stopCondition(StopCondition.noActionFor(3))
    .timeout(Duration.ofMinutes(2))
    .build();

ReActResult result = react.execute("Which is larger, Tokyo or New York by population?");

if (result.isSuccess()) {
    System.out.println(result.getFinalAnswer());
}
for (ReActStep step : result.getSteps()) {
    System.out.println(step.format());
}

ActionHandler.withFallback(primary, message) wraps a handler so an unknown action returns your message.

Stop conditions: StopCondition.finalAnswerDetected(), answerContains(text), noActionFor(n) and anyOf(...).

ReAct result

ReActResult has getFinalAnswer(), getSteps(), getStepCount(), getStatus(), isSuccess(), getDuration(), getTotalLLMCalls() and getReasoningTrace(). Each ReActStep has getStepNumber(), getThought(), getAction(), getActionInput() and getObservation() (the last three are Optional), plus format().

Tree of Thoughts

TreeOfThoughtsExecutor asks the model for branchingFactor next thoughts per node, scores each one with a BranchEvaluator, and keeps the best per round. At maxDepth, or when the time runs out, it asks the model for a final answer on each remaining leaf.

import com.tnsai.reasoning.BranchEvaluator;
import com.tnsai.reasoning.PruningStrategy;
import com.tnsai.reasoning.ToTResult;
import com.tnsai.reasoning.TreeOfThoughtsExecutor;

TreeOfThoughtsExecutor tot = TreeOfThoughtsExecutor.builder()
    .llm(client)
    .evaluator(BranchEvaluator.llm(evalClient))
    .pruning(PruningStrategy.BEAM_SEARCH)
    .beamWidth(3)
    .maxDepth(4)
    .build();

ToTResult result = tot.explore("Design a REST API for a todo app");

result.getBestLeaf().ifPresent(leaf -> System.out.println(leaf.getFinalAnswer()));
System.out.println(result.getBestPath());

Pruning strategies

Evaluators

A BranchEvaluator is a single method, evaluate(Evaluable node, String goal), so a lambda works too.

Tree result

ThoughtNode has getThought(), getScore(), getDepth(), getParent(), getChildren(), getPath(), getThoughtChain(), getCumulativeScore(), getAverageScore() and getFinalAnswer().

Graph of Thoughts

GraphOfThoughtsExecutor grows a graph in rounds. Each round it generates children for the frontier, refines nodes that scored above 0.3, and merges the round's best new nodes into one.

import com.tnsai.reasoning.BranchEvaluator;
import com.tnsai.reasoning.got.GoTOperation;
import com.tnsai.reasoning.got.GoTResult;
import com.tnsai.reasoning.got.GraphOfThoughtsExecutor;
import java.util.List;

GraphOfThoughtsExecutor got = GraphOfThoughtsExecutor.builder()
    .llm(client)
    .evaluator(BranchEvaluator.llm(client))
    .operations(List.of(GoTOperation.GENERATE, GoTOperation.REFINE, GoTOperation.AGGREGATE))
    .maxNodes(20)
    .build();

GoTResult result = got.explore("Design a database schema for e-commerce");
System.out.println(result.getBestThought());
System.out.println(result.mergeCount());

GoTResult is a record: root(), bestNode(), allNodes(), aggregatedInsight() (the best node's thought), totalNodes(), mergeCount() and duration(), plus getBestThought(), getBestScore() and hasSolution() (best score above 0.5). A GoTNode with more than one parent is a merge node: isMergeNode(), getParents().

Self-consistency

SelfConsistencyExecutor asks the same question numPaths times at slightly different temperatures and aggregates the answers.

import com.tnsai.reasoning.Aggregation;
import com.tnsai.reasoning.ConsistencyResult;
import com.tnsai.reasoning.SelfConsistencyExecutor;

SelfConsistencyExecutor executor = SelfConsistencyExecutor.builder()
    .llm(client)
    .numPaths(5)
    .aggregation(Aggregation.MAJORITY_VOTE)
    .build();

ConsistencyResult result = executor.reason("What is 17 * 23?");
System.out.println(result.getConsensusAnswer());
System.out.println(result.getConfidence());
System.out.println(result.getAnswerCounts());

ConsistencyResult has getConsensusAnswer(), getConfidence(), getAnswerCounts(), getAllPaths(), getTotalPaths(), isUnanimous() and isConfident(threshold).

Atom of Thought

AotProcessor splits a question into atoms, solves them in dependency order and combines the answers. Questions that score below the complexity threshold are answered as a single atom.

import com.tnsai.prompt.aot.AotProcessor;
import com.tnsai.prompt.aot.AotResult;

AotProcessor aot = AotProcessor.builder()
    .llmClient(client)
    .maxAtoms(8)
    .build();

try {
    AotResult result = aot.process("Compare the 3-year cost of renting and buying a $300k home at 6%");
    System.out.println(result.getAnswer());
    System.out.println(result.getConfidence());
    System.out.println(result.getDetailedTrace());
} finally {
    aot.shutdown();
}

new AotProcessor(client) uses the defaults.

processForced(question) skips the complexity check. A blank question returns an empty result, and an exception returns a failed one: check isSuccess() and getErrorMessage().

AotResult also has getAtoms(), getAtomCount(), getSolvedAtomCount(), getAverageAtomConfidence(), isConfident(threshold), getReasoning() and getSummary(). Confidence is on a 0 to 100 scale.

Call shutdown() when you are done: the solver owns a thread pool.

Causal questions

CausalReasoner sends one prompt per question, with your causal model and context, and parses the answer, reasoning and confidence from the reply.

import com.tnsai.reasoning.causal.CausalReasoner;
import com.tnsai.reasoning.causal.CausalResult;
import java.util.Map;

CausalReasoner reasoner = CausalReasoner.builder()
    .llm(client)
    .causalModel("Sales depend on marketing spend, season and competitor pricing")
    .build();

Map<String, Object> context = Map.of("q3_sales", 150_000, "marketing_budget", 50_000);

CausalResult why = reasoner.why("Why did sales drop in Q3?", context);
CausalResult whatIf = reasoner.whatIf("What if we doubled marketing?", context);
CausalResult effect = reasoner.intervene("Cut prices by 15%", context);

CausalResult is a record: queryType() (WHY, WHAT_IF or INTERVENTION), answer(), reasoning() and confidence() from 0 to 1. When the reply states no confidence, it is 0.5. When the call fails, the answer starts with Error: and confidence is 0.

Separate thinking from the answer

ExtendedThinkingClient asks the model to reason inside <thinking> tags and answer inside <answer> tags, and splits the reply into a ThinkingResult. It works through the prompt, so any LLMClient can be used.

import com.tnsai.reasoning.ExtendedThinkingClient;
import com.tnsai.reasoning.ThinkingResult;

ExtendedThinkingClient thinker = ExtendedThinkingClient.builder()
    .anthropic(client)
    .thinkingBudget(8_000)
    .build();

ThinkingResult result = thinker.think("Is 2^61 - 1 prime?");
System.out.println(result.getFinalAnswer());
System.out.println(result.getThinkingProcess());

think(problem, Optional<String> systemPrompt) adds your system prompt, and thinkWithHistory(problem, history) passes earlier turns. think returns a result whose answer starts with Extended thinking failed: when the call throws; thinkWithHistory throws.

ThinkingResult has getThinkingProcess(), getFinalAnswer(), getThinkingBlocks(), hasThinking(), getThinkingTokens(), getOutputTokens() and getTotalTokens(). The token counts are estimates (characters divided by 4). Without an <answer> tag, the answer is the reply with the thinking removed.

Use a strategy in agent chat

An agent can route every chat message through ReAct, Tree of Thoughts, Graph of Thoughts or self-consistency. tnsai-intelligence must be on the classpath.

Agent agent = AgentBuilder.create()
    .llm(client)
    // role and the other settings as usual
    .reasoningStrategy("self-consistency")
    .build();

String answer = agent.chat("What is 17 * 23?");
agent.getLastReasoningResult().ifPresent(r -> System.out.println(r.metadata()));

• The strategy gets the grounded message only, not the conversation history.
• On the react path, actions are not run: every observation is [Tool execution delegated to Agent]. To run actions, use ReActExecutor directly with your own ActionHandler.
• If the name cannot be resolved, for example because tnsai-intelligence is missing, the agent chats without a strategy and does not report it.
• reasoningStrategy(ReasoningStrategyHandle) passes your own handle and wins over a name. agent.setReasoningStrategy(null) turns the strategy off.

Choosing an executor

Related

• Planning: goal planners and plan execution.
• Context: compaction and memory consolidation.
• Learning: norms and refinement loops.