core.history.ordered

Ordered prompt-response history management with named references.

This module provides the OrderedPromptHistory class for managing AI interactions with named prompt references, enabling declarative context assembly in the FFAI wrapper.

Ordered prompt-response history management with named references.

This module provides the OrderedPromptHistory class for managing AI interactions with named prompt references, enabling declarative context assembly in the FFAI wrapper.

class Interaction(sequence_number, model, timestamp, prompt_name, prompt, response, history=None)[source]

Bases: object

Represents a single prompt-response interaction.

Parameters:

sequence_number (int)
model (str)
timestamp (float)
prompt_name (str | None)
prompt (str)
response (str)
history (list[str] | None)

sequence_number

Sequential identifier for this interaction.

Type:: int

model

The AI model used for this interaction.

Type:: str

timestamp

Unix timestamp of when the interaction occurred.

Type:: float

prompt_name

Optional name/key for the prompt.

Type:: str | None

prompt

The actual prompt text.

Type:: str

response

The AI’s response text.

Type:: str

history

Optional list of prompt names that form the history chain.

Type:: list[str] | None

sequence_number: int

model: str

timestamp: float

prompt_name: str | None

prompt: str

response: str

history: list[str] | None = None

to_dict()[source]

Convert the interaction to a dictionary representation.

Return type:: dict[str, Any]

class OrderedPromptHistory[source]

Bases: object

Manages ordered prompt-response history with named references.

This class provides: - Named prompt storage for declarative context assembly - Sequential ordering of interactions - Query capabilities by prompt name, model, etc. - History chain tracking for dependency resolution

prompt_dict: OrderedDict mapping prompt names to interaction lists.

__init__()[source]

Initialize an empty OrderedPromptHistory.

Return type:: None

prompt_dict: OrderedDict[str, list[Interaction]]

get_effective_prompt_name(prompt_name)[source]

Get the effective prompt name from various input types.

Parameters:: prompt_name (Any) – Can be a string, tuple, or other type.
Returns:: The cleaned prompt name as a string.
Return type:: str | tuple[str, …]

add_interaction(model, prompt, response, prompt_name=None, history=None)[source]

Add a new interaction to the history, storing cleaned versions of prompt and response.

Parameters:

model (str) – The model used for the interaction
prompt (str) – The prompt text
response (str) – The response text
prompt_name (str | None) – Optional name/key for the prompt. If None, uses prompt text as key
history (list[str] | None) – Optional list of prompt names that form the history chain for this interaction

Returns:

The created Interaction object

Return type:

Interaction

get_interactions_by_prompt_name(prompt_name)[source]

Get all interactions for a specific prompt name.

Parameters:: prompt_name (str)
Return type:: list[Interaction]

get_latest_interaction_by_prompt_name(prompt_name)[source]

Get the most recent interaction for a specific prompt name.

Parameters:: prompt_name (str)
Return type:: Interaction | None

get_all_prompt_names()[source]

Get a list of all prompt names in order of first appearance.

Return type:: list[str]

get_all_interactions()[source]

Get all interactions in sequence order.

Return type:: list[Interaction]

get_prompt_name_usage_stats()[source]

Get statistics on prompt name usage.

Return type:: dict[str, int]

get_interactions_by_model_and_prompt_name(model, prompt_name)[source]

Get all interactions for a specific model and prompt name combination.

Parameters:

model (str)
prompt_name (str)

Return type:

list[Interaction]

merge_histories(other)[source]

Merge another OrderedPromptHistory into this one.

Parameters:: other (OrderedPromptHistory) – Another OrderedPromptHistory instance to merge
Return type:: None

to_dict()[source]

Convert the entire history to a dictionary organized by prompt names.

Return type:: dict[str, list[dict[str, Any]]]

get_interaction_by_prompt(prompt)[source]

Get an interaction by its exact prompt text.

Useful when prompt was used as the prompt_name.

Parameters:: prompt (str)
Return type:: Interaction | None

get_latest_responses_by_prompt_names(prompt_names)[source]

Get the latest prompt and response for each specified prompt name.

Parameters:: prompt_names (list[str]) – List of prompt names to retrieve
Returns:: Dictionary with prompt names as keys and dictionaries containing ‘prompt’ and ‘response’ as values
Return type:: dict[str, dict[str, str]]

get_formatted_responses(prompt_names)[source]

Format the latest prompts and responses including recursive history chains.

Parameters:: prompt_names (list[str]) – List of prompt names to include in the formatted output.
Returns:: Formatted string containing all prompts and responses.
Return type:: str

Classes

class Interaction(sequence_number, model, timestamp, prompt_name, prompt, response, history=None)[source]

Bases: object

Represents a single prompt-response interaction.

Parameters:

sequence_number (int)
model (str)
timestamp (float)
prompt_name (str | None)
prompt (str)
response (str)
history (list[str] | None)

sequence_number

Sequential identifier for this interaction.

Type:: int

model

The AI model used for this interaction.

Type:: str

timestamp

Unix timestamp of when the interaction occurred.

Type:: float

prompt_name

Optional name/key for the prompt.

Type:: str | None

prompt

The actual prompt text.

Type:: str

response

The AI’s response text.

Type:: str

history

Optional list of prompt names that form the history chain.

Type:: list[str] | None

sequence_number: int

model: str

timestamp: float

prompt_name: str | None

prompt: str

response: str

history: list[str] | None = None

to_dict()[source]

Convert the interaction to a dictionary representation.

Return type:: dict[str, Any]

class OrderedPromptHistory[source]

Bases: object

Manages ordered prompt-response history with named references.

This class provides: - Named prompt storage for declarative context assembly - Sequential ordering of interactions - Query capabilities by prompt name, model, etc. - History chain tracking for dependency resolution

prompt_dict

OrderedDict mapping prompt names to interaction lists.

Type:: collections.OrderedDict[str, list[ffai.core.history.ordered.Interaction]]

__init__()[source]

Initialize an empty OrderedPromptHistory.

Return type:: None

prompt_dict: OrderedDict[str, list[Interaction]]

get_effective_prompt_name(prompt_name)[source]

Get the effective prompt name from various input types.

Parameters:: prompt_name (Any) – Can be a string, tuple, or other type.
Returns:: The cleaned prompt name as a string.
Return type:: str | tuple[str, …]

add_interaction(model, prompt, response, prompt_name=None, history=None)[source]

Add a new interaction to the history, storing cleaned versions of prompt and response.

Parameters:

model (str) – The model used for the interaction
prompt (str) – The prompt text
response (str) – The response text
prompt_name (str | None) – Optional name/key for the prompt. If None, uses prompt text as key
history (list[str] | None) – Optional list of prompt names that form the history chain for this interaction

Returns:

The created Interaction object

Return type:

Interaction

get_interactions_by_prompt_name(prompt_name)[source]

Get all interactions for a specific prompt name.

Parameters:: prompt_name (str)
Return type:: list[Interaction]

get_latest_interaction_by_prompt_name(prompt_name)[source]

Get the most recent interaction for a specific prompt name.

Parameters:: prompt_name (str)
Return type:: Interaction | None

get_all_prompt_names()[source]

Get a list of all prompt names in order of first appearance.

Return type:: list[str]

get_all_interactions()[source]

Get all interactions in sequence order.

Return type:: list[Interaction]

get_prompt_name_usage_stats()[source]

Get statistics on prompt name usage.

Return type:: dict[str, int]

get_interactions_by_model_and_prompt_name(model, prompt_name)[source]

Get all interactions for a specific model and prompt name combination.

Parameters:

model (str)
prompt_name (str)

Return type:

list[Interaction]

merge_histories(other)[source]

Merge another OrderedPromptHistory into this one.

Parameters:: other (OrderedPromptHistory) – Another OrderedPromptHistory instance to merge
Return type:: None

to_dict()[source]

Convert the entire history to a dictionary organized by prompt names.

Return type:: dict[str, list[dict[str, Any]]]

get_interaction_by_prompt(prompt)[source]

Get an interaction by its exact prompt text.

Useful when prompt was used as the prompt_name.

Parameters:: prompt (str)
Return type:: Interaction | None

get_latest_responses_by_prompt_names(prompt_names)[source]

Get the latest prompt and response for each specified prompt name.

Parameters:: prompt_names (list[str]) – List of prompt names to retrieve
Returns:: Dictionary with prompt names as keys and dictionaries containing ‘prompt’ and ‘response’ as values
Return type:: dict[str, dict[str, str]]

get_formatted_responses(prompt_names)[source]

Format the latest prompts and responses including recursive history chains.

Parameters:: prompt_names (list[str]) – List of prompt names to include in the formatted output.
Returns:: Formatted string containing all prompts and responses.
Return type:: str