Report Generation Tools

Overview

The Report Generation Tools provide AI-powered automated report creation with support for multiple output formats and customizable templates. These tools integrate with the OpsHub data infrastructure to aggregate portfolio metrics, performance data, and compliance information into professional reports suitable for management, boards, and regulatory audiences. Reports are generated through a three-stage pipeline: template selection, data aggregation, and AI-enhanced narrative generation. The system supports multiple report types including NAV summaries, breach reports, board presentations, and compliance documents.

Quick Reference

Common Report Types

Report Type	Purpose	Primary Audience	Typical Format
`nav_summary`	Portfolio valuation overview	Management/Board	PDF
`breach_report`	Validation failure analysis	Compliance/Risk	Excel/PDF
`board_deck`	Quarterly performance presentation	Board/Investors	PowerPoint
`performance_report`	Fund/portfolio metrics	Management	PDF/Excel
`compliance_report`	Regulatory compliance status	Compliance Officers	PDF

Supported Output Formats

PDF: Professional documents with formatting, tables, and charts
Excel: Spreadsheet format with multiple sheets and data tables
PowerPoint: Presentation format with slides and visual layouts

Common Cron Expressions

9 * * 1       # Every Monday at 9am
9 * * 1-5     # Every weekday at 9am
9 * * 5       # Every Friday at 5pm
9 1 * *       # First day of month at 9am
17 * * *      # Every day at 5pm

Tools

generate_report

Generate a comprehensive professional report with AI-powered narrative sections. Function Signature:

generate_report(
    report_type: str,
    period_start: str,
    period_end: str,
    format: str = "pdf",
    portfolio_ids: Optional[List[str]] = None,
    template_id: Optional[str] = None,
    include_narrative: bool = True
) -> Dict[str, Any]

Parameters:

Parameter	Type	Required	Default	Description
`report_type`	string	Yes	-	Report template type: `nav_summary`, `breach_report`, `board_deck`, `performance_report`, `compliance_report`
`period_start`	string	Yes	-	Report period start date in YYYY-MM-DD format
`period_end`	string	Yes	-	Report period end date in YYYY-MM-DD format
`format`	string	No	pdf	Output format: `pdf`, `excel`, or `powerpoint`
`portfolio_ids`	List[string]	No	None	Filter data to specific portfolio IDs; if not provided, includes all portfolios
`template_id`	string	No	None	Custom template ID; uses default template for report_type if not specified
`include_narrative`	boolean	No	true	Include AI-generated narrative analysis and executive summaries

Returns:

{
  "success": true,
  "report_id": "rpt-abc123",
  "report_name": "NAV Summary - 2024-09-01 to 2024-09-30",
  "file_url": "/reports/rpt-abc123.pdf",
  "sections": 8,
  "narrative_sections": 2,
  "format": "pdf",
  "period": "2024-09-01 to 2024-09-30",
  "generated_at": "2024-10-15T14:32:00Z",
  "message": "Report generated successfully: NAV Summary - 2024-09-01 to 2024-09-30"
}

Error Response:

{
  "success": false,
  "error": "Template not found",
  "message": "Template ID tmpl-invalid does not exist"
}

Key Fields:

report_id: Unique identifier for tracking and retrieval
sections: Total number of report sections (tables, charts, text)
narrative_sections: Count of AI-generated narrative sections (executive summaries, analysis)
file_url: Download URL or generation location (may be “generated_in_memory”)

Data Aggregation: The tool automatically aggregates data from multiple sources based on template configuration:

NAV by Portfolio: Historical net asset values across portfolios
NAV Variance Trends: 30-day performance trends for selected portfolio
NAV Metrics: Aggregate metrics including total NAV, pass rates, validation counts
Breaches: Validation failures and compliance events
Remediation Actions: Corrective actions and compliance efforts

AI Narrative Generation: When include_narrative=true, the system generates two narrative sections:

Executive Summary: High-level overview with key metrics, trends, and performance highlights
Root Cause Analysis: Analysis of validation breaches and remediation approaches

Narrative sections use AI to synthesize data into readable prose with context and insights. Examples:

# Basic NAV summary report
generate_report(
    report_type="nav_summary",
    period_start="2024-09-01",
    period_end="2024-09-30",
    format="pdf"
)

# Breach report with narrative for specific portfolios
generate_report(
    report_type="breach_report",
    period_start="2024-09-26",
    period_end="2024-09-26",
    format="excel",
    portfolio_ids=["port-123", "port-456"],
    include_narrative=True
)

# Board deck presentation
generate_report(
    report_type="board_deck",
    period_start="2024-07-01",
    period_end="2024-09-30",
    format="powerpoint",
    portfolio_ids=["port-789"],
    include_narrative=True
)

# Custom template with specific format
generate_report(
    report_type="compliance_report",
    period_start="2024-09-01",
    period_end="2024-09-30",
    format="pdf",
    template_id="tmpl-compliance-custom-v2"
)

Template System: Reports use a flexible template system with sections and data sources:

Template: Collection of ordered sections with configuration
Section: Individual content block (table, chart, narrative) with data source
Data Source: Query or aggregation method (nav_by_portfolio, breaches, etc.)
Rendering: Template engine interpolates data into final document

Templates are stored in agent.report_templates table with versioning support. Note: If a custom template is not found, the tool returns an error. If no template_id is provided, it automatically uses the default template for the report_type. If no default exists, it creates one from system defaults.

list_report_templates

List available report templates with optional filtering. Function Signature:

list_report_templates(
    report_type: Optional[str] = None
) -> Dict[str, Any]

Parameters:

Parameter	Type	Required	Description
`report_type`	string	No	Filter templates by report type (nav_summary, breach_report, etc.)

Returns:

{
  "success": true,
  "templates": [
    {
      "id": "tmpl-nav-001",
      "name": "NAV Summary - Standard",
      "description": "Monthly NAV summary for management",
      "report_type": "nav_summary",
      "sections": 8,
      "created_at": "2024-09-15T10:00:00Z"
    },
    {
      "id": "tmpl-breach-001",
      "name": "Breach Report - Detailed",
      "description": "Comprehensive breach analysis with root causes",
      "report_type": "breach_report",
      "sections": 6,
      "created_at": "2024-09-20T14:30:00Z"
    }
  ],
  "count": 2,
  "message": "Found 2 report templates"
}

Use Cases:

Discover available templates before calling generate_report
Get template IDs for use in generate_report with template_id parameter
Understand template structure and section count
Verify custom templates are available

Examples:

# List all templates
list_report_templates()

# List NAV summary templates only
list_report_templates(report_type="nav_summary")

# Get breach report templates
list_report_templates(report_type="breach_report")

schedule_report

Schedule recurring report generation and automated distribution. Function Signature:

schedule_report(
    template_id: str,
    schedule_cron: str,
    distribution_list: List[str],
    format: str = "pdf"
) -> Dict[str, Any]

Parameters:

Parameter	Type	Required	Default	Description
`template_id`	string	Yes	-	Template ID to use (get from `list_report_templates`)
`schedule_cron`	string	Yes	-	Cron expression defining schedule frequency and time
`distribution_list`	List[string]	Yes	-	Email addresses for report delivery (minimum 1 recipient)
`format`	string	No	pdf	Output format: `pdf`, `excel`, or `powerpoint`

Returns:

{
  "success": true,
  "schedule_id": "sched-xyz789",
  "template_id": "tmpl-nav-001",
  "frequency": "every Monday",
  "distribution_list": ["cfo@company.com", "controller@company.com"],
  "format": "pdf",
  "is_active": true,
  "message": "Report scheduled successfully. Will run every Monday"
}

Error Response:

{
  "success": false,
  "error": "Template not found",
  "message": "Template ID tmpl-invalid does not exist"
}

Scheduling: Cron expressions use standard format: minute hour day month weekday Common Patterns:

Pattern	Cron	Frequency
Daily at 9am	`0 9 * * *`	Every day
Weekdays at 9am	`0 9 * * 1-5`	Monday-Friday
Monday at 9am	`0 9 * * 1`	Every Monday
Friday at 5pm	`0 17 * * 5`	Every Friday
Month start at 9am	`0 9 1 * *`	1st of each month
Twice daily	`0 9,17 * * *`	9am and 5pm

Distribution:

Reports are emailed to all addresses in distribution_list
Format (PDF, Excel, PowerPoint) is attached and specified in email
Reports use the template configuration for period and data scope
Delivery timing depends on system scheduler and mail queue

Examples:

# Weekly NAV reports every Monday morning
schedule_report(
    template_id="tmpl-nav-001",
    schedule_cron="0 9 * * 1",
    distribution_list=["cfo@company.com"],
    format="pdf"
)

# Daily breach summaries for compliance team
schedule_report(
    template_id="tmpl-breach-001",
    schedule_cron="0 9 * * *",
    distribution_list=["compliance@company.com", "risk@company.com"],
    format="excel"
)

# Monthly board deck on the 1st at 8am
schedule_report(
    template_id="tmpl-board-001",
    schedule_cron="0 8 1 * *",
    distribution_list=["board@company.com", "ceo@company.com"],
    format="powerpoint"
)

# Weekday reports at end of day
schedule_report(
    template_id="tmpl-performance-001",
    schedule_cron="0 17 * * 1-5",
    distribution_list=["manager@company.com"],
    format="pdf"
)

Management: After scheduling, reports are stored in agent.report_schedules table:

schedule_id: Unique identifier
template_id: Reference to report template
schedule_cron: Cron expression
is_active: Boolean flag (can be toggled to pause/resume)
distribution_list: Email recipients

Advanced Features

Custom Templates

Create custom templates for organization-specific needs:

Use list_report_templates to understand template structure
Clone existing template or create new in agent.report_templates
Define sections with data sources and rendering instructions
Reference custom template with template_id in generate_report

Data Source Integration

Available data aggregation sources:

select_nav_by_portfolio: Portfolio-level NAV data
select_nav_variance_trend: Historical performance trends
calculate_nav_metrics: Aggregate metrics and statistics
select_breaches: Validation failures and events
select_remediation_actions: Compliance corrective actions

Narrative Customization

AI narratives are customized per section:

Executive Summary: Data-driven overview of period performance
Root Cause Analysis: Analysis of top 5 breaches with remediation context

Narrative sections respect template configuration for word limits and tone.

Error Handling

Common Errors:

Error	Cause	Solution
Template not found	Invalid template_id or missing default	Use `list_report_templates` to find valid IDs
Invalid format	Format not in pdf/excel/powerpoint	Check format parameter spelling
Invalid date format	Dates not in YYYY-MM-DD	Use standard date format
No data available	Period has no data or invalid portfolio_ids	Adjust date range or verify portfolio IDs

Error Response Structure:

{
  "success": false,
  "error": "Error type",
  "message": "Detailed error message"
}

Integration with OpsHub

Report generation integrates with:

Supabase Database: Stores templates, schedules, and generated reports
Data Aggregation Service: Queries NAV, breach, and performance data
Narrative Engine: AI-powered analysis and summarization
Format Engines: PDF, Excel, and PowerPoint rendering

All operations require authenticated Supabase connection via JWT token.

Performance Considerations

Report Generation Time: Typically 5-30 seconds depending on data volume and format
File Size: PDF (1-5MB), Excel (2-10MB), PowerPoint (3-15MB)
Data Retention: Generated reports stored 90 days by default
Rate Limits: No hard limit; consider scheduling during off-peak hours

File References

Implementation: /opshub-agent-backend/app/agent/tools/report_generation.py
Template Engine: /opshub-agent-backend/app/agent/reporting/template_engine.py
Formatters: /opshub-agent-backend/app/agent/reporting/formatters.py
Data Aggregation: /opshub-agent-backend/app/agent/reporting/data_aggregator.py
Narrative Generator: /opshub-agent-backend/app/agent/reporting/narrative_generator.py

Agent System Overview

Available Agents

Integration Patterns

Agent Tools & Capabilities

Report Generation Tools

Overview

Quick Reference

Common Report Types

Supported Output Formats

Common Cron Expressions

Tools

generate_report

list_report_templates

schedule_report

Advanced Features

Custom Templates

Data Source Integration

Narrative Customization

Error Handling

Integration with OpsHub

Performance Considerations

File References

Agent System Overview

Available Agents

Integration Patterns

Agent Tools & Capabilities

​Overview

​Quick Reference

​Common Report Types

​Supported Output Formats

​Common Cron Expressions

​Tools

​generate_report

​list_report_templates

​schedule_report

​Advanced Features

​Custom Templates

​Data Source Integration

​Narrative Customization

​Error Handling

​Integration with OpsHub

​Performance Considerations

​File References

Overview

Quick Reference

Common Report Types

Supported Output Formats

Common Cron Expressions

Tools

generate_report

list_report_templates

schedule_report

Advanced Features

Custom Templates

Data Source Integration

Narrative Customization

Error Handling

Integration with OpsHub

Performance Considerations

File References