modular-noc-scheduling

Name	modular-noc-scheduling JSON
Version	1.0.3 JSON
	download
home_page	None
Summary	Shift Scheduling Algorithm using OR-Tools with Modular Constraints
upload_time	2025-08-21 12:28:42
maintainer	None
docs_url	None
author	Innovation Team - Digital Transformation
requires_python	>=3.8
license	MIT
keywords	scheduling optimization constraint-programming ortools employee-scheduling shift-scheduling noc-scheduling ramadan-scheduling holiday-scheduling workforce-management
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Modular NOC Scheduling System

[![PyPI version](https://badge.fury.io/py/modular-noc-scheduling.svg)](https://badge.fury.io/py/modular-noc-scheduling)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A comprehensive and intelligent employee scheduling system designed specifically for Network Operations Centers (NOC) and similar 24/7 operations. Built with advanced constraint programming using Google OR-Tools, this system ensures fair, efficient, and culturally-aware work schedules.

## 🚀 Quick Start

### Installation

Install the package from PyPI:

```bash
pip install modular-noc-scheduling
```

### Basic Usage

#### Python API
```python
from modular_scheduling import ModularNOCScheduler, run_modular_scheduling_algorithm

# Quick start with default settings
result = run_modular_scheduling_algorithm(
    employees=['Alice', 'Bob', 'Charlie'],
    employee_types=['E', 'E', 'B'],  # E=Expert, B=Beginner
    year=2025,
    month=9
)

# Print the generated schedule
print(result)
```

#### Command Line Interface
```bash
# Run the interactive scheduling tool
modular-scheduling

# Or with parameters
modular-scheduling --year 2025 --month 9 --employees "Alice,Bob,Charlie"
```

### Key Features at a Glance

- ✅ **24/7 Shift Coverage**: Morning, Evening, Night shifts
- ✅ **Cultural Awareness**: Special Ramadan scheduling
- ✅ **Expert Supervision**: Automatic beginner-expert pairing
- ✅ **Fair Distribution**: Balanced workload across team members
- ✅ **Holiday Management**: Intelligent holiday and weekend coverage
- ✅ **Constraint-Based**: Uses advanced optimization algorithms
- ✅ **Modular Design**: Easy to extend and customize

## 📋 Table of Contents
1. [Installation & Quick Start](#-quick-start)
2. [What is This Algorithm?](#what-is-this-algorithm)
3. [Who Should Use This Guide?](#who-should-use-this-guide)
4. [Key Features](#key-features)
5. [Understanding the Basics](#understanding-the-basics)
6. [How to Use the Algorithm](#how-to-use-the-algorithm)
7. [Understanding the Schedule Output](#understanding-the-schedule-output)
8. [Common Scenarios and Solutions](#common-scenarios-and-solutions)
9. [Troubleshooting](#troubleshooting)
10. [Technical Information](#technical-information)
11. [API Reference](#api-reference)
12. [Contributing](#contributing)

---

## What is This Algorithm?

The **Modular NOC Scheduling System** is an intelligent software tool designed to automatically create work schedules for Network Operations Center (NOC) teams. Think of it as a smart assistant that considers all your workplace rules, employee availability, holidays, and cultural requirements to generate fair and efficient work schedules.

### What Makes It Special?
- **Intelligent**: Uses advanced algorithms to solve complex scheduling puzzles
- **Fair**: Ensures equal distribution of workload among team members
- **Cultural-Aware**: Handles special requirements during Ramadan
- **Flexible**: Adapts to different team sizes and requirements
- **Reliable**: Guarantees all shifts are properly covered with qualified staff

---

## Who Should Use This Guide?

This guide is designed for:
- **Team Managers**: Who need to create monthly schedules
- **HR Personnel**: Responsible for workforce planning
- **Supervisors**: Who monitor shift coverage and fairness
- **Non-Technical Users**: Who want to understand how the algorithm works

**No programming knowledge required!** This guide explains everything in simple terms.

---

## Key Features

### 🕐 Multiple Shift Types
- **Morning Shifts (M)**: Regular daytime work
- **Evening Shifts (E)**: Afternoon/evening coverage
- **Night Shifts (N)**: Overnight operations
- **Ramadan Shifts**: Special shifts during the holy month with adjusted timings

### 🏖️ Holiday & Weekend Management
- Automatic holiday detection from your calendar
- Special holiday shifts with premium staffing
- Weekend coverage ensuring business continuity
- Regional calendar support (Hijri and Gregorian)

### 👥 Smart Team Management
- **Expert vs. Beginner** classification
- Automatic supervision pairing (beginners always work with experts)
- Fair workload distribution based on experience levels
- Vacation balance consideration for off-day allocation

### ⚖️ Fairness Guarantees
- Equal distribution of weekend and holiday work
- Balanced shift assignments over time
- Consideration of remaining vacation days
- Prevention of excessive consecutive shifts

### 🔧 Customizable Rules
- Enable/disable specific scheduling rules as needed
- Adapt to your organization's unique requirements
- Easy modification without technical expertise

---

## Understanding the Basics

### Employee Types
The algorithm recognizes two types of employees:

**Experts (E)**
- Experienced team members who can work independently
- Can supervise and guide beginners

**Beginners (B)**
- Newer team members requiring supervision
- Must always work alongside at least one expert

### Shift Categories

**Normal Days**
- **M (Morning)**: Standard day shift
- **E (Evening)**: Standard evening shift  
- **N (Night)**: Standard night shift

**Ramadan Days** (Special cultural/religious period)
- **MR (Morning Ramadan)**: Adjusted morning hours
- **E1R (Evening 1 Ramadan)**: First evening shift with special timing
- **E2R (Evening 2 Ramadan)**: Second evening shift with special timing
- **NR (Night Ramadan)**: Night shift with special considerations

**Holiday Variants**
- All shift types get an "H" prefix on holidays (e.g., HM, HE, HN)
- Holiday shifts may have different staffing requirements

**Special States**
- **OFF**: Scheduled day off
- **No Shift Assigned - Rest**: Mandatory rest day (cannot be changed)

### Calendar Integration
The algorithm automatically identifies:
- **Weekdays**: Sunday through Thursday (normal work days)
- **Weekends**: Friday and Saturday (require special coverage)
- **Holidays**: National and religious holidays from your calendar
- **Ramadan Period**: Automatically calculated based on Islamic calendar

---

## How to Use the Algorithm

### Installation

Before using the algorithm, you need to install the package and its dependencies.

#### Method 1: Install from Source (Recommended)

**Prerequisites:**
- Python 3.8 or higher
- pip (Python package installer)

**Installation Steps:**

1. **Navigate to the Package Directory**
   ```bash
   # Navigate to the scheduling_package directory
   cd c:\Projects\scheduling_package
   ```

2. **Install the Package**
   ```bash
   # Install in development mode (recommended for customization)
   pip install -e .
   
   # Or install normally
   pip install .
   ```

3. **Verify Installation**
   ```bash
   # Test the command-line interface
   modular-scheduling --help
   
   # Note: The web UI (scheduling-ui) requires additional setup
   # See Method 3 below for web interface setup
   ```

#### Method 2: Run Directly Without Package Installation

If you prefer to run the algorithm directly from source without installing the package:

```bash
# First, install only the required dependencies manually
pip install ortools>=9.0.0 hijri-converter>=2.2.4 streamlit>=1.28.0 pandas>=1.5.0 numpy>=1.21.0 typing-extensions>=4.0.0

# Then navigate to the package directory and run directly
cd c:\Projects\scheduling_package\modular_scheduling
python modular_scheduler.py --help
```

**Note**: When you use Method 1 (`pip install .` or `pip install -e .`), all dependencies are automatically installed from the package's `setup.py` configuration, so you don't need to install them manually.

#### Method 3: Web Interface Setup (Optional)

For the web-based interface, you need to copy the UI module from the main OR-Tools project:

```bash
# Copy the web UI module from the main project
copy "c:\Projects\OR-Tools\Real Projects\modular_scheduling\modular_ui.py" "c:\Projects\scheduling_package\modular_scheduling\"

# Then install the package with the UI
pip install -e .

# Now you can use the web interface
scheduling-ui
```

#### Development Installation (For Developers)

If you plan to modify or contribute to the algorithm:

```bash
pip install -e .
# Install with development dependencies
pip install -e ".[dev]"

# Install with documentation dependencies  
pip install -e ".[docs]"

# Install with all optional dependencies
pip install -e ".[dev,docs]"
```

**Windows Notes:**
- If you encounter issues with OR-Tools installation, you might need Microsoft Visual C++ 14.0 or greater
- Use PowerShell or Command Prompt as Administrator if you get permission errors
- On some Windows systems, you may need to use `python -m pip` instead of just `pip`

### Quick Start

Once installed, you can run the algorithm in several ways:

**Option 1: Command Line (Always Available)**
```bash
# Run the scheduling algorithm directly
modular-scheduling --help

# Or run directly from source
python c:\Projects\scheduling_package\modular_scheduling\modular_scheduler.py --help
```

**Option 2: Web Interface (If UI Module is Set Up)**
```bash
# Launch the web-based user interface (requires Method 3 installation above)
scheduling-ui
```
This will start a local web server and open the algorithm interface in your browser.

**Option 3: Direct Python Import**
```python
# For programmatic use in your own Python scripts
from modular_scheduling.modular_scheduler import main
# Your code here
```

**Getting Started Quickly:**

**Easiest Method (Automatic Dependencies):**
1. Navigate to package: `cd c:\Projects\scheduling_package`
2. Install with dependencies: `pip install -e .`
3. Run: `modular-scheduling --help`

**Manual Method (If you prefer not to install the package):**
1. Install dependencies manually: `pip install ortools hijri-converter streamlit pandas numpy typing-extensions`
2. Navigate to: `cd c:\Projects\scheduling_package\modular_scheduling`
3. Run: `python modular_scheduler.py --help`

---

### Method 1: Web Interface (Recommended for Most Users)

**Step 1: Launch the Algorithm**
1. Open your web browser
2. Navigate to the algorithm URL (provided by your IT team)
3. You'll see a user-friendly interface with clear sections

**Step 2: Enter Basic Information**
- **Year and Month**: Select the period you want to schedule
- **Team Size**: The algorithm will ask how many employees to schedule

**Step 3: Add Employee Information**
For each team member, provide:
- **Employee Type**: Expert or Beginner
- **Remaining Vacation Days**: How many vacation days they have left

**Step 4: Upload Holiday Calendar (Optional)**
- If you have a special holiday file, upload it

**Step 5: Configure Rules (Advanced)**
Most users can skip this section, but you can:
- Enable/disable specific scheduling rules
- Adjust minimum shift requirements
- Modify fairness settings

**Step 6: Generate Schedule**
- Click "Generate Schedule"
- Wait for the algorithm to process (maybe take afew seconds)
- Review the generated schedule

### Method 2: File-Based Input

If your organization prefers file-based processes:
1. Prepare an employee data file with required information
2. Ensure holiday calendar is in the correct format
3. Run the algorithm with these files as input

---

## Understanding the Schedule Output

### Reading the Schedule

The algorithm generates a calendar-style schedule showing:
- **Rows**: Each day of the month
- **Columns**: Each team member
- **Cells**: Assigned shift or status for each person each day

### Color Coding (Web Interface)
- **Blue**: Normal shifts (M, E, N)
- **Green**: Ramadan shifts (MR, E1R, E2R, NR)
- **Red**: Holiday shifts (HM, HE, HN, etc.)
- **Gray**: Off days
- **White**: Rest days (mandatory)

### Schedule Statistics
The algorithm provides helpful statistics:
- **Total shifts per employee**: Ensuring fairness
- **Weekend/Holiday distribution**: Showing equal sharing
- **Shift type distribution**: Balanced assignment patterns
- **Overtime indicators**: If someone exceeds normal limits

### Generated Files
The algorithm creates several detailed reports:

**1. Input Summary**
- All the parameters you entered
- Which rules were enabled/disabled
- Team composition details

**2. Schedule Solution**
- Complete day-by-day assignments
- Easy-to-read format for printing or sharing

**3. Off-Days Distribution**
- Calculation details for vacation day allocation
- Fairness metrics and explanations

**4. Calendar Information**
- Holiday and weekend identification
- Ramadan period calculations

---

## Common Scenarios and Solutions

### Scenario 1: "The Algorithm Says No Solution Found"
**What this means**: Your requirements cannot be met with the current team size or constraints.

**Solutions**:
- Add more team members
- Reduce minimum shift requirements
- Check if vacation day allocations are realistic

### Scenario 2: "Someone Has Too Many Shifts"
**What this means**: The workload distribution isn't perfectly even.

**Solutions**:
- Enable the "Fair Distribution" constraints
- Increase the solution search time
- Consider if the person has fewer vacation days (affecting their off-day allocation)

### Scenario 3: "Weekend Coverage Looks Uneven"
**What this means**: Some people work more weekends than others.

**Solutions**:
- Ensure "Fair Weekend Distribution" is enabled
- Check that you have enough team members for weekend coverage
- Consider the impact of vacation day differences

### Scenario 4: "Ramadan Shifts Aren't Working"
**What this means**: The algorithm can't properly assign special Ramadan shifts.

**Solutions**:
- Verify the Ramadan period is correctly calculated
- Ensure you have enough experts for supervision during Ramadan
- Check that Ramadan-specific constraints are enabled

### Scenario 5: "Holiday Coverage Is Missing"
**What this means**: Some holidays don't have proper shift coverage.

**Solutions**:
- Upload a complete holiday calendar file
- Enable holiday shift constraints
- Ensure minimum holiday staffing requirements are met

---

## Troubleshooting

### Common Issues and Quick Fixes

**Issue**: Algorithm is very slow
- **Solution**: Reduce the number of solutions requested, try with fewer constraints enabled

**Issue**: Schedule looks unfair
- **Solution**: Enable all fairness constraints

**Issue**: Beginners are working alone
- **Solution**: Ensure "Expert Supervision" constraint is enabled, check expert-to-beginner ratio

**Issue**: Too many consecutive work days
- **Solution**: Enable "Limit Contiguous Shifts" constraint, adjust maximum consecutive days

**Issue**: Off days don't match vacation entitlements
- **Solution**: Verify vacation day numbers are correct, enable vacation-based off-day constraints

### When to Contact Support
Contact your IT team if:
- The algorithm doesn't load or crashes
- You get error messages you don't understand
- The schedule results seem completely wrong
- You need to modify algorithm rules or constraints

---

## Technical Information

### Algorithm Architecture

**Core Components**
- **Scheduler Engine**: Uses Google OR-Tools constraint programming
- **Web Interface**: Built with Streamlit for easy use
- **Constraint Algorithm**: Modular rules that can be enabled/disabled
- **Calendar Integration**: Supports both Gregorian and Hijri calendars

**How It Works**
1. **Input Processing**: Algorithm converts your requirements into mathematical constraints
2. **Optimization**: Advanced algorithms find the best schedule that satisfies all rules
3. **Solution Generation**: Multiple valid schedules may be found
4. **Output Formatting**: Results are presented in user-friendly formats

### Constraint Categories

**Coverage Constraints**
- Ensure all shifts have adequate staffing
- Guarantee weekend and holiday coverage
- Maintain 24/7 operations continuity

**Fairness Constraints**
- Equal distribution of workload
- Balanced weekend/holiday assignments
- Fair vacation day consideration

**Safety Constraints**
- Expert supervision for beginners
- Mandatory rest after certain shift sequences
- Limits on consecutive working days

**Cultural Constraints**
- Special Ramadan shift patterns
- Regional holiday observances
- Cultural work week conventions

### File Formats

**Employee Data Input**
Employee information is entered through the web interface with the following parameters:
- **Employee Type**: `EXPERT` or `BEGINNER`
- **Vacation Days**: Integer value (0-21 for experts, 0-14 for beginners)

No separate employee data file is required - all input is handled through the interactive web interface.

**Holiday File Format**
Upload a text file (.txt) with holidays using this exact format:
```
day; month; description
1; 1; New Year's Day
15; 8; Independence Day
25; 12; Christmas Day
```

Format requirements:
- Each line contains: `day; month; description`
- Semicolon (`;`) separated values
- Day and month as integers (e.g., 1-31 for day, 1-12 for month)
- Description is optional but recommended for clarity
- Lines starting with "day" are treated as headers and ignored
- Empty lines are ignored
- File encoding: UTF-8

**Generated Output Files**
The algorithm automatically creates several output files with structured formats:

1. **Input Summary** (`input_summary_YYYY_MM_timestamp.txt`)
   - Contains all input parameters and constraint settings
   - Employee details and configuration used

2. **Solution File** (`solution_YYYY_MM_timestamp_sol1.txt`)
   - Complete day-by-day schedule assignments
   - Employee-day-shift mappings in readable format

---

## 🔧 API Reference

### Core Classes

#### `ModularNOCScheduler`
Main scheduler class with modular constraint architecture.

```python
from modular_scheduling import ModularNOCScheduler

scheduler = ModularNOCScheduler(
    employees=['Alice', 'Bob', 'Charlie'],
    employee_types=['E', 'E', 'B'],
    year=2025,
    month=9,
    holidays=[],
    vacation_days=[10, 15, 5]
)

# Configure constraints
scheduler.enable_constraint('fair_distribution', True)
scheduler.enable_constraint('ramadan_shifts', True)

# Solve
solution = scheduler.solve()
```

#### `SolutionFormatPrinter`
Formats and displays scheduling solutions.

```python
from modular_scheduling import SolutionFormatPrinter

printer = SolutionFormatPrinter(solution, employees, year, month)
printer.print_solution()
printer.export_to_file('schedule.txt')
```

### Main Function

#### `run_modular_scheduling_algorithm()`
High-level function for quick scheduling.

```python
from modular_scheduling import run_modular_scheduling_algorithm

result = run_modular_scheduling_algorithm(
    employees=['Alice', 'Bob'],
    employee_types=['E', 'B'],
    year=2025,
    month=9,
    holidays=[(1, 1), (25, 12)],  # (day, month) tuples
    vacation_days=[10, 5],
    constraint_config={
        'enable_ramadan_shifts': True,
        'enable_fair_distribution': True,
        'enable_expert_supervision': True
    }
)
```

### Available Constraints

All constraints are modular and can be enabled/disabled:

- `one_shift_per_day`: Ensures one shift per employee per day
- `expert_supervision`: Requires expert supervision for beginners
- `fair_distribution`: Balances workload distribution
- `evening_night_rest`: Rest period between evening and night shifts
- `contiguous_shifts_limit`: Limits consecutive working days
- `vacation_based_off_days`: Off-days based on vacation balance
- `holiday_shifts`: Special holiday shift requirements
- `weekend_shifts`: Weekend coverage requirements
- `ramadan_shifts`: Special Ramadan shift patterns

---

## 📦 Installation Options

### Standard Installation
```bash
pip install modular-noc-scheduling
```

### With Optional Dependencies
```bash
# For UI components (if available)
pip install modular-noc-scheduling[ui]

# For development
pip install modular-noc-scheduling[dev]

# For documentation
pip install modular-noc-scheduling[docs]
```

### From Source
```bash
git clone https://github.com/abdalkarimnael/scheduling_package.git
cd scheduling_package
pip install -e .
```

---

## 🤝 Contributing

We welcome contributions! Here's how to get started:

### Development Setup
```bash
# Clone the repository
git clone https://github.com/abdalkarimnael/scheduling_package.git
cd scheduling_package

# Install in development mode
pip install -e .[dev]

# Install pre-commit hooks
pre-commit install
```

### Running Tests
```bash
pytest tests/
```

### Code Style
We use Black for code formatting:
```bash
black modular_scheduling/
```

### Submitting Changes
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🆘 Support

- **Documentation**: [GitHub Repository](https://github.com/abdalkarimnael/scheduling_package)
- **Issues**: [Report bugs or request features](https://github.com/abdalkarimnael/scheduling_package/issues)
- **PyPI Package**: [modular-noc-scheduling](https://pypi.org/project/modular-noc-scheduling/)

---

## 🏷️ Version History

- **v1.0.1** - Enhanced documentation and installation instructions
- **v1.0.0** - Initial release with core scheduling functionality

---

**Made with ❤️ by the Innovation Team - Digital Transformation**

3. **Off-Days Distribution** (`off_days_distribution_YYYY_MM_timestamp.txt`)
   - Detailed vacation day calculations and allocations
   - Fairness metrics and distribution analysis

4. **Calendar Information** (`month_calendar_info_YYYY_MM_timestamp.txt`)
   - Holiday identification and weekend classification
   - Ramadan period calculations and special day markings

### Dependencies and Requirements
- **OR-Tools**: Advanced optimization library by Google
- **Hijri-Converter**: Islamic calendar calculations
- **Streamlit**: Web interface framework
- **Pandas**: Data processing and display

### Performance Considerations
- **Small teams** (5-10 people): Solutions in seconds
- **Medium teams** (10-20 people): Solutions in 1-3 minutes
- **Large teams** (20+ people): May require 5-10 minutes
- **Complex constraints**: Increase processing time

### Data Privacy and Security
- No employee data is stored permanently
- All processing happens locally or on your secure servers
- Generated schedules can be exported and deleted from the algorithm
- No external data transmission required

### Customization Options

**Available Rule Modifications**
- Minimum number of people per shift
- Maximum consecutive working days
- Weekend/holiday distribution preferences
- Vacation day calculation methods
- Rest day requirements

**Advanced Configurations**
- Shift timing adjustments
- Employee skill level definitions
- Holiday calendar modifications
- Reporting format customizations

### Version Information
- **Current Version**: 1.0.0 (Modular Architecture)
- **Developer**: Innovation Team - Digital Transformation Directorate
- **License**: Proprietary software for organizational use

### Support and Maintenance
- Regular updates to improve performance and add features
- Technical support available through your IT department
- User training sessions can be arranged
- Documentation updates provided with new releases

---

*This guide covers the complete functionality of the NOC Scheduling Algorithm. For technical support or advanced customization requests, please contact your IT department or algorithm administrator.*

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "modular-noc-scheduling",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "Innovation Team - Digital Transformation <contact@example.com>",
    "keywords": "scheduling, optimization, constraint-programming, ortools, employee-scheduling, shift-scheduling, noc-scheduling, ramadan-scheduling, holiday-scheduling, workforce-management",
    "author": "Innovation Team - Digital Transformation",
    "author_email": "Innovation Team - Digital Transformation <contact@example.com>",
    "download_url": null,
    "platform": null,
    "description": "# Modular NOC Scheduling System\r\n\r\n[![PyPI version](https://badge.fury.io/py/modular-noc-scheduling.svg)](https://badge.fury.io/py/modular-noc-scheduling)\r\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n\r\nA comprehensive and intelligent employee scheduling system designed specifically for Network Operations Centers (NOC) and similar 24/7 operations. Built with advanced constraint programming using Google OR-Tools, this system ensures fair, efficient, and culturally-aware work schedules.\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Installation\r\n\r\nInstall the package from PyPI:\r\n\r\n```bash\r\npip install modular-noc-scheduling\r\n```\r\n\r\n### Basic Usage\r\n\r\n#### Python API\r\n```python\r\nfrom modular_scheduling import ModularNOCScheduler, run_modular_scheduling_algorithm\r\n\r\n# Quick start with default settings\r\nresult = run_modular_scheduling_algorithm(\r\n    employees=['Alice', 'Bob', 'Charlie'],\r\n    employee_types=['E', 'E', 'B'],  # E=Expert, B=Beginner\r\n    year=2025,\r\n    month=9\r\n)\r\n\r\n# Print the generated schedule\r\nprint(result)\r\n```\r\n\r\n#### Command Line Interface\r\n```bash\r\n# Run the interactive scheduling tool\r\nmodular-scheduling\r\n\r\n# Or with parameters\r\nmodular-scheduling --year 2025 --month 9 --employees \"Alice,Bob,Charlie\"\r\n```\r\n\r\n### Key Features at a Glance\r\n\r\n- \u2705 **24/7 Shift Coverage**: Morning, Evening, Night shifts\r\n- \u2705 **Cultural Awareness**: Special Ramadan scheduling\r\n- \u2705 **Expert Supervision**: Automatic beginner-expert pairing\r\n- \u2705 **Fair Distribution**: Balanced workload across team members\r\n- \u2705 **Holiday Management**: Intelligent holiday and weekend coverage\r\n- \u2705 **Constraint-Based**: Uses advanced optimization algorithms\r\n- \u2705 **Modular Design**: Easy to extend and customize\r\n\r\n## \ud83d\udccb Table of Contents\r\n1. [Installation & Quick Start](#-quick-start)\r\n2. [What is This Algorithm?](#what-is-this-algorithm)\r\n3. [Who Should Use This Guide?](#who-should-use-this-guide)\r\n4. [Key Features](#key-features)\r\n5. [Understanding the Basics](#understanding-the-basics)\r\n6. [How to Use the Algorithm](#how-to-use-the-algorithm)\r\n7. [Understanding the Schedule Output](#understanding-the-schedule-output)\r\n8. [Common Scenarios and Solutions](#common-scenarios-and-solutions)\r\n9. [Troubleshooting](#troubleshooting)\r\n10. [Technical Information](#technical-information)\r\n11. [API Reference](#api-reference)\r\n12. [Contributing](#contributing)\r\n\r\n---\r\n\r\n## What is This Algorithm?\r\n\r\nThe **Modular NOC Scheduling System** is an intelligent software tool designed to automatically create work schedules for Network Operations Center (NOC) teams. Think of it as a smart assistant that considers all your workplace rules, employee availability, holidays, and cultural requirements to generate fair and efficient work schedules.\r\n\r\n### What Makes It Special?\r\n- **Intelligent**: Uses advanced algorithms to solve complex scheduling puzzles\r\n- **Fair**: Ensures equal distribution of workload among team members\r\n- **Cultural-Aware**: Handles special requirements during Ramadan\r\n- **Flexible**: Adapts to different team sizes and requirements\r\n- **Reliable**: Guarantees all shifts are properly covered with qualified staff\r\n\r\n---\r\n\r\n## Who Should Use This Guide?\r\n\r\nThis guide is designed for:\r\n- **Team Managers**: Who need to create monthly schedules\r\n- **HR Personnel**: Responsible for workforce planning\r\n- **Supervisors**: Who monitor shift coverage and fairness\r\n- **Non-Technical Users**: Who want to understand how the algorithm works\r\n\r\n**No programming knowledge required!** This guide explains everything in simple terms.\r\n\r\n---\r\n\r\n## Key Features\r\n\r\n### \ud83d\udd50 Multiple Shift Types\r\n- **Morning Shifts (M)**: Regular daytime work\r\n- **Evening Shifts (E)**: Afternoon/evening coverage\r\n- **Night Shifts (N)**: Overnight operations\r\n- **Ramadan Shifts**: Special shifts during the holy month with adjusted timings\r\n\r\n### \ud83c\udfd6\ufe0f Holiday & Weekend Management\r\n- Automatic holiday detection from your calendar\r\n- Special holiday shifts with premium staffing\r\n- Weekend coverage ensuring business continuity\r\n- Regional calendar support (Hijri and Gregorian)\r\n\r\n### \ud83d\udc65 Smart Team Management\r\n- **Expert vs. Beginner** classification\r\n- Automatic supervision pairing (beginners always work with experts)\r\n- Fair workload distribution based on experience levels\r\n- Vacation balance consideration for off-day allocation\r\n\r\n### \u2696\ufe0f Fairness Guarantees\r\n- Equal distribution of weekend and holiday work\r\n- Balanced shift assignments over time\r\n- Consideration of remaining vacation days\r\n- Prevention of excessive consecutive shifts\r\n\r\n### \ud83d\udd27 Customizable Rules\r\n- Enable/disable specific scheduling rules as needed\r\n- Adapt to your organization's unique requirements\r\n- Easy modification without technical expertise\r\n\r\n---\r\n\r\n## Understanding the Basics\r\n\r\n### Employee Types\r\nThe algorithm recognizes two types of employees:\r\n\r\n**Experts (E)**\r\n- Experienced team members who can work independently\r\n- Can supervise and guide beginners\r\n\r\n**Beginners (B)**\r\n- Newer team members requiring supervision\r\n- Must always work alongside at least one expert\r\n\r\n### Shift Categories\r\n\r\n**Normal Days**\r\n- **M (Morning)**: Standard day shift\r\n- **E (Evening)**: Standard evening shift  \r\n- **N (Night)**: Standard night shift\r\n\r\n**Ramadan Days** (Special cultural/religious period)\r\n- **MR (Morning Ramadan)**: Adjusted morning hours\r\n- **E1R (Evening 1 Ramadan)**: First evening shift with special timing\r\n- **E2R (Evening 2 Ramadan)**: Second evening shift with special timing\r\n- **NR (Night Ramadan)**: Night shift with special considerations\r\n\r\n**Holiday Variants**\r\n- All shift types get an \"H\" prefix on holidays (e.g., HM, HE, HN)\r\n- Holiday shifts may have different staffing requirements\r\n\r\n**Special States**\r\n- **OFF**: Scheduled day off\r\n- **No Shift Assigned - Rest**: Mandatory rest day (cannot be changed)\r\n\r\n### Calendar Integration\r\nThe algorithm automatically identifies:\r\n- **Weekdays**: Sunday through Thursday (normal work days)\r\n- **Weekends**: Friday and Saturday (require special coverage)\r\n- **Holidays**: National and religious holidays from your calendar\r\n- **Ramadan Period**: Automatically calculated based on Islamic calendar\r\n\r\n---\r\n\r\n## How to Use the Algorithm\r\n\r\n### Installation\r\n\r\nBefore using the algorithm, you need to install the package and its dependencies.\r\n\r\n#### Method 1: Install from Source (Recommended)\r\n\r\n**Prerequisites:**\r\n- Python 3.8 or higher\r\n- pip (Python package installer)\r\n\r\n**Installation Steps:**\r\n\r\n1. **Navigate to the Package Directory**\r\n   ```bash\r\n   # Navigate to the scheduling_package directory\r\n   cd c:\\Projects\\scheduling_package\r\n   ```\r\n\r\n2. **Install the Package**\r\n   ```bash\r\n   # Install in development mode (recommended for customization)\r\n   pip install -e .\r\n   \r\n   # Or install normally\r\n   pip install .\r\n   ```\r\n\r\n3. **Verify Installation**\r\n   ```bash\r\n   # Test the command-line interface\r\n   modular-scheduling --help\r\n   \r\n   # Note: The web UI (scheduling-ui) requires additional setup\r\n   # See Method 3 below for web interface setup\r\n   ```\r\n\r\n#### Method 2: Run Directly Without Package Installation\r\n\r\nIf you prefer to run the algorithm directly from source without installing the package:\r\n\r\n```bash\r\n# First, install only the required dependencies manually\r\npip install ortools>=9.0.0 hijri-converter>=2.2.4 streamlit>=1.28.0 pandas>=1.5.0 numpy>=1.21.0 typing-extensions>=4.0.0\r\n\r\n# Then navigate to the package directory and run directly\r\ncd c:\\Projects\\scheduling_package\\modular_scheduling\r\npython modular_scheduler.py --help\r\n```\r\n\r\n**Note**: When you use Method 1 (`pip install .` or `pip install -e .`), all dependencies are automatically installed from the package's `setup.py` configuration, so you don't need to install them manually.\r\n\r\n#### Method 3: Web Interface Setup (Optional)\r\n\r\nFor the web-based interface, you need to copy the UI module from the main OR-Tools project:\r\n\r\n```bash\r\n# Copy the web UI module from the main project\r\ncopy \"c:\\Projects\\OR-Tools\\Real Projects\\modular_scheduling\\modular_ui.py\" \"c:\\Projects\\scheduling_package\\modular_scheduling\\\"\r\n\r\n# Then install the package with the UI\r\npip install -e .\r\n\r\n# Now you can use the web interface\r\nscheduling-ui\r\n```\r\n\r\n#### Development Installation (For Developers)\r\n\r\nIf you plan to modify or contribute to the algorithm:\r\n\r\n```bash\r\npip install -e .\r\n# Install with development dependencies\r\npip install -e \".[dev]\"\r\n\r\n# Install with documentation dependencies  \r\npip install -e \".[docs]\"\r\n\r\n# Install with all optional dependencies\r\npip install -e \".[dev,docs]\"\r\n```\r\n\r\n**Windows Notes:**\r\n- If you encounter issues with OR-Tools installation, you might need Microsoft Visual C++ 14.0 or greater\r\n- Use PowerShell or Command Prompt as Administrator if you get permission errors\r\n- On some Windows systems, you may need to use `python -m pip` instead of just `pip`\r\n\r\n### Quick Start\r\n\r\nOnce installed, you can run the algorithm in several ways:\r\n\r\n**Option 1: Command Line (Always Available)**\r\n```bash\r\n# Run the scheduling algorithm directly\r\nmodular-scheduling --help\r\n\r\n# Or run directly from source\r\npython c:\\Projects\\scheduling_package\\modular_scheduling\\modular_scheduler.py --help\r\n```\r\n\r\n**Option 2: Web Interface (If UI Module is Set Up)**\r\n```bash\r\n# Launch the web-based user interface (requires Method 3 installation above)\r\nscheduling-ui\r\n```\r\nThis will start a local web server and open the algorithm interface in your browser.\r\n\r\n**Option 3: Direct Python Import**\r\n```python\r\n# For programmatic use in your own Python scripts\r\nfrom modular_scheduling.modular_scheduler import main\r\n# Your code here\r\n```\r\n\r\n**Getting Started Quickly:**\r\n\r\n**Easiest Method (Automatic Dependencies):**\r\n1. Navigate to package: `cd c:\\Projects\\scheduling_package`\r\n2. Install with dependencies: `pip install -e .`\r\n3. Run: `modular-scheduling --help`\r\n\r\n**Manual Method (If you prefer not to install the package):**\r\n1. Install dependencies manually: `pip install ortools hijri-converter streamlit pandas numpy typing-extensions`\r\n2. Navigate to: `cd c:\\Projects\\scheduling_package\\modular_scheduling`\r\n3. Run: `python modular_scheduler.py --help`\r\n\r\n---\r\n\r\n### Method 1: Web Interface (Recommended for Most Users)\r\n\r\n**Step 1: Launch the Algorithm**\r\n1. Open your web browser\r\n2. Navigate to the algorithm URL (provided by your IT team)\r\n3. You'll see a user-friendly interface with clear sections\r\n\r\n**Step 2: Enter Basic Information**\r\n- **Year and Month**: Select the period you want to schedule\r\n- **Team Size**: The algorithm will ask how many employees to schedule\r\n\r\n**Step 3: Add Employee Information**\r\nFor each team member, provide:\r\n- **Employee Type**: Expert or Beginner\r\n- **Remaining Vacation Days**: How many vacation days they have left\r\n\r\n**Step 4: Upload Holiday Calendar (Optional)**\r\n- If you have a special holiday file, upload it\r\n\r\n**Step 5: Configure Rules (Advanced)**\r\nMost users can skip this section, but you can:\r\n- Enable/disable specific scheduling rules\r\n- Adjust minimum shift requirements\r\n- Modify fairness settings\r\n\r\n**Step 6: Generate Schedule**\r\n- Click \"Generate Schedule\"\r\n- Wait for the algorithm to process (maybe take afew seconds)\r\n- Review the generated schedule\r\n\r\n### Method 2: File-Based Input\r\n\r\nIf your organization prefers file-based processes:\r\n1. Prepare an employee data file with required information\r\n2. Ensure holiday calendar is in the correct format\r\n3. Run the algorithm with these files as input\r\n\r\n---\r\n\r\n## Understanding the Schedule Output\r\n\r\n### Reading the Schedule\r\n\r\nThe algorithm generates a calendar-style schedule showing:\r\n- **Rows**: Each day of the month\r\n- **Columns**: Each team member\r\n- **Cells**: Assigned shift or status for each person each day\r\n\r\n### Color Coding (Web Interface)\r\n- **Blue**: Normal shifts (M, E, N)\r\n- **Green**: Ramadan shifts (MR, E1R, E2R, NR)\r\n- **Red**: Holiday shifts (HM, HE, HN, etc.)\r\n- **Gray**: Off days\r\n- **White**: Rest days (mandatory)\r\n\r\n### Schedule Statistics\r\nThe algorithm provides helpful statistics:\r\n- **Total shifts per employee**: Ensuring fairness\r\n- **Weekend/Holiday distribution**: Showing equal sharing\r\n- **Shift type distribution**: Balanced assignment patterns\r\n- **Overtime indicators**: If someone exceeds normal limits\r\n\r\n### Generated Files\r\nThe algorithm creates several detailed reports:\r\n\r\n**1. Input Summary**\r\n- All the parameters you entered\r\n- Which rules were enabled/disabled\r\n- Team composition details\r\n\r\n**2. Schedule Solution**\r\n- Complete day-by-day assignments\r\n- Easy-to-read format for printing or sharing\r\n\r\n**3. Off-Days Distribution**\r\n- Calculation details for vacation day allocation\r\n- Fairness metrics and explanations\r\n\r\n**4. Calendar Information**\r\n- Holiday and weekend identification\r\n- Ramadan period calculations\r\n\r\n---\r\n\r\n## Common Scenarios and Solutions\r\n\r\n### Scenario 1: \"The Algorithm Says No Solution Found\"\r\n**What this means**: Your requirements cannot be met with the current team size or constraints.\r\n\r\n**Solutions**:\r\n- Add more team members\r\n- Reduce minimum shift requirements\r\n- Check if vacation day allocations are realistic\r\n\r\n### Scenario 2: \"Someone Has Too Many Shifts\"\r\n**What this means**: The workload distribution isn't perfectly even.\r\n\r\n**Solutions**:\r\n- Enable the \"Fair Distribution\" constraints\r\n- Increase the solution search time\r\n- Consider if the person has fewer vacation days (affecting their off-day allocation)\r\n\r\n### Scenario 3: \"Weekend Coverage Looks Uneven\"\r\n**What this means**: Some people work more weekends than others.\r\n\r\n**Solutions**:\r\n- Ensure \"Fair Weekend Distribution\" is enabled\r\n- Check that you have enough team members for weekend coverage\r\n- Consider the impact of vacation day differences\r\n\r\n### Scenario 4: \"Ramadan Shifts Aren't Working\"\r\n**What this means**: The algorithm can't properly assign special Ramadan shifts.\r\n\r\n**Solutions**:\r\n- Verify the Ramadan period is correctly calculated\r\n- Ensure you have enough experts for supervision during Ramadan\r\n- Check that Ramadan-specific constraints are enabled\r\n\r\n### Scenario 5: \"Holiday Coverage Is Missing\"\r\n**What this means**: Some holidays don't have proper shift coverage.\r\n\r\n**Solutions**:\r\n- Upload a complete holiday calendar file\r\n- Enable holiday shift constraints\r\n- Ensure minimum holiday staffing requirements are met\r\n\r\n---\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues and Quick Fixes\r\n\r\n**Issue**: Algorithm is very slow\r\n- **Solution**: Reduce the number of solutions requested, try with fewer constraints enabled\r\n\r\n**Issue**: Schedule looks unfair\r\n- **Solution**: Enable all fairness constraints\r\n\r\n**Issue**: Beginners are working alone\r\n- **Solution**: Ensure \"Expert Supervision\" constraint is enabled, check expert-to-beginner ratio\r\n\r\n**Issue**: Too many consecutive work days\r\n- **Solution**: Enable \"Limit Contiguous Shifts\" constraint, adjust maximum consecutive days\r\n\r\n**Issue**: Off days don't match vacation entitlements\r\n- **Solution**: Verify vacation day numbers are correct, enable vacation-based off-day constraints\r\n\r\n### When to Contact Support\r\nContact your IT team if:\r\n- The algorithm doesn't load or crashes\r\n- You get error messages you don't understand\r\n- The schedule results seem completely wrong\r\n- You need to modify algorithm rules or constraints\r\n\r\n---\r\n\r\n## Technical Information\r\n\r\n### Algorithm Architecture\r\n\r\n**Core Components**\r\n- **Scheduler Engine**: Uses Google OR-Tools constraint programming\r\n- **Web Interface**: Built with Streamlit for easy use\r\n- **Constraint Algorithm**: Modular rules that can be enabled/disabled\r\n- **Calendar Integration**: Supports both Gregorian and Hijri calendars\r\n\r\n**How It Works**\r\n1. **Input Processing**: Algorithm converts your requirements into mathematical constraints\r\n2. **Optimization**: Advanced algorithms find the best schedule that satisfies all rules\r\n3. **Solution Generation**: Multiple valid schedules may be found\r\n4. **Output Formatting**: Results are presented in user-friendly formats\r\n\r\n### Constraint Categories\r\n\r\n**Coverage Constraints**\r\n- Ensure all shifts have adequate staffing\r\n- Guarantee weekend and holiday coverage\r\n- Maintain 24/7 operations continuity\r\n\r\n**Fairness Constraints**\r\n- Equal distribution of workload\r\n- Balanced weekend/holiday assignments\r\n- Fair vacation day consideration\r\n\r\n**Safety Constraints**\r\n- Expert supervision for beginners\r\n- Mandatory rest after certain shift sequences\r\n- Limits on consecutive working days\r\n\r\n**Cultural Constraints**\r\n- Special Ramadan shift patterns\r\n- Regional holiday observances\r\n- Cultural work week conventions\r\n\r\n### File Formats\r\n\r\n**Employee Data Input**\r\nEmployee information is entered through the web interface with the following parameters:\r\n- **Employee Type**: `EXPERT` or `BEGINNER`\r\n- **Vacation Days**: Integer value (0-21 for experts, 0-14 for beginners)\r\n\r\nNo separate employee data file is required - all input is handled through the interactive web interface.\r\n\r\n**Holiday File Format**\r\nUpload a text file (.txt) with holidays using this exact format:\r\n```\r\nday; month; description\r\n1; 1; New Year's Day\r\n15; 8; Independence Day\r\n25; 12; Christmas Day\r\n```\r\n\r\nFormat requirements:\r\n- Each line contains: `day; month; description`\r\n- Semicolon (`;`) separated values\r\n- Day and month as integers (e.g., 1-31 for day, 1-12 for month)\r\n- Description is optional but recommended for clarity\r\n- Lines starting with \"day\" are treated as headers and ignored\r\n- Empty lines are ignored\r\n- File encoding: UTF-8\r\n\r\n**Generated Output Files**\r\nThe algorithm automatically creates several output files with structured formats:\r\n\r\n1. **Input Summary** (`input_summary_YYYY_MM_timestamp.txt`)\r\n   - Contains all input parameters and constraint settings\r\n   - Employee details and configuration used\r\n\r\n2. **Solution File** (`solution_YYYY_MM_timestamp_sol1.txt`)\r\n   - Complete day-by-day schedule assignments\r\n   - Employee-day-shift mappings in readable format\r\n\r\n---\r\n\r\n## \ud83d\udd27 API Reference\r\n\r\n### Core Classes\r\n\r\n#### `ModularNOCScheduler`\r\nMain scheduler class with modular constraint architecture.\r\n\r\n```python\r\nfrom modular_scheduling import ModularNOCScheduler\r\n\r\nscheduler = ModularNOCScheduler(\r\n    employees=['Alice', 'Bob', 'Charlie'],\r\n    employee_types=['E', 'E', 'B'],\r\n    year=2025,\r\n    month=9,\r\n    holidays=[],\r\n    vacation_days=[10, 15, 5]\r\n)\r\n\r\n# Configure constraints\r\nscheduler.enable_constraint('fair_distribution', True)\r\nscheduler.enable_constraint('ramadan_shifts', True)\r\n\r\n# Solve\r\nsolution = scheduler.solve()\r\n```\r\n\r\n#### `SolutionFormatPrinter`\r\nFormats and displays scheduling solutions.\r\n\r\n```python\r\nfrom modular_scheduling import SolutionFormatPrinter\r\n\r\nprinter = SolutionFormatPrinter(solution, employees, year, month)\r\nprinter.print_solution()\r\nprinter.export_to_file('schedule.txt')\r\n```\r\n\r\n### Main Function\r\n\r\n#### `run_modular_scheduling_algorithm()`\r\nHigh-level function for quick scheduling.\r\n\r\n```python\r\nfrom modular_scheduling import run_modular_scheduling_algorithm\r\n\r\nresult = run_modular_scheduling_algorithm(\r\n    employees=['Alice', 'Bob'],\r\n    employee_types=['E', 'B'],\r\n    year=2025,\r\n    month=9,\r\n    holidays=[(1, 1), (25, 12)],  # (day, month) tuples\r\n    vacation_days=[10, 5],\r\n    constraint_config={\r\n        'enable_ramadan_shifts': True,\r\n        'enable_fair_distribution': True,\r\n        'enable_expert_supervision': True\r\n    }\r\n)\r\n```\r\n\r\n### Available Constraints\r\n\r\nAll constraints are modular and can be enabled/disabled:\r\n\r\n- `one_shift_per_day`: Ensures one shift per employee per day\r\n- `expert_supervision`: Requires expert supervision for beginners\r\n- `fair_distribution`: Balances workload distribution\r\n- `evening_night_rest`: Rest period between evening and night shifts\r\n- `contiguous_shifts_limit`: Limits consecutive working days\r\n- `vacation_based_off_days`: Off-days based on vacation balance\r\n- `holiday_shifts`: Special holiday shift requirements\r\n- `weekend_shifts`: Weekend coverage requirements\r\n- `ramadan_shifts`: Special Ramadan shift patterns\r\n\r\n---\r\n\r\n## \ud83d\udce6 Installation Options\r\n\r\n### Standard Installation\r\n```bash\r\npip install modular-noc-scheduling\r\n```\r\n\r\n### With Optional Dependencies\r\n```bash\r\n# For UI components (if available)\r\npip install modular-noc-scheduling[ui]\r\n\r\n# For development\r\npip install modular-noc-scheduling[dev]\r\n\r\n# For documentation\r\npip install modular-noc-scheduling[docs]\r\n```\r\n\r\n### From Source\r\n```bash\r\ngit clone https://github.com/abdalkarimnael/scheduling_package.git\r\ncd scheduling_package\r\npip install -e .\r\n```\r\n\r\n---\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! Here's how to get started:\r\n\r\n### Development Setup\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/abdalkarimnael/scheduling_package.git\r\ncd scheduling_package\r\n\r\n# Install in development mode\r\npip install -e .[dev]\r\n\r\n# Install pre-commit hooks\r\npre-commit install\r\n```\r\n\r\n### Running Tests\r\n```bash\r\npytest tests/\r\n```\r\n\r\n### Code Style\r\nWe use Black for code formatting:\r\n```bash\r\nblack modular_scheduling/\r\n```\r\n\r\n### Submitting Changes\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\r\n4. Push to the branch (`git push origin feature/amazing-feature`)\r\n5. Open a Pull Request\r\n\r\n---\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n---\r\n\r\n## \ud83c\udd98 Support\r\n\r\n- **Documentation**: [GitHub Repository](https://github.com/abdalkarimnael/scheduling_package)\r\n- **Issues**: [Report bugs or request features](https://github.com/abdalkarimnael/scheduling_package/issues)\r\n- **PyPI Package**: [modular-noc-scheduling](https://pypi.org/project/modular-noc-scheduling/)\r\n\r\n---\r\n\r\n## \ud83c\udff7\ufe0f Version History\r\n\r\n- **v1.0.1** - Enhanced documentation and installation instructions\r\n- **v1.0.0** - Initial release with core scheduling functionality\r\n\r\n---\r\n\r\n**Made with \u2764\ufe0f by the Innovation Team - Digital Transformation**\r\n\r\n3. **Off-Days Distribution** (`off_days_distribution_YYYY_MM_timestamp.txt`)\r\n   - Detailed vacation day calculations and allocations\r\n   - Fairness metrics and distribution analysis\r\n\r\n4. **Calendar Information** (`month_calendar_info_YYYY_MM_timestamp.txt`)\r\n   - Holiday identification and weekend classification\r\n   - Ramadan period calculations and special day markings\r\n\r\n### Dependencies and Requirements\r\n- **OR-Tools**: Advanced optimization library by Google\r\n- **Hijri-Converter**: Islamic calendar calculations\r\n- **Streamlit**: Web interface framework\r\n- **Pandas**: Data processing and display\r\n\r\n### Performance Considerations\r\n- **Small teams** (5-10 people): Solutions in seconds\r\n- **Medium teams** (10-20 people): Solutions in 1-3 minutes\r\n- **Large teams** (20+ people): May require 5-10 minutes\r\n- **Complex constraints**: Increase processing time\r\n\r\n### Data Privacy and Security\r\n- No employee data is stored permanently\r\n- All processing happens locally or on your secure servers\r\n- Generated schedules can be exported and deleted from the algorithm\r\n- No external data transmission required\r\n\r\n### Customization Options\r\n\r\n**Available Rule Modifications**\r\n- Minimum number of people per shift\r\n- Maximum consecutive working days\r\n- Weekend/holiday distribution preferences\r\n- Vacation day calculation methods\r\n- Rest day requirements\r\n\r\n**Advanced Configurations**\r\n- Shift timing adjustments\r\n- Employee skill level definitions\r\n- Holiday calendar modifications\r\n- Reporting format customizations\r\n\r\n### Version Information\r\n- **Current Version**: 1.0.0 (Modular Architecture)\r\n- **Developer**: Innovation Team - Digital Transformation Directorate\r\n- **License**: Proprietary software for organizational use\r\n\r\n### Support and Maintenance\r\n- Regular updates to improve performance and add features\r\n- Technical support available through your IT department\r\n- User training sessions can be arranged\r\n- Documentation updates provided with new releases\r\n\r\n---\r\n\r\n*This guide covers the complete functionality of the NOC Scheduling Algorithm. For technical support or advanced customization requests, please contact your IT department or algorithm administrator.*\r\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Shift Scheduling Algorithm using OR-Tools with Modular Constraints",
    "version": "1.0.3",
    "project_urls": {
        "Bug Reports": "https://github.com/abdalkarimnael/scheduling_package/issues",
        "Documentation": "https://github.com/abdalkarimnael/scheduling_package#readme",
        "Homepage": "https://github.com/abdalkarimnael/scheduling_package",
        "Repository": "https://github.com/abdalkarimnael/scheduling_package"
    },
    "split_keywords": [
        "scheduling",
        " optimization",
        " constraint-programming",
        " ortools",
        " employee-scheduling",
        " shift-scheduling",
        " noc-scheduling",
        " ramadan-scheduling",
        " holiday-scheduling",
        " workforce-management"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "a9fcd07921e4ec9f8eb534666e1f81b362be7f2d012a0db6f303ce07fecd89dd",
                "md5": "c1bb99a9ee03d5747e8d2d921a45f00d",
                "sha256": "21b3ca2b8b4ab5d2575c11203334b2c24e67080daca795c7386179d0805eb2ae"
            },
            "downloads": -1,
            "filename": "modular_noc_scheduling-1.0.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "c1bb99a9ee03d5747e8d2d921a45f00d",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 496019,
            "upload_time": "2025-08-21T12:28:42",
            "upload_time_iso_8601": "2025-08-21T12:28:42.083203Z",
            "url": "https://files.pythonhosted.org/packages/a9/fc/d07921e4ec9f8eb534666e1f81b362be7f2d012a0db6f303ce07fecd89dd/modular_noc_scheduling-1.0.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-21 12:28:42",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "abdalkarimnael",
    "github_project": "scheduling_package",
    "github_not_found": true,
    "lcname": "modular-noc-scheduling"
}