llm4s Master review guidelines

Version: 0.9 Last Updated: 2026-01-30 Purpose: Single source of truth for CI PR review bots and human reviewers

Table of contents

1. Repo Map
2. Review Principles for llm4s
3. PR Review Workflow (CI Playbook)
4. Code Review Checklist (llm4s specific)
5. API and Design Review Checklist
6. Architecture Review Checklist
7. FP Patterns in llm4s
8. Design Patterns in llm4s
9. SOLID in llm4s
10. Testing Strategy Review
11. Documentation Review
12. Build, Release, CI, DevOps Review
13. Security and Dependency Hygiene
14. Performance and Resource Safety
15. Common PR Smells and How to Comment
16. Mermaid Diagrams in Reviews

• Appendix A: Comment Templates
• Appendix B: llm4s Examples Index
• Appendix C: Advanced FP Patterns Reference
• Appendix D: Changelog

1. Repository map

1.1 Module structure

 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

1.2 Key public API surfaces

1.3 Architecture invariants

Error Model: Result[A] = Either[LLMError, A] everywhere. No exceptions in domain logic.

Configuration Boundary: Core code never reads env vars or config directly. All config reads happen in org.llm4s.config. Enforced by Scalafix.

Purity Boundary: IO (HTTP, filesystem, time, randomness) stays at edges. Core logic is pure transformations.

Type safety: Use newtypes (ModelName, ApiKey, ConversationId) to prevent confusion. ApiKey.toString is always redacted.

Cross-build: Scala 2.13.16 and Scala 3.7.1. Single shared source tree with ScalaCompat for tiny shims. Version-specific code goes in src/main/scala-2.13 or src/main/scala-3.

1.4 Scalafix enforcements

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

2. Review principles for llm4s

2.1 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.

2.2 PR quality bar

A good PR 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

2.3 What to review rigorously

3. PR review workflow (CI playbook)

3.1 CI review bot contract

When analyzing a PR, the CI bot MUST produce:

Required outputs

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

Mermaid diagram policy for CI bot

The CI bot MAY include Mermaid diagrams in comments when they materially improve clarity over plain text:

MUST:

• Include 1-2 line plain-text summary above the diagram
• Cite PR diff file path + line range
• Reference the relevant guideline section
• Keep diagrams small (<10 nodes)
• Use semantic color coding (see section 16)
• Validate diagram renders correctly in GitHub

MUST NOT:

• Use diagrams for trivial logic explainable in 1-2 sentences
• Create diagrams with >10 nodes (too large for PR comments)
• Post multiple diagrams in a single comment (overwhelming)
• Use diagrams to restate obvious code structure

Use diagrams for:

• Complex control flow with multiple error paths
• Unclear async/cancellation semantics (sequence diagrams)
• State machine transitions with missing cases
• Architecture boundary violations spanning multiple files

See Section 16: Mermaid Diagrams in Reviews for templates and examples.

3.2 Severity rubric

3.3 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`

3.4 Bot prompt template

 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

You are a Scala code reviewer for the llm4s project.

Load the review guidelines from: docs/internals/code-review-guidelines/MASTER_REVIEW_GUIDELINES.md

Analyze the PR diff provided. For each file changed:

1. Check against the guidelines in this document
2. Focus on correctness, safety, and pattern adherence
3. Ignore formatting (scalafmt handles that)
4. Cite specific guideline sections by name

Produce the outputs specified in "CI Review Bot Contract":

- PR Summary
- Risk Assessment table
- Must-Fix findings (Blocker/Must-Fix severity)
- Should-Fix findings
- Optional questions

For each finding, include:

- Severity level
- Guideline section reference
- File path and line range
- Clear explanation of issue
- Concrete suggestion to fix

4. Code review checklist (llm4s specific)

4.1 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))
}

4.2 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)
}

4.3 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)}"
}

4.4 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

Review aid: If control flow spans >5 cases or has unclear decision paths, consider requesting a Mermaid flowchart showing all branches (see section 16).

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"
  }
}

4.5 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)

4.6 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

def run(
...): 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

5. API and design review checklist

5.1 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)

5.2 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"))
    }
}

5.3 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 = ()
}

6. Architecture review checklist

6.1 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

6.2 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)

Review aid: If async/cancellation semantics are unclear across module boundaries, consider requesting a Mermaid sequence diagram showing call order and cleanup paths (see section 16).

6.3 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)
  }

6.4 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

7. FP patterns in llm4s

Advanced Patterns: See Appendix C for detailed coverage of advanced patterns including MonadError, Validated, Type Classes, Variance, and more.

7.1 Preferred patterns

7.2 Avoided patterns in core

7.3 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

8. Design patterns in llm4s

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 and Cats patterns.

Philosophy: Use the simplest pattern that solves the problem. Prefer FP (ADTs, type classes, monads) for data transformation and composition. Use OOP (traits, classes) for stateful components and external integrations.

8.0 Unified pattern philosophy: How all patterns work together

llm4s uses a hybrid approach where SOLID Principles, Design Patterns (Creational, Structural, Behavioral), * FP Patterns*, Type Classes, Phantom Types, and Cats Patterns support and strengthen each other. This section shows how they integrate cohesively with 100% precision, using real llm4s code and textbook snippets where applicable.

8.0.1 The pattern spectrum

Patterns exist on a continuum. Use the appropriate paradigm based on the problem domain, with SOLID principles guiding all zones:

1
2
3
4
5
6
7

Pure FP ←──────────── Hybrid ──────────→ Pure OOP
   │                     │                    │
ADTs, Monads      Smart Constructors    Mutable State,
Type Classes      + Builder Pattern     Inheritance Trees
Immutable         Phantom Types         Imperative Logic
   │                     │                    │
SOLID: SRP, ISP   SOLID: All 5          SOLID: LSP, DIP

Guidelines:

• Pure FP (Left): Data transformations, validation, business logic, parsing

  • Examples: Result[A], Conversation, CompletionOptions, guardrails
  • Patterns: ADTs (C.1), Type Classes (C.4), Monads (C.11), Pattern Matching (C.2)
  • SOLID alignment: SRP (pure functions do one thing), ISP (type classes as focused interfaces)

  1 2 3 4 5 6 7 8

  // SRP: Each function has single responsibility def parseMessage(json: String): Result[Message] = ??? def validateMessage(msg: Message): Result[Message] = ??? def enrichMessage(msg: Message): Result[Message] = ??? // ISP: Type classes provide focused interfaces trait Show[A] { def show(a: A): String } // Only show, nothing else implicit val showMessage: Show[Message] = msg => msg.content

• Hybrid (Center): Object construction, resource management, external integrations

  • Examples: LLMClient trait + concrete providers, Agent, ToolRegistry
  • Patterns: Factory + Smart Constructors, Builder + Phantom Types, Adapter + Type Classes
  • SOLID alignment: All 5 principles apply (DIP for abstraction, OCP for extension, LSP for substitution)

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

  // DIP: Depend on LLMClient trait, not concrete OpenAIClient class Agent(client: LLMClient) { // ← abstraction, not concretion def run(query: String): Result[AgentState] = ??? } // OCP: Extend via new case, don't modify existing code sealed trait ProviderConfig case class OpenAIConfig(...) extends ProviderConfig case class AnthropicConfig(...) extends ProviderConfig // Adding GeminiConfig doesn't modify existing classes // LSP: All LLMClient implementations are substitutable val openAI: LLMClient = OpenAIClient(config) val anthropic: LLMClient = AnthropicClient(config) // Both work identically in Agent(client)

• Pure OOP (Right): Stateful systems, plugin architectures, legacy integrations

  • Examples: Rare in llm4s - only when external APIs demand it
  • Patterns: Use sparingly, wrap in Resource[F, _] for safety
  • SOLID alignment: LSP (subtype substitution), DIP (depend on interfaces)

  1 2 3 4 5 6 7 8 9 10

  // LSP: Subtypes must honor base type contracts trait ResourceManager { def acquire(): Unit def release(): Unit // MUST be called, else resource leak } class FileManager extends ResourceManager { def acquire(): Unit = openFile() def release(): Unit = closeFile() // Honors contract }

8.0.2 Pattern synergies: Combinations that strengthen each other

Each combination shows how Design Patterns, FP Patterns, Type Classes, Cats Patterns, and SOLID principles reinforce each other:

8.0.3 Pattern hierarchy: Dependencies and relationships

This diagram shows how SOLID principles connect to all major pattern families:

graph TB
%% SOLID as foundation
    SOLID[SOLID Principles §9]
SRP[SRP: Single Responsibility]
OCP[OCP: Open/Closed]
LSP[LSP: Liskov Substitution]
ISP[ISP: Interface Segregation]
DIP[DIP: Dependency Inversion]

SOLID --> SRP
SOLID --> OCP
SOLID --> LSP
SOLID --> ISP
SOLID --> DIP

%% ADTs and Pattern Matching
ADT[ADTs C.1] --> PM[Pattern Matching C.2]
ADT --> SmartCtor[Smart Constructors C.3]
ADT --> Strategy[Strategy Pattern 8.4.1]
OCP -.-> ADT
OCP -.-> Strategy

%% Type Classes
TC[Type Classes C.4] --> Implicits[Implicits C.5]
TC --> Adapter[Adapter Pattern 8.3.1]
ISP -.-> TC
ISP -.-> Adapter

%% Phantom Types and Builders
Phantom[Phantom Types C.30] --> Builder[Builder Pattern 8.2.2]
Phantom --> TypeSafety[Compile-time Safety]
SRP -.-> Builder

%% Monads and Effect Types
Monads[Monads C.11] --> Result[Result Type]
Monads --> StateMonad[State Monad C.16]
Monads --> Kleisli[Kleisli C.15]
SRP -.-> StateMonad

%% Higher-Order Functions
HOF[Higher-Order Functions] --> Decorator[Decorator Pattern 8.3.2]
SRP -.-> Decorator

%% Factory and Abstraction
Factory[Factory Pattern 8.2.1] --> SmartCtor
DIP -.-> Factory

%% Composite and Inheritance
Composite[Composite Pattern 8.3.3]
LSP -.-> Composite

%% Cats Patterns
Cats[Cats Patterns] --> Validated[Validated C.12]
Cats --> EitherT[EitherT C.13]
Cats --> Semigroup[Semigroup C.17]

style SOLID fill: #f5e1ff, stroke:#8800cc, stroke-width: 3px
style SRP fill:#f5e1ff, stroke: #8800cc
style OCP fill:#f5e1ff, stroke: #8800cc
style LSP fill:#f5e1ff, stroke: #8800cc
style ISP fill:#f5e1ff, stroke: #8800cc
style DIP fill:#f5e1ff, stroke: #8800cc
style ADT fill:#e1f5ff, stroke: #0066cc
style TC fill:#e1ffe1, stroke: #00cc00
style Phantom fill:#fff5e1, stroke: #cc8800
style Monads fill:#ffe1f5, stroke: #cc0088

Key relationships:

• SRP → Builder (each step single concern), Decorator (each decorator one job), State Monad (pure transformations)
• OCP → ADTs (extend via new cases), Strategy (add strategies without modification)
• LSP → Composite (leaf/composite substitutable), all trait implementations
• ISP → Type Classes (focused interfaces), Adapter (minimal interface exposure)
• DIP → Factory (return abstractions), all dependency injection patterns

8.0.4 When to use which paradigm (with SOLID guidance)

Use Pure FP when:

• ✅ Transforming data (parsing, validation, serialization)
• ✅ Composing operations (pipelines, workflows)
• ✅ Testing is critical (pure functions are trivial to test)
• ✅ Immutability is required (concurrency, distributed systems)
• ✅ Error handling needs to be explicit (Result, Validated)

SOLID principles in Pure FP:

• SRP: Each pure function does exactly one thing
• ISP: Type classes provide minimal, focused interfaces

Examples with SOLID:

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

// SRP: Single responsibility per function
def parseConfig(json: String): Result[Config] = ??? // Only parse
def validateConfig(cfg: Config): Result[Config] = ??? // Only validate
def applyDefaults(cfg: Config): Config = ??? // Only apply defaults

// ISP: Focused type class interfaces
trait Encoder[A] {
  def encode(a: A): String
} // Only encoding

trait Decoder[A] {
  def decode(s: String): Result[A]
} // Only decoding
// Not: trait Codec[A] { def encode...; def decode...; def validate... } ❌

Use Hybrid (FP + OOP) when:

• ✅ Building complex objects (builders with phantom types)
• ✅ External integrations (wrap imperative APIs in functional interfaces)
• ✅ Polymorphic behavior (traits with ADT-based dispatch)
• ✅ Resource management (traits with Resource[F, _] semantics)

SOLID principles in Hybrid:

• DIP: Depend on traits (abstractions), not concrete classes
• OCP: Extend via new implementations, don’t modify existing code
• LSP: All trait implementations must be substitutable

Examples with SOLID:

 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

// DIP: Depend on abstraction (LLMClient trait), not concretion
trait LLMClient {
  def complete(conv: Conversation): Result[Completion]
}

class Agent(client: LLMClient) { // ← Depends on trait, not OpenAIClient
  def run(query: String): Result[AgentState] = ???
}

// OCP: Add new provider without modifying Agent
class OpenAIClient extends LLMClient {
...
}

class AnthropicClient extends LLMClient {
...
}

class GeminiClient extends LLMClient {
...
} // ← Extension, not modification

// LSP: All implementations honor LLMClient contract
val agent1 = Agent(OpenAIClient(..
.) ) // Works
val agent2 = Agent(AnthropicClient(..
.) ) // Works identically
val agent3 = Agent(GeminiClient(..
.) ) // Works identically

Use Pure OOP when:

• ⚠️ External library demands it (rare in llm4s)
• ⚠️ Stateful plugin systems (wrap in Resource[F, _] for safety)
• ⚠️ Legacy integrations (create thin adapter, keep functional core)

SOLID principles in Pure OOP:

• LSP: Subclasses must honor superclass contracts (preconditions, postconditions, invariants)
• All 5: OOP benefits most from strict SOLID adherence

Example with SOLID:

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

// LSP: Subclass honors base class contract
abstract class Connection {
  def open(): Unit

  def close(): Unit // MUST be idempotent (calling twice is safe)

  def isOpen: Boolean
}

class HttpConnection extends Connection {
  def open(): Unit = if (!isOpen) openSocket()

  def close(): Unit = if (isOpen) closeSocket() // ✅ Idempotent, honors contract

  def isOpen: Boolean = socket.isDefined
}

// ❌ LSP violation:
class BadConnection extends Connection {
  def close(): Unit = throw new Exception("Can't close!") // Breaks contract!
}

Anti-patterns (SOLID violations):

• ❌ Deep inheritance hierarchies (violates SRP, OCP, LSP)
• ❌ Mutable state without synchronization (violates SRP, hard to test)
• ❌ God objects with many responsibilities (violates SRP, ISP)
• ❌ Depending on concrete classes (violates DIP)
• ❌ Modifying existing code to add features (violates OCP)

8.0.5 Pattern composition principles (with SOLID integration)

Principle 1: Pure core, imperative shell (aligns with SRP, DIP)

Keep business logic pure (FP), push side effects to boundaries (OOP/hybrid). Each layer has single responsibility.

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

// Pure core: business logic (SRP - validation is its only job)
def validateMessage(msg: Message): Result[Message] =
  if (msg.content.nonEmpty) Right(msg)
  else Left(LLMError.ValidationError("Empty message"))

// Imperative shell: I/O operations (DIP - depends on LLMClient abstraction)
class Agent(client: LLMClient) { // ← DIP: trait, not concrete class
  def run(query: String, tools: ToolRegistry): Result[AgentState] = {
    for {
      msg <- validateMessage(Message.user(query)) // FP: pure validation (SRP)
      response <- client.complete(Conversation(msg)) // OOP: side effect (DIP)
    } yield AgentState.fromResponse(response) // FP: pure transformation (SRP)
  }
}

// SOLID benefits:
// - SRP: Pure functions have single, testable responsibility
// - DIP: Shell depends on abstractions (LLMClient trait)
// - OCP: Add new validators without modifying Agent

Principle 2: Compose small patterns, not large frameworks (aligns with SRP, ISP, OCP)

Prefer small, composable patterns over large abstractions. Each component does one thing well.

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

// ✅ GOOD: Small, composable (SRP - each decorator single job, ISP - minimal interface)
val withRetry: (=> Result[A]) => Result[A] = op => // SRP: Only retries
  Try(op).recoverWith { case _ => Try(op) }.toResult

val withLogging: (=> Result[A]) => Result[A] = op => // SRP: Only logs
{
  println("Starting...");
  val r = op;
  println(s"Result: $r");
  r
}

// Compose them (OCP - extend behavior without modifying functions)
val safeClient = withRetry(withLogging(client.complete(conv)))

// ❌ BAD: Large framework (violates SRP, ISP - God object)
class MegaClientWrapper extends BaseClient
  with RetryMixin // Retry logic
  with LoggingMixin // Logging logic
  with CachingMixin // Caching logic
  with MetricsMixin // Metrics logic
  with

... // ← Violates SRP (many responsibilities), ISP (fat interface)

Principle 3: Use types to prevent errors, not just document them (aligns with LSP, OCP)

Phantom types, ADTs, and smart constructors make invalid states unrepresentable. Type system enforces correctness.

 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
35
36
37
38
39
40
41
42
43

// ✅ GOOD: Phantom types prevent invalid builder states (LSP - type-safe substitution)
sealed trait BuilderState

sealed trait Empty extends BuilderState

sealed trait HasModel extends BuilderState

sealed trait Complete extends BuilderState

class LLMClientBuilder[State <: BuilderState] private(
                                                       model: Option[ModelName],
                                                       apiKey: Option[ApiKey]
                                                     ) {
  def withModel(m: ModelName): LLMClientBuilder[HasModel] =
    new LLMClientBuilder[HasModel](Some(m), apiKey)

  def withApiKey(k: ApiKey): LLMClientBuilder[Complete] =
    new LLMClientBuilder[Complete](model, Some(k))

  // Only builds if State is Complete (compile-time check)
  def build()(implicit ev: State =:= Complete): Result[LLMClient] =
    OpenAIClient(model.get, apiKey.get) // Safe - guaranteed present by types
}

// Usage:
val builder = new LLMClientBuilder[Empty](None, None)
builder.build() // ❌ Compile error: State =:= Empty, not Complete
val configured = builder.withModel(ModelName("gpt-4")).withApiKey(ApiKey("sk-..."))
configured.build() // ✅ Compiles: State =:= Complete

// ❌ BAD: Runtime validation (violates LSP - can fail at runtime)
class LLMClientBuilder {
  private var model: Option[ModelName] = None

  def withModel(m: ModelName): this.type = {
    model = Some(m);
    this
  }

  def build(): Result[LLMClient] =
    if (model.isEmpty) Left(Error("Model not set")) // Runtime check!
    else OpenAIClient(model.get)
}

Principle 4: Fail fast at compile time, recover gracefully at runtime (aligns with OCP, SRP)

Use types to catch errors early (compile-time); use Result/Validated to handle runtime failures gracefully.

 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

// Compile-time: sealed trait ensures exhaustive matches (OCP - add cases without modification)
sealed trait ProviderConfig // OCP: closed for modification

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

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

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

// Exhaustive match - compiler warns if we miss a case
def buildClient(config: ProviderConfig): Result[LLMClient] =
  config match {
    case cfg: OpenAIConfig => OpenAIClient(cfg) // ✅ All cases covered
    case cfg: AnthropicConfig => AnthropicClient(cfg)
    case cfg: GeminiConfig => GeminiClient(cfg)
  } // Adding new case class forces us to handle it here

// Runtime: Result for graceful error handling (SRP - each validator single job)
def parseApiKey(s: String): Result[ApiKey] =
  if (s.startsWith("sk-")) Right(ApiKey(s))
  else Left(LLMError.ConfigError(s"Invalid API key format: $s"))

def validateModel(m: String): Result[ModelName] =
  if (m.nonEmpty) Right(ModelName(m))
  else Left(LLMError.ConfigError("Model name cannot be empty"))

// Compose validations (SRP - each function single responsibility)
def parseProviderConfig(json: String): Result[ProviderConfig] =
  for {
    parsed <- parseJson(json) // SRP: Only parses JSON
    apiKey <- parseApiKey(parsed.apiKey) // SRP: Only validates API key
    model <- validateModel(parsed.model) // SRP: Only validates model
  } yield OpenAIConfig(apiKey, model)

SOLID benefits across all principles:

• SRP: Each function/class has single, clear responsibility
• OCP: Extend via new types/functions, not modification
• LSP: Type-safe substitution (phantom types, trait implementations)
• ISP: Small, focused interfaces (HOFs, type classes) instead of fat interfaces
• DIP: Depend on abstractions (traits, ADTs), not concrete implementations

8.0.6 Pattern anti-synergies: Combinations to avoid (with SOLID violations)

8.0.7 Pattern review decision tree (with SOLID checkpoints)

Use this flowchart when reviewing code to decide which pattern to recommend. Each path includes relevant SOLID principles.

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 -->|Modifying Code| ApplyOCP[Violates OCP<br/>Extend, don't modify]
    CheckSOLID -->|Fat Interface| ApplyISP[Violates ISP<br/>Split interfaces]
    CheckSOLID -->|No Violations| Question1{Is it data<br/>transformation?}
    Question1 -->|Yes| FP[Use Pure FP:<br/>ADTs C.1, Pattern Matching C.2,<br/>Monads C.11<br/><b>SOLID: SRP</b>]
    Question1 -->|No| Question2{Is it object<br/>construction?}
    Question2 -->|Yes| Question3{Complex validation<br/>or many params?}
    Question3 -->|Yes| Builder[Use Builder + Phantom Types<br/>§8.2.2, C.30<br/><b>SOLID: SRP each step</b>]
Question3 -->|No|Factory[Use Factory + Smart Constructors<br/>§8.2.1, C.3<br/><b>SOLID: DIP return trait</b>]

Question2 -->|No|Question4{Is it external<br/>integration?}

Question4 -->|Yes|Question5{Adapting<br/>external types?}
Question5 -->|Yes|TypeClass[Use Type Classes<br/>§8.3.1, C.4<br/><b>SOLID: ISP focused interfaces</b>]
Question5 -->|No|Wrapper[Use Adapter Pattern<br/>+ Resource F, _<br/><b>SOLID: DIP wrap in abstraction</b>]

Question4 -->|No|Question6{Is it polymorphic<br/>behavior?}

Question6 -->|Yes|Question7{Fixed set<br/>of types?}
Question7 -->|Yes| ADT[Use ADTs + Pattern Matching<br/>§8.4.1, C.1, C.2<br/><b>SOLID: OCP add cases</b>]
Question7 -->|No|TraitDispatch[Use Trait + OOP Dispatch<br/>with SOLID §9<br/><b>SOLID: LSP substitution</b>]

Question6 -->|No|Question8{Is it composable<br/>operations?}

Question8 -->|Yes|HOF[Use Higher-Order Functions<br/>+ Kleisli C.15<br/><b>SOLID: SRP each function</b>]
Question8 -->|No|Question9{Is it state<br/>management?}

Question9 -->|Yes|StateMonad[Use State Monad<br/>C.16<br/><b>SOLID: SRP pure transformations</b>]
Question9 -->|No|Question10{Is it error<br/>handling?}

Question10 -->|Yes|Question11{Single error<br/>or multiple?}
Question11 -->|Single|ResultType[Use Result Type<br/>Either LLMError, A<br/><b>SOLID: SRP error handling</b>]
Question11 -->|Multiple|ValidatedNel[Use ValidatedNel<br/>C.12<br/><b>SOLID: SRP accumulate errors</b>]

Question10 -->|No|ReviewSOLID[Apply SOLID Principles<br/>§9 in depth]

style Start fill: #e1f5ff, stroke: #0066cc
style CheckSOLID fill: #f5e1ff, stroke: #8800cc, stroke-width:3px
style SplitSRP fill: #ffe1e1, stroke:#cc0000
style ApplyDIP fill: #ffe1e1, stroke:#cc0000
style ApplyOCP fill: #ffe1e1, stroke:#cc0000
style ApplyISP fill: #ffe1e1, stroke:#cc0000
style FP fill: #e1ffe1, stroke:#00cc00
style Builder fill: #fff5e1, stroke:#cc8800
style Factory fill: #fff5e1, stroke:#cc8800
style TypeClass fill: #ffe1f5, stroke:#cc0088
style ADT fill: #e1ffe1, stroke:#00cc00
style StateMonad fill: #ffe1f5, stroke:#cc0088
style ResultType fill: #ffe1f5, stroke:#cc0088
style ValidatedNel fill: #ffe1f5, stroke:#cc0088
style ReviewSOLID fill: #f5e1ff, stroke:#8800cc

How to use this tree:

1. Start by checking SOLID violations - If code violates SRP, OCP, LSP, ISP, or DIP, address those first
2. Follow the decision path - Each recommendation includes relevant SOLID principle
3. Verify SOLID alignment - Ensure chosen pattern doesn’t introduce new violations
4. Compose patterns - Many solutions combine multiple patterns (e.g., Factory + DIP, Builder + SRP)

8.0.8 Pattern maturity model: Learning progression (with SOLID integration)

Level 1: Beginner (Focus: Type safety, immutability, SOLID fundamentals)

• ✅ Master: ADTs (C.1), Pattern Matching (C.2), Smart Constructors (C.3)
• ✅ Master: Result type, Option, Either
• ✅ Master: Immutable collections, copy() for updates
• ✅ Master: SOLID: SRP and DIP - single responsibility functions, depend on traits
• 📖 Review: Factory pattern (§8.2.1), basic type classes (C.4), OCP basics

Code snippet (Beginner level):

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

// SRP: Each function single responsibility
def parseJson(s: String): Result[JsonValue] = ???
def validateConfig(json: JsonValue): Result[Config] = ???

// DIP: Depend on trait, not concrete class
trait Storage {
  def save(data: String): Result[Unit]
}

class Service(storage: Storage) { // ← DIP: inject abstraction
  def process(input: String): Result[Unit] =
    for {
      json <- parseJson(input) // SRP: only parse
      config <- validateConfig(json) // SRP: only validate
      _ <- storage.save(config.toString) // DIP: trait, not FileStorage
    } yield ()
}

Level 2: Intermediate (Focus: Composition, abstraction, SOLID in practice)

• ✅ Master: Type Classes (C.4), Implicits (C.5), Higher-Order Functions
• ✅ Master: for-comprehensions (C.6), Monads (C.11)
• ✅ Master: Builder pattern + Phantom Types (§8.2.2, C.30)
• ✅ Master: SOLID: ISP and OCP - focused interfaces, extend without modification
• 📖 Review: Adapter/Decorator patterns (§8.3), Strategy pattern (§8.4.1), LSP

Code snippet (Intermediate level):

 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

// ISP: Focused type class interfaces
trait Encoder[A] {
  def encode(a: A): String
} // Only encode

trait Decoder[A] {
  def decode(s: String): Result[A]
} // Only decode

// OCP: Extend via new cases, don't modify existing code
sealed trait ValidationRule

case class LengthRule(min: Int, max: Int) extends ValidationRule

case class RegexRule(pattern: String) extends ValidationRule
// Adding new rule doesn't modify existing validators

def validate(input: String, rules: Seq[ValidationRule]): Result[String] =
  rules.foldLeft[Result[String]](Right(input)) { (acc, rule) =>
    acc.flatMap { s =>
      rule match { // OCP: exhaustive, compiler warns on new cases
        case LengthRule(min, max) if s.length >= min && s.length <= max => Right(s)
        case RegexRule(p) if s.matches(p) => Right(s)
        case _ => Left(LLMError.ValidationError(s"Failed rule: $rule"))
      }
    }
  }

Level 3: Advanced (Focus: Type-level programming, effect systems, SOLID mastery)

• ✅ Master: EitherT/OptionT (C.13), Semigroup/Monoid (C.17)
• ✅ Master: F-Bounded Polymorphism (C.31), Self Types (C.29)
• ✅ Master: Lazy Evaluation (C.28), Currying/PAFs (C.27)
• ✅ Master: All 5 SOLID principles - apply reflexively to all code
• 📖 Review: All design patterns (§8.2-8.4), Tagless Final (C.20), Free Monads

Code snippet (Advanced level):

 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
35

// F-Bounded Polymorphism + LSP: Type-safe fluent API
trait Builder[A <: Builder[A]] {
  self: A =>
  def build(): Result[Config]

  def withTimeout(t: Int): A // Returns self type, not Builder
}

class ConfigBuilder extends Builder[ConfigBuilder] {
  private var timeout: Int = 30

  def withTimeout(t: Int): ConfigBuilder = {
    timeout = t;
    this
  }

  def build(): Result[Config] = Right(Config(timeout))
}

// LSP: All Builders substitutable, fluent API preserved
def configure[B <: Builder[B]](builder: B): B =
  builder.withTimeout(60) // Returns B, not Builder - type-safe!

// Tagless Final + DIP: Abstract over effect type
trait Logger[F[_]] {
  def log(msg: String): F[Unit]
}

class Service[F[_] : Monad](logger: Logger[F]) { // DIP: abstract Logger[F]
  def process(input: String): F[Result[String]] =
    for {
      _ <- logger.log(s"Processing: $input") // F[_] abstraction
      result <- Monad[F].pure(Right(input.toUpperCase))
    } yield result
}

Level 4: Expert (Focus: Architecture, domain modeling, pattern synergy, SOLID as second nature)

• ✅ Master: Type Members (C.32), Opaque Types (C.33 - Scala 3)
• ✅ Master: Reader/Writer Monads (C.18, C.19), Traverse (C.21)
• ✅ Master: Combining all patterns cohesively (this section!)
• ✅ Master: SOLID violations detection - spot and refactor anti-patterns instantly
• 📖 Review: Advanced Cats patterns (C.22-C.26), multi-paradigm architecture, domain-driven design

Code snippet (Expert level):

 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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

// Combining: Phantom Types + F-Bounded + Type Members + SOLID
sealed trait BuilderState

trait Incomplete extends BuilderState

trait Complete extends BuilderState

// F-Bounded + Phantom Types + SRP (each method single job)
trait ConfigBuilder[S <: BuilderState, Self <: ConfigBuilder[S, Self]] {
  self: Self =>
  type Out // Type member for configuration output

  def withModel(m: String): ConfigBuilder[Complete, Self]

  def build()(implicit ev: S =:= Complete): Result[Out]
}

// DIP + LSP: Depend on ConfigBuilder abstraction, all implementations substitutable
class Service[S <: BuilderState, B <: ConfigBuilder[S, B]](builder: B) {
  def configure(model: String): ConfigBuilder[Complete, B] =
    builder.withModel(model) // Type-safe state transition
}

// OCP: Extend via new implementations without modifying Service
class OpenAIBuilder extends ConfigBuilder[Incomplete, OpenAIBuilder] {
  type Out = OpenAIConfig
  private var model: Option[String] = None

  def withModel(m: String): ConfigBuilder[Complete, OpenAIBuilder] =
    new OpenAIBuilder {
      override type Out = OpenAIConfig;
      /* ... */}.asInstanceOf[ConfigBuilder[Complete, OpenAIBuilder]]

  def build()(implicit ev: Incomplete =:= Complete): Result[OpenAIConfig] =
    ??? // Won't compile - correctly enforces state
}

// ISP: Focused trait per concern
trait ModelConfigurable {
  def withModel(m: String): this.type
}

trait ApiKeyConfigurable {
  def withApiKey(k: String): this.type
}

trait Buildable[A] {
  def build(): Result[A]
}
// Clients only depend on what they need, not fat ConfigBuilder interface

Review Guidance by Level (with SOLID focus):

• Beginner PRs:

  • ✅ Ensure ADTs, pattern matching, Result usage
  • ✅ Check SRP - functions do one thing
  • ✅ Check DIP - inject dependencies via constructors, depend on traits
  • ⚠️ Suggest simpler alternatives if over-engineered
  • ⚠️ Flag global state, mutable vars, exceptions

• Intermediate PRs:

  • ✅ Look for proper abstraction (type classes, monads)
  • ✅ Ensure composition over inheritance
  • ✅ Check ISP - interfaces are focused, not fat
  • ✅ Check OCP - extending via new types, not modifying existing code
  • ⚠️ Flag tight coupling, concrete dependencies

• Advanced PRs:

  • ✅ Verify type-level constraints work correctly
  • ✅ Check for phantom type/F-bounded bugs
  • ✅ Verify LSP - all implementations honor contracts
  • ✅ Check all 5 SOLID principles applied correctly
  • ⚠️ Flag LSP violations (subtype breaks parent contract)

• Expert PRs:

  • ✅ Focus on architecture coherence
  • ✅ Ensure patterns support each other, not conflict (see §8.0.2, §8.0.6)
  • ✅ Verify SOLID mastery - no violations, elegant solutions
  • ✅ Check pattern synergies (Factory+DIP, Builder+SRP, etc.)
  • ⚠️ Flag unnecessary complexity, over-engineering

8.1 Pattern landscape in llm4s

8.2 Creational patterns

8.2.1 Factory pattern: Smart constructors + ADTs

OOP approach (classic Factory):

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

// Classic OOP factory with inheritance
abstract class LLMClientFactory {
  def createClient(): LLMClient
}

class OpenAIFactory extends LLMClientFactory {
  def createClient(): LLMClient = new OpenAIClient(.

..)
}

class AnthropicFactory extends LLMClientFactory {
  def createClient(): LLMClient = new AnthropicClient(.

..)
}

FP approach (Smart constructors + ADTs):

 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

// 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

// Smart constructor returns Result for validation
object ProviderConfig {
  def create(provider: String, model: String, key: String): Result[ProviderConfig] =
    (provider, model, key) match {
      case ("openai", m, k) =>
        for {
          modelName <- ModelName.create(m)
          apiKey <- ApiKey.create(k)
        } yield OpenAIConfig(modelName, apiKey)
      case _ => Left(ValidationError(s"Unknown provider: $provider"))
    }
}

// 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)
  }

llm4s hybrid approach (modules/core/src/main/scala/org/llm4s/llmconnect/LLMConnect.scala:10-46):

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

object LLMConnect {
  // Public factory method - returns Result for validation
  def getClient(config: ProviderConfig): Result[LLMClient] =
    Safety.safely(buildClient(config))

  // Private factory - ADT pattern matching
  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)
    }
}

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

8.2.2 Builder pattern: Phantom types vs currying

OOP approach (classic 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

// Mutable builder (classic Java style)
class LLMClientBuilder {
  private var model: Option[ModelName] = None
  private var apiKey: Option[ApiKey] = None

  def withModel(m: ModelName): LLMClientBuilder = {
    model = Some(m)
    this
  }

  def withApiKey(k: ApiKey): LLMClientBuilder = {
    apiKey = Some(k)
    this
  }

  def build(): LLMClient = {
    require(model.isDefined && apiKey.isDefined) // runtime check!
    new OpenAIClient(model.get, apiKey.get)
  }
}

// Usage: can call build() too early (runtime error)
val client = new LLMClientBuilder()
  .withModel(m)
  .build() // compiles but fails at runtime (missing apiKey)

FP approach 1 (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
33
34
35

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() // ERROR: won't compile

FP approach 2 (Currying for step-by-step configuration):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Curried constructor functions
def createClient(model: ModelName)
                (apiKey: ApiKey)
                (timeout: Duration): Result[LLMClient] =
  OpenAIClient(OpenAIConfig(model, apiKey, timeout))

// Partially apply for specialized factories
val createGPT4Client = createClient(ModelName("gpt-4"))(_: ApiKey)(_: Duration)
val createWithKey = createGPT4Client(myApiKey)(_: Duration)
val client = createWithKey(30.seconds)

llm4s approach (modules/core/src/main/scala/org/llm4s/toolapi/ToolFunction.scala:101-119):

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

// ToolBuilder uses type parameters for input/output
class ToolBuilder[T, R] {
  def withName(name: String): ToolBuilder[T, R] = ???

  def withDescription(desc: String): ToolBuilder[T, R] = ???

  def withFunction(f: T => Result[R]): ToolBuilder[T, R] = ???

  def withSchema(schema: Schema): ToolBuilder[T, R] = ???

  def build(): Result[ToolFunction[T, R]] = ???
}

// Usage
val tool = ToolBuilder[WeatherInput, WeatherOutput]()
  .withName("get_weather")
  .withDescription("Get weather for location")
  .withFunction(getWeather)
  .build()

When to use which:

• Phantom types: Complex builders with many steps, order matters (e.g., ToolBuilder, ClientBuilder)
• Currying: Simple configuration, partial application needed (e.g., factory presets)
• Case class with copy: Immutable config objects (e.g., CompletionOptions.copy(maxTokens = 100))

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)

8.2.3 Singleton pattern: object in Scala

OOP approach (Java singleton):

 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
}

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

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

8.3 Structural patterns

8.3.1 Adapter pattern: Type classes

OOP approach (classic Adapter):

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

// Third-party API we don't control
trait ThirdPartyLLM {
  def generate(prompt: String): String
}

// Adapter wraps third-party API to match our interface
class LLMClientAdapter(thirdParty: ThirdPartyLLM) extends LLMClient {
  def complete(conversation: Conversation, options: CompletionOptions): Result[Completion] = {
    val prompt = conversation.messages.map(_.content).mkString("\n")
    val response = thirdParty.generate(prompt)
    Right(Completion(Message.assistant(response)))
  }
}

FP approach (Type classes - see C.4):

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

// Type class defines the capability
trait JsonWriter[A] {
  def write(value: A): ujson.Value
}

// Instances adapt specific types
implicit val completionWriter: JsonWriter[Completion] = new JsonWriter[Completion] {
  def write(c: Completion): ujson.Value = ujson.Obj(
    "content" -> c.message.content,
    "role" -> c.message.role
  )
}

implicit val conversationWriter: JsonWriter[Conversation] = new JsonWriter[Conversation] {
  def write(c: Conversation): ujson.Value = ujson.Arr(
    c.messages.map(m => ujson.Obj("role" -> m.role, "content" -> m.content)): _*
  )
}

// Generic serialization function
def toJson[A: JsonWriter](value: A): ujson.Value =
  implicitly[JsonWriter[A]].write(value)

llm4s hybrid approach:

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

// Provider clients are adapters wrapping HTTP APIs
class OpenAIClient(config: OpenAIConfig) extends LLMClient {
  // Adapts OpenAI's HTTP API to LLMClient interface
  def complete(conversation: Conversation, options: CompletionOptions): Result[Completion] = {
    val requestBody = toOpenAIFormat(conversation, options) // adapt our format
    val response = httpClient.post("/v1/chat/completions", requestBody)
    fromOpenAIFormat(response) // adapt their format
  }

  private def toOpenAIFormat(conv: Conversation, opts: CompletionOptions): ujson.Value = ???

  private def fromOpenAIFormat(response: ujson.Value): Result[Completion] = ???
}

Why type classes are better for cross-cutting concerns:

• ISP: Clients only import the type class instances they need
• OCP: Add new type → add new instance, don’t modify existing code
• Composition: Type class instances compose (see Semigroup, Monoid)

Review checklist:

• Adapter wraps external API, not internal types
• Adapter translates data formats bidirectionally
• For serialization/validation, prefer type classes over adapters
• Adapter handles errors gracefully (returns Result)

8.3.2 Decorator pattern: Higher-order functions vs traits

OOP approach (classic Decorator):

 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
35
36
37
38
39

// Component interface
trait LLMClient {
  def complete(conversation: Conversation): Result[Completion]
}

// Concrete component
class OpenAIClient extends LLMClient {
  def complete(conversation: Conversation): Result[Completion] = ???
}

// Decorator adds behavior
class LoggingDecorator(client: LLMClient) extends LLMClient {
  def complete(conversation: Conversation): Result[Completion] = {
    println(s"Calling LLM with ${conversation.messages.size} messages")
    val result = client.complete(conversation)
    println(s"LLM returned: ${result.isRight}")
    result
  }
}

class CachingDecorator(client: LLMClient, cache: Cache) extends LLMClient {
  def complete(conversation: Conversation): Result[Completion] = {
    cache.get(conversation) match {
      case Some(cached) => Right(cached)
      case None =>
        val result = client.complete(conversation)
        result.foreach(c => cache.put(conversation, c))
        result
    }
  }
}

// Stack decorators
val client = new CachingDecorator(
  new LoggingDecorator(
    new OpenAIClient()
  ),
  cache
)

FP approach (Higher-order functions + Kleisli):

 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

// Function type alias
type LLMCall = Conversation => Result[Completion]

// Base function
val baseCall: LLMCall = conv => OpenAIClient(config).complete(conv)

// Decorators as HOFs
def withLogging(f: LLMCall): LLMCall = conv => {
  println(s"Calling LLM with ${conv.messages.size} messages")
  val result = f(conv)
  println(s"LLM returned: ${result.isRight}")
  result
}

def withCaching(cache: Cache)(f: LLMCall): LLMCall = conv => {
  cache.get(conv).map(Right(_)).getOrElse {
    val result = f(conv)
    result.foreach(c => cache.put(conv, c))
    result
  }
}

// Compose decorators
val decoratedCall: LLMCall = baseCall
  .pipe(withLogging)
  .pipe(withCaching(cache))

// Or with Kleisli (see C.15)

import cats.data.Kleisli

val baseK = Kleisli[Result, Conversation, Completion](baseCall)
val withLogK = Kleisli[Result, Conversation, Completion](withLogging(baseCall))
val composed = baseK andThen withLogK