Installation

Get LLM4S up and running in minutes.

Table of contents

  1. Prerequisites
    1. Verify Prerequisites
  2. Add LLM4S to Your Project
    1. SBT
    2. Maven
    3. Multi-Module Project
    4. Snapshot Versions
  3. Quick Start with the Starter Kit
  4. Optional Dependencies
    1. For RAG, vector stores, chunking, reranking and document extraction
    2. For agent memory
    3. For MCP (Model Context Protocol)
    4. For speech (STT / TTS)
    5. For image generation and vision
    6. For media types (MediaType, MediaCategory)
    7. For Workspace (Containerized Execution)
  5. API Keys Setup
    1. Environment Variables
    2. Get API Keys
      1. OpenAI
      2. Anthropic
      3. Azure OpenAI
      4. Ollama (Local)
  6. Verify Installation
  7. Troubleshooting
    1. “API key not found”
    2. “Provider not supported”
    3. Compilation Errors
    4. Dependency Resolution Issues
  8. Next Steps
  9. Additional Resources

Prerequisites

Before installing LLM4S, ensure you have:

  • Java Development Kit (JDK) 21
  • Scala 3.7.1
  • SBT 1.10.6 or higher
  • An API key from at least one LLM provider (OpenAI, Anthropic, Azure OpenAI, or Ollama)

Verify Prerequisites 

1
2
3
4
5
6
7
8

# Check Java version
java -version  # Should show 21

# Check Scala version
scala -version  # 3.7.1

# Check SBT version
sbt version  # 1.10.6 or higher

Add LLM4S to Your Project

Artifact coordinates changed in 0.4.0. Every published module now carries an llm4s- prefix (core → llm4s-core, workspaceClient → llm4s-workspace-client, and so on). Releases up to and including 0.3.4 remain available under the old names. See the migration guide for the full old → new table.

SBT

Add LLM4S to your build.sbt:

1
2
3

// Scala 3
libraryDependencies += "org.llm4s" %% "llm4s-core" % "0.4.0"
ThisBuild / scalaVersion := "3.7.1"

Maven 

1
2
3
4
5
6
7

<!-- For Scala 3 -->
<dependency>
    <groupId>org.llm4s</groupId>
    <artifactId>llm4s-core_3</artifactId>
    <version>0.4.0</version>
</dependency>

Multi-Module Project

If you have a multi-module project:

1
2
3
4
5
6
7
8

lazy val myProject = (project in file("."))
  .settings(
    name := "my-llm-project",
    scalaVersion := "3.7.1",
    libraryDependencies ++= Seq(
      "org.llm4s" %% "llm4s-core" % "0.4.0"
    )
  )

Snapshot Versions

To use the latest development snapshot:

1
2

resolvers += Resolver.sonatypeRepo("snapshots")
libraryDependencies += "org.llm4s" %% "llm4s-core" % "0.4.0-SNAPSHOT"

Quick Start with the Starter Kit

The fastest way to get started is using the llm4s.g8 template:

1
2
3
4
5
6
7
8
9
10
11

# Install the template
sbt new llm4s/llm4s.g8

# Follow the prompts
# name [My LLM Project]: my-awesome-agent
# organization [com.example]: com.mycompany
# scala_version [3.7.1]:
# llm4s_version [0.4.0]:

cd my-awesome-agent
sbt run

The starter kit includes:

  • ✅ Pre-configured SBT build
  • ✅ Example agent with tool calling
  • ✅ Configuration templates
  • ✅ Multi-provider setup
  • ✅ Docker configuration for workspace

View the starter kit →

Optional Dependencies

Additional modules are published separately. The core library includes most functionality. Check Maven Central for available artifacts.

For RAG, vector stores, chunking, reranking and document extraction

Not yet published. llm4s-rag exists in the build as of #1128 but ships in the next release; in 0.4.1 and earlier this code is still inside llm4s-core.

1
2

// same version as llm4s-core
libraryDependencies += "org.llm4s" %% "llm4s-rag" % llm4sVersion

Brings llm4s-knowledgegraph with it, along with Tika, POI, PDFBox, jsoup and the AWS S3 client — the document-extraction and loader dependencies that llm4s-core no longer carries. Package names are unchanged, so existing org.llm4s.rag.* imports keep working; see the migration note.

For agent memory

Not yet published. llm4s-memory and llm4s-memory-postgres exist in the build as of #1129 but ship in the next release; in 0.4.1 and earlier this code is still inside llm4s-core.

1
2
3
4
5

// same version as llm4s-core
libraryDependencies += "org.llm4s" %% "llm4s-memory" % llm4sVersion

// only if you store memories in Postgres/pgvector
libraryDependencies += "org.llm4s" %% "llm4s-memory-postgres" % llm4sVersion

llm4s-memory carries MemoryStore, the memory managers, and the in-memory and SQLite-backed stores; it adds sqlite-jdbc to your classpath and nothing else. PostgresMemoryStore lives in llm4s-memory-postgres, which brings HikariCP and the Postgres JDBC driver — the two dependencies llm4s-core no longer carries. Package names are unchanged, so existing org.llm4s.agent.memory.* imports keep working; see the migration note.

For MCP (Model Context Protocol)

Not yet published. llm4s-mcp exists in the build as of #1130 but ships in the next release; in 0.4.1 and earlier this code is still inside llm4s-core.

1
2

// same version as llm4s-core
libraryDependencies += "org.llm4s" %% "llm4s-mcp" % llm4sVersion

Carries the MCP client, server, transports (stdio, HTTP, SSE) and MCPToolRegistry. It adds no third-party dependency of its own. Package names are unchanged, so existing org.llm4s.mcp.* imports keep working; see the migration note.

For speech (STT / TTS)

Not yet published. llm4s-speech exists in the build as of #1130 but ships in the next release; in 0.4.1 and earlier this code is still inside llm4s-core.

1
2

// same version as llm4s-core
libraryDependencies += "org.llm4s" %% "llm4s-speech" % llm4sVersion

Carries speech-to-text (Vosk for offline recognition, Whisper), text-to-speech (Tacotron 2), and the audio IO, conversion and validation helpers. This is the module that brings Vosk, a 25 MB dependency that used to sit on every llm4s-core user’s classpath — which is much of the point of the split. Package names are unchanged; see the migration note.

For image generation and vision

Not yet published. llm4s-image exists in the build as of #1130 but ships in the next release; in 0.4.1 and earlier this code is still inside llm4s-core.

1
2

// same version as llm4s-core
libraryDependencies += "org.llm4s" %% "llm4s-image" % llm4sVersion

Carries image generation (org.llm4s.imagegeneration — Stable Diffusion, Stability AI, Hugging Face, OpenAI) and image processing (org.llm4s.imageprocessing — the OpenAI and Anthropic vision clients plus a local javax.imageio processor). It adds no third-party dependency of its own, and brings llm4s-media with it.

Package names are unchanged, so existing org.llm4s.imagegeneration.* and org.llm4s.imageprocessing.* imports keep working — but note that image formats did change, in llm4s-media. See the migration note.

For media types (MediaType, MediaCategory)

Not yet published. llm4s-media exists in the build as of #1130 but ships in the next release.

1
2

// same version as llm4s-core
libraryDependencies += "org.llm4s" %% "llm4s-media" % llm4sVersion

The shared vocabulary the multimodal modules speak: MediaType (MIME string, canonical extension, category, and lookups by extension, path or MIME type) and MediaCategory. It has no dependencies at all and does no I/O — deciding what a file is from its bytes needs Tika and lives in llm4s-rag.

You will usually get it transitively, from llm4s-core or llm4s-rag; declare it directly only if you name these types in your own signatures. It replaces three overlapping image-format types that used to ship in llm4s-core, which is a source break — see the migration note.

For Workspace (Containerized Execution) 

1

libraryDependencies += "org.llm4s" %% "llm4s-workspace-client" % "0.4.0"

And install Docker:

1
2
3
4
5
6
7
8

# macOS
brew install docker

# Ubuntu/Debian
sudo apt-get install docker.io

# Verify
docker --version

API Keys Setup

LLM4S requires API keys for your chosen provider(s). You can configure these via:

  1. Environment variables (recommended)
  2. Configuration files (application.conf)
  3. System properties (-D flags)

Environment Variables

Create a .env file in your project root (add to .gitignore!):

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

# Choose your provider
LLM_MODEL=openai/gpt-4o

# OpenAI
OPENAI_API_KEY=sk-proj-...
OPENAI_BASE_URL=https://api.openai.com/v1  # Optional

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_BASE_URL=https://api.anthropic.com  # Optional

# Azure OpenAI
AZURE_API_KEY=your-azure-key
AZURE_API_BASE=https://your-resource.openai.azure.com
AZURE_DEPLOYMENT_NAME=gpt-4o

# Ollama (local)
OLLAMA_BASE_URL=http://localhost:11434

# Cohere
COHERE_API_KEY=your-cohere-api-key
COHERE_BASE_URL=https://api.cohere.com  # Optional

Load the .env file before running:

1
2

source .env
sbt run

Or use sbt-dotenv plugin:

1
2

// project/plugins.sbt
addSbtPlugin("au.com.onegeek" %% "sbt-dotenv" % "2.1.233")

Get API Keys

OpenAI

  1. Go to platform.openai.com
  2. Sign up or log in
  3. Navigate to API Keys
  4. Click Create new secret key
  5. Copy the key (starts with sk-)

Anthropic

  1. Go to console.anthropic.com
  2. Sign up or log in
  3. Navigate to API Keys
  4. Click Create Key
  5. Copy the key (starts with sk-ant-)

Azure OpenAI

  1. Create an Azure account
  2. Navigate to Azure OpenAI Service
  3. Create a resource
  4. Deploy a model (e.g., gpt-4o)
  5. Copy the API Key and Endpoint

Ollama (Local)

  1. Install Ollama: ollama.com
  2. Pull a model: ollama pull llama2
  3. Start server: ollama serve
  4. No API key needed!

Verify Installation

Create a simple test file VerifyInstall.scala:

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

import org.llm4s.config.Llm4sConfig
import org.llm4s.llmconnect.LLMConnect
import org.llm4s.llmconnect.model.UserMessage

object VerifyInstall extends App {
  println("Testing LLM4S installation...")

  val result = for {
    providerConfig <- Llm4sConfig.provider()
    client <- LLMConnect.getClient(providerConfig)
    response <- client.complete(
      messages = List(UserMessage("Say 'LLM4S is working!'")),
      model = None
    )
  } yield response

  result match {
    case Right(completion) =>
      println("✅ Success!")
      println(s"Response: ${completion.content}")
    case Left(error) =>
      println("❌ Error:")
      println(error)
  }
}

Run it:

1

sbt run

Expected output:

1
2
3

Testing LLM4S installation...
✅ Success!
Response: LLM4S is working!

Troubleshooting

“API key not found”

Problem: LLM4S can’t find your API key.

Solution:

  1. Verify .env file exists and is in project root
  2. Check you’ve sourced it: source .env
  3. Verify variable name matches your provider (e.g., OPENAI_API_KEY)
  4. Check for typos in the key

“Provider not supported”

Problem: Invalid LLM_MODEL format.

Solution: Use the correct format:

  • OpenAI: openai/gpt-4o
  • Anthropic: anthropic/claude-sonnet-4-5-latest
  • Azure: azure/gpt-4o
  • Ollama: ollama/llama2

Compilation Errors

Problem: Scala version mismatch.

Solution:

1
2
3

# Clean and recompile
sbt clean
sbt compile

Dependency Resolution Issues

Problem: Can’t resolve LLM4S dependency.

Solution:

  • For release versions, no additional resolver needed (uses Maven Central)
  • For snapshots, add the resolver: 
    1

    resolvers += Resolver.sonatypeRepo("snapshots")

Next Steps

Now that LLM4S is installed:

  1. Write your first program → - Create a simple LLM application
  2. Configure providers → - Set up multiple LLM providers
  3. Explore examples → - Browse 69 working examples

Additional Resources

Installation complete! Ready to write your first program →