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

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

// Conversation state is immutable
val state2 = agent.continueConversation(state1, "Next question")
// state1 is unchanged, state2 is a new instance

4. Explicit Configuration

Use ConfigReader instead of raw environment access:

1
2
3
4
5

// ✅ Type-safe configuration
val config = ConfigReader.Provider()

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

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

val result = for {
  client <- LLMConnect.create()
  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 llm4s-core module contains:

1
2
3
4
5
6
7
8
9

org.llm4s/
├── types/              # Result, ModelName, etc.
├── config/             # ConfigReader
├── 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: 0.1.0-SNAPSHOT (pre-release)

Scala Version Compatibility

LLM4S supports:

  • Scala 2.13.16
  • Scala 3.7.1

Cross-compilation ensures the same API on both versions.

Migration Guides

When APIs change, consult:

Getting Help

Explore the APIs: