Model

This module defines the interfaces of code action models. A code action model is a model that responds with code if it decides to perform an action in the environment.

This module defines the core interfaces that code action models must implement to work with the freeact agent system. It defines abstract base classes for:

• The main model interface (CodeActModel)
• Model interaction turns (CodeActModelTurn)
• Model responses (CodeActModelResponse)

CodeActModel

Bases: ABC

Interface for models that can generate code actions.

A code action model handles both initial user queries and feedback from code execution results. It decides when to generate code for execution and when to provide final responses to the user.

feedback abstractmethod

feedback(feedback: str, is_error: bool, tool_use_id: str | None, tool_use_name: str | None, **kwargs) -> CodeActModelTurn

Create a new interaction turn from execution feedback.

Initiates a new interaction based on feedback from previous code execution, allowing the model to refine or correct its responses. A feedback turn must follow a previous request turn or feedback turn.

Parameters:

Name	Type	Description	Default
feedback	str	The feedback text from code execution.	required
is_error	bool	Whether the feedback represents an error condition.	required
tool_use_id	str | None	Identifier for the specific tool use instance.	required
tool_use_name	str | None	Name of the tool that was used.	required
**kwargs		Additional model-specific parameters for the feedback.	{}

Returns:

Name	Type	Description
CodeActModelTurn	CodeActModelTurn	A new turn object representing this interaction.

Source code in freeact/model/base.py

@abstractmethod
def feedback(
    self,
    feedback: str,
    is_error: bool,
    tool_use_id: str | None,
    tool_use_name: str | None,
    **kwargs,
) -> CodeActModelTurn:
    """Create a new interaction turn from execution feedback.

    Initiates a new interaction based on feedback from previous code execution,
    allowing the model to refine or correct its responses. A feedback turn must
    follow a previous request turn or feedback turn.

    Args:
        feedback (str): The feedback text from code execution.
        is_error (bool): Whether the feedback represents an error condition.
        tool_use_id (str | None): Identifier for the specific tool use instance.
        tool_use_name (str | None): Name of the tool that was used.
        **kwargs: Additional model-specific parameters for the feedback.

    Returns:
        CodeActModelTurn: A new turn object representing this interaction.
    """
    ...

request abstractmethod

request(user_query: str, **kwargs) -> CodeActModelTurn

Creates a new interaction turn from a user query.

Parameters:

Name	Type	Description	Default
user_query	str	The user's input query or request	required
**kwargs		Additional model-specific parameters	{}

Returns:

Name	Type	Description
CodeActModelTurn	CodeActModelTurn	A new turn object representing this interaction.

Source code in freeact/model/base.py

@abstractmethod
def request(self, user_query: str, **kwargs) -> CodeActModelTurn:
    """Creates a new interaction turn from a user query.

    Args:
        user_query: The user's input query or request
        **kwargs: Additional model-specific parameters

    Returns:
        CodeActModelTurn: A new turn object representing this interaction.
    """

CodeActModelResponse dataclass

CodeActModelResponse(text: str, is_error: bool, token_usage: Dict[str, int] = dict())

Bases: ABC

A response from a code action model.

Represents a single response from the model, which may contain executable code, error information, and tool usage metadata.

Attributes:

Name	Type	Description
text	str	The raw text response from the model.
is_error	bool	Whether this response represents an error condition.
token_usage	Dict[str, int]	Provider-specific token usage data.

code abstractmethod property

code: str | None

Executable code from the model response if present.

CodeActModelTurn

Bases: ABC

A single turn of interaction with a code action model.

Supports both bulk response retrieval and incremental streaming of the model's output. Each turn represents one complete model interaction, whether from a user query or execution feedback.

response abstractmethod async

response() -> CodeActModelResponse

Get the complete response for this model interaction turn.

Waits for and returns the full model response, including any code blocks and metadata about tool usage.

Source code in freeact/model/base.py

@abstractmethod
async def response(self) -> CodeActModelResponse:
    """Get the complete response for this model interaction turn.

    Waits for and returns the full model response, including any code blocks
    and metadata about tool usage.
    """

stream abstractmethod

stream(emit_retry: bool = False) -> AsyncIterator[str | StreamRetry]

Stream the model's response as it is generated.

Yields chunks of the response as they become available, allowing for real-time processing of model output.

Parameters:

Name	Type	Description	Default
emit_retry	bool	If True, emit StreamRetry objects when retries occur. If False, handle retries silently. Defaults to False.	False

Yields:

Type	Description
AsyncIterator[str | StreamRetry]	str | StreamRetry: Either a chunk of the response text, or a StreamRetry object if a retry event occurs and emit_retry is True.

Source code in freeact/model/base.py

@abstractmethod
def stream(self, emit_retry: bool = False) -> AsyncIterator[str | StreamRetry]:
    """Stream the model's response as it is generated.

    Yields chunks of the response as they become available, allowing for
    real-time processing of model output.

    Args:
        emit_retry (bool): If `True`, emit `StreamRetry` objects when retries occur.
                         If `False`, handle retries silently. Defaults to `False`.

    Yields:
        str | StreamRetry: Either a chunk of the response text, or a `StreamRetry`
                         object if a retry event occurs and `emit_retry` is `True`.
    """

StreamRetry dataclass

StreamRetry(cause: str, retry_wait_time: float)

Emitted in a response stream to inform about a retry event.

Used when streaming responses encounter temporary failures and need to retry.

Attributes:

Name	Type	Description
cause	str	The reason for the retry attempt.
retry_wait_time	float	Time in seconds to wait before retrying.