trueppm-scheduler 0.1.0a1__tar.gz

trueppm_scheduler-0.1.0a1/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.eggs/
+dist/
+build/
+.cache/pip/
+.venv/
+venv/
+env/
+
+# Mypy / Ruff / Pytest
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Node
+node_modules/
+
+# Coverage
+coverage/
+coverage.xml
+
+# uv lockfile — trueppm-scheduler is a library; lockfile not committed
+uv.lock
+
+# Docker
+*.override.yml
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Docusaurus build cache
+.docusaurus/
+
+# Claude Code runtime state
+.claude/scheduled_tasks.lock
+.claude/worktrees/
+
+# Playwright test runtime output
+test-results/
+packages/web/test-results/
+packages/web/playwright-report/

trueppm_scheduler-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,144 @@
+# Contributing to trueppm-scheduler
+
+The scheduler is a pure Python library with no Django dependency.
+It ships independently as `trueppm-scheduler` on PyPI and is also consumed
+by the TruePPM Django API as a service-layer dependency.
+
+## Prerequisites
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/) (recommended) or `pip`
+
+```bash
+# Install with dev dependencies using uv
+cd packages/scheduler
+uv sync --extra dev
+
+# Or with pip
+pip install -e ".[dev]"
+```
+
+## Running the tests
+
+```bash
+cd packages/scheduler
+pytest                          # all tests, short output
+pytest -v                       # verbose
+pytest tests/test_engine.py -x  # stop on first failure
+```
+
+### Performance benchmarks
+
+The bench suite asserts hard time budgets. Run it before submitting a MR
+that touches the engine:
+
+```bash
+pytest tests/test_bench.py -v
+```
+
+Expected output:
+
+```
+PASSED tests/test_bench.py::test_schedule_performance[100-tasks]
+PASSED tests/test_bench.py::test_schedule_performance[500-tasks]
+```
+
+If either test fails, profile before investigating — a warm-up run is included
+to exclude import-time costs, so a failure indicates a genuine algorithmic
+regression.
+
+## Linting and type checking
+
+```bash
+ruff check src tests    # lint
+ruff format src tests   # format
+mypy src                # strict type check
+```
+
+CI runs all three on every MR. Fixes must address root causes — do not use
+`# type: ignore` or `# noqa` to silence errors.
+
+## Interactive notebooks
+
+The `notebooks/` directory contains Jupyter notebooks that serve as
+executable documentation:
+
+| Notebook | Topic |
+|----------|-------|
+| `01-cpm-quickstart.ipynb` | Project definition, CPM, float table, cycle detection |
+| `02-monte-carlo.ipynb` | PERT estimates, Monte Carlo, P50/P80/P95 |
+| `03-calendar-aware.ipynb` | Custom working weeks, holiday exceptions, lag |
+| `04-incremental-scheduling.ipynb` | Incremental CPM, fallback behaviour, bench targets |
+
+Run them locally:
+
+```bash
+pip install -e ".[dev]" jupyter matplotlib
+jupyter notebook notebooks/
+```
+
+The `scheduler:notebooks` CI job executes all notebooks with `jupyter nbconvert
+--execute` to catch regressions. A notebook cell that raises an exception fails
+the job.
+
+## Adding a new notebook
+
+1. Create `notebooks/0N-topic.ipynb` with a markdown header cell explaining
+   the topic and install instructions.
+2. Keep each cell self-contained — cells are run top-to-bottom by CI.
+3. Avoid dependencies outside `trueppm-scheduler` and `matplotlib`
+   (already installed in the CI image). Use a `try/import` guard for
+   optional visualisation libraries.
+4. Add a row to the table in `docs/features/scheduler.md`.
+
+## Project structure
+
+```
+packages/scheduler/
+├── src/
+│   └── trueppm_scheduler/
+│       ├── __init__.py     # Public API exports
+│       ├── models.py       # Data classes: Task, Dependency, Project, Calendar
+│       ├── engine.py       # schedule(), monte_carlo(), CPM algorithms
+│       └── cli.py          # CLI entry point (trueppm-scheduler command)
+├── tests/
+│   ├── test_engine.py      # Unit tests for schedule() and monte_carlo()
+│   ├── test_bench.py       # Performance regression guard
+│   └── conftest.py         # Shared fixtures
+├── notebooks/              # Executable documentation (see above)
+├── pyproject.toml
+└── CONTRIBUTING.md         # This file
+```
+
+## Design constraints
+
+1. **Zero Django dependency.** The scheduler must import and run in any Python
+   environment without Django installed. Never import from `django` or
+   `trueppm_api` inside `src/trueppm_scheduler/`.
+
+2. **Pure data in, pure data out.** `schedule()` and `monte_carlo()` accept
+   `Project` dataclasses and return `ScheduleResult` / `MonteCarloResult`
+   dataclasses. No side effects, no I/O.
+
+3. **Deterministic at a given seed.** Monte Carlo results are reproducible when
+   `seed` is provided. Do not introduce sources of non-determinism outside the
+   PERT sampler.
+
+4. **Incremental results must match full recompute.** Any change to the
+   incremental path must pass `tests/test_incremental_equivalence.py`, which
+   asserts result equality across 1000 random scenarios.
+
+## Commit and MR conventions
+
+See the [Contributing guide](https://docs.trueppm.com/contributing/guide/) for
+branch naming, commit format, and changelog fragments. The short version:
+
+```bash
+git checkout -b feat/scheduler-<topic>      # or fix/, docs/, perf/
+# make changes
+git commit -m "feat(scheduler): <description>"
+# create changelog fragment: changelog.d/<issue>.<type>.md
+```
+
+All scheduler MRs require a green `scheduler:lint`, `scheduler:type-check`,
+`scheduler:test`, and `scheduler:bench` pipeline.

trueppm_scheduler-0.1.0a1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: trueppm-scheduler
+Version: 0.1.0a1
+Summary: Critical-path and resource-leveling scheduler for project management
+Project-URL: Homepage, https://gitlab.com/trueppm/trueppm
+Project-URL: Repository, https://gitlab.com/trueppm/trueppm
+Project-URL: Issues, https://gitlab.com/trueppm/trueppm/-/issues
+Author: Kelly Hair
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.11
+Requires-Dist: networkx>=3.0
+Requires-Dist: numpy>=1.26
+Provides-Extra: dev
+Requires-Dist: diff-cover>=9.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: types-networkx>=3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# trueppm-scheduler
+
+[![PyPI version](https://img.shields.io/pypi/v/trueppm-scheduler.svg)](https://pypi.org/project/trueppm-scheduler/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/trueppm-scheduler.svg)](https://pypi.org/project/trueppm-scheduler/)
+[![CI](https://gitlab.com/trueppm/trueppm/badges/main/pipeline.svg)](https://gitlab.com/trueppm/trueppm/-/pipelines)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+Pure-Python CPM scheduling engine for TruePPM. Ships independently on PyPI — no Django dependency.
+
+## Features
+
+- Forward/backward CPM pass with all four dependency types (FS, SS, FF, SF)
+- Calendar-aware working-day arithmetic (weekend skip + holiday exceptions)
+- Monte Carlo simulation via PERT-Beta distributions (numpy-vectorised, ~10k runs/sec)
+- CLI: `trueppm-scheduler schedule` / `trueppm-scheduler monte-carlo`
+
+## Install
+
+```bash
+pip install trueppm-scheduler
+```
+
+## Quick start
+
+```python
+from datetime import date, timedelta
+from trueppm_scheduler import schedule, Calendar, Project, Task, Dependency, DependencyType
+
+calendar = Calendar()  # Mon–Fri, 8 h/day, no holidays
+task_a = Task(id="t-1", name="Design", duration=timedelta(days=5))
+task_b = Task(id="t-2", name="Build",  duration=timedelta(days=10))
+dep = Dependency(predecessor_id="t-1", successor_id="t-2", dep_type=DependencyType.FS)
+
+project = Project(
+    id="p-1",
+    name="My Project",
+    start_date=date(2026, 1, 5),
+    tasks=[task_a, task_b],
+    dependencies=[dep],
+    calendar=calendar,
+)
+
+result = schedule(project)
+build = next(t for t in result.tasks if t.id == "t-2")
+print(build.early_finish)  # 2026-01-21 (5 + 10 working days from 2026-01-05)
+```
+
+See [the full documentation](https://docs.trueppm.com/features/scheduler) for CPM output fields, Monte Carlo usage, and CLI reference.
+
+## License
+
+Apache 2.0

trueppm_scheduler-0.1.0a1/README.md

@@ -0,0 +1,52 @@
+# trueppm-scheduler
+
+[![PyPI version](https://img.shields.io/pypi/v/trueppm-scheduler.svg)](https://pypi.org/project/trueppm-scheduler/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/trueppm-scheduler.svg)](https://pypi.org/project/trueppm-scheduler/)
+[![CI](https://gitlab.com/trueppm/trueppm/badges/main/pipeline.svg)](https://gitlab.com/trueppm/trueppm/-/pipelines)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+Pure-Python CPM scheduling engine for TruePPM. Ships independently on PyPI — no Django dependency.
+
+## Features
+
+- Forward/backward CPM pass with all four dependency types (FS, SS, FF, SF)
+- Calendar-aware working-day arithmetic (weekend skip + holiday exceptions)
+- Monte Carlo simulation via PERT-Beta distributions (numpy-vectorised, ~10k runs/sec)
+- CLI: `trueppm-scheduler schedule` / `trueppm-scheduler monte-carlo`
+
+## Install
+
+```bash
+pip install trueppm-scheduler
+```
+
+## Quick start
+
+```python
+from datetime import date, timedelta
+from trueppm_scheduler import schedule, Calendar, Project, Task, Dependency, DependencyType
+
+calendar = Calendar()  # Mon–Fri, 8 h/day, no holidays
+task_a = Task(id="t-1", name="Design", duration=timedelta(days=5))
+task_b = Task(id="t-2", name="Build",  duration=timedelta(days=10))
+dep = Dependency(predecessor_id="t-1", successor_id="t-2", dep_type=DependencyType.FS)
+
+project = Project(
+    id="p-1",
+    name="My Project",
+    start_date=date(2026, 1, 5),
+    tasks=[task_a, task_b],
+    dependencies=[dep],
+    calendar=calendar,
+)
+
+result = schedule(project)
+build = next(t for t in result.tasks if t.id == "t-2")
+print(build.early_finish)  # 2026-01-21 (5 + 10 working days from 2026-01-05)
+```
+
+See [the full documentation](https://docs.trueppm.com/features/scheduler) for CPM output fields, Monte Carlo usage, and CLI reference.
+
+## License
+
+Apache 2.0

trueppm_scheduler-0.1.0a1/notebooks/01-cpm-quickstart.ipynb

@@ -0,0 +1,277 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# CPM Scheduling — Quick Start\n",
+    "\n",
+    "This notebook walks through the core `trueppm-scheduler` API:\n",
+    "building a project, running the Critical Path Method (CPM), and\n",
+    "reading the results.\n",
+    "\n",
+    "**Install**\n",
+    "```bash\n",
+    "pip install trueppm-scheduler\n",
+    "```\n",
+    "\n",
+    "Or from the monorepo:\n",
+    "```bash\n",
+    "pip install -e packages/scheduler\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from datetime import date, timedelta\n",
+    "from trueppm_scheduler import (\n",
+    "    Calendar, DateRange, Dependency, DependencyType,\n",
+    "    Project, Task, schedule, CyclicDependencyError,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. Define the project\n",
+    "\n",
+    "We model a simple software release: Design → (Build + Test in parallel) → Deploy."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Calendar: Mon–Fri, no holidays (default)\n",
+    "cal = Calendar()  # working_days=0b0011111 (Mon=bit0 .. Sun=bit6)\n",
+    "\n",
+    "tasks = [\n",
+    "    Task(id=\"design\",  name=\"Design\",  duration=timedelta(days=5)),\n",
+    "    Task(id=\"build\",   name=\"Build\",   duration=timedelta(days=10)),\n",
+    "    Task(id=\"test\",    name=\"Test\",    duration=timedelta(days=7)),\n",
+    "    Task(id=\"deploy\",  name=\"Deploy\",  duration=timedelta(days=2)),\n",
+    "]\n",
+    "\n",
+    "dependencies = [\n",
+    "    Dependency(predecessor_id=\"design\", successor_id=\"build\"),    # FS (default)\n",
+    "    Dependency(predecessor_id=\"design\", successor_id=\"test\"),     # FS\n",
+    "    Dependency(predecessor_id=\"build\",  successor_id=\"deploy\"),   # FS\n",
+    "    Dependency(predecessor_id=\"test\",   successor_id=\"deploy\"),   # FS\n",
+    "]\n",
+    "\n",
+    "project = Project(\n",
+    "    id=\"release-v1\",\n",
+    "    name=\"Release v1.0\",\n",
+    "    start_date=date(2026, 4, 1),\n",
+    "    tasks=tasks,\n",
+    "    dependencies=dependencies,\n",
+    "    calendar=cal,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. Run CPM"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "result = schedule(project)\n",
+    "print(f\"Project start:  {result.project_start}\")\n",
+    "print(f\"Project finish: {result.project_finish}\")\n",
+    "print(f\"Critical path:  {' → '.join(result.critical_path)}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. Inspect per-task results\n",
+    "\n",
+    "Each task in `result.tasks` has its ES/EF/LS/LF and float populated."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(f\"{'Task':<10} {'ES':>12} {'EF':>12} {'LS':>12} {'LF':>12} {'Float':>6} {'Critical':>8}\")\n",
+    "print(\"-\" * 72)\n",
+    "for t in result.tasks:\n",
+    "    float_days = t.total_float.days\n",
+    "    print(\n",
+    "        f\"{t.name:<10} {str(t.early_start):>12} {str(t.early_finish):>12}\"\n",
+    "        f\" {str(t.late_start):>12} {str(t.late_finish):>12}\"\n",
+    "        f\" {float_days:>6} {'✓' if t.is_critical else '':>8}\"\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. Custom calendar: add a holiday\n",
+    "\n",
+    "The Good Friday bank holiday shifts the schedule by one working day."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cal_with_holiday = Calendar(\n",
+    "    exceptions=[\n",
+    "        DateRange(start=date(2026, 4, 3), end=date(2026, 4, 3)),  # Good Friday\n",
+    "    ]\n",
+    ")\n",
+    "\n",
+    "project_with_holiday = Project(\n",
+    "    id=\"release-v1-holiday\",\n",
+    "    name=\"Release v1.0 (with holiday)\",\n",
+    "    start_date=date(2026, 4, 1),\n",
+    "    tasks=[\n",
+    "        Task(id=t.id, name=t.name, duration=t.duration) for t in tasks\n",
+    "    ],\n",
+    "    dependencies=[\n",
+    "        Dependency(predecessor_id=d.predecessor_id, successor_id=d.successor_id)\n",
+    "        for d in dependencies\n",
+    "    ],\n",
+    "    calendar=cal_with_holiday,\n",
+    ")\n",
+    "\n",
+    "result_holiday = schedule(project_with_holiday)\n",
+    "print(f\"Without holiday: {result.project_finish}\")\n",
+    "print(f\"With holiday:    {result_holiday.project_finish}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 5. SS / FF / SF dependency types\n",
+    "\n",
+    "Non-FS dependencies model parallel work with constraints."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# SS with 2-day lag: testing can start 2 days after coding starts\n",
+    "coding = Task(id=\"code\",  name=\"Code\",  duration=timedelta(days=10))\n",
+    "testing = Task(id=\"test2\", name=\"Test\",  duration=timedelta(days=8))\n",
+    "\n",
+    "p2 = Project(\n",
+    "    id=\"p2\",\n",
+    "    name=\"SS example\",\n",
+    "    start_date=date(2026, 4, 1),\n",
+    "    tasks=[coding, testing],\n",
+    "    dependencies=[\n",
+    "        Dependency(\n",
+    "            predecessor_id=\"code\",\n",
+    "            successor_id=\"test2\",\n",
+    "            dep_type=DependencyType.SS,\n",
+    "            lag=timedelta(days=2),\n",
+    "        )\n",
+    "    ],\n",
+    ")\n",
+    "\n",
+    "r2 = schedule(p2)\n",
+    "for t in r2.tasks:\n",
+    "    print(f\"{t.name}: {t.early_start} → {t.early_finish}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 6. Cycle detection"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "t_a = Task(id=\"a\", name=\"A\", duration=timedelta(days=3))\n",
+    "t_b = Task(id=\"b\", name=\"B\", duration=timedelta(days=3))\n",
+    "\n",
+    "p_cycle = Project(\n",
+    "    id=\"p-cycle\",\n",
+    "    name=\"Cycle example\",\n",
+    "    start_date=date(2026, 4, 1),\n",
+    "    tasks=[t_a, t_b],\n",
+    "    dependencies=[\n",
+    "        Dependency(predecessor_id=\"a\", successor_id=\"b\"),\n",
+    "        Dependency(predecessor_id=\"b\", successor_id=\"a\"),  # cycle!\n",
+    "    ],\n",
+    ")\n",
+    "\n",
+    "try:\n",
+    "    schedule(p_cycle)\n",
+    "except CyclicDependencyError as e:\n",
+    "    print(f\"Caught cycle: {' → '.join(e.cycle)}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 7. Serialising a project to JSON\n",
+    "\n",
+    "`Project.to_json()` / `Project.from_json()` round-trip all fields."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json\n",
+    "\n",
+    "json_str = project.to_json(indent=2)\n",
+    "print(json_str[:400], \"...\")\n",
+    "\n",
+    "# Round-trip\n",
+    "project_rt = Project.from_json(json_str)\n",
+    "result_rt = schedule(project_rt)\n",
+    "assert result_rt.project_finish == result.project_finish\n",
+    "print(\"\\nRound-trip OK:\", result_rt.project_finish)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}