Skip to content

Fix Hardware Advisor Playbook structure and rename to index.mdx#217

Merged
itomek merged 7 commits intoamd:mainfrom
itomek:211-fix-hardware-advisor-playbook-structure
Jan 22, 2026
Merged

Fix Hardware Advisor Playbook structure and rename to index.mdx#217
itomek merged 7 commits intoamd:mainfrom
itomek:211-fix-hardware-advisor-playbook-structure

Conversation

@itomek
Copy link
Collaborator

@itomek itomek commented Jan 21, 2026 •
edited
Loading

Summary

This PR restructures the Hardware Advisor Playbook to significantly improve user experience and eliminate common issues encountered during tutorial implementation.

Problem Statement

The original tab-based structure created several user experience issues:

  1. Poor scrollability: Users had to scroll back up to switch tabs, breaking the learning flow
  2. Tab synchronization: Tabs synced across steps, causing unexpected UI shifts
  3. Python indentation errors: Code inside tabs had incorrect indentation, causing runtime errors
  4. Inconsistent progress tracking: Each step showed different checklist items, making progress unclear
  5. Missing import errors: Step 2 lacked critical typing imports, leading to NameError: name 'Dict' is not defined
  6. Inaccurate verification: Step 6 claimed to match the example file but used different implementations

Changes Made

1. Tab-to-Subsection Conversion

  • Replaced <Tabs> and <Tab> components with sequential subsections
  • New structure for Steps 1-5:
    • Implementation: Code to add/modify
    • Running It: How to run and expected output
    • Progress Check: What's built and what's coming next
  • Result: Linear, scrollable documentation without UI navigation complexity

2. Python Code Formatting Fixes

  • Step 1: Fixed class and method indentation (all methods now properly indented 4 spaces)
  • Step 5: Fixed main() function body indentation (print statements, try/except, while loop)
  • All steps: Normalized to PEP 8 standard (4-space indents)
  • Added formatting warnings after each code block to prevent copy-paste errors

3. Standardized Progress Checks

  • Unified checklist across all 6 steps with the same 8 items:
    • Basic agent structure
    • LemonadeClient connection
    • Minimal system prompt
    • GPU detection helper (_get_gpu_info())
    • Hardware detection tool (get_hardware_info())
    • Model catalog tool (list_available_models())
    • Smart recommendations tool (recommend_models())
    • Interactive CLI
  • Used status indicators (✓/✗) consistently
  • Provides clear progress visualization: Step 1 has 3✓/5✗, Step 5 has 8✓/0✗

4. Command Consistency

  • Replaced all python commands with uv run (8 instances)
  • Benefits:
    • Automatically uses correct virtual environment
    • Consistent with GAIA's package manager
    • Safer for users who haven't activated venv manually
    • Modern Python best practice

5. Accurate Step 6 Verification

  • Removed misleading claims about matching examples/hardware_advisor_agent.py
  • Updated checklist to reflect what was actually built (minimal implementation, not full example)
  • Removed incorrect file comparison instructions
  • Changed focus to functional verification rather than file matching

6. Enhanced Step Descriptions

  • Added clarity about when each step becomes runnable/interactive
  • Improved subsection headers for better scannability
  • Added context about what each tool enables

Testing

Verified the following:

  • ✓ All Python code blocks have correct indentation
  • ✓ Progress Check sections are consistent across all steps
  • ✓ All uv run commands reference correct file paths
  • ✓ Step-by-step flow is logical and incremental
  • ✓ Example outputs match code behavior
  • ✓ Formatting warnings appear after code requiring pasting

Impact

Before: Users encountered NameError, indentation issues, and confusing tab navigation

After: Linear, copy-paste-safe tutorial with clear progress tracking and accurate verification

Closes #211

@itomek @claude
Fix Hardware Advisor Playbook structure and rename to index.mdx
9a82e55 
- Restructure playbook to use single file progressive build approach
- Change from 4 separate step files to one hardware_advisor.py that grows
- Step 1: Basic skeleton (not runnable) with clear warning
- Step 2: Add hardware detection tool (runnable)
- Step 3: Add model catalog tool (runnable)
- Step 4: Add recommendations tool (complete agent)
- Fix scope issues where tools couldn't call each other
- Rename part-1-getting-started.mdx to index.mdx (single-page playbook)
- Update all internal documentation links

Fixes #211

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
@github-actions github-actions bot added the documentation Documentation changes label Jan 21, 2026
@itomek itomek self-assigned this Jan 21, 2026
itomek added 3 commits January 21, 2026 14:30
@itomek
Add tests and new Hardware Advisor Agent for LLM capabilities
1d35074 
- Introduced `test_index_fix.py` to verify system prompt updates after indexing documents.
- Created `test_index_interactive.sh` for interactive testing of the /index command.
- Added `test_system_prompt_update.py` to ensure system prompt reflects indexed documents correctly.
- Implemented `HardwareAdvisorAgent` in `zagent.py` to provide hardware capability advice for running LLMs.
- Included methods for GPU detection, system information retrieval, and model recommendations based on available hardware.
@itomek
Refine Hardware Advisor Playbook structure and enhance step descripti…
197be75 
…ons for clarity
@itomek
Update Hardware Advisor Playbook to use 'uv run' for script execution
53815e4
@itomek itomek marked this pull request as ready for review January 21, 2026 19:44
Copilot AI review requested due to automatic review settings January 21, 2026 19:44
@itomek itomek enabled auto-merge January 21, 2026 19:45
@itomek itomek added the agents Agent system changes label Jan 21, 2026
@itomek @claude
Remove temporary test files
b019daa 
- test_index_fix.py
- test_index_interactive.sh
- test_system_prompt_update.py
- zagent.py

These files were used for testing during playbook development and are no longer needed.

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
@itomek
Copy link
Collaborator Author

itomek commented Jan 21, 2026

@claude review please

@github-actions
Copy link

github-actions bot commented Jan 21, 2026 •
edited
Loading

Claude finished @itomek's task —— View job

PR Review Complete

Overall: Approve 🟢

This is an excellent restructuring of the Hardware Advisor Playbook. The changes significantly improve the tutorial experience.

Strengths

1. Tab-to-Subsection Conversion 🟢
The move from <Tabs> to sequential subsections (Implementation → Running It → Progress Check) creates a much better learning flow. Users no longer need to scroll back up to switch tabs.

2. Consistent Progress Checks 🟢
The unified 8-item checklist across all steps provides clear visual feedback:

- ✓ Basic agent structure
- ✓ LemonadeClient connection
- ✗ GPU detection helper
...

3. Code Quality 🟢
The Python code in the playbook now matches examples/hardware_advisor_agent.py:20-327 almost exactly. The code formatting follows PEP 8 standards with proper 4-space indentation.

4. Command Consistency 🟢
All python commands replaced with uv run (consistent with GAIA's package manager).

5. Documentation Structure 🟢
The docs/docs.json update correctly references the new playbooks/hardware-advisor/index path, and all cross-references in docs/guides/hardware-advisor.mdx, docs/playbooks/index.mdx, and docs/quickstart.mdx are properly updated.

Minor Observations

1. Settings File Change 🟡
.claude/settings.local.json removes Bash(git add:*) and Bash(git commit:*) from the allow list. This appears intentional but may affect local development workflows. Verify this is desired.

2. System Prompt Difference 🟡
The playbook uses a minimal system prompt:

return "You are a hardware advisor for running local LLMs on AMD systems."

While the example file (examples/hardware_advisor_agent.py:34-46) has a more detailed prompt with tool descriptions. This is fine for a tutorial progression, but consider noting this difference for users who want the full version.

3. Missing max_steps Attribute 🟡
The example file includes self.max_steps = 50 in __init__, but the playbook's Step 1 skeleton omits this. Minor, but worth noting for completeness.

Files Changed Summary

File Status Notes
docs/playbooks/hardware-advisor/index.mdx ✅ Added New consolidated playbook (1163 lines)
docs/playbooks/hardware-advisor/part-1-getting-started.mdx ✅ Deleted Replaced by index.mdx
docs/docs.json ✅ Updated Navigation path corrected
docs/guides/hardware-advisor.mdx ✅ Updated Link updated
docs/playbooks/index.mdx ✅ Updated Link updated
docs/quickstart.mdx ✅ Updated Link updated
.claude/settings.local.json ⚠️ Modified Git permissions removed

Verdict

The PR successfully addresses the issues outlined in #211:

  • ✓ Tab synchronization issues resolved
  • ✓ Python indentation errors fixed
  • ✓ Progress tracking standardized
  • ✓ Commands use uv run consistently
  • ✓ Accurate verification steps

Ready to merge. The documentation quality is significantly improved.

Copilot AI reviewed Jan 21, 2026
View reviewed changes
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

@itomek itomek added this pull request to the merge queue Jan 22, 2026
Merged via the queue into amd:main with commit 4338b2d Jan 22, 2026
51 checks passed
@itomek itomek deleted the 211-fix-hardware-advisor-playbook-structure branch January 22, 2026 00:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@kovtcharov kovtcharov kovtcharov approved these changes

@kovtcharov-amd kovtcharov-amd Awaiting requested review from kovtcharov-amd kovtcharov-amd is a code owner

Assignees

@itomek itomek

Labels

agents Agent system changes documentation Documentation changes

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Hardware Advisor Agent playbook step1_basic.py

3 participants

@itomek @kovtcharov