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.
