TramAI is a Kotlin-first JVM runtime for governed AI workflows, combining typed AI contracts with runtime policy, human approval, controlled model routing, and verifiable execution evidence.
TramAI is under active development. TramAI 0.5.0 is the current release candidate. Version 0.4.0 remains the latest published release until 0.5.0 completes Central Portal publication. Work on the next release train is under active development on
master. See Project Status. The canonical Product Positioning defines audiences, pillars, boundaries, and messaging.
| Ordinary AI integration | Governed AI workflow |
|---|---|
| Call a model | Call a model through explicit runtime boundaries |
| Register a tool | Authorize the tool before exposure and execution |
| Retry on failure | Preserve typed failure and evidence semantics |
| Add an approval flag | Suspend and resume through a durable approval lifecycle |
| Log a request | Record governance decisions in structured audit evidence |
| Select a provider | Route according to data and trust policy |
Calling an LLM is easy. Governing what data it sees, which model handles it, which actions it may perform, who approves sensitive outcomes, and how the execution is reconstructed later is the harder problem.
git clone https://github.com/GionaGranchelli/tramAI.git
cd tramAI
./gradlew :examples:governed-workflow:runExpected output (deterministic — no model or credentials required):
✓ Low-risk claim: ready-for-review — Policy and approval gates passed
✓ Restricted claim: rejected — Restricted claim requires manual handling
✓ High-risk unapproved claim: rejected — High-risk claim requires human approval
✓ High-risk approved claim: ready-for-review — Policy and approval gates passed
This introductory example demonstrates typed workflow composition and deterministic gates. It does not represent the complete durable approval, persistence, audit, or sovereign-runtime stack.
Typed input
↓
Data classification
↓
Configured policy and DLP
↓
Allowed provider route — or denial
↓
Model response validated against a typed contract
↓
Tool exposure and execution policy
↓
Optional human approval and suspension
↓
Replay-safe continuation
↓
Audit, evidence, and operational recovery
Governance, routing, approval, persistence, and evidence are composable capabilities. Their guarantees apply when the corresponding components are configured.
JVM interfaces, structured output, schema generation, validation, and deterministic testing — no raw prompt plumbing.
Configurable policy enforced before models, tools, and responses proceed. When the secure policy engine is configured, unknown tools, models, and providers are denied by default.
Approval, suspension, denial, idempotency, and replay-safe continuation. High-risk operations are gated by human decisions that leave durable evidence.
Local, trusted, or approved provider zones selected based on workflow classification and policy.
Audit sequencing, evidence export, durable stores, outbox recovery, and worker observability. Tamper-evident audit records when configured.
Standalone and Spring Boot integration. Adopt only the capabilities you need without a mandatory hosted control plane.
| Goal | Start here |
|---|---|
| Run a governed workflow with no credentials | examples/governed-workflow |
| Understand governed workflow concepts | Governed Workflow Quickstart |
| See real approval suspension and resume | examples/approval-resume |
| Inspect the complete sovereign architecture | examples/sovereign-document-intelligence |
| Make a basic AI call | 30-Minute Quickstart |
| Integrate with Spring Boot | Spring Boot Guide |
| Test workflows deterministically | Governed Workflow Testing |
| Compare every example and its prerequisites | Example Selection Guide |
| Decide between TramAI, Spring AI, and LangChain4j | JVM AI Framework Comparison |
| Understand current maturity | Project Status |
- Core runtime — typed services, engine, structured output, testing
- Provider adapters — Ollama, OpenAI-compatible APIs, Anthropic, Azure OpenAI, Bedrock, Gemini, DeepSeek
- Governance runtime — policy, DLP, routing, approval, persistence, audit, evidence, operations
- Optional extensions — orchestration, RAG, memory, scheduling, server, observability, platform, MCP workflow server
See the Architecture Overview and Sovereign Runtime Module Matrix for detailed module descriptions.
| Boundary | Status |
|---|---|
| Typed services and structured output | Released / evolving |
| Governance and sovereign capabilities on master | Implemented / evolving |
| Sovereign runtime | RC+ enterprise proof milestone |
| Stable sovereign 1.0 API | Not yet available |
| Compliance or certification | Not claimed |
| Production readiness for every deployment | Not claimed |
| MCP workflow server | Implemented / evolving |
| Governed remote MCP tool connector | Not implemented |
./gradlew test # run all tests
./gradlew check # full build validation
./gradlew publishToMavenLocal # publish to local MavenTramAI targets JVM 21+. Building the repository requires a JDK 21 toolchain.
- JVM AI Framework Comparison — when to choose TramAI, Spring AI, or LangChain4j
- Beyond the Model Call — publishable introduction to governed AI workflows on the JVM
- Example Selection Guide — choose a demo, integration sample, reference workflow, or verification harness
- Product Positioning — canonical positioning, audiences, pillars, claim boundaries
- Project Status — detailed implementation and maturity tracking
- Post-Sovereignty Roadmap — current and planned development phases
- Guides — quickstart, governed workflows, testing, approval taxonomy
- Security Model — threat model and abuse scenarios
- Runtime Evidence — evidence record shape and export
- API Stability — stable, preview, internal, and deferred surfaces
Apache 2.0 © Giona Granchelli