Skip to content

QUICKSTART.md

Latest commit

 

History

History
283 lines (208 loc) · 5.61 KB

QUICKSTART.md

File metadata and controls

283 lines (208 loc) · 5.61 KB

Quick Start Guide - Interactive Tutor CLI

Get up and running with the Binary Math Interactive Tutor in under 5 minutes.

1. Verify Installation

# Navigate to project directory
cd /Users/bhunt/development/claude/binary

# Verify file structure
ls -la src/

# Should see:
# - interactive_tutor.py
# - __init__.py
# - README.md

2. Run Demo (Optional)

# Test all functionality
python3 demo_tutor.py

Expected Output: "All demos completed successfully! ✓"

3. Start Interactive Tutor

python3 src/interactive_tutor.py

4. Basic Workflow

Start New Lesson

  1. Select "1. Start New Lesson"
  2. Choose lesson: "1. Binary Basics"
  3. Choose difficulty: "1. Beginner"
  4. Answer questions by typing your answer

Use Commands

  • Type h for a hint
  • Type s to save progress
  • Type q to quit to menu

Resume Later

  1. Select "2. Resume Lesson"
  2. Choose your saved session
  3. Continue from where you left off

5. Example Session

Binary Math Interactive Tutor
Main Menu:
  1. Start New Lesson
  2. Resume Lesson
  3. Practice Mode
  4. View Progress
  5. Exit

Select option: 1

Select Your Lesson:
  1. Binary Basics - Introduction to Base-2 Numbers
  ...
Select lesson: 1

Choose Difficulty Level:
  1. Beginner - Step-by-step guidance, unlimited hints
  ...
Select difficulty: 1

============================================================
Question 1/3
============================================================

Convert decimal 10 to binary

Commands: n=next | b=back | h=hint | r=retry | s=save | q=quit | ?=help
> 1010

✓ Correct! Streak: 1

============================================================
Question 2/3
============================================================

Convert binary 1101 to decimal

Commands: n=next | b=back | h=hint | r=retry | s=save | q=quit | ?=help
> h

💡 Hint 1/999:
Each position is a power of 2: 2^3, 2^2, 2^1, 2^0

> 13

✓ Correct! Streak: 2

6. Commands Reference

Command Description
h Request a hint (limited by difficulty)
n Next question
b Previous question
s Save progress
q Quit to main menu
? Show help
[answer] Answer current question

7. Session Storage

Sessions are saved to: ~/.binary_tutor/sessions/

View your saved sessions:

ls -la ~/.binary_tutor/sessions/

8. Difficulty Levels

Beginner

  • Unlimited hints
  • Step-by-step guidance
  • Detailed explanations

Intermediate

  • 3 hints per problem
  • Moderate guidance
  • Standard explanations

Advanced

  • 1 hint per problem
  • Minimal guidance
  • Concise explanations

9. Lesson Types

Binary Basics

  • Decimal to binary conversion
  • Binary to decimal conversion
  • Binary arithmetic

Logic Gates

  • AND, OR, NOT operations
  • XOR operations
  • Gate evaluation

Truth Tables

  • Building truth tables
  • Reading truth tables
  • Analyzing expressions

Practice Mode

  • Mixed problem types
  • Adaptive difficulty
  • Timed sessions

10. Troubleshooting

Colors not showing?

# Disable colors in code
# Edit src/interactive_tutor.py line ~750:
self.display = DisplayRenderer(use_colors=False)

Session won't save?

# Check/create directory
mkdir -p ~/.binary_tutor/sessions
chmod 755 ~/.binary_tutor/sessions

Command not recognized?

  • Make sure to press Enter after typing command
  • Use lowercase letters
  • Check available commands with ?

11. Tips

  1. Use hints wisely - They help you learn, but try solving first
  2. Save often - Type s to save your progress
  3. Check stats - Use "View Progress" to see your accuracy
  4. Resume sessions - Don't lose progress, resume anytime
  5. Practice mode - Use for mixed problem review

12. Next Steps

  1. Complete all Binary Basics lessons
  2. Progress to Logic Gates
  3. Master Truth Tables
  4. Challenge yourself with Advanced difficulty
  5. Try Practice Mode for mixed problems

13. For Developers

Run programmatically

from src.interactive_tutor import TutorOrchestrator

tutor = TutorOrchestrator()
tutor.run()

Access session data

from src.interactive_tutor import SessionManager

manager = SessionManager()
sessions = manager.list_active_sessions()
print(f"Active sessions: {len(sessions)}")

Customize display

from src.interactive_tutor import DisplayRenderer

# Disable colors
display = DisplayRenderer(use_colors=False)

# Use custom renderer
display.show_success("Custom message!")

14. Integration Notes

The current implementation uses mock lesson data. To integrate with actual lesson modules:

  1. Implement lesson modules following the interface:

    • binary_basics.py
    • logic_gates.py
    • truth_tables.py
    • practice_generator.py

  2. Update TutorOrchestrator._start_new_lesson():

    # Replace this:
self.current_lesson = LessonInterface(lesson_type, difficulty)

# With this:
lesson_classes = {
    LessonType.BINARY_BASICS: BinaryBasicsLesson,
    LessonType.LOGIC_GATES: LogicGatesLesson,
    LessonType.TRUTH_TABLES: TruthTablesLesson,
}
self.current_lesson = lesson_classes[lesson_type](difficulty)

15. Support

  • Documentation: See /src/README.md
  • Architecture: See /INTERACTIVE_TUTOR_ARCHITECTURE.md
  • Implementation: See /IMPLEMENTATION_SUMMARY.md

Quick Command Summary

# Run demo
python3 demo_tutor.py

# Run interactive tutor
python3 src/interactive_tutor.py

# View sessions
ls -la ~/.binary_tutor/sessions/

# Clean sessions
rm -rf ~/.binary_tutor/sessions/*

You're ready to go! Start learning binary math! 🎓