mllogs 0.1.3__tar.gz

mllogs-0.1.3/LICENSE

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

mllogs-0.1.3/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: mllogs
+Version: 0.1.3
+Summary: Local experiment logging for machine learning
+Author: Finn Walsh
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# mllogs
+
+Local experiment logging for machine learning.
+
+## Installation
+
+```bash
+pip install mllogs
+```
+
+## Usage
+
+```python
+from mllogs import MLLogsClient
+
+client = MLLogsClient()
+
+client.start_run(
+    name="baseline",
+    run_type="training",
+)
+
+client.log_param("learning_rate", 0.01)
+client.log_metric("accuracy", 0.92)
+client.set_tag("model", "logistic_regression")
+
+client.end_run()
+```
+
+## Features
+
+- Start and end experiment runs
+- Log parameters, metrics, and tags
+- Save runs to local storage
+- Load, list, and delete saved runs
+
+## Development
+
+Install from source with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+## License
+
+MIT

mllogs-0.1.3/README.md

@@ -0,0 +1,53 @@
+# mllogs
+
+Local experiment logging for machine learning.
+
+## Installation
+
+```bash
+pip install mllogs
+```
+
+## Usage
+
+```python
+from mllogs import MLLogsClient
+
+client = MLLogsClient()
+
+client.start_run(
+    name="baseline",
+    run_type="training",
+)
+
+client.log_param("learning_rate", 0.01)
+client.log_metric("accuracy", 0.92)
+client.set_tag("model", "logistic_regression")
+
+client.end_run()
+```
+
+## Features
+
+- Start and end experiment runs
+- Log parameters, metrics, and tags
+- Save runs to local storage
+- Load, list, and delete saved runs
+
+## Development
+
+Install from source with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+## License
+
+MIT

mllogs-0.1.3/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project]
+name = "mllogs"
+version = "0.1.3"
+description = "Local experiment logging for machine learning"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Finn Walsh" }
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]

mllogs-0.1.3/setup.cfg

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

mllogs-0.1.3/src/mllogs/client.py

@@ -0,0 +1,59 @@
+from typing import Any
+from datetime import datetime, UTC
+from uuid import uuid4
+
+from .run import Run, RunStatus
+
+
+class MLLogsClient:
+    def __init__(self):
+        self._active_run: Run | None = None
+
+    def start_run(
+            self,
+            name: str | None = None,
+            run_type: str | None = None,
+    ) -> None:
+        """
+        Start a new MLLogs run.
+
+        Args:
+            name: Optional name for the run.
+            run_type: Optional type used to categorize the run.
+        """
+        # generate run id
+        started_at = datetime.now(UTC)
+        timestamp = started_at.strftime("%Y%m%d%H%M%S")
+        random_suffix = uuid4().hex[:8]
+        run_id = f"{timestamp}-{random_suffix}"
+
+        self._active_run = Run(
+            id=run_id,
+            name=name,
+            run_type=run_type,
+            status = RunStatus.RUNNING,
+            started_at=started_at,
+        )
+        # END
+
+
+    def log_param(self, key: str, value: Any) -> None:
+        self._active_run.params[key] = value
+
+
+    def log_metric(self, key: str, value: float) -> None:
+        self._active_run.metrics[key] = value
+
+
+    def set_tag(self, key: str, value: str) -> None:
+        self._active_run.tags[key] = value
+
+
+    def end_run(self) -> None:
+        self._active_run.ended_at = datetime.now(UTC)
+
+        self._active_run.status = RunStatus.COMPLETE
+
+        # clear run
+        self._active_run = None
+        # END

mllogs-0.1.3/src/mllogs/run.py

@@ -0,0 +1,88 @@
+from datetime import datetime
+from dataclasses import dataclass, field
+from typing import Any
+from enum import Enum
+
+
+class RunStatus(Enum):
+    RUNNING = "running"
+    COMPLETE = "complete"
+    FAILED = "failed"
+
+
+@dataclass
+class Artifact:
+    name: str
+    uri: str
+    artifact_type: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "name": self.name,
+            "uri": self.uri,
+            "artifact_type": self.artifact_type,
+        }
+
+
+    @classmethod
+    def from_dict(cls, d: dict[str, str]) -> "Artifact":
+        return cls(
+            name = d["name"],
+            uri = d["uri"],
+            artifact_type = d["artifact_type"],
+        )
+
+
+@dataclass
+class Run:
+    id: str
+    started_at: datetime
+    status: RunStatus
+
+    name: str | None = None
+    run_type: str | None =  None
+    ended_at: datetime | None = None
+
+    params: dict[str, Any] = field(default_factory=dict)
+    metrics: dict[str, float] = field(default_factory=dict)
+    tags: dict[str, str] = field(default_factory=dict)
+    artifacts: list[Artifact] = field(default_factory=list)
+
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "started_at": self.started_at.isoformat(),
+            "status": self.status.value,
+            "name": self.name,
+            "run_type": self.run_type,
+            "ended_at": (
+                self.ended_at.isoformat()
+                if self.ended_at is not None
+                else None
+            ),
+            "params": self.params,
+            "metrics": self.metrics,
+            "tags": self.tags,
+            "artifacts": [a.to_dict() for a in self.artifacts],
+        }
+
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "Run":
+        return cls(
+            id = d["id"],
+            started_at = datetime.fromisoformat(d["started_at"]),
+            status = RunStatus(d["status"]),
+            name = d["name"],
+            run_type = d["run_type"],
+            ended_at = (
+                datetime.fromisoformat(d["ended_at"])
+                if d["ended_at"] is not None
+                else None
+            ),
+            params = d["params"],
+            metrics = d["metrics"],
+            tags = d["tags"],
+            artifacts = [Artifact.from_dict(a) for a in d["artifacts"]],
+        )

mllogs-0.1.3/src/mllogs/storage.py

@@ -0,0 +1,72 @@
+from pathlib import Path
+import json
+
+from .run import Run
+
+
+class LocalFileStore:
+    def __init__(self, root_dir: str | Path = ".mllogs") -> None:
+        """
+        Initializes LocalFileStore and creates runs directory if it
+        does not already exist.
+        """
+        self._root_dir = Path(root_dir)
+        self._runs_dir = self._root_dir / "runs"
+
+        self._runs_dir.mkdir(parents=True, exist_ok=True)
+
+    def save_run(self, run: Run) -> None:
+        """
+        Writes Run to storage as JSON file.
+        """
+        path = self._runs_dir / f"{run.id}.json"
+
+        with path.open("w") as f:
+            json.dump(run.to_dict(), f, indent=4)
+
+
+    def load_run(self, run_id: str) -> Run:
+        """
+        Reads JSON run file from storage and returns a Run.
+        """
+        path = self._runs_dir / f"{run_id}.json"
+
+        with path.open("r") as f:
+            run_dict = json.load(f)
+
+        return Run.from_dict(run_dict)
+
+    
+    def list_runs(self, limit: int | None = None) -> list[Run]:
+        """
+        Returns the most recent runs.
+
+        If limit is None, returns all runs.
+        """
+        if limit is not None and limit <= 0:
+            raise ValueError("limit must be greater than 0")
+
+        paths = sorted(
+            self._runs_dir.glob("*.json"),
+            reverse=True, # latest first
+        )
+
+        if limit is not None:
+            paths = paths[:limit]
+
+        runs = []
+
+        for path in paths:
+            run = self.load_run(path.stem)
+            runs.append(run)
+
+        return runs
+
+
+    def delete_run(self, run_id: str) -> None:
+        """
+        Deletes a run from storage by run ID.
+        """
+        path = self._runs_dir / f"{run_id}.json"
+
+        path.unlink()

mllogs-0.1.3/src/mllogs.egg-info/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: mllogs
+Version: 0.1.3
+Summary: Local experiment logging for machine learning
+Author: Finn Walsh
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# mllogs
+
+Local experiment logging for machine learning.
+
+## Installation
+
+```bash
+pip install mllogs
+```
+
+## Usage
+
+```python
+from mllogs import MLLogsClient
+
+client = MLLogsClient()
+
+client.start_run(
+    name="baseline",
+    run_type="training",
+)
+
+client.log_param("learning_rate", 0.01)
+client.log_metric("accuracy", 0.92)
+client.set_tag("model", "logistic_regression")
+
+client.end_run()
+```
+
+## Features
+
+- Start and end experiment runs
+- Log parameters, metrics, and tags
+- Save runs to local storage
+- Load, list, and delete saved runs
+
+## Development
+
+Install from source with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+## License
+
+MIT

mllogs-0.1.3/src/mllogs.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/mllogs/__init__.py
+src/mllogs/client.py
+src/mllogs/run.py
+src/mllogs/storage.py
+src/mllogs.egg-info/PKG-INFO
+src/mllogs.egg-info/SOURCES.txt
+src/mllogs.egg-info/dependency_links.txt
+src/mllogs.egg-info/requires.txt
+src/mllogs.egg-info/top_level.txt
+tests/test_client.py
+tests/test_run.py
+tests/test_storage.py

mllogs-0.1.3/src/mllogs.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mllogs-0.1.3/src/mllogs.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=8.0

mllogs-0.1.3/src/mllogs.egg-info/top_level.txt

@@ -0,0 +1 @@
+mllogs

mllogs-0.1.3/tests/test_client.py

@@ -0,0 +1,57 @@
+from mllogs.run import RunStatus
+from mllogs.client import MLLogsClient
+
+
+def test_start_run() -> None:
+    client = MLLogsClient()
+    client.start_run(
+        name="run1",
+        run_type="training",
+    )
+
+    run = client._active_run
+
+    # assert active run is generated
+    assert run is not None
+
+    # assert necessary fields are generated / populated
+    assert run.started_at is not None
+    assert run.id is not None
+    assert run.status == RunStatus.RUNNING
+
+    # assert passed parameters populate designated fields
+    assert run.name == "run1"
+    assert run.run_type == "training"
+
+    # assert no additional fields are populated
+    assert run.ended_at is None
+
+
+def test_end_run() -> None:
+    client = MLLogsClient()
+
+    client.start_run()
+    client.end_run()
+
+    assert client._active_run is None
+
+
+def test_mutate_params() -> None:
+    client = MLLogsClient()
+
+    client.start_run()
+
+    # log param
+    client.log_param("alpha", 0.1)
+    assert "alpha" in client._active_run.params.keys()
+    assert client._active_run.params["alpha"] == 0.1
+
+    # log metric
+    client.log_metric("RMSE", 0.01)
+    assert "RMSE" in client._active_run.metrics.keys()
+    assert client._active_run.metrics["RMSE"] == 0.01
+
+    # set tag
+    client.set_tag("ml_model", "ridge")
+    assert "ml_model" in client._active_run.tags.keys()
+    assert client._active_run.tags["ml_model"] == "ridge"

mllogs-0.1.3/tests/test_run.py

@@ -0,0 +1,69 @@
+from datetime import datetime, UTC
+
+from mllogs.run import Run, RunStatus
+
+
+def test_run_defaults():
+    started_at = datetime(2000, 1, 1, 0, 0, tzinfo=UTC)
+    run = Run(
+        id="run-123",
+        status=RunStatus.RUNNING,
+        started_at=started_at,
+    )
+
+    assert run.name is None
+    assert run.run_type is None
+    assert run.ended_at is None
+    assert run.params == {}
+    assert run.metrics == {}
+    assert run.tags == {}
+    assert run.artifacts == []
+
+
+def test_to_dict():
+    started_at = datetime(2000, 1, 1, 0, 0, tzinfo=UTC)
+    run = Run(
+        id="run-123",
+        status=RunStatus.RUNNING,
+        started_at=started_at,
+    )
+
+    d = run.to_dict()
+
+    assert d["id"] == "run-123"
+    assert d["status"] == "running"
+    assert d["started_at"] == "2000-01-01T00:00:00+00:00"
+
+
+def test_from_dict():
+    d = {
+        "id": "run-123",
+        "status": "running",
+        "started_at": "2000-01-01T00:00:00+00:00",
+        "name": None,
+        "run_type": None,
+        "ended_at": None,
+        "params": {},
+        "metrics": {},
+        "tags": {},
+        "artifacts": [],
+    }
+
+    run = Run.from_dict(d)
+
+    assert run.started_at == datetime(2000, 1, 1, 0, 0, tzinfo=UTC)
+    assert run.status == RunStatus.RUNNING
+
+
+def test_serialization_round_trip():
+    started_at = datetime(2000, 1, 1, 0, 0, tzinfo=UTC)
+
+    before = Run(
+        id="run-123",
+        status=RunStatus.RUNNING,
+        started_at=started_at,
+    )
+
+    after = Run.from_dict(before.to_dict())
+
+    assert before == after

mllogs-0.1.3/tests/test_storage.py

@@ -0,0 +1,66 @@
+from pathlib import Path
+from datetime import datetime, UTC
+import pytest
+
+from mllogs.run import Run, RunStatus
+from mllogs.storage import LocalFileStore
+
+
+def test_persistence_round_trip(tmp_path: Path) -> None:
+    storage = LocalFileStore(root_dir=tmp_path)
+
+    run = Run(
+        id="run123",
+        status=RunStatus.RUNNING,
+        started_at=datetime.now(UTC),
+    )
+    run_path = storage._runs_dir / f"{run.id}.json"
+
+    # save
+    storage.save_run(run)
+    assert run_path.is_file()
+
+    # load
+    run_after = storage.load_run(run.id)
+    assert run == run_after
+
+    # delete
+    storage.delete_run(run.id)
+    assert not run_path.exists()
+
+
+def test_list_runs(tmp_path: Path) -> None:
+    storage = LocalFileStore(root_dir=tmp_path)
+
+    for run_id in ["001", "002", "003"]:
+        storage.save_run(Run(
+            id=run_id,
+            status=RunStatus.RUNNING,
+            started_at=datetime.now(UTC),
+        ))
+
+    runs = storage.list_runs()
+
+    assert [run.id for run in runs] == ["003", "002", "001"]
+
+
+def test_list_runs_with_limit(tmp_path: Path) -> None:
+    storage = LocalFileStore(root_dir=tmp_path)
+    
+    for run_id in ["001", "002", "003"]:
+        storage.save_run(Run(
+            id=run_id,
+            status=RunStatus.RUNNING,
+            started_at=datetime.now(UTC),
+        ))
+
+    runs = storage.list_runs(limit=2)
+
+    assert [run.id for run in runs] == ["003", "002"]
+
+
+def test_runs_with_invalid_limit(tmp_path: Path) -> None:
+    storage = LocalFileStore(root_dir=tmp_path)
+
+    with pytest.raises(ValueError):
+        storage.list_runs(limit=0)