FIX: Cortex doctor - resolve dependency detection + add polished UI

[lu11y0]

Related Issue

Closes #332

Summary

• Case-insensitive package name mapping in SystemDoctor
• PyYAML → yaml, python-dotenv → dotenv...
• raw_name.replace("-", "_") fallback for hyphens

New Features:

• CX-styled "SYSTEM HEALTH CHECK" header
• Consistent cx_header() for all sections
• Full Cortex banner style integration

demo

Screen.Recording.2025-12-21.234242.mp4

Checklist

• Tests pass (pytest tests/test_cortex_doctor)
• PR title format: [#XX] Description
• MVP label added if closing MVP issue

Summary by CodeRabbit

• New Features

  • Animated spinner during health checks and CX-branded banner for consistent UI.

• Bug Fixes

  • Improved dependency detection with expanded name normalization (case, hyphen/underscore and common alias handling).
  • Fixed GPU diagnostics and API key warning formatting for clearer messages.

• Style

  • Unified section header rendering and cohesive branding across health-check output.

• Tests

  • Minor test and example formatting tweaks only; no behavioral or API changes.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Replaced the Panel header with a CX-branded banner, wrapped all doctor check groups in a single console.status spinner, and improved dependency-name normalization (trim, lowercase, hyphen→underscore, python-dotenv → dotenv). Minor formatting and message tweaks; examples/tests contain only whitespace/formatting edits.

Changes

Cohort / File(s)	Summary
Doctor CLI UI & Control Flow cortex/doctor.py	Replaced Panel-based header with cx_header CX banner blocks and moved section headers through cx_header. Wrapped all check groups inside a single console.status/Status spinner to display progress.
Dependency normalization & checks cortex/doctor.py	Normalizes dependency names by trimming and lowercasing, maps hyphens to underscores for import attempts, and maps python-dotenv → dotenv to avoid false missing-package reports.
Messages & Imports cortex/doctor.py	Added Status and cx_header imports; simplified GPU and API-key warning strings and adjusted comments/flow to fit spinner usage.
Example whitespace examples/parallel_llm_demo.py	Minor formatting: added blank line after time import and consolidated a function call onto one line; no behavior change.
Tests formatting test_parallel_llm.py, tests/test_llm_router.py	Cosmetic changes to string literals, whitespace, and line-wrapping; no behavioral changes.
Router formatting cortex/llm_router.py	Whitespace and formatting adjustments in message/payload dicts and prompts; no logic or control-flow changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Attention points:
  • cortex/doctor.py dependency normalization logic (lowercasing, hyphen→underscore, explicit mappings) and potential edge cases (dots, scoped names).
  • Spinner (console.status/Status) wrapping — ensure important output and error traces remain visible and not swallowed.
  • Any implicit assumptions about package/import name resolution that could affect false negatives.

Possibly related PRs

• feat: cortex doctor - System Health Check  #306 — Directly modifies the same cortex/doctor.py SystemDoctor implementation (header, spinner/status usage, and dependency-name normalization).

Suggested reviewers

• Suyashd999

Poem

🐰 I hop through code with careful paws,

I lowercase names and stitch the flaws,
A spinner hums while banners glow,
No missing packages now say "no,"
The doctor checks — on tipsy toes! ✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main changes: fixing dependency detection issues and adding polished UI improvements to Cortex Doctor.
Description check	✅ Passed	The description covers the related issue, provides a comprehensive summary of changes, includes implementation details, and has a mostly complete checklist with two items checked.
Linked Issues check	✅ Passed	The code changes fully address issue #332 by implementing case-insensitive package name mapping, canonical name mappings, and hyphen-to-underscore normalization for dependency detection in SystemDoctor.
Out of Scope Changes check	✅ Passed	All changes are directly related to the stated objectives: fixing dependency detection in doctor.py and adding UI improvements via CX styling. Formatting changes in other files align with the overall polish objective.
Docstring Coverage	✅ Passed	Docstring coverage is 95.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8a72abf and e4d9334.

📒 Files selected for processing (3)

• cortex/llm_router.py
• examples/parallel_llm_demo.py
• tests/test_llm_router.py

✅ Files skipped from review due to trivial changes (2)

• tests/test_llm_router.py
• cortex/llm_router.py

🚧 Files skipped from review as they are similar to previous changes (1)

• examples/parallel_llm_demo.py

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build Package

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

cortex/doctor.py (1)

61-72: Consider centralizing banner in branding module.

The ASCII art banner is hardcoded here, while other branding elements like cx_header are in cortex/branding.py. For consistency and maintainability, consider moving this banner to the branding module.

💡 Example approach

In cortex/branding.py, add:

def show_health_check_banner():
    """Display the SYSTEM HEALTH CHECK banner."""
    console.print("[bold cyan]   ██████╗██╗  ██╗    SYSTEM HEALTH CHECK[/bold cyan]")
    console.print("[bold cyan]  ██╔════╝╚██╗██╔╝   ─────────────────────[/bold cyan]")
    # ... rest of banner lines
    console.print()

Then in this file:

from cortex.branding import console, cx_header, show_health_check_banner

# ...
def run_checks(self) -> int:
    console.print()
    show_health_check_banner()
    console.print()
    # ...

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f6bfa49 and a3ba6c4.

📒 Files selected for processing (1)

• cortex/doctor.py (5 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

**/*.py: Follow PEP 8 style guide
Type hints required in Python code
Docstrings required for all public APIs

Files:

• cortex/doctor.py

🧬 Code graph analysis (1)

cortex/doctor.py (2)

cortex/cli.py (1)

• status (704-735)

cortex/branding.py (1)

• cx_header (82-88)

🔇 Additional comments (3)

cortex/doctor.py (3)

74-93: Nice UX improvement with the spinner!

The spinner-wrapped execution flow provides good visual feedback during checks. Rich's console.status() correctly handles the mixed output from check results while the spinner is active.

---

102-104: Good refactoring to use centralized branding.

Delegating to cx_header improves consistency with other parts of the codebase (e.g., cortex/cli.py).

---

174-174: Good addition for python-dotenv mapping.

This correctly maps the python-dotenv package name to its dotenv import name, preventing false "missing package" reports.

[lu11y0]

@Suyashd999 please review this and merge, I believe that CI / Lint error is from another pr files.

[Suyashd999]

works on local @kr16h just make the change suggested by coderabbit and we will merge this

[Sahilbhatane]

Make sure to lint everything as well

[lu11y0]

Make sure to lint everything as well

@Sahilbhatane the lint error is from test_parallel_llm.py which i haven't modified, its from another pr, i will lint that 👍

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

cortex/doctor.py (1)

14-14: Remove unused import.

The Status class is imported but never directly used. The console.status() call at line 74 is a method that doesn't require explicitly importing the Status class.

🔎 Proposed fix

-from rich.status import Status

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a3ba6c4 and 07cf02d.

📒 Files selected for processing (2)

• cortex/doctor.py
• examples/parallel_llm_demo.py

✅ Files skipped from review due to trivial changes (1)

• examples/parallel_llm_demo.py

🧰 Additional context used

📓 Path-based instructions (1)

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

**/*.py: Follow PEP 8 style guide
Type hints required in Python code
Docstrings required for all public APIs

Files:

• cortex/doctor.py

🧬 Code graph analysis (1)

cortex/doctor.py (2)

cortex/cli.py (1)

• status (704-735)

cortex/branding.py (1)

• cx_header (82-88)

🔇 Additional comments (6)

cortex/doctor.py (6)

60-71: Great branding enhancement!

The CX-styled ASCII banner with "SYSTEM HEALTH CHECK" provides a polished, branded header that significantly improves the user experience. This aligns well with the PR objectives for UI improvements.

---

73-92: Excellent UX improvement with status spinner.

Wrapping all checks in a console.status spinner provides clear feedback to users during the health check process. The logical grouping of checks (Python & Dependencies, GPU & Acceleration, AI & Services, System Resources) improves readability and organization.

---

101-103: Good refactoring for consistent branding.

Delegating to cx_header centralizes the header styling logic and ensures consistent CX branding across all section headers. The updated docstring accurately reflects this change.

---

173-173: Excellent fix for dependency detection!

The addition of the python-dotenv → dotenv mapping and the complete case normalization in the fallback correctly address the issue raised in past review comments and resolve issue #332.

The fallback at line 183 now properly applies .lower() before replacing hyphens with underscores, ensuring packages with non-standard casing in requirements.txt (e.g., Requests, PyYAML) are correctly recognized.

Note: This addresses the previous review comment from @coderabbitai that @Suyashd999 requested be fixed.

Also applies to: 181-184

---

241-241: Clearer messaging for CPU-only mode.

The updated warning message better communicates that CPU-only mode is supported while setting appropriate expectations about performance. This improves user understanding of system capabilities.

---

327-327: LGTM - clean message formatting.

The simplified API key warning message maintains clarity while improving readability.

[lu11y0]

@Sahilbhatane @Suyashd999 ready to merge!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud