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.

Documentation layout (since 2026-10-09): README.md is an overview and index - the provider tables, installation, config, a quick start and the page list; everything else lives in docs/, one page per topic (providers.md, chat-completions.md, responses-api.md, agents-api.md, streaming.md, decision-models.md, adapters.md, http-engine.md, graders-api.md, anthropic-managed-agents.md, claude-agent-client.md, faq.md), split verbatim from the former 2,450-line README. A feature's documentation goes on its page; the README gets at most a table row or an index line. Links from docs/ to sources are ../openai-...; the decision-model anchors (decision-models.md#typesafe-ai-jev- etc.) are GitHub slugs of the page's ## headings. Markers (README and docs): 🔥 = new, i.e. new in the release being published - the user's rule ("new is a fire", 2026-10-16, preparing 1.6.0): when a release is prepared, its new features carry the fire, the older fires are dropped, and the README legends say "🔥 New in X". A ## heading's emoji is part of its anchor slug (openai-decisions-api-gpt-6-luna-), so a heading's 🔥 is swapped for an icon, not deleted.

Versioning: the latest release is 1.6.0 (Maven Central 2026-10-18, tag v1.6.0 on the CHANGELOG commit that dated it; a minor release - the JSON helpers' inferred-schema implicit, ModelInfo's Options and new DecisionProvider fields break binary compatibility with 1.5.0; the published jars hold the code of 7e9d33cf); the build is 1.6.1-SNAPSHOT, its CHANGELOG section "unreleased" - it already breaks binary compatibility with 1.6.0 (the Vertex AI factories' location: Option[String]), so by the rule below it may ship as 1.7.0. The user publishes from a local version setting; afterwards the CHANGELOG gets its date, the tag vX.Y.Z + GitHub release go on that commit and the build moves to the next -SNAPSHOT. If the changes since the last release are not binary compatible with it (new case-class fields, new abstract methods on the service traits, new factory parameters - compare the published jars' public signatures with javap), the next release is a minor one: 1.3.1-SNAPSHOT shipped as 1.4.0. New @deprecated annotations use the upcoming release as their since value. CHANGELOG.md has one section per release, newest on top, written when the release is prepared; it opens with the upgrade notes (API breaks and behavior changes against the previous release). The GitHub release (tag vX.Y.Z on the published commit) carries a shorter form of the same notes.