search-algorithms-explainer 1.0.1

Interactive CLI tool for exploring search algorithms

🔍 Search Algorithms Explainer CLI

A professional, interactive command-line tool for learning and comparing search algorithms. This project demonstrates Linear Search, Binary Search, and their performance characteristics with real-time step-by-step execution.

✨ Features

🎯 Interactive CLI Interface

• User-friendly menu system
• Real-time step-by-step algorithm execution
• Direct visualization of how algorithms work

🔎 Search Algorithms

• Linear Search: Sequential search with O(n) time complexity
• Binary Search: Efficient sorted search with O(log n) time complexity
• Comparison Mode: Run both algorithms side-by-side with the same data

📊 Result Tracking

• Automatic logging of all searches
• Performance metrics (steps taken, time complexity, space complexity)
• Search history with detailed results
• Ability to clear individual results

🎨 Flexible Input

• Pre-loaded questions from JSON
• Manual list input
• Inline number entry (e.g., 1 2 3 4)

📦 Installation

From PyPI (Recommended)

pip install search-algorithms-explainer

From Source

# Clone or download the project
cd search-algorithms-explainer

# Install in development mode
pip install -e .

# Or just run directly
python -m search_algorithms

Requirements

• Python 3.7 or higher
• No external dependencies (uses only Python standard library)

🚀 Quick Start

Start Interactive Mode (Default)

search-algo

# or
python -m search_algorithms

# or
search-algo /start

📖 Usage

Available Commands

Command	Description
search-algo /start	Start interactive program (default)
search-algo /history	View all search history
search-algo /clearresult	Remove last search result
search-algo /end	Exit program
search-algo --version or -v	Show version
search-algo --help or -h	Show help message

Quick Start Guide

1. Start the program

   search-algo
   

2. Choose a question (Q1, Q2, etc.) or enter numbers manually

   Which question (Q1) or command: Q1
   

3. Select an algorithm

   1 - Linear Search
   2 - Binary Search (on sorted list)
   3 - Compare Linear vs Binary
   

4. Enter target number and watch the algorithm execute step-by-step

5. View history at any time with /history

Interactive Mode

$ search-algo /start

======================================================
 SEARCH ALGORITHMS EXPLAINER
 Version 1.0.0
 Interactive Mode Started
======================================================

--------------------------------------
 Choose question key from JSON (e.g. Q1)
--------------------------------------
Available keys:
Q1  Q2  Q3  Q4  Q5
--------------------------------------
You may type: Q1  OR  manual  OR  numbers directly (e.g. 1 2 3 4)
Type 'exit' to quit.
--------------------------------------

Input Options

Input Type	Example	Description
Predefined Questions	Q1, Q2, Q3	Use pre-loaded question data
Manual Input	manual	Enter a custom list manually
Inline Numbers	1 2 3 4	Search in inline-entered numbers

Algorithm Options

1. Linear Search: Sequential search through the list
2. Binary Search: Efficient search on sorted list (automatically sorts input)
3. Compare Both: Run both algorithms and compare results side-by-side

📊 Example Session

$ search-algo /start

Which question (Q1) or command: 5 10 15 20 25

Loaded list for 5 10 15 20 25:
List contents:
5 10 15 20 25
--------------------------------------

--------------------------------------
 Choose algorithm:
 1 - Linear Search
 2 - Binary Search (on sorted list)
 3 - Compare Linear vs Binary
 b - Back to choose Q-key
 exit - Quit program
--------------------------------------
Enter choice (1/2/3/b/exit): 3

Enter target number to search: 15

===== Comparing Linear Search vs Binary Search =====

[1] Running Linear Search...

--------- LINEAR SEARCH ---------
Step 1 : index = 0 , element = 5 , target = 15
=> Not equal, moving next

Step 2 : index = 1 , element = 10 , target = 15
=> Not equal, moving next

Step 3 : index = 2 , element = 15 , target = 15
=> Match found
=> Element 15 found at index 2
Total steps taken (Linear Search): 3

[2] Running Binary Search...

--------- BINARY SEARCH ---------
Note: Binary Search works on a sorted list.
Sorted list used:
List contents:
5 10 15 20 25
Step 1 : low = 0 , high = 4 , mid = 2 , element = 15 , target = 15
=> Match found
=> Element 15 found at index 2 (in sorted list)
Total steps taken (Binary Search): 1

----------- SUMMARY -----------
Linear Search  : Found (index 2 in original list)
Binary Search  : Found (index 2 in sorted list)

Steps taken:
  Linear Search  -> 3 steps
  Binary Search  -> 1 steps

Time Complexity:
  Linear Search  -> O(n)
  Binary Search  -> O(log n)  (requires sorted list)
-------------------------------

📈 View History

$ search-algo /history

============================================================
 SEARCH HISTORY
============================================================

[1] Question: inline: 5 10 15 20 25
    Method: Linear Search (Compare Mode)
    Result: Found
    Steps: 3
    Time Complexity: O(n)
    Space Complexity: O(1)

[2] Question: inline: 5 10 15 20 25
    Method: Binary Search (Compare Mode)
    Result: Found
    Steps: 1
    Time Complexity: O(log n)
    Space Complexity: O(1)

============================================================
Total entries: 2
============================================================

🎓 How It Works

Linear Search

Linear Search examines each element sequentially until finding the target or reaching the end.

• Time Complexity: O(n) - must check every element in worst case
• Space Complexity: O(1) - no extra space needed
• Use Case: Works on unsorted lists, good for small datasets

Binary Search

Binary Search divides the search space in half repeatedly (requires sorted data).

• Time Complexity: O(log n) - halves search space each iteration
• Space Complexity: O(1) - no extra space needed
• Use Case: Very efficient for large sorted datasets
• Note: Algorithm automatically sorts the input for demonstration

Comparison Mode

Run both algorithms with the same target on the same data to see:

• How many steps each algorithm takes
• Which is more efficient for the given dataset
• Real-time visualization of each algorithm's execution

🎓 Learning Objectives

This tool helps you understand:

• How Linear Search works sequentially
• How Binary Search divides the search space
• Time complexity differences (O(n) vs O(log n))
• When to use each algorithm
• Performance comparison with real examples

📁 Project Structure

search-algorithms-explainer/
├── search_algorithms/          # Main package
│   ├── __init__.py
│   ├── __main__.py            # Entry point
│   ├── config.py
│   ├── core/                  # Core algorithms
│   │   ├── __init__.py
│   │   └── search_algorithms.py
│   ├── cli/                   # Command-line interface
│   │   ├── __init__.py
│   │   ├── menu.py
│   │   └── commands.py
│   └── utils/                 # Utility functions
│       ├── __init__.py
│       ├── data_handler.py
│       └── input_handler.py
├── data/                      # Data files
│   └── questions.json         # Pre-loaded questions
├── bin/                       # Executable scripts
├── setup.py                   # Package setup
├── pyproject.toml            # Modern Python packaging
├── requirements.txt          # Dependencies
├── README.md                 # This file
├── LICENSE                   # MIT License
└── .gitignore               # Git ignore rules

💾 Result Logging

All search results are automatically saved to results.json with:

• Question identifier
• Algorithm used
• Number of steps taken
• Time and space complexity
• Whether target was found

Example results.json

[
    {
        "question": "Q1",
        "method": "Linear Search",
        "time_complexity": "O(n)",
        "space_complexity": "O(1)",
        "steps": 5,
        "found": "Found"
    }
]

📋 Data Files

questions.json

Pre-loaded with 30 test questions (Q1-Q30) containing various list configurations:

• Sorted lists
• Reversed lists
• Random lists
• Duplicates
• Special patterns

Location: data/questions.json

🛠️ Development

Running Tests

pytest tests/

Code Style

This project follows PEP 8 guidelines. Use these tools:

# Format code
black search_algorithms/

# Check style
flake8 search_algorithms/
pylint search_algorithms/

# Check types
mypy search_algorithms/

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Created with ❤️ for learning and education

🔗 Links

• PyPI Package: https://pypi.org/project/search-algorithms-explainer/
• GitHub Repository: https://github.com/yourusername/search-algorithms-explainer
• Documentation: https://github.com/yourusername/search-algorithms-explainer/wiki
• Issue Tracker: https://github.com/yourusername/search-algorithms-explainer/issues

🆘 Support

For issues, questions, or suggestions:

• Check existing documentation
• Review example usage
• Create an issue on GitHub
• Contact via email

📝 Changelog

Version 1.0.0 (2024-12-04)

• ✅ Initial release
• ✅ Linear Search implementation
• ✅ Binary Search implementation
• ✅ Comparison mode
• ✅ Result history tracking
• ✅ Professional CLI structure
• ✅ Complete documentation
• ✅ Interactive CLI interface
• ✅ Search history tracking
• ✅ Result logging to JSON
• ✅ Compare mode for algorithms

---

Happy Learning! 🚀

Made with ❤️ for education and learning