core.client_base

Abstract base class for AI client implementations.

Abstract base class for AI client implementations.

class FFAIClientBase

Bases: ABC

Abstract base class defining the contract for AI client implementations.

All AI provider clients (Mistral, Anthropic, OpenAI, etc.) must inherit from this class and implement its abstract methods.

model

The model identifier string.

Type:

str

system_instructions

System prompt/instructions for the AI.

Type:

str

retry_config

Override retry configuration. None uses the global config defaults.

Type:

dict[str, Any] | None

model: str

system_instructions: str

retry_config: dict[str, Any] | None = None

static get_default_retry_config()

Get default retry configuration from global config.

Returns:

Dictionary with retry configuration parameters.

Return type:

dict[str, Any]

configure_retry(retry_config=None)

Configure retry behavior for this client.

Parameters:

retry_config (dict[str, Any] | None) – Optional retry configuration. If None, uses global config.

Return type:

None

property last_usage: TokenUsage | None

Token usage from the most recent generate_response() call.

property last_cost_usd: float

Estimated cost in USD from the most recent generate_response() call.

property last_duration_ms: float | None

Wall-clock duration in ms of the most recent generate_response() call.

abstractmethod generate_response(prompt, **kwargs)

Generate a response from the AI model.

Parameters:

• prompt (str) – The user prompt to send to the model.

• **kwargs (Any) – Additional model-specific parameters (temperature, max_tokens, etc.)

Returns:

The generated response string.

Return type:

str

abstractmethod clear_conversation()

Clear the conversation history.

Return type:

None

abstractmethod get_conversation_history()

Get the conversation history.

Returns:

List of message dictionaries with role and content keys.

Return type:

list[dict[str, Any]]

abstractmethod set_conversation_history(history)

Set the conversation history.

Parameters:

history (list[dict[str, Any]]) – List of message dictionaries with role and content keys.

Return type:

None

add_tool_result(tool_call_id, content)

Add a tool result to the conversation history.

Default implementation appends a tool-role message. Subclasses that manage conversation history differently (e.g. via an external API) should override this method.

Parameters:

• tool_call_id (str) – The ID of the tool call this result responds to.

• content (str) – The tool execution result string.

Return type:

None

abstractmethod clone()

Create a fresh clone of this client with empty history.

Used for thread-safe parallel execution where each thread needs an isolated client instance with the same configuration.

Returns:

New client instance with same config, empty history.

Return type:

FFAIClientBase

Classes

class FFAIClientBase

Bases: ABC

Abstract base class defining the contract for AI client implementations.

All AI provider clients (Mistral, Anthropic, OpenAI, etc.) must inherit from this class and implement its abstract methods.

model

The model identifier string.

Type:

str

system_instructions

System prompt/instructions for the AI.

Type:

str

retry_config

Override retry configuration. None uses the global config defaults.

Type:

dict[str, Any] | None

model: str

system_instructions: str

retry_config: dict[str, Any] | None = None

static get_default_retry_config()

Get default retry configuration from global config.

Returns:

Dictionary with retry configuration parameters.

Return type:

dict[str, Any]

configure_retry(retry_config=None)

Configure retry behavior for this client.

Parameters:

retry_config (dict[str, Any] | None) – Optional retry configuration. If None, uses global config.

Return type:

None

property last_usage: TokenUsage | None

Token usage from the most recent generate_response() call.

property last_cost_usd: float

Estimated cost in USD from the most recent generate_response() call.

property last_duration_ms: float | None

Wall-clock duration in ms of the most recent generate_response() call.

abstractmethod generate_response(prompt, **kwargs)

Generate a response from the AI model.

Parameters:

• prompt (str) – The user prompt to send to the model.

• **kwargs (Any) – Additional model-specific parameters (temperature, max_tokens, etc.)

Returns:

The generated response string.

Return type:

str

abstractmethod clear_conversation()

Clear the conversation history.

Return type:

None

abstractmethod get_conversation_history()

Get the conversation history.

Returns:

List of message dictionaries with role and content keys.

Return type:

list[dict[str, Any]]

abstractmethod set_conversation_history(history)

Set the conversation history.

Parameters:

history (list[dict[str, Any]]) – List of message dictionaries with role and content keys.

Return type:

None

add_tool_result(tool_call_id, content)

Add a tool result to the conversation history.

Default implementation appends a tool-role message. Subclasses that manage conversation history differently (e.g. via an external API) should override this method.

Parameters:

• tool_call_id (str) – The ID of the tool call this result responds to.

• content (str) – The tool execution result string.

Return type:

None

abstractmethod clone()

Create a fresh clone of this client with empty history.

Used for thread-safe parallel execution where each thread needs an isolated client instance with the same configuration.

Returns:

New client instance with same config, empty history.

Return type:

FFAIClientBase