grimoireplot 0.0.1__tar.gz

grimoireplot-0.0.1/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.3
+Name: grimoireplot
+Version: 0.0.1
+Summary: GrimoirePlot is a live dashboard of plotly-compatible plots of remote data
+Author: William Droz
+Author-email: William Droz <william.droz@idiap.ch>
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: aiohttp[speedups]>=3.13.3
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: nicegui>=3.5.0,<4
+Requires-Dist: plotly>=6.5.2
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: requests>=2.32.5
+Requires-Dist: sqlmodel>=0.0.31
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Python: >=3.11
+Project-URL: Home, https://github.com/idiap/GrimoirePlot
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# GrimoirePlot
+
+*GrimoirePlot is a live dashboard of plotly-compatible plots of remote data*
+
+![demo](media/demo_grimoire.gif)
+
+## Installation
+
+```bash
+uv pip install grimoireplot  # not yet on pypi, will setup ci/cd on github later on
+```
+
+Or install from source:
+
+```bash
+# git clone the repo
+cd grimoireplot
+uv sync --extra dev
+```
+
+### Installation as a tool
+
+```bash
+uv tool install grimoireplot  # not yet on pypi, will setup ci/cd on github later on
+```
+
+## Quick Start
+
+### 1. Start the Server
+
+```bash
+grimoireplot serve --host localhost --port 8080
+```
+
+Then open your browser at `http://localhost:8080` to see the dashboard.
+
+### 2. Push Sample Plots (Test the Server)
+
+In another terminal, push some sample plots to verify everything works:
+
+```bash
+grimoireplot push-samples --host localhost --port 8080
+```
+
+## CLI Reference
+
+### `grimoireplot serve`
+
+Start the GrimoirePlot dashboard server.
+
+```bash
+grimoireplot serve [--host HOST] [--port PORT]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--host` | `localhost` | Host to bind the server |
+| `--port` | `8080` | Port to bind the server |
+
+### `grimoireplot push-samples`
+
+Push sample plots to test the server.
+
+```bash
+grimoireplot push-samples [--host HOST] [--port PORT] [--secret SECRET] [--grimoire-name NAME]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--host` | `localhost` | Server host |
+| `--port` | `8080` | Server port |
+| `--secret` | `IDidntSetASecret` | Authentication secret |
+| `--grimoire-name` | `test_grimoire` | Name of the grimoire to create |
+
+### `grimoireplot live-test`
+
+Test live plot updates by continuously adding datapoints to a line plot.
+
+```bash
+grimoireplot live-test [--host HOST] [--port PORT] [--secret SECRET] [--grimoire-name NAME] [--interval SECONDS] [--max-points N]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--host` | `localhost` | Server host |
+| `--port` | `8080` | Server port |
+| `--secret` | `IDidntSetASecret` | Authentication secret |
+| `--grimoire-name` | `live_test` | Name of the grimoire to create |
+| `--interval` | `0.2` | Interval between datapoints in seconds |
+| `--max-points` | `0` | Maximum number of points (0 = unlimited) |
+
+## Programmatic Usage
+
+### Sending Plots from Python
+
+GrimoirePlot organizes plots in a hierarchy: **Grimoire** → **Chapter** → **Plot**
+
+#### Synchronous API
+
+```python
+import plotly.graph_objects as go
+from grimoireplot.client import push_plot_sync
+
+# Create a Plotly figure
+fig = go.Figure()
+fig.add_trace(go.Scatter(x=[1, 2, 3, 4], y=[10, 11, 12, 13], mode='lines+markers'))
+fig.update_layout(title='My Plot')
+
+# Push to the server
+response = push_plot_sync(
+    grimoire_name="my_experiment",
+    chapter_name="training_metrics",
+    plot_name="loss_curve",
+    fig=fig,
+    grimoire_server="http://localhost:8080",
+    grimoire_secret="your-secret",
+)
+```
+
+#### Asynchronous API
+
+```python
+import asyncio
+import plotly.graph_objects as go
+from grimoireplot.client import push_plot
+
+async def main():
+    fig = go.Figure()
+    fig.add_trace(go.Bar(x=['A', 'B', 'C'], y=[20, 14, 23]))
+    fig.update_layout(title='Async Plot')
+
+    response = await push_plot(
+        grimoire_name="my_experiment",
+        chapter_name="results",
+        plot_name="bar_chart",
+        fig=fig,
+        grimoire_server="http://localhost:8080",
+        grimoire_secret="your-secret",
+    )
+
+asyncio.run(main())
+```
+
+### Integration Example: Training Loop
+
+```python
+import plotly.graph_objects as go
+from grimoireplot.client import push_plot_sync
+
+losses = []
+
+for epoch in range(100):
+    loss = train_one_epoch()  # Your training code
+    losses.append(loss)
+
+    # Update the plot every 10 epochs
+    if epoch % 10 == 0:
+        fig = go.Figure()
+        fig.add_trace(go.Scatter(y=losses, mode='lines', name='Training Loss'))
+        fig.update_layout(title=f'Training Progress (Epoch {epoch})',
+                          xaxis_title='Epoch', yaxis_title='Loss')
+
+        push_plot_sync(
+            grimoire_name="experiment_001",
+            chapter_name="training",
+            plot_name="loss",
+            fig=fig,
+        )
+```
+
+## Configuration
+
+GrimoirePlot can be configured via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GRIMOIRE_SERVER` | `http://localhost:8080` | Default server URL |
+| `GRIMOIRE_SECRET` | `IDidntSetASecret` | Authentication secret |
+
+You can also use a `.env` file in your project directory.
+
+## Testing
+
+```bash
+# you need to install with --extra dev
+GRIMOIRE_TEST=true uv run pytest
+```
+
+## Concepts
+
+- **Grimoire**: A collection of related visualizations (e.g., an experiment)
+- **Chapter**: A group of plots within a grimoire (e.g., training metrics, evaluation results)
+- **Plot**: A single Plotly figure
+
+## Acknowledgments
+
+GrimoirePlot is inspired by [visdom](https://github.com/fossasia/visdom)

grimoireplot-0.0.1/README.md

@@ -0,0 +1,197 @@
+# GrimoirePlot
+
+*GrimoirePlot is a live dashboard of plotly-compatible plots of remote data*
+
+![demo](media/demo_grimoire.gif)
+
+## Installation
+
+```bash
+uv pip install grimoireplot  # not yet on pypi, will setup ci/cd on github later on
+```
+
+Or install from source:
+
+```bash
+# git clone the repo
+cd grimoireplot
+uv sync --extra dev
+```
+
+### Installation as a tool
+
+```bash
+uv tool install grimoireplot  # not yet on pypi, will setup ci/cd on github later on
+```
+
+## Quick Start
+
+### 1. Start the Server
+
+```bash
+grimoireplot serve --host localhost --port 8080
+```
+
+Then open your browser at `http://localhost:8080` to see the dashboard.
+
+### 2. Push Sample Plots (Test the Server)
+
+In another terminal, push some sample plots to verify everything works:
+
+```bash
+grimoireplot push-samples --host localhost --port 8080
+```
+
+## CLI Reference
+
+### `grimoireplot serve`
+
+Start the GrimoirePlot dashboard server.
+
+```bash
+grimoireplot serve [--host HOST] [--port PORT]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--host` | `localhost` | Host to bind the server |
+| `--port` | `8080` | Port to bind the server |
+
+### `grimoireplot push-samples`
+
+Push sample plots to test the server.
+
+```bash
+grimoireplot push-samples [--host HOST] [--port PORT] [--secret SECRET] [--grimoire-name NAME]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--host` | `localhost` | Server host |
+| `--port` | `8080` | Server port |
+| `--secret` | `IDidntSetASecret` | Authentication secret |
+| `--grimoire-name` | `test_grimoire` | Name of the grimoire to create |
+
+### `grimoireplot live-test`
+
+Test live plot updates by continuously adding datapoints to a line plot.
+
+```bash
+grimoireplot live-test [--host HOST] [--port PORT] [--secret SECRET] [--grimoire-name NAME] [--interval SECONDS] [--max-points N]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--host` | `localhost` | Server host |
+| `--port` | `8080` | Server port |
+| `--secret` | `IDidntSetASecret` | Authentication secret |
+| `--grimoire-name` | `live_test` | Name of the grimoire to create |
+| `--interval` | `0.2` | Interval between datapoints in seconds |
+| `--max-points` | `0` | Maximum number of points (0 = unlimited) |
+
+## Programmatic Usage
+
+### Sending Plots from Python
+
+GrimoirePlot organizes plots in a hierarchy: **Grimoire** → **Chapter** → **Plot**
+
+#### Synchronous API
+
+```python
+import plotly.graph_objects as go
+from grimoireplot.client import push_plot_sync
+
+# Create a Plotly figure
+fig = go.Figure()
+fig.add_trace(go.Scatter(x=[1, 2, 3, 4], y=[10, 11, 12, 13], mode='lines+markers'))
+fig.update_layout(title='My Plot')
+
+# Push to the server
+response = push_plot_sync(
+    grimoire_name="my_experiment",
+    chapter_name="training_metrics",
+    plot_name="loss_curve",
+    fig=fig,
+    grimoire_server="http://localhost:8080",
+    grimoire_secret="your-secret",
+)
+```
+
+#### Asynchronous API
+
+```python
+import asyncio
+import plotly.graph_objects as go
+from grimoireplot.client import push_plot
+
+async def main():
+    fig = go.Figure()
+    fig.add_trace(go.Bar(x=['A', 'B', 'C'], y=[20, 14, 23]))
+    fig.update_layout(title='Async Plot')
+
+    response = await push_plot(
+        grimoire_name="my_experiment",
+        chapter_name="results",
+        plot_name="bar_chart",
+        fig=fig,
+        grimoire_server="http://localhost:8080",
+        grimoire_secret="your-secret",
+    )
+
+asyncio.run(main())
+```
+
+### Integration Example: Training Loop
+
+```python
+import plotly.graph_objects as go
+from grimoireplot.client import push_plot_sync
+
+losses = []
+
+for epoch in range(100):
+    loss = train_one_epoch()  # Your training code
+    losses.append(loss)
+
+    # Update the plot every 10 epochs
+    if epoch % 10 == 0:
+        fig = go.Figure()
+        fig.add_trace(go.Scatter(y=losses, mode='lines', name='Training Loss'))
+        fig.update_layout(title=f'Training Progress (Epoch {epoch})',
+                          xaxis_title='Epoch', yaxis_title='Loss')
+
+        push_plot_sync(
+            grimoire_name="experiment_001",
+            chapter_name="training",
+            plot_name="loss",
+            fig=fig,
+        )
+```
+
+## Configuration
+
+GrimoirePlot can be configured via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GRIMOIRE_SERVER` | `http://localhost:8080` | Default server URL |
+| `GRIMOIRE_SECRET` | `IDidntSetASecret` | Authentication secret |
+
+You can also use a `.env` file in your project directory.
+
+## Testing
+
+```bash
+# you need to install with --extra dev
+GRIMOIRE_TEST=true uv run pytest
+```
+
+## Concepts
+
+- **Grimoire**: A collection of related visualizations (e.g., an experiment)
+- **Chapter**: A group of plots within a grimoire (e.g., training metrics, evaluation results)
+- **Plot**: A single Plotly figure
+
+## Acknowledgments
+
+GrimoirePlot is inspired by [visdom](https://github.com/fossasia/visdom)

grimoireplot-0.0.1/grimoireplot/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: Copyright © 2026 Idiap Research Institute <contact@idiap.ch>
+# SPDX-FileContributor: William Droz <william.droz@idiap.ch>
+# SPDX-License-Identifier: MIT
+
+"""Module for GrimoirePlot"""

grimoireplot-0.0.1/grimoireplot/client.py

@@ -0,0 +1,166 @@
+# SPDX-FileCopyrightText: Copyright © 2026 Idiap Research Institute <contact@idiap.ch>
+# SPDX-FileContributor: William Droz <william.droz@idiap.ch>
+# SPDX-License-Identifier: MIT
+
+"""
+Client module that push plots
+"""
+
+from plotly.graph_objects import Figure
+import aiohttp
+import requests
+from grimoireplot.common import get_grimoire_secret, get_grimoire_server
+
+
+default_secret = get_grimoire_secret()
+default_server = get_grimoire_server()
+
+
+def push_plot_sync(
+    grimoire_name: str,
+    chapter_name: str,
+    plot_name: str,
+    fig: Figure,
+    grimoire_secret: str = default_secret,
+    grimoire_server: str = default_server,
+) -> dict:
+    """Push a plot to the grimoire server.
+
+    Args:
+        grimoire_name (str): Name of the grimoire.
+        chapter_name (str): Name of the chapter.
+        plot_name (str): Name of the plot.
+        fig (Figure): Plotly figure to push.
+        grimoire_secret (str, optional): Secret for authentication. Defaults to default_secret.
+        grimoire_server (str, optional): Grimoire server URL. Defaults to default_server.
+
+    Returns:
+        dict: Response from the server.
+    """
+    json_data = fig.to_json()
+    match json_data:
+        case str():
+            return push_plot_json_sync(
+                grimoire_name=grimoire_name,
+                chapter_name=chapter_name,
+                plot_name=plot_name,
+                json_data=json_data,
+                grimoire_secret=grimoire_secret,
+                grimoire_server=grimoire_server,
+            )
+        case _:
+            raise ValueError(
+                "fig.to_json() did not return a string, maybe fig is invalid?"
+            )
+
+
+def push_plot_json_sync(
+    grimoire_name: str,
+    chapter_name: str,
+    plot_name: str,
+    json_data: str,
+    grimoire_secret: str = default_secret,
+    grimoire_server: str = default_server,
+) -> dict:
+    """Push a plot to the grimoire server.
+
+    Args:
+        grimoire_name (str): Name of the grimoire.
+        chapter_name (str): Name of the chapter.
+        plot_name (str): Name of the plot.
+        json_data (str): JSON representation of the plotly figure.
+        grimoire_secret (str, optional): Secret for authentication. Defaults to default_secret.
+        grimoire_server (str, optional): Grimoire server URL. Defaults to defualt_server.
+
+    Returns:
+        dict: Response from the server.
+    """
+
+    url = f"{grimoire_server}/add_plot"
+    headers = {"grimoire-secret": grimoire_secret}
+
+    payload = {
+        "grimoire_name": grimoire_name,
+        "chapter_name": chapter_name,
+        "plot_name": plot_name,
+        "json_data": json_data,
+    }
+
+    response = requests.post(url, headers=headers, json=payload)
+    response.raise_for_status()
+    return response.json()
+
+
+async def push_plot(
+    grimoire_name: str,
+    chapter_name: str,
+    plot_name: str,
+    fig: Figure,
+    grimoire_secret: str = default_secret,
+    grimoire_server: str = default_server,
+) -> dict:
+    """Push a plot to the grimoire server asynchronously.
+
+    Args:
+        grimoire_name (str): Name of the grimoire.
+        chapter_name (str): Name of the chapter.
+        plot_name (str): Name of the plot.
+        fig (Figure): Plotly figure to push.
+        grimoire_secret (str, optional): Secret for authentication. Defaults to default_secret.
+        grimoire_server (str, optional): Grimoire server URL. Defaults to default_server.
+
+    Returns:
+        dict: Response from the server.
+    """
+    json_data = fig.to_json()
+    match json_data:
+        case str():
+            return await push_plot_json(
+                grimoire_name=grimoire_name,
+                chapter_name=chapter_name,
+                plot_name=plot_name,
+                json_data=json_data,
+                grimoire_secret=grimoire_secret,
+                grimoire_server=grimoire_server,
+            )
+        case _:
+            raise ValueError(
+                "fig.to_json() did not return a string, maybe fig is invalid?"
+            )
+
+
+async def push_plot_json(
+    grimoire_name: str,
+    chapter_name: str,
+    plot_name: str,
+    json_data: str,
+    grimoire_secret: str = default_secret,
+    grimoire_server: str = default_server,
+) -> dict:
+    """Push a plot to the grimoire server asynchronously.
+
+    Args:
+        grimoire_name (str): Name of the grimoire.
+        chapter_name (str): Name of the chapter.
+        plot_name (str): Name of the plot.
+        json_data (str): JSON representation of the plotly figure.
+        grimoire_secret (str, optional): Secret for authentication. Defaults to default_secret.
+        grimoire_server (str, optional): Grimoire server URL. Defaults to default_server.
+
+    Returns:
+        dict: Response from the server.
+    """
+    url = f"{grimoire_server}/add_plot"
+    headers = {"grimoire-secret": grimoire_secret}
+
+    payload = {
+        "grimoire_name": grimoire_name,
+        "chapter_name": chapter_name,
+        "plot_name": plot_name,
+        "json_data": json_data,
+    }
+
+    async with aiohttp.ClientSession() as session:
+        async with session.post(url, headers=headers, json=payload) as response:
+            response.raise_for_status()
+            return await response.json()

grimoireplot-0.0.1/grimoireplot/common.py

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: Copyright © 2026 Idiap Research Institute <contact@idiap.ch>
+# SPDX-FileContributor: William Droz <william.droz@idiap.ch>
+# SPDX-License-Identifier: MIT
+
+"""
+Common module for grimoireplot client and server
+"""
+
+import os
+from dotenv import load_dotenv
+from loguru import logger
+
+
+load_dotenv()
+
+
+def get_grimoire_secret() -> str:
+    if (grimoire_secret := os.environ.get("GRIMOIRE_SECRET")) is None:
+        logger.warning("GRIMOIRE_SECRET not set; using default secret")
+        grimoire_secret = "IDidntSetASecret"
+
+    return grimoire_secret
+
+
+def get_grimoire_server() -> str:
+    if (grimoire_server := os.environ.get("GRIMOIRE_SERVER")) is None:
+        grimoire_server = "http://localhost:8080"
+        logger.warning(
+            f"GRIMOIRE_SERVER not set; using default server {grimoire_server}"
+        )
+
+    return grimoire_server