Insights

Generating new insights

Currently, Insight generation is manual and command-driven. This approach ensures maximum control while the feature is relatively new. It also allows us to generate new insights only after we possess all of the previous month’s data, rather than automating the process on partial data.

To generate insights for a new month, follow these steps:

1. Access Forge Navigate to the Commands section on the Forge site; this is the easiest method to execute these commands.

2. Process Claims Process any pending insurance claims by running the following command. This processes up to 10 claims at a time.

   php artisan insights:process-claims <tenant_id> --limit=10

3. Verify Processing Check Nightwatch and PMA to verify that no jobs failed and that the row counts in insurance_claims and processed_insurance_claims match. This indicates a successful run.

   If all jobs completed but unprocessed claims remain, simply re-run the command from Step 2 to finish the rest.

4. Generate Insights Once claims are processed, generate the new insights using this command:

   php artisan insights:orchestrate <tenant_id> --date="<date>"

   Note: The date must be in the format YYYY-MM-DD and represents any day within the target month. For example, to generate insights for November 2025, use --date="2025-11-02".

5. Confirm Completion Check Nightwatch to confirm all jobs ran successfully. By default, the system generates up to 10 insights, with each taking approximately 45 seconds.

   You should now see the newly generated insights appear on the Insights page of SHIELD Web.

Regenerating a specific insight

If you need to regenerate a specific insight, you may do so by running the following command:

php artisan insights:regenerate <tenant_id> <insight_id>

This will regenerate the insight associated with the provided ID. You can locate the specific ID within the a_i_insights table in PMA.