# `Jido.AI.Reasoning.TRM.Reasoning`
[🔗](https://github.com/agentjido/jido_ai/blob/v2.4.0/lib/jido_ai/reasoning/trm/reasoning.ex#L1)

Recursive Reasoning Engine for TRM (Tiny-Recursive-Model) strategy.

This module provides structured prompt construction and result parsing for the
reasoning phase of the TRM recursive improvement cycle. It handles:

- Building reasoning prompts that guide the LLM to analyze current answers
- Parsing LLM responses to extract key insights
- Calculating confidence scores from response quality
- Formatting reasoning traces for inclusion in subsequent prompts

## Overview

The TRM reasoning phase takes a question and current answer, then generates
structured analysis that identifies:
- Key insights that are correct
- Areas needing improvement
- Missing considerations
- Logical gaps or errors

## Usage

    context = %{
      question: "What is 2+2?",
      current_answer: "The answer is 4",
      latent_state: %{reasoning_trace: [], step_count: 1}
    }

    {system_prompt, user_prompt} = Reasoning.build_reasoning_prompt(context)
    # Use prompts to create LLM directive

    # After LLM response:
    result = Reasoning.parse_reasoning_result(llm_response)
    # %{insights: [...], issues: [...], confidence: 0.85}

# `parsed_insight`

```elixir
@type parsed_insight() :: %{
  type: :correct | :issue | :missing | :suggestion,
  content: String.t(),
  importance: :high | :medium | :low
}
```

# `reasoning_context`

```elixir
@type reasoning_context() :: %{
  question: String.t(),
  current_answer: String.t() | nil,
  latent_state: map()
}
```

# `reasoning_result`

```elixir
@type reasoning_result() :: %{
  insights: [String.t()],
  issues: [String.t()],
  suggestions: [String.t()],
  confidence: float(),
  raw_text: String.t()
}
```

# `build_latent_update_prompt`

```elixir
@spec build_latent_update_prompt(String.t(), String.t(), map()) :: String.t()
```

Builds a prompt for updating latent state from reasoning insights.

This prompt asks the LLM to summarize the key learnings from the reasoning
step in a format suitable for carrying forward to subsequent iterations.

# `build_reasoning_prompt`

```elixir
@spec build_reasoning_prompt(reasoning_context()) :: {String.t(), String.t()}
```

Builds the reasoning prompt for the TRM reasoning phase.

Returns a tuple of `{system_prompt, user_prompt}` that can be used to create
an LLM directive.

## Parameters

- `context` - A map containing:
  - `:question` - The original question being answered
  - `:current_answer` - The current answer (nil for first reasoning step)
  - `:latent_state` - Map with reasoning trace and other state

## Returns

A tuple `{system_prompt, user_prompt}` where:
- `system_prompt` - Instructions for the LLM's reasoning behavior
- `user_prompt` - The specific prompt for this reasoning step

## Examples

    iex> context = %{question: "What is AI?", current_answer: nil, latent_state: %{}}
    iex> {system, user} = Reasoning.build_reasoning_prompt(context)
    iex> is_binary(system) and is_binary(user)
    true

# `calculate_reasoning_confidence`

```elixir
@spec calculate_reasoning_confidence(String.t()) :: float()
```

Calculates a confidence score from the reasoning response quality.

Uses multiple heuristics to estimate confidence:
- Presence of explicit confidence marker
- Ratio of insights to issues
- Presence of uncertainty/certainty language
- Response structure and completeness

## Parameters

- `response` - The raw LLM response text

## Returns

A float between 0.0 and 1.0 representing the confidence score.

# `default_reasoning_system_prompt`

```elixir
@spec default_reasoning_system_prompt() :: String.t()
```

Returns the default system prompt for guiding recursive reasoning.

The prompt instructs the LLM to:
- Analyze the current answer thoroughly
- Identify correct insights and errors
- Provide structured analysis that can be parsed
- Use explicit markers for different types of findings

# `extract_key_insights`

```elixir
@spec extract_key_insights(String.t()) :: [parsed_insight()]
```

Extracts key insights from a reasoning response.

Identifies the most important points from the reasoning, prioritizing
by relevance and impact. Returns a list of parsed insight structures.

## Parameters

- `response` - The raw LLM response text

## Returns

A list of `parsed_insight` maps, each containing:
- `:type` - The type of insight (:correct, :issue, :missing, :suggestion)
- `:content` - The insight text
- `:importance` - Estimated importance (:high, :medium, :low)

# `format_reasoning_trace`

```elixir
@spec format_reasoning_trace(map() | nil) :: String.t()
```

Formats the reasoning trace from latent state for inclusion in prompts.

Handles various formats of the reasoning trace (list, string, nil) and
returns a formatted string suitable for prompt inclusion.

# `parse_reasoning_result`

```elixir
@spec parse_reasoning_result(String.t()) :: reasoning_result()
```

Parses an LLM reasoning response to extract structured insights.

Looks for formatted markers in the response:
- `INSIGHT:` - Correct insights to preserve
- `ISSUE:` - Problems found in the answer
- `MISSING:` - Missing elements
- `SUGGESTION:` - Improvement recommendations
- `CONFIDENCE:` - Explicit confidence score

## Parameters

- `response` - The raw LLM response text

## Returns

A map with:
- `:insights` - List of correct insights found
- `:issues` - List of problems identified
- `:suggestions` - List of improvement suggestions (includes MISSING items)
- `:confidence` - Calculated confidence score (0.0-1.0)
- `:raw_text` - The original response text

## Examples

    iex> response = "INSIGHT: The math is correct\nISSUE: Missing explanation\nCONFIDENCE: 0.7"
    iex> result = Reasoning.parse_reasoning_result(response)
    iex> length(result.insights)
    1

---

*Consult [api-reference.md](api-reference.md) for complete listing*