hoops_ai.storage.datasetstorage.schema_builder

Quick Overview

Classes

Group(name, primary_dimension[, ...])

Represents a group in a schema with arrays.

SchemaBuilder([domain, version, description])

Standard API builder for creating data storage schemas.

Functions

create_cad_schema()

Create a schema builder pre-configured for CAD analysis.

create_custom_schema(domain)

Create a blank schema builder for custom domains.

create_manufacturing_schema()

Create a schema builder pre-configured for manufacturing data.

create_sensor_schema()

Create a schema builder pre-configured for sensor data.

SchemaBuilder: User-friendly interface for creating data storage schemas.

This module provides a standard, explicit API for building schemas without requiring method chaining. It uses a clear object-oriented approach where groups and arrays are created explicitly.

class hoops_ai.storage.datasetstorage.schema_builder.Group(name, primary_dimension, description=None, special_processing=None)

Bases: object

Represents a group in a schema with arrays.

Parameters:

  • name (str)

  • primary_dimension (str)

  • description (str | None)

  • special_processing (str | None)

create_array(name, dimensions, dtype='float32', description=None, **validation_rules)

Create an array in this group.

Parameters:

  • name (str) – Name of the array

  • dimensions (List[str]) – List of dimension names (e.g., [‘face’, ‘coordinate’])

  • dtype (str) – Data type (default: ‘float32’)

  • description (str | None) – Optional description of the array

  • **validation_rules – Additional validation rules (min_value, max_value, etc.)

Return type:

None

Example:

group.create_array('face_areas', ['face'], 'float32', 'Surface area of each face')
group.create_array('face_normals', ['face', 'coordinate'], 'float32', 'Normal vectors')
get_array(name)

Get array specification by name.

Parameters:

name (str)

Return type:

Dict[str, Any] | None

get_arrays()

Get all arrays in this group.

Return type:

Dict[str, Dict[str, Any]]

list_arrays()

Get list of all array names in this group.

Return type:

List[str]

remove_array(name)

Remove an array from this group.

Parameters:

name (str) – Name of the array to remove

Returns:

True if array was removed, False if not found

Return type:

bool

to_dict()

Convert this group to a dictionary representation.

Return type:

Dict[str, Any]

class hoops_ai.storage.datasetstorage.schema_builder.SchemaBuilder(domain='generic_data', version='1.0', description=None)

Bases: object

Standard API builder for creating data storage schemas.

This class provides a clear, explicit interface for building schemas using a traditional object-oriented approach without method chaining.

Example:

builder = SchemaBuilder(domain='CAD_analysis', version='1.0')

# Create groups
faces_group = builder.create_group('faces', 'face', 'Face geometric data')
edges_group = builder.create_group('edges', 'edge', 'Edge geometric data')

# Create arrays in groups
faces_group.create_array('face_areas', ['face'], 'float32', 'Surface area of each face')
faces_group.create_array('face_normals', ['face', 'coordinate'], 'float32', 'Normal vectors')

edges_group.create_array('edge_lengths', ['edge'], 'float32', 'Length of each edge')

# Build the final schema
schema = builder.build()
Parameters:

  • domain (str)

  • version (str)

  • description (str | None)

build()

Build the final schema dictionary.

Returns:

Complete schema dictionary

Return type:

Dict[str, Any]

Raises:

ValueError – If schema validation fails

copy()

Create a copy of this schema builder.

Returns:

A copy of this builder

Return type:

SchemaBuilder

create_group(name, primary_dimension, description=None, special_processing=None)

Create a new group in the schema.

Parameters:

  • name (str) – Name of the group

  • primary_dimension (str) – Primary dimension for this group

  • description (str | None) – Optional description of the group

  • special_processing (str | None) – Optional special processing type

Returns:

The created group object

Return type:

Group

Example:

faces_group = builder.create_group('faces', 'face', 'Face-related data')
define_categorical_metadata(name, dtype='str', description=None, values=None, labels=None, required=False, **validation_rules)

Define categorical metadata that goes to .attribset files.

Parameters:

  • name (str) – Name of the metadata field

  • dtype (str) – Data type (str, int32, int64, float32, float64, bool)

  • description (str | None) – Optional description of the metadata

  • values (List[Any] | None) – List of allowed values for this category

  • labels (List[str] | None) – List of human-readable labels corresponding to values

  • required (bool) – Whether this metadata is required

  • **validation_rules – Additional validation rules

Return type:

None

Example:

builder.define_categorical_metadata('machining_category', 'int32',
    'Machining complexity', values=[1,2,3,4,5],
    labels=['Simple', 'Easy', 'Medium', 'Hard', 'Complex'])
define_file_metadata(name, dtype='str', description=None, required=False, **validation_rules)

Define file-level metadata that goes to .infoset files.

Parameters:

  • name (str) – Name of the metadata field

  • dtype (str) – Data type (str, int32, int64, float32, float64, bool)

  • description (str | None) – Optional description of the metadata

  • required (bool) – Whether this metadata is required

  • **validation_rules – Additional validation rules

Return type:

None

Example:

builder.define_file_metadata('size_cadfile', 'int64', 'File size in bytes')
builder.define_file_metadata('processing_time', 'float32', 'Processing time in seconds')
extend_template(template_name)

Extend the current schema with data from a template.

Parameters:

template_name (str) – Name of the template to extend with

Returns:

Self for continued configuration

Return type:

SchemaBuilder

classmethod from_dict(schema_dict)

Create a schema builder from a dictionary.

Parameters:

schema_dict (Dict[str, Any]) – Dictionary containing schema definition

Returns:

New builder with loaded schema

Return type:

SchemaBuilder

from_template(template_name)

Initialize the schema from a predefined template.

Parameters:

template_name (str) – Name of the template to use

Returns:

Self for continued configuration

Return type:

SchemaBuilder

get_group(name)

Get an existing group by name.

Parameters:

name (str) – Name of the group to retrieve

Returns:

The group object or None if not found

Return type:

Group

get_metadata(key)

Get metadata value by key.

Parameters:

key (str)

Return type:

Any

get_metadata_routing(metadata_name)

Get the routing destination for a metadata field using patterns and explicit definitions.

Parameters:

metadata_name (str) – Name of the metadata field

Returns:

“file_level” or “categorical”, or None if not found

Return type:

str

list_categorical_metadata_fields()

Get list of defined categorical metadata fields.

Return type:

List[str]

list_file_metadata_fields()

Get list of defined file-level metadata fields.

Return type:

List[str]

list_groups()

Get a list of all group names in the schema.

Return type:

List[str]

list_metadata_fields()

Get all defined metadata fields grouped by destination.

Returns:

Dict containing ‘file_level’ and ‘categorical’ lists

Return type:

Dict[str, List[str]]

classmethod load_from_file(file_path)

Load a schema from a JSON file.

Parameters:

file_path (str | Path) – Path to the schema file

Returns:

Loaded schema builder

Return type:

SchemaBuilder

remove_group(name)

Remove a group from the schema.

Parameters:

name (str) – Name of the group to remove

Returns:

True if group was removed, False if not found

Return type:

bool

route_metadata_field(field_name, value)

Route a metadata field to its destination using schema rules.

Parameters:

  • field_name (str) – Name of the metadata field

  • value (Any) – Value of the metadata field

Returns:

“file_level” or “categorical”

Return type:

str

save_to_file(file_path)

Save the schema to a JSON file.

Parameters:

file_path (str | Path) – Path where to save the schema file

Return type:

None

set_metadata(key, value)

Set metadata for the schema.

Parameters:

  • key (str) – Metadata key

  • value (Any) – Metadata value

Return type:

None

set_metadata_routing_rules(file_level_patterns=None, categorical_patterns=None, default_numeric='file_level', default_categorical='categorical', default_string='categorical')

Set routing rules for metadata fields with pattern-based and default routing.

Parameters:

  • file_level_patterns (List[str] | None) – Patterns for fields that should go to file-level (.infoset)

  • categorical_patterns (List[str] | None) – Patterns for fields that should go to categorical (.attribset)

  • default_numeric (str) – Where to route numeric metadata by default

  • default_categorical (str) – Where to route categorical metadata by default

  • default_string (str) – Where to route string metadata by default

Return type:

None

Pattern examples:

file_level_patterns=['description', 'flow_name', 'stream *', 'Item']
categorical_patterns=['category', 'type', 'material_*', 'complexity']
to_json(indent=2)

Convert the schema to JSON string.

Parameters:

indent (int) – JSON indentation level

Returns:

JSON representation of the schema

Return type:

str

validate()

Validate the current schema configuration.

Returns:

List of validation errors (empty if valid)

Return type:

List[str]

validate_metadata_field(field_name, value)

Validate a metadata field value against its defined type.

Parameters:

  • field_name (str) – Name of the metadata field

  • value (Any) – Value to validate

Returns:

True if valid, False otherwise

Return type:

bool

validate_metadata_schema()

Validate the metadata schema configuration.

Returns:

List of validation errors (empty if valid)

Return type:

List[str]

hoops_ai.storage.datasetstorage.schema_builder.create_cad_schema()

Create a schema builder pre-configured for CAD analysis.

Return type:

SchemaBuilder

hoops_ai.storage.datasetstorage.schema_builder.create_custom_schema(domain)

Create a blank schema builder for custom domains.

Parameters:

domain (str) – Domain name for the custom schema

Returns:

Empty builder configured for the domain

Return type:

SchemaBuilder

hoops_ai.storage.datasetstorage.schema_builder.create_manufacturing_schema()

Create a schema builder pre-configured for manufacturing data.

Return type:

SchemaBuilder

hoops_ai.storage.datasetstorage.schema_builder.create_sensor_schema()

Create a schema builder pre-configured for sensor data.

Return type:

SchemaBuilder