root_mcp.core.io package

Core I/O operations for ROOT files.

class root_mcp.core.io.DataExporter(config)

Bases: object

Export TTree data to various formats.

Supports JSON, CSV, and Parquet exports with compression options.

Parameters:

config (Config)

__init__(config)

Initialize data exporter.

Parameters:

config (Config) – Server configuration

export(data, output_path, format, **kwargs)

Export data to specified format.

Parameters:

• data (awkward.Array) – Awkward array data

• output_path (str | Path) – Output file path

• format (str) – Export format (json, csv, parquet)

• **kwargs (Any) – Format-specific options

Returns:

Export metadata

Raises:

ValueError – If format is not supported

Return type:

dict[str, Any]

export_to_csv(data, output_path, compress=False)

Export data to CSV format.

Parameters:

• data (awkward.Array) – Awkward array data

• output_path (str | Path) – Output file path

• compress (bool) – Whether to compress output

Returns:

Export metadata

Return type:

dict[str, Any]

export_to_json(data, output_path, compress=False)

Export data to JSON format.

Parameters:

• data (awkward.Array) – Awkward array data

• output_path (str | Path) – Output file path

• compress (bool) – Whether to compress output

Returns:

Export metadata

Return type:

dict[str, Any]

export_to_parquet(data, output_path, compression='snappy')

Export data to Parquet format.

Parameters:

• data (awkward.Array) – Awkward array data

• output_path (str | Path) – Output file path

• compression (str) – Compression algorithm (snappy, gzip, brotli, none)

Returns:

Export metadata

Return type:

dict[str, Any]

class root_mcp.core.io.FileCache(max_size)

Bases: object

LRU cache for open ROOT files.

Parameters:

max_size (int)

__init__(max_size)

Initialize file cache.

Parameters:

max_size (int) – Maximum number of files to keep open

clear()

Clear the cache.

Return type:

None

get(path)

Get file from cache.

Parameters:

path (str) – File path

Returns:

Open file object or None if not cached

Return type:

Any | None

put(path, file_obj)

Add file to cache.

Parameters:

• path (str) – File path

• file_obj (Any) – Open file object

Return type:

None

size()

Get current cache size.

Return type:

int

class root_mcp.core.io.FileManager(config)

Bases: object

Manages opening and caching of ROOT files.

Provides safe, efficient access to local and remote ROOT files with automatic caching and connection pooling.

Parameters:

config (Config)

__init__(config)

Initialize file manager.

Parameters:

config (Config) – Server configuration

clear_cache()

Clear the file cache.

Return type:

None

get_branch_schema(path, tree_name, branch_name=None)

Get detailed schema information for branches.

Parameters:

• path (str | Path) – File path

• tree_name (str) – Tree name

• branch_name (str | None) – Optional specific branch (None = all branches)

Returns:

Dictionary with branch schema information

Return type:

dict[str, Any]

get_cache_stats()

Get cache statistics.

Returns:

Dictionary with cache stats

Return type:

dict[str, int]

get_file_info(path)

Get basic information about a ROOT file.

Parameters:

path (str | Path) – File path

Returns:

Dictionary with file metadata

Return type:

dict[str, Any]

get_tree(path, tree_name)

Get a specific TTree from a file.

Parameters:

• path (str | Path) – File path

• tree_name (str) – Name or path to tree

Returns:

uproot TTree object

Raises:

KeyError – If tree doesn’t exist

Return type:

Any

get_tree_info(path, tree_name)

Get comprehensive metadata about a TTree or RNTuple.

Parameters:

• path (str | Path) – File path

• tree_name (str) – Tree name

Returns:

Dictionary with comprehensive tree metadata

Return type:

dict[str, Any]

list_histograms(path)

List all histograms in a ROOT file.

Parameters:

path (str | Path) – File path

Returns:

List of histogram metadata dictionaries

Return type:

list[dict[str, Any]]

list_objects(path)

List all objects in a ROOT file.

Parameters:

path (str | Path) – File path

Returns:

List of object metadata dictionaries

Return type:

list[dict[str, Any]]

list_trees(path)

List all TTrees and RNTuples in a ROOT file.

Parameters:

path (str | Path) – File path

Returns:

List of tree metadata dictionaries

Return type:

list[dict[str, Any]]

open(path, **kwargs)

Open a ROOT file with caching.

Parameters:

• path (str | Path) – File path or URI

• **kwargs (Any) – Additional arguments to pass to uproot.open()

Returns:

Open uproot file object

Raises:

• FileNotFoundError – If file doesn’t exist

• OSError – If file cannot be opened

Return type:

Any

validate_file(path)

Validate ROOT file integrity and readability.

Parameters:

path (str | Path) – File path

Returns:

Dictionary with validation results

Return type:

dict[str, Any]

class root_mcp.core.io.HistogramReader(config, file_manager)

Bases: object

High-level interface for reading histograms.

Provides access to TH1, TH2, TH3, and TProfile objects.

Parameters:

• config (Config)

• file_manager (FileManager)

__init__(config, file_manager)

Initialize HistogramReader.

Parameters:

• config (Config) – Server configuration

• file_manager (FileManager) – File manager instance

read_histogram(path, hist_name)

Read a histogram from a ROOT file.

Parameters:

• path (str) – File path

• hist_name (str) – Histogram name or path

Returns:

Histogram data and metadata

Return type:

dict[str, Any]

class root_mcp.core.io.PathValidator(config)

Bases: object

Validates file paths against security constraints.

Parameters:

config (Config)

__init__(config)

Initialize validator with configuration.

Parameters:

config (Config) – Server configuration

check_file_pattern(path, resource)

Check if a file matches resource patterns.

Parameters:

• path (Path) – File path

• resource (ResourceConfig) – Resource configuration

Returns:

True if file matches allowed patterns and not excluded

Return type:

bool

validate_output_path(path)

Validate an output path for exports.

Parameters:

path (str) – Destination path for export

Returns:

Validated path

Raises:

SecurityError – If path is not allowed for output

Return type:

Path

validate_path(path, resource=None)

Validate a file path against security constraints.

Parameters:

• path (str) – File path or URI to validate

• resource (ResourceConfig | None) – Optional resource context

Returns:

Resolved, validated Path object

Raises:

SecurityError – If path violates security constraints

Return type:

Path

validate_write_operation(input_path, output_path, allow_overwrite=False)

Validate a write operation to ensure security constraints.

This method enforces critical security rules: 1. Input and output paths must be different 2. Output path must be in allowed output directory 3. Cannot overwrite existing files unless explicitly allowed

Parameters:

• input_path (str) – Source file path

• output_path (str) – Destination file path

• allow_overwrite (bool) – Whether to allow overwriting existing files

Returns:

Tuple of (validated_input_path, validated_output_path)

Raises:

SecurityError – If security constraints are violated

Return type:

tuple[Path, Path]

class root_mcp.core.io.TreeReader(config, file_manager)

Bases: object

High-level interface for reading TTree data.

Provides safe, efficient access to TTree branches with chunking, filtering, and pagination.

Parameters:

• config (Config)

• file_manager (FileManager)

__init__(config, file_manager)

Initialize TreeReader.

Parameters:

• config (Config) – Server configuration

• file_manager (FileManager) – File manager instance

compute_branch_stats(path, tree_name, branches, selection=None)

Compute statistics for branches.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• branches (list[str]) – Branches to analyze

• selection (str | None) – Optional cut expression

Returns:

Dictionary mapping branch names to statistics

Return type:

dict[str, dict[str, float]]

get_branch_info(path, tree_name, pattern=None)

Get information about branches in a tree.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• pattern (str | None) – Optional glob pattern to filter branches

Returns:

List of branch info dictionaries

Return type:

list[dict[str, Any]]

read_branches(path, tree_name, branches, selection=None, limit=None, offset=0, flatten=False, defines=None)

Read branch data from a TTree.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• branches (list[str]) – List of branch names to read (can include derived branches from defines)

• selection (str | None) – Optional ROOT-style cut expression

• limit (int | None) – Maximum number of entries to return

• offset (int) – Number of entries to skip

• flatten (bool) – Flatten jagged arrays

• defines (dict[str, str] | None) – Optional derived variable definitions {name: expression}

Returns:

Dictionary with data and metadata

Return type:

dict[str, Any]

sample_tree(path, tree_name, size=100, method='first', branches=None, seed=None)

Get a sample from a tree.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• size (int) – Sample size

• method (str) – “first” or “random”

• branches (list[str] | None) – Branches to include (None = all)

• seed (int | None) – Random seed for reproducibility

Returns:

Sample data and metadata

Return type:

dict[str, Any]

stream_branches(path, tree_name, branches, chunk_size=10000, selection=None)

Stream branch data in chunks for large files.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• branches (list[str]) – Branches to read

• chunk_size (int) – Number of entries per chunk

• selection (str | None) – Optional cut expression

Yields:

Chunks of data as awkward arrays

Submodules

• root_mcp.core.io.exporters module
  • DataExporter
    • DataExporter.__init__()
    • DataExporter.export()
    • DataExporter.export_to_csv()
    • DataExporter.export_to_json()
    • DataExporter.export_to_parquet()
• root_mcp.core.io.file_manager module
  • FileCache
    • FileCache.__init__()
    • FileCache.clear()
    • FileCache.get()
    • FileCache.put()
    • FileCache.size()
  • FileManager
    • FileManager.__init__()
    • FileManager.clear_cache()
    • FileManager.get_branch_schema()
    • FileManager.get_cache_stats()
    • FileManager.get_file_info()
    • FileManager.get_tree()
    • FileManager.get_tree_info()
    • FileManager.list_histograms()
    • FileManager.list_objects()
    • FileManager.list_trees()
    • FileManager.open()
    • FileManager.validate_file()
• root_mcp.core.io.readers module
  • HistogramReader
    • HistogramReader.__init__()
    • HistogramReader.read_histogram()
  • TreeReader
    • TreeReader.__init__()
    • TreeReader.compute_branch_stats()
    • TreeReader.get_branch_info()
    • TreeReader.read_branches()
    • TreeReader.sample_tree()
    • TreeReader.stream_branches()
• root_mcp.core.io.validators module
  • PathValidator
    • PathValidator.__init__()
    • PathValidator.check_file_pattern()
    • PathValidator.validate_output_path()
    • PathValidator.validate_path()
    • PathValidator.validate_write_operation()
  • SecurityError