​
Progress Reporting

When building bots that perform lengthy operations, it’s important to keep users informed about the bot’s progress. The lil’bots platform provides a simple yet powerful progress reporting mechanism that displays a progress bar to users while your bot is running.

​
How It Works

Progress reporting works by allowing your bot to send updates about its completion status. These updates are displayed to the user as a progress bar, helping them understand how far along the bot is in completing its task.

Progress is represented as a decimal value between 0 (not started) and 1 (completed).

​
Implementation

​
JavaScript Runtime

In JavaScript-based bots, you can use the updateProgress function provided by the lilbots library:

import { updateProgress } from 'lilbots';

export async function main(inputs, params) {
  // Initialize progress
  updateProgress(0); // 0% complete
  
  // Processing step 1
  await processStep1();
  updateProgress(0.25); // 25% complete
  
  // Processing step 2
  await processStep2();
  updateProgress(0.5); // 50% complete
  
  // Processing step 3
  await processStep3();
  updateProgress(0.75); // 75% complete
  
  // Final processing
  await finalProcessing();
  updateProgress(1); // 100% complete
  
  return [{
    title: "Process Complete",
    message: "All processing has been completed successfully."
  }];
}

// Example processing functions
async function processStep1() {
  // Simulating work with a delay
  await new Promise(resolve => setTimeout(resolve, 1000));
}

async function processStep2() {
  await new Promise(resolve => setTimeout(resolve, 1500));
}

async function processStep3() {
  await new Promise(resolve => setTimeout(resolve, 800));
}

async function finalProcessing() {
  await new Promise(resolve => setTimeout(resolve, 700));
}

​
Python Runtime

In Python-based bots, you can use the update_progress function from the lilbots module:

from lilbots import update_progress
import time

def main(inputs, params):
    # Initialize progress
    update_progress(0)  # 0% complete
    
    # Processing step 1
    process_step_1()
    update_progress(0.25)  # 25% complete
    
    # Processing step 2
    process_step_2()
    update_progress(0.5)  # 50% complete
    
    # Processing step 3
    process_step_3()
    update_progress(0.75)  # 75% complete
    
    # Final processing
    final_processing()
    update_progress(1)  # 100% complete
    
    return [{
        "title": "Process Complete",
        "message": "All processing has been completed successfully."
    }]

# Example processing functions
def process_step_1():
    # Simulating work with a delay
    time.sleep(1)

def process_step_2():
    time.sleep(1.5)

def process_step_3():
    time.sleep(0.8)

def final_processing():
    time.sleep(0.7)

​
Best Practices

​
1. Use Reasonable Update Frequency

Update progress at meaningful intervals. Updating too frequently (e.g., in tight loops) can create unnecessary network traffic, while updating too infrequently can leave users wondering if the bot is still working.

// Good practice in a loop
for (let i = 0; i < 100; i++) {
  await processItem(i);
  
  // Update every 10 items or use a percentage calculation
  if (i % 10 === 0 || i === 99) {
    updateProgress(i / 99);
  }
}

​
2. Handle Indeterminate Progress

For operations where you can’t determine precise progress, consider using fixed increments or milestone-based reporting:

import { updateProgress } from 'lilbots';

export async function main(inputs, params) {
  // Starting the process
  updateProgress(0.1); // Indicate that processing has begun
  
  try {
    // When you reach a milestone in your process
    const data = await fetchExternalData();
    updateProgress(0.3); // Data fetched successfully
    
    const processedData = await processData(data);
    updateProgress(0.7); // Data processed
    
    await saveResults(processedData);
    updateProgress(1); // Process complete
    
    return [{ title: "Success", message: "Processing completed successfully" }];
  } catch (error) {
    return [{ title: "Error", message: "An error occurred: " + error.message }];
  }
}

​
3. Provide Additional Context (when possible)

In some cases, you might want to provide additional context alongside the progress update:

from lilbots import update_progress

def main(inputs, params):
    files_to_process = get_files_list(inputs.get("source_dir"))
    total_files = len(files_to_process)
    
    for index, file in enumerate(files_to_process):
        process_file(file)
        
        # Update progress with fraction complete
        current_progress = (index + 1) / total_files
        update_progress(current_progress)
        
        # Note: While the lilbots platform currently only displays 
        # the progress bar, future versions might support additional
        # status information
    
    return [{"title": "Processing Complete", "message": f"Processed {total_files} files"}]

​
Example: File Processing Bot

Here’s a complete example of a bot that processes multiple files and reports progress:

import { updateProgress } from 'lilbots';

export async function main(inputs, params) {
  const files = inputs.files || [];
  const totalFiles = files.length;
  
  if (totalFiles === 0) {
    return [{
      title: "No Files",
      message: "No files were provided for processing."
    }];
  }
  
  updateProgress(0);
  
  const results = [];
  for (let i = 0; i < totalFiles; i++) {
    const file = files[i];
    
    // Process the current file
    const result = await processFile(file);
    results.push(result);
    
    // Update progress
    updateProgress((i + 1) / totalFiles);
  }
  
  return [{
    title: "Processing Complete",
    message: `Successfully processed ${totalFiles} files.`,
    data: results
  }];
}

async function processFile(file) {
  // Simulate file processing with a delay
  await new Promise(resolve => setTimeout(resolve, 500));
  
  // Return some mock processing result
  return {
    filename: file.name,
    size: file.size,
    processingStatus: "success",
    timestamp: new Date().toISOString()
  };
}

​
Limitations

  • Progress values must be between 0 and 1 (inclusive). Values outside this range will be clamped.
  • The progress bar is a visual indicator only and doesn’t affect the execution of your bot.
  • Progress updates are best-effort and might be delayed or dropped in case of network issues.

Remember that the progress reporting feature is particularly useful for bots that perform long-running tasks, helping to provide users with confidence that your bot is working as expected.