methodic-research 0.36.0__tar.gz → 0.37.0__tar.gz

{methodic_research-0.36.0/src/methodic_research.egg-info → methodic_research-0.37.0}/PKG-INFO

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

{methodic_research-0.36.0 → methodic_research-0.37.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.36.0"
+version = "0.37.0"
 description = "Python client for the Chronicle experiment platform"
 requires-python = ">=3.11"
 license = "Apache-2.0"

{methodic_research-0.36.0 → methodic_research-0.37.0}/src/methodic/__init__.py

@@ -50,6 +50,7 @@ from methodic.types import (
     SearchResponse,
     SearchResult,
     SearchScope,
+    TentativeParentLink,
     UpstreamRetraction,
     UpstreamRetractionsResponse,
     Variation as VariationData,
@@ -112,6 +113,7 @@ __all__ = [
     "PublicationsAPI",
     "ServerError",
     "TagsAPI",
+    "TentativeParentLink",
     "UploadTracker",
     "UpstreamRetraction",
     "UpstreamRetractionsResponse",

{methodic_research-0.36.0 → methodic_research-0.37.0}/src/methodic/experiments.py

@@ -17,6 +17,7 @@ from methodic.types import (
     GitStatus,
     GitToken,
     LineageResponse,
+    TentativeParentLink,
     UpstreamRetractionsResponse,
     resolve_organization_id,
 )
@@ -162,7 +163,28 @@ class ExperimentsAPI:
                 return
             token = page.next_page_token
 
-    def commit(self, experiment_id: str) -> dict[str, Any]:
+    def commit(
+        self,
+        experiment_id: str,
+        *,
+        tentative_links: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Commit (lock the spec of) an experiment.
+
+        If the experiment has **tentative** parent lineage links (from being
+        created/forked off a still-``open`` parent — see
+        :meth:`tentative_links`), every one must be resolved here or commit
+        returns 409: pass ``tentative_links`` mapping each parent experiment id
+        to ``"promote"`` (make it real lineage — only valid once the parent has
+        committed) or ``"drop"`` (discard the link). Naming a parent that isn't
+        a tentative link, or omitting one that is, is rejected — there is no
+        silent default.
+        """
+        if tentative_links is not None:
+            return self._t.put(
+                f"/experiments/{experiment_id}/commit",
+                json={"tentative_links": tentative_links},
+            )
         return self._t.put(f"/experiments/{experiment_id}/commit")
 
     def conclude(
@@ -399,6 +421,33 @@ class ExperimentsAPI:
             self._t.get(f"/experiments/{experiment_id}/lineage", params=params or None)
         )
 
+    def tentative_links(self, experiment_id: str) -> list[TentativeParentLink]:
+        """The experiment's **tentative** parent lineage links.
+
+        A tentative link is created when an experiment is created/forked off a
+        parent that is still ``open`` (uncommitted). It is **excluded from
+        lineage reads** (won't show in :meth:`get` ``parent_ids`` or
+        :meth:`get_lineage`) and blocks the child's commit until resolved.
+        Returns ``[]`` for the common case (no tentative links). Resolve each
+        by :meth:`promote_lineage` (once ``promotable``) or by passing a
+        ``drop``/``promote`` disposition to :meth:`commit`.
+        """
+        resp = self._t.get(f"/experiments/{experiment_id}/tentative-links")
+        return [
+            TentativeParentLink.from_dict(t) for t in resp.get("tentative_links", [])
+        ]
+
+    def promote_lineage(self, experiment_id: str, parent_id: str) -> dict[str, Any]:
+        """Promote a tentative parent link to real (explicit) lineage.
+
+        The deliberate "yes, this fork is real lineage" action: the parent then
+        appears in :meth:`get` ``parent_ids`` and the lineage DAG. Requires the
+        parent to have **committed** (else 409); a tentative link off a still-
+        ``open`` parent is not yet promotable. Idempotent — re-promoting an
+        already-explicit link succeeds.
+        """
+        return self._t.post(f"/experiments/{experiment_id}/lineage/{parent_id}/promote")
+
     def git_status(self, experiment_id: str) -> GitStatus:
         """Current git-integration state for the experiment.
 
@@ -537,8 +586,11 @@ class Experiment:
         """Mint a 1-hour install token scoped to this experiment's repo."""
         return self._chronicle.experiments.mint_git_token(self.id)
 
-    def commit(self) -> Experiment:
-        self._chronicle.experiments.commit(self.id)
+    def commit(self, *, tentative_links: dict[str, str] | None = None) -> Experiment:
+        """Commit (lock the spec). Pass ``tentative_links`` (parent id →
+        ``"promote"``/``"drop"``) to resolve any tentative parent links, which
+        otherwise block commit. See :meth:`ExperimentsAPI.commit`."""
+        self._chronicle.experiments.commit(self.id, tentative_links=tentative_links)
         self._detail = None
         return self
 
@@ -651,6 +703,16 @@ class Experiment:
             self.id, direction=direction, depth=depth
         )
 
+    def tentative_links(self) -> list[TentativeParentLink]:
+        """This experiment's tentative parent lineage links (empty for the
+        common case). See :meth:`ExperimentsAPI.tentative_links`."""
+        return self._chronicle.experiments.tentative_links(self.id)
+
+    def promote_lineage(self, parent_id: str) -> dict[str, Any]:
+        """Promote a tentative parent link to real lineage (parent must have
+        committed). See :meth:`ExperimentsAPI.promote_lineage`."""
+        return self._chronicle.experiments.promote_lineage(self.id, parent_id)
+
     def get_upstream_retractions(
         self,
         *,

{methodic_research-0.36.0 → methodic_research-0.37.0}/src/methodic/types.py

@@ -228,17 +228,55 @@ class UpstreamRetractionsResponse:
         )
 
 
+@dataclass
+class TentativeParentLink:
+    """One **tentative** parent lineage link — recorded by creating/forking an
+    experiment whose parent was still ``open`` (uncommitted) at the time.
+
+    A tentative link is **excluded from lineage reads** (it does not appear in
+    ``ExperimentDetail.parent_ids`` or ``experiments.get_lineage``) and the
+    child **cannot commit** until every one is resolved — promoted to real
+    lineage (only once ``promotable``) or dropped. Surfaced by
+    ``CreateExperimentResponse.tentative_parents`` and
+    ``experiments.tentative_links(id)``.
+    """
+
+    parent_id: str
+    parent_state: str
+    promotable: bool
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TentativeParentLink:
+        return _from_dict(cls, data)
+
+
 @dataclass
 class CreateExperimentResponse:
-    """`POST /experiments` response: the new experiment plus the always-created variation 0 / run 0."""
+    """`POST /experiments` response: the new experiment plus the always-created variation 0 / run 0.
+
+    ``tentative_parents`` is non-empty only when the experiment was created
+    with a parent that was still ``open`` — see :class:`TentativeParentLink`.
+    Empty for the common (no-parent / committed-parent) case.
+    """
 
     experiment_id: str
     variation: int
     run: int
+    tentative_parents: list[TentativeParentLink] = dataclasses.field(
+        default_factory=list
+    )
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> CreateExperimentResponse:
-        return _from_dict(cls, data)
+        return cls(
+            experiment_id=data["experiment_id"],
+            variation=data["variation"],
+            run=data["run"],
+            tentative_parents=[
+                TentativeParentLink.from_dict(t)
+                for t in data.get("tentative_parents", [])
+            ],
+        )
 
 
 @dataclass

{methodic_research-0.36.0 → methodic_research-0.37.0/src/methodic_research.egg-info}/PKG-INFO

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

{methodic_research-0.36.0 → methodic_research-0.37.0}/tests/test_experiments.py

@@ -390,6 +390,102 @@ def test_upstream_retractions_full_chain(requests_mock):
     assert resp.retractions == []
 
 
+# --- Tentative lineage links (fork of an open parent) ---
+
+def test_create_surfaces_tentative_parents(requests_mock):
+    requests_mock.post(
+        f"{BASE}/v1/experiments",
+        json={
+            "experiment_id": EXP,
+            "variation": 0,
+            "run": 0,
+            "tentative_parents": [
+                {"parent_id": "p-open", "parent_state": "open", "promotable": False}
+            ],
+        },
+    )
+
+    exp = _chronicle().experiments.create(
+        hypothesis_summary="builds on p-open",
+        config_yaml="model: {}\n",
+        parent_experiment_ids=["p-open"],
+    )
+
+    links = exp._create_response.tentative_parents
+    assert len(links) == 1
+    assert links[0].parent_id == "p-open"
+    assert links[0].parent_state == "open"
+    assert links[0].promotable is False
+
+
+def test_tentative_links_lists_pending_links(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/experiments/{EXP}/tentative-links",
+        json={
+            "experiment_id": EXP,
+            "tentative_links": [
+                {"parent_id": "p1", "parent_state": "committed", "promotable": True}
+            ],
+        },
+    )
+
+    links = _chronicle().experiments.tentative_links(EXP)
+
+    assert requests_mock.last_request.path == f"/v1/experiments/{EXP}/tentative-links"
+    assert len(links) == 1
+    assert links[0].parent_id == "p1"
+    assert links[0].promotable is True
+
+
+def test_promote_lineage_posts_to_promote_route(requests_mock):
+    requests_mock.post(
+        f"{BASE}/v1/experiments/{EXP}/lineage/p1/promote",
+        json={"experiment_id": EXP, "parent_id": "p1", "promoted": True},
+    )
+
+    resp = _chronicle().experiments.promote_lineage(EXP, "p1")
+
+    assert requests_mock.last_request.path == f"/v1/experiments/{EXP}/lineage/p1/promote"
+    assert resp["promoted"] is True
+
+
+def test_commit_sends_tentative_link_resolutions(requests_mock):
+    requests_mock.put(f"{BASE}/v1/experiments/{EXP}/commit", json={"committed": True})
+
+    _chronicle().experiments.commit(
+        EXP, tentative_links={"p1": "promote", "p2": "drop"}
+    )
+
+    body = requests_mock.last_request.json()
+    assert body["tentative_links"] == {"p1": "promote", "p2": "drop"}
+
+
+def test_commit_without_resolutions_sends_no_body(requests_mock):
+    requests_mock.put(f"{BASE}/v1/experiments/{EXP}/commit", json={"committed": True})
+
+    _chronicle().experiments.commit(EXP)
+
+    assert requests_mock.last_request.body is None
+
+
+def test_handle_promote_lineage_proxies(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/experiments/{EXP}",
+        json=_detail_payload(),
+    )
+    requests_mock.post(
+        f"{BASE}/v1/experiments/{EXP}/lineage/p1/promote",
+        json={"experiment_id": EXP, "parent_id": "p1", "promoted": True},
+    )
+
+    exp = _chronicle().experiments.get(EXP)
+    from methodic import Experiment
+
+    handle = Experiment(_chronicle(), EXP, _detail=exp)
+    resp = handle.promote_lineage("p1")
+    assert resp["promoted"] is True
+
+
 # --- Variations sub-namespace via handle ---
 
 def test_variations_create_through_handle(requests_mock):