lss4py 0.1.0__tar.gz

lss4py-0.1.0/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: lss4py
+Version: 0.1.0
+Summary: Python-first Lean Six Sigma analytics for telemetry-rich process improvement
+Author: shanewilkins
+Author-email: shanewilkins <shane@wilkinsadvisors.com>
+License-Expression: MIT
+Requires-Dist: click>=8.1.0
+Requires-Dist: numpy>=2.2.0
+Requires-Dist: opentelemetry-api>=1.31.0
+Requires-Dist: opentelemetry-exporter-otlp>=1.31.0
+Requires-Dist: opentelemetry-sdk>=1.31.0
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: scipy>=1.15.0
+Requires-Dist: statsmodels>=0.14.0
+Requires-Dist: structlog>=24.4.0
+Requires-Dist: pulp>=2.9.0 ; extra == 'optimization'
+Requires-Dist: pyomo>=6.8.0 ; extra == 'optimization'
+Requires-Dist: pm4py>=2.7.0 ; extra == 'process-mining'
+Requires-Dist: simpy>=4.1.0 ; extra == 'simulation'
+Requires-Dist: duckdb>=1.2.0 ; extra == 'storage'
+Requires-Dist: pyarrow>=19.0.0 ; extra == 'storage'
+Requires-Dist: matplotlib>=3.10.0 ; extra == 'visualization'
+Requires-Dist: seaborn>=0.13.0 ; extra == 'visualization'
+Requires-Python: >=3.14, <3.15
+Provides-Extra: optimization
+Provides-Extra: process-mining
+Provides-Extra: simulation
+Provides-Extra: storage
+Provides-Extra: visualization
+Description-Content-Type: text/markdown
+
+# LSS4PY
+
+LSS4PY is a Python 3.14 Lean Six Sigma utility library for the current Yellow Belt slice.
+
+It is focused on repeatable process metrics and yield calculations.
+
+It is not yet a full SPC, capability, simulation, or deliverables platform.
+
+## Stable Today
+
+The current stable surface is intentionally small.
+
+It includes these public functions:
+
+- `lead_time`
+- `wait_time`
+- `process_cycle_efficiency`
+- `takt_time`
+- `created_to_booked_yield`
+- `booked_to_completed_yield`
+- `rolled_yield`
+
+It also includes a process-model IR for integrating FLO-derived process structure with observed tabular data:
+
+- `ProcessModelIR`
+- `ProcessStepIR`
+- `ProcessEdgeIR`
+- `MetricBindingsIR`
+- `LeadTimeBindingIR`
+- `StageBindingsIR`
+- `MetricSemanticsIR`
+- `EventLogBindingsIR`
+
+It also includes stable event-log contracts and helpers:
+
+- `EventLog`
+- `validate_event_log`
+- `map_process`
+
+Topology-aware event-log calculations are also part of the current stable surface for:
+
+- `lead_time`
+- `wait_time`
+- `process_cycle_efficiency`
+
+## Contract
+
+LSS4PY works from two inputs.
+
+The FLO side supplies a normalized process model IR.
+
+The pandas side supplies observed process data.
+
+That is the current implementation contract. Proposed
+[ADR-0004](docs/adr/0004-support-dataframe-neutral-inputs-and-results.md) replaces
+the concrete pandas dependency with a tested dataframe-neutral boundary before the
+analytical surface expands.
+
+LSS4PY calculates metrics from both.
+
+The IR defines process structure and semantic bindings.
+
+The DataFrame provides timestamps, stage outcomes, and measured times.
+
+Explicit per-call metric arguments override IR bindings.
+
+Parallel paths and rework loops are represented in the IR with explicit graph edges.
+
+Event-log rows are the canonical observed data shape for process-model-aware metrics.
+
+The default elapsed-time interpretation for parallel paths is `critical_path` semantics.
+
+An alternate `sum_all_branches` interpretation is also supported for event-log-aware calculations.
+
+## Quick Start
+
+### Requirements
+
+- Python 3.14
+- `uv`
+
+### Install
+
+```bash
+uv sync
+```
+
+### Verify
+
+```bash
+uv run python -c "import lss4py; print('lss4py ready')"
+```
+
+## Example
+
+```python
+import pandas as pd
+
+from lss4py import (
+	LeadTimeBindingIR,
+	MetricBindingsIR,
+	MetricSemanticsIR,
+	ProcessEdgeIR,
+	ProcessModelIR,
+	ProcessStepIR,
+	StageBindingsIR,
+	created_to_booked_yield,
+	lead_time,
+	process_cycle_efficiency,
+	rolled_yield,
+	wait_time,
+)
+
+process_model = ProcessModelIR(
+	name="Client intake",
+	steps=[
+		ProcessStepIR(
+			id="review",
+			name="Review",
+			cycle_time_column="review_hours",
+			value_classification="non_value_add",
+		),
+		ProcessStepIR(
+			id="approve",
+			name="Approve",
+			cycle_time_column="approval_hours",
+			value_classification="value_add",
+		),
+	],
+	edges=[
+		ProcessEdgeIR(source_step_id="review", target_step_id="approve", kind="sequence"),
+		ProcessEdgeIR(source_step_id="approve", target_step_id="review", kind="rework"),
+	],
+	bindings=MetricBindingsIR(
+		lead_time=LeadTimeBindingIR(
+			start_column="created_at",
+			end_column="completed_at",
+		),
+		stages=StageBindingsIR(
+			created="created",
+			booked="booked",
+			completed="completed",
+		),
+	),
+	metric_semantics=MetricSemanticsIR(parallel_timing="critical_path"),
+)
+
+data = pd.DataFrame(
+	{
+		"created_at": ["2026-01-01T08:00:00", "2026-01-02T09:00:00"],
+		"completed_at": ["2026-01-01T18:00:00", "2026-01-02T15:00:00"],
+		"review_hours": [2.0, 1.0],
+		"approval_hours": [1.0, 2.0],
+		"created": [1, 1],
+		"booked": [1, 1],
+		"completed": [1, 0],
+	}
+)
+
+lead = lead_time(data, process_model=process_model)
+wait = wait_time(data, process_model=process_model)
+pce = process_cycle_efficiency(data, process_model=process_model)
+created_booked = created_to_booked_yield(data, process_model=process_model)
+rolled = rolled_yield(data, process_model=process_model)
+```
+
+## API Summary
+
+### Basic Process Metrics
+
+- `lead_time(data, ..., process_model=None)` returns per-row elapsed time from start to end timestamps.
+- `wait_time(data, ..., process_model=None)` returns per-row lead time minus active cycle time.
+- `process_cycle_efficiency(data, ..., process_model=None)` returns per-row value-add time divided by lead time.
+- `takt_time(available_time=..., customer_demand=...)` returns a scalar pace target.
+
+### Yield Helpers
+
+- `created_to_booked_yield(data, ..., process_model=None)` returns first-stage conversion yield.
+- `booked_to_completed_yield(data, ..., process_model=None)` returns second-stage conversion yield.
+- `rolled_yield(data, ..., process_model=None)` returns end-to-end rolled yield.
+
+### Process Model IR
+
+- `ProcessModelIR` is the top-level FLO-compatible process model contract.
+- `ProcessStepIR` defines step ids, names, cycle-time columns, and value classification.
+- `ProcessEdgeIR` defines sequence, parallel split, parallel join, and rework edges.
+- `MetricBindingsIR` groups lead-time and stage-column bindings.
+- `MetricSemanticsIR` defines process-metric interpretation defaults such as parallel timing.
+- `EventLogBindingsIR` defines the case, step, start, and end columns for event-log-aware metrics.
+
+### Event-Log Contracts And Helpers
+
+- `EventLog` represents the observed event-log contract used by stable event-log helpers.
+- `validate_event_log(event_log)` returns machine-readable warnings for empty logs or missing required event fields.
+- `map_process(event_log)` returns discovered activity nodes and transition counts from observed event order.
+
+### Topology-Aware Event-Log Metrics
+
+- event-log-aware `lead_time` uses per-case event boundaries from observed rows.
+- event-log-aware `wait_time` supports branch-aware elapsed work from explicit parallel edges.
+- event-log-aware `process_cycle_efficiency` supports value-add calculations across parallel and rework-aware event logs.
+- repeated step occurrences require explicit rework edges in the process model.
+- overlapping step intervals require explicit parallel edges in the process model.
+
+## What Is Not Stable Yet
+
+These areas are not part of the stable book-facing API today:
+
+- capability analysis
+- SPC reporting
+- simulation workflows
+- bottleneck workflows
+- before/after comparison workflows
+- reporting bundles
+- automatic `.flo` parsing inside `lss4py`
+
+The IR and metric engine now support stable topology-aware event-log calculations for the current Yellow Belt slice.
+
+Broader graph-driven semantics outside that slice are still future work.
+
+## Development Status
+
+This repository is in active pre-1.0 development.
+
+The Yellow Belt metric surface above is the current stable target.
+
+Other modules and ideas in the repository should be treated as experimental, internal, or future work unless they are explicitly listed in the stable surface.
+
+## Validation
+
+The repository is currently validated with:
+
+- `uv lock --check`
+- `uv run --locked lint-imports`
+- `uv sync`
+- `uv run --locked ruff check .`
+- `uv run --locked pyright`
+- `uv run --locked xenon --max-absolute B --max-modules A --max-average A src/lss4py tests`
+- `uv run --locked pytest`
+- `uv run --locked vulture src tests --min-confidence 80`
+
+Install both local hook stages with:
+
+```bash
+uv run pre-commit install --install-hooks --hook-type pre-commit --hook-type pre-push
+```
+
+The `pre-commit` stage runs Ruff on changed files and the locked test suite without coverage.
+
+The `pre-push` stage and CI run the full locked repository-wide gates.
+
+CI additionally enforces 95% coverage on the current supported slice and runs a
+built-wheel smoke test outside the source tree.
+
+## Roadmap
+
+The governed [roadmap](docs/roadmap.md) targets a complete Yellow Belt MVP at
+v0.3, Green Belt capability at v0.5, Black Belt capability at v0.7, and a
+feature-frozen polish phase at v0.9 before the stable 1.0 contract.
+
+See the [documentation index](docs/README.md) for user requirements, technical
+requirements, ADRs, and governance conventions. R `SixSigma` coverage is tracked
+separately in the [compatibility matrix](docs/sixsigma-compatibility.md).
+
+## License
+
+LSS4PY is available under the [MIT License](LICENSE.md).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to contribute and
+[SECURITY.md](SECURITY.md) to report a vulnerability privately.

lss4py-0.1.0/README.md

@@ -0,0 +1,270 @@
+# LSS4PY
+
+LSS4PY is a Python 3.14 Lean Six Sigma utility library for the current Yellow Belt slice.
+
+It is focused on repeatable process metrics and yield calculations.
+
+It is not yet a full SPC, capability, simulation, or deliverables platform.
+
+## Stable Today
+
+The current stable surface is intentionally small.
+
+It includes these public functions:
+
+- `lead_time`
+- `wait_time`
+- `process_cycle_efficiency`
+- `takt_time`
+- `created_to_booked_yield`
+- `booked_to_completed_yield`
+- `rolled_yield`
+
+It also includes a process-model IR for integrating FLO-derived process structure with observed tabular data:
+
+- `ProcessModelIR`
+- `ProcessStepIR`
+- `ProcessEdgeIR`
+- `MetricBindingsIR`
+- `LeadTimeBindingIR`
+- `StageBindingsIR`
+- `MetricSemanticsIR`
+- `EventLogBindingsIR`
+
+It also includes stable event-log contracts and helpers:
+
+- `EventLog`
+- `validate_event_log`
+- `map_process`
+
+Topology-aware event-log calculations are also part of the current stable surface for:
+
+- `lead_time`
+- `wait_time`
+- `process_cycle_efficiency`
+
+## Contract
+
+LSS4PY works from two inputs.
+
+The FLO side supplies a normalized process model IR.
+
+The pandas side supplies observed process data.
+
+That is the current implementation contract. Proposed
+[ADR-0004](docs/adr/0004-support-dataframe-neutral-inputs-and-results.md) replaces
+the concrete pandas dependency with a tested dataframe-neutral boundary before the
+analytical surface expands.
+
+LSS4PY calculates metrics from both.
+
+The IR defines process structure and semantic bindings.
+
+The DataFrame provides timestamps, stage outcomes, and measured times.
+
+Explicit per-call metric arguments override IR bindings.
+
+Parallel paths and rework loops are represented in the IR with explicit graph edges.
+
+Event-log rows are the canonical observed data shape for process-model-aware metrics.
+
+The default elapsed-time interpretation for parallel paths is `critical_path` semantics.
+
+An alternate `sum_all_branches` interpretation is also supported for event-log-aware calculations.
+
+## Quick Start
+
+### Requirements
+
+- Python 3.14
+- `uv`
+
+### Install
+
+```bash
+uv sync
+```
+
+### Verify
+
+```bash
+uv run python -c "import lss4py; print('lss4py ready')"
+```
+
+## Example
+
+```python
+import pandas as pd
+
+from lss4py import (
+	LeadTimeBindingIR,
+	MetricBindingsIR,
+	MetricSemanticsIR,
+	ProcessEdgeIR,
+	ProcessModelIR,
+	ProcessStepIR,
+	StageBindingsIR,
+	created_to_booked_yield,
+	lead_time,
+	process_cycle_efficiency,
+	rolled_yield,
+	wait_time,
+)
+
+process_model = ProcessModelIR(
+	name="Client intake",
+	steps=[
+		ProcessStepIR(
+			id="review",
+			name="Review",
+			cycle_time_column="review_hours",
+			value_classification="non_value_add",
+		),
+		ProcessStepIR(
+			id="approve",
+			name="Approve",
+			cycle_time_column="approval_hours",
+			value_classification="value_add",
+		),
+	],
+	edges=[
+		ProcessEdgeIR(source_step_id="review", target_step_id="approve", kind="sequence"),
+		ProcessEdgeIR(source_step_id="approve", target_step_id="review", kind="rework"),
+	],
+	bindings=MetricBindingsIR(
+		lead_time=LeadTimeBindingIR(
+			start_column="created_at",
+			end_column="completed_at",
+		),
+		stages=StageBindingsIR(
+			created="created",
+			booked="booked",
+			completed="completed",
+		),
+	),
+	metric_semantics=MetricSemanticsIR(parallel_timing="critical_path"),
+)
+
+data = pd.DataFrame(
+	{
+		"created_at": ["2026-01-01T08:00:00", "2026-01-02T09:00:00"],
+		"completed_at": ["2026-01-01T18:00:00", "2026-01-02T15:00:00"],
+		"review_hours": [2.0, 1.0],
+		"approval_hours": [1.0, 2.0],
+		"created": [1, 1],
+		"booked": [1, 1],
+		"completed": [1, 0],
+	}
+)
+
+lead = lead_time(data, process_model=process_model)
+wait = wait_time(data, process_model=process_model)
+pce = process_cycle_efficiency(data, process_model=process_model)
+created_booked = created_to_booked_yield(data, process_model=process_model)
+rolled = rolled_yield(data, process_model=process_model)
+```
+
+## API Summary
+
+### Basic Process Metrics
+
+- `lead_time(data, ..., process_model=None)` returns per-row elapsed time from start to end timestamps.
+- `wait_time(data, ..., process_model=None)` returns per-row lead time minus active cycle time.
+- `process_cycle_efficiency(data, ..., process_model=None)` returns per-row value-add time divided by lead time.
+- `takt_time(available_time=..., customer_demand=...)` returns a scalar pace target.
+
+### Yield Helpers
+
+- `created_to_booked_yield(data, ..., process_model=None)` returns first-stage conversion yield.
+- `booked_to_completed_yield(data, ..., process_model=None)` returns second-stage conversion yield.
+- `rolled_yield(data, ..., process_model=None)` returns end-to-end rolled yield.
+
+### Process Model IR
+
+- `ProcessModelIR` is the top-level FLO-compatible process model contract.
+- `ProcessStepIR` defines step ids, names, cycle-time columns, and value classification.
+- `ProcessEdgeIR` defines sequence, parallel split, parallel join, and rework edges.
+- `MetricBindingsIR` groups lead-time and stage-column bindings.
+- `MetricSemanticsIR` defines process-metric interpretation defaults such as parallel timing.
+- `EventLogBindingsIR` defines the case, step, start, and end columns for event-log-aware metrics.
+
+### Event-Log Contracts And Helpers
+
+- `EventLog` represents the observed event-log contract used by stable event-log helpers.
+- `validate_event_log(event_log)` returns machine-readable warnings for empty logs or missing required event fields.
+- `map_process(event_log)` returns discovered activity nodes and transition counts from observed event order.
+
+### Topology-Aware Event-Log Metrics
+
+- event-log-aware `lead_time` uses per-case event boundaries from observed rows.
+- event-log-aware `wait_time` supports branch-aware elapsed work from explicit parallel edges.
+- event-log-aware `process_cycle_efficiency` supports value-add calculations across parallel and rework-aware event logs.
+- repeated step occurrences require explicit rework edges in the process model.
+- overlapping step intervals require explicit parallel edges in the process model.
+
+## What Is Not Stable Yet
+
+These areas are not part of the stable book-facing API today:
+
+- capability analysis
+- SPC reporting
+- simulation workflows
+- bottleneck workflows
+- before/after comparison workflows
+- reporting bundles
+- automatic `.flo` parsing inside `lss4py`
+
+The IR and metric engine now support stable topology-aware event-log calculations for the current Yellow Belt slice.
+
+Broader graph-driven semantics outside that slice are still future work.
+
+## Development Status
+
+This repository is in active pre-1.0 development.
+
+The Yellow Belt metric surface above is the current stable target.
+
+Other modules and ideas in the repository should be treated as experimental, internal, or future work unless they are explicitly listed in the stable surface.
+
+## Validation
+
+The repository is currently validated with:
+
+- `uv lock --check`
+- `uv run --locked lint-imports`
+- `uv sync`
+- `uv run --locked ruff check .`
+- `uv run --locked pyright`
+- `uv run --locked xenon --max-absolute B --max-modules A --max-average A src/lss4py tests`
+- `uv run --locked pytest`
+- `uv run --locked vulture src tests --min-confidence 80`
+
+Install both local hook stages with:
+
+```bash
+uv run pre-commit install --install-hooks --hook-type pre-commit --hook-type pre-push
+```
+
+The `pre-commit` stage runs Ruff on changed files and the locked test suite without coverage.
+
+The `pre-push` stage and CI run the full locked repository-wide gates.
+
+CI additionally enforces 95% coverage on the current supported slice and runs a
+built-wheel smoke test outside the source tree.
+
+## Roadmap
+
+The governed [roadmap](docs/roadmap.md) targets a complete Yellow Belt MVP at
+v0.3, Green Belt capability at v0.5, Black Belt capability at v0.7, and a
+feature-frozen polish phase at v0.9 before the stable 1.0 contract.
+
+See the [documentation index](docs/README.md) for user requirements, technical
+requirements, ADRs, and governance conventions. R `SixSigma` coverage is tracked
+separately in the [compatibility matrix](docs/sixsigma-compatibility.md).
+
+## License
+
+LSS4PY is available under the [MIT License](LICENSE.md).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to contribute and
+[SECURITY.md](SECURITY.md) to report a vulnerability privately.

lss4py-0.1.0/pyproject.toml

@@ -0,0 +1,112 @@
+[project]
+name = "lss4py"
+version = "0.1.0"
+description = "Python-first Lean Six Sigma analytics for telemetry-rich process improvement"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14,<3.15"
+dependencies = [
+    "click>=8.1.0",
+    "numpy>=2.2.0",
+    "opentelemetry-api>=1.31.0",
+    "opentelemetry-exporter-otlp>=1.31.0",
+    "opentelemetry-sdk>=1.31.0",
+    "pandas>=2.2.0",
+    "rich>=13.9.0",
+    "scipy>=1.15.0",
+    "statsmodels>=0.14.0",
+    "structlog>=24.4.0",
+]
+
+[[project.authors]]
+name = "shanewilkins"
+email = "shane@wilkinsadvisors.com"
+
+[project.optional-dependencies]
+process-mining = ["pm4py>=2.7.0"]
+simulation = ["simpy>=4.1.0"]
+optimization = [
+    "pulp>=2.9.0",
+    "pyomo>=6.8.0",
+]
+visualization = [
+    "matplotlib>=3.10.0",
+    "seaborn>=0.13.0",
+]
+storage = [
+    "duckdb>=1.2.0",
+    "pyarrow>=19.0.0",
+]
+
+[project.scripts]
+lss4py = "lss4py.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "import-linter>=2.1",
+    "pre-commit>=4.1.0",
+    "pyright>=1.1.390",
+    "pytest>=8.3.0",
+    "pytest-cov>=6.0.0",
+    "ruff>=0.9.0",
+    "vulture>=2.13",
+    "xenon>=0.9.3",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.coverage.run]
+source = ["src/lss4py"]
+omit = [
+    "src/lss4py/adapters/*",
+    "src/lss4py/analytics/*",
+    "src/lss4py/cli.py",
+    "src/lss4py/observability/*",
+    "src/lss4py/reporting/*",
+    "src/lss4py/workflows/bottleneck.py",
+    "src/lss4py/workflows/comparison.py",
+    "src/lss4py/workflows/simulation.py",
+]
+
+[tool.coverage.report]
+fail_under = 95
+show_missing = true
+skip_covered = true
+
+[tool.pyright]
+pythonVersion = "3.14"
+typeCheckingMode = "standard"
+include = [
+    "src",
+    "tests",
+]
+venvPath = "."
+venv = ".venv"
+reportMissingTypeStubs = false
+
+[tool.vulture]
+paths = [
+    "src",
+    "tests",
+]
+min_confidence = 80
+exclude = ["*/__init__.py"]