Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pysquirrels.com/llms.txt

Use this file to discover all available pages before exploring further.

Dashboards allow you to create custom visualizations or reports (in PNG or HTML format) that can be served via the API. They are useful for creating charts, graphs, or formatted text outputs based on your data. Unlike datasets, there is currently no support for serving dashboards to AI agents through MCP tools. Dashboards are defined in the dashboards/ directory using Python.

​
File structure

The logic of the dashboard is written in a Python file. Optionally, the metadata (such as description and dependencies) can be specified in a YAML file with the same name. 
dashboards/
├── my_dashboard.py      # Python dashboard logic
└── my_dashboard.yml     # optional configuration

​
Python dashboards

A dashboard is defined by a main function in a Python file. This function is async, receives a DashboardArgs object, and returns a Dashboard object (specifically, a PngDashboard or HtmlDashboard).

​
Example: PNG Dashboard

This example creates a simple plot using matplotlib. PngDashboard accepts a matplotlib.figure.Figure, io.BytesIO, or bytes.
dashboards/my_plot.py
from squirrels.arguments import DashboardArgs
from squirrels.dashboards import PngDashboard
import matplotlib.pyplot as plt

async def main(sqrl: DashboardArgs) -> PngDashboard:
    # Get data from a dataset
    df = await sqrl.dataset("my_federate_model")
    
    # Create the plot
    fig, ax = plt.subplots()
    ax.plot(df["date"], df["amount"])
    ax.set_title("Sales Over Time")
    
    # Return as PngDashboard
    return PngDashboard(fig)

​
Example: HTML Dashboard

This example creates an HTML report. HtmlDashboard accepts a string or io.StringIO containing HTML.
dashboards/my_report.py
from squirrels.arguments import DashboardArgs
from squirrels.dashboards import HtmlDashboard

async def main(sqrl: DashboardArgs) -> HtmlDashboard:
    # Get data
    df = await sqrl.dataset("my_federate_model")
    
    # Convert to HTML table (using pandas for convenience)
    html_content = f"<h1>Sales Report</h1>{df.to_pandas().to_html()}"
    
    return HtmlDashboard(html_content)

​
Accessing datasets

In your Python code, you access datasets using sqrl.dataset(). As dashboards are run asynchronously, you must use the await keyword. 
df = await sqrl.dataset("my_federate_model")
The dataset method returns a Polars DataFrame. You can pass fixed_parameters to filter or configure the dataset for this specific dashboard. 
df = await sqrl.dataset("my_federate_model", fixed_parameters={"category": "electronics"})

​
YAML configuration

An optional YAML file with the same name provides additional configuration for the dashboard.
dashboards/my_plot.yml
label: Sales Over Time
description: |
  A plot showing sales over time.

format: png   # png or html

scope: public  # public, protected, or private

depends_on:
  - name: my_sales_data
    dataset: my_federate_model

​
Configuration fields

​
label
string
default:"(same as filename)"
A human-readable label for the dashboard.
​
description
string
default:""
A description of the dashboard for documentation purposes.
​
format
string
default:"png"
The format of the dashboard output. Options are png or html.
​
scope
string
default:"(dynamic based on auth_type)"
The access scope for the dashboard. One of:
  • public: Accessible without authentication.
  • protected: Requires authentication to access.
  • private: Only accessible by users with the admin access level.
The default value is public if auth_type is optional, and protected if it is required.
​
parameters
list[string]
default:"null"
List of parameter names used by this dashboard. If not specified, all parameters are available.
​
depends_on
list[object]
default:"[]"
List of dataset dependencies. Defining these helps with documentation and lineage.