@spec associate_workflow(
  Lightning.AiAssistant.ChatSession.t(),
  Lightning.Workflows.Workflow.t()
) ::
  {:ok, Lightning.AiAssistant.ChatSession.t()} | {:error, Ecto.Changeset.t()}

Associates a workflow with a chat session.

Links a generated workflow to the session that created it, enabling tracking and future modifications through the same conversation context.

Parameters

• session - The %ChatSession{} that generated the workflow
• workflow - The %Workflow{} struct to associate

Returns

• {:ok, session} - Successfully linked workflow to session
• {:error, changeset} - Association failed with validation errors

@spec create_session(
  Lightning.Workflows.Job.t(),
  Lightning.Accounts.User.t(),
  String.t(),
  opts()
) ::
  {:ok, Lightning.AiAssistant.ChatSession.t()} | {:error, Ecto.Changeset.t()}

Creates a new chat session for job-specific AI assistance.

Initializes a new session with:

• Association with the specified job and user
• Auto-generated title from the initial message content
• Job's expression and adaptor context (virtual fields)
• The initial user message

Parameters

• job - The %Job{} struct this session will assist with
• user - The %User{} creating the session
• content - Initial message content that will become the session title
• opts - Keyword list of options:
  • :meta - Optional metadata for the session
  • :code - Optional workflow code for the initial message

Returns

• {:ok, session} - Successfully created session with initial message
• {:error, changeset} - Validation errors during creation

@spec create_workflow_session(
  Lightning.Projects.Project.t(),
  Lightning.Workflows.Workflow.t() | nil,
  Lightning.Accounts.User.t(),
  String.t(),
  opts()
) :: {:ok, Lightning.AiAssistant.ChatSession.t()} | {:error, Ecto.Changeset.t()}

Creates a new chat session for workflow template generation.

Initializes a session specifically for creating workflow templates:

• Associates with a project and optionally an existing workflow
• Sets session type to "workflow_template"
• Includes the initial user message describing the desired workflow

Parameters

• project - The %Project{} struct where the workflow will be created
• workflow - The %Workflow{} struct to associate with the session, or nil for new workflows
• user - The %User{} requesting the workflow template
• content - Description of the desired workflow functionality
• opts - Keyword list of options:
  • :meta - Optional metadata for the session
  • :code - Optional workflow code for the initial message

Returns

• {:ok, session} - Successfully created workflow session with initial message
• {:error, changeset} - Validation errors during creation

@spec enabled?() :: boolean()

Checks if the AI assistant feature is enabled via application configuration.

Verifies that both the Apollo endpoint URL and API key are properly configured, which are required for AI functionality.

Returns

true if AI assistant is properly configured and enabled, false otherwise.

@spec endpoint_available?() :: boolean()

Checks if the Apollo AI service endpoint is reachable and responding.

Performs a connectivity test to ensure the external AI service is available before attempting to make actual queries.

Returns

true if the Apollo endpoint responds successfully, false otherwise.

@spec enrich_session_with_job_context(Lightning.AiAssistant.ChatSession.t()) ::
  Lightning.AiAssistant.ChatSession.t()

Enriches a chat session with job-specific context.

Loads the associated job and enriches the session with:

• Job expression code and adaptor information
• Run logs if following a specific run (via session.meta["follow_run_id"])

Parameters

• session - The chat session to enrich

Returns

The enriched session with job context loaded

@spec find_pending_user_messages(Lightning.AiAssistant.ChatSession.t()) :: [
  Lightning.AiAssistant.ChatMessage.t()
]

Finds all pending user messages in a chat session.

Retrieves messages that have been sent by users but are still waiting for processing or AI responses. Useful for identifying stuck or failed requests.

Parameters

• session - The %ChatSession{} to search

Returns

List of %ChatMessage{} structs with :role of :user and :status of :pending.

Retrieves a chat session by ID with all related data preloaded.

Fetches a complete chat session including:

• All non-cancelled messages ordered by creation time
• User information for each message
• Session metadata
• Project information (for workflow template sessions)

Parameters

• id - UUID string of the session to retrieve

Returns

A ChatSession struct with preloaded :messages and nested :user data. For workflow template sessions, the :project association is also preloaded.

Raises

Ecto.NoResultsError if no session exists with the given ID.

@spec has_more_sessions?(
  Lightning.Projects.Project.t() | Lightning.Workflows.Job.t(),
  integer()
) ::
  boolean()

Checks if additional sessions are available beyond the current count.

This is a convenience function to determine if there are more sessions to load without fetching the actual data. Useful for "Load More" UI patterns.

Parameters

• resource - A %Project{} or %Job{} struct
• current_count - Number of sessions already loaded

Returns

true if more sessions exist, false otherwise.

@spec list_sessions(
  Lightning.Projects.Project.t() | Lightning.Workflows.Job.t(),
  :asc | :desc,
  opts()
) ::
  %{
    sessions: [Lightning.AiAssistant.ChatSession.t()],
    pagination: LightningWeb.Live.AiAssistant.PaginationMeta.t()
  }

Returns paginated chat sessions with metadata for improved user experience.

Retrieves chat sessions associated with either a Project (workflow template sessions) or a Job (job-specific sessions). Results are paginated and include total counts and navigation metadata.

Parameters

• resource - A %Project{}, %Job{}, or %Snapshot.Job{} struct to filter sessions by
• sort_direction - Sort order, either :asc or :desc (default: :desc)
• opts - Keyword list of options:
  • :offset - Number of records to skip (default: 0)
  • :limit - Maximum number of records to return (default: 20)

Returns

A map containing:

• :sessions - List of ChatSession structs with preloaded data
• :pagination - PaginationMeta struct with navigation information

@spec mark_disclaimer_read(Lightning.Accounts.User.t()) ::
  {:ok, Lightning.Accounts.User.t()}

Records that a user has read and accepted the AI assistant disclaimer.

Updates the user's preferences with a timestamp indicating when they acknowledged the AI assistant terms and conditions.

Parameters

• user - The %User{} who read the disclaimer

Returns

{:ok, user} - Successfully recorded disclaimer acceptance.

@spec put_expression_and_adaptor(
  Lightning.AiAssistant.ChatSession.t(),
  String.t(),
  String.t()
) ::
  Lightning.AiAssistant.ChatSession.t()

Adds job-specific context to a chat session for enhanced AI assistance.

Enriches a session with the job's expression code and adaptor information, enabling the AI to provide more targeted and relevant assistance.

Parameters

• session - The %ChatSession{} to enhance
• expression - The job's expression code as a string
• adaptor - The adaptor name/identifier for the job

Returns

An updated ChatSession struct with :expression and :adaptor fields populated. The adaptor is resolved through Lightning.AdaptorRegistry.

@spec query(Lightning.AiAssistant.ChatSession.t(), String.t(), opts()) ::
  {:ok, Lightning.AiAssistant.ChatSession.t()}
  | {:error, String.t() | Ecto.Changeset.t()}

Queries the AI assistant for job-specific code assistance.

Sends a user query to the Apollo AI service along with job context (expression and adaptor) and conversation history. The AI provides targeted assistance for coding tasks, debugging, and adaptor-specific guidance.

Parameters

• session - The job-specific %ChatSession{} with expression and adaptor context
• content - User's question or request for assistance

Returns

• {:ok, session} - AI responded successfully, session updated with response
• {:error, reason} - Query failed, reason is either a string error message or changeset

@spec query_workflow(Lightning.AiAssistant.ChatSession.t(), String.t(), opts()) ::
  {:ok, Lightning.AiAssistant.ChatSession.t()}
  | {:error, String.t() | Ecto.Changeset.t()}

Queries the AI service for workflow template generation.

Sends a request to generate or modify workflow templates based on user requirements. Can include validation errors from previous attempts to help the AI provide corrections.

Parameters

• session - The workflow template %ChatSession{}
• content - User's description of desired workflow functionality or modifications
• opts - Keyword list of options:
  • :code - Current YAML to modify (default: uses latest from session)
  • :errors - Validation errors from previous workflow attempts
  • :meta - Additional metadata to pass to the AI service (default: session.meta)

Returns

• {:ok, session} - Workflow template generated successfully
• {:error, reason} - Generation failed, reason is either a string error message or changeset

Resets a message status to pending and enqueues it for reprocessing. Handles both the database update and Oban job creation atomically.

@spec save_message(Lightning.AiAssistant.ChatSession.t(), map(), opts()) ::
  {:ok, Lightning.AiAssistant.ChatSession.t()} | {:error, Ecto.Changeset.t()}

Saves a message to an existing chat session.

Adds a new message to the session's message history and updates the session. For assistant messages, this also triggers AI usage tracking and limit enforcement.

Parameters

• session - The target %ChatSession{}
• message_attrs - Map containing message data with keys like :role, :content, :user
• opts - Keyword list of options:
  • :usage - Map containing AI usage metrics (default: %{})
  • :meta - Session metadata to update (default: keeps existing)
  • :code - Optional workflow code to attach to the message

Returns

• {:ok, session} - Successfully saved message and updated session
• {:error, changeset} - Validation or database errors

@spec title_max_length() :: non_neg_integer()

Returns the maximum allowed length for chat session titles.

@spec update_message_status(
  Lightning.AiAssistant.ChatSession.t(),
  Lightning.AiAssistant.ChatMessage.t(),
  atom()
) :: {:ok, Lightning.AiAssistant.ChatSession.t()} | {:error, Ecto.Changeset.t()}

Updates the status of a specific message within a chat session.

Changes the status of an individual message (e.g., from :pending to :success or :error) and returns the refreshed session with updated data.

Parameters

• session - The %ChatSession{} containing the message
• message - The specific %ChatMessage{} to update
• status - New status atom (e.g., :pending, :success, :error, :cancelled)

Returns

• {:ok, session} - Successfully updated message, returns refreshed session
• {:error, changeset} - Update failed with validation errors

@spec user_has_read_disclaimer?(Lightning.Accounts.User.t()) :: boolean()

Checks if a user has acknowledged the AI assistant disclaimer recently.

Verifies that the user has read and accepted the AI assistant terms and conditions within the last 24 hours. This ensures users are aware of AI limitations and usage terms.

Parameters

• user - The %User{} struct to check

Returns

true if disclaimer was read within 24 hours, false otherwise.