mcprojsim 0.2.0__py3-none-any.whl

mcprojsim/__init__.py

@@ -0,0 +1,24 @@
+"""Monte Carlo Project Simulator - A probabilistic project estimation tool."""
+
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+import tomllib
+
+from mcprojsim.models.project import Project, Task, Risk
+from mcprojsim.simulation.engine import SimulationEngine
+
+
+def _resolve_version() -> str:
+    try:
+        return version("mcprojsim")
+    except PackageNotFoundError:
+        pyproject_path = Path(__file__).resolve().parents[2] / "pyproject.toml"
+        try:
+            with pyproject_path.open("rb") as pyproject_file:
+                return tomllib.load(pyproject_file)["tool"]["poetry"]["version"]
+        except FileNotFoundError, KeyError, tomllib.TOMLDecodeError:
+            return "0.0.0+unknown"
+
+
+__version__ = _resolve_version()
+__all__ = ["Project", "Task", "Risk", "SimulationEngine"]

mcprojsim/analysis/__init__.py

@@ -0,0 +1,7 @@
+"""Analysis components."""
+
+from mcprojsim.analysis.statistics import StatisticalAnalyzer
+from mcprojsim.analysis.sensitivity import SensitivityAnalyzer
+from mcprojsim.analysis.critical_path import CriticalPathAnalyzer
+
+__all__ = ["StatisticalAnalyzer", "SensitivityAnalyzer", "CriticalPathAnalyzer"]

mcprojsim/analysis/critical_path.py

@@ -0,0 +1,52 @@
+"""Critical path analysis."""
+
+from typing import Dict, List
+
+from mcprojsim.models.simulation import CriticalPathRecord, SimulationResults
+
+
+class CriticalPathAnalyzer:
+    """Analyzer for critical path identification."""
+
+    @staticmethod
+    def get_criticality_index(results: SimulationResults) -> Dict[str, float]:
+        """Get criticality index for each task.
+
+        Args:
+            results: Simulation results
+
+        Returns:
+            Dictionary mapping task IDs to criticality (0.0-1.0)
+        """
+        return results.get_critical_path()
+
+    @staticmethod
+    def get_most_critical_tasks(
+        results: SimulationResults, threshold: float = 0.5
+    ) -> List[str]:
+        """Get tasks that are critical in at least threshold % of iterations.
+
+        Args:
+            results: Simulation results
+            threshold: Minimum criticality threshold (0.0-1.0)
+
+        Returns:
+            List of critical task IDs
+        """
+        criticality = CriticalPathAnalyzer.get_criticality_index(results)
+        return [task_id for task_id, crit in criticality.items() if crit >= threshold]
+
+    @staticmethod
+    def get_most_frequent_paths(
+        results: SimulationResults, top_n: int | None = None
+    ) -> list[CriticalPathRecord]:
+        """Get the most frequent full critical path sequences.
+
+        Args:
+            results: Simulation results
+            top_n: Maximum number of paths to return
+
+        Returns:
+            List of aggregated critical path records
+        """
+        return results.get_critical_path_sequences(top_n)

mcprojsim/analysis/sensitivity.py

@@ -0,0 +1,57 @@
+"""Sensitivity analysis for task impacts."""
+
+from typing import Dict
+import numpy as np
+from scipy import stats
+from mcprojsim.models.simulation import SimulationResults
+
+
+class SensitivityAnalyzer:
+    """Analyzer for sensitivity analysis."""
+
+    @staticmethod
+    def calculate_correlations(results: SimulationResults) -> Dict[str, float]:
+        """Calculate Spearman rank correlation between task durations and project.
+
+        Args:
+            results: Simulation results
+
+        Returns:
+            Dictionary mapping task IDs to correlation coefficients
+        """
+        correlations: Dict[str, float] = {}
+
+        for task_id, task_durations in results.task_durations.items():
+            # Calculate Spearman correlation
+            # Convert to numpy arrays to ensure proper typing
+            x: np.ndarray = np.asarray(task_durations)
+            y: np.ndarray = np.asarray(results.durations)
+
+            # stats.spearmanr returns a tuple (correlation, p-value)
+            correlation_coeff, _ = stats.spearmanr(x, y)
+            # Explicit cast to handle scipy type inference issues
+            correlations[task_id] = float(np.asarray(correlation_coeff).item())
+
+        return correlations
+
+    @staticmethod
+    def get_top_contributors(
+        results: SimulationResults, n: int = 10
+    ) -> list[tuple[str, float]]:
+        """Get top N tasks contributing to schedule variance.
+
+        Args:
+            results: Simulation results
+            n: Number of top tasks to return
+
+        Returns:
+            List of (task_id, correlation) tuples, sorted by correlation
+        """
+        correlations = SensitivityAnalyzer.calculate_correlations(results)
+
+        # Sort by absolute correlation value
+        sorted_tasks = sorted(
+            correlations.items(), key=lambda x: abs(x[1]), reverse=True
+        )
+
+        return sorted_tasks[:n]

mcprojsim/analysis/statistics.py

@@ -0,0 +1,67 @@
+"""Statistical analysis utilities."""
+
+from typing import Dict
+import numpy as np
+from scipy import stats
+
+
+class StatisticalAnalyzer:
+    """Analyzer for simulation statistics."""
+
+    @staticmethod
+    def calculate_statistics(durations: np.ndarray) -> Dict[str, float]:
+        """Calculate statistical measures.
+
+        Args:
+            durations: Array of duration values
+
+        Returns:
+            Dictionary of statistical measures
+        """
+        return {
+            "mean": float(np.mean(durations)),
+            "median": float(np.median(durations)),
+            "std_dev": float(np.std(durations)),
+            "variance": float(np.var(durations)),
+            "min": float(np.min(durations)),
+            "max": float(np.max(durations)),
+            "range": float(np.max(durations) - np.min(durations)),
+            "coefficient_of_variation": (
+                float(np.std(durations) / np.mean(durations))
+                if np.mean(durations) > 0
+                else 0.0
+            ),
+        }
+
+    @staticmethod
+    def calculate_percentiles(
+        durations: np.ndarray, percentiles: list[int]
+    ) -> Dict[int, float]:
+        """Calculate percentile values.
+
+        Args:
+            durations: Array of duration values
+            percentiles: List of percentile values (0-100)
+
+        Returns:
+            Dictionary mapping percentiles to values
+        """
+        return {p: float(np.percentile(durations, p)) for p in percentiles}
+
+    @staticmethod
+    def confidence_interval(
+        durations: np.ndarray, confidence: float = 0.95
+    ) -> tuple[float, float]:
+        """Calculate confidence interval.
+
+        Args:
+            durations: Array of duration values
+            confidence: Confidence level (default 0.95)
+
+        Returns:
+            Tuple of (lower_bound, upper_bound)
+        """
+        mean = np.mean(durations)
+        sem = stats.sem(durations)
+        ci = stats.t.interval(confidence, len(durations) - 1, loc=mean, scale=sem)
+        return float(ci[0]), float(ci[1])

mcprojsim/cli.py

@@ -0,0 +1,242 @@
+"""Command-line interface for Monte Carlo Project Simulator."""
+
+from pathlib import Path
+from typing import Optional, Union
+
+import click
+
+from mcprojsim import __version__
+from mcprojsim.config import Config, DEFAULT_SIMULATION_ITERATIONS
+from mcprojsim.exporters import CSVExporter, HTMLExporter, JSONExporter
+from mcprojsim.parsers import TOMLParser, YAMLParser
+from mcprojsim.simulation import SimulationEngine
+from mcprojsim.utils import Validator, setup_logging
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="mcprojsim")
+def cli() -> None:
+    """Monte Carlo Project Simulator - Probabilistic project estimation."""
+    pass
+
+
+@cli.command()
+@click.argument("project_file", type=click.Path(exists=True))
+@click.option(
+    "--iterations",
+    "-n",
+    type=int,
+    default=DEFAULT_SIMULATION_ITERATIONS,
+    help="Number of simulation iterations",
+)
+@click.option("--config", "-c", type=click.Path(exists=True), help="Configuration file")
+@click.option("--seed", "-s", type=int, help="Random seed for reproducibility")
+@click.option(
+    "--output", "-o", type=click.Path(), help="Output file path (without extension)"
+)
+@click.option(
+    "--output-format",
+    "-f",
+    default="",
+    help="Output formats (comma-separated: json,csv,html). If not specified, only CLI output is shown.",
+)
+@click.option(
+    "--critical-paths",
+    type=int,
+    help="Number of full critical path sequences to include in CLI output and exports.",
+)
+@click.option("--quiet", "-q", is_flag=True, help="Suppress progress output")
+def simulate(
+    project_file: str,
+    iterations: int,
+    config: Optional[str],
+    seed: Optional[int],
+    output: Optional[str],
+    output_format: str,
+    critical_paths: Optional[int],
+    quiet: bool,
+) -> None:
+    """Run Monte Carlo simulation for a project."""
+    logger = setup_logging()
+
+    try:
+        # Load configuration
+        if config:
+            cfg = Config.load_from_file(config)
+            logger.info(f"Loaded configuration from {config}")
+        else:
+            cfg = Config.get_default()
+            logger.info("Using default configuration")
+
+        # Parse project file
+        project_path = Path(project_file)
+        parser: Union[YAMLParser, TOMLParser]
+        if project_path.suffix in [".yaml", ".yml"]:
+            parser = YAMLParser()
+        elif project_path.suffix == ".toml":
+            parser = TOMLParser()
+        else:
+            click.echo(f"Error: Unsupported file format {project_path.suffix}")
+            return
+
+        if not quiet:
+            click.echo(f"Loading project from {project_file}...")
+        project = parser.parse_file(project_file)
+        logger.info(f"Loaded project: {project.project.name}")
+
+        # Run simulation
+        if not quiet:
+            click.echo(f"Running simulation with {iterations} iterations...")
+        engine = SimulationEngine(
+            iterations=iterations,
+            random_seed=seed,
+            config=cfg,
+            show_progress=not quiet,
+        )
+        results = engine.run(project)
+        critical_path_limit = critical_paths or cfg.output.critical_path_report_limit
+
+        if not quiet:
+            click.echo("\n=== Simulation Results ===")
+            click.echo(f"Project: {results.project_name}")
+            click.echo(f"Mean: {results.mean:.2f} days")
+            click.echo(f"Median (P50): {results.median:.2f} days")
+            click.echo(f"Std Dev: {results.std_dev:.2f} days")
+            click.echo("\nConfidence Intervals:")
+            for p in sorted(results.percentiles.keys()):
+                click.echo(f"  P{p}: {results.percentiles[p]:.2f} days")
+
+            critical_path_records = results.get_critical_path_sequences(
+                critical_path_limit
+            )
+            if critical_path_records:
+                click.echo("\nMost Frequent Critical Paths:")
+                for index, record in enumerate(critical_path_records, start=1):
+                    click.echo(
+                        "  "
+                        f"{index}. {record.format_path()} "
+                        f"({record.count}/{results.iterations}, {record.frequency * 100:.1f}%)"
+                    )
+
+        # Export results (only if formats are explicitly specified)
+        if output_format.strip():
+            formats = [f.strip().lower() for f in output_format.split(",") if f.strip()]
+            base_output = (
+                Path(output) if output else Path(f"{project.project.name}_results")
+            )
+
+            for fmt in formats:
+                if fmt == "json":
+                    output_file = base_output.with_suffix(".json")
+                    JSONExporter.export(
+                        results,
+                        output_file,
+                        config=cfg,
+                        critical_path_limit=critical_path_limit,
+                    )
+                    if not quiet:
+                        click.echo(f"\nResults exported to {output_file}")
+                elif fmt == "csv":
+                    output_file = base_output.with_suffix(".csv")
+                    CSVExporter.export(
+                        results,
+                        output_file,
+                        config=cfg,
+                        critical_path_limit=critical_path_limit,
+                    )
+                    if not quiet:
+                        click.echo(f"Results exported to {output_file}")
+                elif fmt == "html":
+                    output_file = base_output.with_suffix(".html")
+                    HTMLExporter.export(
+                        results,
+                        output_file,
+                        project=project,
+                        config=cfg,
+                        critical_path_limit=critical_path_limit,
+                    )
+                    if not quiet:
+                        click.echo(f"Results exported to {output_file}")
+                else:
+                    if not quiet:
+                        click.echo(f"Warning: Unknown format '{fmt}' ignored")
+        else:
+            if not quiet:
+                click.echo(
+                    "\nNo export formats specified. Use -f to export results to files."
+                )
+
+    except Exception as e:
+        logger.error(f"Error during simulation: {e}")
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+
+
+@cli.command()
+@click.argument("project_file", type=click.Path(exists=True))
+def validate(project_file: str) -> None:
+    """Validate a project definition file."""
+    logger = setup_logging()
+
+    click.echo(f"Validating {project_file}...")
+
+    is_valid, error_message = Validator.validate_file(project_file)
+
+    if is_valid:
+        click.echo("✓ Project file is valid!")
+        logger.info(f"Project file {project_file} is valid")
+    else:
+        click.echo("✗ Validation failed:", err=True)
+        click.echo(f"  {error_message}", err=True)
+        logger.error(f"Validation failed for {project_file}: {error_message}")
+        raise click.Abort()
+
+
+@cli.group()
+def config() -> None:
+    """Configuration management commands."""
+    pass
+
+
+@config.command(name="show")
+@click.option("--config-file", "-c", type=click.Path(exists=True), help="Config file")
+def show_config(config_file: Optional[str]) -> None:
+    """Show current configuration."""
+    if config_file:
+        cfg = Config.load_from_file(config_file)
+        click.echo(f"Configuration from {config_file}:")
+    else:
+        cfg = Config.get_default()
+        click.echo("Default configuration:")
+
+    click.echo("\nUncertainty Factors:")
+    for factor_name, levels in cfg.uncertainty_factors.items():
+        click.echo(f"  {factor_name}:")
+        for level, value in levels.items():
+            click.echo(f"    {level}: {value}")
+
+    click.echo("\nT-Shirt Sizes (effort estimates in days):")
+    for size, config in cfg.t_shirt_sizes.items():
+        click.echo(f"  {size}:")
+        click.echo(
+            f"    min: {config.min}, most_likely: {config.most_likely}, max: {config.max}"
+        )
+
+    click.echo("\nSimulation:")
+    click.echo(f"  Default iterations: {cfg.simulation.default_iterations}")
+    click.echo(f"  Random seed: {cfg.simulation.random_seed}")
+    click.echo(
+        "  Max stored critical paths: " f"{cfg.simulation.max_stored_critical_paths}"
+    )
+
+    click.echo("\nOutput:")
+    click.echo(f"  Formats: {', '.join(cfg.output.formats)}")
+    click.echo(f"  Include histogram: {cfg.output.include_histogram}")
+    click.echo(f"  Histogram bins: {cfg.output.histogram_bins}")
+    click.echo(
+        "  Critical path report limit: " f"{cfg.output.critical_path_report_limit}"
+    )
+
+
+if __name__ == "__main__":
+    cli()

mcprojsim/config.py

@@ -0,0 +1,213 @@
+"""Configuration management for uncertainty factors and simulation settings."""
+
+from copy import deepcopy
+from pathlib import Path
+from typing import Dict, Optional
+
+import yaml
+from pydantic import BaseModel, Field
+
+# This file defines the configuration schema and default values for the Monte Carlo Project Simulator.
+# This is where we centralize all configurable parameters, including uncertainty factors, T-shirt size mappings,
+# and simulation settings. The SimulationEngine will use this configuration to adjust task durations and apply
+# risk impacts during simulation.
+# It is the single source of truth for all configuration-related logic, making it easier to maintain and extend in the future.
+
+DEFAULT_SIMULATION_ITERATIONS = 10000
+DEFAULT_OUTPUT_FORMATS = ["json", "csv", "html"]
+DEFAULT_HISTOGRAM_BINS = 50
+DEFAULT_MAX_STORED_CRITICAL_PATHS = 20
+DEFAULT_CRITICAL_PATH_REPORT_LIMIT = 2
+DEFAULT_CONFIDENCE_LEVELS = [25, 50, 75, 80, 85, 90, 95, 99]
+DEFAULT_PROBABILITY_RED_THRESHOLD = 0.50
+DEFAULT_PROBABILITY_GREEN_THRESHOLD = 0.90
+DEFAULT_UNCERTAINTY_FACTOR_LEVELS = {
+    "team_experience": "medium",
+    "requirements_maturity": "medium",
+    "technical_complexity": "medium",
+    "team_distribution": "colocated",
+    "integration_complexity": "medium",
+}
+DEFAULT_UNCERTAINTY_FACTORS = {
+    "team_experience": {"high": 0.90, "medium": 1.0, "low": 1.30},
+    "requirements_maturity": {"high": 1.0, "medium": 1.15, "low": 1.40},
+    "technical_complexity": {"low": 1.0, "medium": 1.20, "high": 1.50},
+    "team_distribution": {"colocated": 1.0, "distributed": 1.25},
+    "integration_complexity": {"low": 1.0, "medium": 1.15, "high": 1.35},
+}
+DEFAULT_T_SHIRT_SIZE_VALUES = {
+    "XS": {"min": 0.5, "most_likely": 1, "max": 2},
+    "S": {"min": 1, "most_likely": 2, "max": 4},
+    "M": {"min": 3, "most_likely": 5, "max": 8},
+    "L": {"min": 5, "most_likely": 8, "max": 13},
+    "XL": {"min": 8, "most_likely": 13, "max": 21},
+    "XXL": {"min": 13, "most_likely": 21, "max": 34},
+}
+DEFAULT_STORY_POINT_VALUES = {
+    1: {"min": 0.5, "most_likely": 1, "max": 3},
+    2: {"min": 1, "most_likely": 2, "max": 4},
+    3: {"min": 1.5, "most_likely": 3, "max": 5},
+    5: {"min": 3, "most_likely": 5, "max": 8},
+    8: {"min": 5, "most_likely": 8, "max": 15},
+    13: {"min": 8, "most_likely": 13, "max": 21},
+    21: {"min": 13, "most_likely": 21, "max": 34},
+}
+
+
+def _build_default_config_data() -> dict:
+    """Build the default configuration payload."""
+    return {
+        "uncertainty_factors": deepcopy(DEFAULT_UNCERTAINTY_FACTORS),
+        "t_shirt_sizes": {
+            size: deepcopy(values)
+            for size, values in DEFAULT_T_SHIRT_SIZE_VALUES.items()
+        },
+        "story_points": {
+            points: deepcopy(values)
+            for points, values in DEFAULT_STORY_POINT_VALUES.items()
+        },
+        "simulation": {
+            "default_iterations": DEFAULT_SIMULATION_ITERATIONS,
+            "random_seed": None,
+            "max_stored_critical_paths": DEFAULT_MAX_STORED_CRITICAL_PATHS,
+        },
+        "output": {
+            "formats": list(DEFAULT_OUTPUT_FORMATS),
+            "include_histogram": True,
+            "histogram_bins": DEFAULT_HISTOGRAM_BINS,
+            "critical_path_report_limit": DEFAULT_CRITICAL_PATH_REPORT_LIMIT,
+        },
+    }
+
+
+def _merge_nested_dicts(base: dict, overrides: dict) -> dict:
+    """Recursively merge dictionaries, preserving defaults."""
+    merged = deepcopy(base)
+
+    for key, value in overrides.items():
+        if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
+            merged[key] = _merge_nested_dicts(merged[key], value)
+        else:
+            merged[key] = value
+
+    return merged
+
+
+class UncertaintyFactorConfig(BaseModel):
+    """Configuration for a single uncertainty factor."""
+
+    high: float = Field(default=1.0)
+    medium: float = Field(default=1.0)
+    low: float = Field(default=1.0)
+
+
+class SimulationConfig(BaseModel):
+    """Simulation settings."""
+
+    default_iterations: int = Field(default=DEFAULT_SIMULATION_ITERATIONS, gt=0)
+    random_seed: Optional[int] = None
+    max_stored_critical_paths: int = Field(
+        default=DEFAULT_MAX_STORED_CRITICAL_PATHS,
+        gt=0,
+    )
+
+
+class OutputConfig(BaseModel):
+    """Output settings."""
+
+    formats: list[str] = Field(default_factory=lambda: list(DEFAULT_OUTPUT_FORMATS))
+    include_histogram: bool = True
+    histogram_bins: int = Field(default=DEFAULT_HISTOGRAM_BINS, gt=0)
+    critical_path_report_limit: int = Field(
+        default=DEFAULT_CRITICAL_PATH_REPORT_LIMIT,
+        gt=0,
+    )
+
+
+class EstimateRangeConfig(BaseModel):
+    """Range configuration for a symbolic estimate."""
+
+    min: float = Field(gt=0)
+    most_likely: float = Field(gt=0)
+    max: float = Field(gt=0)
+
+
+class TShirtSizeConfig(EstimateRangeConfig):
+    """T-shirt size estimate configuration."""
+
+
+class StoryPointConfig(EstimateRangeConfig):
+    """Story Point estimate configuration."""
+
+
+class Config(BaseModel):
+    """Complete application configuration."""
+
+    uncertainty_factors: Dict[str, Dict[str, float]] = Field(default_factory=dict)
+    t_shirt_sizes: Dict[str, TShirtSizeConfig] = Field(default_factory=dict)
+    story_points: Dict[int, StoryPointConfig] = Field(default_factory=dict)
+    simulation: SimulationConfig = Field(default_factory=SimulationConfig)
+    output: OutputConfig = Field(default_factory=OutputConfig)
+
+    @classmethod
+    def load_from_file(cls, config_path: Path | str) -> "Config":
+        """Load configuration from YAML file.
+
+        Args:
+            config_path: Path to configuration file
+
+        Returns:
+            Config object
+        """
+        config_path = Path(config_path)
+        if not config_path.exists():
+            raise FileNotFoundError(f"Config file not found: {config_path}")
+
+        with open(config_path, "r") as f:
+            data = yaml.safe_load(f) or {}
+
+        merged_data = _merge_nested_dicts(_build_default_config_data(), data)
+        return cls.model_validate(merged_data)
+
+    @classmethod
+    def get_default(cls) -> "Config":
+        """Get default configuration with standard uncertainty factors."""
+        return cls.model_validate(_build_default_config_data())
+
+    def get_uncertainty_multiplier(self, factor_name: str, level: str) -> float:
+        """Get uncertainty multiplier for a given factor and level.
+
+        Args:
+            factor_name: Name of uncertainty factor
+            level: Level of the factor (e.g., 'high', 'medium', 'low')
+
+        Returns:
+            Multiplier value
+        """
+        if factor_name not in self.uncertainty_factors:
+            return 1.0
+
+        factor_config = self.uncertainty_factors[factor_name]
+        return factor_config.get(level, 1.0)
+
+    def get_t_shirt_size(self, size: str) -> Optional[TShirtSizeConfig]:
+        """Get T-shirt size configuration.
+
+        Args:
+            size: T-shirt size (e.g., 'XS', 'S', 'M', 'L', 'XL', 'XXL')
+
+        Returns:
+            TShirtSizeConfig object or None if not found
+        """
+        return self.t_shirt_sizes.get(size)
+
+    def get_story_point(self, points: int) -> Optional[StoryPointConfig]:
+        """Get Story Point configuration.
+
+        Args:
+            points: Story Point value (for example 1, 2, 3, 5, 8, 13, 21)
+
+        Returns:
+            StoryPointConfig object or None if not found
+        """
+        return self.story_points.get(points)

mcprojsim/exporters/__init__.py

@@ -0,0 +1,7 @@
+"""Exporters for simulation results."""
+
+from mcprojsim.exporters.json_exporter import JSONExporter
+from mcprojsim.exporters.csv_exporter import CSVExporter
+from mcprojsim.exporters.html_exporter import HTMLExporter
+
+__all__ = ["JSONExporter", "CSVExporter", "HTMLExporter"]