openai-scala-client: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is OpenAI Scala Client - an async Scala client for OpenAI API and multiple LLM providers. It's a multi-module Scala project that supports Scala 2.12, 2.13, and 3, providing comprehensive coverage of OpenAI endpoints plus adapters for Anthropic, Google (Gemini/Vertex AI), Perplexity, and other LLM providers.

The library is designed to be self-contained with minimal dependencies and uses a Play WS backend for HTTP calls. It's published as io.cequence:openai-scala-client on Maven Central.

Build & Test Commands

The project uses SBT with custom command aliases defined in build.sbt:

Core Commands

• Build & test: sbt clean test or sbt ++2.13.11 clean test for a specific Scala version
• Test with coverage: sbt testWithCoverage (alias for coverage; test; coverageReport)
• Format code: sbt formatCode (runs scalafmt, scalafmtSbt, and Test/scalafmt)
• Validate code: sbt validateCode (runs scalafix and scalafmt checks - this is what CI runs)
• Compile specific module: sbt core/compile or sbt client/compile etc.
• Run specific test: sbt "testOnly *YourTestClassName"
• Run example: sbt "examples/runMain io.cequence.openaiscala.examples.YourExampleClass"

Cross-Build

The project cross-compiles for Scala 2.12.18, 2.13.11, and 3.2.2:

• sbt ++2.12.18 test
• sbt ++2.13.11 test
• sbt ++3.2.2 test

Running Examples

The Example trait uses System.exit() which sbt's TrapExit mechanism intercepts, causing output to be swallowed. For reliable output when running examples from sbt, either:

• Run from IntelliJ directly (recommended)
• Write standalone main methods using Await.result instead of extending Example

Module Architecture

The codebase is organized into multiple SBT subprojects with clear dependency relationships:

Core Modules

• openai-core (core): Core domain models, JSON formats, service interfaces (OpenAIService, OpenAICoreService, OpenAIChatCompletionService), adapters, retry helpers, and base exception types. This is the foundation that other modules depend on.
• openai-client (client): Main client implementation with factories (OpenAIServiceFactory, OpenAIChatCompletionServiceFactory) and concrete service implementations. Depends on and aggregates openai-core.
• openai-client-stream (client_stream): Streaming extensions providing OpenAIStreamedServiceExtra and streaming factories for SSE-based completions. Depends on openai-client.