@spec chat_input_disabled?(map()) :: boolean()

Determines if the chat input should be disabled for job assistance.

Evaluates multiple conditions to ensure AI assistance is only available when appropriate permissions, limits, and job state allow it.

Examples

# Input disabled due to unsaved job
chat_input_disabled?(%{
  selected_job: %{__meta__: %{state: :built}},
  can_edit_workflow: true,
  ai_limit_result: :ok,
  endpoint_available?: true,
  pending_message: %{loading: nil}
})
# => true

# Input enabled for saved job with permissions
chat_input_disabled?(%{
  selected_job: %{__meta__: %{state: :loaded}},
  can_edit_workflow: true,
  ai_limit_result: :ok,
  endpoint_available?: true,
  pending_message: %{loading: nil}
})
# => false

@spec chat_title(map()) :: String.t()

Generates contextual titles for job assistance sessions.

Creates descriptive titles that include job context when available, making it easier to identify sessions in lists.

Examples

# With custom title
chat_title(%{title: "Debug HTTP 401 error"})
# => "Debug HTTP 401 error"

# With job context
chat_title(%{job: %{name: "Fetch Salesforce Data"}})
# => "Help with Fetch Salesforce Data"

# Fallback
chat_title(%{})
# => "Job Code Help"

@spec create_session(map(), String.t()) :: {:ok, map()} | {:error, any()}

Creates a new job-specific AI assistance session.

Initializes a session with job context, including the job's expression code and adaptor information for targeted AI assistance.

Required Assigns

• :selected_job - The job struct to provide assistance for
• :current_user - The user creating the session

Examples

# Create session for debugging help
{:ok, session} = JobCode.create_session(
  %{selected_job: job, current_user: user},
  "Help me debug this HTTP request error"
)

@spec disabled_tooltip_message(map()) :: String.t() | nil

Generates appropriate tooltip messages when chat input is disabled.

Provides specific explanations for why AI assistance is unavailable, helping users understand what actions they need to take.

Parameters

• assigns - Map containing permission and state information

Returns

String explanation or nil if input should be enabled.

Examples

# Permission denied
disabled_tooltip_message(%{can_edit_workflow: false})
# => "You are not authorized to use the AI Assistant"

# Usage limit reached
disabled_tooltip_message(%{ai_limit_result: {:error, :limit_exceeded}})
# => "Monthly AI usage limit exceeded"

# Unsaved job
disabled_tooltip_message(%{selected_job: %{__meta__: %{state: :built}}})
# => "Save your workflow first to use the AI Assistant"

@spec error_message(any()) :: String.t()

@spec error_message(any()) :: String.t()

Formats errors consistently for job assistance mode.

Leverages shared error handling to provide user-friendly error messages for various failure scenarios.

Parameters

• error - Error to format (changeset, atom, string, etc.)

Returns

Human-readable error message string.

Examples

error_message({:error, :timeout})
# => "Request timed out. Please try again."

error_message(%Ecto.Changeset{})
# => "Validation failed: [specific field errors]"

@spec get_session!(map()) :: map()

Retrieves and enriches a session with job-specific context.

Loads the session and adds the current job's expression and adaptor information, enabling the AI to provide contextual assistance.

Required Assigns

• :selected_job - The job struct to provide context from

Examples

session = JobCode.get_session!(session_id, %{selected_job: current_job})
# session now includes job.body as expression and job.adaptor

Default: no special response handling needed.

@spec input_placeholder() :: String.t()

Provides job-specific placeholder text for the chat input.

Guides users on the types of assistance available for job development and debugging.

@spec list_sessions(map(), atom(), keyword()) :: %{
  sessions: [map()],
  pagination: map()
}

Lists job-specific AI assistance sessions with pagination.

Retrieves sessions associated with the currently selected job, ordered by recency for easy access to recent conversations.

Required Assigns

• :selected_job - The job to filter sessions by

Examples

# Load recent sessions for current job
%{sessions: sessions, pagination: meta} = JobCode.list_sessions(
  %{selected_job: job},
  :desc,
  limit: 10
)

@spec metadata() :: map()

Provides metadata for the job assistance mode.

Returns information used by the UI to display mode selection options and identify the mode's capabilities.

@spec more_sessions?(map(), integer()) :: boolean()

Checks if more sessions exist for the current job.

Determines if additional sessions are available beyond the current count for implementing "Load More" functionality.

Required Assigns

• :selected_job - The job to check session count for

Examples

if JobCode.more_sessions?(%{selected_job: job}, 20) do
  # Show "Load More" button
end

Default: no special session start handling needed.

@spec query(map(), String.t(), map()) :: {:ok, map()} | {:error, any()}

Processes user queries through the job-specific AI assistant.

Sends the user's question along with job context (expression and adaptor) to the AI service for targeted code assistance and debugging help.

Parameters

• session - Session with job context (expression and adaptor)
• content - User's question or request for assistance

Examples

# Get help with specific code issue
{:ok, updated_session} = JobCode.query(
  session,
  "Why is my data transformation returning undefined?"
)

# Request adaptor-specific guidance
{:ok, updated_session} = JobCode.query(
  session,
  "What's the best way to handle errors in HTTP requests?"
)

@spec save_message(map(), String.t()) :: {:ok, map()} | {:error, any()}

Saves a user message to the job assistance session.

Adds the user's message to the conversation history with proper role and user attribution for AI processing.

Required Assigns

• :session - The target session
• :current_user - The user sending the message

Examples

{:ok, updated_session} = JobCode.save_message(
  %{session: session, current_user: user},
  "How do I handle this API error?"
)

@spec supports_template_generation?() :: boolean()

Indicates that job assistance doesn't generate templates.

Job mode focuses on helping with existing code rather than generating new templates or workflows.