fix(insights): preflight service before analysis

[ryana]

Summary

• probe the remote Insights API before the analyst can read Intake traces or invoke the model
• fail fast with actionable startup guidance when the Insights service is unavailable
• preserve local-file insight output behavior

Validation

• 137 non-testbed Insights tests passed
• Ruff lint and format checks passed
• ty checks passed
• applicable pre-commit hooks passed

Linear: https://linear.app/nvidia/issue/ASE-770/preflight-insights-service-before-generating-insights

Summary by CodeRabbit

• Bug Fixes
  • Added an Insights service availability check before running remote analyses.
  • Prevented analysis from starting when the Insights service cannot be reached.
  • Added clear command-line error messages with guidance for resolving service startup issues.
  • Local-output analyses continue without requiring a remote Insights service.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 988d932a-d22a-45e4-b216-6c1c9ae3d258

📥 Commits

Reviewing files that changed from the base of the PR and between 47a57c3 and c71cdfe.

📒 Files selected for processing (4)

• plugins/nemo-insights/src/nemo_insights_plugin/analyst/run.py
• plugins/nemo-insights/src/nemo_insights_plugin/cli.py
• plugins/nemo-insights/tests/test_analyst_run.py
• plugins/nemo-insights/tests/test_cli_profile.py

---

📝 Walkthrough

Walkthrough

Changes

Insights preflight handling

Layer / File(s)	Summary
Analyst service preflight plugins/nemo-insights/src/nemo_insights_plugin/analyst/run.py, plugins/nemo-insights/tests/test_analyst_run.py	run_analyst checks the remote Insights service before agent execution. Failures become InsightsServiceUnavailableError. Local output bypasses the remote check. Tests cover request ordering, cleanup, failures, and local output.
CLI service error handling plugins/nemo-insights/src/nemo_insights_plugin/cli.py, plugins/nemo-insights/tests/test_cli_profile.py	The CLI reports unavailable Insights services as a one-line error and exits with status 1. Tests verify the output excludes Intake guidance and tracebacks.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant run_analyst
  participant _preflight_insights_service
  participant InsightsBackend
  participant Agent
  CLI->>run_analyst: Start analysis
  run_analyst->>_preflight_insights_service: Check remote Insights service
  _preflight_insights_service->>InsightsBackend: List insights
  InsightsBackend-->>_preflight_insights_service: Response or HTTP/platform error
  _preflight_insights_service-->>run_analyst: Continue or raise InsightsServiceUnavailableError
  run_analyst->>Agent: Generate report
  Agent-->>CLI: Return report or service error

Loading

Possibly related PRs

• NVIDIA-NeMo/nemo-platform#679: Extends the run_analyst workflow with remote Insights service checks.
• NVIDIA-NeMo/nemo-platform#718: Shares the analyst runner and CLI error-handling paths.
• NVIDIA-NeMo/nemo-platform#749: Shares injected client lifecycle and remote Insights interaction tests.

Suggested reviewers: svvarom, callingmedic911, nicot

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding an Insights service preflight before analysis.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch preflight-insights-service/rangilly

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Suite	Lines Covered	Line Rate	Branch Rate
Unit Tests	29340/37347	78.6%	63.2%
Integration Tests	17287/36065	47.9%	20.5%