alag 0.1.0__tar.gz

alag-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.9", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: cargo test
+      - run: pip install pytest psutil matplotlib
+      - run: python -m pytest tests
+        env:
+          PYTHONPATH: python
+
+  wheels:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-latest, target: x86_64, manylinux: "2014" }
+          - { os: ubuntu-latest, target: aarch64, manylinux: "2014" }
+          - { os: macos-latest, target: x86_64 }
+          - { os: macos-latest, target: aarch64 }
+          - { os: windows-latest, target: x64 }
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          manylinux: ${{ matrix.manylinux || 'auto' }}
+          args: --release --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheel-${{ matrix.os }}-${{ matrix.target }}
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist

alag-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+target/
+dist/
+logs/
+__pycache__/
+.pytest_cache/
+*.so
+.venv/

alag-0.1.0/Cargo.lock

@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "alag"
+version = "0.1.0"

alag-0.1.0/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "alag"
+version = "0.1.0"
+edition = "2021"
+description = "A simple logging and graphing tool for researchers"
+license = "MIT"
+repository = "https://github.com/SandyTheAdventurer/alag"
+readme = "README.md"
+
+[[bin]]
+name = "alag"
+path = "src/main.rs"
+
+[profile.release]
+opt-level = "s"
+lto = true
+strip = true
+panic = "abort"

alag-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,179 @@
+# 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/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["maturin>=1.8,<2"]
+build-backend = "maturin"
+
+[project]
+name = "alag"
+version = "0.1.0"
+description = "A simple logging and graphing tool for researchers"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Sandeep S" }]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["experiment tracking", "logging", "machine learning", "plotting"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Rust",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+[project.urls]
+Repository = "https://github.com/SandyTheAdventurer/alag"
+Issues = "https://github.com/SandyTheAdventurer/alag/issues"
+
+[project.optional-dependencies]
+system = ["psutil"]
+
+[tool.maturin]
+bindings = "bin"
+python-source = "python"
+module-name = "alag"

alag-0.1.0/python/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"