1. Behavior and Context

In the jazzmine workflow, the Enhancer executes immediately after a message is ingested but before the agent begins its reasoning loop.

• Contextual Awareness: It utilizes a "Sliding History Window" to understand recent turns. It specifically identifies "Episode Boundaries"—points where the user previously changed the subject—to ensure the LLM isn't confused by stale context.
• Structured Output: It forces the LLM to respond in a strict JSON format, which is then mapped back to the framework's internal Message model.
• Augmented Reasoning: The "Enhanced Query" (where pronouns like "it" or "that" are replaced with actual nouns) is what the agent's brain and memory stores primarily use for searching and reasoning.

2. Purpose

• Anaphora Resolution: Replacing vague references (e.g., "Do it again") with explicit actions (e.g., "Refund the order again") based on context.
• Sentiment Monitoring: Tracking user satisfaction on a scale of -1.0 to 1.0 to trigger specialized support or escalation logic.
• Intent & Entity Extraction: Identifying the core request and specific objects (products, IDs, dates) mentioned by the user.
• Topic Tracking: Determining if a message is a continuation of the current task or a pivot to something new, which is critical for Episodic Memory segmentation.
• Request Retraction: Detecting if the user is attempting to cancel or retract a previous instruction.

3. High-Level API (Usage)

The MessageEnhancer requires a BaseLLM provider and a MessageStore to retrieve history.

Example: Enhancing a User Message

from jazzmine.core.message_enhancer import MessageEnhancer
from jazzmine.core.message_store import Message

# 1. Initialize with a reasoning LLM and the persistent store
enhancer = MessageEnhancer(llm=my_llm, message_store=my_store, history_window=10)

# 2. Receive a raw message from a user
raw_msg = Message(
    conversation_id="conv_123",
    user_id="user_888",
    original_content="Actually, forget that. Where is the other one?",
    # ... other required fields ...
)

# 3. Enhance the message
enhanced_msg = await enhancer.enhance_message(raw_msg)

# The message object is now populated with metadata
print(f"Clarified Query: {enhanced_msg.enhanced_message}")
# Output: "Where is the shipping status for the Dell XPS laptop?"
print(f"Intent: {enhanced_msg.intent}")
# Output: "track_order"
print(f"Is Continuation: {enhanced_msg.is_continuation}")
# Output: False (because 'Actually' signaled a shift)

4. Detailed Functionality

enhance_message(message)

Functionality: The primary entry point. It orchestrates history retrieval, LLM generation, and data persistence.

Process:

1. Fetches the last N messages from the store (defined by history_window).
2. Trims that history to the start of the "current episode" (the last turn where is_continuation was False).
3. Assembles an XML-wrapped payload including the raw message, any explicit RAG context, and the episode transcript.
4. Calls the LLM with a specialized system prompt that enforces JSON output.
5. Parses and validates the response, updating the Message object in the store.

_trim_to_current_episode(history) [Static]

Functionality: Filters conversation history to remove irrelevant context from previous topics.

How it works: It iterates through the provided message history and identifies the most recent message marked with is_continuation=False. It discards everything before that message, ensuring the LLM only "sees" the current logical chapter of the conversation.

_parse_llm_response(raw_text) [Static]

Functionality: Robustly extracts and cleans JSON data from the LLM's output.

How it works:

• Strips Markdown code fences (e.g., ```json) if the model included them.
• Parses the JSON string into a dictionary.
• Validates the presence of required fields: enhanced_query, sentiment_score, intent, entities, is_cancellation, and is_continuation.
• Normalizes the sentiment_score to stay within the range of [-1.0, 1.0].

_build_user_content(...) [Internal]

Functionality: Constructs the XML structure used to prompt the LLM.

Structure:

• <raw_message>: The user's original text.
• <explicit_context>: Any document snippets or facts retrieved by the agent.
• <current_episode_history>: The sequence of turns belonging to the current topic.

5. Error Handling

• EnhancementError: Raised internally if the LLM produces malformed JSON or is missing required keys.
• Safe Fallbacks: If an EnhancementError or any LLM-related exception occurs, the system logs a warning and calls _safe_defaults:
• enhanced_query defaults to the original_content.
• sentiment_score defaults to 0.0.
• intent defaults to "unknown".
• is_continuation defaults to True.
• XML Escaping: All user-provided content and context snippets are automatically escaped (e.g., < becomes &lt;) to prevent prompt injection or XML parsing errors.

6. Remarks

• History Tuning: The default history_window is 8 turns. For conversations involving very complex, multi-step clarifications, this value should be increased.

• Direct-to-Store: The enhancer automatically calls message_store.update_message() before returning, ensuring the database is always in sync with the enhanced metadata.