# chrisgreg/hive architecture

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

- Interactive diagram: https://gitdiagram.com/chrisgreg/hive
- Repository: https://github.com/chrisgreg/hive

## Overview

##### Main Components

a) Core Framework Components:
- Hive Supervisor (top-level supervisor)
- Agent System (core agent functionality)
- Pipeline Worker (handles pipeline execution)
- Schema Management
- LLM Integration Layer

b) Agent Pipeline Components:
- Input/Output Schema Validation
- Agent Processing Logic
- LLM Router
- Error Handler
- Retry Mechanism

**[Hive.Supervisor]**

- [Pipeline Worker Pool]
- [Agent Registry]

**[Input] → [Schema Validation] → [Agent Processing] → [Output Validation] → [Next Agent/Complete]**

- [LLM Router]
- [Error Handler]

##### Specific Implementation Details

Key architectural elements:
**[Agent Definition]**

- Input Schema
- Output Schema
- Outcomes Configuration
- Task Handler

##### LLM Integration Flow
**[Agent] ⟶ [LLM Router] → [Schema Translator] → [LLM Provider] → [Response Parser] → [Next Agent]**

##### Important Notes

a) GenServer-based nature of agents:
- Message passing between components
- Supervision boundaries
- Stateful vs. stateless components

b) Configuration points:
- Retry mechanisms
- Logging levels
- LLM settings
- Pipeline tracking

c) Error handling paths:
- Retry loops
- Error escalation
- Recovery mechanisms

##### Additional Elements

- Component types
- Special symbols

##### Implementation Details

How the following key files interact:
- lib/hive/agent.ex (Agent behavior)
- lib/hive/llm/router.ex (LLM routing)
- lib/hive/schema.ex (Schema validation)
- lib/hive/supervisor.ex (Supervision)

Remember to include notes about:
- Pipeline ID propagation
- Retry behavior configuration
- LLM routing decisions
- Schema translation for LLM integration
- Error handling patterns

This will provide a complete picture of how Hive orchestrates autonomous agent pipelines while maintaining reliability and type safety.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef processing fill:#4CAF50,stroke:#2E7D32,color:white
    classDef validation fill:#FFC107,stroke:#FFA000,color:black
    classDef error fill:#F44336,stroke:#C62828,color:white
    classDef llm fill:#9C27B0,stroke:#6A1B9A,color:white
    classDef example fill:#78909C,stroke:#546E7A,color:white

    %% Main Components
    HiveSupervisor["Hive Supervisor"]:::core
    click HiveSupervisor "https://github.com/chrisgreg/hive/blob/main/lib/hive/supervisor.ex"
    
    AgentSystem["Agent System"]:::core
    click AgentSystem "https://github.com/chrisgreg/hive/blob/main/lib/hive/agent.ex"
    
    PipelineWorker["Pipeline Worker"]:::core
    click PipelineWorker "https://github.com/chrisgreg/hive/blob/main/lib/hive/pipeline_worker.ex"
    
    SchemaManagement["Schema Management"]:::core
    click SchemaManagement "https://github.com/chrisgreg/hive/blob/main/lib/hive/schema.ex"

    %% LLM Components
    LLMRouter["LLM Router"]:::llm
    click LLMRouter "https://github.com/chrisgreg/hive/blob/main/lib/hive/llm/router.ex"
    
    SchemaTranslator["Schema Translator"]:::llm
    click SchemaTranslator "https://github.com/chrisgreg/hive/blob/main/lib/hive/llm/schema_translator.ex"
    
    LLMProvider["LLM Provider"]:::llm
    ResponseParser["Response Parser"]:::llm

    %% Pipeline Components
    InputSchema["Input Schema"]:::validation
    OutputSchema["Output Schema"]:::validation
    ErrorHandler["Error Handler"]:::error
    click ErrorHandler "https://github.com/chrisgreg/hive/blob/main/lib/example/publishing_pipeline/error_handler.ex"

    %% Example Pipeline Implementation
    subgraph ExamplePipeline["Example Publishing Pipeline"]
        ContentGenerator["Content Generator"]:::example
        click ContentGenerator "https://github.com/chrisgreg/hive/blob/main/lib/example/publishing_pipeline/content_generator.ex"
        
        ContentRefiner["Content Refiner"]:::example
        click ContentRefiner "https://github.com/chrisgreg/hive/blob/main/lib/example/publishing_pipeline/content_refiner.ex"
        
        DuplicateChecker["Duplicate Checker"]:::example
        click DuplicateChecker "https://github.com/chrisgreg/hive/blob/main/lib/example/publishing_pipeline/duplicate_checker.ex"
        
        Publisher["Publisher"]:::example
        click Publisher "https://github.com/chrisgreg/hive/blob/main/lib/example/publishing_pipeline/publisher.ex"
    end
    click ExamplePipeline "https://github.com/chrisgreg/hive/tree/main/lib/example/publishing_pipeline/"

    %% Relationships
    HiveSupervisor --> AgentSystem
    HiveSupervisor --> PipelineWorker
    
    AgentSystem --> SchemaManagement
    AgentSystem --> LLMRouter
    
    LLMRouter --> SchemaTranslator
    SchemaTranslator --> LLMProvider
    LLMProvider --> ResponseParser
    
    PipelineWorker --> InputSchema
    PipelineWorker --> OutputSchema
    PipelineWorker --> ErrorHandler
    
    InputSchema --> ContentGenerator
    ContentGenerator --> ContentRefiner
    ContentRefiner --> DuplicateChecker
    DuplicateChecker --> Publisher
    
    ContentGenerator -.-> LLMRouter
    ContentRefiner -.-> LLMRouter
    
    %% Error Handling
    ContentGenerator -.-> ErrorHandler
    ContentRefiner -.-> ErrorHandler
    DuplicateChecker -.-> ErrorHandler
    Publisher -.-> ErrorHandler

    %% Legend
    subgraph Legend
        CoreComponent["Core Component"]:::core
        ProcessingComponent["Processing Component"]:::processing
        ValidationComponent["Validation Component"]:::validation
        ErrorComponent["Error Component"]:::error
        LLMComponent["LLM Component"]:::llm
        ExampleComponent["Example Component"]:::example
    end
```
