maarg 0.2.0__py3-none-any.whl

maarg/__init__.py

@@ -0,0 +1,36 @@
+"""
+maarg — zero-instrumentation experiment tracking for Python.
+
+    from maarg import track
+
+    @track
+    def train_model(learning_rate, epochs):
+        return {"accuracy": 0.95}
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("maarg")
+except PackageNotFoundError:
+    # Fallback for uninstalled local development mode
+    __version__ = "0.2.0"
+
+from maarg._convenience import best_run, filter_runs, get_runs, top_n
+from maarg._models import Run
+from maarg._query import compare
+from maarg._tracking import track
+from maarg.storage._base import StorageBackend as StorageBackend
+from maarg.storage._sqlite import SQLiteStorage as SQLiteStorage
+
+__all__ = [
+    "Run",
+    "SQLiteStorage",
+    "StorageBackend",
+    "best_run",
+    "compare",
+    "filter_runs",
+    "get_runs",
+    "top_n",
+    "track",
+]

maarg/_capture.py

@@ -0,0 +1,132 @@
+"""
+Input filtering logic for maarg.
+
+Decides which of a function's arguments are simple "settings" worth
+logging automatically, versus large/complex objects (datasets, models,
+file handles) that should be skipped.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+# Defaults — overridable per-call via the @track decorator later.
+DEFAULT_MAX_SCALAR_BYTES = 1000
+DEFAULT_MAX_COLLECTION_LENGTH = 20
+
+_SCALAR_TYPES = (int, float, bool, str, type(None))
+_COLLECTION_TYPES = (list, tuple, dict)
+
+
+def is_loggable(
+    value: Any,
+    max_scalar_bytes: int = DEFAULT_MAX_SCALAR_BYTES,
+    max_collection_length: int = DEFAULT_MAX_COLLECTION_LENGTH,
+) -> bool:
+    """
+    Decide whether `value` is simple enough to log automatically.
+
+    Scalars (int, float, bool, str, None) are loggable if they're under
+    `max_scalar_bytes` in size. Collections (list, tuple, dict) are
+    loggable if they have at most `max_collection_length` items AND
+    every item inside them is itself loggable (checked recursively).
+    Anything else (DataFrames, arrays, custom objects, file handles,
+    etc.) is never loggable.
+    """
+    if isinstance(value, _SCALAR_TYPES):
+        return sys.getsizeof(value) <= max_scalar_bytes
+
+    if isinstance(value, _COLLECTION_TYPES):
+        if len(value) > max_collection_length:
+            return False
+
+        items = value.values() if isinstance(value, dict) else value
+        return all(
+            is_loggable(item, max_scalar_bytes, max_collection_length)
+            for item in items
+        )
+
+    # DataFrames, ndarrays, custom classes, file handles, etc.
+    return False
+
+
+def filter_inputs(
+    args: dict[str, Any],
+    max_scalar_bytes: int = DEFAULT_MAX_SCALAR_BYTES,
+    max_collection_length: int = DEFAULT_MAX_COLLECTION_LENGTH,
+) -> dict[str, Any]:
+    """
+    Given a dict of {param_name: value} (e.g. from a function's bound
+    arguments), return only the entries that pass `is_loggable`.
+    """
+    return {
+        name: value
+        for name, value in args.items()
+        if is_loggable(value, max_scalar_bytes, max_collection_length)
+    }
+
+
+# ── Output splitting ─────────────────────────────────────────────────
+
+
+OTHER_REPR_MAX_LEN = 200
+
+
+def _is_matplotlib_figure(value: Any) -> bool:
+    """Check for a matplotlib Figure without hard-depending on matplotlib."""
+    try:
+        import matplotlib.figure
+        return isinstance(value, matplotlib.figure.Figure)
+    except ImportError:
+        return False
+
+
+def _save_figure(fig: Any, name: str, artifacts_dir: str | Path) -> str:
+    """Save a figure to `artifacts_dir/<name>.png` and return the path."""
+    artifacts_dir = Path(artifacts_dir)
+    artifacts_dir.mkdir(parents=True, exist_ok=True)
+    path = artifacts_dir / f"{name}.png"
+    fig.savefig(path)
+    return str(path)
+
+
+def split_output(
+    output: Any,
+    artifacts_dir: str | Path,
+) -> tuple[dict[str, float], list[dict[str, str]], dict[str, Any]]:
+    """
+    Classify a function's return value into (metrics, artifacts, other).
+
+    - A dict return value is walked key by key, classifying each value.
+    - A non-dict return value is treated as a single item named "result".
+
+    Classification rules, in order:
+      - bool         -> other (never treated as a number)
+      - int / float  -> metrics
+      - a known artifact type (currently: matplotlib Figure) -> saved to
+        disk under `artifacts_dir`, recorded in artifacts
+      - str / None   -> other, stored as-is
+      - anything else (unrecognized object) -> other, as a truncated repr
+    """
+    metrics: dict[str, float] = {}
+    artifacts: list[dict[str, str]] = []
+    other: dict[str, Any] = {}
+
+    items = output.items() if isinstance(output, dict) else [("result", output)]
+
+    for name, value in items:
+        if isinstance(value, bool):
+            other[name] = value
+        elif isinstance(value, (int, float)):
+            metrics[name] = value
+        elif _is_matplotlib_figure(value):
+            path = _save_figure(value, name, artifacts_dir)
+            artifacts.append({"name": name, "path": path, "type": "chart"})
+        elif isinstance(value, (str, type(None))):
+            other[name] = value
+        else:
+            other[name] = repr(value)[:OTHER_REPR_MAX_LEN]
+
+    return metrics, artifacts, other

maarg/_convenience.py

@@ -0,0 +1,104 @@
+"""
+Convenience layer for maarg's public API.
+
+maarg._query's functions are deliberately pure — they operate only on an
+already-fetched list[Run], with no storage dependency, so they stay
+trivially testable with hand-built Run lists. The wrappers here add the
+"just fetch it for me" convenience most people actually want at the top
+level, without touching that pure core: if `runs` isn't given, fetch from
+storage first, then delegate to the pure implementation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from maarg._models import Run
+from maarg._query import best_run as _pure_best_run
+from maarg._query import filter_runs as _pure_filter_runs
+from maarg._query import top_n as _pure_top_n
+from maarg._tracking import _get_default_storage
+from maarg.storage._base import StorageBackend
+
+
+def get_runs(
+    function: str | None = None,
+    experiment: str | None = None,
+    *,
+    storage: StorageBackend | None = None,
+) -> list[Run]:
+    """
+    Fetch runs from storage, optionally filtered by function and/or experiment.
+
+    Defaults to the same storage backend @track uses when none is given.
+    """
+    backend = storage if storage is not None else _get_default_storage()
+
+    if function is not None:
+        runs = backend.list_by_function(function)
+        if experiment is not None:
+            runs = [r for r in runs if r.experiment == experiment]
+        return runs
+
+    if experiment is not None:
+        return backend.list_by_experiment(experiment)
+
+    return backend.list_all()
+
+
+def top_n(
+    runs: Sequence[Run] | None = None,
+    *,
+    metric: str,
+    n: int = 5,
+    higher_is_better: bool = True,
+    only_successful: bool = True,
+    function: str | None = None,
+    experiment: str | None = None,
+    storage: StorageBackend | None = None,
+) -> list[Run]:
+    """Like the pure top_n, but fetches from storage when `runs` isn't given."""
+    if runs is None:
+        runs = get_runs(function=function, experiment=experiment, storage=storage)
+    return _pure_top_n(
+        runs, metric, n=n,
+        higher_is_better=higher_is_better,
+        only_successful=only_successful,
+    )
+
+
+def best_run(
+    runs: Sequence[Run] | None = None,
+    *,
+    metric: str,
+    higher_is_better: bool = True,
+    only_successful: bool = True,
+    function: str | None = None,
+    experiment: str | None = None,
+    storage: StorageBackend | None = None,
+) -> Run | None:
+    """Like the pure best_run, but fetches from storage when `runs` isn't given."""
+    if runs is None:
+        runs = get_runs(function=function, experiment=experiment, storage=storage)
+    return _pure_best_run(
+        runs, metric,
+        higher_is_better=higher_is_better,
+        only_successful=only_successful,
+    )
+
+
+def filter_runs(
+    runs: Sequence[Run] | None = None,
+    *,
+    only_successful: bool = True,
+    experiment: str | None = None,
+    function: str | None = None,
+    storage: StorageBackend | None = None,
+    **inputs,
+) -> list[Run]:
+    """Like the pure filter_runs, but fetches from storage when `runs` isn't given."""
+    if runs is None:
+        runs = get_runs(function=function, experiment=experiment, storage=storage)
+    return _pure_filter_runs(
+        runs, only_successful=only_successful, experiment=experiment, **inputs
+    )

maarg/_models.py

@@ -0,0 +1,35 @@
+"""
+Core data model for maarg.
+
+A Run is an immutable record of one execution of a tracked function:
+what it was called with, what it produced, and when.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Run:
+    """An immutable record of a single tracked function execution."""
+
+    function: str
+    experiment: str
+    inputs: dict[str, Any]
+    metrics: dict[str, float] = field(default_factory=dict)
+    artifacts: list[dict[str, str]] = field(default_factory=list)
+    other: dict[str, Any] = field(default_factory=dict)
+    duration_sec: float = 0.0
+
+    run_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize this run to a plain dict (e.g. for JSON/SQLite storage)."""
+        return asdict(self)

maarg/_query.py

@@ -0,0 +1,101 @@
+"""
+Query and comparison utilities for maarg.
+
+These are pure functions operating on already-fetched lists of Run
+objects — deliberately decoupled from StorageBackend, so this layer
+stays trivially testable (hand-built Run lists, no database involved)
+and independent of which backend produced the data.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from maarg._models import Run
+
+
+def _is_failed(run: Run) -> bool:
+    """A run is failed only if explicitly marked so; absence means success."""
+    return run.other.get("status") == "failed"
+
+
+def filter_runs(
+    runs: Sequence[Run],
+    *,
+    only_successful: bool = True,
+    experiment: str | None = None,
+    **inputs,
+) -> list[Run]:
+    """
+    Filter runs by success status, experiment, and/or exact input values.
+
+    `only_successful=True` (the default) excludes runs marked failed.
+    Any extra keyword arguments are treated as exact-match filters against
+    a run's `inputs` dict, e.g. filter_runs(runs, learning_rate=0.01).
+    """
+    result = []
+    for r in runs:
+        if only_successful and _is_failed(r):
+            continue
+        if experiment is not None and r.experiment != experiment:
+            continue
+        if any(r.inputs.get(k) != v for k, v in inputs.items()):
+            continue
+        result.append(r)
+    return result
+
+
+def top_n(
+    runs: Sequence[Run],
+    metric: str,
+    n: int = 5,
+    *,
+    higher_is_better: bool = True,
+    only_successful: bool = True,
+) -> list[Run]:
+    """
+    Rank the top N runs by a metric. Runs missing that metric (or where
+    it isn't numeric) are silently excluded, not treated as an error.
+    """
+    candidates = filter_runs(runs, only_successful=only_successful)
+    valid = [
+        r for r in candidates
+        if isinstance(r.metrics.get(metric), (int, float))
+    ]
+    return sorted(
+        valid,
+        key=lambda r: r.metrics[metric],
+        reverse=higher_is_better,
+    )[:n]
+
+
+def best_run(
+    runs: Sequence[Run],
+    metric: str,
+    *,
+    higher_is_better: bool = True,
+    only_successful: bool = True,
+) -> Run | None:
+    """Return the single best run for a metric, or None if none qualify."""
+    results = top_n(
+        runs, metric, n=1,
+        higher_is_better=higher_is_better,
+        only_successful=only_successful,
+    )
+    return results[0] if results else None
+
+
+def compare(runs: Sequence[Run]) -> dict:
+    """Build a side-by-side view of inputs, metrics, and status across runs."""
+    if not runs:
+        return {"run_ids": [], "inputs": {}, "metrics": {}, "status": []}
+
+    all_input_keys = {k for r in runs for k in r.inputs}
+    all_metric_keys = {k for r in runs for k in r.metrics}
+
+    return {
+        "run_ids": [r.run_id for r in runs],
+        "inputs": {k: [r.inputs.get(k) for r in runs] for k in sorted(all_input_keys)},
+        "metrics": {k: [r.metrics.get(k) for r in runs] for k in sorted(all_metric_keys)},
+        "status": ["failed" if _is_failed(r) else "success" for r in runs],
+    }

maarg/_tracking.py

@@ -0,0 +1,155 @@
+"""
+Decorator module for maarg.
+
+Provides the @track decorator to automatically inspect function parameters,
+filter inputs, time execution, split outputs into metrics and artifacts,
+and persist the resulting Run to a storage backend.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Callable, TypeVar, overload
+
+from maarg._capture import (
+    DEFAULT_MAX_COLLECTION_LENGTH,
+    DEFAULT_MAX_SCALAR_BYTES,
+    filter_inputs,
+    split_output,
+)
+from maarg._models import Run
+from maarg.storage._base import StorageBackend
+from maarg.storage._sqlite import SQLiteStorage
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_DEFAULT_STORAGE: StorageBackend | None = None
+
+
+def _get_default_storage() -> StorageBackend:
+    """Lazy singleton initializer for the default SQLite storage backend."""
+    global _DEFAULT_STORAGE
+    if _DEFAULT_STORAGE is None:
+        _DEFAULT_STORAGE = SQLiteStorage()
+    return _DEFAULT_STORAGE
+
+
+@overload
+def track(_func: F) -> F: ...
+
+
+@overload
+def track(
+    _func: None = None,
+    *,
+    experiment: str | None = None,
+    storage: StorageBackend | None = None,
+    artifacts_dir: str | Path = Path(".maarg") / "artifacts",
+    max_scalar_bytes: int = DEFAULT_MAX_SCALAR_BYTES,
+    max_collection_length: int = DEFAULT_MAX_COLLECTION_LENGTH,
+) -> Callable[[F], F]: ...
+
+
+def track(
+    _func: F | None = None,
+    *,
+    experiment: str | None = None,
+    storage: StorageBackend | None = None,
+    artifacts_dir: str | Path = Path(".maarg") / "artifacts",
+    max_scalar_bytes: int = DEFAULT_MAX_SCALAR_BYTES,
+    max_collection_length: int = DEFAULT_MAX_COLLECTION_LENGTH,
+) -> Any:
+    """
+    Decorator to track function execution, parameters, metrics, and artifacts.
+
+    Usage:
+        @track
+        def train(lr=0.01, epochs=10):
+            return {"accuracy": 0.95}
+
+        @track(experiment="resnet-50", max_scalar_bytes=2000)
+        def evaluate(model, dataset):
+            return {"loss": 0.12}
+
+    `experiment` defaults to the wrapped function's own name if not given.
+    """
+
+    def decorator(func: F) -> F:
+        # Resolved once, at decoration time — the function's name and
+        # signature never change between calls, so no need to redo this
+        # work on every invocation.
+        resolved_experiment = experiment if experiment is not None else func.__name__
+        sig = inspect.signature(func)
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # Storage IS resolved at call time (not here), so runtime
+            # changes to the default backend take effect on already-
+            # decorated functions, and per-test overrides stay isolated.
+            backend = storage if storage is not None else _get_default_storage()
+
+            # 1. Generate run_id early so artifact subdirectories are predictable
+            run_id = str(uuid.uuid4())
+            run_artifacts_dir = Path(artifacts_dir) / run_id
+
+            # 2. Bind parameter values including defaults
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+
+            # 3. Filter bound inputs
+            filtered_inputs = filter_inputs(
+                bound.arguments,
+                max_scalar_bytes=max_scalar_bytes,
+                max_collection_length=max_collection_length,
+            )
+
+            # 4. Execute wrapped function and handle exceptions
+            start_time = time.perf_counter()
+            try:
+                result = func(*args, **kwargs)
+            except Exception as exc:
+                duration_sec = time.perf_counter() - start_time
+                failed_run = Run(
+                    run_id=run_id,
+                    function=func.__name__,
+                    experiment=resolved_experiment,
+                    inputs=filtered_inputs,
+                    duration_sec=duration_sec,
+                    other={
+                        "status": "failed",
+                        "error_type": type(exc).__name__,
+                        "error_message": str(exc),
+                    },
+                )
+                backend.save(failed_run)
+                raise
+
+            duration_sec = time.perf_counter() - start_time
+
+            # 5. Split output into metrics, artifacts, and other metadata
+            metrics, artifacts, other = split_output(result, run_artifacts_dir)
+
+            # 6. Save successful Run
+            successful_run = Run(
+                run_id=run_id,
+                function=func.__name__,
+                experiment=resolved_experiment,
+                inputs=filtered_inputs,
+                metrics=metrics,
+                artifacts=artifacts,
+                other=other,
+                duration_sec=duration_sec,
+            )
+
+            backend.save(successful_run)
+            return result
+
+        return wrapper  # type: ignore[return-value]
+
+    if _func is None:
+        return decorator
+    return decorator(_func)

maarg/storage/__init__.py

@@ -0,0 +1,2 @@
+from maarg.storage._base import StorageBackend as StorageBackend
+from maarg.storage._sqlite import SQLiteStorage as SQLiteStorage

maarg/storage/_base.py

@@ -0,0 +1,52 @@
+"""
+Abstract storage interface for maarg.
+
+Any storage backend (SQLite, JSON files, a future Postgres backend, etc.)
+must implement this interface. Code elsewhere in maarg (the decorator,
+the query layer, the CLI) depends only on this contract — never on any
+specific backend's internals.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from maarg._models import Run
+
+
+class StorageBackend(ABC):
+    """Contract that every maarg storage backend must implement."""
+
+    @abstractmethod
+    def save(self, run: Run) -> None:
+        """Persist a completed Run."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_by_id(self, run_id: str) -> Run | None:
+        """Retrieve a single Run by its ID, or None if it doesn't exist."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def list_by_function(self, function: str) -> list[Run]:
+        """
+        Return all Runs recorded for a given function name,
+        newest-first by timestamp.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def list_by_experiment(self, experiment: str) -> list[Run]:
+        """
+        Return all Runs recorded under a given experiment label,
+        newest-first by timestamp.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def list_all(self) -> list[Run]:
+        """
+        Return every Run this backend has stored,
+        newest-first by timestamp.
+        """
+        raise NotImplementedError

maarg/storage/_sqlite.py

@@ -0,0 +1,160 @@
+"""
+SQLite implementation of the maarg storage backend.
+
+Stores each Run as one row in a `runs` table. Complex fields (inputs,
+metrics, artifacts, other) are stored as JSON-serialized text, since
+SQLite has no native nested-object column type.
+
+Connections are opened fresh for each method call rather than held
+open for the lifetime of this object — simplest correct behavior for
+v1, since we're not yet designing for concurrent/multi-process access.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+
+from maarg._models import Run
+from maarg.storage._base import StorageBackend
+
+DEFAULT_DB_PATH = Path(".maarg") / "runs.db"
+
+# Explicit column order, used consistently for CREATE TABLE, INSERT, and
+# SELECT — avoids relying on "SELECT *" matching table order by accident.
+_COLUMNS = (
+    "run_id", "function", "experiment", "timestamp", "duration_sec",
+    "inputs", "metrics", "artifacts", "other",
+)
+
+_CREATE_TABLE_SQL = """
+CREATE TABLE IF NOT EXISTS runs (
+    run_id TEXT PRIMARY KEY,
+    function TEXT NOT NULL,
+    experiment TEXT NOT NULL,
+    timestamp TEXT NOT NULL,
+    duration_sec REAL NOT NULL,
+    inputs TEXT NOT NULL,
+    metrics TEXT NOT NULL,
+    artifacts TEXT NOT NULL,
+    other TEXT NOT NULL
+)
+"""
+
+_SELECT_COLUMNS_SQL = ", ".join(_COLUMNS)
+
+
+class SQLiteStorage(StorageBackend):
+    """SQLite-backed implementation of StorageBackend."""
+
+    def __init__(self, db_path: str | Path = DEFAULT_DB_PATH):
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_schema()
+
+    def _connect(self) -> sqlite3.Connection:
+        return sqlite3.connect(self.db_path)
+
+    def _init_schema(self) -> None:
+        conn = self._connect()
+        try:
+            conn.execute(_CREATE_TABLE_SQL)
+            conn.commit()
+        finally:
+            conn.close()
+
+    # ── Serialization helpers ────────────────────────────────────────
+
+    @staticmethod
+    def _run_to_row(run: Run) -> tuple:
+        return (
+            run.run_id,
+            run.function,
+            run.experiment,
+            run.timestamp,
+            run.duration_sec,
+            json.dumps(run.inputs),
+            json.dumps(run.metrics),
+            json.dumps(run.artifacts),
+            json.dumps(run.other),
+        )
+
+    @staticmethod
+    def _row_to_run(row: tuple) -> Run:
+        (run_id, function, experiment, timestamp, duration_sec,
+         inputs_json, metrics_json, artifacts_json, other_json) = row
+        return Run(
+            run_id=run_id,
+            function=function,
+            experiment=experiment,
+            timestamp=timestamp,
+            duration_sec=duration_sec,
+            inputs=json.loads(inputs_json),
+            metrics=json.loads(metrics_json),
+            artifacts=json.loads(artifacts_json),
+            other=json.loads(other_json),
+        )
+
+    # ── StorageBackend implementation ────────────────────────────────
+
+    def save(self, run: Run) -> None:
+        conn = self._connect()
+        try:
+            placeholders = ", ".join("?" * len(_COLUMNS))
+            conn.execute(
+                f"INSERT INTO runs ({_SELECT_COLUMNS_SQL}) VALUES ({placeholders})",
+                self._run_to_row(run),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    def get_by_id(self, run_id: str) -> Run | None:
+        conn = self._connect()
+        try:
+            cursor = conn.execute(
+                f"SELECT {_SELECT_COLUMNS_SQL} FROM runs WHERE run_id = ?",
+                (run_id,),
+            )
+            row = cursor.fetchone()
+        finally:
+            conn.close()
+        return self._row_to_run(row) if row is not None else None
+
+    def list_by_function(self, function: str) -> list[Run]:
+        conn = self._connect()
+        try:
+            cursor = conn.execute(
+                f"SELECT {_SELECT_COLUMNS_SQL} FROM runs "
+                f"WHERE function = ? ORDER BY timestamp DESC",
+                (function,),
+            )
+            rows = cursor.fetchall()
+        finally:
+            conn.close()
+        return [self._row_to_run(row) for row in rows]
+
+    def list_by_experiment(self, experiment: str) -> list[Run]:
+        conn = self._connect()
+        try:
+            cursor = conn.execute(
+                f"SELECT {_SELECT_COLUMNS_SQL} FROM runs "
+                f"WHERE experiment = ? ORDER BY timestamp DESC",
+                (experiment,),
+            )
+            rows = cursor.fetchall()
+        finally:
+            conn.close()
+        return [self._row_to_run(row) for row in rows]
+
+    def list_all(self) -> list[Run]:
+        conn = self._connect()
+        try:
+            cursor = conn.execute(
+                f"SELECT {_SELECT_COLUMNS_SQL} FROM runs ORDER BY timestamp DESC"
+            )
+            rows = cursor.fetchall()
+        finally:
+            conn.close()
+        return [self._row_to_run(row) for row in rows]

maarg-0.2.0.dist-info/METADATA

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: maarg
+Version: 0.2.0
+Summary: Zero-instrumentation experiment tracking for Python — a decorator that auto-captures inputs and outputs, no logging calls required.
+Author: Moazzam Matin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Moazzam-Matin/maarg
+Project-URL: Repository, https://github.com/Moazzam-Matin/maarg
+Project-URL: Issues, https://github.com/Moazzam-Matin/maarg/issues
+Keywords: experiment-tracking,mlops,machine-learning,decorator,introspection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: plotting
+Requires-Dist: matplotlib; extra == "plotting"
+Dynamic: license-file
+
+[![CI](https://github.com/Moazzam-Matin/maarg/workflows/CI/badge.svg)](https://github.com/Moazzam-Matin/maarg/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![TestPyPI version](https://img.shields.io/pypi/v/maarg.svg?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://test.pypi.org/project/maarg/)
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/maarg_logo_dark.svg">
+    <img alt="maarg - Zero-Boilerplate Experiment Tracking"
+    src="docs/assets/maarg_logo.svg "width="320">
+  </picture>
+</p>
+
+<h3 align="center">Experiment tracking with zero logging code.</h3>
+
+<p align="center">
+  Put <code>@track</code> on a function. Every execution—arguments,
+  returns, metrics, execution timing, and failures—is automatically saved
+  to local storage for instant querying.
+</p>
+
+---
+
+## How It Works
+
+`maarg` sits transparently at function boundaries. It reads signature parameter defaults and runtime return payloads without requiring explicit parameter or metric logging statements inside your function logic.
+
+
+```text
+  ┌────────────────────────┐
+  │  @track decorated fn   │  ──► (Intercepts arguments & execution context)
+  └───────────┬────────────┘
+              │
+              ▼
+  ┌────────────────────────┐
+  │   Function Execution   │  ──► (Captures return dict / scalars / figures)
+  └───────────┬────────────┘
+              │
+              ▼
+  ┌────────────────────────┐
+  │   SQLite Persistence   │  ──► Saves to .maarg/runs.db (or custom backend)
+  └───────────┬────────────┘
+              │
+              ▼
+  ┌────────────────────────┐
+  │  Query & Analysis API  │  ──► maarg.get_runs() ──► top_n() / filter_runs()
+  └────────────────────────┘
+```
+
+---
+
+## Quickstart
+
+```python
+from maarg import track, get_runs, top_n
+
+@track(experiment="learning-rate-sweep")
+def fit(learning_rate, epochs=100):
+    w = 0.0
+    for _ in range(epochs):
+        grad = sum(2 * (w * x - 3 * x) * x for x in range(1, 6)) / 5
+        w -= learning_rate * grad
+    return {"error": abs(w - 3)}
+
+# Run experiments across hyperparameters
+for lr in (0.001, 0.003, 0.01):
+    fit(learning_rate=lr)
+
+# Query top 3 runs directly from default storage
+for run in top_n(get_runs(), "error", n=3, higher_is_better=False):
+    print(f"lr={run.inputs['learning_rate']:<6} epochs={run.inputs['epochs']}  error={run.metrics['error']:.2e}")
+```
+
+```text
+lr=0.01   epochs=100  error=4.86e-11
+lr=0.003  epochs=100  error=3.25e-03
+lr=0.001  epochs=100  error=3.24e-01
+```
+
+---
+
+## Project & Storage Structure
+
+`maarg` enforces a clean public package API while automatically managing runtime tracking databases and artifact outputs.
+
+### Repository Layout
+```text
+maarg/
+├── .github/
+│   └── workflows/
+│       └── ci.yaml
+├── docs/
+├── src/
+│   └── maarg/
+│       ├── storage/             # Storage backends package
+│       │   ├── __init__.py
+│       │   ├── _base.py         # StorageBackend base interface
+│       │   └── _sqlite.py       # SQLiteStorage implementation
+│       ├── __init__.py          # Public API exports (track, get_runs, top_n, etc.)
+│       ├── _capture.py          # Value parsing & scalar payload truncation
+│       ├── _convenience.py      # get_runs() wrapper & top-level defaults
+│       ├── _models.py           # Core Run and Storage schema dataclasses
+│       ├── _query.py            # Pure analytical query engine (top_n, filter_runs)
+│       └── _tracking.py         # @track decorator implementation
+├── tests/                       # Full test suite matching internal modules
+│   ├── test_capture.py
+│   ├── test_convenience.py
+│   ├── test_models.py
+│   ├── test_query.py
+│   ├── test_storage.py
+│   └── test_tracking.py
+├── LICENSE
+├── PLANNING.md
+├── pyproject.toml
+└── README.md
+```
+
+### Runtime Storage Directory (`.maarg/`)
+When you execute tracked functions, `maarg` initializes a local directory relative to your working workspace:
+
+```text
+your_project/
+├── .maarg/
+│   ├── runs.db                  # Local SQLite database containing experiment runs
+│   └── artifacts/               # Generated PNG plots & exported binary files
+│       └── <run_id>/
+│           └── figure_1.png
+├── train.py
+└── notebook.ipynb
+```
+
+---
+
+## Installation
+
+```bash
+pip install maarg
+```
+
+Supports Python 3.9+ with zero required external server dependencies. To automatically capture Matplotlib plots into `.maarg/artifacts/`, install with plotting support:
+
+```bash
+pip install "maarg[plotting]"
+```
+
+---
+
+## Querying Runs
+
+Query functions operate as pure functions on collections of `Run` objects. You can fetch runs effortlessly using the top-level `get_runs()` helper or pass custom storage backends explicitly.
+
+```python
+from maarg import get_runs, filter_runs, top_n, best_run, compare
+
+# Fetch runs from default local storage (.maarg/runs.db)
+runs = get_runs()
+
+# Optionally scope by experiment
+exp_runs = get_runs(experiment="learning-rate-sweep")
+
+# Identify top performers
+best = best_run(runs, "error", higher_is_better=False)
+top_3 = top_n(runs, "error", n=3, higher_is_better=False)
+
+# Filter by input configuration
+specific = filter_runs(runs, learning_rate=0.01)
+
+# Tabulate run comparisons
+comparison = compare(top_3)
+```
+
+By default, failed runs are filtered out of ranking queries (`only_successful=True`). Pass `only_successful=False` to include failed executions.
+
+---
+
+## What Gets Recorded
+
+| Field | Description |
+| --- | --- |
+| `run_id` | Unique UUID generated automatically per call |
+| `timestamp` | ISO 8601 UTC timestamp of call execution |
+| `function` | Name of the decorated function |
+| `experiment` | Experiment grouping label (defaults to function name) |
+| `inputs` | Captured function call parameters (including defaults) |
+| `metrics` | Numeric dictionary outputs returned by the function |
+| `artifacts` | Saved files/figures stored as `{name, path, type}` |
+| `other` | Unclassified outputs, strings, booleans, or truncated `repr()` representations |
+| `duration_sec` | Execution duration in seconds |
+
+### Value Safety & Limits
+- **Inputs:** Simple scalar values (numbers, strings, booleans) and collections with ≤ 20 elements or ≤ 1000 bytes are recorded. Large arrays, dataframes, or complex objects are automatically skipped to avoid database bloat.
+- **Outputs:** Dictionary return values with numeric scalars become `metrics`. Returned Matplotlib figures are serialized to PNG artifacts inside `.maarg/artifacts/<run_id>/`.
+- **Failures:** Exceptions are caught, recorded with `other["status"] = "failed"` along with the exception class and traceback message, and then re-raised unchanged.
+
+---
+
+## Configuration
+
+Pass optional controls directly to the `@track` decorator:
+
+```python
+from maarg import track
+from maarg.storage import SQLiteStorage
+
+@track(
+    experiment="hyperparameter-sweep",
+    storage=SQLiteStorage("results/custom_experiment.db"),
+    artifacts_dir="results/artifacts"
+)
+def train(lr, batch_size):
+    ...
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `experiment` | Function name | Label for grouping related runs |
+| `storage` | SQLite at `.maarg/runs.db` | Target storage engine instance |
+| `artifacts_dir` | `.maarg/artifacts` | Directory path for stored plots/files |
+| `max_scalar_bytes` | `1000` | Max byte size allowed for individual scalar inputs |
+| `max_collection_length` | `20` | Max items allowed in recorded input lists/dicts |
+
+---
+
+## Custom Storage Backends
+
+You can define custom storage targets by subclassing `StorageBackend` and implementing `save`, `get_by_id`, `list_by_function`, `list_by_experiment`, and `list_all`:
+
+```python
+from maarg.storage import StorageBackend
+
+class CustomStorage(StorageBackend):
+    # Implement persistence methods
+    ...
+```
+
+---
+
+## Roadmap
+
+- Command-line interface (CLI) for browsing and inspecting runs directly in the terminal
+- Event hooks triggered on run completion (e.g., Slack or webhook notifications)
+- Web dashboard extension package
+- Additional remote storage backends
+
+---
+
+## About the Name
+
+*maarg* (मार्ग) is Hindi for "path" or "route".
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

maarg-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+maarg/__init__.py,sha256=71hYo6y0Pj-SjDzd2oo1jzOoLI7rmW24L8Ysue_dUYQ,895
+maarg/_capture.py,sha256=p7IdBfMnv7sHbvHXmML0-OFtIc9vSvniRBrWKDsV5nU,4572
+maarg/_convenience.py,sha256=myUvthKTz3ik_DOs9RM8DmmkuOVrCx5QTYQWTPMMnAg,3403
+maarg/_models.py,sha256=6Q6SUUiagwGPlBBUTB0AHFtGc3H35W8w-KGl_qy152Y,1061
+maarg/_query.py,sha256=hOUo3OQ2xmjxzSirYJEmXoxXFQAbOsnQgoYnj5lcRII,3128
+maarg/_tracking.py,sha256=uVhO2xVbvA0qw8kHmmxM8wmxX0Pg-0-ixd96Z7T-qDc,5176
+maarg/storage/__init__.py,sha256=XsJr7ThbheYKnYea5BHs7YnwUl-SmnncVNQztjANgaw,130
+maarg/storage/_base.py,sha256=MsYIcnK7WHWyO1ld0THiphFCoD_RS_7K_7cMLVQIxAM,1539
+maarg/storage/_sqlite.py,sha256=wdNuAOvULRa9bJAdvGZO_inxaC2he1VJkxrxlpybq5Y,5281
+maarg-0.2.0.dist-info/licenses/LICENSE,sha256=QwTgP1Y04UJcLderk7sRfryP097IGELxbCb_28oy8hg,1091
+maarg-0.2.0.dist-info/METADATA,sha256=Td7VEgVlggV4tVCTSOGS3hCa0L8U2mcTaBKj1zLPU_k,10804
+maarg-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+maarg-0.2.0.dist-info/top_level.txt,sha256=885AA4XNSkyPoGc9r9yjpL-BZvzsBztY06NHH2EMLM4,6
+maarg-0.2.0.dist-info/RECORD,,

maarg-0.2.0.dist-info/WHEEL

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

maarg-0.2.0.dist-info/licenses/LICENSE

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

maarg-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+maarg