API Reference

Complete API documentation for LLM4S.

Primary API Documentation

Scaladoc

The Scaladoc provides comprehensive, auto-generated API documentation for all LLM4S classes and methods.

API Specifications

Document Description
LLM4S API Spec Complete API specification
Tool Calling API Design Tool calling interface design
Workspace Agent Protocol Standardized interface for LLM workspace interaction

API Design Principles

LLM4S follows these design principles:

1. Result-Based Error Handling

Never use exceptions for expected errors. Use Result[A] instead:

1
2
3
4

type Result[+A] = Either[error.LLMError, A]

// Example
def complete(messages: List[Message]): Result[CompletionResponse]

2. Type Safety

Use newtype wrappers to prevent type confusion:

1
2
3
4
5
6
7
8

case class ModelName(value: String) extends AnyVal
case class ApiKey(private val value: String) extends AnyVal

// ✅ Type-safe
def setModel(model: ModelName): Unit

// ❌ Stringly-typed
def setModel(model: String): Unit

3. Immutability

All data structures are immutable:

1
2
3

// A result is an immutable value
val result2 = agent.continueConversation(result1, "Next question")
// result1 is unchanged; result2 is a new instance from the next turn on the same thread

4. Explicit Configuration

Use Llm4sConfig instead of raw environment access:

1
2
3
4
5
6
7
8
9

import org.llm4s.config.Llm4sConfig

// ✅ Type-safe configuration: the default section under llm4s.providers
val config = Llm4sConfig.defaultProvider()
// ...or any section by name
val claude = Llm4sConfig.provider("claude")

// ❌ Raw access
val apiKey = sys.env("OPENAI_API_KEY")

The API key reaches Llm4sConfig through configuration: llm4s-openai binds OPENAI_API_KEY to llm4s.credentials.openai.apiKey, which a named provider section without its own apiKey uses - see API keys.

5. Provider Abstraction

Single interface works across all providers:

1
2

val client: LLMClient = ??? // OpenAI, Anthropic, Azure, or Ollama
// Same API regardless of provider

Common Patterns

Pattern 1: Result Chaining 

1
2
3
4
5
6
7
8
9
10

import org.llm4s.config.Llm4sConfig

val result = for {
  providerConfig <- Llm4sConfig.defaultProvider()
  registry <- Llm4sConfig.modelRegistryService()
  given ModelRegistryService = registry
  client <- LLMConnect.getClient(providerConfig)
  response <- client.complete(messages, None)
  parsed <- parseResponse(response)
} yield parsed

Pattern 2: Fold for Error Handling 

1
2
3
4

result.fold(
  error => println(s"Error: $error"),
  success => println(s"Success: $success")
)

Pattern 3: Map and FlatMap 

1
2

val content: Result[String] = response.map(_.content)
val upper: Result[String] = content.map(_.toUpperCase)

Core Module Structure

The main core module contains:

1
2
3
4
5
6
7
8
9

org.llm4s/
├── types/              # Result, ModelName, etc.
├── config/             # Llm4sConfig + typed loaders
├── llmconnect/         # LLMClient, providers
├── agent/              # Agent framework
├── toolapi/            # Tool calling
├── trace/              # Tracing
├── context/            # Context management
└── error/              # Error types

Error Hierarchy 

1
2
3
4
5
6

sealed trait LLMError
case class NetworkError(message: String) extends LLMError
case class AuthenticationError(message: String) extends LLMError
case class ValidationError(message: String) extends LLMError
case class ConfigurationError(message: String) extends LLMError
// ... and more

Versioning

LLM4S follows semantic versioning:

  • MAJOR: Breaking API changes
  • MINOR: New features, backwards compatible
  • PATCH: Bug fixes

Currently documented release: 0.3.2 (pre-1.0, API stabilizing)

Scala Version Compatibility

LLM4S supports:

  • Scala 3.7.1

The current build is Scala 3.7.1 only. Older design notes may mention historical cross-building, but that is not part of the current supported build matrix.

Migration Guides

When APIs change, consult:

Getting Help

Explore the APIs:

Table of contents