AI, ML & Software Engineering — Sample

# Software, ML, and AI Engineering
# (c) Dr. Yves J. Hilpisch
# AI-Powered by GPT-5.

"""A tiny CLI that computes a reproducible mean and stdev.

Run:
  python code/ch01/mini_cli.py --seed 42 --n 5
"""

from __future__ import annotations  # postpone annotations

import argparse  # parse command-line flags
import random  # deterministic RNG with a seed
import statistics as stats  # mean and stdev utilities


def compute_values(seed: int, n: int) -> tuple[list[float], float, float]:
    """Generate n pseudo-random floats deterministically and summarize.

    Args:
        seed: RNG seed for reproducibility.
        n: number of values to generate (> 0).

    Returns:
        A tuple of (values, mean, stdev).
    """
    rng = random.Random(seed)  # create an isolated RNG
    values = [rng.random() for _ in range(n)]  # n floats in [0, 1)
    mu = stats.fmean(values)  # compute mean (float)
    # Use population stdev for a tiny demo; either is fine when stated.
    sigma = stats.pstdev(values)  # population standard deviation
    return values, mu, sigma  # return both raw values and summary


def build_parser() -> argparse.ArgumentParser:
    """Create the CLI argument parser."""
    p = argparse.ArgumentParser(
        description="Compute a reproducible mean and stdev."
    )
    p.add_argument(
        "--seed", type=int, default=123, help="RNG seed (int)."
    )
    p.add_argument(
        "--n",
        type=int,
        default=5,
        help="Number of values to generate (>0).",
    )
    return p  # return configured parser


def main() -> None:
    """Entry point for the CLI."""
    args = build_parser().parse_args()  # parse flags from sys.argv
    if args.n <= 0:  # validate the input
        raise SystemExit("--n must be > 0")  # exit with a clear error
    values, mu, sigma = compute_values(args.seed, args.n)  # run computation
    # Print a concise, verifiable summary (copy-pastable into tests if needed).
    print(
        f"seed={args.seed} n={args.n} mean={mu:.6f} stdev={sigma:.6f}"
    )  # user-facing output


if __name__ == "__main__":  # only run when executed as a script
    main()  # invoke the CLI entry

$ # Run the CLI twice with different seeds
$ python code/ch01/mini_cli.py --seed 42 --n 5
$ python code/ch01/mini_cli.py --seed 1 --n 5