lang_ex AGENTS.md

LangEx

Graph-based agent orchestration for Elixir. Builds stateful, multi-step LLM workflows using nodes, edges, conditional routing, state reducers, human-in-the-loop interrupts, and checkpointing. Inspired by LangGraph, built on BEAM primitives.

• Version: 0.11.0, Elixir: ~> 1.16
• Deps: req, jason, telemetry; optional redix, postgrex, ecto_sql, opentelemetry_api, opentelemetry_telemetry
• Test: ExUnit with mimic for mocking

Commands

mix deps.get                          # Install dependencies
mix compile --warnings-as-errors      # Compile (0 warnings required)
mix test                              # Run all tests (integration excluded)
mix test --include integration        # Also run Redis/Postgres tests (needs docker compose up)
mix test path/to/test.exs:42          # Run specific test
mix format                            # Auto-format
mix format --check-formatted          # Check formatting

Integration tests read LANG_EX_REDIS_URL / LANG_EX_POSTGRES_URL (defaults match docker-compose.yml).

Always run mix compile --warnings-as-errors before considering work done. Zero warnings required.

Architecture

LangEx (facade: invoke/3, stream/3, get_state/2, get_state_history/2, update_state/3, delete_thread/2)
├── Graph                             # Builder: new, add_node (+retry/cache/defer/timeout/on_error), add_edge, compile, to_mermaid
│   ├── Graph.Compiled                # Compiled executable graph
│   ├── Graph.Pregel                  # Super-step execution engine (internal)
│   ├── Graph.RetryPolicy             # Exponential backoff + jitter for retry: nodes
│   ├── Graph.State                   # State management with reducers
│   ├── Graph.NodeCache               # Bounded ETS memoization for cache: nodes
│   └── Graph.Stream                  # Lazy event streaming with modes + emit/1
├── NodeError / NodeTimeoutError      # Structured node failure contract ({:error, %NodeError{}})
├── LLM                               # Behaviour for provider adapters
│   ├── LLM.Anthropic                 # Claude adapter (streaming SSE)
│   │   ├── Anthropic.SSE             # SSE state machine (internal)
│   │   └── Anthropic.Formatter       # Message wire format (internal)
│   ├── LLM.OpenAI                    # GPT adapter
│   ├── LLM.Gemini                    # Gemini adapter
│   ├── LLM.Resilient                 # Retry wrapper with backoff
│   ├── LLM.ChatModel                 # Graph node helper for LLM calls
│   └── LLM.Registry                  # Provider resolution by model string
├── Tool                              # Tool/function definition struct
│   ├── Tool.Node                     # Graph node for parallel tool execution
│   └── Tool.Annotation               # Error recovery guidance for LLM
├── Message                           # Chat message types (Human, AI, System, Tool, RemoveMessage)
├── Middleware                        # Composable agent hooks for Prebuilt.agent
│   ├── Middleware.ModelRequest       # The model call as data, with override/2
│   ├── Middleware.Summarization      # LLM-summarised, persisted context compaction
│   ├── Middleware.ContextEditing     # Clears stale tool-result contents (no LLM)
│   ├── Middleware.TodoList           # write_todos planning tool + :todos state
│   ├── Middleware.ToolSelector       # LLM tool pre-selection for large tool sets
│   ├── Middleware.ToolApproval       # Human review of guarded tool calls (HITL)
│   ├── Middleware.ToolRetry          # Retries transient tool failures in place
│   ├── Middleware.CallBudget         # Caps model calls / tokens per run
│   ├── Middleware.ModelFallback      # Retries a failed call on fallback models
│   ├── Middleware.Subagent           # Delegation to nested agents as tools
│   ├── Middleware.Filesystem         # Sandboxed file tools
│   └── Middleware.Rubric             # Completion gate scoring the final answer
├── Checkpoint / Checkpointer         # Pause/resume with Memory, Redis, or Postgres
├── Store                             # Long-term memory (ETS / Postgres backends)
├── Migration                         # Versioned Postgres migrations (V1, V2)
├── Prebuilt                          # Ready-made agent graph constructor
├── Command / Send / Interrupt        # Graph control flow primitives
├── Config                            # Layered config resolution
├── ContextCompaction                 # Context window budget enforcement
└── Telemetry                         # Telemetry event definitions (+ Runs, OTel bridge)