API Reference

Here is the API reference for gptme.

core

Some of the core classes and functions in gptme.

Message

A message in the conversation.

class gptme.message.Message

A message in the assistant conversation.

role

The role of the message sender (system, user, or assistant).

content

The content of the message.

pinned

Whether this message should be pinned to the top of the chat, and never context-trimmed.

hide

Whether this message should be hidden from the chat output (but still be sent to the assistant).

quiet

Whether this message should be printed on execution (will still print on resume, unlike hide). This is not persisted to the log file.

timestamp

The timestamp of the message.

files

Files attached to the message, could e.g. be images for vision.

__init__(role: ~typing.Literal['system', 'user', 'assistant'], content: str, pinned: bool = False, hide: bool = False, quiet: bool = False, timestamp: ~datetime.datetime = <factory>, files: list[~pathlib.Path] = <factory>) → None

format(oneline: bool = False, highlight: bool = False, max_length: int | None = None) → str

Format the message for display.

Parameters:

• oneline – Whether to format the message as a single line

• highlight – Whether to highlight code blocks

• max_length – Maximum length of the message. If None, no truncation is applied. If set, will truncate at first newline or max_length, whichever comes first.

classmethod from_toml(toml: str) → Self

Converts a TOML string to a message.

The string can be a single [[message]].

get_codeblocks() → list[Codeblock]

Get all codeblocks from the message content.

replace(**kwargs) → Self

Replace attributes of the message.

to_dict(keys=None, provider: Literal['openai', 'anthropic', 'azure', 'openrouter', 'groq', 'xai', 'deepseek', 'local'] | None = None) → dict

Return a dict representation of the message, serializable to JSON.

to_toml() → str

Converts a message to a TOML string, for easy editing by hand in editor to then be parsed back.

to_xml() → str

Converts a message to an XML string.

Codeblock

A codeblock in a message, possibly executable by tools.

class gptme.codeblock.Codeblock

Codeblock(lang: str, content: str, path: str | None = None, start: int | None = None)

__init__(lang: str, content: str, path: str | None = None, start: int | None = None) → None

classmethod from_xml(content: str) → Codeblock

Example

<codeblock lang=”python” path=”example.py”> print(“Hello, world!”) </codeblock>

LogManager

Holds the current conversation as a list of messages, saves and loads the conversation to and from files, supports branching, etc.

class gptme.logmanager.ConversationMeta

Metadata about a conversation.

__init__(name: str, path: str, created: float, modified: float, messages: int, branches: int) → None

format(metadata=False) → str

Format conversation metadata for display.

class gptme.logmanager.Log

Log(messages: list[gptme.message.Message] = <factory>)

__init__(messages: list[~gptme.message.Message] = <factory>) → None

class gptme.logmanager.LogManager

Manages a conversation log.

__init__(log: list[Message] | None = None, logdir: str | Path | None = None, branch: str | None = None)

append(msg: Message) → None

Appends a message to the log, writes the log, prints the message.

branch(name: str) → None

Switches to a branch.

diff(branch: str) → str | None

Prints the diff between the current branch and another branch.

edit(new_log: Log | list[Message]) → None

Edits the log.

fork(name: str) → None

Copy the conversation folder to a new name.

classmethod load(logdir: str | Path, initial_msgs: list[Message] | None = None, branch: str = 'main', create: bool = False, **kwargs) → LogManager

Loads a conversation log.

rename(name: str, keep_date=False) → None

Rename the conversation. Renames the folder containing the conversation and its branches.

If keep_date is True, we will keep the date part of conversation folder name (“2021-08-01-some-name”) If you want to keep the old log, use fork()

to_dict(branches=False) → dict

Returns a dict representation of the log.

undo(n: int = 1, quiet=False) → None

Removes the last message from the log.

write(branches=True) → None

Writes to the conversation log.

gptme.logmanager.get_conversations() → Generator[ConversationMeta, None, None]

Returns all conversations, excluding ones used for testing, evals, etc.

gptme.logmanager.get_user_conversations() → Generator[ConversationMeta, None, None]

Returns all user conversations, excluding ones used for testing, evals, etc.

gptme.logmanager.list_conversations(limit: int = 20, include_test: bool = False) → list[ConversationMeta]

List conversations with a limit.

Parameters:

• limit – Maximum number of conversations to return

• include_test – Whether to include test conversations

gptme.logmanager.prepare_messages(msgs: list[Message]) → list[Message]

Prepares the messages before sending to the LLM.

prompts

See Prompts for more information.

tools

Supporting classes and functions for creating and using tools.

class gptme.tools.ToolSpec

Tool specification. Defines a tool that can be used by the agent.

Parameters:

• name – The name of the tool.

• desc – A description of the tool.

• instructions – Instructions on how to use the tool.

• examples – Example usage of the tool.

• functions – Functions registered in the IPython REPL.

• init – An optional function that is called when the tool is first loaded.

• execute – An optional function that is called when the tool executes a block.

• block_types – A list of block types that the tool will execute.

• available – Whether the tool is available for use.

__init__(name: str, desc: str, instructions: str = '', examples: str = '', functions: list[~collections.abc.Callable] | None = None, init: ~collections.abc.Callable[[], ~gptme.tools.base.ToolSpec] | None = None, execute: ~gptme.tools.base.ExecuteFuncGen | ~gptme.tools.base.ExecuteFuncMsg | None = None, block_types: list[str] = <factory>, available: bool = True) → None

get_doc(doc: str | None = None) → str

Returns an updated docstring with examples.

class gptme.tools.ToolUse

ToolUse(tool: str, args: list[str], content: str, start: int | None = None)

__init__(tool: str, args: list[str], content: str, start: int | None = None) → None

execute(confirm: Callable[[str], bool]) → Generator[Message, None, None]

Executes a tool-use tag and returns the output.

classmethod iter_from_content(content: str) → Generator[ToolUse, None, None]

Returns all ToolUse in a message, markdown or XML, in order.

gptme.tools.execute_msg(msg: Message, confirm: Callable[[str], bool]) → Generator[Message, None, None]

Uses any tools called in a message and returns the response.

server

See Server for more information.

Server for gptme.

gptme.server.create_app(cors_origin: str | None = None) → Flask

Create the Flask app.

Parameters:

cors_origin – CORS origin to allow. Use ‘*’ to allow all origins.