API Stability

This page defines the public API stability expectations for the TramAI 0.4.x line.

Stability Policy For `0.4.x`

TramAI 0.4.x is still pre-1.0, but it is not intended to be arbitrary.

For documented release-line APIs in 0.4.x, the project aims to avoid intentional breaking changes in:

exported public types and method signatures
documented Spring property names under tramai.*
published module coordinates
documented provider ids and routing behavior
documented failure semantics for retries, structured output, and token budgets

Changes that remain acceptable in 0.4.x:

bug fixes that correct behavior to match existing docs
additive public APIs
stronger validation when the old behavior was ambiguous or unsafe
internal refactors that do not change the documented contract

Stable Consumer Surface In `0.4.x`

The following consumer-facing modules are the primary documented release-line surface in 0.4.x:

tramai-core
tramai-engine
tramai-structured
tramai-standalone
tramai-spring
tramai-openai
tramai-azure-openai
tramai-anthropic
tramai-bedrock
tramai-gemini
tramai-deepseek
tramai-ollama
tramai-observability
tramai-orchestration
tramai-memory
tramai-embedding
tramai-rag
tramai-vectorstore-spi
tramai-vectorstore-chroma
tramai-vectorstore-pgvector
tramai-testing
tramai-bom

These modules reflect the core library plus optional, application-level capabilities that are already documented as normal consumer dependencies.

Fast-Moving Runtime, Platform, And Sovereign Surface

The repository also contains newer operational and sovereign modules:

tramai-memory-store
tramai-scheduler
tramai-server
tramai-mcp
tramai-platform
tramai-dashboard
tramai-security
tramai-sovereign
tramai-persistence-file
tramai-persistence-jdbc
tramai-spring-boot-starter-sovereign
tramai-spring-boot-starter-sovereign-persistence-file
tramai-spring-boot-starter-sovereign-persistence-jdbc
tramai-spring-boot-starter-sovereign-ops
tramai-spring-boot-starter-sovereign-ops-actuator
tramai-spring-boot-starter-sovereign-ops-micrometer
tramai-spring-boot-starter-sovereign-ops-observability
tramai-spring-boot-starter-sovereign-ops-rest

Those modules are real and implemented. They should not be described as "planned only", but they should still be treated as faster-moving than the narrowest core contract.

Stable contract areas include:

@AiService, @Operation, and @SystemPrompt
provider registry and explicit model routing
standalone builder and Spring Boot configuration binding
structured-output schema generation, parsing, and validation loop
engine-owned retries, fallback routing, circuit breaking, caching, and token budgets
observability module spans and metric instrument names documented in the guides
orchestration workflow definition, observation, checkpoint/resume, and optional lease contracts documented in the guides

Stable orchestration contract:

workflow(...), WorkflowBuilder, and Workflow
WorkflowContext(workflowId, attributes)
StopPolicy(maxStepExecutions, maxParallelBranches)
WorkflowObserver
GateDecision
step shapes: localStep(...), aiStep(...), gateStep(...), branchStep(...), parallelStep(...)
checkpoint/resume SPI: WorkflowPersistence, WorkflowStateCodec, WorkflowCheckpointStore, WorkflowCheckpoint
optional lease SPI: WorkflowLeaseStore, WorkflowLeasePolicy, WorkflowLease

Explicitly out of scope for the narrower 0.4.x compatibility contract:

typed deadline or budget-hint fields in WorkflowContext
max-round or terminal-predicate controls in StopPolicy
mid-step replay or token-level stream resume

Experimental Surface

These public APIs are intentionally not covered by the narrowest 0.4.x stability promise.

Codex/ChatGPT Auth-File Reuse

The OpenAI auth-file path is experimental.

That includes:

@ExperimentalCodexAuth
OpenAiProvider.codexAuth(...)
OpenAiCompatibleProvider.codexAuth(...)
Spring properties under tramai.providers.openai.codex-auth.*
Spring properties under tramai.providers.openai-compatible.codex-auth.*

Release Baseline Assumptions

The 0.4.x line is documented against these baseline assumptions:

Java 21+
Kotlin-first APIs with Java-friendly blocking interfaces
framework-agnostic core with optional Spring integration
0.4.x security preview: tramai-security is opt-in, while tramai-sovereign is documented as the secure profile

If any of those assumptions change, that should be treated as release-level change, not quiet drift.

Current Audit Summary

The current 0.4.x documentation sweep concludes:

the core and application-facing library surface is broad but still documentable as a coherent contract
experimental areas should stay explicit in code and docs
the biggest documentation risk is no longer missing modules, but confusing release-line modules with newer operational and sovereign surfaces
top-level docs should always make the stability split visible instead of burying it in release notes or board history