You know how it goes. A pull-request gets approved with “LGTM” after a 1-2 minute glance. Three weeks later, that code crashes production at 2 AM because nobody noticed it was swallowing errors in a catch-all. The on-call engineer (probably you) spends four hours debugging something a reviewer could have caught in four minutes.

This post is about building a review system that prevents that. Not a checklist - an operating system.

This post is a practical code review system that works for two audiences at once: engineers who want actionable patterns, and PMs who want to understand why review rigor actually speeds things up.

The examples come from llm4s , a Scala library for building type-safe LLM applications. But the principles apply to any serious codebase. I’ll call out when something is llm4s-specific and when it generalizes.

This is a cleaned-up, public version of the code/design/infra/ops review checklist I use regularly.

Executive summary (for PMs and stakeholders)

If you’re short on time, here’s what this review system guarantees, what it prevents, and why it matters for delivery.

What this system guarantees

What this system prevents

Common failure modes this catches:

1. The swallowed exception - catch { case _ => } that hides real errors until production
2. The config bomb - hardcoded secrets or environment reads scattered through core logic
3. The breaking change surprise - API modification that breaks consumers without warning
4. The concurrency bug - mutable state shared across threads without synchronization
5. The unbounded cost - LLM calls without token limits or retry caps

How this affects velocity

Here’s the counterintuitive part: rigorous review speeds up delivery.

The ratio: 25:1. One hour of careful review prevents 25 hours of downstream work.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

Day 1:   PR merged with quick approval
Day 14:  Bug reported in production
Day 15:  4 hours debugging to find root cause
Day 16:  Fix PR, review, merge, deploy
Day 17:  Post-mortem meeting (5 people × 1 hour)
Day 18:  Follow-up tasks from post-mortem
─────────────────────────────────────────────
Total:   ~15 engineering hours + customer impact

vs.

Day 1:   Reviewer catches issue in 15 minutes
Day 1:   Author fixes in 20 minutes
Day 1:   PR merged correctly
─────────────────────────────────────────────
Total:   35 minutes

What contributors need to adopt

For engineers joining a codebase with this system:

1. Use Result types for errors - No exceptions in domain logic
2. Follow existing patterns - If there’s a factory, use it; if there’s a builder, use it
3. Test both paths - Success and failure cases get equal attention
4. Keep PRs small - Under 400 lines of diff, focused on one concern
5. Write the “why” - PR description explains motivation, not just mechanics

Repository map and architecture invariants

Understanding the codebase structure is essential for effective review. Here’s the llm4s layout:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

llm4s/
├── modules/
│   ├── core/           # Published library (highest review bar)
│   │   └── src/main/scala/org/llm4s/
│   │       ├── agent/          # Agent framework, guardrails, memory, handoffs, streaming
│   │       ├── config/         # Llm4sConfig - ONLY place for env/config reads
│   │       ├── llmconnect/     # LLMClient trait, LLMConnect factory, providers
│   │       ├── toolapi/        # Tool calling, ToolFunction, ToolRegistry
│   │       ├── types/          # Result[A], newtypes (ModelName, ApiKey, etc.)
│   │       ├── error/          # LLMError hierarchy (ADT)
│   │       ├── core/safety/    # Safety helpers, ErrorMapper
│   │       ├── rag/            # RAG, embeddings, vector stores
│   │       ├── trace/          # Observability, Langfuse integration
│   │       └── resource/       # ManagedResource
│   ├── samples/        # Usage examples (lower review bar)
│   ├── workspace/      # Containerized runner/client (lower review bar)
│   └── crossTest/      # Scala 2.13 and 3.x behavior checks
├── docs/               # User-facing documentation
├── docs/internals/     # Internal docs, design decisions
├── project/            # SBT config (Common.scala, Deps)
└── build.sbt

Boundary map (core vs edge)

The same tree, in one diagram: what counts as core (highest review bar) vs edge (allowed to do IO) vs examples.

flowchart LR
    subgraph Core["Core library (highest review bar)"]
        CoreSrc["modules/core/src/main/scala/..."]
        Types["types/: Result[A], newtypes"]
        Errors["error/: LLMError ADT"]
        ToolApi["toolapi/: ToolRegistry, ToolFunction"]
        Agent["agent/: orchestration (core logic)"]
    end

    subgraph Boundaries["Allowed boundaries (still in core)"]
        Config["config/: ONLY place for env/config reads"]
        Safety["core/safety/: controlled try/catch boundary"]
        Resource["resource/: bracket/use/release"]
    end

    subgraph Edge["Edges + lower review bar"]
        Samples["modules/samples/: usage examples"]
        Workspace["modules/workspace/: runner/client"]
        Docs["docs/: user + internal docs"]
        Cross["modules/crossTest/: cross-version checks"]
    end

    Agent --> ToolApi
    Agent --> Types
    Agent --> Errors
    ToolApi --> Types
    Config --> Types
    Config --> Errors
    Safety --> Errors
    Resource --> Types
    Samples --> CoreSrc
    Workspace --> CoreSrc
    Docs --> CoreSrc
    Cross --> CoreSrc
    style Core fill:#e1f5ff,stroke:#0066cc,color:#000
    style Boundaries fill:#fff4e1,stroke:#cc8800,color:#000
    style Edge fill:#f0e1ff,stroke:#8800cc,color:#000
    style CoreSrc fill:#e1f5ff,stroke:#0066cc,color:#000
    style Types fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style Errors fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style ToolApi fill:#e1f5ff,stroke:#0066cc,color:#000
    style Agent fill:#e1f5ff,stroke:#0066cc,color:#000
    style Config fill:#fff4e1,stroke:#cc8800,color:#000
    style Safety fill:#fff4e1,stroke:#cc8800,color:#000
    style Resource fill:#fff4e1,stroke:#cc8800,color:#000
    style Samples fill:#f0e1ff,stroke:#8800cc,color:#000
    style Workspace fill:#f0e1ff,stroke:#8800cc,color:#000
    style Docs fill:#f0e1ff,stroke:#8800cc,color:#000
    style Cross fill:#f0e1ff,stroke:#8800cc,color:#000

Key public API surfaces

Architecture invariants

Scalafix enforcements

The .scalafix.conf enforces these rules in core sources:

Review principles and quality bar

Core values

1. Correct first, clever never: LLM systems fail in creative ways. Our job is to make failures uncreative.
2. Explicit over implicit: Errors are typed, effects are at boundaries, dependencies are injected.
3. Boring reliability: Predictable behavior, clear contracts, code that stays readable six months later.

Pull request quality bar

A good pull request is:

• Correct: Handles success, failure, edge cases, partial data
• Safe: No secrets leaked, no tool abuse, no prompt injection footguns
• Maintainable: Clear APIs, consistent patterns, minimal cleverness
• Compatible: No accidental breaking changes to published artifacts
• Measurable: Performance claims backed by benchmarks

What to review rigorously

Pull request review workflow (CI playbook)

PR review, in one diagram: the “operating system” is just a tight loop of gating -> classify -> fix -> re-check -> merge.

flowchart TD
    Start["Author opens PR"] --> Scope["Scope + risk summary<br/>(modules, blast radius)"]
    Scope --> CI["CI gates: +compile, +test, scalafmtCheckAll"]
    CI -->|Fail| FixCI["Fix failures<br/>(don’t review broken builds)"]
    FixCI --> CI
    CI -->|Pass| Bot["CI bot review:<br/>checklists + invariants"]
    Bot --> Human["Human review:<br/>design + readability + risks"]
    Human --> Classify{"Classify finding"}
    Classify -->|Blocker| Block["Blocker: must fix before merge"]
    Classify -->|Must - fix| Must["Must-fix: fix before merge"]
    Classify -->|Should - fix| Should["Should-fix: fix or justify"]
    Classify -->|Nit| Nit["Nit: optional, keep sparse"]
    Block --> Fix["Author fixes<br/>+ adds tests/docs"]
    Must --> Fix
    Should --> Fix
    Nit --> Fix
    Fix --> ReCI["Re-run CI + re-review"]
    ReCI --> CI
    Bot --> Merge{"All blockers + must-fix resolved?"}
    Human --> Merge
    Merge -->|No| Fix
    Merge -->|Yes| Ship["Merge + release notes<br/>(README/CHANGELOG if needed)"]
    style Start fill:#e1f5ff,stroke:#0066cc,color:#000
    style Scope fill:#fff4e1,stroke:#cc8800,color:#000
    style CI fill:#e1f5ff,stroke:#0066cc,color:#000
    style FixCI fill:#ffe1e1,stroke:#cc0000,color:#000
    style Bot fill:#f0e1ff,stroke:#8800cc,color:#000
    style Human fill:#f0e1ff,stroke:#8800cc,color:#000
    style Classify fill:#fff4e1,stroke:#cc8800,color:#000
    style Block fill:#ffe1e1,stroke:#cc0000,color:#000
    style Must fill:#ffe1e1,stroke:#cc0000,color:#000
    style Should fill:#fff4e1,stroke:#cc8800,color:#000
    style Nit fill:#e1f5ff,stroke:#0066cc,color:#000
    style Fix fill:#f0e1ff,stroke:#8800cc,color:#000
    style ReCI fill:#e1f5ff,stroke:#0066cc,color:#000
    style Merge fill:#fff4e1,stroke:#cc8800,color:#000
    style Ship fill:#e1ffe1,stroke:#2d7a2d,color:#000

CI review bot contract

When analyzing a PR, the CI bot MUST produce:

1. PR summary (3-5 sentences)

• What the PR changes
• Which modules are affected
• Whether it’s a feature, fix, refactor, or docs change

2. Risk assessment

3. Must-fix findings (Blocker severity)

• Each finding cites: file:lineStart-lineEnd
• Each finding links to guideline section by name

4. Should-fix findings (Should-fix severity)

• Same format as must-fix

5. Optional questions

• Clarifying questions for PR author
• Suggestions that improve but don’t block

Severity rubric

Severity triage, in one diagram: if you and I classify differently, the system breaks.

flowchart TD
    Start["Found an issue in PR"] --> Q1{"Does it break a gate<br/>or violate a core invariant?"}
    Q1 -->|Yes| Blocker["Blocker<br/>Fix before merge"]
    Q1 -->|No| Q2{"Is it correctness, security,<br/>or missing error handling?"}
    Q2 -->|Yes| Must["Must-fix<br/>Fix before merge"]
    Q2 -->|No| Q3{"Is it readability, naming,<br/>tests, or minor inefficiency?"}
    Q3 -->|Yes| Should["Should-fix<br/>Fix or justify deferral"]
    Q3 -->|No| Nit["Nit<br/>Optional suggestion"]
    style Start fill:#e1f5ff,stroke:#0066cc,color:#000
    style Q1 fill:#fff4e1,stroke:#cc8800,color:#000
    style Q2 fill:#fff4e1,stroke:#cc8800,color:#000
    style Q3 fill:#fff4e1,stroke:#cc8800,color:#000
    style Blocker fill:#ffe1e1,stroke:#cc0000,color:#000
    style Must fill:#ffe1e1,stroke:#cc0000,color:#000
    style Should fill:#fff4e1,stroke:#cc8800,color:#000
    style Nit fill:#e1f5ff,stroke:#0066cc,color:#000

Comment format

Every review comment MUST follow this format:

1
2
3
4
5
6
7
8
9

**[SEVERITY]** Brief title

**Guideline**: [Section Name from this doc]

**Issue**: What is wrong and why it matters

**Suggestion**: How to fix (with code if applicable)

**Location**: `path/to/file.scala:42-48`

Code review checklist (llm4s specific)

Error handling

• Uses Result[A] for operations that can fail
• No throw in domain logic (only at hard integration boundaries)
• No try/catch in core (use Safety.safely or Try(...).toResult)
• Preserves error causes when wrapping (cause = Some(e))
• Pattern matches on error types use type patterns, not case _

llm4s pattern (modules/core/src/main/scala/org/llm4s/core/safety/Safety.scala:22-28):

1
2
3
4
5
6
7

def safely[A](thunk: => A)(implicit em: ErrorMapper = DefaultErrorMapper): Result[A] =
  fromTry(Try(thunk))

def fromTry[A](t: Try[A])(implicit em: ErrorMapper = DefaultErrorMapper): Result[A] = t match {
  case Success(v) => Right(v)
  case Failure(e) => Left(em(e))
}

What’s happening here?

• This snippet shows the minimal shape for: Error handling.
• In review, confirm the types make the happy path obvious and the error path explicit.

Configuration

• No sys.env, System.getenv, or ConfigFactory in core main sources
• Config reads happen only in org.llm4s.config
• Core code receives typed config via constructor injection

llm4s pattern (modules/core/src/main/scala/org/llm4s/config/Llm4sConfig.scala):

1
2
3
4

object Llm4sConfig {
  def provider(): Result[ProviderConfig] =
    ProviderConfigLoader.load(ConfigSource.default)
}

What’s happening here?

• This snippet shows the minimal shape for: Configuration.
• In review, confirm the types make the happy path obvious and the error path explicit.

Type safety

• Uses newtypes where confusion is possible (ModelName, ApiKey, ConversationId)
• Secrets never logged (ApiKey.toString returns "ApiKey(***)")
• ADTs used for state machines (sealed trait + case objects)
• No sentinel values (-1, "", null) - use Option or ADT

llm4s pattern (modules/core/src/main/scala/org/llm4s/types/package.scala:88-92):

1
2
3
4
5
6
7

final case class ApiKey(private val value: String) extends AnyVal {
  override def toString: String = "ApiKey(***)"

  def reveal: String = value

  def masked: String = s"${value.take(4)}${"*" * (value.length - 4)}"
}

What’s happening here?

• This snippet shows the minimal shape for: Type safety.
• In review, confirm the types make the happy path obvious and the error path explicit.

Pattern matching

• Exhaustive on sealed traits (no unguarded case _)
• Uses pattern matching for ADT dispatch, not isInstanceOf
• Guards are explicit when partial matching is intentional
• Wildcard case _ has logging or explicit justification

llm4s pattern (modules/core/src/main/scala/org/llm4s/llmconnect/provider/LLMProvider.scala:15-24):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

sealed trait LLMProvider {
  def name: String = this match {
    case LLMProvider.OpenAI => "openai"
    case LLMProvider.Azure => "azure"
    case LLMProvider.Anthropic => "anthropic"
    case LLMProvider.OpenRouter => "openrouter"
    case LLMProvider.Ollama => "ollama"
    case LLMProvider.Zai => "zai"
    case LLMProvider.Gemini => "gemini"
  }
}

What’s happening here?

• This snippet shows the minimal shape for: Pattern matching.
• In review, confirm the types make the happy path obvious and the error path explicit.

Immutability

• Default to val, immutable collections, case classes
• var only in tight, locally-contained loops with measured perf impact
• No mutable state shared across threads without explicit synchronization
• State changes return new instances (e.g., AgentState.copy)

for-Comprehensions

• Used for sequencing dependent operations (not looping)
• Each step has clear semantics
• Not deeply nested (break into named functions if > 5 steps)

llm4s pattern (modules/core/src/main/scala/org/llm4s/agent/Agent.scala:929-949):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

def run(
         query: String,
         tools: ToolRegistry,
         inputGuardrails: Seq[InputGuardrail] = Seq.empty,
         outputGuardrails: Seq[OutputGuardrail] = Seq.empty,
...
): Result[AgentState] =
  for {
    validatedQuery <- validateInput(query, inputGuardrails)
    initialState = initialize(validatedQuery, tools, handoffs, systemPromptAddition, completionOptions)
    finalState <- run(initialState, maxSteps, traceLogPath, debug)
    validatedState <- validateOutput(finalState, outputGuardrails)
  } yield validatedState

What’s happening here?

• This snippet shows the minimal shape for: for-Comprehensions.
• In review, confirm the types make the happy path obvious and the error path explicit.

API and design review checklist

Public API changes

• Backward compatible or explicitly breaking (with migration path)
• Default parameters don’t change existing behavior
• New required parameters fail at compile time, not runtime
• Deprecations include @deprecated with since version and migration hint
• Return types are explicit (no inferred public return types)

Type design

• ADTs for closed sets (sealed trait + case classes/objects)
• Plain traits for extension points (open for implementation)
• Smart constructors for validated types (private constructor + factory returning Result)
• Companion objects for default instances and factory methods

llm4s pattern - Smart constructor (modules/core/src/main/scala/org/llm4s/types/package.scala:115-121):

1
2
3
4
5
6
7
8

object ConversationId {
  def create(value: String): Result[ConversationId] =
    if (value.trim.nonEmpty) {
      Right(ConversationId(value.trim))
    } else {
      Left(ValidationError("Conversation ID cannot be empty", "conversationId"))
    }
}

What’s happening here?

• This snippet shows the minimal shape for: Type design.
• In review, confirm the types make the happy path obvious and the error path explicit.

Trait design

• Small, focused traits (Interface Segregation)
• No god traits with 10+ methods
• Composition over inheritance
• Self-types avoided unless strictly necessary

llm4s pattern (modules/core/src/main/scala/org/llm4s/llmconnect/LLMClient.scala):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

trait LLMClient {
  def complete(conversation: Conversation, options: CompletionOptions = CompletionOptions()): Result[Completion]

  def streamComplete(conversation: Conversation, options: CompletionOptions = CompletionOptions(),
                     onChunk: StreamedChunk => Unit): Result[Completion]

  def getContextWindow(): Int

  def getReserveCompletion(): Int

  def validate(): Result[Unit] = Right(())

  def close(): Unit = ()
}

What’s happening here?

• This snippet shows the minimal shape for: Trait design.
• In review, confirm the types make the happy path obvious and the error path explicit.

Six methods, all essential, all related to the single responsibility of “interact with an LLM”.

Architecture review checklist

Dependency direction

• Core depends on abstractions, not concrete implementations
• No circular dependencies between packages
• Providers implement core interfaces, not the reverse
• Config injected at edges, not pulled from environment

graph TD
    subgraph "High-Level (Core)"
        Agent["Agent"]
        LLMClient["LLMClient (trait)"]
        ToolRegistry["ToolRegistry"]
    end

    subgraph "Low-Level (Implementations)"
        OpenAI["OpenAIClient"]
        Anthropic["AnthropicClient"]
        Gemini["GeminiClient"]
    end

    Agent --> LLMClient
    OpenAI --> LLMClient
    Anthropic --> LLMClient
    Gemini --> LLMClient
    style Agent fill:#e1f5ff,stroke:#0066cc,color:#000
    style LLMClient fill:#fff4e1,stroke:#cc8800,color:#000
    style ToolRegistry fill:#e1f5ff,stroke:#0066cc,color:#000
    style OpenAI fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style Anthropic fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style Gemini fill:#e1ffe1,stroke:#2d7a2d,color:#000

Effect boundaries

• IO (HTTP, file, time, random) at application edges
• Pure transformations in core
• No hidden side effects in map/flatMap chains
• Logging is the only acceptable side effect in core (use sparingly)

Resource management

• Resources acquired with bracket/use/release pattern
• ManagedResource or Resource[F, A] for lifecycle management
• No resource leaks (connections, file handles, threads)
• Cleanup happens even on error paths

llm4s pattern (modules/core/src/main/scala/org/llm4s/resource/ManagedResource.scala:26-30):

1
2
3
4
5

def use[A](f: R => Result[A]): Result[A] =
  acquire().flatMap { resource =>
    val result = f(resource)
    release(resource).flatMap(_ => result)
  }

What’s happening here?

• This snippet shows the minimal shape for: Resource management.
• In review, confirm the types make the happy path obvious and the error path explicit.

Cross-version compatibility

• Code compiles on both Scala 2.13 and 3.x
• No Scala 3-only features in shared source (opaque types, inline, derives)
• Version-specific code in src/main/scala-2.13 or src/main/scala-3
• ScalaCompat used only for tiny shims (not dumping ground)
• modules/crossTest tests pass on both versions

Functional programming patterns in llm4s

Preferred patterns

Avoided patterns in core

Monad transformer usage

Use EitherT or OptionT only when nesting becomes unreadable:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// Before: nested Future[Result[A]]
def process(): Future[Result[User]] =
  fetchUser().flatMap {
    case Right(user) => fetchPermissions(user.id).map {
      case Right(perms) => Right(user.withPerms(perms))
      case Left(e) => Left(e)
    }
    case Left(e) => Future.successful(Left(e))
  }

// After: EitherT
def process(): Future[Result[User]] =
  (for {
    user <- EitherT(fetchUser())
    perms <- EitherT(fetchPermissions(user.id))
  } yield user.withPerms(perms)).value

What’s happening here?

• The first version nests Future and Result, so you end up manually unpacking Right/Left at multiple levels.
• EitherT lets you write one for-comprehension where failures short-circuit automatically; .value gives you back Future[Result[User]].

Advanced FP patterns you’ll actually use

These patterns show up in serious codebases. They’re not theoretical - they solve real problems when basic patterns (Option, Result, for-comprehensions) aren’t enough.

Reader monad: dependency injection without the ceremony

The problem: You have multiple functions that need the same configuration, and you’re tired of threading it through every signature.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// Bad: Config passed everywhere
def fetchUser(id: String, config: Config): Result[User] = ???
def enrichUser(user: User, config: Config): Result[EnrichedUser] = ???
def saveUser(user: EnrichedUser, config: Config): Result[Unit] = ???

// Composition is ugly
def process(id: String, config: Config): Result[Unit] = for {
  user <- fetchUser(id, config)
  enriched <- enrichUser(user, config)
  _ <- saveUser(enriched, config)
} yield ()

Good: Reader monad:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

import cats.data.Reader

case class Config(dbUrl: String, apiKey: String)

// Functions return Reader[Config, A]
def fetchUser(id: String): Reader[Config, Result[User]] =
  Reader { config =>
    database.query(config.dbUrl, s"SELECT * FROM users WHERE id = '$id'")
  }

def enrichUser(user: User): Reader[Config, Result[EnrichedUser]] =
  Reader { config =>
    apiClient.enrich(user, config.apiKey)
  }

// Composition - config provided once at the end
val program: Reader[Config, Result[EnrichedUser]] = for {
  user <- fetchUser("user-123")
  enriched <- enrichUser(user)
} yield enriched

// Run with actual config
val result = program.run(prodConfig)

What’s happening here?

• Reader[Config, A] is a function wrapper that delays config injection.
• You compose operations without mentioning config in signatures.
• Test by running with testConfig, prod with prodConfig.

llm4s application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// Agent orchestration with implicit config
type ConfigReader[A] = Reader[Llm4sConfig, A]

def buildClient: ConfigReader[Result[LLMClient]] =
  Reader(config => LLMConnect.getClient(config.provider))

def createAgent: ConfigReader[Result[Agent]] = for {
  client <- buildClient
  tools <- Reader(_.toolRegistry)
} yield Agent(client.getOrElse(???), tools)

// Run with different configs for different environments
val devAgent = createAgent.run(devConfig)
val prodAgent = createAgent.run(prodConfig)

When to use:

• Multiple functions need same dependencies (DB, API clients, config)
• You want to test with different configs without changing signatures
• Overkill for single function or two-function chains

sequenceDiagram
    participant Client
    participant Program as Reader[Config, A]
    participant FetchUser as fetchUser
    participant EnrichUser as enrichUser
    participant Config

    Client->>Program: program.run(prodConfig)
    activate Program
    Program->>FetchUser: apply(config)
    activate FetchUser
    FetchUser->>Config: config.dbUrl
    Config-->>FetchUser: dbUrl
    FetchUser-->>Program: Result[User]
    deactivate FetchUser

    Program->>EnrichUser: apply(config)
    activate EnrichUser
    EnrichUser->>Config: config.apiKey
    Config-->>EnrichUser: apiKey
    EnrichUser-->>Program: Result[EnrichedUser]
    deactivate EnrichUser

    Program-->>Client: Result[EnrichedUser]
    deactivate Program

    note over Program: Config injected once<br/>Threaded through all steps
    note over FetchUser,EnrichUser: Functions never mention<br/>config in signatures

Writer monad: logging without side effects

The problem: You want to accumulate logs alongside computations, but println is a side effect that doesn’t compose.

Good: Writer monad

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

import cats.data.Writer

type Logged[A] = Writer[Vector[String], A]

def validateEmail(email: String): Logged[Result[Email]] =
  if (email.contains("@"))
    Writer(Vector(s"Valid email: $email"), Right(Email(email)))
  else
    Writer(Vector(s"Invalid email: $email"), Left(ValidationError("Missing @")))

def validateAge(age: Int): Logged[Result[Int]] =
  if (age >= 0)
    Writer(Vector(s"Valid age: $age"), Right(age))
  else
    Writer(Vector(s"Negative age: $age"), Left(ValidationError("age", "Negative")))

// Logs accumulate automatically
val program = for {
  email <- validateEmail("[email protected]")
  age <- validateAge(30)
} yield (email, age)

val (logs, result) = program.run
// logs: Vector("Valid email: [email protected]", "Valid age: 30")

What’s happening here?

• Writer[Vector[String], A] carries both a value (A) and accumulated logs (Vector[String]).
• Each operation adds its log entry; composition merges them.
• Extract final logs with .run - no side effects during composition.

When to use:

• You need structured audit trails for compliance
• Debugging complex pipelines (trace intermediate steps)
• Don’t use for real-time logging (buffering overhead) - use regular logging for that

flowchart TD
    Start[Start: Empty logs] --> ValidateEmail[validateEmail]

    ValidateEmail --> EmailCheck{Email valid?}
    EmailCheck -->|Yes| EmailLog["Log: Valid email<br/>Value: Right(Email)"]
    EmailCheck -->|No| EmailFail["Log: Invalid email<br/>Value: Left(Error)"]

    EmailLog --> ValidateAge[validateAge]

    ValidateAge --> AgeCheck{Age >= 0?}
    AgeCheck -->|Yes| AgeLog["Logs: [email log, Valid age]<br/>Value: Right(30)"]
    AgeCheck -->|No| AgeFail["Logs: [email log, Negative age]<br/>Value: Left(Error)"]

    AgeLog --> Result["Final: (Vector of logs, result)"]
    EmailFail --> ShortCircuit[Short-circuit with logs]
    AgeFail --> ShortCircuit

    style EmailLog fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style AgeLog fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style EmailFail fill:#ffe1e1,stroke:#cc0000,color:#000
    style AgeFail fill:#ffe1e1,stroke:#cc0000,color:#000
    style Result fill:#e1f5ff,stroke:#0066cc,color:#000

Kleisli: composing functions that return monads

The problem: You have functions A => F[B] and B => F[C], and you want to compose them like A => F[C].

Good: Kleisli

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

import cats.data.Kleisli
import cats.effect.IO

type ReaderIO[A] = Kleisli[IO, Config, A]

def fetchUser(id: String): ReaderIO[User] =
  Kleisli { config =>
    IO(database.query(config.dbUrl, id))
  }

def fetchPermissions(user: User): ReaderIO[Permissions] =
  Kleisli { config =>
    IO(permissions.get(user.id, config.permissionsEndpoint))
  }

// Kleisli composes Config => IO[A] functions
val program: ReaderIO[(User, Permissions)] = for {
  user <- fetchUser("user-123")
  perms <- fetchPermissions(user)
} yield (user, perms)

// Run with config
val io: IO[(User, Permissions)] = program.run(prodConfig)

What’s happening here?

• Kleisli[IO, Config, A] is Config => IO[A] with composition built-in.
• It’s Reader + IO combined - dependency injection + async effects.
• andThen chains Kleisli arrows: (A => F[B]) andThen (B => F[C]) = (A => F[C]).

llm4s application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// Agent pipeline with Kleisli
type AgentPipeline[A] = Kleisli[Result, Llm4sConfig, A]

val validateInput: AgentPipeline[String] =
  Kleisli(config => Safety.safely(config.inputGuardrails.validate(input)))

val callLLM: AgentPipeline[Completion] =
  Kleisli(config => config.client.complete(conversation))

// Chain pipelines
val pipeline = validateInput andThen callLLM

When to use:

• Functions return monads (IO, Result, Future) and need shared dependencies
• Building composable pipelines (ETL, agent orchestration)
• Overkill if you just need Reader (no monad) or just IO (no dependencies)

flowchart LR
    subgraph Input["Input"]
        UserId["userId: String"]
    end

    subgraph K1["fetchUser<br/>Kleisli[IO, Config, User]"]
        K1_Config[Read Config] --> K1_IO[IO effect]
        K1_IO --> K1_User[User]
    end

    subgraph K2["fetchPermissions<br/>Kleisli[IO, Config, Permissions]"]
        K2_Config[Read Config] --> K2_IO[IO effect]
        K2_IO --> K2_Perms[Permissions]
    end

    subgraph Composed["Combined Pipeline<br/>Kleisli[IO, Config, (User, Perms)]"]
        Comp_Config[Config shared] --> Comp_Result["(User, Permissions)"]
    end

    UserId --> K1
    K1_User --> K2
    K1 -.andThen.-> K2
    K2 --> Composed

    Config[Config] -.injected once.-> Composed

    style K1 fill:#e1f5ff,stroke:#0066cc,color:#000
    style K2 fill:#e1f5ff,stroke:#0066cc,color:#000
    style Composed fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style Config fill:#fff4e1,stroke:#cc8800,color:#000

State monad: pure stateful computations

The problem: You need to thread state through a sequence of operations without mutable vars.

Good: State monad

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

import cats.data.State

case class GameState(score: Int, lives: Int, level: Int)

type GameAction[A] = State[GameState, A]

def increaseScore(points: Int): GameAction[Int] =
  State { state =>
    val newState = state.copy(score = state.score + points)
    (newState, newState.score)
  }

def loseLife: GameAction[Int] =
  State { state =>
    val newState = state.copy(lives = state.lives - 1)
    (newState, newState.lives)
  }

// Composition
val game: GameAction[String] = for {
  _ <- increaseScore(100)
  _ <- increaseScore(50)
  livesLeft <- loseLife
  result <- State.pure(if (livesLeft > 0) "Continue" else "Game Over")
} yield result

val (finalState, message) = game.run(GameState(0, 3, 1)).value
// finalState: GameState(150, 2, 1), message: "Continue"

What’s happening here?

• State[S, A] is a function S => (S, A) - takes old state, returns new state + value.
• Composition threads state automatically - no manual passing.
• Extract final state and value with .run(initialState).value.

llm4s equivalent:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

case class AgentState(conversation: Conversation, step: Int, toolCalls: Seq[ToolCallRequest])

type AgentAction[A] = State[AgentState, A]

def addMessage(msg: Message): AgentAction[Unit] =
  State.modify(state => state.copy(conversation = state.conversation.addMessage(msg)))

def incrementStep: AgentAction[Int] =
  State { state =>
    val newState = state.copy(step = state.step + 1)
    (newState, newState.step)
  }

// Multi-step agent run
val agentRun: AgentAction[AgentState] = for {
  _ <- addMessage(userMessage)
  _ <- incrementStep
  _ <- addMessage(assistantMessage)
  _ <- incrementStep
  finalState <- State.get
} yield finalState

When to use:

• Complex stateful logic (game loops, parsers, interpreters)
• You want referential transparency (pure functions, testable)
• Simple state - just use case class immutable updates
• Concurrent state - use Ref[F, A] instead

stateDiagram-v2
    [*] --> S0: Start
    S0: GameState with score 0, lives 3, level 1

    S0 --> S1: increaseScore(100)
    S1: GameState with score 100, lives 3, level 1
    note right of S1: Pure function maps S to new S and value A

    S1 --> S2: increaseScore(50)
    S2: GameState with score 150, lives 3, level 1

    S2 --> S3: loseLife
    S3: GameState with score 150, lives 2, level 1
    note right of S3: Returns new state and livesLeft equals 2

    S3 --> [*]: game.run(initialState)
    note left of S3: State threaded automatically without manual passing

Traverse: sequence effects across collections

The problem: You have List[F[A]] and need F[List[A]] - fail-fast on first error, or collect all results.

Bad: manual recursion

1
2
3
4
5
6
7

def fetchAllManual(ids: List[String]): Result[List[User]] =
  ids.foldRight(Right(List.empty[User]): Result[List[User]]) { (id, acc) =>
    for {
      list <- acc
      user <- fetchUser(id)
    } yield user :: list
  }

Good: Traverse

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import cats.syntax.all._

val userIds = List("1", "2", "3")

// Traverse - fail-fast on first error
def fetchAllTraverse(ids: List[String]): Result[List[User]] =
  ids.traverse(fetchUser)

// Parallel traverse (with cats.Parallel)
import cats.Parallel
import cats.effect.IO

def fetchAllParallel(ids: List[String])(using P: Parallel[IO]): IO[List[User]] =
  ids.parTraverse(id => IO(fetchUser(id)))

What’s happening here?

• traverse(f: A => F[B]): F[List[B]] sequences effects and collects results.
• Fail-fast: first Left stops execution and returns that error.
• parTraverse runs effects in parallel (requires Parallel instance).

llm4s application:

1
2
3
4
5
6
7
8

// Execute multiple tool calls, fail-fast on error
def executeTools(calls: List[ToolCallRequest]): Result[List[ToolCallResponse]] =
  calls.traverse { call =>
    toolRegistry.find(call.function.name) match {
      case Some(tool) => tool.execute(call)
      case None => Left(ToolNotFoundError(call.function.name))
    }
  }

When to use:

• Apply effectful function to collection and collect results
• Fail-fast error handling (first error stops everything)
• Parallel execution with parTraverse
• Don’t need sequencing - use map
• Need to collect all errors - use Validated + traverse

flowchart TD
    Input["List[String]<br/>['1', '2', '3']"] --> Traverse[".traverse(fetchUser)"]

    Traverse --> Fetch1["fetchUser('1')<br/>Result[User]"]
    Traverse --> Fetch2["fetchUser('2')<br/>Result[User]"]
    Traverse --> Fetch3["fetchUser('3')<br/>Result[User]"]

    Fetch1 --> Check1{Success?}
    Check1 -->|Right| Acc1["Accumulate User1"]
    Check1 -->|Left| Fail[Short-circuit with error]

    Fetch2 --> Check2{Success?}
    Check2 -->|Right| Acc2["Accumulate User2"]
    Check2 -->|Left| Fail

    Fetch3 --> Check3{Success?}
    Check3 -->|Right| Acc3["Accumulate User3"]
    Check3 -->|Left| Fail

    Acc1 --> Acc2
    Acc2 --> Acc3
    Acc3 --> Result["Result[List[User]]<br/>Right([User1, User2, User3])"]

    Fail --> ErrorResult["Result[List[User]]<br/>Left(error)"]

    style Fetch1 fill:#e1f5ff,stroke:#0066cc,color:#000
    style Fetch2 fill:#e1f5ff,stroke:#0066cc,color:#000
    style Fetch3 fill:#e1f5ff,stroke:#0066cc,color:#000
    style Result fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style ErrorResult fill:#ffe1e1,stroke:#cc0000,color:#000
    style Fail fill:#ffe1e1,stroke:#cc0000,color:#000

Higher-Kinded Types (HKT): abstract over type constructors

The problem: You want generic functions that work with any container (List, Option, Result, IO) without duplicating code.

Good: HKT

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// Generic Functor for any F[_]
trait Functor[F[_]] {
  def map[A, B](fa: F[A])(f: A => B): F[B]
}

// Instances
given Functor[Option] with {
  def map[A, B](fa: Option[A])(f: A => B): Option[B] = fa.map(f)
}

given Functor[List] with {
  def map[A, B](fa: List[A])(f: A => B): List[B] = fa.map(f)
}

// Generic function works with any Functor
def increment[F[_]: Functor](container: F[Int]): F[Int] = {
  val F = summon[Functor[F]]
  F.map(container)(_ + 1)
}

increment(Some(5))       // Some(6)
increment(List(1, 2, 3)) // List(2, 3, 4)

What’s happening here?

• F[_] is a type constructor - it takes a type and returns a type (List[], Option[]).
• Functor[F[_]] abstracts over the container shape.
• One implementation works for List, Option, Result, IO, etc.

llm4s application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// Abstract over Result and IO
trait AsyncAlgebra[F[_]: Monad] {
  def complete(conv: Conversation): F[Completion]
  def execute(tool: ToolFunction[_, _]): F[String]
}

class LiveAgent[F[_]: Monad](client: LLMClient) extends AsyncAlgebra[F] {
  def complete(conv: Conversation): F[Completion] =
    summon[Monad[F]].pure(client.complete(conv).getOrElse(???))
}

// Use with different effect types
val resultAgent = new LiveAgent[Result](client)   // Synchronous
val ioAgent = new LiveAgent[IO](client)           // Asynchronous

When to use:

• Writing libraries that work with multiple effect types
• Tagless Final architecture (abstract over F[_])
• Reusing algorithms across containers (Functor, Monad, Traverse)
• Application code - usually just pick one effect type (IO or Result)
• Beginner teams - start with concrete types, refactor to HKT later

classDiagram
    class Functor~F[_]~ {
        <<trait>>
        +map(fa: F[A])(f: A => B): F[B]
    }

    class FunctorOption {
        +map(fa: Option[A])(f: A => B): Option[B]
    }

    class FunctorList {
        +map(fa: List[A])(f: A => B): List[B]
    }

    class FunctorResult {
        +map(fa: Result[A])(f: A => B): Result[B]
    }

    class IncrementFunction {
        +increment~F[_]: Functor~(F[Int]): F[Int]
    }

    Functor <|.. FunctorOption : implements
    Functor <|.. FunctorList : implements
    Functor <|.. FunctorResult : implements

    IncrementFunction ..> Functor : uses F[_]

    note for Functor "F[_] is a type constructor<br/>Takes type, returns type"
    note for IncrementFunction "One function works for<br/>Option, List, Result, IO..."

    style Functor fill:#e1f5ff,stroke:#0066cc,color:#000
    style FunctorOption fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style FunctorList fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style FunctorResult fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style IncrementFunction fill:#fff4e1,stroke:#cc8800,color:#000

Scala 3 type-level patterns: compile-time guarantees

These are Scala 3-specific features that catch bugs at compile time with zero runtime overhead. If you’re still on Scala 2, see the cross-compilation notes in scala-2-advanced patterns .

Opaque types: zero-cost domain modeling

The problem: You want type-safe wrappers (UserId vs String) without the runtime cost of case class wrappers.

Bad: case class wrapper (allocates objects):

1
2
3
4
5
6
7
8

case class UserId(value: String)
case class Email(value: String)

val userId = UserId("user-123")  // Heap allocation
val email = Email("[email protected]")  // Heap allocation

// Runtime overhead - wrapping/unwrapping everywhere
database.query(userId.value)

Good: opaque type:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

object Domain {
  opaque type UserId = String
  opaque type Email = String

  object UserId {
    def apply(value: String): UserId = value  // No allocation!
    extension (id: UserId)
      def value: String = id
  }

  object Email {
    def apply(value: String): Email = value
    extension (email: Email)
      def domain: String = email.split("@")(1)
  }
}

import Domain._

val userId: UserId = UserId("user-123")  // Zero cost
val email: Email = Email("[email protected]")

// Compile error: can't mix up types
// val badUserId: UserId = email  // Type mismatch!

// Zero runtime overhead - erases to String
database.query(userId)  // Passes String directly

What’s happening here?

• opaque type creates a new type that’s only distinct at compile time.
• At runtime, it’s literally the underlying type (String) - zero allocation.
• Outside the defining scope (object Domain), you can’t mix up UserId and Email.
• Inside the scope, they’re both String (for implementation convenience).

llm4s application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

opaque type ModelName = String
opaque type ApiKey = String
opaque type ConversationId = String

object ModelName {
  def apply(value: String): ModelName = value
  val GPT4 = ModelName("gpt-4")
  val Claude = ModelName("claude-3-sonnet")
}

// Type-safe, no runtime cost
def getClient(model: ModelName, key: ApiKey): Result[LLMClient] = ???

// Can't accidentally swap arguments
getClient(apiKey, modelName)  // Compile error

When to use:

• Domain primitives (UserId, OrderId, Money, Email)
• Performance-critical code (hot paths, tight loops)
• Preventing primitive obsession without overhead
• Scala 2.13 - use AnyVal value classes instead

flowchart LR
    subgraph CompileTime["Compile Time"]
        direction TB
        UserId["UserId"]
        Email["Email"]
        String1["String"]

        UserId -.distinct from.-> Email
        UserId -.opaque to.-> String1
        Email -.opaque to.-> String1

        style UserId fill:#e1f5ff,stroke:#0066cc,color:#000
        style Email fill:#e1ffe1,stroke:#2d7a2d,color:#000
    end

    subgraph Runtime["Runtime"]
        direction TB
        String2["String"]
        String3["String (UserId erased)"]
        String4["String (Email erased)"]

        String3 --> String2
        String4 --> String2

        style String2 fill:#fff4e1,stroke:#cc8800,color:#000
        style String3 fill:#fff4e1,stroke:#cc8800,color:#000
        style String4 fill:#fff4e1,stroke:#cc8800,color:#000
    end

    CompileTime ==>|Erasure| Runtime

    note1["Inside Domain scope:<br/>UserId = String<br/>Email = String"]
    note2["Outside Domain scope:<br/>UserId ≠ Email<br/>(Compile error)"]
    note3["Zero allocation<br/>Zero overhead"]

    style note1 fill:#f0e1ff,stroke:#8800cc,color:#000
    style note2 fill:#f0e1ff,stroke:#8800cc,color:#000
    style note3 fill:#e1ffe1,stroke:#2d7a2d,color:#000

Union types: type-safe APIs without inheritance

The problem: You want to accept multiple unrelated types without creating artificial inheritance hierarchies.

Bad: sealed trait hierarchy (forces inheritance):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

sealed trait InputType
case class StringInput(value: String) extends InputType
case class IntInput(value: Int) extends InputType
case class BoolInput(value: Boolean) extends InputType

// Have to wrap primitives in case classes
def process(input: InputType): String = input match {
  case StringInput(s) => s"String: $s"
  case IntInput(i) => s"Int: $i"
  case BoolInput(b) => s"Boolean: $b"
}

process(StringInput("hello"))  // Wrapping overhead

Good: union type:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

def process(value: String | Int | Boolean): String = value match {
  case s: String => s"String: $s"
  case i: Int => s"Int: $i"
  case b: Boolean => s"Boolean: $b"
}  // Compiler verifies exhaustiveness!

process("hello")  // No wrapping
process(42)       //
process(true)     //
// process(3.14)  // Compile error: Double not in union

What’s happening here?

• String | Int | Boolean means “one of these types” - no inheritance required.
• Pattern matching is exhaustive - compiler warns if you miss a case.
• Zero runtime overhead - no wrapper classes.

Error handling with union types:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

sealed trait NotFound
sealed trait Unauthorized
sealed trait ServerError

type HttpError = NotFound | Unauthorized | ServerError

def handleError(error: HttpError): String = error match {
  case _: NotFound => "404: Not found"
  case _: Unauthorized => "401: Unauthorized"
  case _: ServerError => "500: Server error"
}

llm4s application:

1
2
3
4
5
6
7

type ToolResult = String | ujson.Value | Array[Byte]

def processToolOutput(result: ToolResult): String = result match {
  case s: String => s
  case json: ujson.Value => json.render()
  case bytes: Array[Byte] => new String(bytes)
}

When to use:

• Accepting multiple primitive types without wrapping
• Error modeling (union of error types)
• API responses that can be different shapes
• Complex domain modeling - use ADTs (sealed trait + case classes)

flowchart TD
    Input["value: String | Int | Boolean"] --> Match{Pattern Match}

    Match -->|case s: String| String["String branch<br/>s'String: $s'"]
    Match -->|case i: Int| Int["Int branch<br/>s'Int: $i'"]
    Match -->|case b: Boolean| Boolean["Boolean branch<br/>s'Boolean: $b'"]

    String --> Output[Output: String]
    Int --> Output
    Boolean --> Output

    Invalid["Double"] -.->|Compile Error| Match

    subgraph UnionType["Union Type = String | Int | Boolean"]
        T1[String]
        T2[Int]
        T3[Boolean]
    end

    note1["No inheritance hierarchy<br/>No wrapper classes<br/>Zero runtime overhead"]
    note2["Exhaustiveness checking:<br/>Compiler ensures all cases handled"]

    style String fill:#e1f5ff,stroke:#0066cc,color:#000
    style Int fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style Boolean fill:#fff4e1,stroke:#cc8800,color:#000
    style Invalid fill:#ffe1e1,stroke:#cc0000,color:#000
    style UnionType fill:#f0e1ff,stroke:#8800cc,color:#000
    style note1 fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style note2 fill:#e1f5ff,stroke:#0066cc,color:#000

Intersection types: compound capabilities

The problem: You need an object that implements multiple unrelated traits, but you don’t want to create a new trait just for the combination.

Good: intersection type

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

trait Serializable {
  def serialize: String
}

trait Loggable {
  def log(): Unit
}

// Function requires BOTH capabilities
def processAndLog(obj: Serializable & Loggable): Unit = {
  obj.log()  // Both APIs available
  val data = obj.serialize
  println(data)
}

case class User(name: String) extends Serializable with Loggable {
  def serialize: String = s"""{"name":"$name"}"""
  def log(): Unit = println(s"User: $name")
}

processAndLog(User("Alice"))  // Has both traits

case class Order(id: Int) extends Serializable {
  def serialize: String = s"""{"id":$id}"""
}

// processAndLog(Order(1))  // Compile error: missing Loggable

What’s happening here?

• Serializable & Loggable means “both traits required” - intersection of capabilities.
• Compiler ensures the argument has all required methods.
• No need to create trait SerializableAndLoggable extends Serializable with Loggable.

When to use:

• Function parameters that need multiple capabilities
• Avoiding trait proliferation (DRY)
• Type-safe mixin composition
• Domain modeling - use regular trait extension (with)

flowchart TB
    subgraph Capabilities["Available Capabilities"]
        Serializable["Serializable<br/>serialize()"]
        Loggable["Loggable<br/>log()"]
    end

    Serializable --> Intersection
    Loggable --> Intersection

    Intersection["Serializable & Loggable<br/>(Both required)"]

    Intersection --> ProcessAndLog["processAndLog(obj)"]

    ProcessAndLog --> CallLog["obj.log()"]
    ProcessAndLog --> CallSerialize["obj.serialize"]

    User["User<br/>extends Serializable with Loggable"] -->|Accepted| Intersection
    Order["Order<br/>extends Serializable only"] -.->|Compile Error| Intersection

    note1["Intersection Type:<br/>All capabilities must be present"]
    note2["No need to create<br/>SerializableAndLoggable trait"]

    style Serializable fill:#e1f5ff,stroke:#0066cc,color:#000
    style Loggable fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style Intersection fill:#fff4e1,stroke:#cc8800,color:#000
    style User fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style Order fill:#ffe1e1,stroke:#cc0000,color:#000
    style note1 fill:#f0e1ff,stroke:#8800cc,color:#000
    style note2 fill:#e1f5ff,stroke:#0066cc,color:#000

Literal types: compile-time constants

The problem: You want to restrict a parameter to specific values, not just a type (e.g., only 3, not any Int).

Good: literal type:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

def exactThree(x: 3): String = "You passed exactly 3"

exactThree(3)  //
// exactThree(4)  // Compile error: 4 is not subtype of 3

// String literals
def handleStatus(status: "pending" | "complete" | "failed"): Unit = status match {
  case "pending" => println("In progress")
  case "complete" => println("Done")
  case "failed" => println("Error")
}

handleStatus("pending")  //
// handleStatus("unknown")  // Compile error

What’s happening here?

• Literal types (3, "pending") are exact values, not type ranges.
• Compiler rejects anything that doesn’t match the literal.
• Combine with union types for enums without boilerplate.

Real-world example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

type HttpMethod = "GET" | "POST" | "PUT" | "DELETE"
type StatusCode = 200 | 404 | 500

def handleRequest(method: HttpMethod, expectedStatus: StatusCode): Unit = {
  // Type-safe HTTP constants
  method match {
    case "GET" => println("Fetching")
    case "POST" => println("Creating")
    case "PUT" => println("Updating")
    case "DELETE" => println("Deleting")
  }
}

handleRequest("GET", 200)  //
// handleRequest("PATCH", 200)  // Compile error

llm4s application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

type LLMProvider = "openai" | "anthropic" | "cohere"

def getClient(provider: LLMProvider): Result[LLMClient] = provider match {
  case "openai" => OpenAIClient.create
  case "anthropic" => AnthropicClient.create
  case "cohere" => CohereClient.create
}

// Typos caught at compile time
// getClient("opeanai")  // Compile error

When to use:

• Enums with small, fixed sets of values
• Configuration constants (environments, feature flags)
• Preventing typos in string constants
• Large enums - use enum keyword instead
• Values known only at runtime - use regular types

Compile-time validation: catch drift before production

These patterns use macros to validate schemas, enforce state machines, and eliminate entire classes of runtime errors.

Schema conformance with macros

The problem: Producer schema changes break consumers at runtime. You only discover schema drift when data pipelines fail in production.

Good: compile-time schema validation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

enum SchemaPolicy:
  case Exact      // Exact match required
  case Backward   // Producer can add optional fields
  case Forward    // Consumer can ignore extra fields

// Define contract
case class UserV1(id: Long, email: String)
case class UserV2(id: Long, email: String, age: Option[Int] = None)

// Compiles: V2 adds optional field (backward compatible)
summon[SchemaConforms[UserV2, UserV1, SchemaPolicy.Backward]]

// Compile error: V1 missing 'age' field that V2 expects
// summon[SchemaConforms[UserV1, UserV2, SchemaPolicy.Exact]]

What’s happening here?

• Macro compares case class structures at compile time.
• SchemaConforms[Producer, Contract, Policy] proves compatibility.
• If schemas don’t match policy, code won’t compile.

Prevented at compile time:

• Schema drift in Spark/Kafka pipelines
• Breaking changes between microservices
• Runtime schema mismatch errors

When to use:

• Data pipelines with producer/consumer contracts
• Spark schema evolution (prevent AnalysisException)
• gRPC/Protobuf compatibility checks
• Overkill for internal-only schemas with no external consumers

Phantom type state machines

The problem: You can call builder methods in the wrong order, creating invalid pipelines (e.g., .build() before .addSource()).

Good: phantom type builder:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

sealed trait BuilderState
sealed trait Empty extends BuilderState
sealed trait WithSource extends BuilderState
sealed trait WithTransform extends BuilderState
sealed trait Complete extends BuilderState

case class PipelineBuilder[S <: BuilderState, Contract] private (
  steps: List[PipelineStep]
) {
  def addSource[C](src: TypedSource[C]): PipelineBuilder[WithSource, C] = ???

  def transformAs[Next](f: DataFrame => DataFrame)(using
    ev: S <:< WithSource  // Can only call if state is WithSource
  ): PipelineBuilder[WithTransform, Next] = ???

  def addSink[R, P <: SchemaPolicy](sink: TypedSink[R])(using
    ev0: S <:< WithTransform,  // Must have transform
    ev1: SchemaConforms[Contract, R, P]  // Schema must conform
  ): PipelineBuilder[Complete, Contract] = ???

  def build(using ev: S =:= Complete): Pipeline = ???  // Only if Complete
}

// Usage
val pipeline =
  PipelineBuilder[UserContract]()
    .addSource(csvSource)       // Empty -> WithSource
    .transformAs[Enriched](...)  // WithSource -> WithTransform
    .addSink[Contract, Backward](sink) // WithTransform -> Complete
    .build                       // Only works when Complete

// Compile errors
// PipelineBuilder().build  // Can't build without source
// builder.addSink(...)     // Can't add sink before transform

What’s happening here?

• S <: BuilderState is a phantom type - exists only at compile time, zero runtime overhead.
• Each method returns a builder with a different state type.
• Type constraints (S <:< WithSource) prevent calling methods in wrong order.

Impossible states made unrepresentable:

• Can’t build pipeline without source
• Can’t add sink before transform
• Can’t skip required configuration steps

When to use:

• Complex builders with required sequences (Spark jobs, HTTP clients, DSLs)
• Preventing misconfiguration at compile time
• Simple builders (2-3 optional methods) - phantom types are overkill

stateDiagram-v2
    [*] --> Empty: new PipelineBuilder()

    Empty --> WithSource: addSource(csvSource)
    note right of Empty: State is Empty - Can only call addSource

    WithSource --> WithTransform: transformAs(fn)
    note right of WithSource: State is WithSource - Can call transformAs with constraint ev

    WithTransform --> Complete: addSink(sink)
    note right of WithTransform: State is WithTransform - Can call addSink with constraint ev

    Complete --> [*]: build()
    note right of Complete: State is Complete - Can call build with equality constraint

    Empty --> CompileError1: build()
    Empty --> CompileError2: addSink()
    WithSource --> CompileError3: build()
    WithSource --> CompileError4: addSink()

    state CompileError1 {
        [*] --> Error: Type constraint failed
    }
    state CompileError2 {
        [*] --> Error: Type constraint failed
    }
    state CompileError3 {
        [*] --> Error: Type constraint failed
    }
    state CompileError4 {
        [*] --> Error: Type constraint failed
    }

    note left of CompileError1: Phantom types prevent<br/>invalid state transitions<br/>at compile time

Inline for zero-cost abstractions

The problem: Helper functions add overhead (call stack, allocation). You want abstraction without performance cost.

Good: inline:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

inline def square(inline x: Int): Int = x * x

val result = square(5)
// Compiles to: val result = 25 (no function call!)

// Conditional compilation
inline def debug(inline msg: String): Unit =
  inline if (BuildConfig.debugEnabled) then
    println(s"[DEBUG] $msg")

// In production (debugEnabled = false):
debug("Expensive computation: ${heavyOperation()}")
// Compiles to: () - nothing! heavyOperation() never called

What’s happening here?

• inline tells compiler to replace function call with function body at every call site.
• inline if evaluated at compile time - dead branches eliminated.
• Zero runtime overhead - inlined code is exactly as if you copy-pasted it.

llm4s application:

1
2
3
4
5
6

inline def safely[A](inline operation: => A): Result[A] =
  inline if (BuildConfig.productionMode) then
    try { Right(operation) }
    catch { case e: Exception => Left(UnexpectedError(e.getMessage)) }
  else
    Right(operation)  // Skip try-catch in dev for better stack traces

When to use:

• Performance-critical hot paths
• Compile-time feature flags
• Eliminating abstraction overhead
• Large functions - increases bytecode size
• Functions used in hundreds of places - code bloat

Design patterns: how FP, OOP, and SOLID work together

Scala supports both OOP and FP paradigms. This section shows how to blend design patterns with functional techniques, when to use which approach, and how they relate to SOLID principles.

The pattern spectrum

flowchart LR
    subgraph PureFP["Pure FP"]
        FP1["ADTs, Monads"]
        FP2["Type Classes"]
        FP3["Immutable Data"]
        FP4["SOLID: SRP, ISP"]
    end

    subgraph Hybrid["Hybrid"]
        H1["Smart Constructors"]
        H2["Builder + Phantom Types"]
        H3["Resource Management"]
        H4["SOLID: All 5"]
    end

    subgraph PureOOP["Pure OOP"]
        OOP1["Mutable State"]
        OOP2["Inheritance Trees"]
        OOP3["Imperative Logic"]
        OOP4["SOLID: LSP, DIP"]
    end

    PureFP <-->|" Data transforms,<br/>validation, parsing "| Hybrid
    Hybrid <-->|" External APIs,<br/>stateful components "| PureOOP
    style PureFP fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style Hybrid fill:#fff4e1,stroke:#cc8800,color:#000
    style PureOOP fill:#e1f5ff,stroke:#0066cc,color:#000
    style FP1 fill:#c8e6c9,stroke:#2d7a2d,color:#000
    style FP2 fill:#c8e6c9,stroke:#2d7a2d,color:#000
    style FP3 fill:#c8e6c9,stroke:#2d7a2d,color:#000
    style FP4 fill:#c8e6c9,stroke:#2d7a2d,color:#000
    style H1 fill:#ffe0b2,stroke:#cc8800,color:#000
    style H2 fill:#ffe0b2,stroke:#cc8800,color:#000
    style H3 fill:#ffe0b2,stroke:#cc8800,color:#000
    style H4 fill:#ffe0b2,stroke:#cc8800,color:#000
    style OOP1 fill:#bbdefb,stroke:#0066cc,color:#000
    style OOP2 fill:#bbdefb,stroke:#0066cc,color:#000
    style OOP3 fill:#bbdefb,stroke:#0066cc,color:#000
    style OOP4 fill:#bbdefb,stroke:#0066cc,color:#000

Guidelines:

• Pure FP (Left): Data transformations, validation, business logic, parsing
• Hybrid (Center): Object construction, resource management, external integrations
• Pure OOP (Right): Rare in llm4s - only when external APIs demand it

Pattern synergies: combinations that strengthen each other

Pattern anti-synergies: combinations to avoid

Pattern review decision tree

flowchart TD
    Start([Reviewing Code]) --> CheckSOLID{Check SOLID<br/>violations first}
    CheckSOLID -->|God Object| SplitSRP[Violates SRP<br/>Split responsibilities]
    CheckSOLID -->|Concrete Deps| ApplyDIP[Violates DIP<br/>Depend on abstractions]
    CheckSOLID -->|No Violations| Question1{Is it data<br/>transformation?}
    Question1 -->|Yes| FP[Use Pure FP:<br/>ADTs, Pattern Matching,<br/>Monads]
    Question1 -->|No| Question2{Is it object<br/>construction?}
    Question2 -->|Yes| Question3{Complex validation<br/>or many params?}
    Question3 -->|Yes| Builder[Use Builder +<br/>Phantom Types]
    Question3 -->|No| Factory[Use Factory +<br/>Smart Constructors]
    Question2 -->|No| Question4{Is it external<br/>integration?}
    Question4 -->|Yes| TypeClass[Use Type Classes<br/>or Adapter Pattern]
    Question4 -->|No| Question5{Is it polymorphic<br/>behavior?}
    Question5 -->|Yes| ADT[Use ADTs +<br/>Pattern Matching]
    Question5 -->|No| ReviewSOLID[Apply SOLID<br/>Principles]
    style Start fill:#e1f5ff,stroke:#0066cc,color:#000
    style CheckSOLID fill:#f5e1ff,stroke:#8800cc,color:#000
    style SplitSRP fill:#ffe1e1,stroke:#cc0000,color:#000
    style ApplyDIP fill:#ffe1e1,stroke:#cc0000,color:#000
    style FP fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style Builder fill:#fff4e1,stroke:#cc8800,color:#000
    style Factory fill:#fff4e1,stroke:#cc8800,color:#000
    style TypeClass fill:#f0e1ff,stroke:#8800cc,color:#000
    style ADT fill:#e1ffe1,stroke:#2d7a2d,color:#000

Factory pattern: smart constructors + ADTs

classDiagram
    class LLMClient {
        <<trait>>
        +complete(Conversation, CompletionOptions) Result~Completion~
        +streamComplete(Conversation, CompletionOptions, onChunk) Result~Completion~
    }

    class ProviderConfig {
        <<sealedtrait>>
    }

    class OpenAIConfig {
        +model: ModelName
        +apiKey: ApiKey
    }

    class AnthropicConfig {
        +model: ModelName
        +apiKey: ApiKey
    }

    class LLMConnect {
        <<object>>
        +getClient(ProviderConfig) Result~LLMClient~
    }

    class OpenAIClient {
        +complete() Result~Completion~
    }

    class AnthropicClient {
        +complete() Result~Completion~
    }

    ProviderConfig <|-- OpenAIConfig
    ProviderConfig <|-- AnthropicConfig
    LLMClient <|.. OpenAIClient
    LLMClient <|.. AnthropicClient
    LLMConnect ..> ProviderConfig: uses
    LLMConnect ..> LLMClient: creates

OOP approach (classic Factory):

1
2
3
4
5
6
7
8

abstract class LLMClientFactory {
  def createClient(): LLMClient
}

final class OpenAIFactory extends LLMClientFactory {
  override def createClient(): LLMClient =
    new OpenAIClient(/* provider config */)
}

What’s happening here?

• This snippet shows the minimal shape for: Factory pattern: smart constructors + ADTs.
• In review, confirm the types make the happy path obvious and the error path explicit.

FP approach (Smart constructors + ADTs):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// Sealed ADT represents all possible configs
sealed trait ProviderConfig

case class OpenAIConfig(model: ModelName, apiKey: ApiKey) extends ProviderConfig

case class AnthropicConfig(model: ModelName, apiKey: ApiKey) extends ProviderConfig

// Factory method uses pattern matching (ADT dispatch)
def buildClient(config: ProviderConfig): Result[LLMClient] =
  config match {
    case cfg: OpenAIConfig => OpenAIClient(cfg)
    case cfg: AnthropicConfig => AnthropicClient(cfg)
  }

What’s happening here?

• This snippet shows the minimal shape for: Factory pattern: smart constructors + ADTs.
• In review, confirm the types make the happy path obvious and the error path explicit.

llm4s hybrid approach (LLMConnect.scala:10-46):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

object LLMConnect {
  def getClient(config: ProviderConfig): Result[LLMClient] =
    Safety.safely(buildClient(config))

  private def buildClient(config: ProviderConfig): Result[LLMClient] =
    config match {
      case cfg: OpenAIConfig => OpenAIClient(cfg)
      case cfg: AnthropicConfig => AnthropicClient(cfg)
      case cfg: OllamaConfig => OllamaClient(cfg)
      case cfg: GeminiConfig => GeminiClient(cfg)
    }
}

What’s happening here?

• This snippet shows the minimal shape for: Factory pattern: smart constructors + ADTs.
• In review, confirm the types make the happy path obvious and the error path explicit.

Why this works:

• DIP: High-level code depends on LLMClient trait, not concrete classes
• OCP: Add new provider by adding case to sealed trait, not modifying factory
• Result monad: Handles errors without exceptions (FP)
• ADTs: Exhaustive pattern matching ensures all cases handled (FP)

Review checklist

• Factory returns Result[T] not T (handles validation)
• Factory uses ADT pattern matching, not if/else on strings
• New implementations don’t require modifying factory code
• Factory is in companion object or dedicated object

Builder pattern: phantom types vs currying

classDiagram
    class BuilderState {
        <<sealedtrait>>
    }

    class Empty {
        <<phantomtype>>
    }

    class HasModel {
        <<phantomtype>>
    }

    class Complete {
        <<phantomtype>>
    }

    class LLMClientBuilder~S~ {
        -model: Option~ModelName~
        -apiKey: Option~ApiKey~
        +withModel(ModelName) LLMClientBuilder~HasModel~
        +withApiKey(ApiKey) LLMClientBuilder~Complete~
        +build() Result~LLMClient~
    }

    BuilderState <|-- Empty
    BuilderState <|-- HasModel
    BuilderState <|-- Complete
    LLMClientBuilder ..> BuilderState: S < BuilderState
    note for LLMClientBuilder "Phantom type S tracks builder state at compile time"

FP approach (Phantom types for compile-time safety):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

sealed trait BuilderState

sealed trait Empty extends BuilderState

sealed trait HasModel extends BuilderState

sealed trait Complete extends BuilderState

class LLMClientBuilder[S <: BuilderState] private(model: Option[ModelName], apiKey: Option[ApiKey]) {
  // Only available when Empty
  def withModel(m: ModelName)(implicit ev: S =:= Empty): LLMClientBuilder[HasModel] =
    new LLMClientBuilder[HasModel](Some(m), apiKey)

  // Only available when HasModel
  def withApiKey(k: ApiKey)(implicit ev: S =:= HasModel): LLMClientBuilder[Complete] =
    new LLMClientBuilder[Complete](model, Some(k))

  // Only available when Complete
  def build()(implicit ev: S =:= Complete): Result[LLMClient] =
    for {
      m <- model.toRight(ConfigError("Missing model"))
      k <- apiKey.toRight(ConfigError("Missing API key"))
    } yield OpenAIClient(OpenAIConfig(m, k))
}

// Usage: compile-time safety
val client = LLMClientBuilder.empty()
  .withModel(m)
  .withApiKey(k)
  .build() // OK

// val bad = LLMClientBuilder.empty().build()  // COMPILE ERROR

What’s happening here?

• S <: BuilderState is a phantom type: it exists only at compile time to track which steps you’ve done.
• The implicit ev: S =:= ... constraints make illegal calls (like .build() too early) fail at compile time.
• build() still returns Result[LLMClient] because “builder complete” is not the same thing as “config valid”.

Review checklist

• Builder is immutable (returns new instance, doesn’t mutate)
• build() returns Result[T] for validation
• Required fields enforced at compile time (phantom types) or runtime (validation)
• Builder doesn’t have 10+ methods (split into multiple builders if needed)

Singleton pattern: object in Scala

Singletons, in one diagram: object is fine for stateless shared wiring, but domain code should still depend on abstractions (DI) instead of reaching for globals.

flowchart LR
    subgraph Domain["Domain (core)"]
        Service["Service (depends on trait)"]
        Client["LLMClient (trait)"]
    end

    subgraph Wiring["Wiring (edge)"]
        Live["OpenAIClient (impl)"]
        Registry["ToolRegistry (object)"]
    end

    Service -->|depends on| Client
    Live -->|implements| Client
    Registry --> Service
    style Service fill:#e1f5ff,stroke:#0066cc,color:#000
    style Client fill:#fff4e1,stroke:#cc8800,color:#000
    style Live fill:#e1ffe1,stroke:#2d7a2d,color:#000
    style Registry fill:#f0e1ff,stroke:#8800cc,color:#000

OOP approach (Java singleton, avoid in Scala):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Classic Java singleton (don't do this in Scala)
class MySingleton private() {
  // ...
}

object MySingleton {
  private val instance = new MySingleton()

  def getInstance(): MySingleton = instance
}

What’s happening here?

• You’re manually recreating something Scala already gives you with object.
• It also nudges you towards hidden global state, which makes testing painful.

Scala approach (object is already a singleton):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// object is singleton by definition
object ToolRegistry {
  def empty: ToolRegistry = new ToolRegistry(Seq.empty)

  // Predefined singletons
  val core: ToolRegistry = new ToolRegistry(BuiltinTools.core)
  val safe: ToolRegistry = new ToolRegistry(BuiltinTools.safe())
}

// No getInstance() needed, just use the object
val registry = ToolRegistry.core

What’s happening here?

• object is a single instance by definition, so callers just refer to it directly.
• Keep objects either stateless or holding immutable state; if you need mutation, isolate and synchronize it.

Review checklist

• Use object for singletons, not class with private constructor
• Singleton objects are stateless or have immutable state
• If mutable state needed, synchronize access or use Ref/Atomic

Strategy pattern: ADTs + pattern matching

classDiagram
    class ToolExecutionStrategy {
        <<sealedtrait>>
    }

    class Sequential {
        <<caseobject>>
    }

    class Parallel {
        <<caseobject>>
    }

    class ParallelWithLimit {
        +maxConcurrent: Int
    }

    class ToolRegistry {
        +executeAll(requests, strategy) AsyncResult
    }

    ToolExecutionStrategy <|-- Sequential
    ToolExecutionStrategy <|-- Parallel
    ToolExecutionStrategy <|-- ParallelWithLimit
    ToolRegistry ..> ToolExecutionStrategy: "pattern matches on"
    note for ToolExecutionStrategy "Adding new strategy = adding new case class"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// ADT represents all strategies
sealed trait ToolExecutionStrategy

object ToolExecutionStrategy {
  case object Sequential extends ToolExecutionStrategy

  case object Parallel extends ToolExecutionStrategy

  case class ParallelWithLimit(maxConcurrent: Int) extends ToolExecutionStrategy
}

// Pattern matching dispatches to implementation
def executeAll(requests: Seq[ToolCallRequest], strategy: ToolExecutionStrategy)
              (implicit ec: ExecutionContext): AsyncResult[Seq[Result[String]]] = {
  strategy match {
    case ToolExecutionStrategy.Sequential => executeSequential(requests)
    case ToolExecutionStrategy.Parallel => executeParallel(requests)
    case ToolExecutionStrategy.ParallelWithLimit(n) => executeWithLimit(requests, n)
  }
}

What’s happening here?

• The “strategy” is data (a sealed ADT), not a subtype hierarchy with overridden methods.
• Dispatch stays explicit in one place (match), and Scala enforces exhaustiveness when you add a new strategy.

Why ADTs are better for Strategy:

• OCP: Add new strategy by adding case to sealed trait
• Exhaustiveness: Compiler ensures all strategies handled
• No runtime polymorphism: Direct dispatch, better performance
• Serializable: ADTs can be serialized (strategies as data)

Review checklist

• Strategy is sealed trait (exhaustive matching)
• Strategies are immutable case objects/classes
• Pattern matching covers all cases (no wildcard unless justified)
• New strategy doesn’t require modifying existing strategies

State pattern: ADT + immutable state with copy

stateDiagram-v2
    [*] --> InProgress: Agent started
    InProgress --> WaitingForTools: Tool call requested
    WaitingForTools --> InProgress: Tools executed
    InProgress --> Complete: Task finished
    InProgress --> Failed: Error occurred
    WaitingForTools --> Failed: Tool error
    Complete --> [*]
    Failed --> [*]
    note right of InProgress: Each transition returns new AgentState
    note right of WaitingForTools: Pure functions, no mutation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// ADT for status
sealed trait AgentStatus

case object InProgress extends AgentStatus

case object WaitingForTools extends AgentStatus

case object Complete extends AgentStatus

case class Failed(error: LLMError) extends AgentStatus

// Immutable state with pure transitions
case class AgentState(conversation: Conversation, status: AgentStatus, step: Int, toolCalls: Seq[ToolCallRequest]) {
  // Pure state transitions
  def addMessage(msg: Message): AgentState =
    copy(conversation = conversation.addMessage(msg))

  def nextStep: AgentState =
    copy(step = step + 1)

  def markComplete: AgentState =
    copy(status = AgentStatus.Complete)

  def requestTools(calls: Seq[ToolCallRequest]): AgentState =
    copy(status = AgentStatus.WaitingForTools, toolCalls = calls)
}

What’s happening here?

• You model state as data (AgentState) plus a closed set of statuses (AgentStatus).
• Every transition returns a new value via copy, so you can test transitions as pure functions and avoid “who mutated this?” bugs.

Why ADTs + immutable state are better:

• Immutability: State transitions return new state, don’t mutate
• Pattern matching: Explicit handling of all states
• Serializable: Can save/restore agent state
• Testable: Pure functions, easy to test transitions

Review checklist

• State is represented as sealed ADT
• State transitions are pure functions (return new state)
• No mutable state fields (use copy for updates)
• Illegal transitions return error or are no-ops

Adapter pattern: type classes

classDiagram
    class LLMClient {
        <<trait>>
        +complete(Conversation) Result~Completion~
    }

    class ThirdPartyLLM {
        <<externalAPI>>
        +generate(String) String
    }

    class LLMClientAdapter {
        -thirdParty: ThirdPartyLLM
        +complete(Conversation) Result~Completion~
    }

    class JsonWriter~A~ {
        <<typeclass>>
        +write(A) ujson.Value
    }

    LLMClient <|.. LLMClientAdapter
    LLMClientAdapter o-- ThirdPartyLLM: wraps

note for JsonWriter~A~ "Type class: adapts without inheritance"

OOP approach (classic Adapter):