oee 0.1.0__tar.gz

oee-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atakan Arikan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oee-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: oee
+Version: 0.1.0
+Summary: Overall Equipment Effectiveness for Python: availability, performance and quality with the full time waterfall, TEEP, and correct multi-machine roll-up. Computed from the standard definitions and validated against published examples.
+Author: Atakan Arikan
+License: MIT
+Project-URL: Homepage, https://github.com/arikanatakan/oee
+Project-URL: Repository, https://github.com/arikanatakan/oee
+Project-URL: Issues, https://github.com/arikanatakan/oee/issues
+Keywords: oee,overall-equipment-effectiveness,manufacturing,tpm,teep,availability,performance,quality,six-big-losses,production,lean
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# oee
+
+[![CI](https://github.com/arikanatakan/oee/actions/workflows/ci.yml/badge.svg)](https://github.com/arikanatakan/oee/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/oee)](https://pypi.org/project/oee/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Overall Equipment Effectiveness for Python.
+
+Compute OEE (Availability x Performance x Quality) from machine times and piece
+counts, get the full time waterfall and the three loss categories, TEEP and
+utilization, and roll figures up correctly across machines and shifts. Computed
+from the standard definitions and validated against published worked examples.
+
+## Motivation
+
+OEE is the standard manufacturing efficiency metric, but Python has no library
+for it: what exists is monitoring *applications* (Flask/Django dashboards) or
+one-off tutorial scripts. The arithmetic looks trivial (three numbers
+multiplied) and that is exactly why it is usually done wrong:
+
+* the time waterfall (planned -> run -> net run -> fully productive) and where
+  each loss sits is skipped;
+* TEEP and utilization (which capture schedule loss) are left out;
+* and figures are *averaged* across machines, which is incorrect: a fast machine
+  and a slow one do not combine to the mean of their OEEs.
+
+`oee` does these properly, from the standard definitions, and returns one result
+with the factors, the waterfall, every loss, and provenance.
+
+```
+pip install oee
+```
+
+No runtime dependencies.
+
+## Usage
+
+The canonical worked example (Vorne's *Fast Guide to OEE*):
+
+```python
+import oee
+
+r = oee.oee(
+    planned_production_time=420,   # minutes (480 shift - 60 of breaks)
+    downtime=47,
+    ideal_rate=60,                 # pieces per minute
+    total_count=19271,
+    reject_count=423,
+    all_time=480,                  # optional, for TEEP and utilization
+)
+r.availability   # 0.888
+r.performance    # 0.861
+r.quality        # 0.978
+r.oee            # 0.748
+r.teep           # 0.654
+print(r.summary())
+```
+
+Roll up across machines (correctly, not by averaging):
+
+```python
+m1 = oee.oee(planned_production_time=100, run_time=90, ideal_cycle_time=1,
+             total_count=80, good_count=80)     # OEE 0.80
+m2 = oee.oee(planned_production_time=300, run_time=150, ideal_cycle_time=1,
+             total_count=150, good_count=135)   # OEE 0.45
+
+line = oee.aggregate([m1, m2])
+line.oee         # 0.5375, not the 0.625 average of the two
+```
+
+When you already have the three factors:
+
+```python
+oee.oee_from_factors(0.90, 0.95, 0.999).world_class   # True (OEE >= 85%)
+```
+
+Every result carries the factors, the time waterfall, the losses, `world_class`
+and `meets_target` flags, `summary()`, and a JSON-safe `to_dict()` with
+provenance (version, input hash, timestamp).
+
+## What it computes
+
+| Group | Output |
+|-------|--------|
+| Factors | availability, performance, quality, OEE |
+| Extended | TEEP, utilization (when total calendar time is given) |
+| Waterfall | planned -> run -> net run -> fully productive time, with schedule, availability, performance and quality losses |
+| Roll-up | correct aggregation across machines, lines and shifts |
+
+All times must be in the same unit; `ideal_cycle_time` is that unit per piece
+(or pass `ideal_rate` in pieces per that unit). Performance above 100% is capped
+and flagged, since it means the ideal rate or counts are off.
+
+## Status
+
+Version 0.1.0. Single-machine OEE, the time waterfall, TEEP/utilization, and
+correct roll-up. The `OEEResult` contract is append-only from here.
+
+## Roadmap
+
+| Version | Scope |
+|---------|-------|
+| 0.2 | the six big losses (breakdown/setup, minor stops/speed, defects/startup) and a downtime-reason Pareto; computing OEE from an event log |
+| 0.3 | plotting (the OEE waterfall, six-big-losses and trend charts) as an optional extra |
+| 0.4 | an MCP server so an agent can compute and explain OEE |
+
+Out of scope: data collection / machine connectivity (that is the job of an
+MES or an IoT dashboard); `oee` is the calculation layer they can build on.
+
+## License
+
+MIT. Written and maintained by [Atakan Arikan](https://github.com/arikanatakan),
+MSc Student at Tsinghua University and Politecnico di Milano.

oee-0.1.0/README.md

@@ -0,0 +1,113 @@
+# oee
+
+[![CI](https://github.com/arikanatakan/oee/actions/workflows/ci.yml/badge.svg)](https://github.com/arikanatakan/oee/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/oee)](https://pypi.org/project/oee/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Overall Equipment Effectiveness for Python.
+
+Compute OEE (Availability x Performance x Quality) from machine times and piece
+counts, get the full time waterfall and the three loss categories, TEEP and
+utilization, and roll figures up correctly across machines and shifts. Computed
+from the standard definitions and validated against published worked examples.
+
+## Motivation
+
+OEE is the standard manufacturing efficiency metric, but Python has no library
+for it: what exists is monitoring *applications* (Flask/Django dashboards) or
+one-off tutorial scripts. The arithmetic looks trivial (three numbers
+multiplied) and that is exactly why it is usually done wrong:
+
+* the time waterfall (planned -> run -> net run -> fully productive) and where
+  each loss sits is skipped;
+* TEEP and utilization (which capture schedule loss) are left out;
+* and figures are *averaged* across machines, which is incorrect: a fast machine
+  and a slow one do not combine to the mean of their OEEs.
+
+`oee` does these properly, from the standard definitions, and returns one result
+with the factors, the waterfall, every loss, and provenance.
+
+```
+pip install oee
+```
+
+No runtime dependencies.
+
+## Usage
+
+The canonical worked example (Vorne's *Fast Guide to OEE*):
+
+```python
+import oee
+
+r = oee.oee(
+    planned_production_time=420,   # minutes (480 shift - 60 of breaks)
+    downtime=47,
+    ideal_rate=60,                 # pieces per minute
+    total_count=19271,
+    reject_count=423,
+    all_time=480,                  # optional, for TEEP and utilization
+)
+r.availability   # 0.888
+r.performance    # 0.861
+r.quality        # 0.978
+r.oee            # 0.748
+r.teep           # 0.654
+print(r.summary())
+```
+
+Roll up across machines (correctly, not by averaging):
+
+```python
+m1 = oee.oee(planned_production_time=100, run_time=90, ideal_cycle_time=1,
+             total_count=80, good_count=80)     # OEE 0.80
+m2 = oee.oee(planned_production_time=300, run_time=150, ideal_cycle_time=1,
+             total_count=150, good_count=135)   # OEE 0.45
+
+line = oee.aggregate([m1, m2])
+line.oee         # 0.5375, not the 0.625 average of the two
+```
+
+When you already have the three factors:
+
+```python
+oee.oee_from_factors(0.90, 0.95, 0.999).world_class   # True (OEE >= 85%)
+```
+
+Every result carries the factors, the time waterfall, the losses, `world_class`
+and `meets_target` flags, `summary()`, and a JSON-safe `to_dict()` with
+provenance (version, input hash, timestamp).
+
+## What it computes
+
+| Group | Output |
+|-------|--------|
+| Factors | availability, performance, quality, OEE |
+| Extended | TEEP, utilization (when total calendar time is given) |
+| Waterfall | planned -> run -> net run -> fully productive time, with schedule, availability, performance and quality losses |
+| Roll-up | correct aggregation across machines, lines and shifts |
+
+All times must be in the same unit; `ideal_cycle_time` is that unit per piece
+(or pass `ideal_rate` in pieces per that unit). Performance above 100% is capped
+and flagged, since it means the ideal rate or counts are off.
+
+## Status
+
+Version 0.1.0. Single-machine OEE, the time waterfall, TEEP/utilization, and
+correct roll-up. The `OEEResult` contract is append-only from here.
+
+## Roadmap
+
+| Version | Scope |
+|---------|-------|
+| 0.2 | the six big losses (breakdown/setup, minor stops/speed, defects/startup) and a downtime-reason Pareto; computing OEE from an event log |
+| 0.3 | plotting (the OEE waterfall, six-big-losses and trend charts) as an optional extra |
+| 0.4 | an MCP server so an agent can compute and explain OEE |
+
+Out of scope: data collection / machine connectivity (that is the job of an
+MES or an IoT dashboard); `oee` is the calculation layer they can build on.
+
+## License
+
+MIT. Written and maintained by [Atakan Arikan](https://github.com/arikanatakan),
+MSc Student at Tsinghua University and Politecnico di Milano.

oee-0.1.0/oee/__init__.py

@@ -0,0 +1,32 @@
+"""oee - Overall Equipment Effectiveness for Python.
+
+Compute OEE (Availability x Performance x Quality) from machine times and piece
+counts, get the full time waterfall and the three loss categories, TEEP and
+utilization, and roll figures up correctly across machines and shifts. Every
+result carries provenance and a JSON-safe payload.
+
+    import oee
+
+    r = oee.oee(
+        planned_production_time=420,   # minutes
+        downtime=47,
+        ideal_cycle_time=1 / 60,       # minutes per piece
+        total_count=19271,
+        reject_count=423,
+    )
+    r.oee            # 0.7479
+    r.summary()      # the factor and loss breakdown
+
+Computed from the standard definitions and validated against published worked
+examples.
+"""
+
+from ._result import Alert, OEEResult
+from ._version import __version__
+from .aggregate import aggregate
+from .core import oee, oee_from_factors
+
+__all__ = [
+    "oee", "oee_from_factors", "aggregate",
+    "OEEResult", "Alert", "__version__",
+]

oee-0.1.0/oee/_result.py

@@ -0,0 +1,146 @@
+"""The result contract: one ``OEEResult`` per computation, carrying the three
+factors, the time waterfall, the loss categories, provenance and a JSON-safe
+payload, so a calculation can be reproduced and audited later.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+SCHEMA = 1
+WORLD_CLASS_OEE = 0.85
+
+
+def utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def data_hash(obj: object) -> str:
+    payload = json.dumps(obj, sort_keys=True, default=str).encode("utf-8")
+    return "sha256:" + hashlib.sha256(payload).hexdigest()[:16]
+
+
+@dataclass(frozen=True)
+class Alert:
+    """A data-quality or benchmark note attached to a result."""
+
+    indicator: str
+    message: str
+    severity: str = "warning"  # info | warning | error
+
+    def __str__(self) -> str:
+        return f"[{self.severity.upper()}] {self.indicator}: {self.message}"
+
+
+def _pct(value: float | None) -> float | None:
+    return None if value is None else round(100.0 * value, 1)
+
+
+@dataclass(frozen=True)
+class OEEResult:
+    """Overall Equipment Effectiveness and the time/loss breakdown behind it."""
+
+    name: str | None
+    availability: float
+    performance: float
+    quality: float
+    oee: float
+    performance_raw: float
+    utilization: float | None
+    teep: float | None
+    planned_production_time: float | None
+    run_time: float | None
+    net_run_time: float | None
+    fully_productive_time: float | None
+    all_time: float | None
+    schedule_loss: float | None
+    availability_loss: float | None
+    performance_loss: float | None
+    quality_loss: float | None
+    total_count: float | None
+    good_count: float | None
+    reject_count: float | None
+    target_oee: float
+    alerts: tuple[Alert, ...]
+    meta: dict
+
+    @property
+    def world_class(self) -> bool:
+        """True when OEE meets the widely cited world-class level of 85%."""
+        return self.oee >= WORLD_CLASS_OEE
+
+    @property
+    def meets_target(self) -> bool:
+        return self.oee >= self.target_oee
+
+    @property
+    def ok(self) -> bool:
+        """True when no error-severity (data-quality) alert was raised."""
+        return not any(a.severity == "error" for a in self.alerts)
+
+    def _verdict(self) -> str:
+        if self.world_class:
+            return "world-class"
+        if self.meets_target:
+            return "meets target"
+        return "below target"
+
+    def summary(self) -> str:
+        head = "oee" + (f" {self.name}" if self.name else "")
+        lines = [
+            f"{head} - {self.meta.get('computed_at', '')}",
+            f"  Availability   {_pct(self.availability):>5}%",
+            f"  Performance    {_pct(self.performance):>5}%",
+            f"  Quality        {_pct(self.quality):>5}%",
+            f"  OEE            {_pct(self.oee):>5}%",
+        ]
+        if self.teep is not None:
+            lines.append(f"  TEEP           {_pct(self.teep):>5}%")
+        for alert in self.alerts:
+            lines.append("  " + str(alert))
+        lines.append(f"Verdict: OEE {_pct(self.oee)}% - {self._verdict()}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {
+            "schema": SCHEMA,
+            "name": self.name,
+            "factors": {
+                "availability": self.availability,
+                "performance": self.performance,
+                "quality": self.quality,
+                "oee": self.oee,
+                "performance_raw": self.performance_raw,
+                "utilization": self.utilization,
+                "teep": self.teep,
+            },
+            "times": {
+                "all_time": self.all_time,
+                "planned_production_time": self.planned_production_time,
+                "run_time": self.run_time,
+                "net_run_time": self.net_run_time,
+                "fully_productive_time": self.fully_productive_time,
+            },
+            "losses": {
+                "schedule_loss": self.schedule_loss,
+                "availability_loss": self.availability_loss,
+                "performance_loss": self.performance_loss,
+                "quality_loss": self.quality_loss,
+            },
+            "counts": {
+                "total_count": self.total_count,
+                "good_count": self.good_count,
+                "reject_count": self.reject_count,
+            },
+            "world_class": self.world_class,
+            "meets_target": self.meets_target,
+            "target_oee": self.target_oee,
+            "alerts": [
+                {"indicator": a.indicator, "message": a.message, "severity": a.severity}
+                for a in self.alerts
+            ],
+            "meta": self.meta,
+        }

oee-0.1.0/oee/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

oee-0.1.0/oee/aggregate.py

@@ -0,0 +1,75 @@
+"""Roll OEE up across machines, lines, shifts or periods.
+
+OEE figures must not be averaged: a fast machine and a slow one do not combine
+to the mean of their OEEs. The correct roll-up sums the underlying time and
+count buckets and recomputes the factors from the totals, which this does.
+"""
+
+from __future__ import annotations
+
+from ._result import Alert, OEEResult, data_hash, utcnow
+from ._version import __version__
+
+_REQUIRED = ("planned_production_time", "run_time", "net_run_time",
+             "fully_productive_time", "total_count", "good_count")
+
+
+def aggregate(parts, *, target_oee: float = 0.85,
+              name: str | None = None) -> OEEResult:
+    """Combine several OEEResults into one by summing their time/count buckets."""
+    parts = list(parts)
+    if not parts:
+        raise ValueError("aggregate needs at least one result")
+    for i, part in enumerate(parts):
+        if not isinstance(part, OEEResult):
+            raise TypeError("aggregate expects OEEResult instances")
+        for field in _REQUIRED:
+            if getattr(part, field) is None:
+                raise ValueError(
+                    f"part {i} has no {field}; aggregate needs results created "
+                    "from times and counts (oee(), not oee_from_factors())")
+
+    s_planned = sum(p.planned_production_time for p in parts)
+    s_run = sum(p.run_time for p in parts)
+    s_net = sum(p.net_run_time for p in parts)
+    s_fp = sum(p.fully_productive_time for p in parts)
+    s_total = sum(p.total_count for p in parts)
+    s_good = sum(p.good_count for p in parts)
+
+    availability = s_run / s_planned if s_planned else 0.0
+    performance = s_net / s_run if s_run else 0.0
+    quality = s_fp / s_net if s_net else 0.0
+    oee_value = s_fp / s_planned if s_planned else 0.0
+
+    if all(p.all_time is not None for p in parts):
+        s_all = sum(p.all_time for p in parts)
+        utilization = s_planned / s_all if s_all else 0.0
+        teep = s_fp / s_all if s_all else 0.0
+        schedule_loss = s_all - s_planned
+    else:
+        s_all = utilization = teep = schedule_loss = None
+
+    alerts: list[Alert] = []
+    if oee_value < target_oee:
+        alerts.append(Alert(
+            "oee", f"OEE {oee_value * 100:.1f}% is below the target "
+            f"{target_oee * 100:.0f}%", "info"))
+
+    meta = {
+        "computed_at": utcnow(),
+        "version": __version__,
+        "method": "aggregate",
+        "parts": len(parts),
+        "input_hash": data_hash([p.meta.get("input_hash") for p in parts]),
+    }
+    return OEEResult(
+        name=name, availability=availability, performance=performance,
+        quality=quality, oee=oee_value, performance_raw=performance,
+        utilization=utilization, teep=teep,
+        planned_production_time=s_planned, run_time=s_run, net_run_time=s_net,
+        fully_productive_time=s_fp, all_time=s_all, schedule_loss=schedule_loss,
+        availability_loss=s_planned - s_run, performance_loss=s_run - s_net,
+        quality_loss=s_net - s_fp, total_count=s_total, good_count=s_good,
+        reject_count=s_total - s_good, target_oee=target_oee,
+        alerts=tuple(alerts), meta=meta,
+    )

oee-0.1.0/oee/core.py

@@ -0,0 +1,165 @@
+"""Overall Equipment Effectiveness from the standard definitions.
+
+OEE = Availability x Performance x Quality, with
+
+    Availability = run time / planned production time
+    Performance  = (ideal cycle time x total count) / run time
+    Quality      = good count / total count
+
+All times must be in the same unit, and ``ideal_cycle_time`` in that unit per
+piece (or pass ``ideal_rate`` in pieces per that unit). The full time waterfall
+(planned -> run -> net run -> fully productive) and each loss are returned, plus
+TEEP and utilization when ``all_time`` is given.
+"""
+
+from __future__ import annotations
+
+import math
+
+from ._result import Alert, OEEResult, data_hash, utcnow
+from ._version import __version__
+
+
+def _finite(value: float, label: str) -> float:
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        raise TypeError(f"{label} must be a number")
+    value = float(value)
+    if not math.isfinite(value):
+        raise ValueError(f"{label} must be finite")
+    return value
+
+
+def _exactly_one(a, b, name_a: str, name_b: str):
+    if (a is None) == (b is None):
+        raise ValueError(f"provide exactly one of {name_a} or {name_b}")
+    return a, b
+
+
+def oee(planned_production_time, *, run_time=None, downtime=None,
+        ideal_cycle_time=None, ideal_rate=None, total_count,
+        good_count=None, reject_count=None, all_time=None,
+        target_oee: float = 0.85, name: str | None = None) -> OEEResult:
+    """Compute OEE and the time/loss waterfall from times and piece counts."""
+    planned = _finite(planned_production_time, "planned_production_time")
+    if planned <= 0:
+        raise ValueError("planned_production_time must be positive")
+
+    _exactly_one(run_time, downtime, "run_time", "downtime")
+    run = _finite(run_time, "run_time") if run_time is not None \
+        else planned - _finite(downtime, "downtime")
+    if not 0 <= run <= planned:
+        raise ValueError("run_time must be between 0 and planned_production_time")
+
+    _exactly_one(ideal_cycle_time, ideal_rate, "ideal_cycle_time", "ideal_rate")
+    if ideal_cycle_time is not None:
+        cycle = _finite(ideal_cycle_time, "ideal_cycle_time")
+    else:
+        rate = _finite(ideal_rate, "ideal_rate")
+        if rate <= 0:
+            raise ValueError("ideal_rate must be positive")
+        cycle = 1.0 / rate
+    if cycle <= 0:
+        raise ValueError("ideal_cycle_time must be positive")
+
+    total = _finite(total_count, "total_count")
+    if total <= 0:
+        raise ValueError("total_count must be positive")
+    _exactly_one(good_count, reject_count, "good_count", "reject_count")
+    good = _finite(good_count, "good_count") if good_count is not None \
+        else total - _finite(reject_count, "reject_count")
+    if not 0 <= good <= total:
+        raise ValueError("good_count must be between 0 and total_count")
+    reject = total - good
+
+    alerts: list[Alert] = []
+
+    availability = run / planned if planned else 0.0
+
+    ideal_time_total = cycle * total
+    performance_raw = ideal_time_total / run if run > 0 else 0.0
+    if performance_raw > 1.0 + 1e-9:
+        performance = 1.0
+        net_run = run
+        alerts.append(Alert(
+            "performance", "performance exceeds 100%; capped at 100% (check "
+            "ideal_cycle_time / ideal_rate and counts)", "warning"))
+    else:
+        performance = performance_raw
+        net_run = ideal_time_total
+
+    quality = good / total
+    fully_productive = quality * net_run
+    oee_value = availability * performance * quality
+
+    schedule_loss = None
+    utilization = None
+    teep = None
+    if all_time is not None:
+        at = _finite(all_time, "all_time")
+        if at < planned:
+            raise ValueError("all_time must be at least planned_production_time")
+        schedule_loss = at - planned
+        utilization = planned / at if at > 0 else 0.0
+        teep = fully_productive / at if at > 0 else 0.0
+
+    if not 0 < target_oee <= 1:
+        raise ValueError("target_oee must be in (0, 1]")
+    if oee_value < target_oee:
+        alerts.append(Alert(
+            "oee", f"OEE {oee_value * 100:.1f}% is below the target "
+            f"{target_oee * 100:.0f}%", "info"))
+
+    meta = {
+        "computed_at": utcnow(),
+        "version": __version__,
+        "method": "time_and_counts",
+        "input_hash": data_hash({
+            "planned": planned, "run": run, "cycle": cycle,
+            "total": total, "good": good, "all_time": all_time,
+        }),
+    }
+    return OEEResult(
+        name=name, availability=availability, performance=performance,
+        quality=quality, oee=oee_value, performance_raw=performance_raw,
+        utilization=utilization, teep=teep,
+        planned_production_time=planned, run_time=run, net_run_time=net_run,
+        fully_productive_time=fully_productive, all_time=all_time,
+        schedule_loss=schedule_loss, availability_loss=planned - run,
+        performance_loss=run - net_run, quality_loss=net_run - fully_productive,
+        total_count=total, good_count=good, reject_count=reject,
+        target_oee=target_oee, alerts=tuple(alerts), meta=meta,
+    )
+
+
+def oee_from_factors(availability, performance, quality, *,
+                     target_oee: float = 0.85, name: str | None = None) -> OEEResult:
+    """Compute OEE from the three factors directly (no times or counts)."""
+    a = _finite(availability, "availability")
+    p = _finite(performance, "performance")
+    q = _finite(quality, "quality")
+    alerts: list[Alert] = []
+    for label, value in (("availability", a), ("performance", p), ("quality", q)):
+        if not 0 <= value <= 1.0 + 1e-9:
+            raise ValueError(f"{label} must be between 0 and 1")
+    if not 0 < target_oee <= 1:
+        raise ValueError("target_oee must be in (0, 1]")
+    oee_value = a * p * q
+    if oee_value < target_oee:
+        alerts.append(Alert(
+            "oee", f"OEE {oee_value * 100:.1f}% is below the target "
+            f"{target_oee * 100:.0f}%", "info"))
+    meta = {
+        "computed_at": utcnow(),
+        "version": __version__,
+        "method": "factors",
+        "input_hash": data_hash({"a": a, "p": p, "q": q}),
+    }
+    return OEEResult(
+        name=name, availability=a, performance=p, quality=q, oee=oee_value,
+        performance_raw=p, utilization=None, teep=None,
+        planned_production_time=None, run_time=None, net_run_time=None,
+        fully_productive_time=None, all_time=None, schedule_loss=None,
+        availability_loss=None, performance_loss=None, quality_loss=None,
+        total_count=None, good_count=None, reject_count=None,
+        target_oee=target_oee, alerts=tuple(alerts), meta=meta,
+    )

oee-0.1.0/oee.egg-info/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: oee
+Version: 0.1.0
+Summary: Overall Equipment Effectiveness for Python: availability, performance and quality with the full time waterfall, TEEP, and correct multi-machine roll-up. Computed from the standard definitions and validated against published examples.
+Author: Atakan Arikan
+License: MIT
+Project-URL: Homepage, https://github.com/arikanatakan/oee
+Project-URL: Repository, https://github.com/arikanatakan/oee
+Project-URL: Issues, https://github.com/arikanatakan/oee/issues
+Keywords: oee,overall-equipment-effectiveness,manufacturing,tpm,teep,availability,performance,quality,six-big-losses,production,lean
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# oee
+
+[![CI](https://github.com/arikanatakan/oee/actions/workflows/ci.yml/badge.svg)](https://github.com/arikanatakan/oee/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/oee)](https://pypi.org/project/oee/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Overall Equipment Effectiveness for Python.
+
+Compute OEE (Availability x Performance x Quality) from machine times and piece
+counts, get the full time waterfall and the three loss categories, TEEP and
+utilization, and roll figures up correctly across machines and shifts. Computed
+from the standard definitions and validated against published worked examples.
+
+## Motivation
+
+OEE is the standard manufacturing efficiency metric, but Python has no library
+for it: what exists is monitoring *applications* (Flask/Django dashboards) or
+one-off tutorial scripts. The arithmetic looks trivial (three numbers
+multiplied) and that is exactly why it is usually done wrong:
+
+* the time waterfall (planned -> run -> net run -> fully productive) and where
+  each loss sits is skipped;
+* TEEP and utilization (which capture schedule loss) are left out;
+* and figures are *averaged* across machines, which is incorrect: a fast machine
+  and a slow one do not combine to the mean of their OEEs.
+
+`oee` does these properly, from the standard definitions, and returns one result
+with the factors, the waterfall, every loss, and provenance.
+
+```
+pip install oee
+```
+
+No runtime dependencies.
+
+## Usage
+
+The canonical worked example (Vorne's *Fast Guide to OEE*):
+
+```python
+import oee
+
+r = oee.oee(
+    planned_production_time=420,   # minutes (480 shift - 60 of breaks)
+    downtime=47,
+    ideal_rate=60,                 # pieces per minute
+    total_count=19271,
+    reject_count=423,
+    all_time=480,                  # optional, for TEEP and utilization
+)
+r.availability   # 0.888
+r.performance    # 0.861
+r.quality        # 0.978
+r.oee            # 0.748
+r.teep           # 0.654
+print(r.summary())
+```
+
+Roll up across machines (correctly, not by averaging):
+
+```python
+m1 = oee.oee(planned_production_time=100, run_time=90, ideal_cycle_time=1,
+             total_count=80, good_count=80)     # OEE 0.80
+m2 = oee.oee(planned_production_time=300, run_time=150, ideal_cycle_time=1,
+             total_count=150, good_count=135)   # OEE 0.45
+
+line = oee.aggregate([m1, m2])
+line.oee         # 0.5375, not the 0.625 average of the two
+```
+
+When you already have the three factors:
+
+```python
+oee.oee_from_factors(0.90, 0.95, 0.999).world_class   # True (OEE >= 85%)
+```
+
+Every result carries the factors, the time waterfall, the losses, `world_class`
+and `meets_target` flags, `summary()`, and a JSON-safe `to_dict()` with
+provenance (version, input hash, timestamp).
+
+## What it computes
+
+| Group | Output |
+|-------|--------|
+| Factors | availability, performance, quality, OEE |
+| Extended | TEEP, utilization (when total calendar time is given) |
+| Waterfall | planned -> run -> net run -> fully productive time, with schedule, availability, performance and quality losses |
+| Roll-up | correct aggregation across machines, lines and shifts |
+
+All times must be in the same unit; `ideal_cycle_time` is that unit per piece
+(or pass `ideal_rate` in pieces per that unit). Performance above 100% is capped
+and flagged, since it means the ideal rate or counts are off.
+
+## Status
+
+Version 0.1.0. Single-machine OEE, the time waterfall, TEEP/utilization, and
+correct roll-up. The `OEEResult` contract is append-only from here.
+
+## Roadmap
+
+| Version | Scope |
+|---------|-------|
+| 0.2 | the six big losses (breakdown/setup, minor stops/speed, defects/startup) and a downtime-reason Pareto; computing OEE from an event log |
+| 0.3 | plotting (the OEE waterfall, six-big-losses and trend charts) as an optional extra |
+| 0.4 | an MCP server so an agent can compute and explain OEE |
+
+Out of scope: data collection / machine connectivity (that is the job of an
+MES or an IoT dashboard); `oee` is the calculation layer they can build on.
+
+## License
+
+MIT. Written and maintained by [Atakan Arikan](https://github.com/arikanatakan),
+MSc Student at Tsinghua University and Politecnico di Milano.

oee-0.1.0/oee.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+oee/__init__.py
+oee/_result.py
+oee/_version.py
+oee/aggregate.py
+oee/core.py
+oee/py.typed
+oee.egg-info/PKG-INFO
+oee.egg-info/SOURCES.txt
+oee.egg-info/dependency_links.txt
+oee.egg-info/requires.txt
+oee.egg-info/top_level.txt
+tests/test_aggregate.py
+tests/test_core.py
+tests/test_validation_suite.py

oee-0.1.0/oee.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

oee-0.1.0/oee.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+pytest>=7
+ruff
+build

oee-0.1.0/oee.egg-info/top_level.txt

@@ -0,0 +1 @@
+oee

oee-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oee"
+version = "0.1.0"
+description = "Overall Equipment Effectiveness for Python: availability, performance and quality with the full time waterfall, TEEP, and correct multi-machine roll-up. Computed from the standard definitions and validated against published examples."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Atakan Arikan" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = [
+    "oee", "overall-equipment-effectiveness", "manufacturing", "tpm", "teep",
+    "availability", "performance", "quality", "six-big-losses",
+    "production", "lean",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Manufacturing",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff", "build"]
+
+[project.urls]
+Homepage = "https://github.com/arikanatakan/oee"
+Repository = "https://github.com/arikanatakan/oee"
+Issues = "https://github.com/arikanatakan/oee/issues"
+
+[tool.setuptools.packages.find]
+include = ["oee*"]
+
+[tool.setuptools.package-data]
+oee = ["py.typed"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

oee-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oee-0.1.0/tests/test_aggregate.py

@@ -0,0 +1,70 @@
+import pytest
+
+import oee
+
+
+def test_rollup_is_not_the_average_of_oees():
+    m1 = oee.oee(planned_production_time=100, run_time=90, ideal_cycle_time=1,
+                 total_count=80, good_count=80)
+    m2 = oee.oee(planned_production_time=300, run_time=150, ideal_cycle_time=1,
+                 total_count=150, good_count=135)
+    agg = oee.aggregate([m1, m2])
+    naive = (m1.oee + m2.oee) / 2
+    assert agg.oee == pytest.approx(0.5375, abs=1e-4)
+    assert agg.oee != pytest.approx(naive, abs=1e-3)
+
+
+def test_buckets_sum():
+    m1 = oee.oee(planned_production_time=100, run_time=90, ideal_cycle_time=1,
+                 total_count=80, good_count=80)
+    m2 = oee.oee(planned_production_time=300, run_time=150, ideal_cycle_time=1,
+                 total_count=150, good_count=135)
+    agg = oee.aggregate([m1, m2])
+    assert agg.planned_production_time == 400
+    assert agg.run_time == 240
+    assert agg.total_count == 230
+    assert agg.good_count == 215
+    assert agg.oee == pytest.approx(agg.fully_productive_time / agg.planned_production_time)
+
+
+def test_single_part_matches_itself():
+    m = oee.oee(planned_production_time=100, run_time=90, ideal_cycle_time=1,
+                total_count=80, good_count=80)
+    agg = oee.aggregate([m])
+    assert agg.oee == pytest.approx(m.oee)
+    assert agg.availability == pytest.approx(m.availability)
+
+
+def test_teep_when_all_parts_have_all_time():
+    m1 = oee.oee(planned_production_time=100, run_time=90, ideal_cycle_time=1,
+                 total_count=80, good_count=80, all_time=120)
+    m2 = oee.oee(planned_production_time=300, run_time=150, ideal_cycle_time=1,
+                 total_count=150, good_count=135, all_time=360)
+    agg = oee.aggregate([m1, m2])
+    assert agg.teep is not None
+    assert agg.utilization == pytest.approx(400 / 480)
+
+
+def test_teep_none_when_a_part_lacks_all_time():
+    m1 = oee.oee(planned_production_time=100, run_time=90, ideal_cycle_time=1,
+                 total_count=80, good_count=80, all_time=120)
+    m2 = oee.oee(planned_production_time=300, run_time=150, ideal_cycle_time=1,
+                 total_count=150, good_count=135)
+    agg = oee.aggregate([m1, m2])
+    assert agg.teep is None
+
+
+def test_factors_only_part_cannot_be_aggregated():
+    f = oee.oee_from_factors(0.9, 0.9, 0.9)
+    with pytest.raises(ValueError):
+        oee.aggregate([f])
+
+
+def test_empty_raises():
+    with pytest.raises(ValueError):
+        oee.aggregate([])
+
+
+def test_non_result_raises():
+    with pytest.raises(TypeError):
+        oee.aggregate([{"oee": 0.5}])

oee-0.1.0/tests/test_core.py

@@ -0,0 +1,106 @@
+import json
+
+import pytest
+
+import oee
+
+
+def _vorne(**over):
+    kw = dict(planned_production_time=420, downtime=47, ideal_rate=60,
+              total_count=19271, reject_count=423)
+    kw.update(over)
+    return oee.oee(**kw)
+
+
+def test_basic_factors_and_oee():
+    r = _vorne()
+    assert r.oee == pytest.approx(0.7480, abs=0.001)
+    assert r.availability == pytest.approx(0.8881, abs=0.001)
+    assert not r.world_class
+    assert not r.meets_target
+
+
+def test_run_time_and_downtime_agree():
+    a = oee.oee(planned_production_time=420, downtime=47, ideal_rate=60,
+                total_count=19271, reject_count=423)
+    b = oee.oee(planned_production_time=420, run_time=373, ideal_rate=60,
+                total_count=19271, reject_count=423)
+    assert a.oee == pytest.approx(b.oee)
+
+
+def test_ideal_rate_and_cycle_agree():
+    a = oee.oee(planned_production_time=420, downtime=47, ideal_rate=60,
+                total_count=19271, reject_count=423)
+    b = oee.oee(planned_production_time=420, downtime=47, ideal_cycle_time=1 / 60,
+                total_count=19271, reject_count=423)
+    assert a.performance == pytest.approx(b.performance)
+
+
+def test_waterfall_adds_up():
+    r = _vorne(all_time=480)
+    assert r.schedule_loss + r.planned_production_time == pytest.approx(r.all_time)
+    assert r.availability_loss + r.run_time == pytest.approx(r.planned_production_time)
+    assert r.performance_loss + r.net_run_time == pytest.approx(r.run_time)
+    assert r.quality_loss + r.fully_productive_time == pytest.approx(r.net_run_time)
+    assert r.oee == pytest.approx(r.fully_productive_time / r.planned_production_time)
+
+
+def test_teep_is_oee_times_utilization():
+    r = _vorne(all_time=480)
+    assert r.teep == pytest.approx(r.oee * r.utilization, abs=1e-9)
+
+
+def test_performance_over_100_is_capped_and_flagged():
+    r = oee.oee(planned_production_time=100, run_time=100, ideal_cycle_time=2,
+                total_count=100, good_count=100)
+    assert r.performance == 1.0
+    assert r.performance_raw == pytest.approx(2.0)
+    assert any(a.indicator == "performance" for a in r.alerts)
+
+
+def test_world_class_flag():
+    r = oee.oee_from_factors(0.90, 0.95, 0.999)
+    assert r.world_class
+    assert r.oee == pytest.approx(0.8541, abs=0.001)
+
+
+def test_to_dict_json_serializable():
+    d = _vorne(all_time=480).to_dict()
+    json.dumps(d)
+    assert d["schema"] == 1
+    assert "input_hash" in d["meta"]
+    assert d["factors"]["oee"] == pytest.approx(0.7480, abs=0.001)
+
+
+def test_summary_plain_text():
+    t = _vorne().summary()
+    assert "OEE" in t and "Verdict" in t
+    assert "—" not in t  # no em dash
+
+
+def test_provenance_changes_with_input():
+    a = _vorne().meta["input_hash"]
+    b = _vorne(reject_count=500).meta["input_hash"]
+    assert a != b
+
+
+@pytest.mark.parametrize("over", [
+    {"planned_production_time": 0},
+    {"downtime": 500},                 # run time negative
+    {"total_count": 0},
+    {"good_count": 99999},             # good > total
+])
+def test_invalid_inputs_raise(over):
+    with pytest.raises(ValueError):
+        _vorne(**over)
+
+
+def test_both_run_and_downtime_raises():
+    with pytest.raises(ValueError):
+        oee.oee(planned_production_time=420, run_time=373, downtime=47,
+                ideal_rate=60, total_count=100, good_count=100)
+
+
+def test_factors_out_of_range_raises():
+    with pytest.raises(ValueError):
+        oee.oee_from_factors(1.2, 0.9, 0.9)

oee-0.1.0/tests/test_validation_suite.py

@@ -0,0 +1,27 @@
+"""Check oee against published and hand-derived worked examples."""
+
+import json
+from pathlib import Path
+
+import pytest
+
+import oee
+
+CASES = json.loads((Path(__file__).parent / "validation_cases.json").read_text())["cases"]
+
+
+def _compute(case):
+    if case["method"] == "time_and_counts":
+        return oee.oee(**case["inputs"])
+    if case["method"] == "factors":
+        return oee.oee_from_factors(**case["inputs"])
+    raise ValueError(case["method"])
+
+
+@pytest.mark.parametrize("case", CASES, ids=[c["id"] for c in CASES])
+def test_case(case):
+    result = _compute(case)
+    tol = case["tol"]
+    for field, expected in case["expected"].items():
+        actual = getattr(result, field)
+        assert actual == pytest.approx(expected, abs=tol), f"{case['id']}.{field}"