Batch

Run multiple PraisonAI scripts at once for quick debugging and testing

The praisonai batch command discovers and runs all Python files containing PraisonAI imports in a directory. It’s designed for quick debugging and testing of multiple scripts at once.

Basic Usage

# Run all PraisonAI scripts in current directory
praisonai batch

# Include subdirectories
praisonai batch --sub

# Limit recursion depth
praisonai batch --sub --depth 2

Key Features

• Auto-discovery: Finds all .py files with from praisonaiagents or from praisonai imports
• Server exclusion: Automatically excludes server scripts (uvicorn, Flask, streamlit, etc.) that would hang
• Agent filtering: Filter by agent type (Agent, Agents, Workflow)
• CI integration: Machine-readable output for automated pipelines
• Parallel execution: Run multiple scripts concurrently
• Report generation: JSON, Markdown, and CSV reports

Options

Option	Description
--path, -p	Path to search (default: current directory)
--sub, -r	Include subdirectories
--depth, -d	Maximum recursion depth (only with —sub)
--timeout, -t	Per-script timeout in seconds (default: 60)
--parallel	Run in parallel with async reporting
--workers, -w	Max parallel workers (default: 4)
--server	Run only server scripts with 10s timeout
--filter, -f	Filter by type: ‘agent’, ‘agents’, or ‘workflow’
--ci	CI-friendly output (no colors, proper exit codes)
--quiet, -q	Minimal output
--fail-fast, -x	Stop on first failure
--include-tests	Include test files (test_*.py, *_test.py)
--no-report	Skip report generation
--report-dir	Custom report directory

Server Script Handling

By default, the batch command excludes server scripts that would hang during execution. Server scripts are detected by patterns like:

• uvicorn.run() - ASGI servers
• .launch() - PraisonAI agent APIs, Gradio interfaces
• app.run() - Flask applications
• import streamlit - Streamlit apps
• import gradio - Gradio apps
• FastAPI(), Flask() - Web frameworks

Running Server Scripts

Use the --server flag to run only server scripts with a 10-second timeout:

# Run only server scripts (10s timeout each)
praisonai batch --server

# Server scripts in subdirectories
praisonai batch --server --sub

This is useful for smoke-testing that server scripts start correctly.

Filtering by Agent Type

Filter scripts by the PraisonAI components they use:

# Only scripts using Agent class
praisonai batch --filter agent

# Only scripts using Agents/PraisonAIAgents (multi-agent)
praisonai batch --filter agents

# Only scripts using Workflow
praisonai batch --filter workflow

CI Integration

The --ci flag provides machine-readable output suitable for CI/CD pipelines:

# CI-friendly output
praisonai batch --ci

# CI with proper exit codes
praisonai batch --ci --fail-fast

CI mode features:

• No emoji/color output (plain text)
• Proper exit codes (0 = success, 1 = failures, 2 = errors)
• Machine-parseable summary

Example CI Output

============================================================
PraisonAI Batch Runner
============================================================
Path: /path/to/scripts
Recursive: False
Timeout: 60s
Scripts: 5
Reports: /Users/user/Downloads/reports/batch/20240115_120000

[1/5] Running: agent_example.py
  PASS PASSED (2.34s)
[2/5] Running: multi_agent.py
  PASS PASSED (5.67s)
[3/5] Running: broken_script.py
  FAIL FAILED (0.12s)
     Error: ImportError: No module named 'missing'

============================================================
SUMMARY
============================================================
  PASSED:  2
  FAILED:  1
  SKIPPED: 0
  TIMEOUT: 0
  -----------------
  TOTAL:   3
============================================================
Reports: /Users/user/Downloads/reports/batch/20240115_120000

Parallel Execution

Run scripts concurrently for faster execution:

# Run in parallel with 4 workers (default)
praisonai batch --parallel

# Custom worker count
praisonai batch --parallel --workers 8

# Parallel with CI output
praisonai batch --parallel --ci

Subcommands

List Scripts

List discovered scripts without running them:

# List all discovered scripts
praisonai batch list

# List with subdirectories
praisonai batch list --sub

# Show available groups only
praisonai batch list --groups

Show Statistics

Display statistics about discovered scripts:

praisonai batch stats
praisonai batch stats --sub

Output includes counts by:

• Group (directory)
• Runnable status
• Agent type (Agent, Agents, Workflow)

View Reports

View the latest execution report:

# Summary view
praisonai batch report

# Show failures only
praisonai batch report --format failures

# Full details
praisonai batch report --format full

# Specific report directory
praisonai batch report --dir ~/Downloads/reports/batch/20240115_120000

Script Directives

Control script behavior with comment directives:

# praisonai: skip=true
# praisonai: timeout=120
# praisonai: require_env=OPENAI_API_KEY,ANTHROPIC_API_KEY
# praisonai: xfail=Known issue with API

from praisonaiagents import Agent
# ... rest of script

Directive	Description
skip=true	Skip this script
timeout=N	Custom timeout in seconds
require_env=KEY1,KEY2	Required environment variables
xfail=reason	Expected to fail (mark as xfail instead of fail)

Reports

Reports are saved to ~/Downloads/reports/batch/<timestamp>/ by default:

• report.json - Full JSON report
• report.md - Markdown summary
• report.csv - CSV for spreadsheet analysis
• logs/ - Individual script output logs

Examples

Basic Testing

# Test all scripts in examples folder
praisonai batch --path ./examples

# Test with subdirectories, 2 levels deep
praisonai batch --path ./examples --sub --depth 2

CI Pipeline

# GitHub Actions / GitLab CI
praisonai batch --ci --fail-fast --timeout 30

# With parallel execution
praisonai batch --ci --parallel --workers 4

Development Workflow

# Quick test of agent scripts only
praisonai batch --filter agent --timeout 30

# Test multi-agent workflows
praisonai batch --filter agents --sub

# Smoke test server scripts
praisonai batch --server

Exit Codes

Code	Meaning
0	All scripts passed
1	One or more scripts failed or timed out
2	Configuration error (invalid path, invalid filter)