alag 0.1.0__py3-none-win_amd64.whl

alag/__init__.py

@@ -0,0 +1,6 @@
+"""ALAG: a simple logging and graphing tool for researchers."""
+
+from .logger import ALAG
+
+__all__ = ["ALAG"]
+__version__ = "0.1.0"

alag/logger.py

@@ -0,0 +1,336 @@
+"""The ALAG logger.
+
+``log()`` runs inside the training loop, so it does no I/O, no formatting and
+takes no lock. It puts raw values on a deque and returns. A daemon thread does
+the formatting and the disk writes.
+"""
+
+import atexit
+import collections
+import csv
+import json
+import os
+import shutil
+import subprocess
+import threading
+import time
+import weakref
+
+_FLUSH_INTERVAL = 1.0  # seconds between background writes
+_SYSTEM_INTERVAL = 10.0  # seconds between system metric samples
+_GPU_FIELDS = (
+    ("utilization.gpu", "util_percent"),
+    ("memory.used", "memory_gb"),
+    ("temperature.gpu", "temperature_c"),
+    ("power.draw", "power_w"),
+)
+
+
+def _check_segment(kind, value):
+    if not value or value in (".", "..") or "/" in value or "\\" in value:
+        raise ValueError(f"invalid {kind} name: {value!r}")
+
+
+def _check_image_name(name):
+    parts = name.split("/")
+    if "\\" in name or any(p in ("", ".", "..") for p in parts):
+        raise ValueError(f"invalid image name: {name!r}")
+
+
+def _update_json(path, default, change):
+    """Rewrite a small JSON file atomically, so the viewer never reads half of it."""
+    try:
+        with open(path) as f:
+            data = json.load(f)
+    except (FileNotFoundError, ValueError):
+        data = default
+    data = change(data)
+    tmp = f"{path}.{os.getpid()}.tmp"
+    with open(tmp, "w") as f:
+        json.dump(data, f, indent=2)
+    os.replace(tmp, path)
+
+
+def _parse_gpus(text):
+    """Turn nvidia-smi CSV output into metrics, skipping fields shown as [N/A]."""
+    stats = {}
+    for index, line in enumerate(text.strip().splitlines()):
+        for (_, name), value in zip(_GPU_FIELDS, line.split(",")):
+            try:
+                number = float(value)
+            except ValueError:
+                continue
+            stats[f"system/gpu{index}_{name}"] = (
+                number / 1024 if name == "memory_gb" else number
+            )
+    return stats
+
+
+def _read_gpus():
+    """Return GPU metrics, or None if nvidia-smi isn't usable on this machine."""
+    query = ",".join(field for field, _ in _GPU_FIELDS)
+    try:
+        result = subprocess.run(
+            ["nvidia-smi", f"--query-gpu={query}", "--format=csv,noheader,nounits"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return _parse_gpus(result.stdout) if result.returncode == 0 else None
+
+
+def _new_experiment_dir(parent, experiment):
+    """Create a fresh folder, adding -2, -3... if the name is already used."""
+    os.makedirs(parent, exist_ok=True)
+    name, n = experiment, 1
+    while True:
+        path = os.path.join(parent, name)
+        try:
+            os.mkdir(path)
+            return path
+        except FileExistsError:
+            n += 1
+            name = f"{experiment}-{n}"
+
+
+class ALAG:
+    """Logs one experiment to ``<root>/<group>/<experiment>/``.
+
+    If that experiment already exists, a new one is created with a numeric
+    suffix, so re-running a script never mixes two runs in the same charts.
+    """
+
+    def __init__(
+        self,
+        group,
+        experiment,
+        config=None,
+        root="logs",
+        tags=None,
+        note=None,
+        system_metrics=False,
+    ):
+        _check_segment("group", group)
+        _check_segment("experiment", experiment)
+
+        psutil = None
+        if system_metrics:  # checked first, so a failure leaves no empty folder
+            try:
+                import psutil
+            except ImportError:
+                raise ImportError(
+                    "system_metrics=True needs psutil: pip install 'alag[system]'"
+                ) from None
+
+        self.path = _new_experiment_dir(os.path.join(root, group), experiment)
+        self.experiment = os.path.basename(self.path)
+        self.group = group
+        self._group_path = os.path.join(root, group)
+
+        with open(os.path.join(self.path, "config.json"), "w") as f:
+            json.dump(config or {}, f, indent=2, default=str)
+
+        if tags:
+            self.tag(*tags)
+        if note is not None:
+            self.note(note)
+
+        self._file = open(
+            os.path.join(self.path, "metrics.csv"), "w", newline="", buffering=1 << 16
+        )
+        self._writer = csv.writer(self._file, lineterminator="\n")
+        self._writer.writerow(("step", "time", "metric", "value"))
+        self._file.flush()
+
+        self._queue = collections.deque()
+        self._auto_step = 0
+        self._stop = threading.Event()
+        self._write_lock = threading.Lock()
+        self._closed = False
+
+        self._thread = threading.Thread(
+            target=self._run, name="alag-writer", daemon=True
+        )
+        self._thread.start()
+
+        self._system_thread = None
+        if psutil is not None:
+            self._system_thread = threading.Thread(
+                target=self._watch_system, args=(psutil,), name="alag-system", daemon=True
+            )
+            self._system_thread.start()
+
+        # A weak reference, so atexit doesn't keep every logger alive.
+        ref = weakref.ref(self)
+        self._atexit = lambda: (lambda s: s and s.close())(ref())
+        atexit.register(self._atexit)
+
+    def log(self, metrics, step=None):
+        """Queue scalars. Values may be numbers or 0-d tensors.
+
+        Tensors are detached here, not read: reading a GPU tensor would make
+        the training loop wait for the GPU. The writer thread reads them.
+        """
+        if step is None:
+            step = self._auto_step
+        self._auto_step = step + 1
+
+        items = list(metrics.items())
+        for i, (key, value) in enumerate(items):
+            kind = type(value)
+            if kind is not float and kind is not int:
+                detach = getattr(value, "detach", None)
+                if detach is not None:
+                    items[i] = (key, detach())
+        self._queue.append((step, time.time(), items))
+
+    def log_image(self, name, image, step=None):
+        """Save an image from a file path or a matplotlib figure.
+
+        This one runs on the calling thread: matplotlib isn't thread-safe, and
+        a path may be overwritten as soon as this returns.
+        """
+        _check_image_name(name)
+        if step is None:
+            step = max(self._auto_step - 1, 0)
+
+        folder = os.path.join(self.path, "images", *name.split("/"))
+        os.makedirs(folder, exist_ok=True)
+
+        if isinstance(image, (str, os.PathLike)):
+            ext = os.path.splitext(os.fspath(image))[1].lower() or ".png"
+            final = os.path.join(folder, f"{step}{ext}")
+            tmp = final + ".tmp"
+            shutil.copyfile(image, tmp)
+        elif hasattr(image, "savefig"):
+            final = os.path.join(folder, f"{step}.png")
+            tmp = final + ".tmp"
+            image.savefig(tmp, format="png", bbox_inches="tight")
+        else:
+            raise TypeError("image must be a file path or a matplotlib figure")
+        os.replace(tmp, final)  # the viewer never sees a half-written image
+
+    def tag(self, *tags):
+        """Add tags to this experiment. They show up in the viewer's left panel."""
+
+        def change(meta):
+            current = meta.get("tags", [])
+            meta["tags"] = current + [t for t in tags if t not in current]
+            return meta
+
+        _update_json(os.path.join(self.path, "meta.json"), {}, change)
+
+    def note(self, text):
+        """Set this experiment's note, replacing any earlier one."""
+
+        def change(meta):
+            meta["note"] = text
+            return meta
+
+        _update_json(os.path.join(self.path, "meta.json"), {}, change)
+
+    def flag(self, metric, by_step, below=None, above=None):
+        """Set a target for this group: ``metric`` should cross a value by a step.
+
+        ``logger.flag("val/loss", below=0.5, by_step=1000)`` marks that point on
+        the chart, and the viewer reports which experiments reached it in time.
+        """
+        if (below is None) == (above is None):
+            raise ValueError("pass exactly one of below= or above=")
+        flag = {
+            "metric": metric,
+            "direction": "below" if above is None else "above",
+            "value": below if above is None else above,
+            "step": by_step,
+        }
+
+        def change(flags):
+            return flags if flag in flags else flags + [flag]
+
+        _update_json(os.path.join(self._group_path, "flags.json"), [], change)
+
+    def section(self, name, *metrics):
+        """Show these metrics' charts under a heading, for the whole group.
+
+        ``logger.section("validation", "val/loss", "bleu")``. Metrics without a
+        section go under the part of their name before the first slash.
+        """
+
+        def change(layout):
+            layout.setdefault("sections", {}).update(dict.fromkeys(metrics, name))
+            return layout
+
+        _update_json(os.path.join(self._group_path, "layout.json"), {}, change)
+
+    def pin(self, *names):
+        """Keep these charts or images at the top of the page, for the whole group."""
+
+        def change(layout):
+            pinned = layout.get("pinned", [])
+            layout["pinned"] = pinned + [n for n in names if n not in pinned]
+            return layout
+
+        _update_json(os.path.join(self._group_path, "layout.json"), {}, change)
+
+    def flush(self):
+        """Write everything queued so far to disk."""
+        with self._write_lock:
+            self._drain()
+
+    def close(self):
+        """Flush and stop. Runs automatically when the program exits."""
+        if self._closed:
+            return
+        self._closed = True
+        self._stop.set()
+        self._thread.join()
+        if self._system_thread is not None:
+            self._system_thread.join()
+        self.flush()
+        self._file.close()
+        atexit.unregister(self._atexit)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    def _run(self):
+        while not self._stop.wait(_FLUSH_INTERVAL):
+            self.flush()
+
+    def _watch_system(self, psutil):
+        """Sample on this thread, so nothing here touches the training loop."""
+        process = psutil.Process()
+        psutil.cpu_percent()  # the first reading is meaningless, it starts the count
+        gpus = True
+        while not self._stop.wait(_SYSTEM_INTERVAL):
+            items = [
+                ("system/cpu_percent", psutil.cpu_percent()),
+                ("system/ram_used_gb", psutil.virtual_memory().used / 2**30),
+                ("system/process_ram_gb", process.memory_info().rss / 2**30),
+            ]
+            if gpus:
+                stats = _read_gpus()
+                gpus = stats is not None
+                items.extend((stats or {}).items())
+            step = max(self._auto_step - 1, 0)
+            self._queue.append((step, time.time(), items))
+
+    def _drain(self):
+        queue, writer = self._queue, self._writer
+        wrote = False
+        while queue:
+            step, when, items = queue.popleft()
+            for key, value in items:
+                try:
+                    value = float(value)  # blocks here for a GPU tensor
+                except (TypeError, ValueError):
+                    continue  # not a scalar, so there's nothing to chart
+                writer.writerow((step, f"{when:.3f}", key, value))
+                wrote = True
+        if wrote:
+            self._file.flush()

alag-0.1.0.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: alag
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Dist: psutil ; extra == 'system'
+Provides-Extra: system
+License-File: LICENSE
+Summary: A simple logging and graphing tool for researchers
+Keywords: experiment tracking,logging,machine learning,plotting
+Author: Sandeep S
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Issues, https://github.com/SandyTheAdventurer/alag/issues
+Project-URL: Repository, https://github.com/SandyTheAdventurer/alag
+
+# ALAG
+
+**A** simple **L**ogging **A**nd **G**raphing tool, for researchers.
+
+## Why
+
+Existing experiment trackers ask for more than a researcher who wants to log a run and look at the results should have to give:
+
+- **Weights & Biases** requires an account and other setup.
+- **MLflow** needs a tracking server that is heavy for this job, and comparing runs in it feels awkward.
+- **TensorBoard** has visualizations that leave a lot to be desired, and makes comparing multiple runs hard.
+
+ALAG aims to do two things well, logging and graphing, without the overhead. Comparing multiple runs is a core feature.
+
+## Install
+
+```sh
+pip install alag
+```
+
+This gives you the `ALAG` class for your training code and the `alag` command for viewing results.
+
+Wheels are built for Linux (x86-64 and ARM, glibc 2.17 or newer) and Windows. On macOS, pip builds ALAG from source, which needs [Rust](https://rustup.rs).
+
+## Usage
+
+Log from your training code:
+
+```python
+from alag import ALAG
+
+logger = ALAG(group="my-group", experiment="my-experiment", config={"lr": 3e-4})
+
+logger.log({"train/loss": 0.42}, step=100)
+logger.log_image("confusion-matrix", "confusion.png", step=100)  # from a file
+logger.log_image("loss-curve", fig, step=100)                    # from a matplotlib figure
+
+logger.tag("baseline", "ablation")
+logger.note("Loss spikes after the LR warmup ends")
+logger.flag("val/loss", below=0.5, by_step=1000)
+logger.section("validation", "val/loss", "bleu")
+logger.pin("val/loss")
+```
+
+`ALAG` also takes `tags=[...]`, `note="..."` and `system_metrics=True` directly.
+
+Then view your experiments:
+
+```sh
+alag                # serves ./logs at http://localhost:6100
+alag path/to/logs --port 8000
+alag --export report.html   # one HTML file to send to someone
+```
+
+If an experiment with that name already exists in the group, ALAG creates a new one with a number on the end, such as `my-experiment-2`, so a re-run never mixes with earlier results.
+
+To view experiments on a remote machine, run `alag` there and forward the port with `ssh -L 6100:localhost:6100 my-server`.
+
+## Speed
+
+`logger.log` is built to stay out of your training loop. It only puts the values on an in-memory queue and returns. A background thread formats them and writes to disk about once a second.
+
+You can pass GPU tensors straight to `logger.log`. The background thread reads them, so your training loop doesn't wait for the GPU the way it does with `loss.item()`.
+
+On an RTX 3050 laptop GPU, a `logger.log` call with a GPU tensor took about 15 µs. A 6 ms training step was no slower with logging than without it, with or without system metrics. Any difference was smaller than the variation between runs.
+
+`logger.log_image` does its work immediately, because matplotlib isn't thread-safe. Log images occasionally, not on every step.
+
+Queued values are written when your program exits, including after an exception. If the process is killed outright, you can lose about the last second of values.
+
+## What it logs
+
+- **Scalars**, such as loss and accuracy.
+- **Images**, such as custom graphs you make yourself.
+- **Hyperparameters**, from the `config` you pass to `ALAG`.
+- **System metrics**, if you turn them on.
+
+### System metrics
+
+These are off by default. To turn them on, install the extra and pass `system_metrics=True`:
+
+```sh
+pip install 'alag[system]'
+```
+
+```python
+logger = ALAG(group="my-group", experiment="my-experiment", system_metrics=True)
+```
+
+Every 10 seconds, a background thread logs CPU use, system RAM and your process's RAM under `system/`. If `nvidia-smi` is available, it also logs utilization, memory, temperature and power for each GPU. GPU memory is the total in use on that card, including other programs.
+
+Each sample uses your latest training step. Before your first `logger.log`, or during a long step, several samples share a step, so set **X axis** to **Time** to read these charts.
+
+## Storage
+
+Experiments are organized into groups. Each experiment is a plain folder inside its group's folder. There is no database or account.
+
+```
+logs/
+└── my-group/
+    ├── flags.json         # targets shared by the group
+    ├── layout.json        # chart sections and pins shared by the group
+    └── my-experiment/
+        ├── config.json    # the experiment's settings
+        ├── metrics.csv    # every scalar, appended as it is logged
+        ├── meta.json      # tags and note
+        └── images/        # logged images
+```
+
+`metrics.csv` has one row per logged value, so an experiment can add new metrics at any point and metrics logged at different intervals don't leave empty cells:
+
+```csv
+step,time,metric,value
+100,1762444800.1,train/loss,0.42
+100,1762444800.1,train/acc,0.81
+200,1762444812.6,train/loss,0.37
+200,1762444812.7,val/loss,0.45
+```
+
+## Viewing experiments
+
+The `alag` command is a small compiled Rust program that generates an HTML page and serves it on localhost. The page updates automatically while your experiments are training.
+
+A panel on the left lists your groups and the experiments inside them. Select experiments in the panel to compare them: each metric gets one chart, with a line for every selected experiment.
+
+### Hyperparameters
+
+The **Hyperparameters** tab has a row for each selected experiment and a column for each setting in its `config`. Settings that differ come first, in bold. Click a column to sort by it, or tick **Only settings that differ** to hide the rest.
+
+### Sections and pins
+
+Charts are grouped into sections by the part of the metric name before the first slash, so `val/loss` goes under `val` and `system/cpu_percent` goes under `system`.
+
+To choose a section yourself, use **Section** on a chart or `logger.section`. **Pin** on a chart or image, or `logger.pin`, moves it to the top of its tab.
+
+Sections and pins apply to the whole group, so they stay in place when you compare its experiments.
+
+### Mean and std over seeds
+
+Tick **Mean ± std over seeds** to merge selected experiments into one line with a shaded band. Experiments merge when they are in the same group and their configs differ only by a key named `seed`. Experiments with no `seed` in their config stay separate.
+
+The band is one sample standard deviation at each step. Smoothing is applied to each seed before merging.
+
+### Flags
+
+A flag sets a target, such as "`val/loss` should go below 0.5 by step 1,000". Set one with `logger.flag`, or with **Flag** on a chart, where clicking the chart fills in the values.
+
+The flag is drawn on the chart, and each experiment in the group is listed as reached, missed or not yet. Verdicts use the line as plotted, so they follow your smoothing and seed settings.
+
+### Notes and tags
+
+Add these in the **Notes** tab or from Python. Tags appear in the left panel, and the filter box searches names, tags and notes.
+
+### Exporting charts
+
+Each chart has **SVG**, **PNG**, **PDF**, **CSV** and **LaTeX** buttons. Exports use a white background and match the current view, including every selected experiment, smoothing, zoom, log scale and flags.
+
+**LaTeX** gives you a `pgfplots` figure to copy and paste. The data is included, so there's no file to upload, but long runs are thinned to keep it small enough for pdflatex. Your document needs:
+
+```latex
+\usepackage{pgfplots}
+\pgfplotsset{compat=1.18}
+```
+
+### Sharing a report
+
+`alag --export report.html` writes one HTML file that opens in any browser, with no server or install. It opens on the most recently updated group, with its experiments selected.
+
+You can still select experiments, zoom, smooth, merge seeds and export charts. It's a read-only snapshot, so it doesn't update, and notes, tags, flags, sections and pins can't be changed.
+
+The file contains everything in the log folder, including every group, config, note and image. To share only part of it, export a folder with just those groups. Runs with many images can make the file large.
+
+## Building wheels
+
+`scripts/build-wheels.sh` builds the source package and every wheel into `dist/`. It needs only Docker.
+
+## License
+
+MIT
+

alag-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+alag/__init__.py,sha256=odLgkMdpz1fJM24SViGpytVRLkT6FWjNJIGxc-MbUb0,132
+alag/logger.py,sha256=QP1ggtu3b0PVO7yXK-R7WkNCU6pBx3Fq40ajc8vB_ps,11463
+alag-0.1.0.data/scripts/alag.exe,sha256=H4TdtciyaFD6JjiCJg12x7wakRmIXVLiBLJ2hLg80u0,452608
+alag-0.1.0.dist-info/METADATA,sha256=xeg9R0R3YBzRTLWNnAQeJivzx-f_86ITGKHoXkjAVBM,8923
+alag-0.1.0.dist-info/WHEEL,sha256=8Aej0W0a6Cz6apA3IzJrTnxLRVLAt-w0Oh8SA3Con_c,94
+alag-0.1.0.dist-info/licenses/LICENSE,sha256=MJF8cEazYYmeI8Ol3KH2xvCIH0X0qgDEplEjxhRZB6Y,1066
+alag-0.1.0.dist-info/sboms/alag.cyclonedx.json,sha256=EN0MyLrtEFmGxtKlveWLsr5nAc_r9NneGypbdANTjQQ,1373
+alag-0.1.0.dist-info/RECORD,,

alag-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.15.0)
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64

alag-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sandeep S
+
+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.

alag-0.1.0.dist-info/sboms/alag.cyclonedx.json

@@ -0,0 +1,57 @@
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.5",
+  "version": 1,
+  "serialNumber": "urn:uuid:d96090c6-b0ff-49b7-9050-fa7dc1967c02",
+  "metadata": {
+    "timestamp": "2026-11-07T15:31:24.158007241Z",
+    "tools": [
+      {
+        "vendor": "CycloneDX",
+        "name": "cargo-cyclonedx",
+        "version": "0.5.9"
+      }
+    ],
+    "component": {
+      "type": "application",
+      "bom-ref": "path+file:///io#alag@0.1.0",
+      "name": "alag",
+      "version": "0.1.0",
+      "description": "A simple logging and graphing tool for researchers",
+      "scope": "required",
+      "licenses": [
+        {
+          "expression": "MIT"
+        }
+      ],
+      "purl": "pkg:cargo/alag@0.1.0?download_url=file://.",
+      "externalReferences": [
+        {
+          "type": "vcs",
+          "url": "https://github.com/SandyTheAdventurer/alag"
+        }
+      ],
+      "components": [
+        {
+          "type": "application",
+          "bom-ref": "path+file:///io#alag@0.1.0 bin-target-0",
+          "name": "alag",
+          "version": "0.1.0",
+          "purl": "pkg:cargo/alag@0.1.0?download_url=file://.#src/main.rs"
+        }
+      ]
+    },
+    "properties": [
+      {
+        "name": "cdx:rustc:sbom:target:all_targets",
+        "value": "true"
+      }
+    ]
+  },
+  "components": [],
+  "dependencies": [
+    {
+      "ref": "path+file:///io#alag@0.1.0"
+    }
+  ]
+}