agents.planning.base.models¶

Planning Base Models - Advanced planning system with generics, indexing, and intelligent tree structures.

This module provides a sophisticated planning framework with: - Maximum flexibility generics: Plan[Union[Step, Plan, Callable, str, Any]] - Intelligent tree traversal with cycle detection - Event-driven modifiable sequences with undo/redo - Auto-propagating status management - Smart field validation and auto-completion - Dynamic model adaptation based on content

Classes¶

`BasePlan`	Ultimate flexible plan supporting any content type with maximum intelligence.
`BaseStep`	Intelligent base step with adaptive behavior and smart validation.
`ChangeEvent`	Event representing a change in the planning structure.
`ConditionalPlan`	Conditional execution plan.
`EventEmitter`	Event system for tracking changes.
`FlexiblePlan`	Maximum flexibility plan - can contain anything.
`IntelligentSequence`	Advanced modifiable sequence with event system, undo/redo, and cycle detection.
`IntelligentStatusMixin`	Advanced mixin with intelligent status management and auto-adaptation.
`ParallelPlan`	Parallel execution plan.
`Priority`	Priority levels with critical and emergency levels.
`SequentialPlan`	Sequential execution plan.
`Task`	Ultimate task model with maximum intelligence and flexibility.
`TaskStatus`	Enhanced status enumeration with parallel execution support.
`TraversalMode`	Tree traversal patterns.

Module Contents¶

class agents.planning.base.models.BasePlan(**data)¶

Bases: IntelligentStatusMixin, Generic[T]

Ultimate flexible plan supporting any content type with maximum intelligence.

Init .

add_step(step)¶

Add any type of content as a step.

Parameters:: step (PlanContent)
Return type:: Self

add_steps(steps)¶

Add multiple steps.

Parameters:: steps (list[PlanContent])
Return type:: Self

async execute(mode=None)¶

Execute the plan using specified mode.

Parameters:: mode (str)
Return type:: dict[str, Any]

find_by_id(item_id)¶

Find any item by ID recursively.

Parameters:: item_id (str)
Return type:: Any | None

find_by_predicate(predicate)¶

Find all items matching predicate.

Parameters:: predicate (collections.abc.Callable[[Any], bool])
Return type:: list[Any]

get_statistics()¶

Get comprehensive plan statistics.

Return type:: dict[str, Any]

traverse(mode=TraversalMode.DEPTH_FIRST)¶

Traverse the plan tree using specified mode.

Parameters:: mode (TraversalMode)
Return type:: list[Any]

property completed_items: int¶

Count completed items recursively.

Return type:: int

property complexity_score: float¶

Calculate overall plan complexity.

Return type:: float

property next_executable_items: list[BaseStep | BasePlan]¶

Find all items ready for execution (supports parallel).

Return type:: list[BaseStep | BasePlan]

property progress_percentage: float¶

Intelligent progress calculation.

Return type:: float

property total_steps: int¶

Recursively count all executable items.

Return type:: int

class agents.planning.base.models.BaseStep(**data)¶

Bases: IntelligentStatusMixin

Intelligent base step with adaptive behavior and smart validation.

Init .

add_feedback(feedback, quality_score=None)¶

Add execution feedback.

Parameters:

feedback (str)
quality_score (float | None)

Return type:

Self

async execute()¶

Execute the step intelligently.

Return type:: Any

property complexity_score: float¶

Calculate complexity score based on various factors.

Return type:: float

property is_executable: bool¶

Intelligent executability check.

Return type:: bool

property readiness_score: float¶

Calculate how ready this step is for execution.

Return type:: float

class agents.planning.base.models.ChangeEvent(/, **data)¶

Bases: pydantic.BaseModel

Event representing a change in the planning structure.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

class agents.planning.base.models.ConditionalPlan¶

Bases: BasePlan[Union[BaseStep, BasePlan, collections.abc.Callable]]

Conditional execution plan.

class agents.planning.base.models.EventEmitter¶

Event system for tracking changes.

Init .

emit(event)¶

Emit an event.

Parameters:: event (ChangeEvent)

on(event_type, callback)¶

Parameters:

event_type (str)
callback (collections.abc.Callable)

class agents.planning.base.models.FlexiblePlan¶

Bases: BasePlan[PlanContent]

Maximum flexibility plan - can contain anything.

class agents.planning.base.models.IntelligentSequence(items=None, parent=None)¶

Bases: list[PlanContent], Generic[T]

Advanced modifiable sequence with event system, undo/redo, and cycle detection.

Init .

Parameters:

items (list[T]) – [TODO: Add description]
parent (BasePlan | None) – [TODO: Add description]

append(item)¶

Add item with undo support and events.

Parameters:: item (T)
Return type:: None

insert(index, item)¶

Insert item with undo support and events.

Parameters:

index (int)
item (T)

Return type:

None

pop(index=-1)¶

Pop item with undo support and events.

Parameters:: index (int)
Return type:: T

redo()¶

Redo last undone operation.

Return type:: bool

remove(item)¶

Remove item with undo support and events.

Parameters:: item (T)
Return type:: None

undo()¶

Undo last operation.

Return type:: bool

class agents.planning.base.models.IntelligentStatusMixin(**data)¶

Bases: pydantic.BaseModel, abc.ABC

Advanced mixin with intelligent status management and auto-adaptation.

Init .

update_status(new_status, propagate=True)¶

Update status with intelligent propagation.

Parameters:

new_status (TaskStatus)
propagate (bool)

Return type:

Self

class agents.planning.base.models.ParallelPlan¶

Bases: BasePlan[Union[BaseStep, BasePlan]]

Parallel execution plan.

class agents.planning.base.models.Priority¶

Bases: str, enum.Enum

Priority levels with critical and emergency levels.

Initialize self. See help(type(self)) for accurate signature.

class agents.planning.base.models.SequentialPlan¶

Bases: BasePlan[Union[BaseStep, BasePlan]]

Sequential execution plan.

class agents.planning.base.models.Task(**data)¶

Bases: IntelligentStatusMixin

Ultimate task model with maximum intelligence and flexibility.

Init .

activate_plan(plan)¶

Intelligently activate a plan.

Parameters:: plan (BasePlan)
Return type:: Self

add_contingency(plan, trigger_condition)¶

Add contingency plan with trigger condition.

Parameters:

plan (BasePlan)
trigger_condition (str)

Return type:

Self

async execute()¶

Execute the primary plan intelligently.

Return type:: dict[str, Any]

get_comprehensive_status()¶

Get comprehensive status across all plans.

Return type:: dict[str, Any]

property is_complete: bool¶

Intelligent completion check.

Return type:: bool

property overall_complexity: float¶

Calculate overall task complexity.

Return type:: float

property overall_progress: float¶

Calculate progress across all active plans.

Return type:: float

class agents.planning.base.models.TaskStatus¶

Bases: str, enum.Enum

Enhanced status enumeration with parallel execution support.

Initialize self. See help(type(self)) for accurate signature.

class agents.planning.base.models.TraversalMode¶

Bases: str, enum.Enum

Tree traversal patterns.

Initialize self. See help(type(self)) for accurate signature.