haive.agents.common.models.task_analysis.base
=============================================

.. py:module:: haive.agents.common.models.task_analysis.base

.. autoapi-nested-parse::

   Base classes and enums for task complexity analysis.

   This module defines the fundamental building blocks for task complexity analysis
   including task representations, dependency types, and complexity classifications.



Classes
-------

.. autoapisummary::

   haive.agents.common.models.task_analysis.base.ComplexityLevel
   haive.agents.common.models.task_analysis.base.ComputationalComplexity
   haive.agents.common.models.task_analysis.base.DependencyNode
   haive.agents.common.models.task_analysis.base.DependencyType
   haive.agents.common.models.task_analysis.base.KnowledgeComplexity
   haive.agents.common.models.task_analysis.base.ResourceType
   haive.agents.common.models.task_analysis.base.SolvabilityStatus
   haive.agents.common.models.task_analysis.base.Task
   haive.agents.common.models.task_analysis.base.TaskStep
   haive.agents.common.models.task_analysis.base.TaskType
   haive.agents.common.models.task_analysis.base.TimeComplexity


Module Contents
---------------

.. py:class:: ComplexityLevel

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Overall complexity classification for tasks.

   .. attribute:: TRIVIAL

      Simple, single-step tasks (1-2 minutes)

   .. attribute:: SIMPLE

      Straightforward tasks with few steps (5-15 minutes)

   .. attribute:: MODERATE

      Multi-step tasks with some dependencies (30 minutes - 2 hours)

   .. attribute:: COMPLEX

      Involved tasks with multiple branches (2-8 hours)

   .. attribute:: COMPLICATED

      Sophisticated tasks requiring expertise (1-3 days)

   .. attribute:: EXPERT

      High-expertise tasks with uncertainty (weeks)

   .. attribute:: RESEARCH

      Unknown solution path, investigation required (months)

   .. attribute:: UNSOLVABLE

      Currently impossible or undefined problems

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


.. py:class:: ComputationalComplexity

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Computational complexity classifications.

   .. attribute:: CONSTANT

      O(1) - Fixed time regardless of input size

   .. attribute:: LOGARITHMIC

      O(log n) - Scales logarithmically with input

   .. attribute:: LINEAR

      O(n) - Scales linearly with input size

   .. attribute:: LINEARITHMIC

      O(n log n) - Common in efficient algorithms

   .. attribute:: QUADRATIC

      O(n²) - Scales quadratically

   .. attribute:: POLYNOMIAL

      O(n^k) - Polynomial time complexity

   .. attribute:: EXPONENTIAL

      O(2^n) - Exponential time complexity

   .. attribute:: UNKNOWN

      Complexity cannot be determined

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


.. py:class:: DependencyNode(/, **data)

   Bases: :py:obj:`pydantic.BaseModel`


   Represents a dependency relationship between tasks or steps.

   .. attribute:: source_id

      ID of the source task/step

   .. attribute:: target_id

      ID of the target task/step

   .. attribute:: dependency_type

      Type of dependency relationship

   .. attribute:: condition

      Optional condition for conditional dependencies

   .. attribute:: weight

      Strength/importance of the dependency (0.0 to 1.0)

   .. attribute:: description

      Human-readable description of the dependency

   .. rubric:: Example

   .. code-block:: python

       dependency = DependencyNode(
       source_id="lookup_winner",
       target_id="lookup_birthday",
       dependency_type=DependencyType.SEQUENTIAL,
       weight=1.0,
       description="Must know winner before looking up their birthday"
       )

   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.


   .. py:method:: allows_parallelization()

      Check if this dependency allows parallel execution.

      :returns: True if source and target can run in parallel



   .. py:method:: creates_join_point()

      Check if this dependency creates a join point.

      :returns: True if this is a join dependency



   .. py:method:: is_blocking()

      Check if this dependency creates a blocking relationship.

      :returns: True if the target cannot proceed without the source



.. py:class:: DependencyType

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Types of dependency relationships between tasks.

   .. attribute:: SEQUENTIAL

      Task B cannot start until Task A completes (A → B)

   .. attribute:: PARALLEL

      Tasks can execute simultaneously (A || B)

   .. attribute:: CONDITIONAL

      Task B only executes if Task A meets conditions (A ?→ B)

   .. attribute:: ITERATIVE

      Task B feeds back to Task A (A ↔ B)

   .. attribute:: JOIN

      Multiple tasks must complete before next task (A,B → C)

   .. attribute:: SPLIT

      One task creates multiple parallel branches (A → B,C)

   .. attribute:: OPTIONAL

      Task is optional based on conditions

   .. attribute:: ALTERNATIVE

      Either Task A or Task B, but not both (A ⊕ B)

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


.. py:class:: KnowledgeComplexity

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Knowledge complexity requirements.

   .. attribute:: BASIC

      General knowledge or simple lookup

   .. attribute:: INTERMEDIATE

      Domain-specific knowledge required

   .. attribute:: ADVANCED

      Deep expertise in specific domain

   .. attribute:: EXPERT

      Cutting-edge expertise, research-level knowledge

   .. attribute:: INTERDISCIPLINARY

      Knowledge across multiple domains

   .. attribute:: UNKNOWN

      Knowledge requirements unclear

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


.. py:class:: ResourceType

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Types of resources required for task execution.

   .. attribute:: HUMAN

      Human expertise or labor

   .. attribute:: COMPUTATIONAL

      Computing resources

   .. attribute:: DATA

      Access to specific datasets or information

   .. attribute:: TOOLS

      Specialized tools or software

   .. attribute:: FINANCIAL

      Monetary resources

   .. attribute:: TIME

      Significant time investment

   .. attribute:: NETWORK

      Network access or connectivity

   .. attribute:: STORAGE

      Data storage capabilities

   .. attribute:: EXPERTISE

      Specialized domain expertise

   .. attribute:: APPROVAL

      Authorization or approval from authorities

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


.. py:class:: SolvabilityStatus

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Current solvability status of a task.

   .. attribute:: TRIVIAL

      Task is trivially solvable with basic knowledge/tools

   .. attribute:: READY

      Task is immediately solvable with available resources

   .. attribute:: FEASIBLE

      Task is solvable with some effort or resource acquisition

   .. attribute:: CHALLENGING

      Task is solvable but requires significant effort

   .. attribute:: THEORETICAL

      Task is theoretically solvable but practically difficult

   .. attribute:: RESEARCH

      Task requires research or unknown solution paths

   .. attribute:: IMPOSSIBLE

      Task is currently impossible given constraints

   .. attribute:: UNDEFINED

      Solvability cannot be determined

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


.. py:class:: Task(/, **data)

   Bases: :py:obj:`pydantic.BaseModel`


   Represents a complex task that can contain subtasks and steps.

   This is the main building block for task complexity analysis.
   Tasks can contain either other Tasks or TaskSteps, creating a
   hierarchical structure that AutoTree can automatically handle.

   .. attribute:: name

      Descriptive name for the task

   .. attribute:: description

      Detailed description of the task

   .. attribute:: task_type

      Primary type of this task

   .. attribute:: subtasks

      List of subtasks and steps (Union type for AutoTree)

   .. attribute:: dependencies

      Dependency relationships

   .. attribute:: estimated_duration_minutes

      Total estimated duration

   .. attribute:: complexity_level

      Overall complexity assessment

   .. attribute:: required_resources

      Resources needed for the entire task

   .. attribute:: success_criteria

      How to measure successful completion

   .. rubric:: Example

   .. code-block:: python

       # Create a complex task with mixed subtasks and steps
       main_task = Task(
       name="Analyze Wimbledon Champion Age",
       description="Find recent champion, calculate age, and analyze",
       task_type=TaskType.RESEARCH,
       subtasks=[
       TaskStep(
       name="Find winner",
       description="Look up most recent Wimbledon champion",
       task_type=TaskType.FACTUAL
       ),
       Task(
       name="Age Analysis",
       description="Calculate and analyze age",
       task_type=TaskType.COMPUTATIONAL,
       subtasks=[
       TaskStep(name="Get birthday", ...),
       TaskStep(name="Calculate age", ...),
       TaskStep(name="Find square root", ...)
       ]
       )
       ]
       )

   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.


   .. py:method:: calculate_total_duration()

      Calculate total estimated duration for all subtasks.

      :returns: Total duration in minutes



   .. py:method:: create_auto_tree()

      Create an AutoTree representation of this task.

      :returns: AutoTree instance wrapping this task



   .. py:method:: get_all_steps()

      Get all TaskStep objects from the entire task hierarchy.

      :returns: Flattened list of all TaskStep objects



   .. py:method:: get_all_tasks()

      Get all Task objects from the hierarchy including self.

      :returns: List of all Task objects in the hierarchy



   .. py:method:: get_breadth()

      Get the breadth (number of direct subtasks) of this task.

      :returns: Number of direct subtasks



   .. py:method:: get_max_depth()

      Calculate the maximum depth of the task hierarchy.

      :returns: Maximum depth (0 for leaf tasks)



   .. py:method:: has_parallel_opportunities()

      Check if this task has opportunities for parallelization.

      :returns: True if some subtasks can potentially run in parallel



   .. py:attribute:: model_config

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


.. py:class:: TaskStep(/, **data)

   Bases: :py:obj:`pydantic.BaseModel`


   Individual executable step within a task.

   Represents an atomic unit of work that cannot be further decomposed
   in the current analysis context.

   .. attribute:: name

      Descriptive name for the step

   .. attribute:: description

      Detailed description of what the step involves

   .. attribute:: task_type

      The type of task this step represents

   .. attribute:: estimated_duration_minutes

      Estimated time to complete

   .. attribute:: required_resources

      Resources needed for this step

   .. attribute:: difficulty_level

      Subjective difficulty assessment

   .. attribute:: can_be_automated

      Whether this step can be automated

   .. attribute:: requires_human_judgment

      Whether human judgment is essential

   .. attribute:: dependencies

      IDs of other steps this depends on

   .. attribute:: outputs

      What this step produces

   .. rubric:: Example

   .. code-block:: python

       step = TaskStep(
       name="Look up Wimbledon winner",
       description="Search for the most recent Wimbledon men's singles champion",
       task_type=TaskType.FACTUAL,
       estimated_duration_minutes=5,
       required_resources=[ResourceType.NETWORK, ResourceType.DATA],
       can_be_automated=True
       )

   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.


   .. py:method:: get_complexity_score()

      Calculate a complexity score for this step.

      Combines duration, difficulty, and resource requirements.

      :returns: Complexity score (0.0 to 10.0)



   .. py:method:: get_duration_hours()

      Get estimated duration in hours.

      :returns: Duration in hours



   .. py:method:: is_blocking()

      Check if this step blocks other steps.

      :returns: True if other steps depend on this one



   .. py:attribute:: model_config

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


.. py:class:: TaskType

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Types of tasks based on their fundamental nature.

   .. attribute:: FACTUAL

      Tasks requiring factual information lookup

   .. attribute:: COMPUTATIONAL

      Tasks involving calculations or data processing

   .. attribute:: RESEARCH

      Tasks requiring investigation and analysis

   .. attribute:: CREATIVE

      Tasks involving creative or generative work

   .. attribute:: DECISION

      Tasks requiring decision-making or judgment

   .. attribute:: COORDINATION

      Tasks involving coordination between multiple entities

   .. attribute:: COMMUNICATION

      Tasks involving information exchange

   .. attribute:: VERIFICATION

      Tasks involving validation or checking

   .. attribute:: SYNTHESIS

      Tasks combining multiple inputs into new outputs

   .. attribute:: ITERATIVE

      Tasks that require multiple cycles or refinement

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


.. py:class:: TimeComplexity

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Time complexity categories for task completion.

   .. attribute:: INSTANT

      Less than 1 minute

   .. attribute:: QUICK

      1-10 minutes

   .. attribute:: SHORT

      10-60 minutes

   .. attribute:: MEDIUM

      1-8 hours

   .. attribute:: LONG

      1-7 days

   .. attribute:: EXTENDED

      1-4 weeks

   .. attribute:: PROJECT

      1-6 months

   .. attribute:: RESEARCH

      6+ months or unknown timeline

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