TramAI examples serve different purposes: some teach the basic API, some demonstrate governed workflow composition, some prove durable approval or sovereign-runtime behavior, and some are verification harnesses rather than application templates.
TramAI is under active development. Examples reflect the current state of the project; see Project Status for detailed maturity tracking.
Use this guide to select the smallest example that answers your question.
New to TramAI? Start with:
./gradlew :examples:governed-workflow:runIt is deterministic, requires no credentials or external model, and shows typed workflow composition, policy gates, approval gates, and failure paths.
This example demonstrates composition. It does not demonstrate durable approval storage, replay persistence, audit export, or sovereign deployment.
| Goal | Recommended path |
|---|---|
| Learn governed AI service, policy, and approval patterns | Tool Governance |
| See a governed workflow in five minutes | Governed Workflow |
| Learn typed AI services, tools, and structured output | Support Agent |
| Explore a conventional Spring Boot backend integration | Kotlin Spring Boot Example |
| Test durable approval suspension and resume | Approval Resume |
| Learn sovereign Spring Boot auto-configuration | Spring Sovereign Starter |
| Inspect the complete sovereign reference architecture | Sovereign Document Intelligence |
| Verify offline/zero-egress runtime behavior | Sovereign Offline Verification |
| Run a real local-model sovereign environment | Sovereign Lab |
| Example | Type | Real model | External infrastructure | Persistence | Governance depth | Primary command |
|---|---|---|---|---|---|---|
| Tool Governance | Learning demo | No | None | None | Tool permission outcomes | ./gradlew :examples:tool-governance:run |
| Governed Workflow | Learning demo | No | None | None | Composition | ./gradlew :examples:governed-workflow:run |
| Support Agent | Core API demo | Ollama for runtime | Ollama | None | Basic AI integration | ./gradlew :examples:support-agent:run |
| Kotlin Spring Boot | Integration application | Ollama | Ollama | File checkpoints | Core workflow integration | ./gradlew -p examples/kotlin-springboot-example bootRun |
| Approval Resume | Lifecycle proof | Deterministic | Embedded PostgreSQL | JDBC | Durable approval | ./gradlew :examples:approval-resume:test |
| Spring Sovereign Starter | Starter integration | Deterministic | None for basic path | In-memory by default | Sovereign configuration | ./gradlew :examples:spring-sovereign-starter:bootRun |
| Sovereign Document Intelligence | Reference workflow | Repository-local example provider | None required | Runtime stores/artifacts | Full reference architecture | ./gradlew :examples:sovereign-document-intelligence:run |
| Sovereign Offline Verification | Verification harness | Loopback provider | Docker + Python 3 | Evidence files | Offline verification | ./scripts/verify-zero-egress.sh |
| Sovereign Lab | Physical lab | Yes, local | PostgreSQL, local model, optional Docker | JDBC | Full local evaluation | Follow lab quickstart in sovereign-lab/README.md |
The examples above are part of the root Gradle build. The following are separate Gradle builds with their own settings.gradle.kts that prove different standalone TramAI consumer configurations:
| Example | Consumer type | Primary command |
|---|---|---|
| Kotlin Spring Boot | Standalone composite/local consumer (includeBuild("../..")), version overridable via -PtramaiVersion |
./gradlew -p examples/kotlin-springboot-example bootRun |
| Kotlin Native Smoke | Standalone composite/local consumer (includeBuild("../..")) |
./gradlew -p examples/kotlin-native-smoke-example nativeSmokeCompile |
| Sovereign Runtime Consumer Smoke | Release-verification-repository consumer — does NOT use the composite build; resolves dev.tramai exclusively from a local verification repo, deliberately excluding dev.tramai from Maven Central |
./gradlew -p examples/sovereign-runtime-consumer-smoke test -PsovereignRuntimeVerificationRepo=<verification-repo-path> -PtramaiVersion=<version> |
For the sovereign consumer smoke, the verification repo is produced by verifySovereignRuntimeSignedBundle; the build fails fast if -PsovereignRuntimeVerificationRepo is missing.
These builds are not module-catalog modules and are excluded from module-card and module-dependency-graph coverage by design.
Choose this when: you want to understand tool permission outcomes (ALLOW, DENY, REQUIRE_APPROVAL) and the dedicated tool.permission runtime evidence family.
Run:
./gradlew :examples:tool-governance:runRequires: nothing — deterministic, no credentials, no external model, no Docker.
Demonstrates: three deterministic tool governance scenarios — read-only lookup (ALLOW), account deletion (DENY via policy wrapper), payment (REQUIRE_APPROVAL via approval suspension). Each scenario verifies tool execution count, enforcement point decisions, and dedicated tool.permission runtime evidence export. Shows that tool enforcement events are excluded from generic policy.decision evidence.
Does not demonstrate: durable approval storage, replay persistence, audit export, sovereign deployment, REDACT_RESULT, ALLOW_INTERNAL_ONLY, or MCP governance.
Next step: Governed Workflow for composition patterns, or Approval Resume for durable human approval.
Choose this when: this is your first TramAI evaluation.
Run:
./gradlew :examples:governed-workflow:runRequires: nothing — deterministic, no credentials, no external model.
Demonstrates: typed workflow composition — aiStep wrapping a deterministic classifier, gateStep for policy and approval enforcement, localStep for finalization, four success and rejection scenarios.
Does not demonstrate: durable approval storage, replay persistence, audit export, sovereign deployment.
Next step: Approval Resume for durable human approval, or Sovereign Document Intelligence for the full reference architecture.
Choose this when: you want the smallest real local-model example using annotations, tools, structured output, retry, and deterministic tests.
Run:
./gradlew :examples:support-agent:runRequires: Ollama with gemma4:e2b for the runtime path. Tests use MockAiProvider and do not require Ollama.
Demonstrates: @AiService annotations, typed Response output with @AiDescription fields, tool calling, retry policies, and deterministic testing with MockAiProvider.
Does not demonstrate: sovereign governance, durable approval, policy enforcement, audit evidence, or sovereign persistence. This is a core AI integration example consuming released 0.6.0 artifacts.
Next step: Kotlin Spring Boot Example for a fuller application, or Governed Workflow for governance.
Choose this when: you want to see TramAI inside a conventional Spring Boot HTTP application.
Run:
./gradlew -p examples/kotlin-springboot-example bootRunRequires: a separate Gradle build (not part of the root project), released TramAI 0.6.0 dependencies (version overridable via -PtramaiVersion), Ollama, and the configured models:
ollama pull gemma4:e4b
ollama pull deepseek-r1:8b-64kSee the Kotlin Spring Boot example README for endpoints and manual requests.
Demonstrates: raw text generation, streaming responses, tool calling, structured output mapped to typed DTOs, HTTP endpoints, persisted workflow orchestration with checkpoint inspection and resume.
Does not demonstrate: the sovereign Spring starter path; its file-based workflow persistence is not the same as sovereign approval/audit persistence.
Next step: Spring Sovereign Starter for sovereign auto-configuration.
Choose this when: you specifically want to understand durable human approval.
Run:
./gradlew :examples:approval-resume:testRequires: embedded PostgreSQL only — no Docker, no external model, no credentials.
Demonstrates: low-value bypass, high-value suspension, approved and denied decision paths, repeated-resume behavior, and an at-most-once reimbursement side effect.
Does not demonstrate: every workflow resuming exactly once, every side effect executing exactly once, every database configuration, or production reviewer authorization.
Next step: Sovereign Document Intelligence for the full reference architecture combining routing, approval, audit, and evidence.
Choose this when: you want to understand how the sovereign runtime is integrated through Spring Boot configuration and auto-configuration.
Run:
./gradlew :examples:spring-sovereign-starter:bootRunRequires: nothing for the basic path — a deterministic local provider, no cloud call, no API key.
Demonstrates — basic path: SovereignTramaiRuntime auto-configuration, typed @AiService with @Operation, in-memory audit, approval, continuation, and suspension stores.
Note: state is lost on restart in the basic in-memory path.
Demonstrates — advanced paths: encrypted file persistence, JDBC persistence, operational services, Actuator and observability modules. See the full starter README for advanced configuration.
Does not demonstrate: a full sovereign evidence chain, durable audit persistence in the basic path, or production IAM.
Next step: Sovereign Lab for a physical environment, or Sovereign Document Intelligence for a bounded reference workflow.
Choose this when: you want the deepest self-contained architectural example.
Run:
./gradlew :examples:sovereign-document-intelligence:runA --release-bundle-manifest argument is available for release/evidence artifact generation but is optional for the standard run.
Requires: nothing — uses a repository-local example provider. No credentials, no external infrastructure.
Demonstrates: restricted input classification, local-only routing, policy enforcement, approval suspension, replay-safe continuation, audit chain, and evidence artifacts.
Important: this is a reference workflow, not a production deployment template.
Next step: Sovereign Offline Verification for controlled offline verification, or Sovereign Lab for a real local model.
Choose this when: you are evaluating offline-runtime and zero-egress evidence behavior.
Primary command:
./scripts/verify-zero-egress.shSee the verification script for implementation details.
Requires: Docker and Python 3. The script builds the verification image, runs it with --network=none, and validates the generated report. No real model or API credentials are required.
Demonstrates: creating a temporary local model artifact, verifying its digest, using a loopback HTTP provider, configuring the runtime in OFFLINE mode, executing external network probes, and writing verification and evidence output.
Important: this is a verification harness, not an application template. A successful harness run is evidence about that controlled run; it does not prove universal zero-egress behavior for every deployment.
Next step: Sovereign Lab for physical local-model evaluation.
Choose this when: you want to evaluate TramAI with a real local model and production-like supporting infrastructure.
Entry levels:
No-infrastructure smoke (no model or Docker required):
./gradlew verifySovereignLabProfile
./gradlew verifySovereignLabRuntimeSmokeThese validate configuration and Spring wiring without invoking a real model.
Physical lab (requires infrastructure):
- Java 21+
- PostgreSQL
- A local OpenAI-compatible model endpoint (Ollama, llama.cpp, vLLM, LM Studio, or LocalAI)
- Encryption key
- Optionally Docker Compose
See the Sovereign Lab README for the full setup guide.
Demonstrates: full local-model sovereign evaluation with PostgreSQL persistence, approval workflow, REST control plane, reviewer UI, evidence bundles, and zero-egress configuration.
Important: this is an advanced, operator/evidence-oriented evaluation path. It is not suitable as the first example and requires more infrastructure than the self-contained reference workflows.
Next step: review the sovereign-lab README for detailed setup, or refer to Sovereign Offline Verification for a lighter verification path.
governed-workflow → approval-resume → sovereign-document-intelligence
support-agent → kotlin-springboot-example → spring-sovereign-starter
spring-sovereign-starter → sovereign-document-intelligence → sovereign-offline-verification → sovereign-lab
./gradlew test → ./gradlew check → sovereign runtime closure tasks → offline verification harness
These are learning and evaluation paths, not maturity certification levels.
- Running an example does not establish compliance.
- A successful example is not a security certification.
- LOCAL is a configured trust zone, not automatic proof of physical isolation.
- A zero-egress harness result applies to the observed test environment.
- Deterministic providers do not prove model quality.
- Human approval does not prove that the underlying decision was correct.
- Examples are not production deployment templates unless explicitly stated.
- Governed remote MCP tool import is not demonstrated.