actop 1.0.0__py3-none-any.whl

actop/__init__.py

@@ -0,0 +1,18 @@
+import importlib.metadata
+
+from .api import AsyncMonitor, Monitor, Profiler
+from .models import CoreSample, SystemSnapshot
+
+try:
+    __version__ = importlib.metadata.version("actop")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "dev"
+
+__all__ = [
+    "Monitor",
+    "Profiler",
+    "AsyncMonitor",
+    "SystemSnapshot",
+    "CoreSample",
+    "__version__",
+]

actop/actop.py

@@ -0,0 +1,219 @@
+import argparse
+import re
+
+from actop import __version__
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        description="actop: Performance monitoring CLI tool for Apple Silicon"
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    parser.add_argument(
+        "--interval",
+        type=int,
+        default=2,
+        help="Display and sampling interval in seconds",
+    )
+    parser.add_argument(
+        "--avg", type=int, default=30, help="Interval for averaged values (seconds)"
+    )
+    parser.add_argument(
+        "--subsamples",
+        type=_validate_subsamples,
+        default=1,
+        help="Number of internal sampler deltas per interval (>=1)",
+    )
+    parser.add_argument(
+        "--show_cores",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Enable per-core panels (disable with --no-show_cores)",
+    )
+    parser.add_argument(
+        "--power-scale",
+        choices=["auto", "profile"],
+        default="profile",
+        help="Power chart scaling mode: profile uses SoC reference, auto uses rolling peak",
+    )
+    parser.add_argument(
+        "--chart-glyph",
+        choices=["dots", "block"],
+        default="dots",
+        help="Chart glyph style: dots (braille) or block (square)",
+    )
+    parser.add_argument(
+        "--proc-filter",
+        type=_validate_proc_filter,
+        default="",
+        help='Regex filter for process panel command names (example: "python|ollama|vllm|docker|mlx")',
+    )
+    parser.add_argument(
+        "--show-processes",
+        action="store_true",
+        default=False,
+        help="Show top process panel at startup (default: off)",
+    )
+    parser.add_argument(
+        "--alert-bw-sat-percent",
+        type=_validate_percent_threshold,
+        default=85,
+        help="Bandwidth saturation alert threshold percent (1-100)",
+    )
+    parser.add_argument(
+        "--alert-package-power-percent",
+        type=_validate_percent_threshold,
+        default=85,
+        help="Package power alert threshold percent (1-100, profile-relative)",
+    )
+    parser.add_argument(
+        "--alert-swap-rise-gb",
+        type=_validate_swap_rise_gb,
+        default=0.3,
+        help="Alert when swap rises by at least this many GB over sustained samples",
+    )
+    parser.add_argument(
+        "--alert-sustain-samples",
+        type=_validate_sustain_samples,
+        default=3,
+        help="Consecutive samples required for sustained alerts",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        default=False,
+        help="Stream metrics as NDJSON to stdout instead of launching the TUI",
+    )
+    parser.add_argument(
+        "--serve",
+        type=_validate_port,
+        default=None,
+        metavar="PORT",
+        help="Serve Prometheus metrics on http://0.0.0.0:PORT/metrics (no TUI)",
+    )
+    return parser
+
+
+def _validate_proc_filter(value):
+    if value in (None, ""):
+        return ""
+    try:
+        re.compile(value, re.IGNORECASE)
+    except re.error as error:
+        raise argparse.ArgumentTypeError(
+            "invalid --proc-filter regex: {}".format(error)
+        ) from error
+    return value
+
+
+def _validate_percent_threshold(value):
+    try:
+        threshold = int(value)
+    except (TypeError, ValueError) as error:
+        raise argparse.ArgumentTypeError("threshold must be an integer") from error
+    if threshold < 1 or threshold > 100:
+        raise argparse.ArgumentTypeError("threshold must be in the range 1-100")
+    return threshold
+
+
+def _validate_swap_rise_gb(value):
+    try:
+        swap_rise = float(value)
+    except (TypeError, ValueError) as error:
+        raise argparse.ArgumentTypeError(
+            "swap rise threshold must be a number"
+        ) from error
+    if swap_rise < 0:
+        raise argparse.ArgumentTypeError("swap rise threshold must be >= 0")
+    return swap_rise
+
+
+def _validate_sustain_samples(value):
+    try:
+        samples = int(value)
+    except (TypeError, ValueError) as error:
+        raise argparse.ArgumentTypeError(
+            "sustain samples must be an integer"
+        ) from error
+    if samples < 1:
+        raise argparse.ArgumentTypeError("sustain samples must be >= 1")
+    return samples
+
+
+def _validate_port(value):
+    try:
+        port = int(value)
+    except (TypeError, ValueError) as error:
+        raise argparse.ArgumentTypeError("port must be an integer") from error
+    if port < 1 or port > 65535:
+        raise argparse.ArgumentTypeError("port must be in the range 1-65535")
+    return port
+
+
+def _validate_subsamples(value):
+    try:
+        subsamples = int(value)
+    except (TypeError, ValueError) as error:
+        raise argparse.ArgumentTypeError("subsamples must be an integer") from error
+    if subsamples < 1:
+        raise argparse.ArgumentTypeError("subsamples must be >= 1")
+    return subsamples
+
+
+def _run_dashboard(args, runtime_state):
+    from actop.tui.app import ActopApp
+
+    app = ActopApp(args)
+    app.run()
+
+
+def _run_export(args):
+    """Route to a non-TUI export backend. Returns an exit code."""
+    from actop import export
+
+    interval_s = max(1, int(args.interval))
+    subsamples = max(1, int(args.subsamples))
+    try:
+        if args.serve is not None:
+            export.serve_prometheus(args.serve, interval_s, subsamples)
+        else:
+            export.run_json_stream(interval_s, subsamples)
+        return 0
+    except KeyboardInterrupt:
+        return 130
+
+
+def main(args=None):
+    if args is None:
+        args = build_parser().parse_args()
+    if getattr(args, "json", False) or getattr(args, "serve", None) is not None:
+        return _run_export(args)
+    runtime_state = {"monitor": None, "cursor_hidden": False}
+    try:
+        _run_dashboard(args, runtime_state)
+        return 0
+    except KeyboardInterrupt:
+        print("Stopping...")
+        return 130
+    finally:
+        monitor = runtime_state.get("monitor")
+        if monitor is not None:
+            monitor.close()
+        if runtime_state["cursor_hidden"]:
+            print("\033[?25h")
+
+
+def cli(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return main(args)
+    except Exception as e:
+        print(e)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(cli())

actop/api.py

@@ -0,0 +1,202 @@
+"""Public Python API for actop hardware profiling."""
+
+import dataclasses
+import threading
+import time
+
+from .models import CoreSample, SystemSnapshot
+from .sampler import SampleResult, create_sampler
+from .utils import get_ram_metrics_dict
+
+
+def _sample_to_snapshot(
+    sample: SampleResult, ram: dict, interval_s: float
+) -> SystemSnapshot:
+    """Map raw SampleResult + RAM dict to a clean SystemSnapshot."""
+    cm = sample.cpu_metrics
+    gm = sample.gpu_metrics
+    bw = sample.bandwidth_metrics
+    bw_avail = bool(isinstance(bw, dict) and bw.get("_available", False))
+    # total_gbps is a residency-weighted average already in GB/s — not a
+    # byte counter, so it is not divided by the sample interval.
+    total_bw = float(bw.get("total_gbps", 0.0)) if bw_avail else 0.0
+    e_cores = [
+        CoreSample(
+            index=sys_idx,
+            active_pct=int(cm.get("E-Cluster" + str(sys_idx) + "_active", 0)),
+            freq_mhz=int(cm.get("E-Cluster" + str(sys_idx) + "_freq_Mhz", 0)),
+        )
+        for sys_idx in cm.get("e_core", [])
+    ]
+    p_cores = [
+        CoreSample(
+            index=sys_idx,
+            active_pct=int(cm.get("P-Cluster" + str(sys_idx) + "_active", 0)),
+            freq_mhz=int(cm.get("P-Cluster" + str(sys_idx) + "_freq_Mhz", 0)),
+        )
+        for sys_idx in cm.get("p_core", [])
+    ]
+    return SystemSnapshot(
+        timestamp=sample.timestamp,
+        cpu_watts=cm["cpu_W"] / interval_s,
+        gpu_watts=cm["gpu_W"] / interval_s,
+        ane_watts=cm["ane_W"] / interval_s,
+        package_watts=cm["package_W"] / interval_s,
+        ecpu_util_pct=float(cm["E-Cluster_active"]),
+        pcpu_util_pct=float(cm["P-Cluster_active"]),
+        gpu_util_pct=float(gm["active"]),
+        cpu_temp_c=sample.cpu_temp_c,
+        gpu_temp_c=sample.gpu_temp_c,
+        ecpu_freq_mhz=int(cm["E-Cluster_freq_Mhz"]),
+        pcpu_freq_mhz=int(cm["P-Cluster_freq_Mhz"]),
+        gpu_freq_mhz=int(gm["freq_MHz"]),
+        ram_used_gb=float(ram.get("used_GB", 0.0)),
+        swap_used_gb=float(ram.get("swap_used_GB", 0.0)),
+        thermal_state=sample.thermal_pressure,
+        bandwidth_gbps=total_bw,
+        bandwidth_available=bw_avail,
+        e_cores=e_cores,
+        p_cores=p_cores,
+    )
+
+
+class Monitor:
+    """Synchronous, single-sample hardware monitor."""
+
+    def __init__(self, interval_s: float = 1.0, subsamples: int = 1):
+        self._interval_s = max(1, int(interval_s))
+        self._sampler, self.backend_name = create_sampler(
+            self._interval_s, subsamples=subsamples
+        )
+        # Prime delta: first sample() always returns None
+        self._sampler.sample()
+
+    @property
+    def manages_timing(self) -> bool:
+        """True if the underlying sampler manages its own sleep timing."""
+        return bool(getattr(self._sampler, "manages_timing", False))
+
+    def get_snapshot(self) -> SystemSnapshot:
+        """Block for interval_s (unless sampler manages timing), return SystemSnapshot."""
+        if not self.manages_timing:
+            time.sleep(self._interval_s)
+        sample = self._sampler.sample()
+        while sample is None:
+            # A None sample means the delta interval was non-positive; sleep
+            # briefly so the re-sample sees a meaningful elapsed time (avoids a
+            # frame with an inflated interval/elapsed power scale).
+            time.sleep(0.01)
+            sample = self._sampler.sample()
+        ram = get_ram_metrics_dict()
+        return _sample_to_snapshot(sample, ram, self._interval_s)
+
+    def close(self):
+        self._sampler.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+
+class Profiler:
+    """Threaded background collector. Use as a context manager."""
+
+    def __init__(self, interval_s: float = 1.0):
+        self._interval_s = interval_s
+        self._monitor = Monitor(interval_s)
+        self._samples: list = []
+        self._lock = threading.Lock()
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._alerts: list = []  # list of (metric, threshold, callback)
+
+    def __enter__(self):
+        self.start()
+        return self
+
+    def __exit__(self, *_):
+        self.stop()
+
+    def start(self):
+        with self._lock:
+            self._samples.clear()
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._run_loop, daemon=True)
+        self._thread.start()
+
+    def stop(self):
+        self._stop_event.set()
+        if self._thread:
+            self._thread.join()
+        self._monitor.close()
+
+    def _run_loop(self):
+        while not self._stop_event.is_set():
+            snapshot = self._monitor.get_snapshot()  # blocks for interval_s
+            with self._lock:
+                self._samples.append(snapshot)
+            for metric, threshold, callback in self._alerts:
+                val = getattr(snapshot, metric, None)
+                if val is not None and val >= threshold:
+                    try:
+                        callback(val)
+                    except Exception:
+                        pass
+
+    def register_alert(self, metric: str, threshold: float, callback):
+        """Fire callback(value) when snapshot.metric >= threshold."""
+        if metric not in SystemSnapshot.__dataclass_fields__:
+            raise ValueError(f"Unknown SystemSnapshot field: {metric!r}")
+        self._alerts.append((metric, threshold, callback))
+
+    def get_summary(self) -> dict:
+        with self._lock:
+            samples = list(self._samples)
+        if not samples:
+            return {}
+        duration_s = (
+            samples[-1].timestamp - samples[0].timestamp if len(samples) > 1 else 0.0
+        )
+        cpu_w = [s.cpu_watts for s in samples]
+        gpu_w = [s.gpu_watts for s in samples]
+        pkg_w = [s.package_watts for s in samples]
+        avg_cpu = sum(cpu_w) / len(cpu_w)
+        avg_gpu = sum(gpu_w) / len(gpu_w)
+        avg_pkg = sum(pkg_w) / len(pkg_w)
+        return {
+            "sample_count": len(samples),
+            "duration_s": duration_s,
+            "avg_cpu_watts": avg_cpu,
+            "avg_gpu_watts": avg_gpu,
+            "avg_package_watts": avg_pkg,
+            "peak_cpu_watts": max(cpu_w),
+            "peak_gpu_watts": max(gpu_w),
+            "peak_package_watts": max(pkg_w),
+            "total_cpu_joules": avg_cpu * duration_s,
+            "total_gpu_joules": avg_gpu * duration_s,
+            "total_package_joules": avg_pkg * duration_s,
+        }
+
+    def to_pandas(self):
+        try:
+            import pandas as pd
+        except ImportError:
+            raise ImportError("pandas is required: pip install actop[pandas]")
+        with self._lock:
+            samples = list(self._samples)
+        df = pd.DataFrame([dataclasses.asdict(s) for s in samples])
+        df["datetime"] = pd.to_datetime(df["timestamp"], unit="s")
+        df.set_index("datetime", inplace=True)
+        return df
+
+
+class AsyncMonitor(Monitor):
+    """Async wrapper around Monitor; runs blocking get_snapshot in a thread pool."""
+
+    async def get_snapshot_async(self) -> SystemSnapshot:
+        import asyncio
+
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self.get_snapshot)

actop/config.py

@@ -0,0 +1,95 @@
+"""Dashboard configuration dataclass."""
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class DashboardConfig:
+    """Immutable values computed once from args + soc_info_dict."""
+
+    sample_interval: int
+    avg_window: int
+    usage_track_window: int
+    core_history_window: int
+
+    cpu_chart_ref_w: float
+    gpu_chart_ref_w: float
+    ane_max_power: float
+    package_ref_w: float
+    max_cpu_bw: float
+    max_gpu_bw: float
+    max_media_bw: float
+
+    e_core_count: int
+    p_core_count: int
+
+    power_scale: str
+    chart_glyph: str
+    show_cores: bool
+
+    alert_bw_sat_percent: int
+    alert_package_power_percent: int
+    alert_swap_rise_gb: float
+    alert_sustain_samples: int
+
+    subsamples: int
+
+    process_display_count: int
+    show_processes: bool
+    process_filter_pattern: Optional[object]  # compiled regex or None
+    proc_filter_raw: str
+
+
+def create_dashboard_config(args, soc_info_dict):
+    """Build an immutable DashboardConfig from parsed CLI args and SoC info."""
+    sample_interval = max(1, args.interval)
+    avg_window = max(1, int(args.avg / sample_interval))
+    usage_track_window = max(200, int(args.avg / sample_interval))
+    core_history_window = max(200, int(args.avg / sample_interval))
+
+    cpu_chart_ref_w = soc_info_dict["cpu_chart_ref_w"]
+    gpu_chart_ref_w = soc_info_dict["gpu_chart_ref_w"]
+    ane_max_power = 8.0
+    package_ref_w = max(cpu_chart_ref_w + gpu_chart_ref_w + ane_max_power, 1.0)
+    max_cpu_bw = max(float(soc_info_dict.get("cpu_max_bw", 0.0)), 1.0)
+    max_gpu_bw = max(float(soc_info_dict.get("gpu_max_bw", 0.0)), 1.0)
+    max_media_bw = max(max_cpu_bw, max_gpu_bw)
+
+    e_core_count = max(0, int(soc_info_dict["e_core_count"]))
+    p_core_count = max(0, int(soc_info_dict["p_core_count"]))
+
+    process_filter_pattern = (
+        re.compile(args.proc_filter, re.IGNORECASE)
+        if getattr(args, "proc_filter", "")
+        else None
+    )
+
+    return DashboardConfig(
+        sample_interval=sample_interval,
+        avg_window=avg_window,
+        usage_track_window=usage_track_window,
+        core_history_window=core_history_window,
+        cpu_chart_ref_w=cpu_chart_ref_w,
+        gpu_chart_ref_w=gpu_chart_ref_w,
+        ane_max_power=ane_max_power,
+        package_ref_w=package_ref_w,
+        max_cpu_bw=max_cpu_bw,
+        max_gpu_bw=max_gpu_bw,
+        max_media_bw=max_media_bw,
+        e_core_count=e_core_count,
+        p_core_count=p_core_count,
+        power_scale=args.power_scale,
+        chart_glyph=getattr(args, "chart_glyph", "dots"),
+        show_cores=args.show_cores,
+        alert_bw_sat_percent=args.alert_bw_sat_percent,
+        alert_package_power_percent=args.alert_package_power_percent,
+        alert_swap_rise_gb=args.alert_swap_rise_gb,
+        alert_sustain_samples=max(1, int(args.alert_sustain_samples)),
+        process_display_count=50,
+        show_processes=bool(getattr(args, "show_processes", False)),
+        subsamples=max(1, int(args.subsamples)),
+        process_filter_pattern=process_filter_pattern,
+        proc_filter_raw=getattr(args, "proc_filter", ""),
+    )