​
Core Data Types

This guide explains the primary data types used in the Reward Kit, including the input and output structures for reward functions.

​
Overview

The Reward Kit uses several core data types to represent:

  • Conversation messages
  • Evaluation results
  • Component metrics

Understanding these types is crucial for creating effective reward functions.

​
Message Types

​
The Message Class

from reward_kit import Message

message = Message(
    role="assistant",
    content="This is the response content",
    name=None,  # Optional
    tool_call_id=None,  # Optional, for tool calling
    tool_calls=None,  # Optional, for tool calling
    function_call=None  # Optional, for function calling
)

The Message class represents a single message in a conversation and is compatible with the OpenAI message format.

​
Message Dictionary Format

When working with reward functions, messages are often passed as dictionaries:

message_dict = {
    "role": "assistant",
    "content": "This is the response content"
}

The minimum required fields are:

  • role: The sender of the message ("user", "assistant", or "system")
  • content: The text content of the message

Additional fields for function/tool calling may include:

  • name: Name of the sender (for named system messages)
  • tool_calls: Tool call information
  • function_call: Function call information (legacy format)

​
Evaluation Output Types

​
EvaluateResult Class

from reward_kit import EvaluateResult, MetricResult

result = EvaluateResult(
    score=0.75,  # Overall score between 0.0 and 1.0
    reason="The response meets quality requirements",  # Optional explanation
    metrics={    # Component metrics dictionary
        "clarity": MetricResult(
            score=0.8,
            reason="The response is clear and concise"
        ),
        "accuracy": MetricResult(
            score=0.7,
            reason="Contains one minor factual error"
        )
    }
)

The EvaluateResult class represents the complete result of a reward function evaluation, containing:

  • An overall score (typically 0.0 to 1.0)
  • An optional reason/explanation for the overall score
  • A dictionary of component metrics
  • An optional error field for handling evaluation failures

​
MetricResult Class

from reward_kit import MetricResult

metric = MetricResult(
    score=0.8,  # Score for this specific metric
    reason="Explanation for why this score was assigned",  # Description
    success=True  # Optional success indicator
)

The MetricResult class represents a single component metric in the evaluation, containing:

  • A score value (typically 0.0 to 1.0)
  • A reason/explanation for the score
  • An optional success flag indicating if this metric evaluation was successful

​
Deprecated Output Types

The RewardOutput and MetricRewardOutput classes are deprecated and will be removed in a future version:

# Deprecated - use EvaluateResult instead
from reward_kit import RewardOutput, MetricRewardOutput

# This will show a deprecation warning
result = RewardOutput(
    score=0.75,
    metrics={
        "clarity": MetricRewardOutput(
            score=0.8,
            reason="The response is clear and concise"
        )
    }
)

# Convert to the preferred EvaluateResult format
evaluate_result = result.to_evaluate_result()

​
Type Conversion

The Reward Kit provides built-in methods for converting between types:

# Convert EvaluateResult to RewardOutput (for backwards compatibility)
evaluate_result = EvaluateResult(
    score=0.8, 
    metrics={"quality": MetricResult(score=0.8, reason="Good quality")}
)
reward_output = evaluate_result.to_reward_output()

# Convert RewardOutput to EvaluateResult
reward_output = RewardOutput(
    score=0.9, 
    metrics={"clarity": MetricRewardOutput(score=0.9, reason="Very clear")}
)
evaluate_result = reward_output.to_evaluate_result()

​
Using Types in Reward Functions

Here’s how to use these types properly in your reward functions:

from reward_kit import reward_function, EvaluateResult, MetricResult, Message
from typing import List, Optional, Dict, Any

@reward_function
def my_reward_function(
    messages: List[Dict[str, str]],
    original_messages: Optional[List[Dict[str, str]]] = None,
    metadata: Optional[Dict[str, Any]] = None,
    **kwargs
) -> EvaluateResult:
    """
    Example reward function with proper type annotations.
    """
    # Default values
    metadata = metadata or {}
    
    # Get the assistant's response
    response = messages[-1].get("content", "")
    
    # Evaluate the response
    clarity_score = evaluate_clarity(response)
    
    # Create metrics
    metrics = {
        "clarity": MetricResult(
            score=clarity_score,
            reason=f"Clarity score: {clarity_score:.2f}",
            success=clarity_score >= 0.7  # Optional success indicator
        )
    }
    
    return EvaluateResult(
        score=clarity_score, 
        reason=f"Overall quality assessment: {clarity_score:.2f}",
        metrics=metrics
    )

​
Best Practices for Data Types

  1. Use EvaluateResult: Always return EvaluateResult from your reward functions
  2. Use Type Hints: Include proper type annotations in your functions
  3. Provide Reasons: Include clear reason strings for both overall score and individual metrics
  4. Use Success Flags: Set the success flag in MetricResult to indicate pass/fail conditions
  5. Default Values: Provide defaults for optional parameters
  6. Validation: Validate input data before processing
  7. Error Handling: Handle missing or malformed data gracefully
  8. Documentation: Document the expected format for your inputs and outputs

​
Migration from RewardOutput to EvaluateResult

If you have existing code using RewardOutput, here’s how to migrate to EvaluateResult:

# Old code (deprecated)
@reward_function
def my_reward(messages, **kwargs):
    # ...
    return RewardOutput(
        score=0.75,
        metrics={
            "clarity": MetricRewardOutput(score=0.8, reason="Clear explanation")
        }
    )

# New code (preferred)
@reward_function
def my_reward(messages, **kwargs):
    # ...
    return EvaluateResult(
        score=0.75,
        reason="Overall assessment",  # Add an overall reason
        metrics={
            "clarity": MetricResult(
                score=0.8, 
                reason="Clear explanation",
                success=True  # Add success flag if applicable
            )
        }
    )

​
Next Steps

Now that you understand the core data types:

  1. Learn about Evaluation Workflows for testing and deploying your functions
  2. Explore Advanced Reward Functions to see these types in action
  3. Check the API Reference for complete details on all data types