# prefecthq/marvin architecture

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

- Interactive diagram: https://gitdiagram.com/prefecthq/marvin
- Repository: https://github.com/prefecthq/marvin

## Overview

##### Main Components

a) Core Engine Layer:
- Orchestrator (src/marvin/engine/orchestrator.py)
- LLM Integration (src/marvin/engine/llm.py)
- Event System (src/marvin/engine/events.py)
- Handlers (src/marvin/engine/handlers.py)

b) Agent Layer:
- Agent System (src/marvin/agents/)
- Team Management (src/marvin/agents/team.py)
- Actor Implementation (src/marvin/agents/actor.py)

c) Task Management Layer:
- Task System (src/marvin/tasks/)
- Thread Management (src/marvin/thread.py)

d) Memory Layer:
- Memory System (src/marvin/memory/)
- Multiple Storage Providers:
- Chroma
- Lance
- Postgres

e) Functions Layer:
- High-level Functions (src/marvin/fns/):
- cast
- classify
- extract
- generate
- plan
- run
- say
- summarize

f) Tools Layer:
- Interactive Tools (src/marvin/tools/interactive/)
- Thread Tools (src/marvin/tools/thread.py)

**[Client Applications]**
- ↓
**[High-level Functions Layer]**
- ↓
**[Task & Thread Management]**
- ↓
**[Agent & Team Layer]**
- ↓
**[Core Engine Layer]**
- ↓
**[Memory Layer]**

##### Component Relationships

Following key interactions:
- Tasks are managed by the Orchestrator
- Agents interact with Tasks through the Engine
- Memory providers are accessed by both Tasks and Agents
- High-level functions utilize the Task system
- Tools can be accessed by Agents during task execution

##### Implementation Details

Use the following symbols and notations:
**[ Rectangle ] - Core components**
**( Oval ) - External services**
**<Diamond> - Decision points**
**→ - Data flow**
**⟷ - Bidirectional communication**

##### Additional Elements

Supporting components:
- Configuration management (settings.py)
- CLI interface (src/marvin/cli/)
- Utility functions (src/marvin/utilities/)
- Type system integration (pydantic models)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef core fill:#b3d9ff,stroke:#333,stroke-width:2px
    classDef agent fill:#90EE90,stroke:#333,stroke-width:2px
    classDef task fill:#FFE5B4,stroke:#333,stroke-width:2px
    classDef memory fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef function fill:#FFA07A,stroke:#333,stroke-width:2px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:2px
    classDef tools fill:#98FB98,stroke:#333,stroke-width:2px

    %% Client Applications Layer
    subgraph ClientApps["Client Applications"]
        CLI["CLI Interface"]:::external
        API["API Clients"]:::external
    end

    %% High-level Functions Layer
    subgraph Functions["High-level Functions"]
        Cast["Cast"]:::function
        Classify["Classify"]:::function
        Extract["Extract"]:::function
        Generate["Generate"]:::function
        Plan["Plan"]:::function
        Run["Run"]:::function
        Say["Say"]:::function
        Summarize["Summarize"]:::function
    end

    %% Task & Thread Management Layer
    subgraph TaskThread["Task & Thread Management"]
        TaskSystem["Task System"]:::task
        ThreadMgmt["Thread Management"]:::task
    end

    %% Agent Layer
    subgraph Agents["Agent & Team Layer"]
        AgentSystem["Agent System"]:::agent
        TeamMgmt["Team Management"]:::agent
        Actor["Actor Implementation"]:::agent
    end

    %% Core Engine Layer
    subgraph Engine["Core Engine"]
        Orchestrator["Orchestrator"]:::core
        LLM["LLM Integration"]:::core
        EventSystem["Event System"]:::core
        Handlers["Handlers"]:::core
    end

    %% Memory Layer
    subgraph Memory["Memory Layer"]
        MemorySystem["Memory System"]:::memory
        Chroma["Chroma Provider"]:::memory
        Lance["Lance Provider"]:::memory
        Postgres["Postgres Provider"]:::memory
    end

    %% Tools Layer
    subgraph Tools["Tools Layer"]
        InteractiveTools["Interactive Tools"]:::tools
        ThreadTools["Thread Tools"]:::tools
    end

    %% Relationships
    ClientApps --> Functions
    Functions --> TaskThread
    TaskThread --> Agents
    Agents --> Engine
    Engine --> Memory
    Tools --> Agents
    
    %% Click events
    click CLI "https://github.com/PrefectHQ/marvin/tree/main/src/marvin/cli/"
    click Cast "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/fns/cast.py"
    click Classify "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/fns/classify.py"
    click Extract "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/fns/extract.py"
    click Generate "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/fns/generate.py"
    click Plan "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/fns/plan.py"
    click Run "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/fns/run.py"
    click Say "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/fns/say.py"
    click Summarize "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/fns/summarize.py"
    click TaskSystem "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/tasks/task.py"
    click ThreadMgmt "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/thread.py"
    click AgentSystem "https://github.com/PrefectHQ/marvin/tree/main/src/marvin/agents/"
    click TeamMgmt "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/agents/team.py"
    click Actor "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/agents/actor.py"
    click Orchestrator "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/engine/orchestrator.py"
    click LLM "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/engine/llm.py"
    click EventSystem "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/engine/events.py"
    click Handlers "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/engine/handlers.py"
    click MemorySystem "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/memory/memory.py"
    click Chroma "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/memory/providers/chroma.py"
    click Lance "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/memory/providers/lance.py"
    click Postgres "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/memory/providers/postgres.py"
    click InteractiveTools "https://github.com/PrefectHQ/marvin/tree/main/src/marvin/tools/interactive/"
    click ThreadTools "https://github.com/PrefectHQ/marvin/blob/main/src/marvin/tools/thread.py"

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Agent Components"]:::agent
        L3["Task Components"]:::task
        L4["Memory Components"]:::memory
        L5["Function Components"]:::function
        L6["External Components"]:::external
        L7["Tools Components"]:::tools
    end
```
