API Reference

This section contains detailed reference documentation for DAG logging to files in Graphbook.

class graphbook.logging.CallableNode(ref: DAGNodeRef, log_every: int = 1)
class graphbook.logging.DAGLogger(name: str | None = None, log_dir: str | None = 'logs')

Logger for both code execution and image logging.

This class provides a single interface for logging both general outputs and images in a directed acyclic graph (DAG).

close()

Close the log file.

log_image(node_id: str, image: Image)

Log an image for a specific node.

Parameters:

  • node_id – ID of the node

  • image – PIL Image to log

log_message(node_id: str, message: str, log_type: str = 'info')

Log a message for a specific node.

Parameters:

  • node_id – ID of the node

  • message – Message to log

  • log_type – Type of log (info, warning, error)

log_output(node_id: str, output: Any, pin_id: str = 'out')

Log an output for a specific node.

Parameters:

  • node_id – ID of the node

  • output – Any output data to log

  • pin_id – ID of the output pin (defaults to “out”)

node(id: str, name: str, doc: str = '', back_refs: List[str] | None = None)

Register a node in the graph.

Parameters:

  • id – ID of the node

  • name – Name of the node

  • doc – Documentation for the node

  • back_refs – List of IDs of nodes that this node depends on

Returns:

The ID of the node for future reference

update_graph(graph: Dict[str, Any])

Update the graph structure metadata.

Parameters:

graph – Dict containing the graph structure

class graphbook.logging.DAGNodeRef(id: str, logger: DAGLogger)

Reference to a DAG node capable of logging images. You should not create this directly, but instead use the graphbook.logging.DAGLogger.node() to create one.

Parameters:

  • id – Unique identifier for the node

  • logger – Owner DAGLogger instance

log_image(image: Image)

Logs an image to the DAG.

Parameters:

pil_or_tensor – PIL Image

log_message(message: str, log_type: str = 'info')

Logs a message to the DAG.

Parameters:

  • message – Log message

  • log_type – Type of log (info, warning, error)

log_output(output: Any, pin_id: str = 'out')

Logs an output to the DAG.

Parameters:

  • output – Output data

  • pin_id – ID of the output pin

class graphbook.logging.LogDirectoryReader(log_dir: str, queue: Queue, poll_interval: float = 0.1, close_event: Event | None = None)

Watches a directory for log files and manages their watchers.

get_output(graph_id: str, step_id: str, pin_id: str, index: int) → Any | None

Get an output from a specific log file.

handle_deleted_file(filepath: str)

Handle a log file being deleted.

handle_new_file(filepath: str)

Handle a new log file being created.

initialize_files()

Initialize tracking for all log files in the directory.

async loop()

Check for updates in watched log files.

start()

Start watching the log directory.

async stop()

Stop watching the log directory and all log files.

class graphbook.logging.LogManager(log_dir: str = 'logs')

Manager for log files.

This class maintains a mapping of graph IDs to log files and watchers.

close()

Close all log files and stop all watchers.

create_watcher(graph_id: str, viewer_interface: ViewManagerInterface) → LogWatcher

Create a log watcher for a graph.

Parameters:

  • graph_id – ID of the graph

  • viewer_interface – Interface to the viewer

Returns:

The log watcher

get_watcher(graph_id: str) → LogWatcher | None

Get a watcher for a graph.

Parameters:

graph_id – ID of the graph

Returns:

The log watcher or None if no log exists

get_writer(graph_id: str) → LogWriter

Get or create a writer for a graph.

Parameters:

graph_id – ID of the graph

Returns:

The log writer

stop_watcher(graph_id: str)

Stop a log watcher for a graph.

Parameters:

graph_id – ID of the graph

class graphbook.logging.LogWriter(log_file_path: str)

Writer for the log file format.

This class serializes graph metadata, images, and logs using msgpack and cloudpickle, writing them to a log file for later retrieval.

close()

Close the log file.

flush()

Flush the buffer to disk.

update_metadata(metadata: Dict[str, Any])

Update the graph structure metadata.

Parameters:

metadata – Dict containing graph structure information

write_image(node_id: str, image: Image)

Write an image to the log file.

Parameters:

  • node_id – ID of the node that generated the image

  • image – PIL Image to log

write_log(step_id: str, message: str, log_type: str = 'info')

Write a log entry to the log file.

Parameters:

  • step_id – ID of the step

  • message – Log message

  • log_type – Type of log (info, warning, error)

write_output(step_id: str, pin_id: str, output: Any)

Write a step output to the log file.

Parameters:

  • step_id – ID of the step

  • pin_id – ID of the output pin

  • output – Output data

class graphbook.logging.torch.TensorDAGNodeRef(id: str, name: str, doc: str, filepath: Path, lock, *back_refs: List[TensorDAGNodeRef])

Inherits from DAGNodeRef and adds the ability to log PIL images or tensors. You should not create this directly, but instead use the graphbook.logging.torch.TransformsLogger.node() to create one.

log(pil_or_tensor: Image | Tensor)

Logs a PIL image or tensor to the node in the associated DAG.

Parameters:

pil_or_tensor – The PIL image or tensor to log.

class graphbook.logging.torch.TransformsLogger(name: str | None = None, log_dir: str | None = 'logs', log_every: int = 1)

A DAG logger designed specifically to log the image outputs from torchvision transforms.

Parameters:

  • name – Name of the DAG. Will randomly generate an ID if not provided

  • log_dir – Directory to store the log files. Defaults to logs/

  • log_every – Log every nth transform. Defaults to 1 (log every time).

Example

from torchvision import transforms as T
import torch
from PIL import Image
import graphbook as gb

l = gb.TransformsLogger()
transforms = T.Compose([
    T.ToTensor(),
    T.CenterCrop(600),
    T.Grayscale(),
    T.RandomHorizontalFlip(p=1),
])
transforms = l.log(transforms)

img_path = "<YOUR_IMAGE_PATH>"
img = Image.open(img_path)
img = transforms(img)
log(transform: Transform | Compose | Compose)

Sets up the transforms to log the image outputs.

Parameters:

transform – A torchvision transform or a sequence of transforms

node(name: str, doc: str, *back_refs: List[TensorDAGNodeRef]) → TensorDAGNodeRef

Creates a new node in the DAG that can log PIL images or tensors.

Parameters:

  • name – Name of the node

  • doc – Description of the node

  • back_refs – List of back references to other nodes

Returns:

The reference to the new node

Return type:

TensorDAGNodeRef