TramAI - governed AI workflows for Java and Kotlin

tramai-sovereign

Version: 0.6.0
Status: Preview
Role: Sealed, governed, offline-capable execution boundary built on the standalone runtime.

Purpose

tramai-sovereign is the secure embedded runtime profile. It wraps tramai-standalone around the governance primitives in tramai-security and refuses to start unless the deployment is fully specified:

  • DefaultPolicyEngine with PolicyConfiguration.secure() (deny-by-default, wildcards rejected)
  • approved-model registry enforcement — always on, not disableable through the sovereign API
  • classification-aware provider routing with explicit ProviderTrustZone per provider
  • hash-chained policy-decision, DLP and approval-lifecycle audit emission
  • optional local-model artifact verification (streaming SHA-256 over each artifact)

It runs embedded in a JVM process. Neither tramai-platform nor Spring Boot is required.

What it provides

TypeRole
SovereignTramaiRuntime entry point: create<T>(), runtime(), verificationReceipts(), evidencePack(...), close()
SovereignProfileConfigurationAllowlists, provider trust zones, SovereignDeploymentMode
SovereignDeploymentModeSTANDARD (default) or OFFLINE — OFFLINE requires every provider, route and default to target ProviderTrustZone.LOCAL
SovereignTramaiRuntimeThe owned engine wrapper returned by runtime()
dev.tramai.sovereign.evidence.*SovereignEvidencePackV1, SovereignEvidencePackGenerator, SovereignEvidencePackWriter and the optional evidence subsections (zero-egress, audit chain, supply chain, release bundle, attestation)

SovereignTramai.Builder.build() validates the provider routing plan before any invocation: profile present, registry present, audit store present, at least one provider, every provider allowed and zone-mapped, every allowed model routed to an allowed provider, fallback providers inside the allowlist. Missing pieces fail the build with IllegalStateException — there is no permissive fallback path.

evidencePack(...) produces a deterministic, auditor-safe SovereignEvidencePackV1 (schema version 1, sorted allowlists, generatedAt timestamp) that contains no secrets, prompts, stack traces or filesystem paths.

Dependencies

dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
    implementation("dev.tramai:tramai-sovereign")
}

val registry = InMemoryModelRegistry.builder()
    .register(
        RegisteredModel(
            registryEntryId = "local-llama-3",
            providerId = "ollama",
            modelName = "llama3.2",
            revision = "2026-06",
        ),
    )
    .build()

val tramai = SovereignTramai.builder()
    .profile(
        SovereignProfileConfiguration(
            allowedModels = setOf("llama3.2"),
            allowedProviders = setOf("ollama"),
            providerZones = mapOf("ollama" to ProviderTrustZone.LOCAL),
        ),
    )
    .modelRegistry(registry)
    .auditStore(InMemoryAuditStore())
    .provider(ollamaProvider, name = "ollama", default = true)
    .model("llama3.2", "ollama")
    .build()

val service = tramai.create<MyService>()
tramai.close()

Spring Boot applications select this runtime with tramai.profile: sovereign through tramai-spring-boot-starter rather than building it by hand.

When to use this module

  • The deployment requires provable allowlists, local-only or EU-only routing, approval gates and a tamper-evident audit chain.
  • You need an auditor-facing evidence pack for the deployment's security posture.
  • You are running offline and want the build to fail if any provider escapes the local trust zone.

When NOT to use this module

  • You just want typed AI calls with no governance requirements — use tramai-standalone.
  • You expect the profile to enforce network isolation: OFFLINE mode is a composition contract, not a firewall. Infrastructure controls remain your responsibility.
  • You need continuous re-attestation of model artifacts: verification happens once at build time.
Previous
Next