# instruct-rb/instruct architecture

> Architecture diagram of the GitHub repository instruct-rb/instruct, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/instruct-rb/instruct
- Repository: https://github.com/instruct-rb/instruct

## Overview

##### Main Components

a) Core Components:
- Prompt Management System
- Generation System
- Middleware Chain
- LLM Provider Adapters
- Rails Integration Layer

b) External Components:
- OpenAI API
- Anthropic API
- Rails Framework (optional integration)

**┌─ Application Layer ─────────────────────────────────────┐**

- User Code / Rails Applications                     │

- Public API Layer ──────────────────────────────────── │

- Core Processing Layer ────────────────────────────────│

- ┌─ Prompt System ─┐   ┌─ Generation System ─┐        │

- ERB Compiler  │   │ - Completion Request │        │
- Safety Marking│   │ - Response Handling  │        │
- ┘   └──────────────────────┘        │

- Middleware Chain ───────────────────────────────────┐ │

- Chat Completion → Chomp → Custom Middleware → ...   │ │

- Provider Adapters ─────────────────────────────────┐ │

- OpenAI Adapter         Anthropic Adapter         │ │

- ┘

- ▼                           ▼
**OpenAI API                 Anthropic API**

##### Key Elements to Highlight

a) Data Flow:

- Blue: Core components
- Green: External services
- Yellow: Middleware components
- Purple: Integration points
- Gray: Optional components

##### Important Architectural Patterns

a) Middleware Chain Pattern:
- How middleware components can be chained
- Order of middleware execution
- How middleware can transform both requests and responses

b) Provider Adapter Pattern:
- How different LLM providers are abstracted
- Standardized interface they implement
- Provider-specific middleware

c) Rails Integration:
- Optional Rails components
- Serialization paths
- ActiveJob integration points

##### Additional Details

- The different types of components
- Common middleware configurations

##### Implementation Notes

- The separation between prompt management and generation
- The flexibility of the middleware system
- The safety mechanisms for prompt handling
- The streaming capability throughout the stack

##### Specific Features to Highlight

- ERB-based prompt templating
- Safe/unsafe content handling
- Completion capture mechanism
- Streaming support
- Serialization capabilities
- Rails integration points

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Application Layer"
        UserCode["User Code / Rails Applications"]
    end

    subgraph "Public API Layer"
        Helpers["Instruct::Helpers"]:::api
        click Helpers "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/helpers/helpers.rb"
        GenHelper["Gen Helper"]:::api
        click GenHelper "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/helpers/gen_helper.rb"
        ERBHelper["ERB Helper"]:::api
        click ERBHelper "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/helpers/erb_helper.rb"
        ModelHelper["Model Helper"]:::api
        click ModelHelper "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/helpers/model_helper.rb"
    end

    subgraph "Core Processing Layer"
        subgraph "Prompt System"
            Prompt["Prompt Management"]:::core
            click Prompt "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/prompt.rb"
            ERBCompiler["ERB Compiler"]:::core
            click ERBCompiler "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/compile_erb.rb"
            SafetyMarking["Safety Marking"]:::core
        end

        subgraph "Generation System"
            CompletionRequest["Completion Request"]:::core
            click CompletionRequest "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/gen/completion_request.rb"
            CompletionResponse["Response Handling"]:::core
            click CompletionResponse "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/gen/completion_response.rb"
            GenerateCompletion["Generate Completion"]:::core
            click GenerateCompletion "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/gen/generate_completion.rb"
        end
    end

    subgraph "Middleware Chain"
        MiddlewareChain["Middleware Chain"]:::middleware
        click MiddlewareChain "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/utils/middleware_chain.rb"
        ChatCompletion["Chat Completion"]:::middleware
        click ChatCompletion "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/middleware/chat_completion_middleware.rb"
        Chomp["Chomp"]:::middleware
        click Chomp "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/middleware/chomp_middleware.rb"
        CustomMiddleware["Custom Middleware"]:::middleware
    end

    subgraph "Provider Adapters"
        OpenAIAdapter["OpenAI Adapter"]:::adapter
        click OpenAIAdapter "https://github.com/instruct-rb/instruct/tree/development/lib/instruct/llms/openai"
        AnthropicAdapter["Anthropic Adapter"]:::adapter
        click AnthropicAdapter "https://github.com/instruct-rb/instruct/tree/development/lib/instruct/llms/anthropic"
    end

    subgraph "Rails Integration"
        ActiveJob["ActiveJob Serializer"]:::rails
        click ActiveJob "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/rails/active_job_object_serializer.rb"
        ActiveRecord["ActiveRecord Coders"]:::rails
        click ActiveRecord "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/rails/active_record_coders.rb"
        Railtie["Railtie"]:::rails
        click Railtie "https://github.com/instruct-rb/instruct/blob/development/lib/instruct/railtie.rb"
    end

    subgraph "External Services"
        OpenAIAPI["OpenAI API"]:::external
        AnthropicAPI["Anthropic API"]:::external
    end

    %% Connections
    UserCode --> Helpers
    Helpers --> GenHelper & ERBHelper & ModelHelper
    GenHelper & ERBHelper & ModelHelper --> Prompt
    Prompt --> ERBCompiler
    ERBCompiler --> SafetyMarking
    SafetyMarking --> CompletionRequest
    CompletionRequest --> GenerateCompletion
    GenerateCompletion --> CompletionResponse
    CompletionResponse --> MiddlewareChain
    MiddlewareChain --> ChatCompletion --> Chomp --> CustomMiddleware
    CustomMiddleware --> OpenAIAdapter & AnthropicAdapter
    OpenAIAdapter --> OpenAIAPI
    AnthropicAdapter --> AnthropicAPI
    UserCode -.-> ActiveJob & ActiveRecord & Railtie

    %% Styles
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef api fill:#9C27B0,stroke:#7B1FA2,color:white
    classDef middleware fill:#FFC107,stroke:#FFA000,color:black
    classDef adapter fill:#4CAF50,stroke:#388E3C,color:white
    classDef external fill:#607D8B,stroke:#455A64,color:white
    classDef rails fill:#E91E63,stroke:#C2185B,color:white

    %% Legend
    subgraph Legend
        CoreComponent["Core Component"]:::core
        APIComponent["API Component"]:::api
        MiddlewareComponent["Middleware Component"]:::middleware
        AdapterComponent["Adapter Component"]:::adapter
        ExternalComponent["External Service"]:::external
        RailsComponent["Rails Integration"]:::rails
    end
```
