Docs / Core Concepts / Architecture & Purity

Architecture & Purity

The 3-tier monorepo architecture, effect polymorphism, and pure functional guarantees.

Monorepo Architecture

langchain-hs is split into decoupled, modular packages so applications remain lightweight and only depend on the providers and protocols they actually invoke:

┌─────────────────────────────────────────────────────────────┐
│  Provider & Protocol Satellite Packages                     │
│  langchain-hs-ollama · langchain-hs-openai                  │
│  langchain-hs-gemini · langchain-hs-mcp                     │
└──────────────────────────────┬──────────────────────────────┘
                               │ depends directly on
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                    langchain-hs-core                        │
│  Core Primitives & Framework:                               │
│  RunnableTree · ChatModel · Tool m · Agents (ReAct, P&E)    │
│  RetrievalQA · VectorStore · BM25 & Hybrid Retriever        │
│  Memory · Cache · Parsers · Guardrails · Resilience · OTel  │
└──────────────────────────────▲──────────────────────────────┘
                               │ extends
┌──────────────────────────────┴──────────────────────────────┐
│                    langchain-hs-graph                       │
│  StateGraph s m · StateReducer s · Checkpointers · HITL     │
│  TimeTravel · SubGraphs · Runnable Nodes · DOT Export       │
└──────────────────────────────▲──────────────────────────────┘
                               │ re-exported by
┌──────────────────────────────┴──────────────────────────────┐
│                       langchain-hs                          │
│  Umbrella Package: re-exports langchain-hs-core + graph     │
└─────────────────────────────────────────────────────────────┘

1. Pure Functional Effect Management

In many imperative AI frameworks, state mutation, network I/O, and tool executions are side-effecting operations scattered throughout code. In langchain-hs:

  • Construction is Pure: Creating a RunnableTree, StateGraph, or Chain produces a pure data structure AST without executing any network or disk operations.
  • Execution is Explicit: All effects are tracked in the monad m (e.g. IO, LangchainT m, or custom monad stacks).
  • Zero Hidden Global State: State is explicitly passed or held in STM TVar cells with ACID properties.

2. Algebraic Laws & QuickCheck Properties

Components in langchain-hs are verified against standard algebraic laws:

1. StateReducer Monoid Associativity

State reducers must satisfy associativity so that concurrent parallel branches can be merged in any order without race conditions:

∀a, b, c. (a⋄b)⋄c ≡ a⋄(b⋄c)

2. Runnable Identity & Composition Laws

Pure runnable pipelines satisfy Category / Arrow laws:

interpret (id| ≫f) ≡ interpret f interpret (f| ≫id) ≡ interpret f


3. Effect Polymorphism

All models and tools are polymorphic over their execution monad m:

-- Effect-polymorphic ChatModel
class (MonadIO m, MonadError LangchainError m) => ChatModel model m where
  invoke :: model -> [Message] -> m Message
  streamModel :: model -> [Message] -> (StreamEvent -> m ()) -> m ()

This allows you to run pipelines inside unit test harnesses with Identity or State monads, or in production web servers inside custom ReaderT AppEnv (ExceptT AppError IO).

ESC