GSOC(L2-2): experiment client API + /experiments/log endpoint

Add vis.experiment/log_metrics/finish_experiment client methods that POST
to a new /experiments/log Tornado handler. The handler records metadata
through ExperimentStore over the server's DataStore and mirrors the blob
into in-memory env state so a later full-env save preserves it. Covers
create/update, metric append+autocreate, and finish (finished/failed).

Once an experiment is terminal, further log/metrics writes are rejected:
the store raises ExperimentFinishedError and the handler maps it to 409
Conflict, so a finished run's recorded data cannot change after the fact.
Validation returns 400 (bad action/params/status), 404 (finish without
experiment), 409 (write to terminal). Adds end-to-end + client-shape tests.

Author: Manik-Khajuria-5

openapi.yaml

@@ -52,6 +52,8 @@ tags:
     description: Query, close, and retrieve window data
   - name: Environment
     description: Manage environments (create, delete, fork, list, save, compare)
+  - name: Experiments
+    description: Track experiment metadata (hyper-parameters, metrics, tags)
   - name: Authentication
     description: Login and session management
   - name: Socket Polling
@@ -382,6 +384,92 @@ paths:
         "500":
           description: Server error. Occurs if the source environment does not exist (unhandled assertion error).
 
+  /experiments/log:
+    post:
+      operationId: logExperiment
+      tags: [Experiments]
+      summary: Record experiment metadata for an environment
+      description: >
+        Attaches experiment metadata (hyper-parameters, metric observations,
+        and tags) to an environment, stored under the environment's
+        `experiment` key and persisted through the server's data store. The
+        `action` field selects the operation:
+
+
+        - `log` (default): create or update the experiment. Repeated calls
+        merge new `params`/`tags` and overwrite `name`/`description`.
+
+
+        - `metrics`: append one or more `{name: value}` observations at an
+        optional `step`, creating the experiment if it does not exist yet.
+
+
+        - `finish`: mark the experiment terminal (`finished` or `failed`).
+
+
+        Once an experiment is terminal, `log` and `metrics` are rejected with
+        `409` so a finished run's recorded data cannot change after the fact.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                eid:
+                  type: string
+                  description: Target environment ID. Defaults to `main`.
+                action:
+                  type: string
+                  enum: [log, metrics, finish]
+                  default: log
+                  description: Operation to perform.
+                name:
+                  type: string
+                  description: Display name (action `log`). Defaults to the eid.
+                description:
+                  type: string
+                  description: Free-form description (action `log`).
+                params:
+                  type: object
+                  additionalProperties: true
+                  description: 'Hyper-parameters as `{name: value}` (action `log`).'
+                tags:
+                  type: object
+                  additionalProperties: true
+                  description: 'Free-form tags as `{name: value}` (action `log`).'
+                metrics:
+                  type: object
+                  additionalProperties:
+                    type: number
+                  description: >
+                    Metric observations as `{name: value}` (action `metrics`).
+                    Must be a non-empty object.
+                step:
+                  type: integer
+                  description: Optional training step for the metrics (action `metrics`).
+                status:
+                  type: string
+                  enum: [finished, failed]
+                  default: finished
+                  description: Terminal status (action `finish`).
+      responses:
+        "200":
+          description: The stored experiment as JSON.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Experiment"
+        "400":
+          description: >
+            Invalid request — unknown `action`, non-object `params`/`tags`/`metrics`,
+            empty `metrics`, or a non-terminal `finish` status. Also returned when
+            authentication is required but not provided.
+        "404":
+          description: A `finish` was requested for an env that has no experiment.
+        "409":
+          description: A `log`/`metrics` write was attempted on a terminal (finished/failed) experiment.
+
   /upload_env:
     post:
       operationId: uploadEnvironment
@@ -845,6 +933,66 @@ components:
 
   schemas:
 
+    Experiment:
+      type: object
+      description: Experiment metadata attached to an environment.
+      properties:
+        env_id:
+          type: string
+          description: Environment the experiment belongs to.
+        name:
+          type: string
+          description: Display name. Defaults to the env_id.
+        description:
+          type: string
+        status:
+          type: string
+          enum: [running, finished, failed]
+          description: Lifecycle state. New experiments start `running`.
+        created_at:
+          type: number
+          description: Unix timestamp when the experiment was created.
+        finished_at:
+          type: [number, "null"]
+          description: Unix timestamp when finished, or `null` while running.
+        params:
+          type: array
+          description: Hyper-parameters, keyed by name.
+          items:
+            type: object
+            properties:
+              key:
+                type: string
+              value: {}
+              dtype:
+                type: string
+                enum: [bool, int, float, str]
+                description: Inferred type, so a stored value can be cast back.
+        metrics:
+          type: array
+          description: Metric observations, appended over time.
+          items:
+            type: object
+            properties:
+              key:
+                type: string
+              value:
+                type: number
+              step:
+                type: [integer, "null"]
+              timestamp:
+                type: number
+        tags:
+          type: array
+          description: Free-form key/value labels.
+          items:
+            type: object
+            properties:
+              key:
+                type: string
+              value:
+                type: string
+
     UploadErrorResponse:
       type: object
       description: Error response returned by the /upload_env endpoint.

py/tests/test_experiment_log_handler.py

@@ -0,0 +1,211 @@
+"""End-to-end tests for the ``/experiments/log`` endpoint (Layer 2, PR 2).
+
+Drives a real :class:`~visdom.server.app.Application` over a temp env dir with
+Tornado's ``AsyncHTTPTestCase``, so the full route -> handler -> ``ExperimentStore``
+-> ``JSONStore`` path is exercised. Also unit-tests the client-side
+``Visdom.experiment``/``log_metrics``/``finish_experiment`` message shapes with
+``send=False`` (no server needed).
+"""
+
+import json
+import tempfile
+import unittest
+
+import tornado.testing
+
+from visdom import Visdom
+from visdom.data_model import JSONStore
+from visdom.experiments import ExperimentStore
+from visdom.server.app import Application
+
+
+class TestExperimentLogEndpoint(tornado.testing.AsyncHTTPTestCase):
+    def setUp(self):
+        self._tmp_dir = tempfile.mkdtemp(prefix="visdom_exp_test_")
+        super().setUp()
+
+    def get_app(self):
+        return Application(port=self.get_http_port(), env_path=self._tmp_dir)
+
+    def post_json(self, path, body):
+        return self.fetch(
+            path,
+            method="POST",
+            body=json.dumps(body),
+            headers={"Content-Type": "application/json"},
+        )
+
+    def read_experiment(self, eid):
+        """Read the persisted experiment straight from disk via a fresh store."""
+        return ExperimentStore(JSONStore(self._tmp_dir)).get_experiment(eid)
+
+    def test_log_creates_and_persists_experiment(self):
+        resp = self.post_json(
+            "/experiments/log",
+            {
+                "eid": "main",
+                "action": "log",
+                "name": "run-1",
+                "params": {"lr": 0.01, "epochs": 10},
+                "tags": {"dataset": "mnist"},
+                "description": "first run",
+            },
+        )
+        self.assertEqual(resp.code, 200)
+        body = json.loads(resp.body)
+        self.assertEqual(body["name"], "run-1")
+        self.assertEqual(body["params"][0]["key"], "lr")
+
+        exp = self.read_experiment("main")
+        self.assertIsNotNone(exp)
+        self.assertEqual(exp.get_param("epochs").value, 10)
+        self.assertEqual(exp.get_param("epochs").dtype, "int")
+        self.assertEqual(exp.tags[0].value, "mnist")
+
+    def test_action_defaults_to_log(self):
+        resp = self.post_json(
+            "/experiments/log", {"eid": "main", "params": {"lr": 0.5}}
+        )
+        self.assertEqual(resp.code, 200)
+        self.assertEqual(self.read_experiment("main").get_param("lr").value, 0.5)
+
+    def test_metrics_append_and_autocreate(self):
+        resp = self.post_json(
+            "/experiments/log",
+            {
+                "eid": "main",
+                "action": "metrics",
+                "metrics": {"acc": 0.9, "loss": 0.1},
+                "step": 3,
+            },
+        )
+        self.assertEqual(resp.code, 200)
+        exp = self.read_experiment("main")
+        self.assertEqual(len(exp.metrics), 2)
+        self.assertEqual(exp.latest_metric("acc").value, 0.9)
+        self.assertEqual(exp.latest_metric("acc").step, 3)
+
+    def test_finish_sets_terminal_status(self):
+        self.post_json("/experiments/log", {"eid": "main", "params": {"lr": 0.01}})
+        resp = self.post_json(
+            "/experiments/log",
+            {"eid": "main", "action": "finish", "status": "failed"},
+        )
+        self.assertEqual(resp.code, 200)
+        self.assertEqual(self.read_experiment("main").status, "failed")
+
+    def test_finish_without_experiment_is_404(self):
+        resp = self.post_json("/experiments/log", {"eid": "ghost", "action": "finish"})
+        self.assertEqual(resp.code, 404)
+
+    def test_finish_with_running_status_is_400(self):
+        self.post_json("/experiments/log", {"eid": "main", "params": {"lr": 0.01}})
+        resp = self.post_json(
+            "/experiments/log",
+            {"eid": "main", "action": "finish", "status": "running"},
+        )
+        self.assertEqual(resp.code, 400)
+
+    def test_log_to_finished_is_409(self):
+        self.post_json("/experiments/log", {"eid": "main", "params": {"lr": 0.01}})
+        self.post_json("/experiments/log", {"eid": "main", "action": "finish"})
+        resp = self.post_json(
+            "/experiments/log", {"eid": "main", "params": {"lr": 0.02}}
+        )
+        self.assertEqual(resp.code, 409)
+        self.assertEqual(self.read_experiment("main").get_param("lr").value, 0.01)
+
+    def test_metrics_to_finished_is_409(self):
+        self.post_json(
+            "/experiments/log",
+            {"eid": "main", "action": "metrics", "metrics": {"acc": 0.9}},
+        )
+        self.post_json("/experiments/log", {"eid": "main", "action": "finish"})
+        resp = self.post_json(
+            "/experiments/log",
+            {"eid": "main", "action": "metrics", "metrics": {"acc": 0.95}},
+        )
+        self.assertEqual(resp.code, 409)
+        self.assertEqual(len(self.read_experiment("main").metrics), 1)
+
+    def test_unknown_action_is_400(self):
+        resp = self.post_json("/experiments/log", {"eid": "main", "action": "bogus"})
+        self.assertEqual(resp.code, 400)
+
+    def test_empty_metrics_is_400(self):
+        resp = self.post_json(
+            "/experiments/log", {"eid": "main", "action": "metrics", "metrics": {}}
+        )
+        self.assertEqual(resp.code, 400)
+
+    def test_non_mapping_params_is_400(self):
+        resp = self.post_json("/experiments/log", {"eid": "main", "params": [1, 2, 3]})
+        self.assertEqual(resp.code, 400)
+
+    def test_experiment_survives_full_env_save(self):
+        """A window save must not clobber a previously logged experiment.
+
+        This guards the in-memory/on-disk sync: logging writes the blob to disk
+        and mirrors it into server state, so persisting that env (which writes
+        the in-memory state) keeps the experiment instead of dropping it.
+        """
+        self.post_json("/experiments/log", {"eid": "main", "params": {"lr": 0.01}})
+        win_resp = self.post_json(
+            "/events", {"eid": "main", "data": [{"type": "text", "content": "hi"}]}
+        )
+        self.assertEqual(win_resp.code, 200)
+        save_resp = self.post_json("/save", {"data": ["main"]})
+        self.assertEqual(save_resp.code, 200)
+
+        exp = self.read_experiment("main")
+        self.assertIsNotNone(exp, "experiment was clobbered by the env save")
+        self.assertEqual(exp.get_param("lr").value, 0.01)
+
+
+class TestClientMessageShapes(unittest.TestCase):
+    """Client methods build the right request without needing a server.
+
+    A ``send=False`` client short-circuits ``_send`` to return the
+    ``(msg, endpoint)`` it would have posted, so we can assert on it directly.
+    """
+
+    def _client(self):
+        return Visdom(send=False, env="expenv")
+
+    def test_experiment_message(self):
+        msg, endpoint = self._client().experiment(
+            name="r1", params={"lr": 0.01}, tags={"ds": "mnist"}, description="d"
+        )
+        self.assertEqual(endpoint, "experiments/log")
+        self.assertEqual(msg["action"], "log")
+        self.assertEqual(msg["eid"], "expenv")
+        self.assertEqual(msg["params"], {"lr": 0.01})
+        self.assertEqual(msg["tags"], {"ds": "mnist"})
+
+    def test_experiment_env_override(self):
+        msg, _ = self._client().experiment(params={"lr": 0.01}, env="other")
+        self.assertEqual(msg["eid"], "other")
+
+    def test_log_metrics_message(self):
+        msg, endpoint = self._client().log_metrics({"acc": 0.9}, step=5)
+        self.assertEqual(endpoint, "experiments/log")
+        self.assertEqual(msg["action"], "metrics")
+        self.assertEqual(msg["metrics"], {"acc": 0.9})
+        self.assertEqual(msg["step"], 5)
+
+    def test_finish_experiment_message(self):
+        msg, _ = self._client().finish_experiment(status="failed")
+        self.assertEqual(msg["action"], "finish")
+        self.assertEqual(msg["status"], "failed")
+
+    def test_experiment_rejects_bad_params(self):
+        with self.assertRaises(TypeError):
+            self._client().experiment(params=[1, 2, 3])
+
+    def test_log_metrics_rejects_empty(self):
+        with self.assertRaises(TypeError):
+            self._client().log_metrics({})
+
+
+if __name__ == "__main__":
+    unittest.main()