haive.core.common.structures.tree

Automatic tree structure generator for Pydantic BaseModels with Union type support.

This module provides the AutoTree class that automatically wraps any BaseModel in a tree structure, handling complex type relationships including Union types. It enables hierarchical visualization and analysis of nested BaseModel structures.

The AutoTree automatically detects fields containing BaseModels (including those in Union types) and creates child tree nodes, making it perfect for visualizing complex data structures like plans with mixed content types.

Usage:

from pydantic import BaseModel, Field from typing import List, Union from haive.core.common.structures.tree import AutoTree

class Step(BaseModel):

name: str duration_hours: float = 1.0

class Plan(BaseModel):

name: str # Can contain either Steps OR other Plans items: List[Union[Step, ‘Plan’]] = Field(default_factory=list)

# Create nested structure main_plan = Plan(name=”Project Alpha”) main_plan.items.append(Step(name=”Setup”, duration_hours=2))

sub_plan = Plan(name=”Development Phase”) sub_plan.items.append(Step(name=”Code”, duration_hours=40)) main_plan.items.append(sub_plan)

# Visualize as tree tree = AutoTree(main_plan) print(tree.visualize())

Classes

AutoTree

Automatically wraps any BaseModel in a tree structure with Union type support.

Module Contents

class haive.core.common.structures.tree.AutoTree(content, parent=None, field_source=None, **kwargs)[source]

Bases: pydantic.BaseModel, Generic[T]

Automatically wraps any BaseModel in a tree structure with Union type support.

This generic class creates a tree representation of any BaseModel by automatically detecting fields that contain other BaseModels (including those in Union types) and creating child tree nodes for them.

The tree structure enables easy navigation, visualization, and analysis of complex nested data structures. It’s particularly useful for handling self-referential or polymorphic data structures.

content

The wrapped BaseModel instance.

_children

List of child AutoTree nodes.

_parent

Reference to parent AutoTree node (if any).

_field_source

Name of the field this node came from in its parent.

Parameters:

  • content (T) – The BaseModel instance to wrap in the tree.

  • parent (Optional[AutoTree]) – Optional parent AutoTree node.

  • field_source (str | None) – Optional name of the field this content came from.

Examples

>>> class Step(BaseModel):
...     name: str
>>> class Plan(BaseModel):
...     name: str
...     items: List[Union[Step, 'Plan']] = []
>>> plan = Plan(name="Main", items=[Step(name="Task1")])
>>> tree = AutoTree(plan)
>>> print(tree.visualize())

Init .

Parameters:

  • content (T) – [TODO: Add description]

  • parent (Optional[AutoTree]) – [TODO: Add description]

  • field_source (str | None) – [TODO: Add description]

visualize(show_field=True, show_type=True, max_depth=None)[source]

Generate a visual tree representation with customizable display options.

Creates a text-based tree visualization using Unicode box-drawing characters to show the hierarchical structure. The display can be customized to include or exclude field names, type information, and can be limited to a specific depth.

Parameters:

  • show_field (bool) – Whether to show the source field name for each node.

  • show_type (bool) – Whether to show the BaseModel class name for each node.

  • max_depth (int | None) – Maximum depth to display (None for unlimited).

Returns:

String representation of the tree structure with appropriate indentation and connectors.

Return type:

str

Example

>>> tree.visualize(show_field=True, show_type=True, max_depth=2)
'MainPlan <Plan>\\n├── [items] Setup <Step>\\n└── [items] Development <Plan>'
property children: list[AutoTree]

Get child trees.

Return type:

list[AutoTree]

property children_by_field: dict[str, list[AutoTree]]

Get children grouped by their source field.

Return type:

dict[str, list[AutoTree]]

property children_by_type: dict[str, list[AutoTree]]

Get children grouped by their type.

Return type:

dict[str, list[AutoTree]]

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property node_name: str

Get display name - tries common fields first.

Return type:

str

property node_type: str

Get the type name of the content.

Return type:

str