# future-house/aviary architecture

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

- Interactive diagram: https://gitdiagram.com/future-house/aviary
- Repository: https://github.com/future-house/aviary

## Overview

##### Main Components

a) Core Framework Layer:
- Message System (src/aviary/message.py)
- Environment Core (src/aviary/env.py)
- Tool System (src/aviary/tools/)
- Functional Interface (src/aviary/functional.py)

b) Environment Implementation Layer:
- Base Environment Class
- Functional Environment Interface
- Environment Registry

c) Package Environments:
- GSM8k Environment
- HotPotQA Environment
- PaperQA Environment

d) Testing Infrastructure:
- Test Fixtures
- Cassettes for API Testing

**[Client Applications]**
- ↕
**[Environment Packages Layer]**
- ↕
**[Core Framework Layer]**
- ↕
**[External Dependencies/Services]**

##### Component Relationships

- Message flow between components
- Inheritance relationships for environments
- Tool registration and execution paths
- Dataset server interactions

##### Specific Elements

a) Core Framework Components:
**[Message System] ←→ [Environment Core]**
- ↕                    ↕
**[Tool System] ←→ [Functional Interface]**

b) Environment Implementation:
**[Base Environment]**
- ↙     ↓     ↘
**[GSM8k] [HotPotQA] [PaperQA]**

c) Tool System Detail:
**[Tool Registry]**
- ↓
**[Tool Definitions]**
- ↓
**[Tool Execution Engine]**

##### Important Implementation Details

- Async execution flow paths
- Message-based communication system
- Tool registration and discovery mechanism
- Environment state management
- Testing integration points

##### Technical Details to Emphasize

- Python 3.11+ requirement
- Pydantic model usage for state management
- Gymnasium compatibility
- Tool documentation and type hint system
- Dataset server architecture

Remember to include version compatibility notes and external dependency relationships, as these are critical for understanding the system's boundaries and requirements.

This system design should help developers understand both how to use the framework and how to extend it with new environments and tools.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client["Client Applications"]
        EnvClient["Environment Client"]
    end

    subgraph Environments["Environment Packages Layer"]
        BaseEnv["Base Environment"]
        GSM8k["GSM8k Environment"]
        HotPot["HotPotQA Environment"]
        PaperQA["PaperQA Environment"]
    end

    subgraph Core["Core Framework Layer"]
        Message["Message System"]
        EnvCore["Environment Core"]
        Tools["Tool System"]
        Functional["Functional Interface"]
        CoreImpl["Core Implementation"]
        DataServer["Dataset Server"]
    end

    subgraph Testing["Testing Infrastructure"]
        TestFix["Test Fixtures"]
        TestCass["Test Cassettes"]
        EnvTests["Environment Tests"]
        MsgTests["Message Tests"]
        ToolTests["Tools Tests"]
    end

    subgraph ToolSystem["Tool System Detail"]
        ToolBase["Tool Base"]
        ToolUtils["Tool Utilities"]
        ToolServer["Tool Server"]
    end

    %% Relationships
    EnvClient --> BaseEnv
    BaseEnv --> GSM8k
    BaseEnv --> HotPot
    BaseEnv --> PaperQA
    
    Message <--> EnvCore
    EnvCore <--> Tools
    Tools <--> Functional
    Message <--> Functional
    
    Tools --> ToolSystem
    CoreImpl --> Message
    CoreImpl --> EnvCore
    DataServer --> EnvCore
    
    Testing --> Core
    Testing --> Environments

    %% Click Events
    click EnvClient "https://github.com/Future-House/aviary/blob/main/src/aviary/env_client.py"
    click Message "https://github.com/Future-House/aviary/blob/main/src/aviary/message.py"
    click EnvCore "https://github.com/Future-House/aviary/blob/main/src/aviary/env.py"
    click Functional "https://github.com/Future-House/aviary/blob/main/src/aviary/functional.py"
    click CoreImpl "https://github.com/Future-House/aviary/blob/main/src/aviary/core.py"
    click DataServer "https://github.com/Future-House/aviary/blob/main/src/aviary/dataset_server.py"
    click GSM8k "https://github.com/Future-House/aviary/blob/main/packages/gsm8k/src/aviary/envs/gsm8k/env.py"
    click HotPot "https://github.com/Future-House/aviary/blob/main/packages/hotpotqa/src/aviary/envs/hotpotqa/env.py"
    click TestFix "https://github.com/Future-House/aviary/tree/main/tests/fixtures/"
    click TestCass "https://github.com/Future-House/aviary/tree/main/tests/cassettes/"
    click EnvTests "https://github.com/Future-House/aviary/blob/main/tests/test_envs.py"
    click MsgTests "https://github.com/Future-House/aviary/blob/main/tests/test_messages.py"
    click ToolTests "https://github.com/Future-House/aviary/blob/main/tests/test_tools.py"
    click ToolBase "https://github.com/Future-House/aviary/blob/main/src/aviary/tools/base.py"
    click ToolUtils "https://github.com/Future-House/aviary/blob/main/src/aviary/tools/utils.py"
    click ToolServer "https://github.com/Future-House/aviary/blob/main/src/aviary/tools/server.py"

    %% Styling
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px
    classDef core fill:#dae8fc,stroke:#6c8ebf
    classDef env fill:#d5e8d4,stroke:#82b366
    classDef tool fill:#fff2cc,stroke:#d6b656
    classDef test fill:#e1d5e7,stroke:#9673a6
    
    class Message,EnvCore,Tools,Functional,CoreImpl,DataServer core
    class BaseEnv,GSM8k,HotPot,PaperQA env
    class ToolBase,ToolUtils,ToolServer tool
    class TestFix,TestCass,EnvTests,MsgTests,ToolTests test
```
