planaco 0.2.1__py3-none-any.whl

planaco/__init__.py

@@ -0,0 +1,158 @@
+"""
+Planaco: Probabilistic Project Planning with Monte Carlo Simulation.
+
+Planaco is a Python library for estimating project completion times using
+Monte Carlo simulation. It models task durations as probability distributions
+and calculates project timelines while accounting for uncertainty and
+task dependencies.
+
+Key Features
+------------
+- **Multiple distribution types**: Choose from 6 probability distributions
+  to model task duration uncertainty.
+- **Task dependencies**: Define complex workflows with parallel and
+  sequential task execution.
+- **Critical path analysis**: Identify which tasks drive your timeline.
+- **Monte Carlo simulation**: Run thousands of simulations to understand
+  probability distributions.
+- **Statistical analysis**: Get mean, median, percentiles, and confidence
+  intervals.
+- **Visualization**: Generate histograms, cumulative plots, and dependency
+  graphs.
+- **Configuration files**: Define projects in YAML for easy sharing.
+- **CLI tool**: Run simulations from the command line.
+
+Main Components
+---------------
+Distribution classes (from ``planaco.distributions``):
+    - ``TriangularDistribution``: Three-point estimate (min, mode, max).
+      Best for tasks where you can estimate optimistic, likely, and
+      pessimistic durations.
+    - ``UniformDistribution``: Equal probability between bounds.
+      Use when all durations in a range are equally likely.
+    - ``NormalDistribution``: Gaussian/bell curve with optional truncation.
+      Good for well-understood, repeatable tasks.
+    - ``PERTDistribution``: Smooth version of triangular (Program Evaluation
+      Review Technique). More weight on the mode than triangular.
+    - ``LogNormalDistribution``: Right-skewed distribution.
+      Good for tasks that may have unexpected delays.
+    - ``BetaDistribution``: Highly flexible with alpha/beta parameters.
+      For advanced modeling when you need specific shapes.
+
+Task:
+    Represents a single task with probabilistic duration. Tasks are the
+    building blocks of projects.
+
+Project:
+    Collection of tasks with optional dependencies. Provides Monte Carlo
+    simulation, statistics, critical path analysis, and visualization.
+
+Quick Start
+-----------
+>>> from planaco import Project, Task
+>>>
+>>> # Create tasks with uncertainty (min, mode, max)
+>>> design = Task(name="Design", min_duration=5, mode_duration=7, max_duration=14)
+>>> develop = Task(name="Develop", min_duration=10, mode_duration=15, max_duration=25)
+>>> test = Task(name="Test", min_duration=3, mode_duration=5, max_duration=10)
+>>>
+>>> # Create project with dependencies
+>>> project = Project(name="My Project", unit="days")
+>>> project.add_task(design)
+>>> project.add_task(develop, depends_on=[design])
+>>> project.add_task(test, depends_on=[develop])
+>>>
+>>> # Run simulation and get statistics
+>>> stats = project.statistics(n=10000)
+>>> print(f"Expected duration: {stats['mean']:.1f} days")
+>>> print(f"P85 estimate: {stats['percentiles']['p85']:.1f} days")
+
+Using Distribution Objects
+--------------------------
+>>> from planaco import Task, PERTDistribution
+>>>
+>>> # Use PERT distribution for smoother estimates
+>>> dist = PERTDistribution(minimum=5, mode=7, maximum=14)
+>>> task = Task(name="Design", distribution=dist)
+
+Configuration Files
+-------------------
+Projects can be defined in YAML configuration files for easy sharing
+and version control. See ``planaco.config`` for loading configurations.
+
+Example YAML::
+
+    project:
+      name: "Website Redesign"
+      unit: "days"
+
+    tasks:
+      - name: "Design"
+        distribution:
+          type: "pert"
+          minimum: 5
+          mode: 7
+          maximum: 14
+
+      - name: "Development"
+        depends_on: ["Design"]
+        distribution:
+          type: "triangular"
+          minimum: 10
+          mode: 15
+          maximum: 25
+
+Command Line Interface
+----------------------
+Planaco provides a CLI for running simulations::
+
+    $ planaco init              # Create template config file
+    $ planaco run config.yaml   # Run simulation
+    $ planaco stats config.yaml # Show statistics
+    $ planaco plot config.yaml  # Generate visualization
+    $ planaco graph config.yaml # Show dependency graph
+
+See Also
+--------
+planaco.distributions : Probability distribution classes.
+planaco.task : Task class for individual tasks.
+planaco.project : Project class for task collections.
+planaco.config : YAML configuration loading.
+planaco.cli : Command-line interface.
+
+Version
+-------
+0.2.1
+"""
+
+# Import order matters: distributions -> task -> project to avoid circular imports
+from planaco.distributions import (
+    BetaDistribution,
+    Distribution,
+    LogNormalDistribution,
+    NormalDistribution,
+    PERTDistribution,
+    TriangularDistribution,
+    UniformDistribution,
+)
+from planaco.task import Task
+from planaco.project import Project
+
+__version__ = "0.2.1"
+
+__all__ = [
+    # Core classes
+    "Project",
+    "Task",
+    # Distribution base
+    "Distribution",
+    # Distribution types
+    "BetaDistribution",
+    "LogNormalDistribution",
+    "NormalDistribution",
+    "PERTDistribution",
+    "TriangularDistribution",
+    "UniformDistribution",
+    # Version
+    "__version__",
+]

planaco/cli.py

@@ -0,0 +1,336 @@
+"""Planaco CLI - Monte Carlo simulation for project estimation."""
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional, Tuple
+
+import click
+
+from planaco import __version__
+from planaco.config import (
+    ConfigError,
+    build_project_from_config,
+    get_seed_from_config,
+    get_template_config,
+    load_config,
+)
+
+
+def _setup_seed(config: dict, cli_seed: Optional[int]) -> None:
+    """Set up random seed from config or CLI, with warning if none specified.
+
+    Priority: CLI --seed > YAML config seed > random (no seed)
+
+    Parameters
+    ----------
+    config : dict
+        Parsed configuration dictionary
+    cli_seed : Optional[int]
+        Seed from CLI --seed option (takes priority)
+    """
+    import random
+
+    # CLI seed takes priority over config seed
+    if cli_seed is not None:
+        random.seed(cli_seed)
+        return
+
+    # Try config seed
+    config_seed = get_seed_from_config(config)
+    if config_seed is not None:
+        random.seed(config_seed)
+        return
+
+    # No seed specified - show warning
+    click.secho(
+        "Note: No seed specified. Results will vary between runs.",
+        fg="yellow",
+        err=True,
+    )
+    click.secho(
+        "      Add 'seed: <number>' to your project config for reproducible results.",
+        fg="yellow",
+        err=True,
+    )
+
+
+@click.group()
+@click.version_option(version=__version__)
+def main() -> None:
+    """Planaco - Monte Carlo simulation for project estimation.
+
+    Define projects and tasks in YAML, run simulations, and get
+    probabilistic completion time estimates.
+
+    Examples:
+
+        planaco init my_project.yaml
+
+        planaco stats my_project.yaml
+
+        planaco plot my_project.yaml -o chart.png
+    """
+    pass
+
+
+@main.command()
+@click.argument("output", default="planaco_project.yaml")
+@click.option(
+    "--name", "-n", default="My Project", help="Project name for the template"
+)
+def init(output: str, name: str) -> None:
+    """Create a template YAML project file.
+
+    OUTPUT: Path for the new YAML file (default: planaco_project.yaml)
+
+    Example:
+        planaco init my_project.yaml --name "Web App Development"
+    """
+    output_path = Path(output)
+
+    if output_path.exists():
+        click.secho(f"Error: File '{output}' already exists", fg="red", err=True)
+        sys.exit(1)
+
+    template = get_template_config(name)
+
+    with open(output_path, "w") as f:
+        f.write(template)
+
+    click.secho(f"Created template project file: {output}", fg="green")
+    click.echo("\nEdit the file to define your tasks, then run:")
+    click.echo(f"  planaco stats {output}")
+
+
+@main.command()
+@click.argument("config_file", type=click.Path(exists=True))
+@click.option("-n", "--simulations", default=10000, help="Number of simulations to run")
+@click.option(
+    "-o", "--output", default=None, help="Output file for results (default: stdout)"
+)
+@click.option(
+    "-f",
+    "--format",
+    "output_format",
+    type=click.Choice(["json", "csv"]),
+    default="json",
+    help="Output format",
+)
+@click.option("--seed", default=None, type=int, help="Random seed for reproducibility")
+def run(
+    config_file: str,
+    simulations: int,
+    output: Optional[str],
+    output_format: str,
+    seed: Optional[int],
+) -> None:
+    """Run Monte Carlo simulation and export results.
+
+    CONFIG_FILE: Path to the YAML project configuration file.
+
+    Example:
+        planaco run project.yaml -n 10000 -o results.json
+    """
+    try:
+        config = load_config(config_file)
+        _setup_seed(config, seed)
+        project = build_project_from_config(config)
+
+        if output:
+            project.export_results(n=simulations, format=output_format, output=output)
+            click.secho(f"Results exported to {output}", fg="green")
+        else:
+            stats = project.statistics(n=simulations)
+            _print_stats(project.name, stats)
+
+    except (ConfigError, FileNotFoundError) as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.argument("config_file", type=click.Path(exists=True))
+@click.option("-n", "--simulations", default=10000, help="Number of simulations to run")
+@click.option(
+    "--json", "as_json", is_flag=True, help="Output as JSON instead of formatted text"
+)
+@click.option(
+    "--seed",
+    default=None,
+    type=int,
+    help="Random seed for reproducibility (overrides config)",
+)
+def stats(
+    config_file: str, simulations: int, as_json: bool, seed: Optional[int]
+) -> None:
+    """Calculate and display project statistics.
+
+    CONFIG_FILE: Path to the YAML project configuration file.
+
+    Example:
+        planaco stats project.yaml -n 10000
+    """
+    try:
+        config = load_config(config_file)
+        _setup_seed(config, seed)
+        project = build_project_from_config(config)
+
+        stats_result = project.statistics(n=simulations)
+
+        if as_json:
+            click.echo(json.dumps(stats_result, indent=2))
+        else:
+            _print_stats(project.name, stats_result)
+
+    except (ConfigError, FileNotFoundError) as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.argument("config_file", type=click.Path(exists=True))
+@click.option("-n", "--simulations", default=1000, help="Number of simulations to run")
+@click.option(
+    "-o", "--output", default=None, help="Save plot to file instead of displaying"
+)
+@click.option(
+    "--cumulative",
+    is_flag=True,
+    help="Show cumulative distribution instead of histogram",
+)
+@click.option("--kde", is_flag=True, help="Show kernel density estimate on histogram")
+@click.option(
+    "-p",
+    "--percentile",
+    "percentiles",
+    multiple=True,
+    type=int,
+    help="Percentile markers to show (e.g., -p 50 -p 85 -p 95)",
+)
+@click.option(
+    "--seed",
+    default=None,
+    type=int,
+    help="Random seed for reproducibility (overrides config)",
+)
+def plot(
+    config_file: str,
+    simulations: int,
+    output: Optional[str],
+    cumulative: bool,
+    kde: bool,
+    percentiles: Tuple[int, ...],
+    seed: Optional[int],
+) -> None:
+    """Generate visualization of simulation results.
+
+    CONFIG_FILE: Path to the YAML project configuration file.
+
+    Examples:
+        planaco plot project.yaml -o chart.png
+
+        planaco plot project.yaml --cumulative
+
+        planaco plot project.yaml -p 50 -p 85 -p 95
+    """
+    try:
+        config = load_config(config_file)
+        _setup_seed(config, seed)
+        project = build_project_from_config(config)
+
+        percentiles_list = list(percentiles) if percentiles else None
+        show_percentiles = bool(percentiles_list)
+
+        project.plot(
+            n=simulations,
+            hist=not cumulative,
+            kde=kde,
+            save_path=output,
+            show_percentiles=show_percentiles,
+            percentiles=percentiles_list,
+        )
+
+        if output:
+            click.secho(f"Plot saved to {output}", fg="green")
+
+    except (ConfigError, FileNotFoundError) as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.argument("config_file", type=click.Path(exists=True))
+@click.option(
+    "-o", "--output", default=None, help="Save graph to file instead of displaying"
+)
+@click.option("--no-durations", is_flag=True, help="Hide duration information on nodes")
+def graph(config_file: str, output: Optional[str], no_durations: bool) -> None:
+    """Visualize the task dependency graph.
+
+    CONFIG_FILE: Path to the YAML project configuration file.
+
+    Examples:
+        planaco graph project.yaml
+
+        planaco graph project.yaml -o dependencies.png
+    """
+    try:
+        config = load_config(config_file)
+        project = build_project_from_config(config)
+
+        project.plot_dependency_graph(save_path=output, show_durations=not no_durations)
+
+        if output:
+            click.secho(f"Dependency graph saved to {output}", fg="green")
+
+    except (ConfigError, FileNotFoundError) as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+
+
+def _print_stats(project_name: Optional[str], stats: dict) -> None:
+    """Print formatted statistics to stdout."""
+    click.echo()
+    click.secho(f"Project: {project_name or 'Unnamed'}", fg="cyan", bold=True)
+    click.secho("=" * 50, fg="cyan")
+    click.echo()
+
+    click.echo(f"Simulations: {stats['n_simulations']:,}")
+    click.echo(f"Time Unit: {stats['unit']}")
+    click.echo()
+
+    click.secho("Duration Estimates:", bold=True)
+    click.echo(f"  Mean:              {stats['mean']:.1f} {stats['unit']}")
+    click.echo(f"  Median (P50):      {stats['median']:.1f} {stats['unit']}")
+    click.echo(f"  Std Deviation:     {stats['std_dev']:.1f} {stats['unit']}")
+    click.echo(f"  Min:               {stats['min']:.1f} {stats['unit']}")
+    click.echo(f"  Max:               {stats['max']:.1f} {stats['unit']}")
+    click.echo()
+
+    click.secho("Percentiles:", bold=True)
+    for key, value in stats["percentiles"].items():
+        label = key.upper()
+        click.echo(f"  {label}:              {value:.1f} {stats['unit']}")
+    click.echo()
+
+    ci = stats["confidence_intervals"]["95%"]
+    click.secho("Confidence Interval:", bold=True)
+    click.echo(f"  95% CI:            [{ci[0]:.1f}, {ci[1]:.1f}] {stats['unit']}")
+    click.echo()
+
+
+if __name__ == "__main__":
+    main()