mllogs 0.1.3__py3-none-any.whl

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+mllogs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mllogs/client.py,sha256=o1gjE9NT4UqQfEgJf4FfK8MZhaAOiSdYZm9vPtMOzrY,1447
+mllogs/run.py,sha256=gsZnG-hWhN6fXDie73xz6H8X3ts_jBV0MmjcZj3i2DY,2324
+mllogs/storage.py,sha256=uILR8SYsZL6IjC6vxl-tlABo7LRcSHkFIRwuj10FuSo,1753
+mllogs-0.1.3.dist-info/licenses/LICENSE,sha256=JlLb6swOXBl0b_vjSfh-Cd0m6XWAAnAgmzIivu6GJkc,1067
+mllogs-0.1.3.dist-info/METADATA,sha256=KQIyG1TfN5vWeTxOmQ7b6iV5lhYyO5a8yFJ6t5oA_mQ,1027
+mllogs-0.1.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mllogs-0.1.3.dist-info/top_level.txt,sha256=CHao4JCO6OOKT-wDwz8xEDDdTRYC5zL8JBroggHTyWY,7
+mllogs-0.1.3.dist-info/RECORD,,

mllogs-0.1.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mllogs-0.1.3.dist-info/licenses/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.dist-info/top_level.txt

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