The Unexpected the in demand of mentorship and salary negotiation: What Matters

import csv
import datetime
from typing import List, Dict, Optional
import logging

# Configure logging for audit trails
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s",
    handlers=[logging.FileHandler("mentorship_tracker.log"), logging.StreamHandler()]
)

class Mentee:
    """Represents a mentee with progress tracking metrics"""
    def __init__(self, id: str, start_date: datetime.date, stack: str):
        self.id = id
        self.start_date = start_date
        self.stack = stack
        self.milestones: List[str] = []
        self.feedback_scores: List[int] = []  # 1-5 scale
        self.last_checkin: Optional[datetime.date] = None

    def add_milestone(self, milestone: str) -> None:
        """Log a completed milestone for the mentee"""
        if not milestone.strip():
            logging.error(f"Empty milestone provided for mentee {self.id}")
            return
        self.milestones.append(milestone)
        logging.info(f"Mentee {self.id} completed milestone: {milestone}")

    def add_feedback(self, score: int) -> None:
        """Record mentee feedback score, validate range"""
        if not 1 <= score <= 5:
            logging.error(f"Invalid feedback score {score} for mentee {self.id}, must be 1-5")
            return
        self.feedback_scores.append(score)

    def update_checkin(self) -> None:
        """Update last checkin date to today"""
        self.last_checkin = datetime.date.today()
        logging.info(f"Updated checkin for mentee {self.id} to {self.last_checkin}")

class MentorshipTracker:
    """Tracks mentorship ROI and generates reports"""
    def __init__(self, mentor_id: str):
        self.mentor_id = mentor_id
        self.mentees: List[Mentee] = []
        self.total_hours_invested: float = 0.0

    def add_mentee(self, mentee: Mentee) -> None:
        """Add a new mentee to the tracker"""
        self.mentees.append(mentee)
        logging.info(f"Added mentee {mentee.id} to mentor {self.mentor_id}'s tracker")

    def log_hours(self, hours: float) -> None:
        """Log time invested in mentorship"""
        if hours <= 0:
            logging.error(f"Invalid hours logged: {hours}, must be positive")
            return
        self.total_hours_invested += hours
        logging.info(f"Logged {hours} hours for mentor {self.mentor_id}, total: {self.total_hours_invested}")

    def calculate_roi(self) -> Dict[str, float]:
        """Calculate mentorship ROI metrics: promotion rate, feedback avg, hours per mentee"""
        if not self.mentees:
            return {"promotion_rate": 0.0, "avg_feedback": 0.0, "hours_per_mentee": 0.0}

        promoted_count = sum(1 for m in self.mentees if "promotion" in [milestone.lower() for milestone in m.milestones])
        avg_feedback = sum(sum(m.feedback_scores) for m in self.mentees) / sum(len(m.feedback_scores) for m in self.mentees) if any(m.feedback_scores for m in self.mentees) else 0.0
        hours_per_mentee = self.total_hours_invested / len(self.mentees) if self.mentees else 0.0

        return {
            "promotion_rate": (promoted_count / len(self.mentees)) * 100,
            "avg_feedback": round(avg_feedback, 2),
            "hours_per_mentee": round(hours_per_mentee, 2)
        }

    def export_report(self, filename: str = "mentorship_report.csv") -> None:
        """Export mentorship data to CSV for HR/performance reviews"""
        try:
            with open(filename, "w", newline="") as f:
                writer = csv.writer(f)
                writer.writerow(["Mentor ID", "Mentee ID", "Start Date", "Stack", "Milestones", "Avg Feedback", "Last Checkin"])
                for mentee in self.mentees:
                    avg_feedback = sum(mentee.feedback_scores)/len(mentee.feedback_scores) if mentee.feedback_scores else 0.0
                    writer.writerow([
                        self.mentor_id,
                        mentee.id,
                        mentee.start_date.isoformat(),
                        mentee.stack,
                        "; ".join(mentee.milestones),
                        round(avg_feedback, 2),
                        mentee.last_checkin.isoformat() if mentee.last_checkin else "N/A"
                    ])
            logging.info(f"Exported mentorship report to {filename}")
        except IOError as e:
            logging.error(f"Failed to export report: {e}")
        except Exception as e:
            logging.error(f"Unexpected error exporting report: {e}")

if __name__ == "__main__":
    # Example usage: track mentorship for a senior backend engineer
    tracker = MentorshipTracker(mentor_id="eng_4921")

    # Add mentees
    mentee1 = Mentee(id="junior_782", start_date=datetime.date(2024, 1, 15), stack="Python/FastAPI")
    mentee1.add_milestone("Completed first production PR")
    mentee1.add_milestone("Led small feature rollout")
    mentee1.add_feedback(5)
    mentee1.update_checkin()

    mentee2 = Mentee(id="junior_901", start_date=datetime.date(2024, 3, 1), stack="Go/gRPC")
    mentee2.add_milestone("Fixed critical P0 latency bug")
    mentee2.add_feedback(4)
    mentee2.update_checkin()

    tracker.add_mentee(mentee1)
    tracker.add_mentee(mentee2)
    tracker.log_hours(12.5)
    tracker.log_hours(8.0)

    # Calculate and print ROI
    roi = tracker.calculate_roi()
    print(f"Mentorship ROI for {tracker.mentor_id}:")
    for key, value in roi.items():
        print(f"{key}: {value}")

    # Export report
    tracker.export_report()

import requests
import json
import time
from typing import Dict, List, Optional
import logging
from dataclasses import dataclass

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s"
)

@dataclass
class SalaryDataPoint:
    """Structured salary data from Levels.fyi"""
    company: str
    title: str
    years_experience: int
    base_salary: int
    total_comp: int
    location: str
    has_mentorship_experience: bool

class LevelsScraper:
    """Scrapes salary data from Levels.fyi with rate limiting and error handling"""
    BASE_URL = "https://www.levels.fyi/api/v2/salaryData"
    RATE_LIMIT_DELAY = 1.5  # Seconds between requests to avoid 429s

    def __init__(self, api_key: Optional[str] = None):
        self.api_key = api_key
        self.session = requests.Session()
        self.session.headers.update({
            "User-Agent": "SeniorEngineerBot/1.0 (contact: eng@example.com)",
            "Accept": "application/json"
        })
        if api_key:
            self.session.headers.update({"Authorization": f"Bearer {api_key}"})

    def _make_request(self, params: Dict) -> Optional[Dict]:
        """Make a rate-limited request with error handling"""
        try:
            response = self.session.get(self.BASE_URL, params=params, timeout=10)
            response.raise_for_status()
            time.sleep(self.RATE_LIMIT_DELAY)  # Respect rate limits
            return response.json()
        except requests.exceptions.HTTPError as e:
            logging.error(f"HTTP error fetching salary data: {e}")
            if response.status_code == 429:
                logging.warning("Rate limited, waiting 5 seconds")
                time.sleep(5)
                return self._make_request(params)  # Retry once
            return None
        except requests.exceptions.Timeout:
            logging.error("Request timed out fetching salary data")
            return None
        except requests.exceptions.RequestException as e:
            logging.error(f"Request failed: {e}")
            return None

    def fetch_salary_range(self, title: str, location: str, years_exp: int) -> List[SalaryDataPoint]:
        """Fetch salary data for a given title, location, and experience level"""
        params = {
            "title": title,
            "location": location,
            "yearsExperience": years_exp,
            "limit": 100  # Fetch up to 100 data points
        }

        raw_data = self._make_request(params)
        if not raw_data or "data" not in raw_data:
            logging.error(f"No salary data found for {title} in {location} with {years_exp} years exp")
            return []

        salary_points = []
        for entry in raw_data["data"]:
            try:
                # Parse mentorship experience from additional data field
                has_mentorship = False
                if "additionalData" in entry and entry["additionalData"]:
                    has_mentorship = "mentorship" in entry["additionalData"].lower() or "mentor" in entry["additionalData"].lower()

                point = SalaryDataPoint(
                    company=entry.get("company", "Unknown"),
                    title=entry.get("title", title),
                    years_experience=entry.get("yearsExperience", years_exp),
                    base_salary=entry.get("baseSalary", 0),
                    total_comp=entry.get("totalComp", 0),
                    location=entry.get("location", location),
                    has_mentorship_experience=has_mentorship
                )
                salary_points.append(point)
            except KeyError as e:
                logging.error(f"Missing key {e} in salary entry, skipping")
                continue
            except TypeError as e:
                logging.error(f"Invalid data type in salary entry: {e}, skipping")
                continue

        logging.info(f"Fetched {len(salary_points)} salary data points for {title} in {location}")
        return salary_points

    def calculate_negotiation_baseline(self, points: List[SalaryDataPoint]) -> Dict[str, float]:
        """Calculate 25th, 50th, 75th percentile total comp for negotiation baselines"""
        if not points:
            return {"p25": 0.0, "p50": 0.0, "p75": 0.0, "mentor_premium": 0.0}

        # Sort by total comp
        sorted_points = sorted(points, key=lambda x: x.total_comp)
        n = len(sorted_points)

        p25_idx = int(n * 0.25)
        p50_idx = int(n * 0.5)
        p75_idx = int(n * 0.75)

        # Calculate mentor premium: avg total comp for mentors vs non-mentors
        mentor_points = [p for p in points if p.has_mentorship_experience]
        non_mentor_points = [p for p in points if not p.has_mentorship_experience]

        avg_mentor = sum(p.total_comp for p in mentor_points) / len(mentor_points) if mentor_points else 0.0
        avg_non_mentor = sum(p.total_comp for p in non_mentor_points) / len(non_mentor_points) if non_mentor_points else 0.0
        mentor_premium = ((avg_mentor - avg_non_mentor) / avg_non_mentor) * 100 if avg_non_mentor > 0 else 0.0

        return {
            "p25": float(sorted_points[p25_idx].total_comp),
            "p50": float(sorted_points[p50_idx].total_comp),
            "p75": float(sorted_points[p75_idx].total_comp),
            "mentor_premium": round(mentor_premium, 2)
        }

if __name__ == "__main__":
    # Example: Fetch senior backend engineer salary data for SF, 8 years exp
    scraper = LevelsScraper()

    try:
        salary_points = scraper.fetch_salary_range(
            title="Senior Backend Engineer",
            location="San Francisco, CA",
            years_exp=8
        )

        if salary_points:
            baseline = scraper.calculate_negotiation_baseline(salary_points)
            print("Negotiation Baseline (Total Comp):")
            for key, value in baseline.items():
                if key == "mentor_premium":
                    print(f"{key}: {value}%")
                else:
                    print(f"{key}: ${value:,.0f}")

            # Save raw data to JSON for later analysis
            with open("salary_data.json", "w") as f:
                json.dump([vars(p) for p in salary_points], f, indent=2)
            logging.info("Saved raw salary data to salary_data.json")
        else:
            print("No salary data found.")
    except Exception as e:
        logging.error(f"Unexpected error in main: {e}")

interface MentorshipRecord {
    menteeId: string;
    startDate: Date;
    milestonesCompleted: number;
    feedbackScore: number; // 1-5
    hoursInvested: number;
}

interface PerformanceReview {
    id: string;
    employeeId: string;
    reviewPeriod: string;
    codeQualityScore: number; // 1-5
    systemDesignScore: number; // 1-5
    mentorshipRecords: MentorshipRecord[];
    currentLevel: string;
    targetLevel: string;
    yearsAtCompany: number;
}

interface PromotionEligibility {
    isEligible: boolean;
    gaps: string[];
    recommendedActions: string[];
    mentorshipBonus: number; // Percentage points added to eligibility score
}

class PromotionChecker {
    private readonly MENTORSHIP_WEIGHT = 0.3; // 30% of promotion score
    private readonly CODE_QUALITY_WEIGHT = 0.25;
    private readonly SYSTEM_DESIGN_WEIGHT = 0.25;
    private readonly TENURE_WEIGHT = 0.2;
    private readonly MIN_MENTORSHIP_HOURS = 20; // Minimum hours per review period
    private readonly MIN_MENTEES = 1; // Minimum mentees per review period

    /**
     * Check if an employee is eligible for promotion based on performance and mentorship
     */
    public checkEligibility(review: PerformanceReview): PromotionEligibility {
        const gaps: string[] = [];
        const recommendedActions: string[] = [];
        let score = 0;

        // Calculate code quality component
        const codeQualityScore = this.validateScore(review.codeQualityScore, "code quality");
        score += codeQualityScore * this.CODE_QUALITY_WEIGHT;

        // Calculate system design component
        const systemDesignScore = this.validateScore(review.systemDesignScore, "system design");
        score += systemDesignScore * this.SYSTEM_DESIGN_WEIGHT;

        // Calculate tenure component
        const tenureScore = Math.min(review.yearsAtCompany / 5, 1); // Max 1.0 for 5+ years
        score += tenureScore * this.TENURE_WEIGHT;

        // Calculate mentorship component
        const mentorshipResult = this.calculateMentorshipScore(review.mentorshipRecords);
        score += mentorshipResult.score * this.MENTORSHIP_WEIGHT;
        const mentorshipBonus = mentorshipResult.bonus;

        // Check eligibility threshold (0.8 or higher)
        const isEligible = score >= 0.8;

        // Identify gaps if not eligible
        if (!isEligible) {
            if (codeQualityScore < 0.8) {
                gaps.push(`Code quality score (${review.codeQualityScore}/5) below threshold`);
                recommendedActions.push("Complete 2 code quality workshops and lead 1 architecture review");
            }
            if (systemDesignScore < 0.8) {
                gaps.push(`System design score (${review.systemDesignScore}/5) below threshold`);
                recommendedActions.push("Design and document 1 production system with 99.9% uptime");
            }
            if (tenureScore < 0.6) {
                gaps.push(`Tenure (${review.yearsAtCompany} years) below recommended 3 years for promotion`);
                recommendedActions.push("Wait until next review cycle or take on cross-team lead role");
            }
            if (mentorshipResult.gaps.length > 0) {
                gaps.push(...mentorshipResult.gaps);
                recommendedActions.push(...mentorshipResult.recommendedActions);
            }
        }

        return {
            isEligible,
            gaps,
            recommendedActions,
            mentorshipBonus
        };
    }

    private validateScore(score: number, metric: string): number {
        if (score < 1 || score > 5) {
            throw new Error(`Invalid ${metric} score: ${score}. Must be between 1 and 5.`);
        }
        return score / 5; // Normalize to 0-1
    }

    private calculateMentorshipScore(records: MentorshipRecord[]): {
        score: number;
        bonus: number;
        gaps: string[];
        recommendedActions: string[];
    } {
        const gaps: string[] = [];
        const recommendedActions: string[] = [];
        let bonus = 0;

        // Check minimum mentees
        if (records.length < this.MIN_MENTEES) {
            gaps.push(`Only ${records.length} mentees, minimum ${this.MIN_MENTEES} required`);
            recommendedActions.push("Take on at least 1 new mentee in the next quarter");
        }

        // Check total hours
        const totalHours = records.reduce((sum, r) => sum + r.hoursInvested, 0);
        if (totalHours < this.MIN_MENTORSHIP_HOURS) {
            gaps.push(`Total mentorship hours (${totalHours}) below minimum ${this.MIN_MENTORSHIP_HOURS}`);
            recommendedActions.push("Log at least 5 mentorship hours per month");
        }

        // Calculate average feedback score
        const avgFeedback = records.length > 0 
            ? records.reduce((sum, r) => sum + r.feedbackScore, 0) / records.length 
            : 0;
        const feedbackScore = avgFeedback / 5; // Normalize to 0-1

        // Calculate milestone completion rate
        const totalMilestones = records.reduce((sum, r) => sum + r.milestonesCompleted, 0);
        const milestoneScore = Math.min(totalMilestones / 10, 1); // Max 1.0 for 10+ milestones

        // Calculate mentorship score (avg of feedback and milestones)
        const mentorshipScore = (feedbackScore + milestoneScore) / 2;

        // Apply bonus for high-performing mentorship (avg feedback 4+)
        if (avgFeedback >= 4) {
            bonus = 5; // 5 percentage point bonus to total score
        }

        return {
            score: mentorshipScore,
            bonus,
            gaps,
            recommendedActions
        };
    }
}

// Example usage
const exampleReview: PerformanceReview = {
    id: "rev_2024_q3_eng_4921",
    employeeId: "eng_4921",
    reviewPeriod: "2024 Q3",
    codeQualityScore: 4,
    systemDesignScore: 5,
    mentorshipRecords: [
        {
            menteeId: "junior_782",
            startDate: new Date("2024-01-15"),
            milestonesCompleted: 3,
            feedbackScore: 5,
            hoursInvested: 12.5
        },
        {
            menteeId: "junior_901",
            startDate: new Date("2024-03-01"),
            milestonesCompleted: 2,
            feedbackScore: 4,
            hoursInvested: 8
        }
    ],
    currentLevel: "Senior",
    targetLevel: "Staff",
    yearsAtCompany: 4
};

try {
    const checker = new PromotionChecker();
    const eligibility = checker.checkEligibility(exampleReview);

    console.log(`Promotion Eligibility for ${exampleReview.employeeId}:`);
    console.log(`Eligible: ${eligibility.isEligible}`);
    console.log(`Mentorship Bonus: ${eligibility.mentorshipBonus}%`);
    if (eligibility.gaps.length > 0) {
        console.log("Gaps:");
        eligibility.gaps.forEach(gap => console.log(`- ${gap}`));
    }
    if (eligibility.recommendedActions.length > 0) {
        console.log("Recommended Actions:");
        eligibility.recommendedActions.forEach(action => console.log(`- ${action}`));
    }
} catch (error) {
    console.error("Error checking promotion eligibility:", error);
}