Skip to content

model

Canonical interoperability models

Attributes

ROLE_AI module-attribute 

ROLE_AI = 'assistant'

ROLE_HUMAN module-attribute 

ROLE_HUMAN = 'user'

ROLE_SYSTEM module-attribute 

ROLE_SYSTEM = 'system'

T module-attribute 

T = TypeVar('T')

Classes

CanonicalChat

Bases: BaseDataModel

Eleanor framework canonical chat representation

Attributes

ai_messages property 
ai_messages: List[CanonicalMessage]

Returns a list of CanonicalMessage objects representing AI messages in the conversation.

Returns:

  • List[CanonicalMessage] –

    List[CanonicalMessage]: A list of CanonicalMessage objects representing AI messages.

ai_name class-attribute instance-attribute 
ai_name: Optional[str] = Field(
    default=None,
    description="Optional name to use for AI when it isn't provided at the message level. Some templates use this when rendering AI/assistaint messages.",
)
ai_role class-attribute instance-attribute 
ai_role: str = Field(
    default=ROLE_AI, description="Default AI role name"
)
ai_turns property 
ai_turns: int

Returns the number of turns made by the AI in the conversation.

all_turns property 
all_turns: int

Returns the number of turns made by the human and AI in the conversation.

Note: system messages are omitted.

human_and_ai_messages property 
human_and_ai_messages: List[CanonicalMessage]

Returns a list of CanonicalMessage objects that belong to either the default human role or the default AI role.

Returns:

  • List[CanonicalMessage] –

    List[CanonicalMessage]: A list of CanonicalMessage objects.

human_messages property 
human_messages: List[CanonicalMessage]

Returns a list of CanonicalMessage objects representing the messages sent by humans in the conversation.

Returns:

  • List[CanonicalMessage] –

    List[CanonicalMessage]: A list of CanonicalMessage objects representing the messages sent by humans.

human_role class-attribute instance-attribute 
human_role: str = Field(
    default=ROLE_HUMAN,
    description="Default human role name",
)
human_turns property 
human_turns: int

Returns the number of turns made by the human in the conversation.

messages class-attribute instance-attribute 
messages: List[CanonicalMessage] = Field(
    default_factory=list, description="Chat message objects"
)
system_messages property 
system_messages: List[CanonicalMessage]

Returns a list of system messages from the conversation.

System messages are messages with the role equal to the default system role.

Returns:

system_role class-attribute instance-attribute 
system_role: str = Field(
    default=ROLE_SYSTEM,
    description="Default system role name",
)
system_turns property 
system_turns: int

Returns the number of turns made by the system in the conversation.

Functions

__getitem__ 
__getitem__(key: Union[int, slice]) -> CanonicalChat

Retrieve a conversation or a slice of conversations from the ChatML object.

Parameters:

  • key (Union[int, slice]) –

    The index or slice to retrieve the conversation(s).

Returns:

  • ChatConversation ( CanonicalChat ) –

    The conversation or slice of conversations.

Raises:

  • TypeError –

    If the argument type is invalid.

__len__ 
__len__() -> int
append_ai 
append_ai(
    content: str,
    name: Optional[str] = None,
    override_role: Optional[str] = None,
) -> None
append_header 
append_header(header: EleanorFrameworkHeader) -> None

Appends an EleanorFrameworkHeader object to the conversation as a system message.

Parameters:

append_human 
append_human(
    content: str,
    name: Optional[str] = None,
    override_role: Optional[str] = None,
) -> None
append_system 
append_system(
    content: str,
    name: Optional[str] = None,
    placement: Literal[
        "append",
        "before_system_content",
        "after_system_content",
    ] = "append",
    system_msg_patterns: Optional[
        Union[str, List[str]]
    ] = None,
) -> None

Appends a system message to the conversation.

Gives users some control over the placement position, this is particularly useful when adding framework-generated system messages

Parameters:

  • content (str) –

    The content of the system message.

  • placement (Literal['append', 'after_system_content'], default: 'append' ) –

    The placement of the system message. Defaults to “append”. Valid values are “append” or “after_system_content”.

  • system_msg_patterns (Optional[Union[str, List[str]]], default: None ) –

    The specific content in the system block to look for when placing the new system message. Only applicable when placement is set to “after_system_content”. Defaults to None.

Raises:

  • ValueError –

    If the placement value is invalid.

from_single staticmethod 
from_single(text: str) -> CanonicalChat

Create a CanonicalChat object with a single system message. This is useful for building completion-style requests where we need to map a Langchain PromptTemplate into a LLM specific prompt formatted string.

Parameters:

  • text (str) –

    The chat message text.

Returns:

parse_system_message 
parse_system_message(
    pattern: str, default: T, parser: Callable[[Tuple], T]
) -> Tuple[Optional[CanonicalMessage], T, Optional[int]]

Utility method to assist with detecting and parsing data from system messages.

Example usage:

eleanor_framework_msg, eleanor_framework_header = chat.parse_system_message( pattern=r”^ELEANOR_SYSTEM\s*({.+})$”, default=None, parser=lambda x: EleanorFrameworkHeader.model_validate_json(x[0]), )

Parameters:

  • pattern (str) –

    The regular expression pattern to match against the system message content.

  • default (T) –

    The default value to return if parsing fails.

  • parser (Callable[[Tuple], T]) –

    A callable function that takes a tuple of matched groups and returns a parsed value.

Returns:

  • Tuple[Optional[CanonicalMessage], T, Optional[int]] –

    Tuple[Optional[ChatMessage], T]: A tuple containing the matched system message (or None if no match is found) and the parsed value.

to_langchain 
to_langchain() -> List[BaseMessage]

Converts the iteroperable conversation messages to a list of BaseMessage objects that can be used with OpenAI chat models.

Returns:

  • List[BaseMessage] –

    A list of BaseMessage objects representing the conversation messages.

CanonicalMessage

Bases: BaseDataModel

Canonical chat message representation

Attributes

content class-attribute instance-attribute 
content: str = Field(..., description='Message content')
fewshot_example class-attribute instance-attribute 
fewshot_example: bool = Field(
    default=False,
    description="Some templates render fewshot examples differently than regular chat messages (ex ChatML). This flag will trigger the correct rendering or will simply be ignored if the destionation format does not use this distinction. When true, the name attribute cannot be None",
)
name class-attribute instance-attribute 
name: Optional[str] = Field(
    default=None, description="Optional name of participant"
)
role class-attribute instance-attribute 
role: str = Field(..., description='Message role')
tool_call_id class-attribute instance-attribute 
tool_call_id: Optional[str] = Field(
    default=None,
    description="OpenAI tool call that this message is responding to. Applicable when role=tool.",
)

Functions

check_name_if_fewshot_example 
check_name_if_fewshot_example() -> Self

EleanorFrameworkHeader

Bases: BaseDataModel

Eleanor Framework Header

This is an optional header that can be sent from clients such as SillyTavern that will pass hints to the detection logic implemented in the chat completions API.

This system will be removed by the framework; the AI will not see it.

All fields are optional, here is an example ‘content’ field for the system message:

ELEANOR_SYSTEM { “source”: “ST”, “user”: “{{user}}”, “char”: “{{char}}”, “session”: null }

Attributes

char class-attribute instance-attribute 
char: Optional[str] = Field(
    default=None,
    description="Responding AI agent/character name",
)
chat_type class-attribute instance-attribute 
chat_type: Optional[str] = Field(
    default=None,
    title="Chat Type",
    description="Chat type, should be 'single' or 'group'",
)
model_config class-attribute instance-attribute 
model_config = ConfigDict(
    populate_by_name=True,
    use_enum_values=True,
    extra="forbid",
    strict=True,
)
session class-attribute instance-attribute 
session: Optional[str] = Field(
    default=None,
    title="Chat Session Name",
    description="Session name to use for the chat",
)
session_settings class-attribute instance-attribute 
session_settings: Optional[SessionResourceSettings] = Field(
    default=None,
    title="Session Resource Settings",
    description="Override session resource settings",
)
source class-attribute instance-attribute 
source: Optional[str] = Field(
    default=None,
    description="Chat message source identifier, often this will be the name of the client that is managing the chat",
)
user class-attribute instance-attribute 
user: Optional[str] = Field(
    default=None, description="Human user name"
)

Functions

from_header staticmethod 
from_header(header: str) -> EleanorFrameworkHeader

Converts a system message content string into an EleanorFrameworkHeader object.

Parameters:

  • header (str) –

    The system message content.

Returns:

to_header 
to_header() -> str

Converts the EleanorFrameworkHeader object into a string that can be embedded into a system message.

Returns:

  • str ( str ) –

    The system message content.