methodic-research 0.34.0__tar.gz → 0.35.0__tar.gz

{methodic_research-0.34.0/src/methodic_research.egg-info → methodic_research-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodic-research
-Version: 0.34.0
+Version: 0.35.0
 Summary: Python client for the Chronicle experiment platform
 License-Expression: Apache-2.0
 Project-URL: Documentation, https://docs.methodiclabs.ai

{methodic_research-0.34.0 → methodic_research-0.35.0}/pyproject.toml

@@ -8,7 +8,7 @@ name = "methodic-research"
 # methodic-lib-publish.yml overwrites this from versions.toml at build
 # time, so the published artifact has a single source of truth. Kept
 # here for local `pip install -e conductor/`.
-version = "0.34.0"
+version = "0.35.0"
 description = "Python client for the Chronicle experiment platform"
 requires-python = ">=3.11"
 license = "Apache-2.0"

{methodic_research-0.34.0 → methodic_research-0.35.0}/src/methodic/runs.py

@@ -47,6 +47,20 @@ class RunsAPI:
     def get_status(self, experiment_id: str, variation: int, run: int) -> Any:
         return self._t.get(f"{self._run_path(experiment_id, variation, run)}/status")
 
+    def list_outputs(
+        self, experiment_id: str, variation: int, run: int
+    ) -> list[dict[str, Any]]:
+        """List the output assets produced by a single run (newest-first)."""
+        return self._t.get(f"{self._run_path(experiment_id, variation, run)}/outputs")
+
+    def list_variation_outputs(
+        self, experiment_id: str, variation: int
+    ) -> list[dict[str, Any]]:
+        """List output assets produced across **all runs** of a variation
+        (newest-first). The resume-discovery scope: a fresh run finds the prior
+        run's checkpoint here."""
+        return self._t.get(f"{self._variation_path(experiment_id, variation)}/outputs")
+
     def start(
         self,
         experiment_id: str,
@@ -132,6 +146,52 @@ class Run:
     def get_status(self) -> Any:
         return self._api.get_status(self.experiment_id, self.variation, self.run)
 
+    # --- Outputs / resume ---
+
+    def list_outputs(self, *, across_runs: bool = False) -> list[dict[str, Any]]:
+        """List this run's output assets (newest-first). With
+        ``across_runs=True``, list outputs across **all runs** of the variation
+        — the scope to use when resuming, since the checkpoint to resume from
+        was produced by an earlier run."""
+        if across_runs:
+            return self._api.list_variation_outputs(self.experiment_id, self.variation)
+        return self._api.list_outputs(self.experiment_id, self.variation, self.run)
+
+    def latest_output(
+        self,
+        asset_type: str | None = None,
+        *,
+        across_runs: bool = True,
+        ready_only: bool = True,
+    ) -> dict[str, Any] | None:
+        """Return the most recent matching output asset, or ``None`` — the
+        resume-discovery helper.
+
+        Filters by ``asset_type`` (e.g. ``"checkpoint"``) and, by default, to
+        ``state == "ready"`` (finalized + immutable). Searches across all runs of
+        the variation by default. Pair with :meth:`download_asset`::
+
+            ckpt = run.latest_output("checkpoint")
+            if ckpt:
+                run.download_asset(ckpt["id"], Path("./resume"))
+        """
+        assets = self.list_outputs(across_runs=across_runs)
+
+        def _match(a: dict[str, Any]) -> bool:
+            if asset_type is not None and a.get("asset_type") != asset_type:
+                return False
+            if ready_only and a.get("state") != "ready":
+                return False
+            return True
+
+        matches = [a for a in assets if _match(a)]
+        if not matches:
+            return None
+        # The endpoint returns newest-first; sort defensively on created_at
+        # (RFC3339 strings sort chronologically) in case a caller reorders.
+        matches.sort(key=lambda a: a.get("created_at") or "", reverse=True)
+        return matches[0]
+
     def start(
         self,
         *,

{methodic_research-0.34.0 → methodic_research-0.35.0}/src/methodic/variations.py

@@ -147,6 +147,14 @@ class VariationsAPI:
         """
         return self._t.get(f"{self._path(experiment_id, variation)}/inputs")
 
+    def list_outputs(self, experiment_id: str, variation: int) -> list[dict[str, Any]]:
+        """List the variation's output assets across all its runs (each a dict
+        with ``id``, ``asset_type``, ``name``, ``state``, ``created_at``, …),
+        newest-first. Use to find produced checkpoints, snapshots, and reports —
+        e.g. the latest ready ``checkpoint`` to resume from.
+        """
+        return self._t.get(f"{self._path(experiment_id, variation)}/outputs")
+
     def unlink_input(
         self, experiment_id: str, variation: int, asset_id: str
     ) -> dict[str, Any]:
@@ -202,6 +210,9 @@ class _BoundVariations:
     def list_inputs(self, variation: int) -> list[dict[str, Any]]:
         return self._api.list_inputs(self._experiment_id, variation)
 
+    def list_outputs(self, variation: int) -> list[dict[str, Any]]:
+        return self._api.list_outputs(self._experiment_id, variation)
+
     def unlink_input(self, variation: int, asset_id: str) -> dict[str, Any]:
         return self._api.unlink_input(self._experiment_id, variation, asset_id)
 
@@ -304,6 +315,11 @@ class Variation:
         """List this variation's input assets (raw dicts)."""
         return self._chronicle.variations.list_inputs(self.experiment_id, self.variation)
 
+    def list_outputs(self) -> list[dict[str, Any]]:
+        """List this variation's output assets across all runs (raw dicts),
+        newest-first — produced checkpoints, snapshots, and reports."""
+        return self._chronicle.variations.list_outputs(self.experiment_id, self.variation)
+
     def unlink_input(self, asset_id: str) -> Variation:
         """Unlink an input asset from this (open) variation. Returns self for chaining."""
         self._chronicle.variations.unlink_input(self.experiment_id, self.variation, asset_id)

{methodic_research-0.34.0 → methodic_research-0.35.0/src/methodic_research.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodic-research
-Version: 0.34.0
+Version: 0.35.0
 Summary: Python client for the Chronicle experiment platform
 License-Expression: Apache-2.0
 Project-URL: Documentation, https://docs.methodiclabs.ai

{methodic_research-0.34.0 → methodic_research-0.35.0}/src/methodic_research.egg-info/SOURCES.txt

@@ -48,6 +48,7 @@ tests/test_pending.py
 tests/test_pending_reasons.py
 tests/test_reports.py
 tests/test_research_prompts.py
+tests/test_runs.py
 tests/test_search.py
 tests/test_upload_tracker.py
 tests/test_variations.py

methodic_research-0.35.0/tests/test_runs.py

@@ -0,0 +1,96 @@
+"""Tests for the runs namespace — output listing + resume discovery.
+
+HTTP is mocked via `requests_mock`; tests focus on URL paths and the
+`latest_output` filter/sort logic that backs checkpoint resume.
+"""
+
+from methodic import Chronicle
+
+BASE = "http://localhost:8080"
+EXP = "exp-abc-123"
+
+
+def _chronicle():
+    return Chronicle(server_url=BASE, api_key="sk_agent_test")
+
+
+# Deliberately NOT newest-first, to exercise the defensive sort in latest_output.
+_VARIATION_OUTPUTS = [
+    {"id": "ckpt-old", "asset_type": "checkpoint", "state": "ready", "created_at": "2026-01-01T00:00:00Z"},
+    {"id": "ckpt-new", "asset_type": "checkpoint", "state": "ready", "created_at": "2026-01-03T00:00:00Z"},
+    {"id": "ckpt-pending", "asset_type": "checkpoint", "state": "pending", "created_at": "2026-01-04T00:00:00Z"},
+    {"id": "snap", "asset_type": "snapshot", "state": "ready", "created_at": "2026-01-05T00:00:00Z"},
+]
+
+
+def test_run_list_outputs_hits_run_scoped_path(requests_mock):
+    url = f"{BASE}/v1/experiments/{EXP}/variations/1/runs/0/outputs"
+    requests_mock.get(url, json=[{"id": "a1", "asset_type": "checkpoint"}])
+
+    with _chronicle() as chronicle:
+        out = chronicle.run(EXP, 1, 0).list_outputs()
+
+    assert requests_mock.last_request.path == f"/v1/experiments/{EXP}/variations/1/runs/0/outputs"
+    assert out == [{"id": "a1", "asset_type": "checkpoint"}]
+
+
+def test_run_list_outputs_across_runs_hits_variation_path(requests_mock):
+    url = f"{BASE}/v1/experiments/{EXP}/variations/1/outputs"
+    requests_mock.get(url, json=_VARIATION_OUTPUTS)
+
+    with _chronicle() as chronicle:
+        out = chronicle.run(EXP, 1, 5).list_outputs(across_runs=True)
+
+    assert requests_mock.last_request.path == f"/v1/experiments/{EXP}/variations/1/outputs"
+    assert len(out) == 4
+
+
+def test_variation_handle_list_outputs(requests_mock):
+    url = f"{BASE}/v1/experiments/{EXP}/variations/2/outputs"
+    requests_mock.get(url, json=_VARIATION_OUTPUTS)
+
+    with _chronicle() as chronicle:
+        out = chronicle.variation(EXP, 2).list_outputs()
+
+    assert requests_mock.last_request.path == f"/v1/experiments/{EXP}/variations/2/outputs"
+    assert len(out) == 4
+
+
+def test_latest_output_picks_newest_ready_of_type(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/experiments/{EXP}/variations/1/outputs", json=_VARIATION_OUTPUTS
+    )
+    with _chronicle() as chronicle:
+        # Resuming run 6 → looks across the variation's earlier runs by default.
+        ckpt = chronicle.run(EXP, 1, 6).latest_output("checkpoint")
+
+    # Newest READY checkpoint — the pending one is skipped, the snapshot is the
+    # wrong type even though it is newer.
+    assert ckpt["id"] == "ckpt-new"
+
+
+def test_latest_output_no_type_returns_newest_ready(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/experiments/{EXP}/variations/1/outputs", json=_VARIATION_OUTPUTS
+    )
+    with _chronicle() as chronicle:
+        latest = chronicle.run(EXP, 1, 6).latest_output()
+    assert latest["id"] == "snap"
+
+
+def test_latest_output_returns_none_when_no_match(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/experiments/{EXP}/variations/1/outputs", json=_VARIATION_OUTPUTS
+    )
+    with _chronicle() as chronicle:
+        assert chronicle.run(EXP, 1, 6).latest_output("dataset") is None
+
+
+def test_latest_output_ready_only_false_includes_pending(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/experiments/{EXP}/variations/1/outputs", json=_VARIATION_OUTPUTS
+    )
+    with _chronicle() as chronicle:
+        ckpt = chronicle.run(EXP, 1, 6).latest_output("checkpoint", ready_only=False)
+    # With pending allowed, ckpt-pending (2026-01-04) is the newest checkpoint.
+    assert ckpt["id"] == "ckpt-pending"