Lightning.AiAssistant.ChatMessage (Lightning v2.18.0)

View Source

Represents a message within an AI chat session.

Messages can be from users (role: :user) or from the AI assistant (role: :assistant). User messages start with :pending status and are updated based on processing results. Assistant messages typically have :success status when created.

Schema Fields

  • content - The text content of the message (required, 1-10,000 characters)
  • code - Optional code associated with the message (e.g., generated workflows)
  • response_segments - Optional display timeline of text and status segments for assistant messages (global chat); [] for flat messages (the column is NULL, which embeds_many loads as an empty list)
  • role - Who sent the message: :user or :assistant
  • status - Processing status: :pending, :success, :error, or :cancelled
  • is_deleted - Soft deletion flag (defaults to false)
  • is_public - Whether the message is publicly visible (defaults to true)
  • meta - Additional metadata (e.g., "unsaved_job" for job data not yet saved)
  • chat_session_id - Reference to the parent chat session
  • user_id - Reference to the user who sent the message (required for user messages)

Summary

Types

role()
status()
t()

Functions

changeset(chat_message, attrs)

Creates a changeset for a chat message.

max_response_segments()

Maximum number of segments accepted on a message.

status_changeset(chat_message, status)

Creates a changeset for updating message status.

Types

role()

@type role() :: :user | :assistant

status()

@type status() :: :pending | :processing | :success | :error | :cancelled

t()

@type t() :: %Lightning.AiAssistant.ChatMessage{
  __meta__: term(),
  chat_session: term(),
  chat_session_id: Ecto.UUID.t(),
  code: String.t() | nil,
  content: String.t() | nil,
  id: Ecto.UUID.t(),
  inserted_at: DateTime.t(),
  is_deleted: boolean(),
  is_public: boolean(),
  job: term(),
  job_id: Ecto.UUID.t() | nil,
  meta: map() | nil,
  processing_completed_at: DateTime.t() | nil,
  processing_started_at: DateTime.t() | nil,
  response_segments: [Lightning.AiAssistant.ChatMessage.Segment.t()],
  role: role(),
  status: status(),
  updated_at: DateTime.t(),
  user: term(),
  user_id: Ecto.UUID.t() | nil
}

Functions

changeset(chat_message, attrs)

Creates a changeset for a chat message.

Parameters

  • chat_message - The ChatMessage struct to update (typically %ChatMessage{})
  • attrs - Map of attributes to set/update

Validation Rules

  • content and role are required
  • content must be between 1 and 10,000 characters
  • response_segments, when present, must be 200 or fewer segments, each with a type of text or status and a content string of at most 10000 characters
  • User messages (role: :user) require an associated user
  • Status defaults based on role: :pending for users, :success for assistant
  • If status is explicitly provided, it takes precedence over role-based defaults

max_response_segments()

Maximum number of segments accepted on a message.

status_changeset(chat_message, status)

Creates a changeset for updating message status.

This is a focused changeset that only updates the status field, useful for updating message state during processing.

Parameters

  • chat_message - The existing ChatMessage struct
  • status - New status (:pending, :success, :error, or :cancelled)

Examples

# Mark message as successful
ChatMessage.status_changeset(message, :success)

# Mark message as failed
ChatMessage.status_changeset(message, :error)