Reports

Core Components

The reporting system is built around four key concepts:

• Report Configuration (`ReportConfiguration`)

  This is the template or blueprint for a specific type of report. It's typically defined using Markdown mixed with simple configuration blocks. It specifies the static content (text, headers), the dynamic analysis blocks to include, and any parameters needed for those blocks. Configurations are stored and managed within Plexus, allowing reuse.

  Think of it like a recipe for generating a specific kind of analysis.

  # Score Performance Report
  
  This report analyzes the performance of the 'Agent Professionalism' score.
  
  ```block name="Professionalism Score Analysis"
  class: ScorePerformanceBlock
  scorecard: "Customer Service v2"
  score: "Agent Professionalism"
  time_range: last_30_days
  ```
  

• Report (`Report`)

  This represents a specific instance of a report generated from a `ReportConfiguration` at a particular time, potentially with specific runtime parameters. It stores the final rendered output (e.g., the Markdown content after processing) and links to the results of the individual analysis blocks.

  If the Configuration is the recipe, the Report is the finished cake, baked on a specific day.

• Report Block (`ReportBlock`)

  These are the reusable Python components that perform the actual data fetching and analysis for specific sections within a report. Examples might include `ScorePerformanceBlock`, `FeedbackTopicAnalysisBlock`, or `SentimentTrendBlock`. When a report is generated, the system executes the Python code for each block defined in the configuration.

  Each block generates structured data (usually JSON) containing its findings (e.g., metrics, lists of feedback, chart data) and optionally logs. This structured output is stored alongside the final report.

• Task Integration (`Task`)

  Generating a report, especially one involving multiple complex analysis blocks, can take time. Plexus leverages the existing `Task` system to manage report generation as a background job. When you request a new report, a `Task` is created to handle the process. You can monitor the report's progress (Initializing, Running Blocks, Finalizing, Completed/Failed) through the standard Task interface, ensuring consistency with other background operations like Evaluations. The `Report` record itself is directly linked to its corresponding `Task` record.

How It Works

The typical workflow for using reports involves these steps:

1. Define a `ReportConfiguration`

   Create a template (using Markdown and block definitions) for the type of report you need. This is often done once and then reused. You might use the CLI or eventually a UI editor.

   Create a template (using Markdown and block definitions) for the type of report you need. This is often done once and then reused. This can be done using the Plexus CLI, the Dashboard UI, or programmatically via the API/SDK (used by AI agents).

   # Example: Creating a config from a file
   python -m plexus.cli.CommandLineInterface report config create --name "Agent Prof Report" --file agent_prof_report.md

2. Run the Report

   Trigger the generation of a new `Report` based on a chosen `ReportConfiguration`. This creates a `Task` to handle the background processing.

   # Example: Running the report
   python -m plexus.cli.CommandLineInterface report run --config "Agent Prof Report"

3. Monitor the Task

   Track the progress of the report generation via the associated `Task`.

4. View the `Report`

   Once the task is complete, view the generated `Report`. This includes the rendered output (e.g., Markdown display) and access to the structured data generated by each `ReportBlock` for deeper dives or visualization.

   # Example: Viewing the latest generated report
   python -m plexus.cli.CommandLineInterface report last

Benefits

• Flexibility: Define custom analyses without needing new API endpoints or dedicated UI pages for each report type.
• Reusability: Report Configurations and Report Blocks can be reused across different reports.
• Consistency: Leverages the standard `Task` system for progress tracking and status updates.
• Extensibility: New analysis types can be added by creating new Python `ReportBlock` classes.
• Structured Data: Provides both human-readable output (Markdown) and machine-readable structured data (JSON) from analysis blocks.

Next Steps

Explore how Reports integrate with other core concepts like Scores and Evaluations. Check the CLI documentation for detailed commands on managing and running reports.