methodic-research 0.40.0__tar.gz → 0.41.0__tar.gz

{methodic_research-0.40.0/src/methodic_research.egg-info → methodic_research-0.41.0}/PKG-INFO

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

{methodic_research-0.40.0 → methodic_research-0.41.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.40.0"
+version = "0.41.0"
 description = "Python client for the Chronicle experiment platform"
 requires-python = ">=3.11"
 license = "Apache-2.0"

{methodic_research-0.40.0 → methodic_research-0.41.0}/src/methodic/experiments.py

@@ -268,6 +268,146 @@ class ExperimentsAPI:
             payload["source_asset_id"] = source_asset_id
         return self._t.post(f"/experiments/{experiment_id}/findings", json=payload)
 
+    def record_lesson(
+        self,
+        experiment_id: str,
+        *,
+        title: str,
+        body_md: str,
+        origin: str,
+        category: str | None = None,
+        variation: int | None = None,
+        evidence: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Record a research lesson — a durable corrected assumption — onto
+        the experiment (designs/research-lessons.md).
+
+        Record one when you have repeatedly made the same bad assumption,
+        when the researcher explicitly or implicitly corrects a wrong
+        premise, or on request. List existing lessons first and refine
+        (:meth:`update_lesson`) instead of duplicating. Lessons surface on
+        the experiment's Lessons tab, are injected into every future
+        agent's context (this experiment + descendants), and emit a
+        ``lesson.recorded`` feed event. Requires ``Write`` on the
+        experiment. (MCP-native agents have the same surface as the
+        ``chronicle.record_lesson`` tool.)
+
+        Args:
+            experiment_id: Target experiment.
+            title: One line, imperative where possible.
+            body_md: The lesson (Markdown, self-contained): wrong
+                assumption, correction, evidence, what to do instead.
+            origin: ``"repeated_error"`` | ``"researcher_correction"`` |
+                ``"self_identified"`` | ``"manual"``.
+            category: ``"assumption"`` (default) | ``"methodology"`` |
+                ``"environment"`` | ``"data"`` | ``"other"``.
+            variation: The variation the lesson arose from, when
+                variation-specific.
+            evidence: Pointers only (session shard / run / report ids) —
+                never content.
+
+        Returns the recorded lesson.
+        """
+        payload: dict[str, Any] = {
+            "title": title,
+            "body_md": body_md,
+            "origin": origin,
+        }
+        if category is not None:
+            payload["category"] = category
+        if variation is not None:
+            payload["variation"] = variation
+        if evidence is not None:
+            payload["evidence"] = evidence
+        return self._t.post(f"/experiments/{experiment_id}/lessons", json=payload)
+
+    def list_lessons(
+        self,
+        experiment_id: str,
+        *,
+        status: str | None = None,
+        category: str | None = None,
+        include_ancestors: bool = True,
+    ) -> list[dict[str, Any]]:
+        """List the experiment's research lessons — the corrected
+        assumptions every conclusion and proposal must be checked against.
+
+        Defaults to active lessons **including** those inherited from
+        ancestor experiments (each stamped ``inherited_from``). Consult
+        this before writing conclusions or proposing variations.
+        Requires ``Read`` on the experiment.
+
+        Args:
+            experiment_id: Target experiment.
+            status: ``"active"`` (default) | ``"retired"`` | ``"all"`` —
+                own-lesson filter; inherited lessons are always
+                active-only.
+            category: Optional category filter.
+            include_ancestors: Include ancestor experiments' active
+                lessons (default True).
+
+        Returns the lesson list.
+        """
+        params: dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status
+        if category is not None:
+            params["category"] = category
+        if include_ancestors:
+            params["include_ancestors"] = "true"
+        resp = self._t.get(
+            f"/experiments/{experiment_id}/lessons", params=params or None
+        )
+        return resp.get("lessons", [])
+
+    def update_lesson(
+        self,
+        experiment_id: str,
+        lesson_id: str,
+        *,
+        title: str | None = None,
+        body_md: str | None = None,
+        category: str | None = None,
+        variation: int | None = None,
+        evidence: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Refine an existing lesson in place (the dedup contract) — absent
+        fields are unchanged; retired lessons are immutable (409).
+        Requires ``Write`` on the experiment. Returns the updated lesson."""
+        payload: dict[str, Any] = {}
+        if title is not None:
+            payload["title"] = title
+        if body_md is not None:
+            payload["body_md"] = body_md
+        if category is not None:
+            payload["category"] = category
+        if variation is not None:
+            payload["variation"] = variation
+        if evidence is not None:
+            payload["evidence"] = evidence
+        return self._t.put(
+            f"/experiments/{experiment_id}/lessons/{lesson_id}", json=payload
+        )
+
+    def retire_lesson(
+        self,
+        experiment_id: str,
+        lesson_id: str,
+        *,
+        reason: str,
+        superseded_by: str | None = None,
+    ) -> dict[str, Any]:
+        """Retire a lesson that turned out wrong or obsolete (``active`` →
+        ``retired``; retire-don't-delete). Only lessons owned by this
+        experiment — inherited ones are retired at their home experiment.
+        Requires ``Write`` on the experiment. Returns the retired lesson."""
+        payload: dict[str, Any] = {"reason": reason}
+        if superseded_by is not None:
+            payload["superseded_by"] = superseded_by
+        return self._t.put(
+            f"/experiments/{experiment_id}/lessons/{lesson_id}/retire", json=payload
+        )
+
     def distill(
         self,
         experiment_id: str,
@@ -674,6 +814,16 @@ class Experiment:
         self._detail = None
         return summary_doc
 
+    def record_lesson(self, **kwargs: Any) -> dict[str, Any]:
+        """Record a research lesson on this experiment. Proxies to
+        :meth:`ExperimentsAPI.record_lesson`."""
+        return self._chronicle.experiments.record_lesson(self.id, **kwargs)
+
+    def list_lessons(self, **kwargs: Any) -> list[dict[str, Any]]:
+        """List this experiment's research lessons (own + inherited by
+        default). Proxies to :meth:`ExperimentsAPI.list_lessons`."""
+        return self._chronicle.experiments.list_lessons(self.id, **kwargs)
+
     def distill(
         self,
         *,

{methodic_research-0.40.0 → methodic_research-0.41.0/src/methodic_research.egg-info}/PKG-INFO

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

{methodic_research-0.40.0 → methodic_research-0.41.0}/tests/test_experiments.py

@@ -937,3 +937,68 @@ def test_create_passes_title(requests_mock):
     body = requests_mock.last_request.json()
     assert body["title"] == "Display title"
     assert body["hypothesis_summary"] == "h"
+
+
+# --- Research lessons (designs/research-lessons.md) ---
+
+def test_record_lesson_posts_body(requests_mock):
+    requests_mock.post(
+        f"{BASE}/v1/experiments/{EXP}/lessons",
+        json={"id": "les-1", "title": "check the mask", "status": "active"},
+    )
+
+    lesson = _chronicle().experiments.record_lesson(
+        EXP,
+        title="check the mask",
+        body_md="The boundary mask is inverted in this dataset.",
+        origin="researcher_correction",
+        category="data",
+        variation=4,
+        evidence={"run": 3},
+    )
+
+    assert lesson["id"] == "les-1"
+    sent = requests_mock.last_request.json()
+    assert sent == {
+        "title": "check the mask",
+        "body_md": "The boundary mask is inverted in this dataset.",
+        "origin": "researcher_correction",
+        "category": "data",
+        "variation": 4,
+        "evidence": {"run": 3},
+    }
+
+
+def test_list_lessons_defaults_include_ancestors(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/experiments/{EXP}/lessons",
+        json={"lessons": [{"id": "les-1"}, {"id": "les-2", "inherited_from": "parent-1"}]},
+    )
+
+    lessons = _chronicle().experiments.list_lessons(EXP)
+
+    assert [l["id"] for l in lessons] == ["les-1", "les-2"]
+    assert requests_mock.last_request.qs.get("include_ancestors") == ["true"]
+
+
+def test_update_and_retire_lesson_put_bodies(requests_mock):
+    requests_mock.put(
+        f"{BASE}/v1/experiments/{EXP}/lessons/les-1",
+        json={"id": "les-1", "body_md": "sharper"},
+    )
+    updated = _chronicle().experiments.update_lesson(EXP, "les-1", body_md="sharper")
+    assert updated["body_md"] == "sharper"
+    assert requests_mock.last_request.json() == {"body_md": "sharper"}
+
+    requests_mock.put(
+        f"{BASE}/v1/experiments/{EXP}/lessons/les-1/retire",
+        json={"id": "les-1", "status": "retired"},
+    )
+    retired = _chronicle().experiments.retire_lesson(
+        EXP, "les-1", reason="fixed upstream", superseded_by="les-2"
+    )
+    assert retired["status"] == "retired"
+    assert requests_mock.last_request.json() == {
+        "reason": "fixed upstream",
+        "superseded_by": "les-2",
+    }