Module: tramai-openai

dependencies {
    implementation("dev.tramai:tramai-openai:0.3.1")
}

<dependency>
    <groupId>dev.tramai</groupId>
    <artifactId>tramai-openai</artifactId>
    <version>0.3.1</version>
</dependency>

implementation(platform("dev.tramai:tramai-bom:0.3.1"))
implementation("dev.tramai:tramai-openai")

import dev.tramai.core.annotations.AiService
import dev.tramai.core.annotations.Operation
import dev.tramai.openai.OpenAiProvider
import dev.tramai.standalone.Tramai

@AiService
@SystemPrompt("You are a helpful assistant.")
interface ChatService {
    @Operation(prompt = "What is the capital of Japan?", model = "gpt-4o")
    suspend fun ask(): String
}

suspend fun main() {
    val chat = Tramai
        .builder()
        .provider(OpenAiProvider(apiKey = System.getenv("OPENAI_API_KEY")), default = true)
        .build()
        .create<ChatService>()

    println(chat.ask()) // "Tokyo"
}

val provider = OpenAiProvider(
    apiKey = System.getenv("OPENAI_API_KEY"),
    organization = "org-abc123",   // optional: OpenAI organization ID
    project = "proj-def456",       // optional: OpenAI project ID
)
val engine = TramaiEngine(provider)
val service = engine.create<ChatService>()

// Together AI
val together = OpenAiCompatibleProvider.bearerToken(
    bearerToken = System.getenv("TOGETHER_API_KEY"),
    baseUrl = "https://api.together.xyz/v1",
    providerName = "together",
)

// Groq
val groq = OpenAiCompatibleProvider.bearerToken(
    bearerToken = System.getenv("GROQ_API_KEY"),
    baseUrl = "https://api.groq.com/openai/v1",
    providerName = "groq",
)

// Self-hosted vLLM
val vllm = OpenAiCompatibleProvider.bearerToken(
    bearerToken = "not-needed",  // vLLM often doesn't require auth locally
    baseUrl = "http://localhost:8000/v1",
    providerName = "vllm",
)

val service = Tramai
    .builder()
    .provider(together, name = "together")
    .provider(groq, name = "groq")
    .model("mixtral-8x22b", "together")
    .model("llama-3.3-70b", "groq")
    .defaultProvider("groq")
    .build()
    .create<MultiModelService>()

import dev.tramai.core.model.StreamChunk
import dev.tramai.core.model.Message
import dev.tramai.core.model.MessageRole
import dev.tramai.core.model.ModelRequest
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.runBlocking

val provider = OpenAiProvider(apiKey = System.getenv("OPENAI_API_KEY"))

val request = ModelRequest(
    model = "gpt-4o",
    messages = listOf(Message(MessageRole.USER, "Count from 1 to 5")),
)

runBlocking {
    provider.stream(request).collect { chunk ->
        when (chunk) {
            is StreamChunk.Token -> print(chunk.text)
            is StreamChunk.Complete -> println("\n[Done: ${chunk.usage.outputTokens} tokens]")
            is StreamChunk.Error -> System.err.println("\n[Error: ${chunk.cause.message}]")
        }
    }
}

@AiService
interface StreamingService {
    @Operation(prompt = "Tell me a story", model = "gpt-4o")
    fun stream(): Flow<StreamChunk>
}

import dev.tramai.openai.OpenAiProvider
import dev.tramai.openai.ExperimentalCodexAuth

@OptIn(ExperimentalCodexAuth::class)
fun localProvider(): OpenAiProvider = OpenAiProvider.codexAuth()

@OptIn(ExperimentalCodexAuth::class)
val localCompat = OpenAiCompatibleProvider.codexAuth(
    baseUrl = "http://localhost:8000/v1",
    providerName = "local-vllm",
)

val request = ModelRequest(
    model = "gpt-4o",
    messages = listOf(Message(MessageRole.USER, "What's the weather in Paris?")),
    tools = listOf(
        ToolDefinition(
            name = "get_weather",
            description = "Get current temperature for a city",
            inputSchemaJson = """{"type":"object","properties":{"city":{"type":"string"}}}""",
        ),
    ),
)
val response = provider.complete(request)
response.toolCalls?.forEach { toolCall ->
    println("Call ${toolCall.name} with ${toolCall.argumentsJson}")
}

val customClient = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(15))
    .build()

val customMapper = JsonMapper.builder()
    .enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS)
    .build()

val provider = OpenAiProvider(
    apiKey = System.getenv("OPENAI_API_KEY"),
    httpClient = customClient,
    objectMapper = customMapper,
)

class VaultTokenSource : OpenAiAccessTokenSource {
    override fun accessToken(): String {
        // Fetch dynamically from HashiCorp Vault, AWS Secrets Manager, etc.
        return fetchSecret("openai/api-key")
    }
}

val provider = OpenAiProvider(
    accessTokenSource = VaultTokenSource(),
)

{
  "message": {
    "content": [
      { "type": "text", "text": "Hello" },
      { "type": "text", "text": "World" }
    ]
  }
}

Public API:
  dev.tramai.openai
    OpenAiProvider                    — ModelProvider + StreamCapable (OpenAI-specific)
      constructor(apiKey, baseUrl?, httpClient?, objectMapper?, organization?, project?)
      constructor(accessTokenSource, ...)
      bearerToken(token, ...)         — factory method
      codexAuth(...)                  — factory method (@ExperimentalCodexAuth)
      providerId(): String            — always "openai"

    OpenAiCompatibleProvider          — ModelProvider + StreamCapable (generic)
      constructor(accessTokenSource, baseUrl, providerName?, ...)
      bearerToken(token, baseUrl, ...) — factory method
      codexAuth(baseUrl, ...)         — factory method (@ExperimentalCodexAuth)
      providerId(): String            — configurable via constructor

    OpenAiAccessTokenSource           — fun interface SAM
      fun accessToken(): String

    StaticOpenAiAccessTokenSource     — wraps a static string token
      constructor(token: String)

    CodexAuthFileTokenSource          — reads ~/.codex/auth.json (@ExperimentalCodexAuth)
      constructor(authFile?, objectMapper?)
      defaultAuthFile(): Path         — companion static method

    @ExperimentalCodexAuth            — opt-in annotation (RequiresOptIn)

Package: dev.tramai.openai
  2 source files, no sub-packages.

OpenAiCompatibleProvider  (open)     ← implements ModelProvider, StreamCapable
    │
    └── OpenAiProvider   (final)     ← pre-configures baseUrl, organization, project

OpenAiAccessTokenSource   (fun interface)
    ├── StaticOpenAiAccessTokenSource
    └── CodexAuthFileTokenSource     ← @ExperimentalCodexAuth

tramai-openai
  Depends on:
    - tramai-core (api)        — ModelProvider, ModelRequest, ModelResponse,
                                 StreamCapable, StreamChunk, ProviderException
    - jackson-databind (impl)  — JSON serialization/deserialization of payloads
    - kotlinx-coroutines-core  — Flow-based streaming via stream()

  Depended on by:
    - tramai-standalone        — wired via Tramai.builder().provider()
    - tramai-spring            — auto-configuration discovers OpenAiProvider beans

1. User calls service.method() via @AiService proxy
2. Engine builds ModelRequest (model, messages, tools, parameters)
3. Engine resolves provider → calls OpenAiProvider.complete(request)
4. Provider serializes payload on Dispatchers.IO:

   POST {baseUrl}/chat/completions
   Authorization: Bearer <token>
   Content-Type: application/json
   OpenAI-Organization: <org>        (OpenAiProvider only)
   OpenAI-Project: <project>         (OpenAiProvider only)

   {
     "model": "gpt-4o",
     "stream": false,
     "messages": [
       {"role": "system", "content": "You are helpful."},
       {"role": "user", "content": "What is the capital of Japan?"}
     ],
     "tools": [ ... ],               (if tool definitions provided)
     "max_tokens": 200,
     "temperature": 0.7
   }

5. Response parsed:

   {
     "model": "gpt-4o-2024-08-06",
     "choices": [{
       "message": {
         "role": "assistant",
         "content": "Tokyo",
         "tool_calls": [...]         (if model requested tools)
       },
       "finish_reason": "stop"
     }],
     "usage": {
       "prompt_tokens": 25,
       "completion_tokens": 3
     }
   }

6. Provider constructs ModelResponse:
   - content          ← message.content (supports string or array-of-content-blocks)
   - toolCalls        ← message.tool_calls array → List<ToolCall>
   - inputTokens      ← usage.prompt_tokens
   - outputTokens     ← usage.completion_tokens
   - modelUsed        ← response.model
   - finishReason     ← choices[0].finish_reason ("stop"→STOP, "length"→LENGTH,
                       "tool_calls"→STOP, "content_filter"→CONTENT_FILTER, else→OTHER)

7. ModelResponse returned to engine

1. Provider builds payload with "stream": true
2. HTTP POST to {baseUrl}/chat/completions
3. Response consumed as Flow<StreamChunk> via kotlinx.coroutines.flow.flow { }

   SSE data lines arrive as:
     data: {"choices":[{"delta":{"role":"assistant"}}]}
     data: {"choices":[{"delta":{"content":"Tok"}}]}
     data: {"choices":[{"delta":{"content":"yo"}}]}
     data: {"choices":[{"delta":{"content":""},"finish_reason":"stop"}]}
     data: {"usage":{"prompt_tokens":25,"completion_tokens":3}}
     data: [DONE]

4. Each line parsed:
   - Starts with "data: " → strip prefix
   - "[DONE]" → end of stream
   - Otherwise → parse JSON, extract choices[0].delta.content
   - Non-empty content → emit StreamChunk.Token(text)
   - usage present → capture final UsageMetrics

5. On stream end → emit StreamChunk.Complete(fullText, usage)
6. On parse/transport error → emit StreamChunk.Error(exception)

   All SSE parsing happens on the IO dispatcher.
   The calling collect() runs on whatever coroutine context the caller provides.