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, orChainproduces 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
TVarcells 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).