ExLLM.Session (ex_llm v0.5.0)

View Source

Session management for ExLLM - handles conversation sessions with LLM providers.

ExLLM.Session provides pure functional operations for managing conversation sessions, including message history, token tracking, and session persistence. All operations are stateless and return updated session structs.

Quick Start

# Create a new session
session = ExLLM.Session.new("anthropic")

# Add messages
session = ExLLM.Session.add_message(session, "user", "Hello!")
session = ExLLM.Session.add_message(session, "assistant", "Hi there!")

# Get messages
messages = ExLLM.Session.get_messages(session)

# Update token usage
session = ExLLM.Session.update_token_usage(session, %{input_tokens: 10, output_tokens: 15})

Features

  • Pure Functional: All operations are stateless and immutable
  • Message Management: Add, retrieve, and filter conversation messages
  • Token Tracking: Track input/output token usage across conversations
  • Context Storage: Store arbitrary metadata with sessions
  • Session Persistence: Serialize/deserialize sessions to/from JSON
  • LLM Integration: Seamlessly works with ExLLM providers

Session Structure

Sessions are represented by ExLLM.Session.Types.Session structs containing:

  • id - Unique session identifier
  • llm_backend - LLM backend name (optional)
  • messages - List of conversation messages
  • context - Arbitrary metadata map
  • created_at/updated_at - Timestamps
  • token_usage - Token consumption tracking
  • name - Human-readable session name (optional)

Summary

Functions

Add a message to the session.

Clear all messages from the session.

Deserialize session from JSON.

Get messages from the session, optionally with a limit.

Load session from a JSON file.

Create a new session with the specified backend.

Save session to a JSON file.

Set context for the session.

Set the name of the session.

Serialize session to JSON.

Get the total token count for the session.

Update the token usage for the session.

Functions

add_message(session, role, content, opts \\ [])

Add a message to the session.

Parameters

  • session - The session to update
  • role - Message role ("user", "assistant", etc.)
  • content - Message content
  • opts - Additional message metadata

Returns

Updated session with the new message.

Examples

session = ExLLM.Session.add_message(session, "user", "Hello!")
session = ExLLM.Session.add_message(session, "assistant", "Hi there!", timestamp: DateTime.utc_now())

clear_messages(session)

Clear all messages from the session.

Parameters

  • session - The session to clear

Returns

Updated session with empty message list.

Examples

session = ExLLM.Session.clear_messages(session)

from_json(json_string)

@spec from_json(String.t()) ::
  {:ok, ExLLM.Session.Types.Session.t()} | {:error, term()}

Deserialize session from JSON.

Parameters

  • json_string - JSON string to deserialize

Returns

{:ok, session} on success, {:error, reason} on failure.

Examples

{:ok, session} = ExLLM.Session.from_json(json_string)

get_messages(session, limit \\ nil)

Get messages from the session, optionally with a limit.

Parameters

  • session - The session to get messages from
  • limit - Maximum number of messages to return (optional)

Returns

List of messages, most recent first if limited.

Examples

all_messages = ExLLM.Session.get_messages(session)
last_5 = ExLLM.Session.get_messages(session, 5)

load_from_file(file_path)

@spec load_from_file(String.t()) ::
  {:ok, ExLLM.Session.Types.Session.t()} | {:error, term()}

Load session from a JSON file.

Parameters

  • file_path - Path to the file containing session data

Returns

  • {:ok, session} on success
  • {:error, reason} on failure

Examples

{:ok, session} = ExLLM.Session.load_from_file("my_session.json")

new(backend \\ nil, opts \\ [])

@spec new(
  String.t() | nil,
  keyword()
) :: ExLLM.Session.Types.Session.t()

Create a new session with the specified backend.

Parameters

  • backend - LLM backend to use (optional)
  • opts - Additional options (:name for session name)

Returns

A new Session struct.

Examples

session = ExLLM.Session.new("anthropic")
session = ExLLM.Session.new("openai", name: "My Chat")

save_to_file(session, file_path)

@spec save_to_file(ExLLM.Session.Types.Session.t(), String.t()) ::
  :ok | {:error, term()}

Save session to a JSON file.

Parameters

  • session - The session to save
  • file_path - Path to the file where session will be saved

Returns

  • :ok on success
  • {:error, reason} on failure

Examples

ExLLM.Session.save_to_file(session, "my_session.json")

set_context(session, context)

Set context for the session.

Parameters

  • session - The session to update
  • context - Context map to set

Returns

Updated session with new context.

Examples

session = ExLLM.Session.set_context(session, %{temperature: 0.7, max_tokens: 1000})

set_name(session, name)

Set the name of the session.

Parameters

  • session - The session to update
  • name - New session name

Returns

Updated session with new name.

Examples

session = ExLLM.Session.set_name(session, "My Important Chat")

to_json(session)

@spec to_json(ExLLM.Session.Types.Session.t()) :: {:ok, String.t()} | {:error, term()}

Serialize session to JSON.

Parameters

  • session - The session to serialize

Returns

{:ok, json_string} on success, {:error, reason} on failure.

Examples

{:ok, json} = ExLLM.Session.to_json(session)

total_tokens(session)

@spec total_tokens(ExLLM.Session.Types.Session.t()) :: non_neg_integer()

Get the total token count for the session.

Parameters

  • session - The session to analyze

Returns

Total token count (input + output).

Examples

total = ExLLM.Session.total_tokens(session)

update_token_usage(session, usage)

Update the token usage for the session.

Parameters

  • session - The session to update
  • usage - Token usage map with :input_tokens and :output_tokens

Returns

Updated session with new token usage.

Examples

session = ExLLM.Session.update_token_usage(session, %{input_tokens: 100, output_tokens: 150})