# yan25-06/project2_wumpus architecture

> Architecture diagram of the GitHub repository yan25-06/project2_wumpus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yan25-06/project2_wumpus
- Repository: https://github.com/yan25-06/project2_wumpus

## Overview

##### Project Type and Purpose
- This is a Python-based simulation/game framework implementing the “Wumpus World.”
- It provides both a command-line mode and a GUI mode for playing/testing agent behaviors (random, hybrid, etc.).
- Core functionality includes world/environment modeling, AI inference and planning, and a visual interface.

##### Top-Level Components
- wumpus/main.py            → entry point (CLI or GUI launcher)
- wumpus/config/settings.py → global configuration (game settings, scoring, orientations)
- wumpus/core/environment.py→ world model & state transitions
- wumpus/ai/*               → inference_engine, knowledge_base, planning_module, rules_parser
- wumpus/agents/*           → agent interface + implementations (random_agent, hybrid_agent)
- wumpus/GUI/*              → UI layers (setup_ui, draw_ui, game_board, button_functions)
- saved_envs/               → persisted probability maps and checkpoints (pickled)
- facts.txt, rules.txt      → domain definitions for inference engine
- tests/                    → unit tests for AI, agents, and models

##### Key Interactions and Data Flow
- User invokes `wumpus.main` → loads settings → chooses headless or GUI
- Main creates Environment instance (model) and Agent instance (controller)
- If GUI mode: setup_ui initializes windows → draw_ui renders board → button_functions dispatch user actions
- On each turn:
- Agent.request_percept() pulls sensor data from Environment
- Agent calls inference_engine & planning_module using knowledge_base & rules_parser
- Agent decides on next action → calls environment.act(action)
- Environment updates world state & returns new percepts
- UI listens for state changes, re-renders the board after each move
- saved_envs files are loaded by inference_engine or planning_module to bootstrap probabilities

##### Architectural Patterns & Principles
- MVC-style separation:
- Model = core/environment + saved_envs data
- View  = GUI modules
- Controller = main.py + agents + AI modules
- Plugin-style agents: agent.py defines interface, new agents can be added easily
- Data-driven rules: rules.txt & facts.txt parsed at runtime by rules_parser
- Single responsibility: each module focuses on one concern (UI, AI, config, core, agents)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point and Configuration
    Main["main.py\n(entry point)"]:::controller
    Settings["settings.py"]:::data
    Main --> Settings
    Main --> Env

    %% Core Model
    subgraph "wumpus.core" 
        direction TB
        Env["environment.py"]:::core
    end
    click Main "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/main.py"
    click Settings "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/config/settings.py"
    click Env "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/core/environment.py"

    %% Agents
    subgraph "wumpus.agents"
        direction TB
        AgentInt["agent.py"]:::ai
        RandAgent["random_agent.py"]:::ai
        HybridAgent["hybrid_agent.py"]:::ai
        AgentInt --> RandAgent
        AgentInt --> HybridAgent
    end
    click AgentInt "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/agents/agent.py"
    click RandAgent "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/agents/random_agent.py"
    click HybridAgent "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/agents/hybrid_agent.py"

    Main --> AgentInt

    %% AI Modules
    subgraph "wumpus.ai"
        direction TB
        RulesParser["rules_parser.py"]:::ai
        KnowledgeBase["knowledge_base.py"]:::ai
        InferenceEng["inference_engine.py"]:::ai
        PlanningMod["planning_module.py"]:::ai

        RulesParser --> KnowledgeBase
        KnowledgeBase --> InferenceEng
        InferenceEng --> PlanningMod
    end
    click RulesParser "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/ai/rules_parser.py"
    click KnowledgeBase "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/ai/knowledge_base.py"
    click InferenceEng "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/ai/inference_engine.py"
    click PlanningMod "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/ai/planning_module.py"

    AgentInt <--> RulesParser
    AgentInt <--> KnowledgeBase
    AgentInt <--> InferenceEng
    AgentInt <--> PlanningMod

    %% Data Stores
    Facts["facts.txt"]:::data
    Rules["rules.txt"]:::data
    SavedEnvs["saved_envs/*.pkl"]:::data

    RulesParser --> Facts
    RulesParser --> Rules
    InferenceEng --> SavedEnvs
    click Facts "https://github.com/yan25-06/project2_wumpus/blob/main/facts.txt"
    click Rules "https://github.com/yan25-06/project2_wumpus/blob/main/rules.txt"
    click SavedEnvs "https://github.com/yan25-06/project2_wumpus/blob/main/saved_envs/*.pkl"

    %% Execution Modes
    Main -->|"GUI mode"| GUISetup
    Main -->|"CLI mode"| CLI["CLI Interface"]:::controller

    %% GUI Layer
    subgraph "wumpus.GUI"
        direction TB
        GUISetup["setup_ui.py"]:::ui
        GUIDraw["draw_ui.py"]:::ui
        GameBoard["game_board.py"]:::ui
        GameBoardClean["game_board_clean.py"]:::ui
        ButtonFuncs["button_functions.py"]:::ui

        GUISetup --> GUIDraw
        GUIDraw --> GameBoard
        GUIDraw --> GameBoardClean
        GameBoard --> ButtonFuncs
    end
    click GUISetup "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/GUI/setup_ui.py"
    click GUIDraw "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/GUI/draw_ui.py"
    click GameBoard "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/GUI/game_board.py"
    click GameBoardClean "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/GUI/game_board_clean.py"
    click ButtonFuncs "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/GUI/button_functions.py"

    GUISetup --> Env
    GUISetup --> AgentInt
    ButtonFuncs --> AgentInt
    GUIDraw --> Env

    %% Interaction flows
    AgentInt -->|"act(action)"| Env
    Env -->|"percept(data)"| AgentInt

    %% Test Suite
    subgraph Tests
        direction TB
        TestInf["test_inference.py"]:::data
        TestHybrid["test_hybrid_agent.py"]:::data
        TestModel["test_model_prob.py"]:::data
    end
    click TestInf "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/test/test_inference.py"
    click TestHybrid "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/test/test_hybrid_agent.py"
    click TestModel "https://github.com/yan25-06/project2_wumpus/blob/main/wumpus/test/test_model_prob.py"

    TestInf --> InferenceEng
    TestHybrid --> HybridAgent
    TestModel --> Env

    %% Styles
    classDef core fill:#b6e3b6,stroke:#333,stroke-width:1px
    classDef ai fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef ui fill:#ffddb3,stroke:#333,stroke-width:1px
    classDef data fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef controller fill:#f5b7b1,stroke:#333,stroke-width:1px
```
