AI Report Orchestrator Tool Configuration Guide

Overview

The AI Report Orchestrator Tool is a powerful tool that provides advanced report generation with automated analysis report creation, multiple report types and formats, integration with analysis results, visualization embedding, and export to multiple formats. It can generate comprehensive analysis reports, customize report structure and style, include visualizations and tables, export to multiple formats, and integrate analysis results and insights. The tool integrates with report_tool for document generation and supports various report types (executive_summary, technical_report, business_report, research_paper, data_quality_report) and formats (markdown, html, pdf, word, json). The tool can be configured via environment variables using the AI_REPORT_ORCHESTRATOR_ prefix or through programmatic configuration when initializing the tool.

Using .env Files in Your Project

When using aiecs as a dependency in your project, you can store configuration in a .env file for convenience. The AI Report Orchestrator Tool reads from environment variables that are already loaded into the process, so you need to load the .env file in your application before importing aiecs tools.

Setting Up .env Files

1. Install python-dotenv:

pip install python-dotenv

2. Create a .env file in your project root:

# .env file in your project root
AI_REPORT_ORCHESTRATOR_DEFAULT_REPORT_TYPE=business_report
AI_REPORT_ORCHESTRATOR_DEFAULT_FORMAT=markdown
AI_REPORT_ORCHESTRATOR_OUTPUT_DIRECTORY=/tmp/reports
AI_REPORT_ORCHESTRATOR_INCLUDE_CODE=false
AI_REPORT_ORCHESTRATOR_INCLUDE_VISUALIZATIONS=true
AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=20

3. Load the .env file in your application:

# main.py or app.py - at the top of your entry point
from dotenv import load_dotenv

# Load environment variables from .env file
# This must be done BEFORE importing aiecs tools
load_dotenv()

# Now import and use aiecs tools
from aiecs.tools.statistics.ai_report_orchestrator_tool import AIReportOrchestratorTool

# The tool will automatically use the environment variables
report_tool = AIReportOrchestratorTool()

Multiple Environment Files

You can use different .env files for different environments:

import os
from dotenv import load_dotenv

# Load environment-specific configuration
env = os.getenv('APP_ENV', 'development')

if env == 'production':
    load_dotenv('.env.production')
elif env == 'staging':
    load_dotenv('.env.staging')
else:
    load_dotenv('.env.development')

from aiecs.tools.statistics.ai_report_orchestrator_tool import AIReportOrchestratorTool
report_tool = AIReportOrchestratorTool()

Example .env.production:

# Production settings - optimized for professional reports
AI_REPORT_ORCHESTRATOR_DEFAULT_REPORT_TYPE=business_report
AI_REPORT_ORCHESTRATOR_DEFAULT_FORMAT=pdf
AI_REPORT_ORCHESTRATOR_OUTPUT_DIRECTORY=/app/reports
AI_REPORT_ORCHESTRATOR_INCLUDE_CODE=false
AI_REPORT_ORCHESTRATOR_INCLUDE_VISUALIZATIONS=true
AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=30

Example .env.development:

# Development settings - optimized for testing and debugging
AI_REPORT_ORCHESTRATOR_DEFAULT_REPORT_TYPE=technical_report
AI_REPORT_ORCHESTRATOR_DEFAULT_FORMAT=markdown
AI_REPORT_ORCHESTRATOR_OUTPUT_DIRECTORY=./reports
AI_REPORT_ORCHESTRATOR_INCLUDE_CODE=true
AI_REPORT_ORCHESTRATOR_INCLUDE_VISUALIZATIONS=false
AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=10

Best Practices for .env Files

1. Never commit .env files to version control - Add .env to your .gitignore:

   # .gitignore
   .env
   .env.local
   .env.*.local
   .env.production
   .env.staging
   

2. Provide a template - Create .env.example with documented dummy values:

   # .env.example
   # AI Report Orchestrator Tool Configuration
   
   # Default report type to generate
   AI_REPORT_ORCHESTRATOR_DEFAULT_REPORT_TYPE=business_report
   
   # Default report output format
   AI_REPORT_ORCHESTRATOR_DEFAULT_FORMAT=markdown
   
   # Directory for report output files
   AI_REPORT_ORCHESTRATOR_OUTPUT_DIRECTORY=/tmp/reports
   
   # Whether to include code snippets in reports
   AI_REPORT_ORCHESTRATOR_INCLUDE_CODE=false
   
   # Whether to include visualizations in reports
   AI_REPORT_ORCHESTRATOR_INCLUDE_VISUALIZATIONS=true
   
   # Maximum number of insights to include per report
   AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=20
   

3. Document your variables - Add comments explaining each setting

4. Use load_dotenv() early - Call it at the very top of your entry point, before any aiecs imports

5. Format values correctly:

   • Strings: Plain text: business_report, markdown, /tmp/reports

   • Integers: Plain numbers: 20, 30

   • Booleans: true or false

Configuration Options

1. Default Report Type

Environment Variable: AI_REPORT_ORCHESTRATOR_DEFAULT_REPORT_TYPE

Type: String

Default: "business_report"

Description: Default report type to generate when no specific type is specified. This determines the structure, style, and content focus of the generated reports.

Supported Types:

• executive_summary - Executive summary reports

• technical_report - Technical analysis reports

• business_report - Business-focused reports (default)

• research_paper - Academic research papers

• data_quality_report - Data quality assessment reports

Example:

export AI_REPORT_ORCHESTRATOR_DEFAULT_REPORT_TYPE=technical_report

Type Note: Choose the type that best fits your typical reporting needs.

2. Default Format

Environment Variable: AI_REPORT_ORCHESTRATOR_DEFAULT_FORMAT

Type: String

Default: "markdown"

Description: Default report output format when no specific format is specified. This determines how the report is structured and exported.

Supported Formats:

• markdown - Markdown format (default, lightweight)

• html - HTML format (web-friendly)

• pdf - PDF format (professional documents)

• word - Microsoft Word format

• json - JSON format (structured data)

Example:

export AI_REPORT_ORCHESTRATOR_DEFAULT_FORMAT=pdf

Format Note: Choose the format based on your distribution and presentation needs.

3. Output Directory

Environment Variable: AI_REPORT_ORCHESTRATOR_OUTPUT_DIRECTORY

Type: String

Default: tempfile.gettempdir()

Description: Directory where generated reports are saved. This directory must be accessible and writable by the application.

Example:

export AI_REPORT_ORCHESTRATOR_OUTPUT_DIRECTORY="/app/reports"

Directory Note: Ensure the directory has appropriate permissions and is accessible.

4. Include Code

Environment Variable: AI_REPORT_ORCHESTRATOR_INCLUDE_CODE

Type: Boolean

Default: False

Description: Whether to include code snippets and technical implementation details in reports. Useful for technical reports but may not be appropriate for business reports.

Values:

• true - Include code snippets

• false - Exclude code snippets (default)

Example:

export AI_REPORT_ORCHESTRATOR_INCLUDE_CODE=true

Code Note: Enable for technical reports, disable for business-focused reports.

5. Include Visualizations

Environment Variable: AI_REPORT_ORCHESTRATOR_INCLUDE_VISUALIZATIONS

Type: Boolean

Default: True

Description: Whether to include charts, graphs, and other visualizations in reports. Visualizations enhance report readability but may increase file size.

Values:

• true - Include visualizations (default)

• false - Exclude visualizations

Example:

export AI_REPORT_ORCHESTRATOR_INCLUDE_VISUALIZATIONS=true

Visualization Note: Visualizations improve report quality but may impact performance and file size.

6. Max Insights Per Report

Environment Variable: AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT

Type: Integer

Default: 20

Description: Maximum number of insights to include in each report. This helps control report length and focus on the most important findings.

Common Values:

• 10 - Concise reports (key insights only)

• 20 - Standard reports (default, balanced)

• 30 - Comprehensive reports (detailed insights)

• 50 - Extensive reports (maximum detail)

Example:

export AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=30

Insights Note: Higher values provide more detail but may make reports less focused.

Usage Examples

Example 1: Basic Environment Configuration

# Set basic report generation parameters
export AI_REPORT_ORCHESTRATOR_DEFAULT_REPORT_TYPE=business_report
export AI_REPORT_ORCHESTRATOR_DEFAULT_FORMAT=markdown
export AI_REPORT_ORCHESTRATOR_OUTPUT_DIRECTORY=/tmp/reports
export AI_REPORT_ORCHESTRATOR_INCLUDE_CODE=false
export AI_REPORT_ORCHESTRATOR_INCLUDE_VISUALIZATIONS=true
export AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=20

# Run your application
python app.py

Example 2: Professional Configuration

# Optimized for professional business reports
export AI_REPORT_ORCHESTRATOR_DEFAULT_REPORT_TYPE=business_report
export AI_REPORT_ORCHESTRATOR_DEFAULT_FORMAT=pdf
export AI_REPORT_ORCHESTRATOR_OUTPUT_DIRECTORY=/app/reports
export AI_REPORT_ORCHESTRATOR_INCLUDE_CODE=false
export AI_REPORT_ORCHESTRATOR_INCLUDE_VISUALIZATIONS=true
export AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=30

Example 3: Development Configuration

# Development-friendly settings
export AI_REPORT_ORCHESTRATOR_DEFAULT_REPORT_TYPE=technical_report
export AI_REPORT_ORCHESTRATOR_DEFAULT_FORMAT=markdown
export AI_REPORT_ORCHESTRATOR_OUTPUT_DIRECTORY=./reports
export AI_REPORT_ORCHESTRATOR_INCLUDE_CODE=true
export AI_REPORT_ORCHESTRATOR_INCLUDE_VISUALIZATIONS=false
export AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=10

Example 4: Programmatic Configuration

from aiecs.tools.statistics.ai_report_orchestrator_tool import AIReportOrchestratorTool

# Initialize with custom configuration
report_tool = AIReportOrchestratorTool(config={
    'default_report_type': 'business_report',
    'default_format': 'markdown',
    'output_directory': '/app/reports',
    'include_code': False,
    'include_visualizations': True,
    'max_insights_per_report': 20
})

Example 5: Mixed Configuration

Environment variables are used as defaults, but can be overridden programmatically:

# Set environment defaults
export AI_REPORT_ORCHESTRATOR_DEFAULT_FORMAT=markdown
export AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=20

# Override for specific instance
report_tool = AIReportOrchestratorTool(config={
    'default_format': 'pdf',  # This overrides the environment variable
    'max_insights_per_report': 30  # This overrides the environment variable
})

Configuration Priority

When the AI Report Orchestrator Tool is initialized, configuration values are resolved in the following order (highest to lowest priority):

1. Programmatic config - Values passed to the constructor

2. Environment variables - Values set via AI_REPORT_ORCHESTRATOR_* variables

3. Default values - Built-in defaults as specified above

Data Type Parsing

String Values

Strings should be provided as plain text without quotes:

export AI_REPORT_ORCHESTRATOR_DEFAULT_REPORT_TYPE=business_report
export AI_REPORT_ORCHESTRATOR_DEFAULT_FORMAT=markdown
export AI_REPORT_ORCHESTRATOR_OUTPUT_DIRECTORY=/app/reports

Integer Values

Integers should be provided as numeric strings:

export AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=20
export AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=30

Boolean Values

Booleans should be provided as lowercase strings:

export AI_REPORT_ORCHESTRATOR_INCLUDE_CODE=true
export AI_REPORT_ORCHESTRATOR_INCLUDE_VISUALIZATIONS=false

Validation

Automatic Type Validation

Pydantic automatically validates configuration values:

• default_report_type must be a valid report type string

• default_format must be a valid format string

• output_directory must be a non-empty string

• include_code must be a boolean

• include_visualizations must be a boolean

• max_insights_per_report must be a positive integer

Runtime Validation

When generating reports, the tool validates:

1. Output directory - Directory must be accessible and writable

2. Report type - Type must be supported

3. Format compatibility - Format must be compatible with report type

4. Insight limits - Number of insights must not exceed maximum

5. File permissions - Output directory must have write permissions

Report Types

The AI Report Orchestrator Tool supports various report types:

Business Reports

• Executive Summary - High-level executive summaries

• Business Report - Business-focused analysis reports

• Data Quality Report - Data quality assessment reports

Technical Reports

• Technical Report - Technical analysis and implementation reports

• Research Paper - Academic-style research papers

Report Formats

Document Formats

• Markdown - Lightweight, readable format

• HTML - Web-friendly format with styling

• PDF - Professional document format

• Word - Microsoft Word format

Data Formats

• JSON - Structured data format for programmatic use

Operations Supported

The AI Report Orchestrator Tool supports comprehensive report generation operations:

Basic Report Generation

• generate_report - Generate comprehensive analysis reports

• generate_executive_summary - Generate executive summary reports

• generate_technical_report - Generate technical analysis reports

• generate_business_report - Generate business-focused reports

• generate_research_paper - Generate academic research papers

Advanced Report Operations

• customize_report_structure - Customize report structure and layout

• embed_visualizations - Embed charts and graphs in reports

• include_code_snippets - Include code snippets in reports

• export_multiple_formats - Export reports in multiple formats

• batch_generate_reports - Generate multiple reports in batch

Report Management

• save_report - Save reports to specified location

• load_report_template - Load custom report templates

• validate_report_content - Validate report content and structure

• optimize_report_size - Optimize report file size

• archive_reports - Archive old reports

Integration Operations

• integrate_analysis_results - Integrate analysis results into reports

• embed_insights - Embed insights and findings in reports

• include_metadata - Include analysis metadata in reports

• link_visualizations - Link visualizations to report content

Troubleshooting

Issue: Output directory not accessible

Error: Permission denied or directory not found

Solutions:

# Set accessible directory
export AI_REPORT_ORCHESTRATOR_OUTPUT_DIRECTORY=/accessible/path

# Create directory with proper permissions
mkdir -p /path/to/reports
chmod 755 /path/to/reports

Issue: Report generation fails

Error: ReportGenerationError during report creation

Solutions:

1. Check output directory permissions

2. Verify report type and format compatibility

3. Check available disk space

4. Validate input data and analysis results

Issue: Visualizations not included

Error: Visualizations missing from reports

Solutions:

# Enable visualizations
export AI_REPORT_ORCHESTRATOR_INCLUDE_VISUALIZATIONS=true

# Check visualization generation
# Verify chart and graph creation

Issue: Reports too long or too short

Error: Report length not appropriate

Solutions:

# Adjust insights limit
export AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=15

# Or increase for more detail
export AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=30

Issue: Format conversion fails

Error: Report format conversion errors

Solutions:

1. Check format compatibility

2. Verify required dependencies

3. Check file permissions

4. Validate report content

Issue: Code inclusion problems

Error: Code snippets not properly formatted

Solutions:

# Disable code inclusion for business reports
export AI_REPORT_ORCHESTRATOR_INCLUDE_CODE=false

# Or enable for technical reports
export AI_REPORT_ORCHESTRATOR_INCLUDE_CODE=true

Issue: Performance issues

Error: Slow report generation

Solutions:

1. Reduce max insights per report

2. Disable visualizations if not needed

3. Use simpler report formats

4. Check system resources

Best Practices

Performance Optimization

1. Insight Management - Set appropriate max insights per report

2. Format Selection - Choose formats based on use case

3. Visualization Control - Enable visualizations only when needed

4. Directory Management - Use efficient output directories

5. Resource Monitoring - Monitor disk space and memory usage

Error Handling

1. Graceful Degradation - Handle report generation failures gracefully

2. Validation - Validate inputs before report generation

3. Fallback Strategies - Provide fallback report formats

4. Error Logging - Log errors for debugging and monitoring

5. User Feedback - Provide clear error messages

Security

1. Directory Permissions - Secure output directory access

2. Content Validation - Validate report content before saving

3. Access Control - Control access to generated reports

4. Audit Logging - Log report generation activities

5. Data Privacy - Ensure data privacy in reports

Resource Management

1. Disk Space - Monitor disk space usage

2. File Cleanup - Clean up temporary files

3. Memory Usage - Monitor memory consumption

4. Processing Time - Set reasonable timeouts

5. Storage Optimization - Optimize report file sizes

Integration

1. Tool Dependencies - Ensure required tools are available

2. API Compatibility - Maintain API compatibility

3. Error Propagation - Properly propagate errors

4. Logging Integration - Integrate with logging systems

5. Monitoring - Monitor tool performance and usage

Development vs Production

Development:

AI_REPORT_ORCHESTRATOR_DEFAULT_REPORT_TYPE=technical_report
AI_REPORT_ORCHESTRATOR_DEFAULT_FORMAT=markdown
AI_REPORT_ORCHESTRATOR_OUTPUT_DIRECTORY=./reports
AI_REPORT_ORCHESTRATOR_INCLUDE_CODE=true
AI_REPORT_ORCHESTRATOR_INCLUDE_VISUALIZATIONS=false
AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=10

Production:

AI_REPORT_ORCHESTRATOR_DEFAULT_REPORT_TYPE=business_report
AI_REPORT_ORCHESTRATOR_DEFAULT_FORMAT=pdf
AI_REPORT_ORCHESTRATOR_OUTPUT_DIRECTORY=/app/reports
AI_REPORT_ORCHESTRATOR_INCLUDE_CODE=false
AI_REPORT_ORCHESTRATOR_INCLUDE_VISUALIZATIONS=true
AI_REPORT_ORCHESTRATOR_MAX_INSIGHTS_PER_REPORT=30

Error Handling

Always wrap report generation operations in try-except blocks:

from aiecs.tools.statistics.ai_report_orchestrator_tool import AIReportOrchestratorTool, ReportOrchestratorError, ReportGenerationError

report_tool = AIReportOrchestratorTool()

try:
    report = report_tool.generate_report(
        analysis_results=results,
        report_type="business_report",
        format="pdf"
    )
except ReportGenerationError as e:
    print(f"Report generation error: {e}")
except ReportOrchestratorError as e:
    print(f"Report orchestrator error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Dependencies

Core Dependencies

# Install core dependencies
pip install pydantic python-dotenv

# Install report generation dependencies
pip install markdown jinja2 weasyprint python-docx

# Install visualization dependencies
pip install matplotlib seaborn plotly

Optional Dependencies

# For advanced report formats
pip install reportlab fpdf2

# For HTML to PDF conversion
pip install wkhtmltopdf

# For advanced visualization
pip install bokeh altair

# For template processing
pip install mako cheetah3

Verification

# Test dependency availability
try:
    import pydantic
    import markdown
    import jinja2
    print("Core dependencies available")
except ImportError as e:
    print(f"Missing dependency: {e}")

# Test report generation availability
try:
    import weasyprint
    print("PDF generation available")
except ImportError:
    print("PDF generation not available")

try:
    import docx
    print("Word generation available")
except ImportError:
    print("Word generation not available")

# Test visualization availability
try:
    import matplotlib
    import seaborn
    print("Visualization available")
except ImportError:
    print("Visualization not available")

Related Documentation

• Tool implementation details in the source code

• Report tool documentation for document generation

• Visualization tools documentation for charts and graphs

• Main aiecs documentation for architecture overview

Support

For issues or questions about AI Report Orchestrator Tool configuration:

• Check the tool source code for implementation details

• Review report tool documentation for document generation

• Consult the main aiecs documentation for architecture overview

• Test with simple reports first to isolate configuration vs. generation issues

• Verify output directory permissions and accessibility

• Check report type and format compatibility

• Ensure proper insight limits and visualization settings

• Validate report content and structure requirements