methodic-research 0.1.2__py3-none-any.whl

methodic/experiments.py

@@ -0,0 +1,342 @@
+"""Experiments namespace and resource handle."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Iterator
+
+from methodic.reports import _BoundReports
+from methodic.transport import Transport
+from methodic.types import (
+    CreateExperimentResponse,
+    Experiment as ExperimentData,
+    ExperimentDetail,
+    ExperimentListPage,
+    ExperimentSummary,
+    GitStatus,
+    GitToken,
+    LineageResponse,
+    UpstreamRetractionsResponse,
+)
+from methodic.variations import _BoundVariations
+
+if TYPE_CHECKING:
+    from methodic.chronicle import Chronicle
+
+logger = logging.getLogger(__name__)
+
+
+class ExperimentsAPI:
+    """Experiments namespace. Stateless; every method takes the experiment id explicitly."""
+
+    def __init__(self, transport: Transport, chronicle: Chronicle) -> None:
+        self._t = transport
+        self._chronicle = chronicle
+
+    def create(
+        self,
+        *,
+        hypothesis_summary: str,
+        config_yaml: str,
+        rationale: str | None = None,
+        description: str | None = None,
+        accelerate_config_yaml: str | None = None,
+        launch_config: dict[str, Any] | None = None,
+        parent_experiment_ids: list[str] | None = None,
+        allow_retracted_parent: bool = False,
+    ) -> Experiment:
+        """Create a new experiment. Returns a handle with the create-response cached."""
+        payload: dict[str, Any] = {
+            "hypothesis_summary": hypothesis_summary,
+            "config_yaml": config_yaml,
+        }
+        if rationale is not None:
+            payload["rationale"] = rationale
+        if description is not None:
+            payload["description"] = description
+        if accelerate_config_yaml is not None:
+            payload["accelerate_config_yaml"] = accelerate_config_yaml
+        if launch_config is not None:
+            payload["launch_config"] = launch_config
+        if parent_experiment_ids is not None:
+            payload["parent_experiment_ids"] = parent_experiment_ids
+        if allow_retracted_parent:
+            payload["allow_retracted_parent"] = True
+
+        resp = self._t.post("/experiments", json=payload)
+        result = CreateExperimentResponse.from_dict(resp)
+        return Experiment(self._chronicle, result.experiment_id, _create_response=result)
+
+    def get(self, experiment_id: str) -> ExperimentDetail:
+        return ExperimentDetail.from_dict(self._t.get(f"/experiments/{experiment_id}"))
+
+    def get_rationale(self, experiment_id: str) -> str | None:
+        resp = self._t.get(f"/experiments/{experiment_id}/rationale")
+        return resp.get("rationale") if resp else None
+
+    def list(
+        self,
+        *,
+        status: str | None = None,
+        created_by: str | None = None,
+        page_size: int | None = None,
+        page_token: str | None = None,
+    ) -> ExperimentListPage:
+        """One page of experiments matching the filters. Cursor-aware (when server supports it)."""
+        params: dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status
+        if created_by is not None:
+            params["created_by"] = created_by
+        if page_size is not None:
+            params["page_size"] = page_size
+        if page_token is not None:
+            params["page_token"] = page_token
+        return ExperimentListPage.from_dict(
+            self._t.get("/experiments", params=params or None)
+        )
+
+    def iter(
+        self,
+        *,
+        status: str | None = None,
+        created_by: str | None = None,
+        page_size: int | None = None,
+    ) -> Iterator[ExperimentSummary]:
+        """Yield every experiment matching the filters, paging server-side as needed."""
+        token: str | None = None
+        while True:
+            page = self.list(
+                status=status,
+                created_by=created_by,
+                page_size=page_size,
+                page_token=token,
+            )
+            yield from page.results
+            if page.next_page_token is None:
+                return
+            token = page.next_page_token
+
+    def commit(self, experiment_id: str) -> dict[str, Any]:
+        return self._t.put(f"/experiments/{experiment_id}/commit")
+
+    def conclude(self, experiment_id: str) -> dict[str, Any]:
+        return self._t.put(f"/experiments/{experiment_id}/conclude")
+
+    def retract(
+        self,
+        experiment_id: str,
+        *,
+        reason: str,
+        document_asset_id: str | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"reason": reason}
+        if document_asset_id is not None:
+            payload["document_asset_id"] = document_asset_id
+        return self._t.put(f"/experiments/{experiment_id}/retract", json=payload)
+
+    def get_lineage(
+        self,
+        experiment_id: str,
+        *,
+        direction: str | None = None,
+        depth: int | None = None,
+    ) -> LineageResponse:
+        params: dict[str, Any] = {}
+        if direction is not None:
+            params["direction"] = direction
+        if depth is not None:
+            params["depth"] = depth
+        return LineageResponse.from_dict(
+            self._t.get(f"/experiments/{experiment_id}/lineage", params=params or None)
+        )
+
+    def git_status(self, experiment_id: str) -> GitStatus:
+        """Current git-integration state for the experiment.
+
+        Returns lightweight status info — `state` (pending/ready/failed/archived),
+        `repo_url` (when ready), `failure_reason` (when failed). Cheap to poll;
+        UI calls this every couple seconds while state is `pending`.
+        """
+        return GitStatus.from_dict(self._t.get(f"/experiments/{experiment_id}/git"))
+
+    def wait_for_repo(
+        self,
+        experiment_id: str,
+        *,
+        timeout: float = 300.0,
+        poll_interval: float = 2.0,
+    ) -> GitStatus:
+        """Poll `git_status` until the repo is `ready` or `failed`, or timeout."""
+        import time
+
+        deadline = time.monotonic() + timeout
+        while True:
+            status = self.git_status(experiment_id)
+            if status.state in ("ready", "failed", "archived"):
+                return status
+            if time.monotonic() >= deadline:
+                return status  # caller checks state
+            time.sleep(poll_interval)
+
+    def mint_git_token(self, experiment_id: str) -> GitToken:
+        """Mint a 1-hour install token scoped to this experiment's repo.
+
+        The returned token has Administration permission stripped — pushes
+        to `agent/*` branches will be rejected by branch protection. Use it
+        to clone the repo and push to `user/...` branches you create.
+
+        Raises `ServerError(503)` if the server has no GitHub App configured;
+        `ConflictError(409)` if the experiment's repo isn't `ready` yet.
+        """
+        return GitToken.from_dict(self._t.post(f"/experiments/{experiment_id}/git/token"))
+
+    def get_upstream_retractions(
+        self,
+        experiment_id: str,
+        *,
+        depth: int | None = None,
+        since: str | None = None,
+        full_chain: bool = False,
+    ) -> UpstreamRetractionsResponse:
+        params: dict[str, Any] = {}
+        if depth is not None:
+            params["depth"] = depth
+        if since is not None:
+            params["since"] = since
+        if full_chain:
+            params["full_chain"] = "true"
+        return UpstreamRetractionsResponse.from_dict(
+            self._t.get(
+                f"/experiments/{experiment_id}/upstream-retractions",
+                params=params or None,
+            )
+        )
+
+
+class Experiment:
+    """Handle for one experiment.
+
+    Mutators (`commit`, `conclude`, `retract`) return `self` so callers can
+    chain (`exp.commit().variations.create(...)`). Cached detail is dropped
+    after each mutation; the next attribute access re-fetches transparently.
+    """
+
+    def __init__(
+        self,
+        chronicle: Chronicle,
+        experiment_id: str,
+        *,
+        _detail: ExperimentDetail | None = None,
+        _create_response: CreateExperimentResponse | None = None,
+    ) -> None:
+        self._chronicle = chronicle
+        self.id = experiment_id
+        self._detail = _detail
+        self._create_response = _create_response
+        self.variations = _BoundVariations(chronicle.variations, experiment_id)
+        self.reports = _BoundReports(chronicle.reports, experiment_id)
+
+    @property
+    def detail(self) -> ExperimentDetail:
+        if self._detail is None:
+            self._detail = self._chronicle.experiments.get(self.id)
+        return self._detail
+
+    @property
+    def data(self) -> ExperimentData:
+        return self.detail.experiment
+
+    @property
+    def state(self) -> str:
+        return self.data.state
+
+    @property
+    def hypothesis_summary(self) -> str:
+        return self.data.hypothesis_summary
+
+    @property
+    def committed_at(self) -> str | None:
+        return self.data.committed_at
+
+    @property
+    def concluded_at(self) -> str | None:
+        return self.data.concluded_at
+
+    @property
+    def retracted_at(self) -> str | None:
+        return self.data.retracted_at
+
+    def get_rationale(self) -> str | None:
+        return self._chronicle.experiments.get_rationale(self.id)
+
+    def git_status(self) -> GitStatus:
+        """Lightweight current git-integration state for this experiment."""
+        return self._chronicle.experiments.git_status(self.id)
+
+    def wait_for_repo(
+        self, *, timeout: float = 300.0, poll_interval: float = 2.0
+    ) -> GitStatus:
+        """Poll until this experiment's repo is `ready` (or `failed`/timeout)."""
+        return self._chronicle.experiments.wait_for_repo(
+            self.id, timeout=timeout, poll_interval=poll_interval
+        )
+
+    def mint_git_token(self) -> GitToken:
+        """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)
+        self._detail = None
+        return self
+
+    def conclude(self) -> Experiment:
+        self._chronicle.experiments.conclude(self.id)
+        self._detail = None
+        return self
+
+    def retract(
+        self, *, reason: str, document_asset_id: str | None = None
+    ) -> Experiment:
+        self._chronicle.experiments.retract(
+            self.id, reason=reason, document_asset_id=document_asset_id
+        )
+        self._detail = None
+        return self
+
+    def get_lineage(
+        self, *, direction: str | None = None, depth: int | None = None
+    ) -> LineageResponse:
+        return self._chronicle.experiments.get_lineage(
+            self.id, direction=direction, depth=depth
+        )
+
+    def get_upstream_retractions(
+        self,
+        *,
+        depth: int | None = None,
+        since: str | None = None,
+        full_chain: bool = False,
+    ) -> UpstreamRetractionsResponse:
+        return self._chronicle.experiments.get_upstream_retractions(
+            self.id, depth=depth, since=since, full_chain=full_chain
+        )
+
+    def set_report_settings(self, settings: dict[str, Any]) -> Experiment:
+        """Replace `experiment.report_settings`. Frozen at commit (server
+        returns 409 once committed). `settings` shape matches the
+        `ReportSettings` server type:
+
+            {
+                "hypothesis": {"mode": "freeform", "freeform_prompt": "..."},
+                "takeaways":  {"mode": "template", "template_asset_id": "...", "per_variation": true},
+                "research":   {...}
+            }
+
+        Returns `self` for chaining. Drops cached `_detail` so the next
+        access re-fetches the updated row.
+        """
+        self._chronicle.reports.update_settings(self.id, settings=settings)
+        self._detail = None
+        return self

methodic/reports.py

@@ -0,0 +1,294 @@
+"""Reports namespace: render hypothesis / takeaways / research, check
+compile status, download the rendered PDF.
+
+Usage:
+
+    chronicle = Chronicle(server_url=..., api_key=...)
+    exp = chronicle.experiments.create(hypothesis_summary="...", config_yaml="...")
+
+    # Template mode (default).
+    report = exp.reports.hypothesis.render(payload={
+        "title": "Ripple study",
+        "abstract": "...",
+        "hypothesis": "...",
+        "motivation": "...",
+        "plan": ["sweep coefficient", "measure convergence"],
+    })
+
+    # The render endpoint compiles synchronously when the chronicle-tex
+    # service is configured; check the result.
+    if report.compile_status == "compiled":
+        report.download_pdf("hypothesis.pdf")
+
+    # Free-form mode (per-experiment opt-in via report_settings).
+    exp.set_report_settings(hypothesis={
+        "mode": "freeform",
+        "freeform_prompt": "Write a one-page hypothesis focusing on...",
+    })
+    report = exp.reports.hypothesis.render(tex_body=open("draft.tex").read())
+
+See `runes/chronicle/designs/reports.md` for the full design.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import time
+from typing import TYPE_CHECKING, Any
+
+from methodic.transport import Transport
+
+if TYPE_CHECKING:
+    from methodic.chronicle import Chronicle
+
+logger = logging.getLogger(__name__)
+
+# Outcomes the gates accept; everything else is in-flight or terminal-fail.
+_TERMINAL_COMPILE_STATUSES = ("compiled", "failed", "stale")
+
+
+class ReportsAPI:
+    """Reports namespace. Stateless; every method takes the experiment id
+    + report kind explicitly. Most users access via `exp.reports` instead
+    of calling these methods directly."""
+
+    def __init__(self, transport: Transport, chronicle: Chronicle) -> None:
+        self._t = transport
+        self._chronicle = chronicle
+
+    def render(
+        self,
+        experiment_id: str,
+        kind: str,
+        *,
+        payload: dict[str, Any] | None = None,
+        tex_body: str | None = None,
+        template_asset_id: str | None = None,
+    ) -> Report:
+        """Render (and compile, when chronicle-tex is configured) a report.
+
+        Pass `payload` for template mode; `tex_body` for freeform mode.
+        Mode is selected by the experiment's `report_settings.{kind}.mode`
+        — these args feed the chosen mode and are ignored otherwise.
+        """
+        body: dict[str, Any] = {}
+        if payload is not None:
+            body["payload"] = payload
+        if tex_body is not None:
+            body["tex_body"] = tex_body
+        if template_asset_id is not None:
+            body["template_asset_id"] = template_asset_id
+
+        resp = self._t.post(
+            f"/experiments/{experiment_id}/reports/{kind}/render", json=body
+        )
+        return Report(self._chronicle, asset_dict=resp)
+
+    def get(self, asset_id: str) -> Report:
+        """Fetch a report by its asset id. Returns the asset metadata
+        plus content (compile_status, log, pdf_b64 if compiled)."""
+        resp = self._t.get(f"/v1/reports/{asset_id}")
+        return Report(self._chronicle, full_dict=resp)
+
+    def update_settings(
+        self,
+        experiment_id: str,
+        *,
+        settings: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Replace `experiment.report_settings` with `settings`. Frozen at
+        commit — server returns 409 once the experiment is committed."""
+        return self._t.put(
+            f"/v1/experiments/{experiment_id}/report-settings",
+            json={"settings": settings},
+        )
+
+
+class Report:
+    """Handle for one rendered report asset.
+
+    Wraps the asset metadata plus (when fetched via `reports.get` or
+    `refresh`) the json_asset_store content with `compile_status`, `log`,
+    and `pdf_b64`. Mutators return `self` for chaining.
+    """
+
+    def __init__(
+        self,
+        chronicle: Chronicle,
+        *,
+        asset_dict: dict[str, Any] | None = None,
+        full_dict: dict[str, Any] | None = None,
+    ) -> None:
+        self._chronicle = chronicle
+        if full_dict is not None:
+            self._asset = full_dict["asset"]
+            self._content = full_dict.get("content")
+        else:
+            assert asset_dict is not None
+            self._asset = asset_dict
+            self._content = None
+
+    @property
+    def id(self) -> str:
+        return self._asset["id"]
+
+    @property
+    def asset_type(self) -> str:
+        return self._asset["asset_type"]
+
+    @property
+    def name(self) -> str:
+        return self._asset["name"]
+
+    @property
+    def asset_config(self) -> dict[str, Any]:
+        return self._asset.get("asset_config") or {}
+
+    @property
+    def compile_status(self) -> str:
+        """Current `compile_status`: pending / compiled / failed / stale.
+
+        Reads from the asset's `asset_config.compile_status` (always
+        present on render-pipeline-produced assets); for content-fetched
+        reports also cross-references the json_asset_store body.
+        """
+        if self._content is not None:
+            cs = self._content.get("compile_status")
+            if isinstance(cs, str):
+                return cs
+        return str(self.asset_config.get("compile_status", "unknown"))
+
+    @property
+    def template_asset_id(self) -> str | None:
+        v = self.asset_config.get("template_asset_id")
+        return v if isinstance(v, str) else None
+
+    @property
+    def mode(self) -> str:
+        return str(self.asset_config.get("mode", "unknown"))
+
+    @property
+    def compile_request_id(self) -> str | None:
+        v = self.asset_config.get("compile_request_id")
+        return v if isinstance(v, str) else None
+
+    @property
+    def compile_log(self) -> str | None:
+        """Tectonic stdout/stderr — only available when content has been
+        fetched (via `refresh()` or `chronicle.reports.get(...)`)."""
+        if self._content is None:
+            return None
+        v = self._content.get("compile_log")
+        return v if isinstance(v, str) else None
+
+    def refresh(self) -> Report:
+        """Re-fetch the report's asset + content. Returns `self` for
+        chaining (e.g. `report.refresh().compile_status`)."""
+        latest = self._chronicle.reports.get(self.id)
+        self._asset = latest._asset
+        self._content = latest._content
+        return self
+
+    def wait_for_compile(
+        self,
+        *,
+        timeout: float = 60.0,
+        poll_interval: float = 1.0,
+    ) -> Report:
+        """Poll `refresh` until `compile_status` is terminal (compiled,
+        failed, stale) or `timeout` elapses. Returns `self`; check
+        `.compile_status` on the result.
+
+        On most deployments the render endpoint compiles synchronously, so
+        this returns immediately on the first refresh. Useful for
+        deployments where the compile worker is configured to run
+        out-of-band (or for the M4-style stub where compile_status starts
+        at `pending` and never advances — in that case this times out)."""
+        deadline = time.monotonic() + timeout
+        while True:
+            self.refresh()
+            if self.compile_status in _TERMINAL_COMPILE_STATUSES:
+                return self
+            if time.monotonic() >= deadline:
+                logger.warning(
+                    "wait_for_compile timed out after %.1fs (status=%s)",
+                    timeout,
+                    self.compile_status,
+                )
+                return self
+            time.sleep(poll_interval)
+
+    def download_pdf(self, path: str | None = None) -> bytes:
+        """Download the compiled PDF. If `path` is given, write it there.
+        Returns the PDF bytes regardless. Raises `RuntimeError` if the
+        compile hasn't succeeded or no PDF is available.
+
+        Will fetch content if not already loaded (i.e. one extra round
+        trip when called on a Report obtained from `render` rather than
+        `get`)."""
+        if self._content is None:
+            self.refresh()
+        assert self._content is not None
+        if self.compile_status != "compiled":
+            raise RuntimeError(
+                f"cannot download PDF: compile_status is {self.compile_status!r}"
+            )
+        pdf_b64 = self._content.get("pdf_b64")
+        if not isinstance(pdf_b64, str) or not pdf_b64:
+            raise RuntimeError(
+                "report has no pdf_b64 content — was it compiled by this server?"
+            )
+        pdf_bytes = base64.b64decode(pdf_b64)
+        if path is not None:
+            with open(path, "wb") as f:
+                f.write(pdf_bytes)
+            logger.debug("Wrote %d bytes of PDF to %s", len(pdf_bytes), path)
+        return pdf_bytes
+
+    def download_source(self) -> str:
+        """Return the rendered `.tex` source. Loads content on first call."""
+        if self._content is None:
+            self.refresh()
+        assert self._content is not None
+        rendered = self._content.get("rendered_tex") or self._content.get("tex_body")
+        if not isinstance(rendered, str):
+            raise RuntimeError("report has no rendered_tex / tex_body content")
+        return rendered
+
+
+class _BoundReportKind:
+    """Per-(experiment, kind) report shim — what `exp.reports.hypothesis`
+    returns. Provides `.render(...)` without re-passing the experiment id
+    or kind every call."""
+
+    def __init__(self, api: ReportsAPI, experiment_id: str, kind: str) -> None:
+        self._api = api
+        self._experiment_id = experiment_id
+        self._kind = kind
+
+    def render(
+        self,
+        *,
+        payload: dict[str, Any] | None = None,
+        tex_body: str | None = None,
+        template_asset_id: str | None = None,
+    ) -> Report:
+        return self._api.render(
+            self._experiment_id,
+            self._kind,
+            payload=payload,
+            tex_body=tex_body,
+            template_asset_id=template_asset_id,
+        )
+
+
+class _BoundReports:
+    """Per-experiment reports shim — what `exp.reports` returns. Exposes
+    one `_BoundReportKind` per kind: `.hypothesis`, `.takeaways`,
+    `.research`."""
+
+    def __init__(self, api: ReportsAPI, experiment_id: str) -> None:
+        self.hypothesis = _BoundReportKind(api, experiment_id, "hypothesis")
+        self.takeaways = _BoundReportKind(api, experiment_id, "takeaways")
+        self.research = _BoundReportKind(api, experiment_id, "research")