enhance context

src/dashboard/pages/3_Simulation_Workflow.py

@@ -530,6 +530,7 @@ elif st.session_state.workflow_step == 3:
                 st.session_state.sim_results = {
                     "success": True,
                     "output": result["summary"],
+                    "insights": result.get("insights"),
                     "log_dir": str(run_dir),
                     "completed_at": datetime.now().isoformat(),
                 }
@@ -583,6 +584,13 @@ elif st.session_state.workflow_step == 4:
         with st.expander("View simulation output"):
             st.code(results["output"], language="text")
 
+        # Key Insights from engine (if available)
+        insights_text = results.get("insights")
+        if insights_text:
+            st.markdown("### Key Insights")
+            with st.expander("Show engine insights", expanded=True):
+                st.code(insights_text, language="text")
+
         # Check for generated files
         log_dir = Path(results["log_dir"])
 

src/dashboard/pages/6_Analytics_And_Reports.py

@@ -43,14 +43,18 @@ tab1, tab2, tab3, tab4 = st.tabs(
 # TAB 1: Simulation Comparison
 with tab1:
     st.markdown("### Simulation Comparison")
-    st.markdown("Compare multiple simulation runs to evaluate different policies and parameters.")
+    st.markdown(
+        "Compare multiple simulation runs to evaluate different policies and parameters."
+    )
 
     # Check for available simulation runs
     outputs_dir = Path("outputs")
     runs_dir = outputs_dir / "simulation_runs"
 
     if not runs_dir.exists():
-        st.warning("No simulation outputs found. Run simulations first to generate data.")
+        st.warning(
+            "No simulation outputs found. Run simulations first to generate data."
+        )
     else:
         # Collect all run directories that actually contain a metrics.csv file.
         # Some runs may be nested (version folder inside timestamp). We treat every
@@ -100,6 +104,33 @@ with tab1:
 
                         st.success("Loaded metrics successfully")
 
+                        # Show Key Insights from report.txt for both runs
+                        st.markdown("#### Key Insights (from report.txt)")
+                        col_ins_1, col_ins_2 = st.columns(2)
+
+                        report1_path = run_map[run1_label] / "report.txt"
+                        report2_path = run_map[run2_label] / "report.txt"
+
+                        with col_ins_1:
+                            st.markdown(f"**{run1_label}**")
+                            if report1_path.exists():
+                                st.code(
+                                    report1_path.read_text(encoding="utf-8"),
+                                    language="text",
+                                )
+                            else:
+                                st.info("No report.txt found for this run.")
+
+                        with col_ins_2:
+                            st.markdown(f"**{run2_label}**")
+                            if report2_path.exists():
+                                st.code(
+                                    report2_path.read_text(encoding="utf-8"),
+                                    language="text",
+                                )
+                            else:
+                                st.info("No report.txt found for this run.")
+
                         # Summary comparison
                         st.markdown("#### Summary Comparison")
 
@@ -125,10 +156,16 @@ with tab1:
 
                         with col3:
                             st.markdown("**Difference**")
-                            if "disposal_rate" in df1.columns and "disposal_rate" in df2.columns:
+                            if (
+                                "disposal_rate" in df1.columns
+                                and "disposal_rate" in df2.columns
+                            ):
                                 diff_disposal = avg_disposal2 - avg_disposal1
                                 st.metric("Disposal Rate Δ", f"{diff_disposal:+.2%}")
-                            if "utilization" in df1.columns and "utilization" in df2.columns:
+                            if (
+                                "utilization" in df1.columns
+                                and "utilization" in df2.columns
+                            ):
                                 diff_util = avg_util2 - avg_util1
                                 st.metric("Utilization Δ", f"{diff_util:+.2%}")
 
@@ -137,7 +174,10 @@ with tab1:
                         # Time series comparison
                         st.markdown("#### Performance Over Time")
 
-                        if "disposal_rate" in df1.columns and "disposal_rate" in df2.columns:
+                        if (
+                            "disposal_rate" in df1.columns
+                            and "disposal_rate" in df2.columns
+                        ):
                             fig = go.Figure()
 
                             fig.add_trace(
@@ -169,7 +209,10 @@ with tab1:
 
                             st.plotly_chart(fig, use_container_width=True)
 
-                        if "utilization" in df1.columns and "utilization" in df2.columns:
+                        if (
+                            "utilization" in df1.columns
+                            and "utilization" in df2.columns
+                        ):
                             fig = go.Figure()
 
                             fig.add_trace(
@@ -271,7 +314,10 @@ with tab2:
                         x="run",
                         y="disposal_rate",
                         title="Disposal Rate Distribution by Run",
-                        labels={"disposal_rate": "Disposal Rate", "run": "Simulation Run"},
+                        labels={
+                            "disposal_rate": "Disposal Rate",
+                            "run": "Simulation Run",
+                        },
                     )
                     fig.update_layout(height=400)
                     st.plotly_chart(fig, use_container_width=True)
@@ -325,7 +371,9 @@ with tab3:
             events_path = label_to_path[selected_run] / "events.csv"
 
             if not events_path.exists():
-                st.warning("Events file not found. Fairness analysis requires detailed event logs.")
+                st.warning(
+                    "Events file not found. Fairness analysis requires detailed event logs."
+                )
             else:
                 try:
                     events_df = pd.read_csv(events_path)
@@ -337,9 +385,12 @@ with tab3:
                         st.markdown("#### Case Age Distribution")
 
                         # Calculate case ages (simplified - would need filed_date for accurate calculation)
-                        case_dates = events_df.groupby("case_id")["date"].agg(["min", "max"])
+                        case_dates = events_df.groupby("case_id")["date"].agg(
+                            ["min", "max"]
+                        )
                         case_dates["age_days"] = (
-                            pd.to_datetime(case_dates["max"]) - pd.to_datetime(case_dates["min"])
+                            pd.to_datetime(case_dates["max"])
+                            - pd.to_datetime(case_dates["min"])
                         ).dt.days
 
                         fig = px.histogram(
@@ -347,7 +398,10 @@ with tab3:
                             x="age_days",
                             nbins=30,
                             title="Distribution of Case Ages",
-                            labels={"age_days": "Age (days)", "count": "Number of Cases"},
+                            labels={
+                                "age_days": "Age (days)",
+                                "count": "Number of Cases",
+                            },
                         )
                         fig.update_layout(height=400)
                         st.plotly_chart(fig, use_container_width=True)
@@ -356,11 +410,18 @@ with tab3:
                         col1, col2, col3 = st.columns(3)
 
                         with col1:
-                            st.metric("Median Age", f"{case_dates['age_days'].median():.0f} days")
+                            st.metric(
+                                "Median Age",
+                                f"{case_dates['age_days'].median():.0f} days",
+                            )
                         with col2:
-                            st.metric("Mean Age", f"{case_dates['age_days'].mean():.0f} days")
+                            st.metric(
+                                "Mean Age", f"{case_dates['age_days'].mean():.0f} days"
+                            )
                         with col3:
-                            st.metric("Max Age", f"{case_dates['age_days'].max():.0f} days")
+                            st.metric(
+                                "Max Age", f"{case_dates['age_days'].max():.0f} days"
+                            )
 
                         # Additional Fairness Metrics: Gini and Lorenz Curve
                         st.markdown("#### Inequality Metrics (Fairness)")
@@ -403,7 +464,12 @@ with tab3:
                                     lorenz = cum_ages / cum_ages[-1]
                                     fig_lorenz = go.Figure()
                                     fig_lorenz.add_trace(
-                                        go.Scatter(x=cum_pop, y=lorenz, mode="lines", name="Lorenz")
+                                        go.Scatter(
+                                            x=cum_pop,
+                                            y=lorenz,
+                                            mode="lines",
+                                            name="Lorenz",
+                                        )
                                     )
                                     fig_lorenz.add_trace(
                                         go.Scatter(
@@ -420,18 +486,24 @@ with tab3:
                                         yaxis_title="Cumulative share of total age",
                                         height=350,
                                     )
-                                    st.plotly_chart(fig_lorenz, use_container_width=True)
+                                    st.plotly_chart(
+                                        fig_lorenz, use_container_width=True
+                                    )
                                 else:
                                     st.info("Not enough data to plot Lorenz curve")
                             except Exception:
-                                st.info("Unable to compute Lorenz curve for current data")
+                                st.info(
+                                    "Unable to compute Lorenz curve for current data"
+                                )
 
                     # Case type fairness
                     if "case_type" in events_df.columns:
                         st.markdown("---")
                         st.markdown("#### Case Type Balance")
 
-                        case_type_counts = events_df["case_type"].value_counts().reset_index()
+                        case_type_counts = (
+                            events_df["case_type"].value_counts().reset_index()
+                        )
                         case_type_counts.columns = ["case_type", "count"]
 
                         fig = px.bar(
@@ -439,7 +511,10 @@ with tab3:
                             x="case_type",
                             y="count",
                             title="Top 10 Case Types by Hearing Count",
-                            labels={"case_type": "Case Type", "count": "Number of Hearings"},
+                            labels={
+                                "case_type": "Case Type",
+                                "count": "Number of Hearings",
+                            },
                         )
                         fig.update_layout(height=400, xaxis_tickangle=-45)
                         st.plotly_chart(fig, use_container_width=True)
@@ -456,10 +531,15 @@ with tab3:
                             age_with_type = (
                                 case_dates[["age_days"]]
                                 .join(cid_to_type, how="left")
-                                .dropna(subset=["case_type"])  # keep only cases with type
+                                .dropna(
+                                    subset=["case_type"]
+                                )  # keep only cases with type
                             )
                             top_types = (
-                                age_with_type["case_type"].value_counts().head(8).index.tolist()
+                                age_with_type["case_type"]
+                                .value_counts()
+                                .head(8)
+                                .index.tolist()
                             )
                             filt = age_with_type["case_type"].isin(top_types)
                             fig_box = px.box(
@@ -468,7 +548,10 @@ with tab3:
                                 y="age_days",
                                 points="outliers",
                                 title="Case Age by Case Type (Top 8)",
-                                labels={"case_type": "Case Type", "age_days": "Age (days)"},
+                                labels={
+                                    "case_type": "Case Type",
+                                    "age_days": "Age (days)",
+                                },
                             )
                             fig_box.update_layout(height=420, xaxis_tickangle=-45)
                             st.plotly_chart(fig_box, use_container_width=True)
@@ -498,7 +581,9 @@ with tab3:
                             else:
                                 st.info("Insufficient data to compute per-type Gini")
                         except Exception as _:
-                            st.info("Unable to compute per-type age distributions for current data")
+                            st.info(
+                                "Unable to compute per-type age distributions for current data"
+                            )
 
                 except Exception as e:
                     st.error(f"Error loading events data: {e}")
@@ -506,7 +591,9 @@ with tab3:
 # TAB 4: Report Generation
 with tab4:
     st.markdown("### Report Generation")
-    st.markdown("Generate comprehensive reports summarizing system performance and analysis.")
+    st.markdown(
+        "Generate comprehensive reports summarizing system performance and analysis."
+    )
 
     outputs_dir = Path("outputs")
     runs_dir = outputs_dir / "simulation_runs"
@@ -549,11 +636,15 @@ with tab4:
                         report_sections = []
 
                         # Header
-                        report_sections.append("# Court Scheduling System - Performance Report")
+                        report_sections.append(
+                            "# Court Scheduling System - Performance Report"
+                        )
                         report_sections.append(
                             f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}"
                         )
-                        report_sections.append(f"Runs included: {', '.join(selected_runs)}")
+                        report_sections.append(
+                            f"Runs included: {', '.join(selected_runs)}"
+                        )
                         report_sections.append("")
 
                         # Performance metrics
@@ -579,7 +670,9 @@ with tab4:
                                             f"- Average Utilization: {avg_util:.2%}"
                                         )
 
-                                    report_sections.append(f"- Simulation Days: {len(df)}")
+                                    report_sections.append(
+                                        f"- Simulation Days: {len(df)}"
+                                    )
                                     report_sections.append("")
 
                         # Comparison

src/dashboard/utils/simulation_runner.py

@@ -94,8 +94,13 @@ Efficiency:
   Utilization: {res.utilization:.2%}
   Avg hearings/day: {res.hearings_total / max(1, cfg.days):.2f}
 """
-
-    (run_dir / "report.txt").write_text(summary_text, encoding="utf-8")
+    # Merge engine insights into report.txt
+    insights_text = (getattr(res, "insights_text", "") or "").strip()
+    if insights_text:
+        full_report = summary_text.rstrip() + "\n\n" + insights_text + "\n"
+    else:
+        full_report = summary_text
+    (run_dir / "report.txt").write_text(full_report, encoding="utf-8")
 
     # -------------------------------------------------------
     # Locate generated CSVs (if they exist)
@@ -105,6 +110,7 @@ Efficiency:
 
     return {
         "summary": summary_text,
+        "insights": insights_text,
         "end_date": res.end_date,
         "metrics_path": metrics_path if metrics_path.exists() else None,
         "events_path": events_path if events_path.exists() else None,

src/simulation/engine.py

@@ -67,6 +67,7 @@ class CourtSimResult:
     end_date: date
     ripeness_transitions: int = 0  # Number of ripeness status changes
     unripe_filtered: int = 0  # Cases filtered out due to unripeness
+    insights_text: str = ""  # Collected insights as plain text
 
 
 class CourtSim:
@@ -587,25 +588,31 @@ class CourtSim:
             else 0.0
         )
 
-        # Generate ripeness summary
+        # Collect insights text (previously printed inline)
+        insights_lines: List[str] = []
+
+        # Ripeness summary
         active_cases = [c for c in self.cases if c.status != CaseStatus.DISPOSED]
-        ripeness_dist = {}
+        ripeness_dist: Dict[str, int] = {}
         for c in active_cases:
-            status = c.ripeness_status  # Already a string
+            status = c.ripeness_status
             ripeness_dist[status] = ripeness_dist.get(status, 0) + 1
 
-        print("\n=== Ripeness Summary ===")
-        print(f"Total ripeness transitions: {self._ripeness_transitions}")
-        print(f"Cases filtered (unripe): {self._unripe_filtered}")
-        print("\nFinal ripeness distribution:")
+        insights_lines.append("=== Ripeness Summary ===")
+        insights_lines.append(
+            f"Total ripeness transitions: {self._ripeness_transitions}"
+        )
+        insights_lines.append(f"Cases filtered (unripe): {self._unripe_filtered}")
+        insights_lines.append("\nFinal ripeness distribution:")
         for status, count in sorted(ripeness_dist.items()):
             pct = (count / len(active_cases) * 100) if active_cases else 0
-            print(f"  {status}: {count} ({pct:.1f}%)")
+            insights_lines.append(f"  {status}: {count} ({pct:.1f}%)")
 
-        # Generate courtroom allocation summary
-        print(f"\n{self.allocator.get_courtroom_summary()}")
+        # Courtroom allocation summary
+        insights_lines.append("")
+        insights_lines.append(self.allocator.get_courtroom_summary())
 
-        # Generate comprehensive case status breakdown
+        # Comprehensive case status breakdown
         total_cases = len(self.cases)
         disposed_cases = [c for c in self.cases if c.status == CaseStatus.DISPOSED]
         scheduled_at_least_once = [
@@ -616,27 +623,29 @@ class CourtSim:
             c for c in scheduled_at_least_once if c.status != CaseStatus.DISPOSED
         ]
 
-        print("\n=== Case Status Breakdown ===")
-        print(f"Total cases in system: {total_cases:,}")
-        print("\nScheduling outcomes:")
-        print(
-            f"  Scheduled at least once: {len(scheduled_at_least_once):,} ({len(scheduled_at_least_once) / total_cases * 100:.1f}%)"
+        insights_lines.append("\n=== Case Status Breakdown ===")
+        insights_lines.append(f"Total cases in system: {total_cases:,}")
+        insights_lines.append("\nScheduling outcomes:")
+        insights_lines.append(
+            f"  Scheduled at least once: {len(scheduled_at_least_once):,} ({len(scheduled_at_least_once) / max(1, total_cases) * 100:.1f}%)"
         )
-        print(
-            f"    - Disposed: {len(disposed_cases):,} ({len(disposed_cases) / total_cases * 100:.1f}%)"
+        insights_lines.append(
+            f"    - Disposed: {len(disposed_cases):,} ({len(disposed_cases) / max(1, total_cases) * 100:.1f}%)"
         )
-        print(
-            f"    - Active (not disposed): {len(scheduled_but_not_disposed):,} ({len(scheduled_but_not_disposed) / total_cases * 100:.1f}%)"
+        insights_lines.append(
+            f"    - Active (not disposed): {len(scheduled_but_not_disposed):,} ({len(scheduled_but_not_disposed) / max(1, total_cases) * 100:.1f}%)"
         )
-        print(
-            f"  Never scheduled: {len(never_scheduled):,} ({len(never_scheduled) / total_cases * 100:.1f}%)"
+        insights_lines.append(
+            f"  Never scheduled: {len(never_scheduled):,} ({len(never_scheduled) / max(1, total_cases) * 100:.1f}%)"
         )
 
         if scheduled_at_least_once:
             avg_hearings = sum(c.hearing_count for c in scheduled_at_least_once) / len(
                 scheduled_at_least_once
             )
-            print(f"\nAverage hearings per scheduled case: {avg_hearings:.1f}")
+            insights_lines.append(
+                f"\nAverage hearings per scheduled case: {avg_hearings:.1f}"
+            )
 
         if disposed_cases:
             avg_hearings_to_disposal = sum(
@@ -645,9 +654,18 @@ class CourtSim:
             avg_days_to_disposal = sum(
                 (c.disposal_date - c.filed_date).days for c in disposed_cases
             ) / len(disposed_cases)
-            print("\nDisposal metrics:")
-            print(f"  Average hearings to disposal: {avg_hearings_to_disposal:.1f}")
-            print(f"  Average days to disposal: {avg_days_to_disposal:.0f}")
+            insights_lines.append("\nDisposal metrics:")
+            insights_lines.append(
+                f"  Average hearings to disposal: {avg_hearings_to_disposal:.1f}"
+            )
+            insights_lines.append(
+                f"  Average days to disposal: {avg_days_to_disposal:.0f}"
+            )
+
+        insights_text = "\n".join(insights_lines)
+
+        # Still echo to console for CLI users
+        print("\n" + insights_text)
 
         return CourtSimResult(
             hearings_total=self._hearings_total,
@@ -658,4 +676,5 @@ class CourtSim:
             end_date=working_days[-1] if working_days else self.cfg.start,
             ripeness_transitions=self._ripeness_transitions,
             unripe_filtered=self._unripe_filtered,
+            insights_text=insights_text,
         )