# genilab-fau/owlmind architecture

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

- Interactive diagram: https://gitdiagram.com/genilab-fau/owlmind
- Repository: https://github.com/genilab-fau/owlmind

## Overview

##### Project Type and Purpose
- The project is a hybrid intelligence framework designed for education and experimentation. Its purpose is to support local AI solutions by combining rule-based inference with generative AI (GenAI) pipelines.
- It also supports building agentic systems (notably for Discord bots) using a Belief-Desire-Intention (BDI) model. The framework provides both rule-based and dynamic GenAI capabilities for flexible decision-making.

##### Analyzing the File Structure
- Key directories/files:
- Top-level files: README.md, INSTALLING.md, CONFIG.md, CONTRIBUTING.md, etc., indicate documented configuration and contribution processes.
- The “owlmind” package contains core modules like agent.py, bot.py, context.py, discord.py, pipeline.py, and simple.py. These represent the internal logic for agents, pipelines, and the interface with external platforms (e.g., Discord).
- Scripts like bot-1.py and rule CSV files (in the “rules” directory) denote sample bot implementations and system rules.
- The “tests” directory indicates unit tests targeting components like context and simple functionality.

##### Key Components
a. Main Components to include:
- Bot Runner for Discord Bots: Represented by bot-1.py and owlmind/discord.py. This handles the hosting and operation of interactive bots.
- Agentic Core: Found in files such as owlmind/agent.py and owlmind/context.py, which implement the BDI model (agent’s beliefs, desires, and intentions).
- Configurable GenAI Pipelines: Highlight owlmind/pipeline.py, which integrates GenAI model orchestration, and supports dynamically generated rules.
- Workflow Templates & Artifacts: Although not represented as separate directories, they are part of the framework’s modularity. They could be indicated as plugins or extension points supporting external APIs, databases, and other functionalities.
- Model Orchestrator: Can be considered an abstraction that manages the interactions between the GenAI pipelines and the agentic decision-making process.
- Supporting components like configuration files (.env_example, CONFIG.md) and rule files (CSV files in the “rules” directory) which feed into both rule-based and GenAI logic.

b. Relationships and Interactions:
- How external workflow templates and artifacts integrate into the pipelines and enable external functionalities.

c. Architectural Patterns and Principles:
- BDI cognitive architectural pattern in the agentic core.
- Hybrid approach where local rule inference and remote GenAI-driven mechanisms are used.
- The modular design (separation of Discord bot logic, agent processing, and pipeline configuration) is a key design principle.

d. Relevant Technologies, Frameworks, or Libraries:
- Python is the underlying language (as seen from *.py and pytest test scripts).
- Integration with external services like Discord (via the owlmind/discord.py module).
- The CSV-based rule mechanism suggests a straightforward, file-based rule configuration that feeds into the system.
- Testing and documentation frameworks are also indicated (pytest, docs).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Discord Client"]:::external
    B["Bot Runner (Discord Integration)"]:::service
    C["Agentic Core (BDI Model)"]:::core
    D["Rule-based Configuration (CSV Rules)"]:::core
    E["Model Orchestrator"]:::core
    F["GenAI Pipelines"]:::pipeline
    G["Workflow & Artifacts"]:::pipeline
    H["Configuration Management"]:::support
    I["Documentation"]:::support
    J["Testing Modules"]:::support

    %% Main Flow
    A -->|"request"| B
    B -->|"process"| C
    D -->|"feeds"| C
    C -->|"delegates"| E
    E <-->|"dynamicInteraction"| F
    F -->|"integratesWith"| G

    %% Supporting Infrastructure
    H ---|"suppliesConfig"| C
    I ---|"supports"| B
    I ---|"supports"| C
    J ---|"validates"| C

    %% Click Events
    click B "https://github.com/genilab-fau/owlmind/blob/main/bot-1.py"
    click B "https://github.com/genilab-fau/owlmind/blob/main/owlmind/discord.py"
    
    click C "https://github.com/genilab-fau/owlmind/blob/main/owlmind/agent.py"
    click C "https://github.com/genilab-fau/owlmind/blob/main/owlmind/context.py"
    
    click F "https://github.com/genilab-fau/owlmind/blob/main/owlmind/pipeline.py"
    
    click D "https://github.com/genilab-fau/owlmind/tree/main/rules"
    click D "https://github.com/genilab-fau/owlmind/blob/main/rules/bot-rules-1.csv"
    click D "https://github.com/genilab-fau/owlmind/blob/main/rules/bot-rules-2.csv"
    click D "https://github.com/genilab-fau/owlmind/blob/main/rules/bot-rules-3.csv"
    
    click H "https://github.com/genilab-fau/owlmind/blob/main/CONFIG.md"
    click H "https://github.com/genilab-fau/owlmind/blob/main/.env_example"
    
    click I "https://github.com/genilab-fau/owlmind/tree/main/docs"
    click I "https://github.com/genilab-fau/owlmind/blob/main/docs/bot-1.md"
    click I "https://github.com/genilab-fau/owlmind/blob/main/docs/discord.md"
    click I "https://github.com/genilab-fau/owlmind/tree/main/docs/images"
    
    click J "https://github.com/genilab-fau/owlmind/tree/main/tests"
    click J "https://github.com/genilab-fau/owlmind/blob/main/tests/unit/test_context.py"
    click J "https://github.com/genilab-fau/owlmind/blob/main/tests/unit/test_simple.py"
    click J "https://github.com/genilab-fau/owlmind/tree/main/tests/fixtures"

    %% Styles
    classDef external fill:#cfe2f3,stroke:#333,stroke-width:2px;
    classDef service fill:#f9cb9c,stroke:#333,stroke-width:2px;
    classDef core fill:#d9ead3,stroke:#333,stroke-width:2px;
    classDef pipeline fill:#ead1dc,stroke:#333,stroke-width:2px;
    classDef support fill:#fce5cd,stroke:#333,stroke-width:2px;
```
