ExLLM.Session (ex_llm v0.5.0)
View SourceSession 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 identifierllm_backend
- LLM backend name (optional)messages
- List of conversation messagescontext
- Arbitrary metadata mapcreated_at
/updated_at
- Timestampstoken_usage
- Token consumption trackingname
- 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
@spec add_message(ExLLM.Session.Types.Session.t(), String.t(), String.t(), keyword()) :: ExLLM.Session.Types.Session.t()
Add a message to the session.
Parameters
session
- The session to updaterole
- Message role ("user", "assistant", etc.)content
- Message contentopts
- 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())
@spec clear_messages(ExLLM.Session.Types.Session.t()) :: ExLLM.Session.Types.Session.t()
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)
@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)
@spec get_messages(ExLLM.Session.Types.Session.t(), non_neg_integer() | nil) :: [ ExLLM.Session.Types.message() ]
Get messages from the session, optionally with a limit.
Parameters
session
- The session to get messages fromlimit
- 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)
@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")
@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")
@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 savefile_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")
@spec set_context(ExLLM.Session.Types.Session.t(), ExLLM.Session.Types.context()) :: ExLLM.Session.Types.Session.t()
Set context for the session.
Parameters
session
- The session to updatecontext
- Context map to set
Returns
Updated session with new context.
Examples
session = ExLLM.Session.set_context(session, %{temperature: 0.7, max_tokens: 1000})
@spec set_name(ExLLM.Session.Types.Session.t(), String.t() | nil) :: ExLLM.Session.Types.Session.t()
Set the name of the session.
Parameters
session
- The session to updatename
- New session name
Returns
Updated session with new name.
Examples
session = ExLLM.Session.set_name(session, "My Important Chat")
@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)
@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)
@spec update_token_usage( ExLLM.Session.Types.Session.t(), ExLLM.Session.Types.token_usage() ) :: ExLLM.Session.Types.Session.t()
Update the token usage for the session.
Parameters
session
- The session to updateusage
- 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})