Support Claude native API

[mkrzemien]

Although Claude provides a compatibility layer that enables you to use the OpenAI SDK to test the Anthropic API (link), it's primarily intended to test and compare model capabilities, and is not considered a long-term or production-ready solution (compatibility limitations)

In production, it's advised to use Claude native API (link)

[lukaszlenart]

Claude API Implementation Plan

Following the review and technical analysis, here's a comprehensive implementation plan for native Claude API support in sttp-openai.

🎯 Overview

This plan addresses the production limitations of the OpenAI SDK compatibility layer and provides native, first-class support for Anthropic's Claude API.

1. Project Structure

New Submodule Structure

claude/
├── src/
│   ├── main/scala/sttp/ai/claude/
│   │   ├── ClaudeClient.scala
│   │   ├── auth/
│   │   │   ├── ApiKeyAuth.scala
│   │   │   └── AuthConfig.scala
│   │   ├── requests/
│   │   │   ├── CompletionRequest.scala
│   │   │   ├── MessageRequest.scala
│   │   │   └── StreamingRequest.scala
│   │   ├── responses/
│   │   │   ├── CompletionResponse.scala
│   │   │   ├── MessageResponse.scala
│   │   │   ├── StreamingResponse.scala
│   │   │   └── ErrorResponse.scala
│   │   ├── models/
│   │   │   ├── ClaudeModel.scala
│   │   │   ├── Message.scala
│   │   │   └── Usage.scala
│   │   ├── streaming/
│   │   │   ├── ClaudeStreamProcessor.scala
│   │   │   └── StreamingSupport.scala
│   │   └── config/
│   │       ├── ClaudeConfig.scala
│   │       └── HttpConfig.scala
│   └── test/scala/sttp/ai/claude/
│       ├── ClaudeClientSpec.scala
│       ├── unit/
│       ├── integration/
│       └── fixtures/
├── build.sbt
└── README.md

Build Configuration

// In build.sbt, add Claude module
lazy val claude = (projectMatrix in file("claude"))
  .jvmPlatform(
    scalaVersions = scala3 ++ scala2  // Scala 3 FIRST priority
  )
  .settings(commonSettings: _*)
  .settings(
    libraryDependencies ++= Seq(
      Libraries.tapirApispecDocs,
      Libraries.uJsonCirce,
      Libraries.uPickle
    ) ++ Libraries.sttpApispec ++ Libraries.sttpClient ++ Seq(Libraries.scalaTest)
  )

// Claude streaming modules for fs2, zio, akka, pekko, ox
lazy val claudeFs2 = (projectMatrix in file("claude-streaming/fs2"))
  .jvmPlatform(scalaVersions = scala3 ++ scala2)
  .settings(commonSettings)
  .settings(libraryDependencies ++= Libraries.sttpClientFs2)
  .dependsOn(claude % "compile->compile;test->test")

2. API Implementation Requirements

Claude API Endpoints to Implement

1. Messages API (/v1/messages)
   • POST for creating messages/completions
   • Streaming support via Server-Sent Events
2. Models API (/v1/models)
   • GET for listing available models

Request/Response Models

Key Differences from OpenAI:

• Claude uses ContentBlock arrays instead of simple strings
• System messages are handled via system parameter, not role
• Different tool calling structure
• Image support via ContentBlock with base64 encoding

case class MessageRequest(
  model: String,
  messages: List[Message],
  system: Option[String] = None,      // Claude-specific system messages
  maxTokens: Int,
  temperature: Option[Double] = None,
  topP: Option[Double] = None,
  topK: Option[Int] = None,
  stopSequences: Option[List[String]] = None,
  stream: Option[Boolean] = None,
  tools: Option[List[Tool]] = None    // Claude-specific tool structure
)

case class Message(
  role: String, // "user", "assistant" (no "system" - use system parameter)
  content: List[ContentBlock] // Claude uses content blocks, not simple strings
)

case class ContentBlock(
  `type`: String,    // "text" or "image"
  text: Option[String] = None,
  source: Option[ImageSource] = None
)

case class ImageSource(
  `type`: String,    // "base64"
  mediaType: String, // "image/jpeg", "image/png", etc.
  data: String       // base64 encoded image data
)

Authentication Mechanism

• x-api-key header: API Key based authentication
• anthropic-version header: Required version header (e.g., "2023-06-01")
• Environment variable configuration support

case class ClaudeConfig(
  apiKey: String,
  anthropicVersion: String = "2023-06-01", // Required header
  baseUrl: String = "https://api.anthropic.com",
  timeout: Duration = 60.seconds,
  maxRetries: Int = 3,
  organization: Option[String] = None
)

3. Implementation Phases

Phase 1: Core Foundation (Week 1-2)

• Project structure and build configuration with Scala 3 priority
• Basic ClaudeClient interface and implementation
• Authentication with both x-api-key and anthropic-version headers
• Accurate Claude API request/response models (ContentBlock, system parameter, tools)

Phase 2: Basic API Implementation (Week 3-4)

• Claude Messages API implementation with proper ContentBlock support
• Claude Models API implementation
• Claude-specific error handling and response parsing
• Image content support via ContentBlock structure
• Basic integration tests with real Claude API

Phase 3: Streaming Support (Week 5-6)

• Claude-specific Server-Sent Events parsing for streaming responses
• Claude streaming modules for fs2, zio, akka, pekko, ox
• Streaming integration tests with Claude API

Phase 4: Advanced Features (Week 7-8)

• Claude-specific rate limiting and retry mechanisms
• Performance optimizations for Claude API patterns
• Comprehensive Claude error handling
• Claude tool calling implementation

Phase 5: Documentation and Polish (Week 9-10)

• Complete Claude API documentation with examples
• Claude-specific usage examples and guides
• Performance benchmarks against Claude API

🚀 Ready for Implementation

This plan provides:

• ✅ Accurate Claude API specification alignment
• ✅ Native Claude features support (ContentBlock, system parameter, tools)
• ✅ Production-ready architecture and error handling
• ✅ Comprehensive testing strategy
• ✅ Future-proof design for sttp-ai direction
• ✅ Clear implementation phases with concrete deliverables

Full detailed plan: Available in docs/plans/claude-api-implementation-plan.md in PR #408

The plan is technically validated and ready for developer assignment.