TramAI - governed AI workflows for Java and Kotlin

tramai-spring-core

Version: 0.6.0
Status: Preview
Role: Shared Spring integration base for every TramAI Spring adapter.

Purpose

tramai-spring-core is the profile-neutral half of TramAI's Spring support. It turns annotated interfaces into Spring beans and binds tramai.* configuration — without knowing anything about provider SDKs or the sovereign runtime.

It is not normally a direct dependency: tramai-spring-boot-starter brings it in and selects which runtime integration (standard or sovereign) is active.

What it provides

Auto-configuration (registered in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports)

ConfigurationWhen it applies
TramaiSecretResolutionAutoConfigurationAssembles the bootstrap and full secret-resolution chains
StandardTramaiProfileAutoConfigurationImports TramaiAutoConfiguration when tramai.profile is standard or missing
AiServiceProxyAutoConfigurationRegisters @AiService interfaces found by classpath scanning
SecurityClassificationAutoConfigurationBinds classification rules from tramai.security.*

TramaiRuntimeProfileEnvironmentPostProcessor (spring.factories) validates tramai.profile early: only standard and sovereign are accepted, and the standard runtime stays the default.

Bean model

  • @AiService interfaces become injectable proxies through AiServiceBeanDefinitionRegistrar / AiServiceFactoryBean.
  • @AiTool methods on existing Spring beans are discovered by AiToolScanner and registered on the runtime.
  • EnableTramai is an optional annotation for annotation-driven (non-Boot) Spring contexts. It does not select a runtime profile — tramai.profile remains the sole selector.
  • SpringSecretChain / SpringBootstrapSecretChain hold the assembled SecretValueResolver chains: user resolvers first, then built-in module resolvers, then env:, then bootstrap resolvers.

Properties — TramaiProperties binds tramai.default-provider, tramai.models, tramai.fallbacks, tramai.resilience.circuit-breaker.*, tramai.resilience.retry.*, tramai.cost.token-budget.*, tramai.cache.in-memory.*, tramai.security.classification.* and tramai.security.model-registry.enabled.

Dependencies

dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
    implementation("dev.tramai:tramai-spring-core")
    implementation("dev.tramai:tramai-spring-provider-openai") // provider adapter
}

tramai:
  default-provider: openai
  models:
    gpt-4o: openai
  providers:
    openai:
      api-key: ${OPENAI_API_KEY}

@AiService
interface InvoiceAnalyzer {
    @Operation(prompt = "Analyze this invoice and return a one-line status.", model = "gpt-4o")
    suspend fun analyze(invoiceText: String): String
}

When to use this module

  • You are writing a provider adapter, a secrets module or a runtime integration and want the shared Spring plumbing.
  • You want @AiService proxies and tramai.* property binding without pulling in a runtime profile.

When NOT to use this module

  • You are writing an application: depend on tramai-spring-boot-starter instead.
  • You need provider adapters or the sovereign runtime: those live in their own modules and must be added explicitly.
  • You are not using Spring — see tramai-standalone.
Previous
Next