# maximooch/penguin architecture

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

- Interactive diagram: https://gitdiagram.com/maximooch/penguin
- Repository: https://github.com/maximooch/penguin

## Overview

##### Main Components

a) Core System Components:
- CLI Interface Layer
- Agent System
- Chat Management
- LLM Integration Layer
- Memory Management
- Tool Management
- File System Interface

b) External Dependencies:
- LiteLLM API
- File System
- Virtual Environment

**User Interface Layer**
**↓**
**Core Processing Layer**
**↓**
**Service Layer**
**↓**
**External Services Layer**

##### Specific Component Relationships

a) User Interface → Core:
- How main.py interfaces with the agent system
- Demonstrate the chat flow through prompt_ui.py

b) Agent System:
- Relationship between task_manager, task_planner, and run_agent
- How automode.py fits into the workflow

c) Memory System:
- Different memory components (declarative_memory, context_window, summary_notes)
- How they interact with the core system

d) Tools System:
- Demonstrate how tool_manager.py orchestrates various tools
- Integration points for custom tools

##### Key Architectural Patterns to Highlight

- Modular Design: Show clear boundaries between components
- Plugin Architecture: Highlight the extensible tools system
- Memory Management: Illustrate the sophisticated memory hierarchy

##### Detailed Component Breakdown

**Module Name**

**Key Classes**

**Main Functions**

**Dependencies**

##### Implementation Notes

- Maintain consistent spacing and alignment
- Version information
- Notes for key configuration requirements

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Legend
        A[Regular Component]
        B[(Database)]
        C{{Processing Unit}}
        D[/Interface/]
        style A fill:#a8d1f0
        style B fill:#c297d8
        style C fill:#f7d794
        style D fill:#7bed9f
        class A core
        class B memory
        class C cognition
        class D interface
    end

    subgraph Core["Core System"]
        CoreSystem["Core Controller"]
        click CoreSystem "https://github.com/Maximooch/penguin/blob/main/penguin/core.py"
    end

    subgraph Memory["Memory System"]
        MemorySystem["Memory System"]
        ChromaDB[(ChromaDB)]
        ContextWindow["Context Window"]
        DeclarativeMemory["Declarative Memory"]
        SummaryMgmt["Summary Management"]
        
        click MemorySystem "https://github.com/Maximooch/penguin/blob/main/penguin/memory/memory_system.py"
        click ChromaDB "https://github.com/Maximooch/penguin/blob/main/penguin/memory/chroma_provider.py"
        click ContextWindow "https://github.com/Maximooch/penguin/blob/main/penguin/memory/context_window.py"
        click DeclarativeMemory "https://github.com/Maximooch/penguin/blob/main/penguin/memory/declarative_memory.py"
        click SummaryMgmt "https://github.com/Maximooch/penguin/blob/main/penguin/memory/summary_notes.py"
    end

    subgraph Cognition["Cognition System"]
        CognitionEngine{{Cognition Engine}}
        ResponseGen{{Response Generator}}
        
        click CognitionEngine "https://github.com/Maximooch/penguin/blob/main/penguin/cognition/cognition.py"
    end

    subgraph Tools["Tools System"]
        ToolManager["Tool Manager"]
        WebSearch["Web Search"]
        WorkspaceSearch["Workspace Search"]
        MemorySearch["Memory Search"]
        AutoControl["Autonomous Control"]
        
        click ToolManager "https://github.com/Maximooch/penguin/blob/main/penguin/tools/tool_manager.py"
        click WebSearch "https://github.com/Maximooch/penguin/blob/main/penguin/tools/web_search.py"
        click WorkspaceSearch "https://github.com/Maximooch/penguin/blob/main/penguin/tools/workspace_search.py"
        click MemorySearch "https://github.com/Maximooch/penguin/blob/main/penguin/tools/memory_search.py"
        click AutoControl "https://github.com/Maximooch/penguin/blob/main/penguin/tools/autonomous_control.py"
    end

    subgraph System["System Management"]
        ConversationMgr["Conversation Manager"]
        SessionHandler["Session Handler"]
        StateMgmt["State Management"]
        FileMgmt["File Management"]
        
        click ConversationMgr "https://github.com/Maximooch/penguin/blob/main/penguin/system/conversation_manager.py"
        click SessionHandler "https://github.com/Maximooch/penguin/blob/main/penguin/system/session.py"
        click StateMgmt "https://github.com/Maximooch/penguin/blob/main/penguin/system/state.py"
        click FileMgmt "https://github.com/Maximooch/penguin/blob/main/penguin/system/file_manager.py"
    end

    subgraph Interface["Interface Layer"]
        CLI[/CLI Interface/]
        WebUI[/Web Interface/]
        WSServer[/WebSocket Server/]
        
        click CLI "https://github.com/Maximooch/penguin/blob/main/penguin/chat/cli.py"
        click WebUI "https://github.com/Maximooch/penguin/blob/main/penguin/interfaces/web.py"
        click WSServer "https://github.com/Maximooch/penguin/blob/main/penguin/server/ws_server.py"
    end

    subgraph LLM["LLM Integration"]
        APIClient["API Client"]
        ModelConfig["Model Configuration"]
        ProviderAdapters["Provider Adapters"]
        StreamHandler["Stream Handler"]
        
        click APIClient "https://github.com/Maximooch/penguin/blob/main/penguin/llm/api_client.py"
        click ModelConfig "https://github.com/Maximooch/penguin/blob/main/penguin/llm/model_config.py"
        click ProviderAdapters "https://github.com/Maximooch/penguin/blob/main/penguin/llm/provider_adapters.py"
        click StreamHandler "https://github.com/Maximooch/penguin/blob/main/penguin/llm/stream_handler.py"
    end

    subgraph Utils["Utility Services"]
        ErrorHandler["Error Handling"]
        Diagnostics["Diagnostics"]
        Logging["Logging"]
        
        click ErrorHandler "https://github.com/Maximooch/penguin/blob/main/penguin/utils/errors.py"
        click Diagnostics "https://github.com/Maximooch/penguin/blob/main/penguin/utils/diagnostics.py"
        click Logging "https://github.com/Maximooch/penguin/blob/main/penguin/system/logging.py"
    end

    CoreSystem <--> CognitionEngine
    CoreSystem <--> MemorySystem
    CoreSystem <--> ToolManager
    CoreSystem <--> ConversationMgr
    CoreSystem <--> APIClient

    MemorySystem --> ChromaDB
    MemorySystem --> ContextWindow
    MemorySystem --> DeclarativeMemory
    MemorySystem --> SummaryMgmt

    CognitionEngine --> ResponseGen

    ToolManager --> WebSearch
    ToolManager --> WorkspaceSearch
    ToolManager --> MemorySearch
    ToolManager --> AutoControl

    ConversationMgr --> SessionHandler
    ConversationMgr --> StateMgmt
    ConversationMgr --> FileMgmt

    CLI --> CoreSystem
    WebUI --> CoreSystem
    WSServer --> CoreSystem

    APIClient --> ModelConfig
    APIClient --> ProviderAdapters
    APIClient --> StreamHandler

    ErrorHandler --> CoreSystem
    Diagnostics --> CoreSystem
    Logging --> CoreSystem

    classDef core fill:#a8d1f0
    classDef memory fill:#c297d8
    classDef cognition fill:#f7d794
    classDef tools fill:#f19066
    classDef system fill:#778beb
    classDef interface fill:#7bed9f
    classDef llm fill:#f8a5c2
    classDef utils fill:#c8d6e5

    class CoreSystem core
    class MemorySystem,ChromaDB,ContextWindow,DeclarativeMemory,SummaryMgmt memory
    class CognitionEngine,ResponseGen cognition
    class ToolManager,WebSearch,WorkspaceSearch,MemorySearch,AutoControl tools
    class ConversationMgr,SessionHandler,StateMgmt,FileMgmt system
    class CLI,WebUI,WSServer interface
    class APIClient,ModelConfig,ProviderAdapters,StreamHandler llm
    class ErrorHandler,Diagnostics,Logging utils
```
