TramAI

Architecture Overview

TramAI is a structured-first, observability-native AI workflow library for the JVM. The core product goal is to let application code interact with AI through typed interface methods instead of framework-specific chains, agents, or prompt orchestration objects.

Core Flow

  1. Application code defines an @AiService interface.
  2. TramAI generates a proxy for that interface at startup.
  3. A method call is translated into an AI operation.
  4. Inputs are rendered into model messages.
  5. If the return type is structured, TramAI generates or loads a cached schema and validates the response.
  6. The provider call is wrapped in observability instrumentation when OpenTelemetry is available.
  7. The provider returns raw model output plus metadata.
  8. TramAI either returns raw text, streams chunks, or parses and validates structured output.
  9. Parse failures enter a retry loop with validation feedback.

Layer Stack

In a Spring Boot application, TramAI adds AI as a 4th architectural layer:

Presentation Layer   @Controller / @RestController  — HTTP endpoints
Business Logic       @Service                       — Application logic
AI Layer             @AiService                      — Typed AI contracts  ← NEW
Persistence          @Repository / @Entity           — Data access

The @AiService annotation marks an interface as an AI service contract. @EnableTramai on a configuration class imports TramaiAutoConfiguration, which wires providers, DLP interceptors, caching, retry policies, and circuit breakers through Spring DI. AI services are injected as Spring beans.

In standalone mode (no Spring), the same typed contract pattern applies via Tramai.create<Service>() — the engine-owned infrastructure still exists, just without the DI container.

Major Layers

Application Layer
    @AiService interfaces — any framework or plain JVM

Proxy Layer
    JDK Dynamic Proxy generated at startup
    Intercepts method calls, routes to Operation Engine

Operation Engine
    Prompt Renderer | Structured Output Parser | Retry/Error Handler

Observability Layer
    OTel span wraps every provider call
    GenAI semantic conventions, auto-detected

Provider Layer
    Anthropic Provider | OpenAI Provider | Ollama Provider

Application Layer

Consumer-defined @AiService interfaces. This is the only API surface most developers interact with.

Proxy Layer

Runtime-generated implementations that intercept method calls and transform them into AI operations. Uses JDK dynamic proxies.

Operation Engine

Prompt rendering, provider dispatch, streaming, tool calling, parsing, retry, and error handling. This is where all the intelligence lives.

Observability Layer

OpenTelemetry spans, metrics, and semantic attributes, auto-detected when OTel is on the classpath.

Provider Layer

Implementations for Anthropic, Ollama, OpenAI, and OpenAI-compatible providers. Each is a separate opt-in module.

Orchestration Layer (Optional)

Typed workflow coordination above the engine. Includes aiStep, localStep, gateStep, branchStep, and parallelStep.

Architectural Priorities

  1. Typed contracts over prompt engineering — Application code never manipulates raw prompt strings
  2. Framework-agnostic core with optional adapters
  3. Automatic observability with OpenTelemetry semantic conventions
  4. Kotlin-first APIs with Java-compatible entry points
  5. Narrow v1 scope with explicit exclusions for autonomous agent loops, RAG, and hidden orchestration

Design Philosophy

  1. Typed contracts over prompt engineering — Inputs and outputs are typed data classes, not raw strings
  2. Observable by default — Every AI call emits an OpenTelemetry span automatically
  3. Fail loudly, recover gracefully — Structured output failures are retried with validation feedback
  4. Boring to use, interesting to build — Minimal consumer API surface
  5. Kotlin-native, Java-friendly — Idiomatic Kotlin APIs with Java-callable entry points everywhere

v1 Boundaries

TramAI v1 deliberately does not include:

  • RAG or vector stores
  • autonomous agent loops
  • conversation memory
  • prompt dashboards or registries
  • fine-tuning workflows

These are explicitly excluded from the v1 scope.

Module Structure

TramAI's current repository inventory is broader than the old 31-module framing. The TramAI MCP currently exposes 41 framework modules plus 4 reference examples.

The useful split is between release-line foundations, runtime/platform modules, and sovereign/security preview modules. Key modules include:

tramai-core           — Annotations, interfaces, data models — zero dependencies
tramai-engine         — Proxy generation, operation execution, retry logic
tramai-structured     — Schema generation (Jackson), response parsing, validation
tramai-observability  — OTel integration, span emission, GenAI conventions
tramai-anthropic      — Anthropic API provider
tramai-openai         — OpenAI API provider and OpenAI-compatible adapter base
tramai-azure-openai   — Dedicated Azure OpenAI provider module
tramai-deepseek       — Dedicated DeepSeek provider module
tramai-bedrock        — Dedicated AWS Bedrock provider module
tramai-ollama         — Ollama local provider
tramai-standalone     — Minimal entry point for plain JVM usage
tramai-spring         — Optional Spring Boot autoconfiguration adapter
tramai-testing        — Test utilities, mock provider, assertion helpers
tramai-bom            — Bill of materials for version management
tramai-orchestration  — Typed workflow composition and checkpoint/resume
tramai-scheduler      — Cron-backed workflow scheduling
tramai-server         — REST API, webhooks, SSE
tramai-mcp            — MCP protocol adapter
tramai-platform       — Multi-tenancy, API keys, plugins, audit
tramai-dashboard      — Admin dashboard SPA
tramai-rag            — Retrieval-Augmented Generation pipeline
tramai-embedding      — Embedding generation
tramai-memory         — Conversation memory management
tramai-security       — Policy enforcement, approval, audit, and DLP preview
tramai-sovereign      — Sovereign runtime profile and secure-by-default deployment mode
tramai-persistence-file  — File-backed sovereign persistence
tramai-persistence-jdbc  — JDBC-backed sovereign persistence

See Module Design for the current dependency split and module boundaries.

Related Pages

Previous
Next