tramai-spring-sovereign

Version: 0.6.0
Status: Preview
Role: Sovereign-profile Spring integration: the composition layer under the unified starter.

Purpose

tramai-spring-sovereign brings the sovereign runtime into a Spring Boot application. It is the sovereign half of tramai-spring-boot-starter and activates only when tramai.profile: sovereign is set — there is no starter-level sovereign default.

Application code does not change between profiles: the same @AiService interfaces, @AiTool methods and constructor injection work in both. What changes is the runtime underneath, and therefore the governance guarantees.

What it provides

Activation

• SovereignTramaiProfileAutoConfiguration — internal; imports the sovereign configuration when tramai.profile=sovereign.
• SovereignTramaiAutoConfiguration — builds the sovereign beans.
• SovereignAiServiceProxyAutoConfiguration — internal; publishes the tramaiAiServiceCreator bean that tramai-spring-core resolves by name, so @AiService proxies delegate to SovereignTramai.
• StandardProfileSovereignAuthorityGuardAutoConfiguration — internal; the other half of the one-authority invariant.

Beans (all @ConditionalOnMissingBean, so add-ons or your own beans take precedence)

One runtime authority. tramai.profile is the sole selector, and exactly one authority may exist: a plain Tramai bean present while tramai.profile=sovereign fails startup, and a manual SovereignTramai bean while the profile is standard (or unset) fails startup too. Startup also fails when the sovereign profile resolves zero model providers.

Properties — SovereignTramaiProperties (tramai.sovereign.*): allowed-models, allowed-providers, allowed-tools, allowed-permissions, provider-zones, models. Validation rejects wildcard entries, providers without a trust zone, zones for unknown providers, models without a route, and routes to unknown providers. tramai.sovereign.enabled: false is rejected with an explicit startup failure — the profile is the selector, the legacy switch is not.

Dependencies

dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
    implementation("dev.tramai:tramai-spring-boot-starter") // brings this module in
    implementation("dev.tramai:tramai-spring-provider-ollama")
}

tramai:
  profile: sovereign
  providers:
    ollama:
      base-url: http://localhost:11434
  sovereign:
    allowed-models: [gemma4:e2b]
    allowed-providers: [ollama]
    provider-zones:
      ollama: LOCAL
    models:
      gemma4:e2b: ollama

When to use this module

• You are deploying the sovereign profile in Spring Boot; the unified starter already pulls this module in.
• You are writing a sovereign add-on starter and need the base composition to build on.

When NOT to use this module

• You want the standard runtime — leave tramai.profile unset and this module stays dormant.
• You are not using Spring Boot: compose tramai-sovereign directly.
• You expect provider adapters or persistence here — add the provider and sovereign-persistence starters explicitly.