Module: tramai-engine

dependencies {
    implementation("dev.tramai:tramai-engine:0.3.1")
}

<dependency>
    <groupId>dev.tramai</groupId>
    <artifactId>tramai-engine</artifactId>
    <version>0.3.1</version>
</dependency>

implementation(platform("dev.tramai:tramai-bom:0.3.1"))
implementation("dev.tramai:tramai-engine")

import dev.tramai.engine.TramaiEngine
import dev.tramai.core.annotations.AiService
import dev.tramai.core.annotations.Operation
import dev.tramai.core.annotations.SystemPrompt
import dev.tramai.openai.OpenAiProvider

// 1. Define your AI service interface
@AiService
@SystemPrompt("You are a helpful assistant.")
interface Summarizer {
    @Operation(
        prompt = "Summarize the following text in one sentence",
        model = "gpt-4o",
    )
    fun summarize(text: String): String
}

// 2. Create the engine
val provider = OpenAiProvider(apiKey = System.getenv("OPENAI_API_KEY"))
val engine = TramaiEngine(provider)

// 3. Get a proxy and call it
val service = engine.create<Summarizer>()
val summary = service.summarize("Long article text...")
println(summary) // "The article discusses..."

// 4. Clean up
engine.close()

@AiService
@SystemPrompt("You are a precise billing assistant.")
interface SuspendAnalyzer {
    @Operation(
        prompt = "Analyze the invoice and return a raw summary",
        model = "claude-sonnet-4-20250514",
    )
    suspend fun analyze(invoiceId: String): String
}

// Usage
val result = runBlocking { service.analyze("invoice-123") }

val engine = TramaiEngine(
    provider = provider,
    retryPolicySettings = RetryPolicySettings(
        maxRetryAfterMillis = 30_000,   // cap for provider-supplied Retry-After headers
        jitterRatio = 0.2,              // 20% random jitter added to delay
    ),
)

@Operation(
    prompt = "Analyze under rate limiting",
    model = "gpt-4o",
    providerRetries = 5,   // up to 5 retries on this route before fallback
)
suspend fun analyze(id: String): String

val engine = TramaiEngine(
    provider = provider,
    circuitBreakerSettings = CircuitBreakerSettings(
        enabled = true,
        failureThreshold = 3,         // 3 consecutive failures opens the circuit
        openDurationMillis = 30_000,  // stay open for 30 seconds
    ),
)

val engine = TramaiEngine(
    provider = provider,
    responseCache = InMemoryOperationResponseCache(
        maxEntries = 1_000,   // LRU eviction
    ),
)

@Operation(
    prompt = "Classify this text",
    model = "gpt-4o-mini",
    cacheable = true,
    cacheTtlMillis = 60_000,   // 1 minute TTL
)
fun classify(text: String): String

val engine = TramaiEngine(
    provider = provider,
    tokenBudgetSettings = TokenBudgetSettings(
        hardMaxTokensPerAttempt = 4_000,           // fail if a single response exceeds 4K tokens
        hardMaxTokensPerOperation = 16_000,         // fail if cumulative tokens across retries exceed 16K
        softMaxTokensPerOperation = 10_000,         // emit event (no failure) at 10K cumulative
    ),
)

val registry = ProviderRegistry.builder()
    .provider("anthropic", AnthropicProvider(apiKey = "..."))
    .provider("fallback", OllamaProvider(baseUrl = "http://localhost:11434"))
    .model("claude-sonnet-4-20250514", "anthropic")
    .fallbackModel("claude-sonnet-4-20250514", "llama3.2", "fallback")
    .build()

val engine = TramaiEngine(providerRegistry = registry)

@Operation(
    prompt = "Analyze with Ollama explicitly",
    model = "claude-sonnet-4-20250514",
    provider = "ollama",           // bypass model→provider resolution
)
suspend fun analyze(id: String): String

import dev.tramai.structured.JacksonStructuredOutputHandler

data class InvoiceAnalysis(
    val total: Double,
    val currency: String,
    val isFraudulent: Boolean,
)

@AiService
interface InvoiceService {
    @Operation(
        prompt = "Analyze this invoice for fraud indicators",
        model = "claude-sonnet-4-20250514",
        maxRetries = 2,   // structured-output retries on parse failure
    )
    suspend fun analyze(invoiceId: String): InvoiceAnalysis
}

// Usage
val engine = TramaiEngine(
    provider = provider,
    structuredOutputHandler = JacksonStructuredOutputHandler(),
)
val service = engine.create<InvoiceService>()
val result = service.analyze("INV-042")
println(result.total)        // Double
println(result.isFraudulent) // Boolean

import kotlinx.coroutines.flow.Flow
import dev.tramai.core.model.StreamChunk

@AiService
interface StreamingService {
    @Operation(
        prompt = "Stream a detailed analysis",
        model = "claude-sonnet-4-20250514",
    )
    fun stream(invoiceId: String): Flow<StreamChunk>
}

// Usage
runBlocking {
    service.stream("INV-042").collect { chunk ->
        when (chunk) {
            is StreamChunk.Token -> print(chunk.text)
            is StreamChunk.Complete -> println("\n[Done: ${chunk.usage.outputTokens} tokens]")
            is StreamChunk.Error -> System.err.println("Error: ${chunk.cause.message}")
        }
    }
}

import dev.tramai.core.model.ToolResult
import dev.tramai.core.model.ToolExecutionContext
import dev.tramai.core.model.ResolvedTool
import dev.tramai.core.model.SideEffectLevel

val lookupTool = object : ResolvedTool {
    override val name = "lookup"
    override val description = "Looks up a tenant by ID"
    override val inputSchemaJson = """{"type":"object","properties":{"id":{"type":"string"}}}"""
    override val idempotent = true     // allows retry on transient failure
    override val sideEffectLevel = SideEffectLevel.READ_ONLY

    override suspend fun execute(input: Any, context: ToolExecutionContext): ToolResult {
        val id = (input as Map<*, *>)["id"] as? String ?: return ToolResult.InvalidInput("missing id")
        return ToolResult.Success("""{"name":"Acme Corp"}""")
    }
}

val engine = TramaiEngine(
    provider = provider,
    toolRegistry = ToolRegistry(mapOf(lookupTool.name to lookupTool)),
)

@AiService
interface QueryService {
    @Operation(
        prompt = "Look up the tenant",
        model = "claude-sonnet-4-20250514",
        tools = ["lookup"],
    )
    suspend fun query(tenantId: String): String
}

class RedisOperationResponseCache(
    private val redis: RedisClient,
) : OperationResponseCache {
    override fun get(key: OperationCacheKey): Any? {
        // Deserialize from Redis
    }

    override fun put(key: OperationCacheKey, value: Any, ttlMillis: Long) {
        // Serialize and store in Redis with TTL
    }
}

val redactingInterceptor = object : OperationInterceptor {
    override fun interceptRequest(
        context: OperationCallContext,
        messages: List<Message>,
    ): List<Message> = messages.map {
        it.copy(content = it.content.replace(Regex("\\b\\d{16}\\b"), "****-****-****-****"))
    }

    override fun interceptResponse(
        context: OperationCallContext,
        response: ModelResponse,
    ): ModelResponse = response.copy(
        content = response.content.replace(Regex("\\b\\d{16}\\b"), "****-****-****-****"),
    )
}

val engine = TramaiEngine(
    provider = provider,
    operationInterceptor = redactingInterceptor,
)

class MetricCollectingObserver : OperationObserver {
    override fun onCallStarted(context: OperationCallContext): OperationObservation {
        val startTime = System.nanoTime()
        return object : OperationObservation {
            override fun onProviderResponse(response: ModelResponse) { /* record */ }
            override fun onProviderFailure(error: Throwable) { /* record */ }
            override fun onStructuredParseFailure(rawResponse: String, errorSummary: String) { /* record */ }
            override fun onEngineEvent(name: String, attributes: Map<String, Any?>) { /* record */ }
            override fun onCallCompleted(parseSuccess: Boolean?) {
                val elapsed = System.nanoTime() - startTime
                metrics.recordLatency(context.providerId, context.methodName, elapsed)
            }
        }
    }
}

dependencies {
    implementation("dev.tramai:tramai-memory:0.3.1")
}

val memory = MessageWindowChatMemory(
    maxMessages = 20,        // non-system messages per conversation
    maxConversations = 1000, // active conversations before LRU eviction
)

val engine = TramaiEngine(
    provider = provider,
    chatMemory = memory,     // enables history injection + persistence
)

@AiService
interface ChatService {
    @Operation(prompt = "Answer the user's question", model = "claude-sonnet-4-20250514")
    suspend fun chat(
        @ConversationId sessionId: String,
        message: String,
    ): String
}

tramai-engine
  ├── api: tramai-core (annotations, models, providers, exceptions, observation SPI)
  ├── impl: kotlinx-coroutines-core
  ├── impl: kotlin-reflect
  └── test: tramai-structured (JacksonStructuredOutputHandler)

┌─────────────────────────────────────────────────────────────────────┐
│ TramaiEngine.create(ServiceType)                                    │
│   │                                                                 │
│   ├─ ServiceDefinition.create(serviceType, toolRegistry)            │
│   │   ├─ Validate: is interface? has @AiService?                    │
│   │   ├─ Read @SystemPrompt (optional)                              │
│   │   └─ For each method (excluding Object methods):                │
│   │       ├─ Read @Operation (required, fail if missing)            │
│   │       ├─ Resolve tool names → ToolDefinition[]                  │
│   │       ├─ Determine return kind (String/Unit/STRUCTURED/STREAMING│
│   │       │   via Kotlin reflection or Java fallback)               │
│   │       ├─ Detect suspend vs blocking via Continuation parameter  │
│   │       └─ Store as OperationDefinition in method→op map          │
│   │                                                                 │
│   └─ TramaiInvocationHandler(providerRegistry, cache, circuit,      │
│       retry, tokenBudget, observer, interceptor, definition,        │
│       chatMemory, conversationIdProvider)                           │
│         │                                                           │
│         └─ Proxy.newProxyInstance(loader, [ServiceType], handler)   │
│                                                                     │
│ On method invocation:                                               │
│   handler.invoke(proxy, method, args)                               │
│     ├─ Object method? → delegate to toString/hashCode/equals        │
│     ├─ Resolve conversationId from @ConversationId or provider      │
│     ├─ Suspend? → launch in engine scope, return COROUTINE_SUSPENDED│
│     └─ Blocking? → runBlocking { execute(op, args) }                │
│                                                                     │
│   execute(op, args):                                                │
│     ├─ ReturnKind.STRING → executeRaw → executeWithTools            │
│     ├─ ReturnKind.UNIT → executeRaw, return Unit                    │
│     ├─ ReturnKind.STRUCTURED → executeStructured (retry loop)       │
│     └─ ReturnKind.STREAMING → executeStreaming (Flow)               │
└─────────────────────────────────────────────────────────────────────┘

For each candidate route (primary → fallback1 → fallback2):
  Repeat up to (providerRetries + 1) times:
    Call provider
    If success → return
    If retryable error (TimeoutException, ProviderException(retryable=true)):
      Compute delay = min(retryAfterHint, maxRetryAfterMillis) + jitter
      Emit "tramai.retry.scheduled" event
      Delay and retry
    If non-retryable error → throw immediately
  After exhausting retries → fall through to next route

For structured return types, after Level 1 succeeds:
  Parse response through StructuredOutputHandler
  If Success → return value
  If Failure:
    If maxRetries not exceeded → append corrective messages, retry Level 1
    If exhausted → throw StructuredOutputException

rawDelay = error.retryAfterMillis  (from ProviderException)
           ?: INITIAL_PROVIDER_RETRY_DELAY_MILLIS shl retryIndex  (50ms, 100ms, 200ms...)
capped  = min(rawDelay, maxRetryAfterMillis)
jitter  = capped * jitterRatio * random(0..1)
delay   = capped + jitter

CLOSED ──(consecutive failures >= threshold)──→ OPEN
OPEN ──(openDurationMillis elapsed)──→ HALF_OPEN (next call probes)
HALF_OPEN ──(success)──→ CLOSED
HALF_OPEN ──(failure)──→ OPEN