@spec job_chat(String.t(), context(), list(), map()) :: Tesla.Env.result()

Requests AI assistance for job-specific coding tasks and debugging.

Sends user queries along with job context (expression code and adaptor) to the Apollo job_chat service. The AI provides targeted assistance for coding tasks, error debugging, adaptor-specific guidance, and best practices.

Parameters

• content - User's question or request for assistance
• context - Job context including expression code and adaptor info
• history - Previous conversation messages for context (list of maps with :role and :content)
• meta - Additional metadata like session IDs or user preferences

Returns

Tesla.Env.result() with response body containing:

• "history" - Updated conversation including AI response
• "usage" - Token usage and cost information
• "meta" - Updated metadata

Examples

# Basic job assistance
{:ok, %{body: %{"history" => updated_history}}} = ApolloClient.job_chat(
  "Why is my HTTP request returning a 401 error?",
  %{
    expression: "fn(state) => http.get('https://api.example.com/data', {headers: {'Authorization': 'Bearer ' + state.token}})",
    adaptor: "@openfn/language-http"
  }
)

# With conversation history
{:ok, response} = ApolloClient.job_chat(
  "Can you show me how to add error handling?",
  job_context,
  [
    %{role: "user", content: "How do I make an HTTP request?"},
    %{role: "assistant", content: "Here's how to make HTTP requests..."}
  ],
  %{session_id: session.id}
)

@spec query(String.t(), context(), list(), map()) :: Tesla.Env.result()

Legacy alias for job_chat/4 maintained for backward compatibility.

Deprecated

Use job_chat/4 instead. This function will be removed in a future version.

Parameters

Same as job_chat/4.

Examples

# Old way (deprecated)
{:ok, response} = ApolloClient.query(content, context, history, meta)

# New way (preferred)
{:ok, response} = ApolloClient.job_chat(content, context, history, meta)

@spec test() :: :ok | :error

Performs a health check on the Apollo service endpoint.

Sends a GET request to the root endpoint to verify the service is running and accessible. This should be called before attempting AI operations to ensure graceful degradation when the service is unavailable.

Returns

• :ok - Service responded with 2xx status code
• :error - Service unavailable, network error, or non-2xx response

Examples

case ApolloClient.test() do
  :ok ->
    # Service is healthy, proceed with AI operations
    show_ai_features()
  :error ->
    # Service unavailable, disable AI features
    hide_ai_features()
end

@spec workflow_chat(
  String.t(),
  String.t() | nil,
  String.t() | nil,
  list(),
  map()
) :: Tesla.Env.result()

Generates or improves workflow templates using AI assistance.

Sends requests to the Apollo workflow_chat service to create complete workflow YAML definitions from natural language descriptions. Can also iteratively improve existing workflows based on validation errors or user feedback.

Parameters

• content - Natural language description of desired workflow functionality
• existing_yaml - Optional existing workflow YAML to modify or improve
• errors - Optional validation errors from previous workflow attempts
• history - Previous conversation messages for context
• meta - Additional metadata

Returns

Tesla.Env.result() with response body containing:

• "response" - Human-readable explanation of the generated workflow
• "response_yaml" - Complete workflow YAML definition
• "usage" - Token usage and cost information

Examples

# Generate new workflow from description
{:ok, %{body: %{"response_yaml" => yaml}}} = ApolloClient.workflow_chat(
  "Create a daily workflow that syncs Salesforce contacts to a PostgreSQL database"
)

# Improve existing workflow
{:ok, response} = ApolloClient.workflow_chat(
  "Add error handling and logging to this workflow",
  existing_workflow_yaml
)

# Fix validation errors
{:ok, response} = ApolloClient.workflow_chat(
  "Please fix the validation errors in this workflow",
  broken_yaml,
  "Invalid cron expression: '0 0 * * 8'. Day of week must be 0-6."
)

# With conversation context
{:ok, response} = ApolloClient.workflow_chat(
  "Make the sync run every 2 hours instead of daily",
  current_yaml,
  nil,
  previous_conversation,
  %{project_id: project.id}
)