tramai-spring-provider-openai

Version: 0.6.0
Status: Preview
Role: Provider adapter module: OpenAI and OpenAI-compatible configuration for Spring applications.

Purpose

This adapter turns tramai.providers.openai.* and tramai.providers.openai-compatible.* into provider beans. It constructs providers only: model routing, fallbacks, retries, circuit breaking, caching and cost budgets stay in the runtime and are configured under tramai.* in tramai-spring-core.

What it provides

Component	Detail
`OpenAiProviderAutoConfiguration`	Contributes both provider beans; backs off when the application defines its own `Tramai` bean
`OpenAiProperties`	Binds `tramai.providers.openai.*`
`OpenAiCompatibleProperties`	Binds `tramai.providers.openai-compatible.*`
`CodexAuth`	`enabled` / `auth-file` for ChatGPT-codex credential files (experimental, local testing)
Beans	`SpringConfiguredModelProvider` descriptors for provider ids `openai` and the configured compatible-provider name

Property surface:

Key	Notes
`tramai.providers.openai.api-key`	Direct key
`tramai.providers.openai.api-key-secret-ref`	Secret reference resolved through the shared chain (`env:`, `file:`, `vault:`, `aws-secretsmanager:`)
`tramai.providers.openai.bearer-token`, `…-secret-ref`	Bearer-token auth instead of an API key
`tramai.providers.openai.base-url`, `organization`, `project`	Endpoint and account scoping
`tramai.providers.openai-compatible.provider-name`	Provider id registered on the runtime (default `openai-compatible`)
`tramai.providers.openai-compatible.api-key`, `…-secret-ref`, `bearer-token`, `…-secret-ref`, `base-url`	Same auth options for compatible endpoints

Configuring api-key and its *-secret-ref at once is a misconfiguration and fails at startup rather than silently preferring one.

Dependencies

dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
    implementation("dev.tramai:tramai-spring-boot-starter")
    implementation("dev.tramai:tramai-spring-provider-openai")
}

tramai:
  default-provider: openai
  models:
    gpt-4o: openai
  providers:
    openai:
      api-key: ${OPENAI_API_KEY}
    openai-compatible:
      provider-name: my-local
      base-url: https://my-endpoint.example.com/v1
      api-key: ${MY_LOCAL_KEY}

When to use this module

You call OpenAI, an Azure-style compatible gateway, or any OpenAI-compatible endpoint from a Spring application.
You need credentials resolved from Vault or AWS Secrets Manager through *-secret-ref.

When NOT to use this module

You serve models locally with Ollama proper — use tramai-spring-provider-ollama.
You want the sovereign-lab loopback provider: that is tramai-spring-boot-starter-local-provider-openai.
You expect retry/fallback policy here — the engine owns it.