trackio/pr_320/en/api.md

# API Reference

## Run[[trackio.Run]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>class trackio.Run</name><anchor>trackio.Run</anchor><source>https://github.com/gradio-app/trackio/blob/vr_320/trackio/run.py#L19</source><parameters>[{"name": "url", "val": ": str"}, {"name": "project", "val": ": str"}, {"name": "client", "val": ": gradio_client.client.Client | None"}, {"name": "name", "val": ": str | None = None"}, {"name": "group", "val": ": str | None = None"}, {"name": "config", "val": ": dict | None = None"}, {"name": "space_id", "val": ": str | None = None"}]</parameters></docstring>



<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>finish</name><anchor>trackio.Run.finish</anchor><source>https://github.com/gradio-app/trackio/blob/vr_320/trackio/run.py#L183</source><parameters>[]</parameters></docstring>
Cleanup when run is finished.

</div></div>

## init[[trackio.init]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>trackio.init</name><anchor>trackio.init</anchor><source>https://github.com/gradio-app/trackio/blob/vr_320/trackio/__init__.py#L61</source><parameters>[{"name": "project", "val": ": str"}, {"name": "name", "val": ": str | None = None"}, {"name": "group", "val": ": str | None = None"}, {"name": "space_id", "val": ": str | None = None"}, {"name": "space_storage", "val": ": huggingface_hub._space_api.SpaceStorage | None = None"}, {"name": "dataset_id", "val": ": str | None = None"}, {"name": "config", "val": ": dict | None = None"}, {"name": "resume", "val": ": str = 'never'"}, {"name": "settings", "val": ": typing.Any = None"}, {"name": "private", "val": ": bool | None = None"}, {"name": "embed", "val": ": bool = True"}]</parameters><paramsdesc>- **project** (`str`) --
  The name of the project (can be an existing project to continue tracking or
  a new project to start tracking from scratch).
- **name** (`str`, *optional*) --
  The name of the run (if not provided, a default name will be generated).
- **group** (`str`, *optional*) --
  The name of the group which this run belongs to in order to help organize
  related runs together. You can toggle the entire group's visibilitiy in the
  dashboard.
- **space_id** (`str`, *optional*) --
  If provided, the project will be logged to a Hugging Face Space instead of
  a local directory. Should be a complete Space name like
  `"username/reponame"` or `"orgname/reponame"`, or just `"reponame"` in which
  case the Space will be created in the currently-logged-in Hugging Face
  user's namespace. If the Space does not exist, it will be created. If the
  Space already exists, the project will be logged to it.
- **space_storage** ([SpaceStorage](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/space_runtime#huggingface_hub.SpaceStorage), *optional*) --
  Choice of persistent storage tier.
- **dataset_id** (`str`, *optional*) --
  If a `space_id` is provided, a persistent Hugging Face Dataset will be
  created and the metrics will be synced to it every 5 minutes. Specify a
  Dataset with name like `"username/datasetname"` or `"orgname/datasetname"`,
  or `"datasetname"` (uses currently-logged-in Hugging Face user's namespace),
  or `None` (uses the same name as the Space but with the `"_dataset"`
  suffix). If the Dataset does not exist, it will be created. If the Dataset
  already exists, the project will be appended to it.
- **config** (`dict`, *optional*) --
  A dictionary of configuration options. Provided for compatibility with
  `wandb.init()`.
- **resume** (`str`, *optional*, defaults to `"never"`) --
  Controls how to handle resuming a run. Can be one of:

  - `"must"`: Must resume the run with the given name, raises error if run
    doesn't exist
  - `"allow"`: Resume the run if it exists, otherwise create a new run
  - `"never"`: Never resume a run, always create a new one
- **private** (`bool`, *optional*) --
  Whether to make the Space private. If None (default), the repo will be
  public unless the organization's default is private. This value is ignored
  if the repo already exists.
- **settings** (`Any`, *optional*) --
  Not used. Provided for compatibility with `wandb.init()`.
- **embed** (`bool`, *optional*, defaults to `True`) --
  If running inside a jupyter/Colab notebook, whether the dashboard should
  automatically be embedded in the cell when trackio.init() is called.</paramsdesc><paramgroups>0</paramgroups><rettype>`Run`</rettype><retdesc>A [Run](/docs/trackio/pr_320/en/api#trackio.Run) object that can be used to log metrics and finish the run.</retdesc></docstring>

Creates a new Trackio project and returns a [Run](/docs/trackio/pr_320/en/api#trackio.Run) object.








</div>

## log[[trackio.log]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>trackio.log</name><anchor>trackio.log</anchor><source>https://github.com/gradio-app/trackio/blob/vr_320/trackio/__init__.py#L232</source><parameters>[{"name": "metrics", "val": ": dict"}, {"name": "step", "val": ": int | None = None"}]</parameters><paramsdesc>- **metrics** (`dict`) --
  A dictionary of metrics to log.
- **step** (`int`, *optional*) --
  The step number. If not provided, the step will be incremented
  automatically.</paramsdesc><paramgroups>0</paramgroups></docstring>

Logs metrics to the current run.




</div>

## finish[[trackio.finish]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>trackio.finish</name><anchor>trackio.finish</anchor><source>https://github.com/gradio-app/trackio/blob/vr_320/trackio/__init__.py#L252</source><parameters>[]</parameters></docstring>

Finishes the current run.


</div>

## show[[trackio.show]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>trackio.show</name><anchor>trackio.show</anchor><source>https://github.com/gradio-app/trackio/blob/vr_320/trackio/__init__.py#L262</source><parameters>[{"name": "project", "val": ": str | None = None"}, {"name": "theme", "val": ": str | gradio.themes.base.ThemeClass | None = None"}, {"name": "mcp_server", "val": ": bool | None = None"}]</parameters><paramsdesc>- **project** (`str`, *optional*) --
  The name of the project whose runs to show. If not provided, all projects
  will be shown and the user can select one.
- **theme** (`str` or `ThemeClass`, *optional*) --
  A Gradio Theme to use for the dashboard instead of the default Gradio theme,
  can be a built-in theme (e.g. `'soft'`, `'citrus'`), a theme from the Hub
  (e.g. `"gstaff/xkcd"`), or a custom Theme class. If not provided, the
  `TRACKIO_THEME` environment variable will be used, or if that is not set, the
  default Gradio theme will be used.
- **mcp_server** (`bool`, *optional*) --
  If `True`, the Trackio dashboard will be set up as an MCP server and certain
  functions will be added as MCP tools. If `None` (default behavior), then the
  `GRADIO_MCP_SERVER` environment variable will be used to determine if the
  MCP server should be enabled (which is `"True"` on Hugging Face Spaces).</paramsdesc><paramgroups>0</paramgroups></docstring>

Launches the Trackio dashboard.




</div>

## import_csv[[trackio.import_csv]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>trackio.import_csv</name><anchor>trackio.import_csv</anchor><source>https://github.com/gradio-app/trackio/blob/vr_320/trackio/imports.py#L10</source><parameters>[{"name": "csv_path", "val": ": str | pathlib.Path"}, {"name": "project", "val": ": str"}, {"name": "name", "val": ": str | None = None"}, {"name": "space_id", "val": ": str | None = None"}, {"name": "dataset_id", "val": ": str | None = None"}, {"name": "private", "val": ": bool | None = None"}]</parameters><paramsdesc>- **csv_path** (`str` or `Path`) --
  The str or Path to the CSV file to import.
- **project** (`str`) --
  The name of the project to import the CSV file into. Must not be an existing
  project.
- **name** (`str`, *optional*) --
  The name of the Run to import the CSV file into. If not provided, a default
  name will be generated.
- **name** (`str`, *optional*) --
  The name of the run (if not provided, a default name will be generated).
- **space_id** (`str`, *optional*) --
  If provided, the project will be logged to a Hugging Face Space instead of a
  local directory. Should be a complete Space name like `"username/reponame"`
  or `"orgname/reponame"`, or just `"reponame"` in which case the Space will
  be created in the currently-logged-in Hugging Face user's namespace. If the
  Space does not exist, it will be created. If the Space already exists, the
  project will be logged to it.
- **dataset_id** (`str`, *optional*) --
  If provided, a persistent Hugging Face Dataset will be created and the
  metrics will be synced to it every 5 minutes. Should be a complete Dataset
  name like `"username/datasetname"` or `"orgname/datasetname"`, or just
  `"datasetname"` in which case the Dataset will be created in the
  currently-logged-in Hugging Face user's namespace. If the Dataset does not
  exist, it will be created. If the Dataset already exists, the project will
  be appended to it. If not provided, the metrics will be logged to a local
  SQLite database, unless a `space_id` is provided, in which case a Dataset
  will be automatically created with the same name as the Space but with the
  `"_dataset"` suffix.
- **private** (`bool`, *optional*) --
  Whether to make the Space private. If None (default), the repo will be
  public unless the organization's default is private. This value is ignored
  if the repo already exists.</paramsdesc><paramgroups>0</paramgroups></docstring>

Imports a CSV file into a Trackio project. The CSV file must contain a `"step"`
column, may optionally contain a `"timestamp"` column, and any other columns will be
treated as metrics. It should also include a header row with the column names.

TODO: call init() and return a Run object so that the user can continue to log metrics to it.




</div>

## import_tf_events[[trackio.import_tf_events]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>trackio.import_tf_events</name><anchor>trackio.import_tf_events</anchor><source>https://github.com/gradio-app/trackio/blob/vr_320/trackio/imports.py#L152</source><parameters>[{"name": "log_dir", "val": ": str | pathlib.Path"}, {"name": "project", "val": ": str"}, {"name": "name", "val": ": str | None = None"}, {"name": "space_id", "val": ": str | None = None"}, {"name": "dataset_id", "val": ": str | None = None"}, {"name": "private", "val": ": bool | None = None"}]</parameters><paramsdesc>- **log_dir** (`str` or `Path`) --
  The str or Path to the directory containing TensorFlow Events files.
- **project** (`str`) --
  The name of the project to import the TensorFlow Events files into. Must not
  be an existing project.
- **name** (`str`, *optional*) --
  The name prefix for runs (if not provided, will use directory names). Each
  subdirectory will create a separate run.
- **space_id** (`str`, *optional*) --
  If provided, the project will be logged to a Hugging Face Space instead of a
  local directory. Should be a complete Space name like `"username/reponame"`
  or `"orgname/reponame"`, or just `"reponame"` in which case the Space will
  be created in the currently-logged-in Hugging Face user's namespace. If the
  Space does not exist, it will be created. If the Space already exists, the
  project will be logged to it.
- **dataset_id** (`str`, *optional*) --
  If provided, a persistent Hugging Face Dataset will be created and the
  metrics will be synced to it every 5 minutes. Should be a complete Dataset
  name like `"username/datasetname"` or `"orgname/datasetname"`, or just
  `"datasetname"` in which case the Dataset will be created in the
  currently-logged-in Hugging Face user's namespace. If the Dataset does not
  exist, it will be created. If the Dataset already exists, the project will
  be appended to it. If not provided, the metrics will be logged to a local
  SQLite database, unless a `space_id` is provided, in which case a Dataset
  will be automatically created with the same name as the Space but with the
  `"_dataset"` suffix.
- **private** (`bool`, *optional*) --
  Whether to make the Space private. If None (default), the repo will be
  public unless the organization's default is private. This value is ignored
  if the repo already exists.</paramsdesc><paramgroups>0</paramgroups></docstring>

Imports TensorFlow Events files from a directory into a Trackio project. Each
subdirectory in the log directory will be imported as a separate run.




</div>

## Table[[trackio.Table]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>class trackio.Table</name><anchor>trackio.Table</anchor><source>https://github.com/gradio-app/trackio/blob/vr_320/trackio/table.py#L6</source><parameters>[{"name": "columns", "val": ": list[str] | None = None"}, {"name": "data", "val": ": list[list[typing.Any]] | None = None"}, {"name": "dataframe", "val": ": pandas.core.frame.DataFrame | None = None"}, {"name": "rows", "val": ": list[list[typing.Any]] | None = None"}, {"name": "optional", "val": ": bool | list[bool] = True"}, {"name": "allow_mixed_types", "val": ": bool = False"}, {"name": "log_mode", "val": ": typing.Optional[typing.Literal['IMMUTABLE', 'MUTABLE', 'INCREMENTAL']] = 'IMMUTABLE'"}]</parameters><paramsdesc>- **columns** (`list[str]`, *optional*) --
  Names of the columns in the table. Optional if `data` is provided. Not
  expected if `dataframe` is provided. Currently ignored.
- **data** (`list[list[Any]]`, *optional*) --
  2D row-oriented array of values.
- **dataframe** (`pandas.`DataFrame``, *optional*) --
  DataFrame object used to create the table. When set, `data` and `columns`
  arguments are ignored.
- **rows** (`list[list[any]]`, *optional*) --
  Currently ignored.
- **optional** (`bool` or `list[bool]`, *optional*, defaults to `True`) --
  Currently ignored.
- **allow_mixed_types** (`bool`, *optional*, defaults to `False`) --
  Currently ignored.
- **log_mode** -- (`Literal["IMMUTABLE", "MUTABLE", "INCREMENTAL"]` or `None`, *optional*, defaults to `"IMMUTABLE"`):
  Currently ignored.</paramsdesc><paramgroups>0</paramgroups></docstring>

Initializes a Table object.




</div>

## Image[[trackio.TrackioImage]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>class trackio.TrackioImage</name><anchor>trackio.TrackioImage</anchor><source>https://github.com/gradio-app/trackio/blob/vr_320/trackio/media.py#L97</source><parameters>[{"name": "value", "val": ": str | pathlib.Path | numpy.ndarray | PIL.Image.Image"}, {"name": "caption", "val": ": str | None = None"}]</parameters><paramsdesc>- **value** (`str`, `Path`, `numpy.ndarray`, or `PIL.Image`, *optional*) --
  A path to an image, a PIL Image, or a numpy array of shape (height, width, channels).
  If numpy array, should be of type `np.uint8` with RGB values in the range `[0, 255]`.
- **caption** (`str`, *optional*) --
  A string caption for the image.</paramsdesc><paramgroups>0</paramgroups></docstring>

Initializes an Image object.

<ExampleCodeBlock anchor="trackio.TrackioImage.example">

Example:
```python
import trackio
import numpy as np
from PIL import Image

# Create an image from numpy array
image_data = np.random.randint(0, 255, (64, 64, 3), dtype=np.uint8)
image = trackio.Image(image_data, caption="Random image")
trackio.log({"my_image": image})

# Create an image from PIL Image
pil_image = Image.new('RGB', (100, 100), color='red')
image = trackio.Image(pil_image, caption="Red square")
trackio.log({"red_image": image})

# Create an image from file path
image = trackio.Image("path/to/image.jpg", caption="Photo from file")
trackio.log({"file_image": image})
```

</ExampleCodeBlock>




</div>

## Video[[trackio.TrackioVideo]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>class trackio.TrackioVideo</name><anchor>trackio.TrackioVideo</anchor><source>https://github.com/gradio-app/trackio/blob/vr_320/trackio/media.py#L172</source><parameters>[{"name": "value", "val": ": str | pathlib.Path | numpy.ndarray"}, {"name": "caption", "val": ": str | None = None"}, {"name": "fps", "val": ": int | None = None"}, {"name": "format", "val": ": typing.Optional[typing.Literal['gif', 'mp4', 'webm']] = None"}]</parameters><paramsdesc>- **value** (`str`, `Path`, or `numpy.ndarray`, *optional*) --
  A path to a video file, or a numpy array.
  If numpy array, should be of type `np.uint8` with RGB values in the range `[0, 255]`.
  It is expected to have shape of either (frames, channels, height, width) or (batch, frames, channels, height, width).
  For the latter, the videos will be tiled into a grid.
- **caption** (`str`, *optional*) --
  A string caption for the video.
- **fps** (`int`, *optional*) --
  Frames per second for the video. Only used when value is an ndarray. Default is `24`.
- **format** (`Literal["gif", "mp4", "webm"]`, *optional*) --
  Video format ("gif", "mp4", or "webm"). Only used when value is an ndarray. Default is "gif".</paramsdesc><paramgroups>0</paramgroups></docstring>

Initializes a Video object.

<ExampleCodeBlock anchor="trackio.TrackioVideo.example">

Example:
```python
import trackio
import numpy as np

# Create a simple video from numpy array
frames = np.random.randint(0, 255, (10, 3, 64, 64), dtype=np.uint8)
video = trackio.Video(frames, caption="Random video", fps=30)

# Create a batch of videos
batch_frames = np.random.randint(0, 255, (3, 10, 3, 64, 64), dtype=np.uint8)
batch_video = trackio.Video(batch_frames, caption="Batch of videos", fps=15)

# Create video from file path
video = trackio.Video("path/to/video.mp4", caption="Video from file")
```

</ExampleCodeBlock>




</div>

<EditOnGithub source="https://github.com/gradio-app/trackio/blob/main/docs/source/api.md" />