extract-tracker 0.2.2__tar.gz → 0.3.0__tar.gz

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: extract-tracker
-Version: 0.2.2
+Version: 0.3.0
 Summary: Local-first experiment tracking for deep learning
 Author: Phil Oh
 Keywords: experiment-tracking,machine-learning,deep-learning,sqlite,tui,mcp

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/manual/mcp.md

@@ -47,3 +47,27 @@ All tools are read-only.
 | `list_models` | Registered models with metadata |
 
 Full schemas, response shapes, and error catalog live in [`DOC.md`](../DOC.md#mcp-server).
+
+## Agent CLI surface
+
+The same read-only operations are also exposed as JSON CLI commands for agents or hosts that cannot attach the MCP server:
+
+```bash
+extract experiments list --store .extract --format json
+extract runs list --limit 20 --store .extract --format json
+extract runs get RUN_ID --store .extract --format json
+extract runs compare RUN_A RUN_B --store .extract --format json
+extract search --query resnet --tag production-candidate --store .extract --format json
+extract todos list --scope-type run --scope-id RUN_ID --store .extract --format json
+extract lineage get run RUN_ID --direction both --store .extract --format json
+extract models list --store .extract --format json
+```
+
+An installable Pi package in `pi/extract-pi-tools/` wraps these commands as native Pi tools such as `extract_list_runs`, `extract_get_run`, and `extract_compare_runs`:
+
+```bash
+pi install ./pi/extract-pi-tools      # user-scoped
+pi install -l ./pi/extract-pi-tools   # project-scoped
+```
+
+Reload or restart Pi after installation. These native tools are context-safe summaries, not raw dumps: list tools cap rows, `extract_get_run` omits full config unless specific `configKeys` are requested, and large raw JSON is written to a temp file path. For full configs, curves, or bulk aggregation, rerun the returned `meta.command` inside `ctx_execute` and print only the derived answer.

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "extract-tracker"
-version = "0.2.2"
+version = "0.3.0"
 description = "Local-first experiment tracking for deep learning"
 readme = "README.md"
 requires-python = ">=3.10"

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/python/src/extract/__main__.py

@@ -29,7 +29,9 @@ def _find_tui_binary() -> str | None:
     return None
 
 
-def _print_merge_stats(verb: str, src: object, dst: object, stats: dict[str, int]) -> None:
+def _print_merge_stats(
+    verb: str, src: object, dst: object, stats: dict[str, int]
+) -> None:
     print(f"{verb} {src} → {dst}")
     exps = stats.get("experiments", 0)
     runs = stats.get("runs", 0)
@@ -45,29 +47,39 @@ def _print_merge_stats(verb: str, src: object, dst: object, stats: dict[str, int
 
 
 def main(argv: list[str] | None = None) -> None:
-    parser = argparse.ArgumentParser(prog="extract", description="Extract experiment tracker")
+    parser = argparse.ArgumentParser(
+        prog="extract", description="Extract experiment tracker"
+    )
     sub = parser.add_subparsers(dest="command")
 
+    from extract.cli_query import add_query_parsers, run_query_command
+
+    add_query_parsers(sub)
+
     # --- tui ---
     tui_parser = sub.add_parser("tui", help="Launch the TUI explorer")
-    tui_parser.add_argument("--store", default=".extract", help="Path to .extract/ directory")
+    tui_parser.add_argument(
+        "--store", default=".extract", help="Path to .extract/ directory"
+    )
 
     # --- init ---
     init_parser = sub.add_parser(
         "init", help="Bootstrap a .extract/ store with a hierarchy"
     )
     init_parser.add_argument(
-        "path", nargs="?", default=".extract",
-        help="Path to create the store at (default: .extract)"
+        "path",
+        nargs="?",
+        default=".extract",
+        help="Path to create the store at (default: .extract)",
     )
     init_parser.add_argument(
-        "--hierarchy", default=None,
+        "--hierarchy",
+        default=None,
         help="Skip the interactive picker; use this hierarchy "
-             "(e.g. 'benchmark > model > variant')"
+        "(e.g. 'benchmark > model > variant')",
     )
     init_parser.add_argument(
-        "--no-gitignore", action="store_true",
-        help="Do not add .extract/ to .gitignore"
+        "--no-gitignore", action="store_true", help="Do not add .extract/ to .gitignore"
     )
 
     # --- sync ---
@@ -84,14 +96,24 @@ def main(argv: list[str] | None = None) -> None:
 
     export_p = sync_sub.add_parser("export", help="Archive .extract/ to tar.gz")
     export_p.add_argument("output", help="Output archive path, e.g. experiments.tar.gz")
-    export_p.add_argument("--root", default=".extract", help="Local .extract/ directory")
+    export_p.add_argument(
+        "--root", default=".extract", help="Local .extract/ directory"
+    )
 
-    import_p = sync_sub.add_parser("import", help="Import tar.gz archive into .extract/")
+    import_p = sync_sub.add_parser(
+        "import", help="Import tar.gz archive into .extract/"
+    )
     import_p.add_argument("archive", help="Archive path to import")
-    import_p.add_argument("--root", default=".extract", help="Target .extract/ directory")
+    import_p.add_argument(
+        "--root", default=".extract", help="Target .extract/ directory"
+    )
 
     args = parser.parse_args(argv)
 
+    query_exit = run_query_command(args)
+    if query_exit is not None:
+        sys.exit(query_exit)
+
     if args.command == "tui":
         binary = _find_tui_binary()
         if binary is None:
@@ -105,7 +127,10 @@ def main(argv: list[str] | None = None) -> None:
         os.execvp(binary, [binary, "--store", args.store])
 
     elif args.command == "init":
-        from extract import init  # lazy import — pulls in rich/questionary only when needed
+        from extract import (
+            init,
+        )  # lazy import — pulls in rich/questionary only when needed
+
         sys.exit(init.run(args))
 
     elif args.command == "sync":

extract_tracker-0.3.0/python/src/extract/cli_query.py

@@ -0,0 +1,223 @@
+"""JSON CLI adapter for Extract read-only query tools.
+
+This module reuses the existing MCP tool implementations so the command-line
+surface and MCP surface share one result contract while the query core is
+factored out in a later cleanup.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from extract.store import Store
+
+
+def _add_common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--store", default=".extract", help="Path to .extract/ directory"
+    )
+    parser.add_argument(
+        "--format",
+        choices=("json",),
+        default="json",
+        help="Output format (default: json)",
+    )
+
+
+def add_query_parsers(sub: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    """Register read-only query subcommands on the top-level CLI parser."""
+    experiments = sub.add_parser("experiments", help="Read experiments from a store")
+    exp_sub = experiments.add_subparsers(dest="query_action")
+    exp_list = exp_sub.add_parser("list", help="List experiments")
+    _add_common(exp_list)
+    exp_list.add_argument("--prefix", default="", help="Experiment path prefix")
+    exp_list.add_argument("--limit", type=int, default=50, help="Max rows (max 500)")
+    exp_list.add_argument("--include-archived", action="store_true")
+    exp_list.set_defaults(_extract_query="list_experiments")
+
+    runs = sub.add_parser("runs", help="Read runs from a store")
+    runs_sub = runs.add_subparsers(dest="query_action")
+    runs_list = runs_sub.add_parser("list", help="List runs")
+    _add_common(runs_list)
+    runs_list.add_argument(
+        "--experiment-id", default=None, help="Scope to one experiment id"
+    )
+    runs_list.add_argument("--limit", type=int, default=50, help="Max rows (max 500)")
+    runs_list.add_argument("--include-archived", action="store_true")
+    runs_list.set_defaults(_extract_query="list_runs")
+
+    runs_get = runs_sub.add_parser("get", help="Get full run detail")
+    _add_common(runs_get)
+    runs_get.add_argument("run_id", help="Run ULID")
+    runs_get.set_defaults(_extract_query="get_run")
+
+    runs_compare = runs_sub.add_parser("compare", help="Compare 2-10 runs")
+    _add_common(runs_compare)
+    runs_compare.add_argument("run_ids", nargs="+", help="Run ULIDs")
+    runs_compare.add_argument("--include-curves", action="store_true")
+    runs_compare.set_defaults(_extract_query="compare_runs")
+
+    search = sub.add_parser("search", help="Search runs")
+    _add_common(search)
+    search.add_argument("--query", default="", help="Case-insensitive text search")
+    search.add_argument("--tag", default=None, help="Require tag")
+    search.add_argument("--status", default=None, help="Require status")
+    search.add_argument(
+        "--experiment-prefix", default=None, help="Experiment path prefix"
+    )
+    search.add_argument(
+        "--started-after", default=None, help="ISO timestamp lower bound"
+    )
+    search.add_argument(
+        "--started-before", default=None, help="ISO timestamp upper bound"
+    )
+    search.add_argument("--limit", type=int, default=50, help="Max rows (max 500)")
+    search.add_argument("--include-archived", action="store_true")
+    search.set_defaults(_extract_query="search")
+
+    todos = sub.add_parser("todos", help="Read TODOs from a store")
+    todos_sub = todos.add_subparsers(dest="query_action")
+    todos_list = todos_sub.add_parser("list", help="List TODOs")
+    _add_common(todos_list)
+    todos_list.add_argument(
+        "--scope-type",
+        default="global",
+        choices=("global", "experiment", "run"),
+        help="TODO scope",
+    )
+    todos_list.add_argument(
+        "--scope-id", default=None, help="Required for experiment/run scope"
+    )
+    todos_list.add_argument("--include-done", action="store_true")
+    todos_list.add_argument("--limit", type=int, default=50, help="Max rows (max 500)")
+    todos_list.set_defaults(_extract_query="list_todos")
+
+    lineage = sub.add_parser("lineage", help="Read lineage graph from a store")
+    lineage_sub = lineage.add_subparsers(dest="query_action")
+    lineage_get = lineage_sub.add_parser("get", help="Walk lineage DAG")
+    _add_common(lineage_get)
+    lineage_get.add_argument("node_type", choices=("experiment", "run", "model"))
+    lineage_get.add_argument("node_id")
+    lineage_get.add_argument(
+        "--direction",
+        default="both",
+        choices=("ancestors", "descendants", "both"),
+    )
+    lineage_get.add_argument("--depth", type=int, default=2)
+    lineage_get.set_defaults(_extract_query="get_lineage")
+
+    models = sub.add_parser("models", help="Read model registry from a store")
+    models_sub = models.add_subparsers(dest="query_action")
+    models_list = models_sub.add_parser("list", help="List registered models")
+    _add_common(models_list)
+    models_list.add_argument("--name-prefix", default="", help="Model name prefix")
+    models_list.add_argument("--limit", type=int, default=50, help="Max rows (max 500)")
+    models_list.set_defaults(_extract_query="list_models")
+
+
+def _json_error(code: str, message: str) -> str:
+    return json.dumps(
+        {"error": {"code": code, "message": message}}, indent=2, sort_keys=True
+    )
+
+
+def _build_filters(args: argparse.Namespace) -> dict[str, str]:
+    filters: dict[str, str] = {}
+    for attr, key in (
+        ("tag", "tag"),
+        ("status", "status"),
+        ("experiment_prefix", "experiment_prefix"),
+        ("started_after", "started_after"),
+        ("started_before", "started_before"),
+    ):
+        value = getattr(args, attr, None)
+        if value is not None:
+            filters[key] = value
+    return filters
+
+
+def _call_query(args: argparse.Namespace) -> Any:
+    import extract.mcp as mcp_mod
+
+    action = args._extract_query
+    if action == "list_experiments":
+        return mcp_mod.list_experiments(
+            prefix=args.prefix,
+            limit=args.limit,
+            include_archived=args.include_archived,
+        )
+    if action == "list_runs":
+        return mcp_mod.list_runs(
+            experiment_id=args.experiment_id,
+            limit=args.limit,
+            include_archived=args.include_archived,
+        )
+    if action == "get_run":
+        return mcp_mod.get_run(args.run_id)
+    if action == "compare_runs":
+        return mcp_mod.compare_runs(args.run_ids, include_curves=args.include_curves)
+    if action == "search":
+        return mcp_mod.search(
+            query=args.query,
+            filters=_build_filters(args),
+            limit=args.limit,
+            include_archived=args.include_archived,
+        )
+    if action == "list_todos":
+        return mcp_mod.list_todos(
+            scope_type=args.scope_type,
+            scope_id=args.scope_id,
+            include_done=args.include_done,
+            limit=args.limit,
+        )
+    if action == "get_lineage":
+        return mcp_mod.get_lineage(
+            node_type=args.node_type,
+            node_id=args.node_id,
+            direction=args.direction,
+            depth=args.depth,
+        )
+    if action == "list_models":
+        return mcp_mod.list_models(name_prefix=args.name_prefix, limit=args.limit)
+    raise RuntimeError(f"unknown query action: {action}")
+
+
+def run_query_command(args: argparse.Namespace) -> int | None:
+    """Run a query command if args selects one; else return None."""
+    if not hasattr(args, "_extract_query"):
+        return None
+
+    store_path = Path(args.store)
+    if not store_path.exists():
+        print(
+            _json_error(
+                "store_not_found",
+                f"store not found: {store_path} — run training with extract-tracker first, or pass --store",
+            ),
+            file=sys.stdout,
+        )
+        return 2
+
+    import extract.mcp as mcp_mod
+
+    store: Store | None = None
+    try:
+        store = Store(store_path)
+        mcp_mod._store = store
+        result = _call_query(args)
+        print(json.dumps(result, indent=2, sort_keys=True))
+        return 0
+    except ValueError as exc:
+        print(_json_error("invalid_request", str(exc)), file=sys.stdout)
+        return 1
+    except Exception as exc:  # pragma: no cover - defensive CLI boundary
+        print(_json_error("internal_error", str(exc)), file=sys.stdout)
+        return 70
+    finally:
+        mcp_mod._store = None
+        if store is not None:
+            store.close()

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/python/src/extract/mcp.py

@@ -12,9 +12,9 @@ import json
 import sys
 from pathlib import Path
 
-from mcp.server.fastmcp import FastMCP
-
+import tomli
 from extract.store import Store
+from mcp.server.fastmcp import FastMCP
 
 # Module-level state. Set by main() at startup; monkey-patched by tests.
 _store: Store | None = None
@@ -31,8 +31,17 @@ def _tool(fn):
 # ----------------------------------------------------------------------
 
 _MIN_METRIC_PATTERNS = (
-    "loss", "error", "perplexity", "mse", "mae", "rmse",
-    "nll", "cer", "wer", "fid", "divergence",
+    "loss",
+    "error",
+    "perplexity",
+    "mse",
+    "mae",
+    "rmse",
+    "nll",
+    "cer",
+    "wer",
+    "fid",
+    "divergence",
 )
 
 
@@ -70,8 +79,18 @@ def _flatten_config(config: dict, prefix: str = "") -> dict:
     return result
 
 
-def _metric_direction(name: str) -> str:
-    """Return 'min' if metric name matches a minimize pattern, else 'max'."""
+def _metric_direction(
+    name: str,
+    overrides: tuple[set[str], set[str]] | None = None,
+) -> str:
+    """Return 'min' or 'max' using config overrides, then heuristics."""
+    if overrides is not None:
+        minimize, maximize = overrides
+        if name in minimize:
+            return "min"
+        if name in maximize:
+            return "max"
+
     lowered = name.lower()
     for pat in _MIN_METRIC_PATTERNS:
         if pat in lowered:
@@ -79,6 +98,35 @@ def _metric_direction(name: str) -> str:
     return "max"
 
 
+def _metric_direction_overrides(store: Store) -> tuple[set[str], set[str]]:
+    """Read [metrics] minimize/maximize overrides from config.toml."""
+    config_path = store.root / "config.toml"
+    if not config_path.exists():
+        return set(), set()
+
+    with config_path.open("rb") as f:
+        data = tomli.load(f)
+
+    metrics = data.get("metrics", {})
+    if not isinstance(metrics, dict):
+        return set(), set()
+
+    minimize = metrics.get("minimize", [])
+    maximize = metrics.get("maximize", [])
+    return (
+        (
+            {m for m in minimize if isinstance(m, str)}
+            if isinstance(minimize, list)
+            else set()
+        ),
+        (
+            {m for m in maximize if isinstance(m, str)}
+            if isinstance(maximize, list)
+            else set()
+        ),
+    )
+
+
 def _config_diffs(runs_configs: list[tuple[str, dict]]) -> dict:
     """Return {flat_key: {run_id: value}} for keys that differ across runs.
 
@@ -96,8 +144,9 @@ def _config_diffs(runs_configs: list[tuple[str, dict]]) -> dict:
     result: dict = {}
     for key in all_keys:
         values = [(rid, flat.get(key, _MISSING)) for rid, flat in flattened]
-        distinct = {id(v) if v is _MISSING else (type(v).__name__, repr(v))
-                    for _, v in values}
+        distinct = {
+            id(v) if v is _MISSING else (type(v).__name__, repr(v)) for _, v in values
+        }
         if len(distinct) > 1:
             result[key] = {rid: v for rid, v in values if v is not _MISSING}
     return result
@@ -193,14 +242,16 @@ def list_experiments(
                 f"SELECT COUNT(*) FROM runs WHERE experiment_id = ?{run_filter}",
                 (row["id"],),
             ).fetchone()
-            items.append({
-                "id": row["id"],
-                "path": row["path"],
-                "name": row["name"],
-                "node_type": row["node_type"],
-                "parent_id": row["parent_id"],
-                "n_runs": n_runs_row[0],
-            })
+            items.append(
+                {
+                    "id": row["id"],
+                    "path": row["path"],
+                    "name": row["name"],
+                    "node_type": row["node_type"],
+                    "parent_id": row["parent_id"],
+                    "n_runs": n_runs_row[0],
+                }
+            )
 
     return _listing(items, total=len(items), limit=limit, limit_clamped=clamped)
 
@@ -257,23 +308,25 @@ def list_runs(
     for row in rows:
         config_dict = json.loads(row["config"]) if row["config"] else {}
         top_keys = list(config_dict.keys())
-        items.append({
-            "id": row["id"],
-            "label": _label(row["experiment_path"], row["name"], row["id"]),
-            "experiment_id": row["experiment_id"],
-            "experiment_path": row["experiment_path"],
-            "name": row["name"],
-            "status": row["status"],
-            "started_at": row["started_at"],
-            "ended_at": row["ended_at"],
-            "tags": json.loads(row["tags"]) if row["tags"] else [],
-            "git_sha": row["git_sha"],
-            "hostname": row["hostname"],
-            "config_summary": {
-                "n_keys": len(top_keys),
-                "top_level_keys": top_keys,
-            },
-        })
+        items.append(
+            {
+                "id": row["id"],
+                "label": _label(row["experiment_path"], row["name"], row["id"]),
+                "experiment_id": row["experiment_id"],
+                "experiment_path": row["experiment_path"],
+                "name": row["name"],
+                "status": row["status"],
+                "started_at": row["started_at"],
+                "ended_at": row["ended_at"],
+                "tags": json.loads(row["tags"]) if row["tags"] else [],
+                "git_sha": row["git_sha"],
+                "hostname": row["hostname"],
+                "config_summary": {
+                    "n_keys": len(top_keys),
+                    "top_level_keys": top_keys,
+                },
+            }
+        )
 
     return _listing(items, total=len(items), limit=limit, limit_clamped=clamped)
 
@@ -308,16 +361,18 @@ def list_models(name_prefix: str = "", limit: int = 50) -> dict:
 
     items: list[dict] = []
     for row in rows:
-        items.append({
-            "id": row["id"],
-            "name": row["name"],
-            "version": row["version"],
-            "run_id": row["run_id"],
-            "framework": row["framework"],
-            "artifact_path": row["artifact_path"],
-            "metadata": json.loads(row["metadata"]) if row["metadata"] else None,
-            "created_at": row["created_at"],
-        })
+        items.append(
+            {
+                "id": row["id"],
+                "name": row["name"],
+                "version": row["version"],
+                "run_id": row["run_id"],
+                "framework": row["framework"],
+                "artifact_path": row["artifact_path"],
+                "metadata": json.loads(row["metadata"]) if row["metadata"] else None,
+                "created_at": row["created_at"],
+            }
+        )
 
     return _listing(items, total=len(items), limit=limit, limit_clamped=clamped)
 
@@ -429,14 +484,16 @@ def get_run(run_id: str) -> dict:
         ).fetchall()
         artifacts: list[dict] = []
         for a in art_rows:
-            artifacts.append({
-                "name": a["name"],
-                "kind": a["kind"],
-                "step": a["step"],
-                "rel_path": a["rel_path"],
-                "shape": json.loads(a["shape"]) if a["shape"] else None,
-                "dtype": a["dtype"],
-            })
+            artifacts.append(
+                {
+                    "name": a["name"],
+                    "kind": a["kind"],
+                    "step": a["step"],
+                    "rel_path": a["rel_path"],
+                    "shape": json.loads(a["shape"]) if a["shape"] else None,
+                    "dtype": a["dtype"],
+                }
+            )
 
         todo_rows = _store._conn.execute(
             "SELECT id, content, priority, done, created_at, completed_at "
@@ -470,7 +527,11 @@ def get_run(run_id: str) -> dict:
 
 _VALID_STATUS = {"running", "completed", "failed", "archived"}
 _VALID_FILTERS = {
-    "tag", "status", "experiment_prefix", "started_after", "started_before",
+    "tag",
+    "status",
+    "experiment_prefix",
+    "started_after",
+    "started_before",
 }
 
 
@@ -568,23 +629,25 @@ def search(
     for row in rows:
         config_dict = json.loads(row["config"]) if row["config"] else {}
         top_keys = list(config_dict.keys())
-        items.append({
-            "id": row["id"],
-            "label": _label(row["experiment_path"], row["name"], row["id"]),
-            "experiment_id": row["experiment_id"],
-            "experiment_path": row["experiment_path"],
-            "name": row["name"],
-            "status": row["status"],
-            "started_at": row["started_at"],
-            "ended_at": row["ended_at"],
-            "tags": json.loads(row["tags"]) if row["tags"] else [],
-            "git_sha": row["git_sha"],
-            "hostname": row["hostname"],
-            "config_summary": {
-                "n_keys": len(top_keys),
-                "top_level_keys": top_keys,
-            },
-        })
+        items.append(
+            {
+                "id": row["id"],
+                "label": _label(row["experiment_path"], row["name"], row["id"]),
+                "experiment_id": row["experiment_id"],
+                "experiment_path": row["experiment_path"],
+                "name": row["name"],
+                "status": row["status"],
+                "started_at": row["started_at"],
+                "ended_at": row["ended_at"],
+                "tags": json.loads(row["tags"]) if row["tags"] else [],
+                "git_sha": row["git_sha"],
+                "hostname": row["hostname"],
+                "config_summary": {
+                    "n_keys": len(top_keys),
+                    "top_level_keys": top_keys,
+                },
+            }
+        )
 
     return _listing(items, total=len(items), limit=limit, limit_clamped=clamped)
 
@@ -617,7 +680,9 @@ def compare_runs(run_ids: list[str], include_curves: bool = False) -> dict:
         }
     """
     if len(run_ids) < 2:
-        raise ValueError(f"compare_runs requires at least 2 run_ids (got {len(run_ids)})")
+        raise ValueError(
+            f"compare_runs requires at least 2 run_ids (got {len(run_ids)})"
+        )
     if len(run_ids) > 10:
         raise ValueError(
             f"compare_runs supports at most 10 runs per call (got {len(run_ids)})"
@@ -627,7 +692,9 @@ def compare_runs(run_ids: list[str], include_curves: bool = False) -> dict:
     runs_out: list[dict] = []
     configs: list[tuple[str, dict]] = []
     metric_values: dict[str, dict[str, float]] = {}  # name -> {run_id: final_val}
-    curves_out: dict[str, dict[str, list[list]]] = {}  # name -> {run_id: [[step, value], ...]}
+    curves_out: dict[str, dict[str, list[list]]] = (
+        {}
+    )  # name -> {run_id: [[step, value], ...]}
 
     with _store.lock:
         for rid in run_ids:
@@ -640,12 +707,14 @@ def compare_runs(run_ids: list[str], include_curves: bool = False) -> dict:
             if row is None:
                 raise ValueError(f"Run not found: {rid!r}")
 
-            runs_out.append({
-                "id": row["id"],
-                "label": _label(row["experiment_path"], row["name"], row["id"]),
-                "experiment_path": row["experiment_path"],
-                "status": row["status"],
-            })
+            runs_out.append(
+                {
+                    "id": row["id"],
+                    "label": _label(row["experiment_path"], row["name"], row["id"]),
+                    "experiment_path": row["experiment_path"],
+                    "status": row["status"],
+                }
+            )
             cfg = json.loads(row["config"]) if row["config"] else {}
             configs.append((rid, cfg))
 
@@ -671,13 +740,15 @@ def compare_runs(run_ids: list[str], include_curves: bool = False) -> dict:
                     )
 
     # Build the metrics dict.
+    direction_overrides = _metric_direction_overrides(_store)
     metrics_out: dict[str, dict] = {}
     for name, vals in metric_values.items():
-        direction = _metric_direction(name)
-        reverse = (direction == "max")
-        ranking = [rid for rid, _ in sorted(
-            vals.items(), key=lambda kv: kv[1], reverse=reverse
-        )]
+        direction = _metric_direction(name, direction_overrides)
+        reverse = direction == "max"
+        ranking = [
+            rid
+            for rid, _ in sorted(vals.items(), key=lambda kv: kv[1], reverse=reverse)
+        ]
         metrics_out[name] = {
             "direction": direction,
             "values": vals,
@@ -767,7 +838,9 @@ def get_lineage(
     with _store.lock:
         root_label = _lookup_node_label(_store._conn, node_type, node_id)
         if root_label is None:
-            pretty = {"run": "Run", "experiment": "Experiment", "model": "Model"}[node_type]
+            pretty = {"run": "Run", "experiment": "Experiment", "model": "Model"}[
+                node_type
+            ]
             raise ValueError(f"{pretty} not found: {node_id!r}")
 
         visited: set[tuple[str, str]] = {(node_type, node_id)}
@@ -776,7 +849,7 @@ def get_lineage(
 
         for _hop in range(depth):
             next_frontier: list[tuple[str, str]] = []
-            for (nt, nid) in frontier:
+            for nt, nid in frontier:
                 # Descendants: I am the parent.
                 if direction in ("descendants", "both"):
                     rows = _store._conn.execute(
@@ -811,14 +884,19 @@ def get_lineage(
         seen_edges: set[tuple] = set()
         unique_edges: list[dict] = []
         for e in edges_out:
-            key = (e["parent_type"], e["parent_id"],
-                   e["child_type"], e["child_id"], e["relation"])
+            key = (
+                e["parent_type"],
+                e["parent_id"],
+                e["child_type"],
+                e["child_id"],
+                e["relation"],
+            )
             if key not in seen_edges:
                 seen_edges.add(key)
                 unique_edges.append(e)
 
         nodes_out: list[dict] = []
-        for (nt, nid) in visited:
+        for nt, nid in visited:
             if (nt, nid) == (node_type, node_id):
                 continue  # root is emitted separately
             label = _lookup_node_label(_store._conn, nt, nid)

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/python/src/extract_tracker.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: extract-tracker
-Version: 0.2.2
+Version: 0.3.0
 Summary: Local-first experiment tracking for deep learning
 Author: Phil Oh
 Keywords: experiment-tracking,machine-learning,deep-learning,sqlite,tui,mcp

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/python/src/extract_tracker.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ manual/tui.md
 manual/usage.md
 python/src/extract/__init__.py
 python/src/extract/__main__.py
+python/src/extract/cli_query.py
 python/src/extract/experiment.py
 python/src/extract/init.py
 python/src/extract/mcp.py

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/rust/Cargo.lock

@@ -592,7 +592,7 @@ dependencies = [
 
 [[package]]
 name = "extract-tui"
-version = "0.2.2"
+version = "0.3.0"
 dependencies = [
  "chrono",
  "clap",

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "extract-tui"
-version = "0.2.2"
+version = "0.3.0"
 edition = "2024"
 
 [dependencies]

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/rust/src/app.rs

@@ -306,6 +306,7 @@ pub struct RunBrowserState {
     pub filtered: Vec<usize>,
     pub cursor: usize,
     pub search_query: Option<String>,
+    pub rename_buffer: Option<String>,
     pub scroll_offset: usize,
 }
 
@@ -318,6 +319,7 @@ impl RunBrowserState {
             filtered,
             cursor: 0,
             search_query: None,
+            rename_buffer: None,
             scroll_offset: 0,
         }
     }

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/rust/src/db.rs

@@ -854,6 +854,19 @@ impl Db {
         Ok(())
     }
 
+    /// Rename a run. Empty string clears the name. Opens a writable connection.
+    pub fn rename_run(db_path: &Path, id: &str, name: &str) -> Result<()> {
+        let conn = Connection::open(db_path)?;
+        conn.execute_batch("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON;")?;
+        let trimmed = name.trim();
+        let value: Option<&str> = if trimmed.is_empty() { None } else { Some(trimmed) };
+        conn.execute(
+            "UPDATE runs SET name = ? WHERE id = ?",
+            params![value, id],
+        )?;
+        Ok(())
+    }
+
     /// Set status on a single run or experiment. Opens a writable connection.
     pub fn set_status(db_path: &Path, table: &str, id: &str, status: &str) -> Result<()> {
         assert!(table == "runs" || table == "experiments");
@@ -1314,6 +1327,18 @@ mod tests {
         assert_eq!(run.status, "failed");
     }
 
+    #[test]
+    fn test_rename_run() {
+        let tdb = test_db_with_path();
+        Db::rename_run(&tdb.path, "r1", "renamed").unwrap();
+        let run = tdb.db.get_run("r1").unwrap().unwrap();
+        assert_eq!(run.name.as_deref(), Some("renamed"));
+
+        Db::rename_run(&tdb.path, "r1", "   ").unwrap();
+        let run = tdb.db.get_run("r1").unwrap().unwrap();
+        assert!(run.name.is_none());
+    }
+
     #[test]
     fn test_archive_experiment() {
         let tdb = test_db_with_path();

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/rust/src/ui/layout.rs

@@ -82,7 +82,14 @@ impl AppLayout {
         // focused panel's input handler see every keystroke unmodified.
         let in_text_input = state.tag_picker.is_some()
             || state.note_input.is_some()
-            || state.todo_input.is_some();
+            || state.todo_input.is_some()
+            || state
+                .run_picker
+                .as_ref()
+                .is_some_and(|picker| picker.search_query.is_some())
+            || state.run_browser.as_ref().is_some_and(|browser| {
+                browser.search_query.is_some() || browser.rename_buffer.is_some()
+            });
 
         if !in_text_input {
             // Global keys: gg/G, ?, work in all views

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/rust/src/ui/popup.rs

@@ -1,4 +1,5 @@
-use crossterm::event::{KeyCode, KeyEvent};
+use chrono::{DateTime, Local};
+use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
 use ratatui::layout::Rect;
 use ratatui::style::{Modifier, Style};
 use ratatui::symbols::border;
@@ -216,6 +217,70 @@ impl PopupRenderer {
         };
 
         let is_searching = browser.search_query.is_some();
+        let is_renaming = browser.rename_buffer.is_some();
+
+        // Rename mode
+        if is_renaming {
+            match key.code {
+                KeyCode::Esc => {
+                    browser.rename_buffer = None;
+                    return false;
+                }
+                KeyCode::Enter => {
+                    if let Some(&run_idx) = browser.filtered.get(browser.cursor) {
+                        if let Some(run) = browser.runs.get(run_idx) {
+                            let run_id = run.id.clone();
+                            let new_name = browser.rename_buffer.take().unwrap_or_default();
+                            let db_path = state.store_root.join("extract.db");
+                            match crate::db::Db::rename_run(&db_path, &run_id, &new_name) {
+                                Ok(()) => {
+                                    let trimmed = new_name.trim();
+                                    let value = if trimmed.is_empty() {
+                                        None
+                                    } else {
+                                        Some(trimmed.to_string())
+                                    };
+                                    if let Some(run) = browser.runs.get_mut(run_idx) {
+                                        run.name = value.clone();
+                                    }
+                                    if let Some(state_idx) = state.runs.iter().position(|r| r.id == run_id) {
+                                        state.runs[state_idx].name = value;
+                                    }
+                                    let _ = state.refresh_selection_summary();
+                                    state.notify(crate::app::NotifyLevel::Success, "Run renamed");
+                                }
+                                Err(err) => {
+                                    state.notify(
+                                        crate::app::NotifyLevel::Error,
+                                        format!("Rename failed: {err}"),
+                                    );
+                                }
+                            }
+                        } else {
+                            browser.rename_buffer = None;
+                        }
+                    } else {
+                        browser.rename_buffer = None;
+                    }
+                    return false;
+                }
+                KeyCode::Backspace => {
+                    if let Some(ref mut name) = browser.rename_buffer {
+                        name.pop();
+                    }
+                    return false;
+                }
+                KeyCode::Char(c) => {
+                    if accepts_text_modifiers(key) {
+                        if let Some(ref mut name) = browser.rename_buffer {
+                            name.push(c);
+                        }
+                    }
+                    return false;
+                }
+                _ => return false,
+            }
+        }
 
         // Search mode
         if is_searching {
@@ -290,6 +355,15 @@ impl PopupRenderer {
             return false;
         }
 
+        if is_rename_key(key) {
+            if let Some(&run_idx) = browser.filtered.get(browser.cursor) {
+                if let Some(run) = browser.runs.get(run_idx) {
+                    browser.rename_buffer = Some(run.name.clone().unwrap_or_default());
+                }
+            }
+            return false;
+        }
+
         if keys::matches(key, keys::SELECT) {
             if let Some(&filtered_idx) = browser.filtered.get(browser.cursor) {
                 if let Some(run) = browser.runs.get(filtered_idx) {
@@ -499,6 +573,7 @@ impl PopupRenderer {
         browser: &mut RunBrowserState,
     ) {
         let is_searching = browser.search_query.is_some();
+        let is_renaming = browser.rename_buffer.is_some();
         let width = POPUP_WIDTH.min(area.width.saturating_sub(4));
         let height = POPUP_HEIGHT.min(area.height.saturating_sub(4));
         let popup_area = centered_rect(width, height, area);
@@ -508,12 +583,16 @@ impl PopupRenderer {
         let title = format!(" {} — runs ", browser.experiment_name);
         let footer_spans = if is_searching {
             search_footer_spans(&self.theme)
+        } else if is_renaming {
+            rename_footer_spans(&self.theme)
         } else {
             vec![
                 Span::styled("j/k", Style::default().fg(self.theme.accent)),
                 Span::styled(" nav  ", Style::default().fg(self.theme.accent_dim)),
                 Span::styled("Enter", Style::default().fg(self.theme.accent)),
                 Span::styled(" select  ", Style::default().fg(self.theme.accent_dim)),
+                Span::styled("R", Style::default().fg(self.theme.accent)),
+                Span::styled(" rename  ", Style::default().fg(self.theme.accent_dim)),
                 Span::styled("/", Style::default().fg(self.theme.accent)),
                 Span::styled(" search  ", Style::default().fg(self.theme.accent_dim)),
                 Span::styled("x", Style::default().fg(self.theme.accent)),
@@ -570,11 +649,19 @@ impl PopupRenderer {
                 Style::default()
             };
 
-            let label = run
-                .name
-                .as_deref()
-                .map(|n| format!("{} ", n))
-                .unwrap_or_default();
+            let label = if is_cursor {
+                browser
+                    .rename_buffer
+                    .as_ref()
+                    .map(|name| format!("{name}_ "))
+                    .or_else(|| run.name.as_deref().map(|n| format!("{} ", n)))
+                    .unwrap_or_default()
+            } else {
+                run.name
+                    .as_deref()
+                    .map(|n| format!("{} ", n))
+                    .unwrap_or_default()
+            };
             let date = format_date(run);
             let config_summary = differing_config_summary(run, &diff_keys);
 
@@ -624,14 +711,24 @@ fn compute_scroll(cursor: usize, current_offset: usize, list_height: usize) -> u
     }
 }
 
-/// Format a run's date for display (first 19 chars of ended_at or started_at).
+/// Format a run timestamp for display in the user's local timezone.
 fn format_date(run: &Run) -> String {
-    run.ended_at
-        .as_deref()
-        .unwrap_or(&run.started_at)
-        .chars()
-        .take(19)
-        .collect()
+    let raw = run.ended_at.as_deref().unwrap_or(&run.started_at);
+    format_local_timestamp(raw).unwrap_or_else(|| raw.chars().take(19).collect())
+}
+
+fn format_local_timestamp(raw: &str) -> Option<String> {
+    DateTime::parse_from_rfc3339(raw)
+        .ok()
+        .map(|dt| dt.with_timezone(&Local).format("%Y-%m-%d %H:%M:%S").to_string())
+}
+
+fn is_rename_key(key: &KeyEvent) -> bool {
+    matches!(key.code, KeyCode::Char('R')) && accepts_text_modifiers(key)
+}
+
+fn accepts_text_modifiers(key: &KeyEvent) -> bool {
+    key.modifiers == KeyModifiers::NONE || key.modifiers == KeyModifiers::SHIFT
 }
 
 /// Build search input line with blinking cursor.
@@ -655,6 +752,17 @@ fn search_footer_spans(theme: &Theme) -> Vec<Span<'static>> {
     ]
 }
 
+fn rename_footer_spans(theme: &Theme) -> Vec<Span<'static>> {
+    vec![
+        Span::styled("Type", Style::default().fg(theme.accent)),
+        Span::styled(" name  ", Style::default().fg(theme.accent_dim)),
+        Span::styled("Enter", Style::default().fg(theme.accent)),
+        Span::styled(" save  ", Style::default().fg(theme.accent_dim)),
+        Span::styled("Esc", Style::default().fg(theme.accent)),
+        Span::styled(" cancel", Style::default().fg(theme.accent_dim)),
+    ]
+}
+
 /// Compare configs across all runs and return only the keys whose values differ.
 fn differing_config_keys(runs: &[Run]) -> Vec<String> {
     use std::collections::HashMap;

{extract_tracker-0.2.2 → extract_tracker-0.3.0}/rust/src/ui/summary.rs

@@ -1,3 +1,4 @@
+use chrono::{DateTime, Local};
 use ratatui::buffer::Buffer;
 use ratatui::layout::Rect;
 use ratatui::style::{Color, Modifier, Style};
@@ -219,7 +220,7 @@ impl SummaryRenderer {
             }
 
             let run = &data.runs[i];
-            let date = run.started_at.get(..10).unwrap_or(&run.started_at);
+            let date = format_run_time(run);
             let label = run.name.clone().unwrap_or_else(|| {
                 let id = &run.id;
                 if id.len() > 8 { id[id.len() - 8..].to_string() } else { id.clone() }
@@ -632,6 +633,13 @@ impl SummaryRenderer {
     }
 }
 
+fn format_run_time(run: &Run) -> String {
+    DateTime::parse_from_rfc3339(&run.started_at)
+        .ok()
+        .map(|dt| dt.with_timezone(&Local).format("%Y-%m-%d %H:%M:%S").to_string())
+        .unwrap_or_else(|| run.started_at.chars().take(19).collect())
+}
+
 /// Catmull-Rom spline interpolation.
 /// Generates `num_points` evenly spaced points along the spline that passes
 /// through all input points. Requires at least 3 input points.