API Reference

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.

timestamp#: The timestamp of the message.

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

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.

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

cost(model: str | None = None, output=False) → float#: Get the input cost of the message in USD.

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) → 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, lock: bool = True)#

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, lock: bool = True, **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.

property workspace: Path#: Path to workspace directory (resolves symlink if exists).

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], workspace: Path | None = None) → list[Message]#: Prepares the messages before sending to the LLM. - Takes the stored gptme conversation log - Enhances it with context such as file contents - Transforms it to the format expected by LLM providers

Config#

Configuration for gptme on user-level (Global config), project-level (Project config), and conversation-level.

class gptme.config.ChatConfig#

Configuration for a chat session.

__init__(_logdir: ~pathlib.Path | None = None, model: str | None = None, tools: list[str] | None = None, tool_format: ToolFormat | None = None, stream: bool = True, interactive: bool = True, env: dict = <factory>, mcp: ~gptme.config.MCPConfig = <factory>) → None#

classmethod from_dict(config_data: dict) → Self#: Create a ChatConfig instance from a dictionary. Warns about unknown keys.

classmethod from_logdir(path: Path) → Self#: Load ChatConfig from a log directory.

classmethod load_or_create(logdir: Path, cli_config: Self) → Self#: Load or create a chat config, applying CLI overrides.

save() → None#: Save the chat config to the log directory.

class gptme.config.Config#

A complete configuration object, including user and project configurations.

It is meant to be used to resolve configuration values, not to be passed around everywhere. Care must be taken to avoid this becoming a “god object” passed around loosely, or frequently used as a global.

__init__(user: ~gptme.config.UserConfig = <factory>, project: ~gptme.config.ProjectConfig | None = None) → None#

classmethod from_workspace(workspace: Path) → Self#: Load the configuration from a workspace directory. Clearing any cache.

get_env(key: str, default: str | None = None) → str | None#: Gets an environment variable, checks the config file if it’s not set in the environment.

get_env_required(key: str) → str#: Gets an environment variable, checks the config file if it’s not set in the environment.

property mcp: MCPConfig#: Get the MCP configuration, merging user and project configurations.

class gptme.config.MCPConfig#

Configuration for Model Context Protocol support, including which MCP servers to use.

__init__(enabled: bool = False, auto_start: bool = False, servers: list[~gptme.config.MCPServerConfig] = <factory>) → None#

classmethod from_dict(doc: dict) → Self#: Create a MCPConfig instance from a dictionary. Warns about unknown keys.

class gptme.config.MCPServerConfig#

Configuration for a MCP server.

__init__(name: str, enabled: bool = True, command: str = '', args: list[str] = <factory>, env: dict = <factory>) → None#

class gptme.config.ProjectConfig#

Project-level configuration, such as which files to include in the context by default.

This is loaded from a gptme.toml Project config file in the project directory or .github directory.

__init__(_workspace: ~pathlib.Path | None = None, base_prompt: str | None = None, prompt: str | None = None, files: list[str] = <factory>, rag: ~gptme.config.RagConfig = <factory>, env: dict[str, str] = <factory>, mcp: ~gptme.config.MCPConfig | None = None) → None#

class gptme.config.RagConfig#

Configuration for retrieval-augmented generation support.

__init__(enabled: bool = False, max_tokens: int | None = None, min_relevance: float | None = None, post_process: bool = True, post_process_model: str | None = None, post_process_prompt: str | None = None, workspace_only: bool = True, paths: list[str] = <factory>) → None#

class gptme.config.UserConfig#

User-level configuration, such as user-specific prompts and environment variables.

__init__(prompt: ~gptme.config.UserPromptConfig = <factory>, env: dict[str, str] = <factory>, mcp: ~gptme.config.MCPConfig = <factory>) → None#

class gptme.config.UserPromptConfig#

User-level configuration for user-specific prompts and project descriptions.

__init__(about_user: str | None = None, response_preference: str | None = None, project: dict[str, str] = <factory>) → None#

gptme.config.get_config() → Config#: Get the current configuration.

gptme.config.get_project_config(workspace: Path | None) → ProjectConfig | None#

Get a cached copy of or load the project configuration from a gptme.toml file in the workspace or .github directory.

Run reload_config() or Config.from_workspace() to reset cache and reload the project config.

gptme.config.load_user_config(path: str | None = None) → UserConfig#: Load the user configuration from the config file.

gptme.config.reload_config() → Config#: Reload the configuration files.

gptme.config.set_config(workspace: Path)#: Set the configuration to use a specific workspace, possibly having a project config.

gptme.config.set_config_value(key: str, value: str) → None#: Set a value in the user config file.

prompts#

See Prompts for more information.

tools#

Supporting classes and functions for creating and using tools.

class gptme.tools.Parameter#

A wrapper for function parameters to convert them to JSON schema.

__init__(name: str, type: str, description: str | None = None, enum: list[Any] | None = None, required: bool = False) → None#

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.
instructions_format – Per tool format instructions when needed.
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.
parameters – Descriptor of parameters use by this tool.
load_priority – Influence the loading order of this tool. The higher the later.
disabled_by_default – Whether this tool should be disabled by default.

__init__(name: str, desc: str, instructions: str = '', instructions_format: dict[str, str] = <factory>, examples: str | ~collections.abc.Callable[[str], 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, parameters: list[~gptme.tools.base.Parameter] = <factory>, load_priority: int = 0, disabled_by_default: bool = False) → None#

get_doc(doc: str | None = None) → str#: Returns an updated docstring with examples.

class gptme.tools.ToolUse#

__init__(tool: str, args: list[str] | None, content: str | None, kwargs: dict[str, str] | None = None, call_id: str | None = None, 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.

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.

API Reference

Contents

API Reference#

core#

Message#

Codeblock#

LogManager#

Config#

prompts#

tools#

server#