Tool Evaluator

python
# Advanced tool evaluation framework with quantitative analysis
import pandas as pd
import numpy as np
from dataclasses import dataclass
from typing import Dict, List, Optional
import requests
import time

@dataclass
class EvaluationCriteria:
    name: str
    weight: float  # 0-1 importance weight
    max_score: int = 10
    description: str = ""

@dataclass
class ToolScoring:
    tool_name: str
    scores: Dict[str, float]
    total_score: float
    weighted_score: float
    notes: Dict[str, str]

class ToolEvaluator:
    def __init__(self):
        self.criteria = self._define_evaluation_criteria()
        self.test_results = {}
        self.cost_analysis = {}
        self.risk_assessment = {}
    
    def _define_evaluation_criteria(self) -> List[EvaluationCriteria]:
        """Define weighted evaluation criteria"""
        return [
            EvaluationCriteria("functionality", 0.25, description="Core feature completeness"),
            EvaluationCriteria("usability", 0.20, description="User experience and ease of use"),
            EvaluationCriteria("performance", 0.15, description="Speed, reliability, scalability"),
            EvaluationCriteria("security", 0.15, description="Data protection and compliance"),
            EvaluationCriteria("integration", 0.10, description="API quality and system compatibility"),
            EvaluationCriteria("support", 0.08, description="Vendor support quality and documentation"),
            EvaluationCriteria("cost", 0.07, description="Total cost of ownership and value")
        ]
    
    def evaluate_tool(self, tool_name: str, tool_config: Dict) -> ToolScoring:
        """Comprehensive tool evaluation with quantitative scoring"""
        scores = {}
        notes = {}
        
        # Functional testing
        functionality_score, func_notes = self._test_functionality(tool_config)
        scores["functionality"] = functionality_score
        notes["functionality"] = func_notes
        
        # Usability testing
        usability_score, usability_notes = self._test_usability(tool_config)
        scores["usability"] = usability_score
        notes["usability"] = usability_notes
        
        # Performance testing
        performance_score, perf_notes = self._test_performance(tool_config)
        scores["performance"] = performance_score
        notes["performance"] = perf_notes
        
        # Security assessment
        security_score, sec_notes = self._assess_security(tool_config)
        scores["security"] = security_score
        notes["security"] = sec_notes
        
        # Integration testing
        integration_score, int_notes = self._test_integration(tool_config)
        scores["integration"] = integration_score
        notes["integration"] = int_notes
        
        # Support evaluation
        support_score, support_notes = self._evaluate_support(tool_config)
        scores["support"] = support_score
        notes["support"] = support_notes
        
        # Cost analysis
        cost_score, cost_notes = self._analyze_cost(tool_config)
        scores["cost"] = cost_score
        notes["cost"] = cost_notes
        
        # Calculate weighted scores
        total_score = sum(scores.values())
        weighted_score = sum(
            scores[criterion.name] * criterion.weight 
            for criterion in self.criteria
        )
        
        return ToolScoring(
            tool_name=tool_name,
            scores=scores,
            total_score=total_score,
            weighted_score=weighted_score,
            notes=notes
        )
    
    def _test_functionality(self, tool_config: Dict) -> tuple[float, str]:
        """Test core functionality against requirements"""
        required_features = tool_config.get("required_features", [])
        optional_features = tool_config.get("optional_features", [])
        
        # Test each required feature
        feature_scores = []
        test_notes = []
        
        for feature in required_features:
            score = self._test_feature(feature, tool_config)
            feature_scores.append(score)
            test_notes.append(f"{feature}: {score}/10")
        
        # Calculate score with required features as 80% weight
        required_avg = np.mean(feature_scores) if feature_scores else 0
        
        # Test optional features
        optional_scores = []
        for feature in optional_features:
            score = self._test_feature(feature, tool_config)
            optional_scores.append(score)
            test_notes.append(f"{feature} (optional): {score}/10")
        
        optional_avg = np.mean(optional_scores) if optional_scores else 0
        
        # An absent category is not a failed category: normalize active weights.
        active_scores = []
        if feature_scores:
            active_scores.append((required_avg, 0.8))
        if optional_scores:
            active_scores.append((optional_avg, 0.2))
        if not active_scores:
            raise ValueError("Define at least one feature before scoring functionality")
        final_score = sum(score * weight for score, weight in active_scores) / sum(
            weight for _, weight in active_scores
        )
        notes = "; ".join(test_notes)
        
        return final_score, notes
    
    def _test_performance(self, tool_config: Dict) -> tuple[float, str]:
        """Performance testing with quantitative metrics"""
        api_endpoint = tool_config.get("api_endpoint")
        if not api_endpoint:
            return 5.0, "No API endpoint for performance testing"
        
        # Response time testing
        response_times = []
        failed_requests = 0
        for _ in range(10):
            start_time = time.time()
            try:
                response = requests.get(api_endpoint, timeout=10)
                response.raise_for_status()
                end_time = time.time()
                response_times.append(end_time - start_time)
            except requests.RequestException:
                failed_requests += 1
                response_times.append(10.0)  # Network/HTTP failure penalty
        
        avg_response_time = np.mean(response_times)
        p95_response_time = np.percentile(response_times, 95)
        
        # Score based on response time (lower is better)
        if avg_response_time < 0.1:
            speed_score = 10
        elif avg_response_time < 0.5:
            speed_score = 8
        elif avg_response_time < 1.0:
            speed_score = 6
        elif avg_response_time < 2.0:
            speed_score = 4
        else:
            speed_score = 2
        
        notes = (f"Penalty-adjusted avg: {avg_response_time:.2f}s, P95: {p95_response_time:.2f}s; "
                 f"failed requests: {failed_requests}/{len(response_times)}")
        return speed_score, notes
    
    def calculate_total_cost_ownership(self, tool_config: Dict, years: int = 3) -> Dict:
        """Calculate TCO only for a defined positive adoption horizon."""
        users = tool_config.get("expected_users", 1)
        if isinstance(years, bool) or not isinstance(years, int) or years <= 0:
            raise ValueError("years must be a positive integer")
        if (isinstance(users, bool) or not isinstance(users, (int, float))
                or not np.isfinite(users) or users <= 0):
            raise ValueError("expected_users must be a positive finite number")
        costs = {
            "licensing": tool_config.get("annual_license_cost", 0) * years,
            "implementation": tool_config.get("implementation_cost", 0),
            "training": tool_config.get("training_cost", 0),
            "maintenance": tool_config.get("annual_maintenance_cost", 0) * years,
            "integration": tool_config.get("integration_cost", 0),
            "migration": tool_config.get("migration_cost", 0),
            "support": tool_config.get("annual_support_cost", 0) * years,
        }
        
        total_cost = sum(costs.values())
        
        # Calculate cost per user per year
        cost_per_user_year = total_cost / (users * years)
        
        return {
            "cost_breakdown": costs,
            "total_cost": total_cost,
            "cost_per_user_year": cost_per_user_year,
            "years_analyzed": years
        }
    
    def generate_comparison_report(self, tool_evaluations: List[ToolScoring]) -> Dict:
        """Generate comprehensive comparison report"""
        # Create comparison matrix
        comparison_df = pd.DataFrame([
            {
                "Tool": eval.tool_name,
                **eval.scores,
                "Weighted Score": eval.weighted_score
            }
            for eval in tool_evaluations
        ])
        
        # Equal best scores share rank 1; average ranking would give 1.5
        # and make the existing Rank == 1 lookup fail. Stable input order
        # selects the convenience top_performer field among tied leaders.
        comparison_df["Rank"] = comparison_df["Weighted Score"].rank(method="min", ascending=False)
        
        # Identify strengths and weaknesses
        analysis = {
            "top_performer": comparison_df.loc[comparison_df["Rank"] == 1, "Tool"].iloc[0],
            "score_comparison": comparison_df.to_dict("records"),
            "category_leaders": {
                criterion.name: comparison_df.loc[comparison_df[criterion.name].idxmax(), "Tool"]
                for criterion in self.criteria
            },
            "recommendations": self._generate_recommendations(comparison_df, tool_evaluations)
        }
        
        return analysis

markdown
# [Tool Category] Evaluation and Recommendation Report

## 🎯 Executive Summary
**Recommended Solution**: [Top-ranked tool with key differentiators]
**Investment Required**: [Total cost with ROI timeline and break-even analysis]
**Implementation Timeline**: [Phases with key milestones and resource requirements]
**Business Impact**: [Quantified productivity gains and efficiency improvements]

## 📊 Evaluation Results
**Tool Comparison Matrix**: [Weighted scoring across all evaluation criteria]
**Category Leaders**: [Best-in-class tools for specific capabilities]
**Performance Benchmarks**: [Quantitative performance testing results]
**User Experience Ratings**: [Usability testing results across user roles]

## 💰 Financial Analysis
**Total Cost of Ownership**: [3-year TCO breakdown with sensitivity analysis]
**ROI Calculation**: [Projected returns with different adoption scenarios]
**Cost Comparison**: [Per-user costs and scaling implications]
**Budget Impact**: [Annual budget requirements and payment options]

## 🔒 Risk Assessment
**Implementation Risks**: [Technical, organizational, and vendor risks]
**Security Evaluation**: [Compliance, data protection, and vulnerability assessment]
**Vendor Assessment**: [Stability, roadmap alignment, and partnership potential]
**Mitigation Strategies**: [Risk reduction and contingency planning]

## 🛠 Implementation Strategy
**Rollout Plan**: [Phased implementation with pilot and full deployment]
**Change Management**: [Training strategy, communication plan, and adoption support]
**Integration Requirements**: [Technical integration and data migration planning]
**Success Metrics**: [KPIs for measuring implementation success and ROI]

---
**Tool Evaluator**: [Your name]
**Evaluation Date**: [Date]
**Confidence Level**: [High/Medium/Low with supporting methodology]
**Next Review**: [Scheduled re-evaluation timeline and trigger criteria]

• Be objective: "Tool A scores 8.7/10 vs Tool B's 7.2/10 based on weighted criteria analysis"
• Focus on value: "Implementation cost of 50K delivers 180K annual productivity gains"
• Think strategically: "This tool aligns with 3-year digital transformation roadmap and scales to 500 users"
• Consider risks: "Vendor financial instability presents medium risk - recommend contract terms with exit protections"