openrunner-sdk 0.2.0__tar.gz → 0.3.0__tar.gz

{openrunner_sdk-0.2.0 → openrunner_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openrunner-sdk
-Version: 0.2.0
+Version: 0.3.0
 Summary: OpenRunner SDK - W&B-compatible ML experiment tracking client
 Project-URL: Homepage, https://github.com/jqueguiner/openrunner
 Project-URL: Repository, https://github.com/jqueguiner/openrunner
@@ -238,6 +238,175 @@ print(run.config)      # Config object
 print(run.summary)     # Summary object
 ```
 
+### HTML
+
+```python
+# Log raw HTML for rich reports, custom visualizations, or formatted output
+openrunner.log({"report": openrunner.Html("<h1>Training Report</h1><p>Loss converged at epoch 42.</p>")})
+```
+
+### Histograms
+
+```python
+import numpy as np
+
+weights = np.random.randn(10000)
+openrunner.log({"weight_dist": openrunner.Histogram(weights, num_bins=50)})
+```
+
+### Plotly Charts
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(data=go.Scatter(x=[1, 2, 3], y=[4, 5, 6]))
+openrunner.log({"interactive_plot": openrunner.Plotly(fig)})
+```
+
+### Point Clouds
+
+```python
+import numpy as np
+
+points = np.random.randn(1000, 3)
+colors = np.random.randint(0, 255, (1000, 3), dtype=np.uint8)
+openrunner.log({"lidar": openrunner.PointCloud3D(points, colors=colors)})
+```
+
+### Bounding Boxes
+
+```python
+img = openrunner.Image("photo.jpg")
+boxes = [{"position": {"minX": 10, "minY": 20, "maxX": 100, "maxY": 150}, "class_id": 0}]
+openrunner.log({"detections": openrunner.BoundingBoxes2D(img, boxes, class_labels={0: "cat"})})
+```
+
+### Audio
+
+```python
+import numpy as np
+
+# From numpy array (mono, float32, -1 to 1)
+audio = openrunner.Audio(np.random.randn(44100).astype(np.float32), sample_rate=44100)
+openrunner.log({"audio_sample": audio})
+```
+
+### Video
+
+```python
+# From file path
+openrunner.log({"demo": openrunner.Video("output.mp4", caption="training demo")})
+```
+
+### Matplotlib Figures
+
+```python
+import matplotlib.pyplot as plt
+
+plt.figure()
+plt.plot([1, 2, 3], [4, 5, 6])
+openrunner.log({"chart": openrunner.MatplotlibFigure()})  # captures current figure
+plt.close()
+```
+
+## LLM Tracing
+
+Trace LLM API calls for debugging and cost tracking.
+
+```python
+import openrunner
+
+openrunner.init(project="llm-app")
+
+# Auto-trace OpenAI calls
+openrunner.trace.patch_openai()
+
+# Or manually trace any function
+@openrunner.trace
+def generate(prompt):
+    return client.chat.completions.create(
+        model="gpt-4", messages=[{"role": "user", "content": prompt}]
+    )
+```
+
+## Hyperparameter Sweeps
+
+Run distributed hyperparameter searches.
+
+```python
+import openrunner
+
+sweep_config = {
+    "method": "bayes",
+    "metric": {"name": "val_loss", "goal": "minimize"},
+    "parameters": {
+        "lr": {"min": 1e-5, "max": 1e-2, "distribution": "log_uniform"},
+        "epochs": {"values": [10, 20, 50]},
+    },
+}
+
+sweep_id = openrunner.sweep(sweep_config, project="my-project")
+
+def train():
+    run = openrunner.init()
+    lr = openrunner.config.lr
+    # ... training loop ...
+    openrunner.finish()
+
+openrunner.agent(sweep_id, function=train, count=20)
+```
+
+## Remote Launch
+
+Submit training jobs to remote infrastructure.
+
+```python
+import openrunner
+
+job = openrunner.launch(
+    project="my-project",
+    config={"lr": 0.001, "epochs": 50},
+    resource="gpu-a100",
+)
+
+job.wait()  # block until finished
+print(job.state)  # "finished"
+```
+
+## Model Registry
+
+Version and alias models for production deployment.
+
+```python
+# Log a model with aliases
+artifact = openrunner.Artifact(name="classifier", type="model")
+artifact.add_file("model.pt")
+openrunner.link_artifact(artifact, aliases=["staging"])
+
+# Use a model by alias
+model_dir = openrunner.use_artifact("classifier:production")
+```
+
+## Alerts
+
+Send notifications when training reaches milestones or encounters issues.
+
+```python
+openrunner.alert(title="Training complete", text="Final accuracy: 95.2%", level="INFO")
+openrunner.alert(title="Loss spike detected", level="WARN")
+```
+
+## Query API
+
+Read-only access to runs, metrics, and projects for analysis and dashboards.
+
+```python
+api = openrunner.Api()
+runs = api.runs("my-project", filters={"state": "finished"})
+for run in runs:
+    print(f"{run.name}: {run.summary.get('accuracy')}")
+```
+
 ## Migrating from W&B
 
 Change one import — everything else stays the same:
@@ -302,6 +471,67 @@ trainer = pl.Trainer(logger=logger)
 trainer.fit(model)
 ```
 
+### Keras
+
+```python
+from openrunner.integration.keras import OpenRunnerCallback
+
+openrunner.init(project="keras-example")
+
+model.fit(x_train, y_train, callbacks=[OpenRunnerCallback()])
+
+openrunner.finish()
+```
+
+### XGBoost
+
+```python
+from openrunner.integration.xgboost import OpenRunnerCallback
+
+openrunner.init(project="xgboost-example")
+
+bst = xgb.train(params, dtrain, callbacks=[OpenRunnerCallback()])
+
+openrunner.finish()
+```
+
+### scikit-learn
+
+```python
+from openrunner.integration.sklearn import log_model
+
+openrunner.init(project="sklearn-example")
+model.fit(X_train, y_train)
+log_model(model)  # Logs parameters and metrics
+openrunner.finish()
+```
+
+### FastAI
+
+```python
+from openrunner.integration.fastai import OpenRunnerCallback
+
+openrunner.init(project="fastai-example")
+
+learn = cnn_learner(dls, resnet34, cbs=[OpenRunnerCallback()])
+learn.fine_tune(5)
+
+openrunner.finish()
+```
+
+### LangChain
+
+```python
+from openrunner.integration.langchain import OpenRunnerTracer
+
+openrunner.init(project="langchain-example")
+
+tracer = OpenRunnerTracer()
+chain.invoke({"input": "Hello"}, config={"callbacks": [tracer]})
+
+openrunner.finish()
+```
+
 ## Offline Mode
 
 Train without connectivity, sync later:

{openrunner_sdk-0.2.0 → openrunner_sdk-0.3.0}/README.md

@@ -190,6 +190,175 @@ print(run.config)      # Config object
 print(run.summary)     # Summary object
 ```
 
+### HTML
+
+```python
+# Log raw HTML for rich reports, custom visualizations, or formatted output
+openrunner.log({"report": openrunner.Html("<h1>Training Report</h1><p>Loss converged at epoch 42.</p>")})
+```
+
+### Histograms
+
+```python
+import numpy as np
+
+weights = np.random.randn(10000)
+openrunner.log({"weight_dist": openrunner.Histogram(weights, num_bins=50)})
+```
+
+### Plotly Charts
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(data=go.Scatter(x=[1, 2, 3], y=[4, 5, 6]))
+openrunner.log({"interactive_plot": openrunner.Plotly(fig)})
+```
+
+### Point Clouds
+
+```python
+import numpy as np
+
+points = np.random.randn(1000, 3)
+colors = np.random.randint(0, 255, (1000, 3), dtype=np.uint8)
+openrunner.log({"lidar": openrunner.PointCloud3D(points, colors=colors)})
+```
+
+### Bounding Boxes
+
+```python
+img = openrunner.Image("photo.jpg")
+boxes = [{"position": {"minX": 10, "minY": 20, "maxX": 100, "maxY": 150}, "class_id": 0}]
+openrunner.log({"detections": openrunner.BoundingBoxes2D(img, boxes, class_labels={0: "cat"})})
+```
+
+### Audio
+
+```python
+import numpy as np
+
+# From numpy array (mono, float32, -1 to 1)
+audio = openrunner.Audio(np.random.randn(44100).astype(np.float32), sample_rate=44100)
+openrunner.log({"audio_sample": audio})
+```
+
+### Video
+
+```python
+# From file path
+openrunner.log({"demo": openrunner.Video("output.mp4", caption="training demo")})
+```
+
+### Matplotlib Figures
+
+```python
+import matplotlib.pyplot as plt
+
+plt.figure()
+plt.plot([1, 2, 3], [4, 5, 6])
+openrunner.log({"chart": openrunner.MatplotlibFigure()})  # captures current figure
+plt.close()
+```
+
+## LLM Tracing
+
+Trace LLM API calls for debugging and cost tracking.
+
+```python
+import openrunner
+
+openrunner.init(project="llm-app")
+
+# Auto-trace OpenAI calls
+openrunner.trace.patch_openai()
+
+# Or manually trace any function
+@openrunner.trace
+def generate(prompt):
+    return client.chat.completions.create(
+        model="gpt-4", messages=[{"role": "user", "content": prompt}]
+    )
+```
+
+## Hyperparameter Sweeps
+
+Run distributed hyperparameter searches.
+
+```python
+import openrunner
+
+sweep_config = {
+    "method": "bayes",
+    "metric": {"name": "val_loss", "goal": "minimize"},
+    "parameters": {
+        "lr": {"min": 1e-5, "max": 1e-2, "distribution": "log_uniform"},
+        "epochs": {"values": [10, 20, 50]},
+    },
+}
+
+sweep_id = openrunner.sweep(sweep_config, project="my-project")
+
+def train():
+    run = openrunner.init()
+    lr = openrunner.config.lr
+    # ... training loop ...
+    openrunner.finish()
+
+openrunner.agent(sweep_id, function=train, count=20)
+```
+
+## Remote Launch
+
+Submit training jobs to remote infrastructure.
+
+```python
+import openrunner
+
+job = openrunner.launch(
+    project="my-project",
+    config={"lr": 0.001, "epochs": 50},
+    resource="gpu-a100",
+)
+
+job.wait()  # block until finished
+print(job.state)  # "finished"
+```
+
+## Model Registry
+
+Version and alias models for production deployment.
+
+```python
+# Log a model with aliases
+artifact = openrunner.Artifact(name="classifier", type="model")
+artifact.add_file("model.pt")
+openrunner.link_artifact(artifact, aliases=["staging"])
+
+# Use a model by alias
+model_dir = openrunner.use_artifact("classifier:production")
+```
+
+## Alerts
+
+Send notifications when training reaches milestones or encounters issues.
+
+```python
+openrunner.alert(title="Training complete", text="Final accuracy: 95.2%", level="INFO")
+openrunner.alert(title="Loss spike detected", level="WARN")
+```
+
+## Query API
+
+Read-only access to runs, metrics, and projects for analysis and dashboards.
+
+```python
+api = openrunner.Api()
+runs = api.runs("my-project", filters={"state": "finished"})
+for run in runs:
+    print(f"{run.name}: {run.summary.get('accuracy')}")
+```
+
 ## Migrating from W&B
 
 Change one import — everything else stays the same:
@@ -254,6 +423,67 @@ trainer = pl.Trainer(logger=logger)
 trainer.fit(model)
 ```
 
+### Keras
+
+```python
+from openrunner.integration.keras import OpenRunnerCallback
+
+openrunner.init(project="keras-example")
+
+model.fit(x_train, y_train, callbacks=[OpenRunnerCallback()])
+
+openrunner.finish()
+```
+
+### XGBoost
+
+```python
+from openrunner.integration.xgboost import OpenRunnerCallback
+
+openrunner.init(project="xgboost-example")
+
+bst = xgb.train(params, dtrain, callbacks=[OpenRunnerCallback()])
+
+openrunner.finish()
+```
+
+### scikit-learn
+
+```python
+from openrunner.integration.sklearn import log_model
+
+openrunner.init(project="sklearn-example")
+model.fit(X_train, y_train)
+log_model(model)  # Logs parameters and metrics
+openrunner.finish()
+```
+
+### FastAI
+
+```python
+from openrunner.integration.fastai import OpenRunnerCallback
+
+openrunner.init(project="fastai-example")
+
+learn = cnn_learner(dls, resnet34, cbs=[OpenRunnerCallback()])
+learn.fine_tune(5)
+
+openrunner.finish()
+```
+
+### LangChain
+
+```python
+from openrunner.integration.langchain import OpenRunnerTracer
+
+openrunner.init(project="langchain-example")
+
+tracer = OpenRunnerTracer()
+chain.invoke({"input": "Hello"}, config={"callbacks": [tracer]})
+
+openrunner.finish()
+```
+
 ## Offline Mode
 
 Train without connectivity, sync later:

{openrunner_sdk-0.2.0 → openrunner_sdk-0.3.0}/openrunner/__init__.py

@@ -13,6 +13,9 @@ Public API:
     openrunner.Video        -> Video class for video logging
     openrunner.Histogram    -> Histogram class for distribution logging
     openrunner.Plotly       -> Plotly class for interactive charts
+    openrunner.PlotlyChart  -> Enhanced Plotly with static PNG fallback
+    openrunner.MatplotlibFigure -> Capture matplotlib figure as PNG
+    openrunner.PointCloud3D -> 3D point cloud visualization
     openrunner.BoundingBoxes2D -> Bounding box overlay on images
     openrunner.Artifact     -> Artifact class for versioned file collections
     openrunner.Api          -> Query API for read-only access to runs/projects
@@ -37,7 +40,18 @@ from typing import Any
 from openrunner.artifact import Artifact
 from openrunner.config import Config
 from openrunner.launch import LaunchJob, launch, from_run as _launch_from_run
-from openrunner.media import Audio, BoundingBoxes2D, Histogram, Image, Plotly, Table, Video
+from openrunner.media import (
+    Audio,
+    BoundingBoxes2D,
+    Histogram,
+    Image,
+    MatplotlibFigure,
+    Plotly,
+    PlotlyChart,
+    PointCloud3D,
+    Table,
+    Video,
+)
 from openrunner.query_api import Api
 from openrunner.run import Run
 from openrunner.settings import SDKSettings
@@ -53,7 +67,7 @@ launch.from_run = _launch_from_run  # type: ignore[attr-defined]
 # openrunner.trace.patch_openai() syntax
 trace.patch_openai = _patch_openai  # type: ignore[attr-defined]
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 logger = logging.getLogger("openrunner")
 

{openrunner_sdk-0.2.0 → openrunner_sdk-0.3.0}/openrunner/media.py

@@ -421,6 +421,183 @@ class Plotly:
             )
 
 
+class MatplotlibFigure:
+    """Capture a Matplotlib figure as a PNG image for experiment logging.
+
+    Accepts an optional ``matplotlib.figure.Figure``.  When *fig* is ``None``
+    the current active figure (``pyplot.gcf()``) is used, making the
+    common pattern ``openrunner.log({"chart": openrunner.MatplotlibFigure()})``
+    a one-liner.
+
+    Serialization is lazy -- the PNG bytes are produced only when the sender
+    thread calls ``_serialize()``.
+    """
+
+    def __init__(
+        self,
+        fig: Any | None = None,
+        caption: str | None = None,
+        dpi: int = 150,
+    ) -> None:
+        self._fig = fig
+        self.caption = caption
+        self.dpi = dpi
+
+    def _serialize(self) -> tuple[bytes, str]:
+        """Render figure to PNG bytes. Returns (bytes, content_type)."""
+        import matplotlib.pyplot as plt  # lazy import
+
+        fig = self._fig if self._fig is not None else plt.gcf()
+        buf = io.BytesIO()
+        fig.savefig(buf, format="png", dpi=self.dpi, bbox_inches="tight")
+        buf.seek(0)
+        return buf.getvalue(), "image/png"
+
+
+class PlotlyChart:
+    """Enhanced Plotly figure that stores both interactive JSON and static PNG.
+
+    Stores the full Plotly JSON for interactive rendering in the frontend,
+    and optionally generates a static PNG fallback via ``fig.to_image()``
+    (requires the ``kaleido`` package).
+
+    Use ``Plotly`` for JSON-only storage, ``PlotlyChart`` when you also
+    want a static image fallback.
+    """
+
+    def __init__(
+        self,
+        figure: Any,
+        caption: str | None = None,
+    ) -> None:
+        self._figure = figure
+        self.caption = caption
+
+    def _serialize(self) -> dict[str, Any]:
+        """Serialize Plotly figure to dict with optional static PNG.
+
+        Returns a dict with keys:
+        - ``data``, ``layout`` (standard Plotly JSON)
+        - ``static_image`` (base64-encoded PNG string, or None if kaleido
+          is not available)
+        """
+        import base64
+
+        # Get the JSON representation
+        if hasattr(self._figure, "to_json"):
+            json_str = self._figure.to_json()
+            result = json.loads(json_str)
+        elif hasattr(self._figure, "to_dict"):
+            result = self._figure.to_dict()
+        elif isinstance(self._figure, dict):
+            result = dict(self._figure)
+        else:
+            raise TypeError(
+                f"PlotlyChart: unsupported figure type {type(self._figure).__name__}. "
+                "Expected plotly.graph_objects.Figure or dict."
+            )
+
+        # Try to generate a static PNG fallback
+        static_image: str | None = None
+        if hasattr(self._figure, "to_image"):
+            try:
+                png_bytes = self._figure.to_image(format="png", width=800, height=500)
+                static_image = base64.b64encode(png_bytes).decode("ascii")
+            except Exception:
+                pass  # kaleido not installed or failed -- skip
+
+        result["_static_image"] = static_image
+        return result
+
+
+class PointCloud3D:
+    """A 3D point cloud for experiment logging.
+
+    Accepts XYZ coordinates as a numpy array of shape (N, 3), with optional
+    per-point RGB colors and string labels.  Data is serialized inline as
+    JSON (no S3 upload needed).
+
+    Usage::
+
+        pts = np.random.randn(1000, 3)
+        colors = np.random.randint(0, 255, (1000, 3))
+        openrunner.log({"cloud": openrunner.PointCloud3D(pts, colors=colors)})
+    """
+
+    def __init__(
+        self,
+        points: Any,
+        colors: Any | None = None,
+        labels: list[str] | None = None,
+        caption: str | None = None,
+    ) -> None:
+        self._points = points
+        self._colors = colors
+        self._labels = labels
+        self.caption = caption
+
+    def _serialize(self) -> dict[str, Any]:
+        """Serialize point cloud data to dict for JSON transmission.
+
+        Returns a dict with:
+        - ``points``: list of [x, y, z] lists
+        - ``colors``: list of [r, g, b] lists (or None)
+        - ``labels``: list of strings (or None)
+        - ``num_points``: total point count
+        - ``bounds``: {min: [x,y,z], max: [x,y,z]}
+        """
+        import numpy as np
+
+        pts = np.asarray(self._points, dtype=np.float64)
+        if pts.ndim != 2 or pts.shape[1] != 3:
+            raise ValueError(
+                f"PointCloud3D: expected array of shape (N, 3), "
+                f"got {pts.shape}"
+            )
+
+        result: dict[str, Any] = {
+            "points": pts.tolist(),
+            "num_points": int(pts.shape[0]),
+        }
+
+        # Bounds for frontend camera setup
+        if pts.shape[0] > 0:
+            result["bounds"] = {
+                "min": pts.min(axis=0).tolist(),
+                "max": pts.max(axis=0).tolist(),
+            }
+        else:
+            result["bounds"] = {"min": [0, 0, 0], "max": [0, 0, 0]}
+
+        # Colors
+        if self._colors is not None:
+            clr = np.asarray(self._colors)
+            if clr.shape != pts.shape:
+                raise ValueError(
+                    f"PointCloud3D: colors shape {clr.shape} does not match "
+                    f"points shape {pts.shape}"
+                )
+            # Normalize float colors (0-1) to int (0-255)
+            if clr.dtype.kind == "f":
+                clr = (clr.clip(0.0, 1.0) * 255).astype(np.uint8)
+            result["colors"] = clr.tolist()
+        else:
+            result["colors"] = None
+
+        # Labels
+        if self._labels is not None:
+            if len(self._labels) != pts.shape[0]:
+                raise ValueError(
+                    f"PointCloud3D: labels length {len(self._labels)} does not "
+                    f"match points count {pts.shape[0]}"
+                )
+            result["labels"] = list(self._labels)
+        else:
+            result["labels"] = None
+
+        return result
+
+
 class BoundingBoxes2D:
     """Bounding box annotations overlaid on an image.
 

{openrunner_sdk-0.2.0 → openrunner_sdk-0.3.0}/openrunner/run.py

@@ -23,7 +23,18 @@ from openrunner.buffer import WriteBuffer
 from openrunner.cache import ArtifactCache
 from openrunner.config import Config
 from openrunner.git_info import capture_git_info
-from openrunner.media import Audio, BoundingBoxes2D, Histogram, Image, Plotly, Table, Video
+from openrunner.media import (
+    Audio,
+    BoundingBoxes2D,
+    Histogram,
+    Image,
+    MatplotlibFigure,
+    Plotly,
+    PlotlyChart,
+    PointCloud3D,
+    Table,
+    Video,
+)
 from openrunner.offline import OfflineStorage
 from openrunner.sender import Sender
 from openrunner.settings import SDKSettings
@@ -267,6 +278,16 @@ class Run:
                     "caption": value.caption,
                     "_histogram_data": value._serialize(),
                 })
+            elif isinstance(value, PlotlyChart):
+                # Enhanced Plotly: JSON + optional static PNG (inline JSONB)
+                self._buffer.put({
+                    "_media": True,
+                    "_media_type": "plotly",
+                    "key": key,
+                    "step": current_step,
+                    "caption": value.caption,
+                    "_plotly_data": value._serialize(),
+                })
             elif isinstance(value, Plotly):
                 # Queue plotly figure (inline JSONB, no S3)
                 self._buffer.put({
@@ -277,6 +298,26 @@ class Run:
                     "caption": value.caption,
                     "_plotly_data": value._serialize(),
                 })
+            elif isinstance(value, MatplotlibFigure):
+                # Capture matplotlib figure as PNG image
+                self._buffer.put({
+                    "_media": True,
+                    "_media_type": "image",
+                    "key": key,
+                    "step": current_step,
+                    "caption": value.caption,
+                    "_image_obj": value,
+                })
+            elif isinstance(value, PointCloud3D):
+                # Queue point cloud data (inline JSONB, no S3)
+                self._buffer.put({
+                    "_media": True,
+                    "_media_type": "point_cloud_3d",
+                    "key": key,
+                    "step": current_step,
+                    "caption": value.caption,
+                    "_point_cloud_data": value._serialize(),
+                })
             elif isinstance(value, BoundingBoxes2D):
                 # Queue bbox overlay (image bytes + JSON box data)
                 self._buffer.put({

{openrunner_sdk-0.2.0 → openrunner_sdk-0.3.0}/openrunner/sender.py

@@ -252,6 +252,17 @@ class Sender:
                 data=item.get("_plotly_data"),
             )
 
+        elif media_type == "point_cloud_3d":
+            # Point cloud data is already serialized -- send inline as JSONB
+            self._client.create_media_file(
+                run_id=self._run_id,
+                key=item["key"],
+                media_type="point_cloud_3d",
+                step=item.get("step"),
+                caption=item.get("caption"),
+                data=item.get("_point_cloud_data"),
+            )
+
         elif media_type == "bounding_boxes_2d":
             # BBox: upload the image first, then store box data as JSONB
             bbox_obj = item["_bbox_obj"]

{openrunner_sdk-0.2.0 → openrunner_sdk-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openrunner-sdk"
-version = "0.2.0"
+version = "0.3.0"
 description = "OpenRunner SDK - W&B-compatible ML experiment tracking client"
 readme = "README.md"
 license = {text = "MIT"}

{openrunner_sdk-0.2.0 → openrunner_sdk-0.3.0}/tests/test_media.py

@@ -15,7 +15,10 @@ from openrunner.media import (
     BoundingBoxes2D,
     Histogram,
     Image,
+    MatplotlibFigure,
     Plotly,
+    PlotlyChart,
+    PointCloud3D,
     Table,
     Video,
 )
@@ -459,3 +462,267 @@ class TestBoundingBoxes2D:
         bbox = BoundingBoxes2D(img, [])
         box_data = bbox._serialize_boxes()
         assert box_data["boxes"] == []
+
+
+# ---------------------------------------------------------------------------
+# MatplotlibFigure tests
+# ---------------------------------------------------------------------------
+
+class TestMatplotlibFigure:
+    """Tests for the MatplotlibFigure class."""
+
+    def test_matplotlib_explicit_figure(self) -> None:
+        """MatplotlibFigure from explicit figure serializes to PNG bytes."""
+        import matplotlib
+        matplotlib.use("Agg")  # non-interactive backend
+        import matplotlib.pyplot as plt
+
+        fig, ax = plt.subplots()
+        ax.plot([1, 2, 3], [4, 5, 6])
+        mf = MatplotlibFigure(fig)
+        data, content_type = mf._serialize()
+        assert _is_png(data)
+        assert content_type == "image/png"
+        assert len(data) > 100  # non-trivial PNG
+        plt.close(fig)
+
+    def test_matplotlib_gcf(self) -> None:
+        """MatplotlibFigure with no fig arg captures gcf()."""
+        import matplotlib
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+
+        plt.figure()
+        plt.plot([0, 1], [0, 1])
+        mf = MatplotlibFigure()
+        data, content_type = mf._serialize()
+        assert _is_png(data)
+        assert content_type == "image/png"
+        plt.close("all")
+
+    def test_matplotlib_caption(self) -> None:
+        """Caption attribute is stored correctly."""
+        mf = MatplotlibFigure(caption="loss curve")
+        assert mf.caption == "loss curve"
+
+    def test_matplotlib_custom_dpi(self) -> None:
+        """Custom DPI produces larger PNG than low DPI."""
+        import matplotlib
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+
+        fig, ax = plt.subplots()
+        ax.plot([1, 2, 3], [4, 5, 6])
+
+        mf_low = MatplotlibFigure(fig, dpi=50)
+        data_low, _ = mf_low._serialize()
+
+        mf_high = MatplotlibFigure(fig, dpi=300)
+        data_high, _ = mf_high._serialize()
+
+        assert len(data_high) > len(data_low)
+        plt.close(fig)
+
+    def test_matplotlib_roundtrip(self) -> None:
+        """PNG output is a valid image loadable by PIL."""
+        import matplotlib
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+
+        fig, ax = plt.subplots(figsize=(4, 3))
+        ax.bar([1, 2, 3], [10, 20, 15])
+        mf = MatplotlibFigure(fig)
+        data, _ = mf._serialize()
+
+        pil = PILImage.open(io.BytesIO(data))
+        assert pil.size[0] > 0
+        assert pil.size[1] > 0
+        plt.close(fig)
+
+
+# ---------------------------------------------------------------------------
+# PlotlyChart tests
+# ---------------------------------------------------------------------------
+
+class TestPlotlyChart:
+    """Tests for the PlotlyChart class (enhanced Plotly)."""
+
+    def test_plotly_chart_from_dict(self) -> None:
+        """PlotlyChart from dict returns data/layout with _static_image."""
+        fig = {
+            "data": [{"type": "scatter", "x": [1, 2], "y": [3, 4]}],
+            "layout": {"title": "Test"},
+        }
+        pc = PlotlyChart(fig)
+        result = pc._serialize()
+        assert result["data"] == fig["data"]
+        assert result["layout"] == fig["layout"]
+        # Dict input has no to_image method, so static_image should be None
+        assert result["_static_image"] is None
+
+    def test_plotly_chart_from_object_with_to_json(self) -> None:
+        """PlotlyChart from object with to_json() serializes correctly."""
+
+        class FakeFigure:
+            def to_json(self):
+                return '{"data": [{"type": "bar"}], "layout": {}}'
+
+        pc = PlotlyChart(FakeFigure())
+        result = pc._serialize()
+        assert result["data"] == [{"type": "bar"}]
+        assert "_static_image" in result
+
+    def test_plotly_chart_from_object_with_to_dict(self) -> None:
+        """PlotlyChart from object with to_dict() serializes correctly."""
+
+        class FakeFigure:
+            def to_dict(self):
+                return {"data": [{"type": "pie"}], "layout": {"title": "Pie"}}
+
+        pc = PlotlyChart(FakeFigure())
+        result = pc._serialize()
+        assert result["data"][0]["type"] == "pie"
+
+    def test_plotly_chart_caption(self) -> None:
+        """Caption attribute is stored."""
+        pc = PlotlyChart({}, caption="interactive chart")
+        assert pc.caption == "interactive chart"
+
+    def test_plotly_chart_static_image_with_to_image(self) -> None:
+        """When to_image() is available, _static_image is populated."""
+        import base64
+
+        class FakeFigure:
+            def to_json(self):
+                return '{"data": [], "layout": {}}'
+
+            def to_image(self, format="png", width=800, height=500):
+                # Return fake PNG bytes
+                return b"\x89PNG\r\n\x1a\n" + b"\x00" * 50
+
+        pc = PlotlyChart(FakeFigure())
+        result = pc._serialize()
+        assert result["_static_image"] is not None
+        # Verify it's valid base64
+        decoded = base64.b64decode(result["_static_image"])
+        assert decoded[:8] == b"\x89PNG\r\n\x1a\n"
+
+    def test_plotly_chart_unsupported_type(self) -> None:
+        """Unsupported type raises TypeError."""
+        pc = PlotlyChart(42)
+        try:
+            pc._serialize()
+            assert False, "Should have raised"
+        except TypeError as e:
+            assert "int" in str(e)
+
+
+# ---------------------------------------------------------------------------
+# PointCloud3D tests
+# ---------------------------------------------------------------------------
+
+class TestPointCloud3D:
+    """Tests for the PointCloud3D class."""
+
+    def test_point_cloud_basic(self) -> None:
+        """PointCloud3D with xyz points serializes correctly."""
+        pts = np.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
+        pc = PointCloud3D(pts)
+        result = pc._serialize()
+
+        assert result["num_points"] == 2
+        assert len(result["points"]) == 2
+        assert result["points"][0] == [1.0, 2.0, 3.0]
+        assert result["points"][1] == [4.0, 5.0, 6.0]
+        assert result["colors"] is None
+        assert result["labels"] is None
+        assert result["bounds"]["min"] == [1.0, 2.0, 3.0]
+        assert result["bounds"]["max"] == [4.0, 5.0, 6.0]
+
+    def test_point_cloud_with_colors(self) -> None:
+        """PointCloud3D with per-point colors serializes correctly."""
+        pts = np.array([[0.0, 0.0, 0.0], [1.0, 1.0, 1.0]])
+        colors = np.array([[255, 0, 0], [0, 255, 0]], dtype=np.uint8)
+        pc = PointCloud3D(pts, colors=colors)
+        result = pc._serialize()
+
+        assert result["colors"] is not None
+        assert result["colors"][0] == [255, 0, 0]
+        assert result["colors"][1] == [0, 255, 0]
+
+    def test_point_cloud_float_colors(self) -> None:
+        """Float colors (0-1) are normalized to int (0-255)."""
+        pts = np.array([[0.0, 0.0, 0.0]])
+        colors = np.array([[1.0, 0.5, 0.0]])
+        pc = PointCloud3D(pts, colors=colors)
+        result = pc._serialize()
+
+        assert result["colors"][0] == [255, 127, 0] or result["colors"][0] == [255, 128, 0]
+
+    def test_point_cloud_with_labels(self) -> None:
+        """PointCloud3D with per-point labels serializes correctly."""
+        pts = np.array([[0.0, 0.0, 0.0], [1.0, 1.0, 1.0]])
+        labels = ["origin", "corner"]
+        pc = PointCloud3D(pts, labels=labels)
+        result = pc._serialize()
+
+        assert result["labels"] == ["origin", "corner"]
+
+    def test_point_cloud_caption(self) -> None:
+        """Caption attribute is stored correctly."""
+        pts = np.zeros((1, 3))
+        pc = PointCloud3D(pts, caption="lidar scan")
+        assert pc.caption == "lidar scan"
+
+    def test_point_cloud_wrong_shape(self) -> None:
+        """Non-(N,3) array raises ValueError."""
+        pts = np.zeros((5, 2))
+        pc = PointCloud3D(pts)
+        try:
+            pc._serialize()
+            assert False, "Should have raised"
+        except ValueError as e:
+            assert "(N, 3)" in str(e)
+
+    def test_point_cloud_color_shape_mismatch(self) -> None:
+        """Mismatched colors shape raises ValueError."""
+        pts = np.zeros((3, 3))
+        colors = np.zeros((2, 3))
+        pc = PointCloud3D(pts, colors=colors)
+        try:
+            pc._serialize()
+            assert False, "Should have raised"
+        except ValueError as e:
+            assert "colors shape" in str(e)
+
+    def test_point_cloud_label_length_mismatch(self) -> None:
+        """Mismatched labels length raises ValueError."""
+        pts = np.zeros((3, 3))
+        pc = PointCloud3D(pts, labels=["a", "b"])
+        try:
+            pc._serialize()
+            assert False, "Should have raised"
+        except ValueError as e:
+            assert "labels length" in str(e)
+
+    def test_point_cloud_empty(self) -> None:
+        """Empty point cloud (0 points) serializes correctly."""
+        pts = np.zeros((0, 3))
+        pc = PointCloud3D(pts)
+        result = pc._serialize()
+        assert result["num_points"] == 0
+        assert result["points"] == []
+        assert result["bounds"]["min"] == [0, 0, 0]
+        assert result["bounds"]["max"] == [0, 0, 0]
+
+    def test_point_cloud_large(self) -> None:
+        """Large point cloud (1000 points) serializes without error."""
+        pts = np.random.randn(1000, 3)
+        colors = np.random.randint(0, 255, (1000, 3), dtype=np.uint8)
+        labels = [f"pt_{i}" for i in range(1000)]
+        pc = PointCloud3D(pts, colors=colors, labels=labels)
+        result = pc._serialize()
+        assert result["num_points"] == 1000
+        assert len(result["points"]) == 1000
+        assert len(result["colors"]) == 1000
+        assert len(result["labels"]) == 1000