# teachable-ai-lab/pyhtn architecture

> Architecture diagram of the GitHub repository teachable-ai-lab/pyhtn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/teachable-ai-lab/pyhtn
- Repository: https://github.com/teachable-ai-lab/pyhtn

## Overview

##### Project Type and Purpose
- The project is an implementation of the SHOP2 hierarchical task network (HTN) planner in Python. Its main purpose is to take a planning domain (comprised of tasks, methods, operators, and facts) and, given an initial state, drive a planning process that iteratively suggests actions to be executed externally.
- The README and examples indicate that the system is both a planning engine (with a Horn clause inference engine) and a domain modeling tool (defining tasks, methods, operators, and facts).

##### Analyzing the Project File Structure
- Key top-level files include:
- run.py: Likely the entry point that initializes state, domain, and tasks, then invokes the planner.
- setup.py and setup.cfg: For packaging and installation.
- The main code lives under the “shop2” directory with the following important modules:
- shop2/domain.py: Contains definitions for Tasks, Methods, Operators, and Axioms (the domain description).
- shop2/fact.py: Implements the Fact notation for preconditions and state representation.
- shop2/planner.py: Implements the planning coroutine that drives the planning algorithm, handling state updates and requested actions.
- shop2/common.py: Provides common utilities such as variable (V) handling.
- shop2/condition_learning/: Contains modules for condition learning and refinement (including the decision tree implementation and tilde_essentials submodule) to assist in matching or optimizing planning conditions.
- shop2/utils.py: Likely includes utility functions to complement the main modules.

##### Main Components
a. Entry/Driver Component:
- run.py serves as the application’s driver. It sets up the initial state and domain and then invokes the planner.
b. Planner Module:
- shop2/planner.py: The core planning engine running as a coroutine (or in a separate process) that receives the state, domain, and tasks, and then iteratively suggests actions.
c. Domain Description and Modeling:
- shop2/domain.py, shop2/common.py, and shop2/fact.py: These modules define the tasks, methods (which decompose tasks using preconditions and subtasks), and operators (which have preconditions and effects). They also encapsulate the underlying Horn clause inference system used to match world states.
d. Condition Learning:
- shop2/condition_learning/ and its subdirectories, including “refactor” and “tilde_essentials”: This component includes decision-tree-based condition learners, evaluation, tree building, splitting criteria, leaf strategies, and more. Their purpose is to help refine or learn pattern-matching conditions from the domain descriptions.
e. Examples and Testing:
- The examples directory evidences sample usage scenarios. Even though not part of the production system, they help illustrate how to invoke and integrate the system components.

##### Relationships and Interactions
- The driver (run.py) initiates the process by setting up the initial state (using Facts) and building the domain (by aggregating Tasks, Methods, and Operators).
- The planner (in shop2/planner.py) receives inputs from the driver and then uses logic defined in domain.py and fact.py to infer valid operations.
- During planning, the planner interacts with the condition learning module when evaluating complex preconditions (such as through decision-tree based strategies) allowing dynamic adaptation.
- Methods and operators defined via the domain interact with the fact representations (from shop2/fact.py) and may use underlying utility functions provided in shop2/common.py and shop2/utils.py.
- Directional flows: The planner suggests actions (outputs) that the driver then interprets to update the world state and possibly feed those updates back into the planner.

##### Important Architectural Patterns and Design Principles
- Modularity: Each major feature (planning, domain definition, condition learning) is encapsulated in its own module.
- Separation of Concerns: Domain modeling (tasks, methods, operators) is kept distinct from the planning execution engine and the condition learning component.
- Decoupling via the HTN Pattern: The design clearly separates high-level planning (decomposition of tasks) from execution (operators and effects), consistent with hierarchical planning principles.
- Use of Logical Operators and Functional Programming: The system uses Horn clause logic, lambdas (for effects and filter functions), and logical operators for composing preconditions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Driver/Entry Point
    subgraph "Driver/Entry Point"
        R["run.py"]:::core
    end

    %% Planner Engine
    subgraph "Planner Engine"
        P["shop2/planner.py"]:::core
    end

    %% Domain Model & Fact System
    subgraph "Domain Model & Fact System"
        D1["shop2/domain.py"]:::domain
        D2["shop2/fact.py"]:::domain
        D3["shop2/common.py"]:::domain
    end

    %% Condition Learning Module
    subgraph "Condition Learning Module"
        CL["shop2/condition_learning/"]:::condition
        Ref["Refactor"]:::condition
        TE["Tilde Essentials"]:::condition
    end

    %% Support Components
    subgraph "Support Components"
        U["shop2/utils.py"]:::support
        E["Examples & Testing"]:::external
    end

    %% Relationships
    R -->|"sends_state/domain/tasks"| P
    P -->|"invokes_domain_logic"| D1
    D1 -->|"references"| D2
    D1 -->|"calls_utilities"| U
    P -->|"evaluates_conditions"| CL
    CL -->|"delegates"| Ref
    CL -->|"includes"| TE
    CL -->|"refines_decisions"| P
    P -->|"suggests_actions"| R
    E -->|"demonstrates_usage"| R

    %% Class Definitions for Colors
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef domain fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef condition fill:#F5CBA7,stroke:#943126,stroke-width:2px;
    classDef support fill:#ABEBC6,stroke:#1D8348,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;

    %% Click Events
    click R "https://github.com/teachable-ai-lab/pyhtn/blob/main/run.py"
    click P "https://github.com/teachable-ai-lab/pyhtn/blob/main/shop2/planner.py"
    click D1 "https://github.com/teachable-ai-lab/pyhtn/blob/main/shop2/domain.py"
    click D2 "https://github.com/teachable-ai-lab/pyhtn/blob/main/shop2/fact.py"
    click D3 "https://github.com/teachable-ai-lab/pyhtn/blob/main/shop2/common.py"
    click CL "https://github.com/teachable-ai-lab/pyhtn/tree/main/shop2/condition_learning/"
    click Ref "https://github.com/teachable-ai-lab/pyhtn/tree/main/shop2/condition_learning/refactor"
    click TE "https://github.com/teachable-ai-lab/pyhtn/tree/main/shop2/condition_learning/refactor/tilde_essentials"
    click U "https://github.com/teachable-ai-lab/pyhtn/blob/main/shop2/utils.py"
    click E "https://github.com/teachable-ai-lab/pyhtn/tree/main/examples/"
```
