Skip to content

START_HERE.md

Latest commit

 

History

History
298 lines (219 loc) · 6.93 KB

START_HERE.md

File metadata and controls

298 lines (219 loc) · 6.93 KB

🚀 START HERE - PYTHON DEBUGGER SETUP FOR ZED

⚡ You're 30 Seconds Away From Debugging!

This file tells you EXACTLY what to do right now.

📋 WHAT WAS SET UP FOR YOU

✅ Configuration Files Created:

  • .zed/settings.json - Python language server & formatter settings
  • .zed/tasks.json - 20+ debugging & development tasks

✅ Documentation Created:

  • DEBUG_GUIDE.md - Complete 769-line guide with 10 examples
  • ZED_DEBUGGER_QUICKREF.md - 2-minute quick reference card
  • SENTINEL_DEBUGGING.md - Sentinel project-specific debugging guide
  • debug_example.py - 10 interactive debugging examples to run
  • This file you're reading now

✅ Ready to Debug:

  • Python debugger (DAP) - Built-in to Zed
  • Breakpoints - Click on line numbers
  • Step through code - F10, F11 shortcuts
  • Inspect variables - Variables panel
  • Execute expressions - Console panel

🎯 DO THIS NOW (5 MINUTES)

Step 1: Prepare (1 minute)

cd ~/DaatScience/Sentinel

# Activate virtual environment
source .venv/bin/activate

# Install debugger tools (if needed)
pip install debugpy

# Verify
python -c "import debugpy; print('✓ Ready to debug!')"

Step 2: Open Zed (1 minute)

# Open the project in Zed
zed .

Step 3: Set a Breakpoint (1 minute)

  1. Open main.py
  2. Click on line number 2 (the line with print("Hello from sentinel!"))
  3. A red dot appears - that's your breakpoint!

Step 4: Start Debugging (1 minute)

  • Press F5 (or use Ctrl+Shift+T → "Debug: Run Current File")
  • The debugger will pause at your breakpoint
  • You should see the Variables panel appear at the bottom
  • Your code paused! 🎉

Step 5: Step Through Code (1 minute)

  • Press F10 to step to the next line
  • Press F10 again to finish
  • Press F5 to continue
  • See how easy that was? 🎊

🎮 KEYBOARD SHORTCUTS - PRINT THESE!

F5              Start Debugger / Continue
F9              Toggle Breakpoint
F10             Step Over (execute line, don't enter functions)
F11             Step Into (enter function to debug inside)
Shift+F11       Step Out (exit current function)
Ctrl+Shift+D    Show/Hide Debugger Panel
Ctrl+Shift+T    Open Tasks Menu

📖 NEXT: LEARN THE BASICS

Read These Files (In This Order)

  1. ZED_DEBUGGER_QUICKREF.md (2 minutes)

    • Quick reference card
    • Essential shortcuts
    • Common scenarios

  2. DEBUG_GUIDE.md (20 minutes)

    • Comprehensive guide
    • All features explained
    • Troubleshooting

  3. SENTINEL_DEBUGGING.md (15 minutes)

    • Sentinel project-specific
    • Agent debugging
    • FastAPI debugging
    • LLM debugging

🧪 TRY INTERACTIVE EXAMPLES

# This runs 10 debugging examples
python debug_example.py

# When it starts, press F5 to debug
# Then use F10 to step through each example
# Each example teaches a different debugging technique

🎯 DEBUG YOUR SENTINEL PROJECT

Debug the Response Agent

# Method 1: Direct run with debugger
python debug_response_agent.py
# Then press F5

# Method 2: Using Zed tasks
# Press Ctrl+Shift+T → "Debug: Run Agent Debug Script"

Debug LLM Setup

python debug_llm_setup.py
# Press F5 to debug

Debug FastAPI

# In Zed: Ctrl+Shift+T → "Debug: FastAPI with Auto-reload"
# Wait for "Uvicorn running on http://0.0.0.0:8000"

# In another terminal:
curl http://localhost:8000/health
# Debugger will pause at your breakpoints

Debug Tests

# In Zed: Ctrl+Shift+T → "Test: Run Current Test File"
# Or: Ctrl+Shift+T → "Test: Run All Tests"

🔍 INSPECT YOUR CODE

When Paused (At Breakpoint)

Variables Panel (Bottom right)

  • Shows all local variables
  • Click ▶ to expand nested objects
  • Hover over any variable in code to see value

Console Panel (Bottom)

  • Type Python code to evaluate
  • Examples: 
    my_variable        # Print value
len(my_list)       # Call function
x + y              # Math
my_dict["key"]     # Access dict

Call Stack Panel (Bottom)

  • Shows function call hierarchy
  • Click any frame to jump to that code
  • Understand how you got here

Watch Expressions (Bottom)

  • Click + to add expression
  • Examples: 
    len(items)
x * 2
data["key"]
  • Expression updates as you step

🐛 COMMON DEBUGGING WORKFLOW

1. Understand the problem
   "What should happen? What actually happens?"

2. Find where it fails
   "Which line causes the issue?"

3. Set breakpoint there
   Click on line number → red dot

4. Start debugger
   Press F5

5. Inspect variables
   Hover over, check Variables panel

6. Step through code
   F10 to step line by line

7. Find the bug
   Which variable is wrong?

8. Fix it
   Edit the code

9. Test it
   Run again without debugger

✅ CHECKLIST - YOU'RE READY IF:

  • Read this file (you're doing it!)
  • Activated virtual environment: source .venv/bin/activate
  • Installed debugpy: pip install debugpy
  • Opened Zed: zed .
  • Set a breakpoint: Click on line number (red dot appears)
  • Started debugger: Press F5
  • Saw Variables panel: Should appear at bottom
  • Stepped through code: Press F10

If all checked ✓, you're ready to debug!

🆘 QUICK TROUBLESHOOTING

Problem Solution
Breakpoint not hit Verify correct Python: which python (should show .venv/bin/python)
Debugger won't start Install: pip install debugpy
Can't see variables Make sure debugger is paused at breakpoint (look for Variables panel)
Print statements don't show Use logger instead: logger.debug("msg")
Stuck in infinite loop Press Ctrl+C to stop, then fix code

📚 FULL DOCUMENTATION

If you need more details:

  • Quick reference? → Read ZED_DEBUGGER_QUICKREF.md
  • Complete guide? → Read DEBUG_GUIDE.md
  • Sentinel-specific? → Read SENTINEL_DEBUGGING.md
  • Want examples? → Run python debug_example.py

🚀 NOW GO DEBUG!

  1. Open terminal
  2. Run: cd ~/DaatScience/Sentinel && zed .
  3. Click on a line number to set breakpoint
  4. Press F5 to start debugging
  5. Use F10 to step through
  6. Inspect variables in the Variables panel
  7. Press F5 to continue

You've got this! Happy debugging! 🎉

💡 PRO TIPS

  • Breakpoints stay when you close Zed (Zed remembers them)
  • You can set conditions on breakpoints (right-click → Edit Breakpoint)
  • Stepping with F10 is faster than F11 (doesn't enter functions)
  • Use console to quickly test expressions
  • Use watch expressions to monitor specific values

📞 NEED HELP?

  1. Quick answer? → Check ZED_DEBUGGER_QUICKREF.md
  2. Don't understand? → Read the section in DEBUG_GUIDE.md
  3. Want examples? → See debug_example.py
  4. Project specific? → Check SENTINEL_DEBUGGING.md
  5. Still stuck? → Read Troubleshooting section above

You're all set! Press F5 and start debugging! 🚀