tb-query

A CLI tool and MCP (Model Context Protocol) server for querying and analyzing TensorBoard event files without requiring a running TensorBoard server.

Overview

tb-query allows you to directly interact with TensorBoard's events.out.tfevents.* files to extract scalar data, calculate statistics, find correlations, and more. It's particularly useful for:

• Programmatic access to training metrics
• Automated analysis of training runs
• Integration with AI coding agents through MCP
• Quick inspection of TensorBoard logs without starting a web server

Features

• Query scalar data with step and tag filtering
• Find all TensorBoard event files in a directory tree
• List available scalar tags with optional filtering
• Calculate statistics (min, max, mean, std) for specific tags
• Compute correlations between different scalar metrics
• CLI interface for command-line usage
• MCP server for integration with AI coding assistants

Installation

From PyPI

pip install tb-query

From Source

git clone https://github.com/Alir3z4/tb-query.git
cd tb-query
pip install -e .

Requirements

• Python >= 3.11
• tensorboard
• fastmcp
• pandas

CLI Usage

Query Command

Extract scalar data from a TensorBoard event file:

# Query all available tags
tb-query query path/to/events.out.tfevents.12345

# Query specific tags
tb-query query path/to/events.out.tfevents.12345 --tags loss --tags accuracy

# Query with step range filtering
tb-query query path/to/events.out.tfevents.12345 --start_step 100 --end_step 200

# Combine filters
tb-query query path/to/events.out.tfevents.12345 --tags loss --start_step 100 --end_step 200

Output format (JSON):

{
  "loss": [
    {"step": 100, "value": 0.5},
    {"step": 101, "value": 0.48}
  ],
  "accuracy": [
    {"step": 100, "value": 0.85},
    {"step": 101, "value": 0.86}
  ]
}

Tags Command

List all available scalar tags in an event file:

# List all tags
tb-query tags path/to/events.out.tfevents.12345

# Filter tags containing specific strings
tb-query tags path/to/events.out.tfevents.12345 --filter loss
tb-query tags path/to/events.out.tfevents.12345 --filter loss --filter accuracy

Output format (JSON):

{
  "tags": ["train/loss", "train/accuracy", "eval/loss", "eval/accuracy"]
}

Find Command

Locate all TensorBoard event files in a directory:

tb-query find path/to/logs

Output format (JSON):

{
  "event_files": [
    {
      "path": "path/to/logs/run1/events.out.tfevents.12345",
      "created_at": "2025-11-04T10:30:00.123456"
    },
    {
      "path": "path/to/logs/run2/events.out.tfevents.67890",
      "created_at": "2025-11-03T15:20:00.654321"
    }
  ]
}

Files are sorted by creation time (newest first).

Steps Command

Get the step numbers for specific tags:

tb-query steps path/to/events.out.tfevents.12345 --tags loss --tags accuracy

Output format (JSON):

{
  "loss": [0, 10, 20, 30, 40, 50],
  "accuracy": [0, 10, 20, 30, 40, 50]
}

Stats Command

Calculate statistical measures for tag values:

tb-query stats path/to/events.out.tfevents.12345 --tags loss --tags accuracy

Output format (JSON):

{
  "loss": {
    "min": 0.15,
    "max": 2.34,
    "mean": 0.85,
    "std": 0.42,
    "count": 1000
  },
  "accuracy": {
    "min": 0.65,
    "max": 0.98,
    "mean": 0.87,
    "std": 0.08,
    "count": 1000
  }
}

Correlation Command

Calculate Pearson correlations between scalar tags:

# Basic correlation
tb-query correlation path/to/events.out.tfevents.12345 --tags "loss,accuracy"

# With step range
tb-query correlation path/to/events.out.tfevents.12345 --tags "loss,accuracy" --start_step 100 --end_step 200

# With interpretation
tb-query correlation path/to/events.out.tfevents.12345 --tags "loss,accuracy" --display-interpretation true

# Custom rounding
tb-query correlation path/to/events.out.tfevents.1

... [View full README on GitHub](https://github.com/Alir3z4/tb-query#readme)