TramAI

Annotation Reference

TramAI currently uses a small annotation set.

@AiService

Marks an interface as a TramAI service contract.

Use it on interfaces only.

@AiService
interface Summarizer

@Operation

Declares an AI-backed method.

Fields:

  • prompt: base user prompt
  • model: logical model name
  • provider: optional explicit provider id override
  • tools: optional list of tool names available to the operation
  • maxRetries: structured-output retry count
  • providerRetries: provider retry count for transient failures
  • timeoutMillis: per-attempt provider timeout in milliseconds
  • cacheable: enables engine-owned caching for successful non-streaming responses
  • cacheTtlMillis: cache lifetime in milliseconds when caching is enabled

Example:

@Operation(
    prompt = "Summarize the incident",
    model = "gpt-4o",
    provider = "openai",
    tools = ["lookup"],
    maxRetries = 3,
    providerRetries = 2,
    timeoutMillis = 15_000,
    cacheable = true,
    cacheTtlMillis = 60_000,
)

@SystemPrompt

Applies a service-wide system prompt to all operations on the interface.

@AiService
@SystemPrompt("You are a precise billing assistant.")
interface BillingAnalyzer

@AiTool

Marks a function, method, or class as a tool that AI models can invoke.

Use on:

  • Methods within an @AiService interface to declare tools
  • Standalone classes implementing TramaiTool interface

Fields:

  • name: explicit tool name (defaults to method name)
  • description: tool description for model tool definitions
  • idempotent: safe to retry on transient failure (default: false)
  • sideEffectLevel: side-effect classification — UNKNOWN, NONE, READ_ONLY, MUTATING (default: UNKNOWN)
@AiTool(
    name = "lookup_vendor",
    description = "Looks up vendor details by ID",
    idempotent = true,
)
suspend fun lookupVendor(vendorId: String): Vendor

@AiDescription

Adds a human-readable description to a structured output property or tool parameter.

Useful for:

  • clarifying field intent
  • making schema prompts less ambiguous
  • documenting tool input parameters

@AiRange

Constrains a numeric field.

@property:AiRange(min = 0.0, max = 1.0)
val confidence: Double

@AiMinItems

Constrains collection length.

@property:AiMinItems(1)
val recommendations: List<String>

Current Annotation Behavior

  • annotations are runtime-retained
  • structured field annotations influence schema generation and validation
  • operation annotations influence prompt rendering and routing

Current Behavior Boundaries

TramAI does not currently use dedicated annotations for:

  • streaming
  • provider-native structured output toggles

Streaming is selected through the return type Flow<StreamChunk>.

Tool calling is enabled through @AiTool annotations and @Operation(tools = [...]) rather than through a single separate annotation.

Conversation state is configured through the tramai-memory module, not through operation-level annotations.

Previous
Next