# brainlid/langchain architecture

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

- Interactive diagram: https://gitdiagram.com/brainlid/langchain
- Repository: https://github.com/brainlid/langchain

## Overview

##### Project type and purpose
- This is an Elixir library/framework (“LangChain”) for wiring together LLMs (large language models), tools, data sources and application logic into higher-level “chains.” It is not a stand-alone app but a collection of modules you pull into your Elixir project to build AI-powered workflows.

##### File structure
- Top-level: mix.exs, config/, lib/, notebooks/, test/
- lib/ splits into feature modules:
- LangChain.Chains (LLMChain, DataExtractionChain, RoutingChain, etc.)
- LangChain.ChatModels (ChatOpenAI, ChatAnthropic, ChatBumblebee, etc.)
- LangChain.Function (custom tool integration) + lib/tools (Calculator example)
- LangChain.Message & MessageProcessors (JSON decoding, deltas)
- LangChain.PromptTemplate
- LangChain.TextSplitter (various splitting strategies)
- LangChain.Images (generated/open_ai)
- LangChain.Utils (parsers, decoders, chain_result)
- Config and Telemetry modules
- notebooks/ show usage and demos, test/ exercises every module.

##### README insights
- Entry point: `LangChain.Chains.LLMChain`
- Supports many LLM services via modular adapters
- Key abstractions: Chains (higher-level workflows), Components (prompt templates, text splitters), ChatModels (adapters), Functions (tools), Message objects, Prompt caching, etc.

##### Main components & interactions
a. Components
- Your Elixir Application (uses LangChain)
- Public API layer: Chains (LLMChain, other off-the-shelf chains) + Function/Tool registration + PromptTemplate
- Core engine: builds Message structs, applies MessageProcessors, splits text, tracks TokenUsage, handles Telemetry
- Adapters: ChatModels modules (OpenAI, Anthropic, Google, Ollama, Bumblebee, Perplexity, etc.)
- External services/hosts: cloud APIs or self-hosted model servers
- Optional local Tools: LangChain.Function hooks (e.g., Calculator)
- Auxiliary modules: TextSplitter, Images, Utils, Config, Telemetry
b. Relationships & data flow
1. App calls `LLMChain.new!(opts) |> add_message(...) |> run()`
2. LLMChain composes a prompt via PromptTemplate, attaches context, tools
3. It serializes to JSON, hands off to a ChatModel adapter
4. Adapter invokes external service (Req HTTP client or Nx.Serving)
5. Streaming or batch response flows back through MessageProcessors
6. Library updates ChainResult, may invoke registered Functions (tool calls)
7. Final ChainResult returned to App
c. Architectural patterns
- Functional pipelines (|> syntax)
- Adapter pattern for ChatModels
- Strategy for splitting text (TextSplitter modules)
- Modular components (prompt templates, message processors, tools)
- Dependency injection of context and tools into chains
d. Technologies & libs
- Elixir/OTP modules
- Req for HTTP calls
- Nx & Bumblebee for self-hosted models
- JSON parsing / streaming via LangChain.MessageProcessors
- Telemetry for metrics

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Application Layer"
        App["Your Elixir Application"]:::app
    end

    subgraph "Public API Layer"
        subgraph "Chains"
            LLMChain["LangChain.Chains.LLMChain"]:::chains
            DataExtractionChain["LangChain.Chains.DataExtractionChain"]:::chains
            RoutingChain["LangChain.Chains.RoutingChain"]:::chains
            SummarizeConversationChain["LangChain.Chains.SummarizeConversationChain"]:::chains
            TextToTitleChain["LangChain.Chains.TextToTitleChain"]:::chains
            ChainCallbacks["Chain Callbacks"]:::chains
        end
        PromptTemplate["LangChain.PromptTemplate"]:::api
        FunctionLayer["LangChain.Function"]:::api
        Tools["Tools (Calculator)"]:::api
    end

    subgraph "Core Engine"
        Message["LangChain.Message"]:::core
        MessageProcessors["LangChain.MessageProcessors"]:::core
        TextSplitter["LangChain.TextSplitter"]:::core
        Utils["LangChain.Utils"]:::core
        Telemetry["Config & Telemetry"]:::core
        TokenUsage["LangChain.TokenUsage"]:::core
    end

    subgraph "Adapter Layer"
        ChatModelBase["LangChain.ChatModels.ChatModel"]:::adapter
        ChatOpenAI["LangChain.ChatModels.ChatOpenAI"]:::adapter
        ChatAnthropic["LangChain.ChatModels.ChatAnthropic"]:::adapter
        ChatBumblebee["LangChain.ChatModels.ChatBumblebee"]:::adapter
        ChatGoogleAI["LangChain.ChatModels.ChatGoogleAI"]:::adapter
        ChatMistralAI["LangChain.ChatModels.ChatMistralAI"]:::adapter
        ChatOllamaAI["LangChain.ChatModels.ChatOllamaAI"]:::adapter
        ChatPerplexity["LangChain.ChatModels.ChatPerplexity"]:::adapter
        ChatVertexAI["LangChain.ChatModels.ChatVertexAI"]:::adapter
    end

    subgraph "External Services"
        ExternalLLM["External LLM Services"]:::external
        SelfHosted["Self-Hosted Models (Nx/Bumblebee)"]:::external
    end

    %% Connections
    App -->|calls| LLMChain
    LLMChain -->|uses| PromptTemplate
    LLMChain -->|registers| FunctionLayer
    FunctionLayer -->|invokes| Tools
    LLMChain -->|builds| Message
    Message -->|processed by| MessageProcessors
    MessageProcessors -->|tracks| TokenUsage
    MessageProcessors -->|emits| Telemetry
    Message -->|splits| TextSplitter
    TextSplitter -->|uses| Utils
    LLMChain -->|delegates to| ChatModelBase
    ChatModelBase --> ChatOpenAI
    ChatModelBase --> ChatAnthropic
    ChatModelBase --> ChatBumblebee
    ChatModelBase --> ChatGoogleAI
    ChatModelBase --> ChatMistralAI
    ChatModelBase --> ChatOllamaAI
    ChatModelBase --> ChatPerplexity
    ChatModelBase --> ChatVertexAI
    ChatOpenAI -->|HTTP/Req| ExternalLLM
    ChatAnthropic -->|HTTP/Req| ExternalLLM
    ChatBumblebee -->|Nx.Serving| SelfHosted
    ChatGoogleAI -->|API| ExternalLLM
    ChatMistralAI -->|API| ExternalLLM
    ChatOllamaAI -->|API| SelfHosted
    ChatPerplexity -->|API| ExternalLLM
    ChatVertexAI -->|API| ExternalLLM
    ExternalLLM -->|response| ChatModelBase
    SelfHosted -->|response| ChatModelBase
    ChatModelBase -->|streams| MessageProcessors
    MessageProcessors -->|returns| LLMChain
    LLMChain -->|results| App

    %% Click Events
    click LLMChain "https://github.com/brainlid/langchain/blob/main/lib/chains/llm_chain.ex"
    click DataExtractionChain "https://github.com/brainlid/langchain/blob/main/lib/chains/data_extraction_chain.ex"
    click RoutingChain "https://github.com/brainlid/langchain/blob/main/lib/chains/routing_chain.ex"
    click SummarizeConversationChain "https://github.com/brainlid/langchain/blob/main/lib/chains/summarize_conversation_chain.ex"
    click TextToTitleChain "https://github.com/brainlid/langchain/blob/main/lib/chains/text_to_title_chain.ex"
    click ChainCallbacks "https://github.com/brainlid/langchain/blob/main/lib/chains/chain_callbacks.ex"
    click ChainCallbacks "https://github.com/brainlid/langchain/blob/main/lib/callbacks.ex"
    click ChatModelBase "https://github.com/brainlid/langchain/blob/main/lib/chat_models/chat_model.ex"
    click ChatOpenAI "https://github.com/brainlid/langchain/blob/main/lib/chat_models/chat_open_ai.ex"
    click ChatAnthropic "https://github.com/brainlid/langchain/blob/main/lib/chat_models/chat_anthropic.ex"
    click ChatBumblebee "https://github.com/brainlid/langchain/blob/main/lib/chat_models/chat_bumblebee.ex"
    click ChatGoogleAI "https://github.com/brainlid/langchain/blob/main/lib/chat_models/chat_google_ai.ex"
    click ChatMistralAI "https://github.com/brainlid/langchain/blob/main/lib/chat_models/chat_mistral_ai.ex"
    click ChatOllamaAI "https://github.com/brainlid/langchain/blob/main/lib/chat_models/chat_ollama_ai.ex"
    click ChatPerplexity "https://github.com/brainlid/langchain/blob/main/lib/chat_models/chat_perplexity.ex"
    click ChatVertexAI "https://github.com/brainlid/langchain/blob/main/lib/chat_models/chat_vertex_ai.ex"
    click FunctionLayer "https://github.com/brainlid/langchain/blob/main/lib/function.ex"
    click FunctionLayer "https://github.com/brainlid/langchain/blob/main/lib/function_param.ex"
    click Tools "https://github.com/brainlid/langchain/blob/main/lib/native_tool.ex"
    click Tools "https://github.com/brainlid/langchain/blob/main/lib/tools/calculator.ex"
    click Message "https://github.com/brainlid/langchain/blob/main/lib/message.ex"
    click MessageProcessors "https://github.com/brainlid/langchain/blob/main/lib/message_processors/json_processor.ex"
    click TextSplitter "https://github.com/brainlid/langchain/blob/main/lib/text_splitter.ex"
    click TextSplitter "https://github.com/brainlid/langchain/blob/main/lib/text_splitter/character_text_splitter.ex"
    click TextSplitter "https://github.com/brainlid/langchain/blob/main/lib/text_splitter/recursive_character_text_splitter.ex"
    click TextSplitter "https://github.com/brainlid/langchain/blob/main/lib/text_splitter/language_separators.ex"
    click PromptTemplate "https://github.com/brainlid/langchain/blob/main/lib/prompt_template.ex"
    click Utils "https://github.com/brainlid/langchain/blob/main/lib/utils.ex"
    click Utils "https://github.com/brainlid/langchain/blob/main/lib/utils/aws_eventstream_decoder.ex"
    click Utils "https://github.com/brainlid/langchain/blob/main/lib/utils/bedrock_config.ex"
    click Utils "https://github.com/brainlid/langchain/blob/main/lib/utils/bedrock_stream_decoder.ex"
    click Utils "https://github.com/brainlid/langchain/blob/main/lib/utils/chain_result.ex"
    click Utils "https://github.com/brainlid/langchain/blob/main/lib/utils/chat_templates.ex"
    click Utils "https://github.com/brainlid/langchain/blob/main/lib/utils/parser/llama3_1_custom_tool_parser.ex"
    click Utils "https://github.com/brainlid/langchain/blob/main/lib/utils/parser/llama3_2_custom_tool_parser.ex"
    click Telemetry "https://github.com/brainlid/langchain/blob/main/lib/config.ex"
    click Telemetry "https://github.com/brainlid/langchain/blob/main/lib/telemetry.ex"
    click TokenUsage "https://github.com/brainlid/langchain/blob/main/lib/token_usage.ex"

    %% Styles
    classDef app fill:#fdf,stroke:#333,stroke-width:1px
    classDef chains fill:#ccf,stroke:#333,stroke-width:1px
    classDef api fill:#cfc,stroke:#333,stroke-width:1px
    classDef core fill:#cff,stroke:#333,stroke-width:1px
    classDef adapter fill:#fc9,stroke:#333,stroke-width:1px
    classDef external fill:#f99,stroke:#333,stroke-width:1px
```
