Module: tramai-core

dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
    implementation("dev.tramai:tramai-core")
}

<dependency>
    <groupId>dev.tramai</groupId>
    <artifactId>tramai-core</artifactId>
    <version>0.6.0</version>
</dependency>

import dev.tramai.core.annotations.*
import dev.tramai.core.model.*

// --- 1. Define a structured output type ---
data class Weather(
    @AiDescription("Temperature in Celsius")
    val temperature: Double,
    @AiDescription("Weather condition description")
    val condition: String,
    @AiRange(min = 0.0, max = 100.0)
    val humidity: Double,
)

// --- 2. Define a tool that the model can call ---
data class GetTimeInput(val timezone: String)

class GetTimeTool : TramaiTool<GetTimeInput, String> {
    override val name = "get_time"
    override val description = "Returns the current time for a given timezone"
    override val inputType = GetTimeInput::class

    override suspend fun execute(input: GetTimeInput, context: ToolExecutionContext): String {
        return "Current time in ${input.timezone} is 12:00 UTC"
    }
}

// --- 3. Define the AI service interface ---
@AiService
@SystemPrompt("You are a helpful weather assistant.")
interface WeatherService {

    @Operation(
        prompt = "What is the weather in {city}?",
        model = "gpt-4o",
        tools = ["get_time"],
        timeoutMillis = 15_000,
    )
    suspend fun getWeather(city: String): Weather

    @Operation(
        prompt = "Summarize the weather for the next week.",
        model = "gpt-4o-mini",
        cacheable = true,
    )
    suspend fun summarizeForecast(data: String): String
}

import dev.tramai.core.model.*
import dev.tramai.core.provider.*

class CustomProvider(
    private val apiKey: String,
) : ModelProvider {
    override suspend fun complete(request: ModelRequest): ModelResponse {
        // Translate ModelRequest -> your API format
        // Call your API
        // Translate response -> ModelResponse
        return ModelResponse(
            content = "Processed: ${request.messages.lastOrNull()?.content ?: ""}",
            inputTokens = 10,
            outputTokens = 5,
            modelUsed = "custom-model",
        )
    }

    override fun providerId(): String = "custom"
}

import dev.tramai.core.model.*
import dev.tramai.core.provider.*
import kotlinx.coroutines.flow.*

class CustomStreamingProvider : ModelProvider, StreamCapable {
    override suspend fun complete(request: ModelRequest): ModelResponse {
        return ModelResponse(content = "Hello!")
    }

    override suspend fun stream(request: ModelRequest): Flow<StreamChunk> = flow {
        emit(StreamChunk.Token("Hello"))
        emit(StreamChunk.Token(" world"))
        emit(StreamChunk.Complete(fullText = "Hello world"))
    }
}

import dev.tramai.core.provider.*

val registry = ProviderRegistry.builder()
    .provider("openai", openAiProvider, default = true)
    .provider("anthropic", anthropicProvider)
    .model("gpt-4o", "openai")
    .model("claude-3-opus", "anthropic")
    .fallbackProvider("gpt-4o", "anthropic") // falls back to Anthropic if OpenAI fails
    .build()

import dev.tramai.core.observation.*

class PiiRedactionInterceptor : OperationInterceptor {
    override fun interceptRequest(
        context: OperationCallContext,
        messages: List<Message>,
    ): List<Message> {
        return messages.map { msg ->
            msg.copy(
                content = msg.content.replace(Regex("\\b\\d{3}-\\d{2}-\\d{4}\\b"), "***-**-****")
            )
        }
    }
}

import dev.tramai.core.secret.*
import java.nio.file.Path

val resolver = CompositeSecretValueResolver(listOf(
    EnvironmentSecretValueResolver,
    FileSecretValueResolver(allowedDirectory = Path.of("/etc/secrets")),
))

val apiKey: String? = resolver.resolve("env:OPENAI_API_KEY")       // null when unset
val apiKey2: String? = resolver.resolve("file:key")               // resolved under the allowed directory

import dev.tramai.core.structured.*
import kotlin.reflect.KType

class CustomSchemaHandler : StructuredOutputHandler {
    override fun createContract(targetType: KType): StructuredOutputContract {
        val schema = generateSchema(targetType)
        return StructuredOutputContract(
            targetType = targetType,
            schemaJson = schema,
        )
    }

    override fun analyze(rawResponse: String, targetType: KType): StructuredOutputResult {
        return try {
            val value = deserialize(parseJson(rawResponse), targetType)
            StructuredOutputResult.Success(value, rawResponse)
        } catch (e: Exception) {
            StructuredOutputResult.Failure(
                rawResponse = rawResponse,
                errorSummary = "Parse failed: ${e.message}",
                feedbackMessage = "Please respond with valid JSON matching the expected schema.",
            )
        }
    }

    override fun generateSchema(type: KType): String = buildSchemaFor(type)
    override fun deserialize(input: Any, targetType: KType): Any = customDeserialize(input, targetType)
    override fun serialize(value: Any): Any = customSerialize(value)
}

import dev.tramai.core.nativeimage.*
import java.nio.file.*

NativeImageProxyConfig.write(
    outputPath = Path.of("META-INF/native-image/reflect-config.json"),
    WeatherService::class,
    StockAnalysisService::class,
)

import dev.tramai.core.observation.*

class MetricsObserver : OperationObserver {
    override fun onCallStarted(context: OperationCallContext): OperationObservation {
        println("[START] ${context.serviceInterface}.${context.methodName} " +
                "attempt #${context.attempt} on ${context.providerId}")
        val startTime = System.nanoTime()
        return object : OperationObservation {
            override fun onProviderResponse(response: ModelResponse) {
                println("[TOKENS] in=${response.inputTokens} out=${response.outputTokens}")
            }
            override fun onProviderFailure(error: Throwable) {
                println("[FAIL] ${error.message}")
            }
            override fun onStructuredParseFailure(rawResponse: String, errorSummary: String) {
                println("[PARSE_FAIL] $errorSummary")
            }
            override fun onEngineEvent(name: String, attributes: Map<String, Any?>) {
                println("[EVENT] $name $attributes")
            }
            override fun onCallCompleted(parseSuccess: Boolean?) {
                val elapsed = (System.nanoTime() - startTime) / 1_000_000
                println("[END] ${context.methodName} took ${elapsed}ms")
            }
        }
    }
}

┌──────────────────────────────────────────────┐
│               tramai-core                     │
│                                               │
│   ┌─────────────────────────────────┐         │
│   │      annotations (10 types)     │         │
│   │  @AiService  @Operation         │         │
│   │  @AiTool     @SystemPrompt      │         │
│   │  @System     @User              │         │
│   │  @AiDescription  @AiMinItems    │         │
│   │  @AiRange    @ConversationId    │         │
│   └─────────────────────────────────┘         │
│                                               │
│   ┌─────────────────────────────────┐         │
│   │        model (20 files)         │         │
│   │  Message  ModelRequest          │         │
│   │  ModelResponse  StreamChunk     │         │
│   │  ToolCall  ToolResult           │         │
│   │  ToolDefinition  ToolExecCtx    │         │
│   │  TramaiTool  ResolvedTool       │         │
│   │  ModelRegistry  ContentPart     │         │
│   └─────────────────────────────────┘         │
│                                               │
│   ┌─────────────────────────────────┐         │
│   │     provider (5 files)          │         │
│   │  ModelProvider  ProviderRegistry│         │
│   │  StreamCapable  ProviderFailures│         │
│   │  ProviderRoutingPlan            │         │
│   │  + transport/ (4 files)         │         │
│   └─────────────────────────────────┘         │
│                                               │
│   ┌─────────────────────────────────┐         │
│   │   structured (6 files)          │         │
│   │  StructuredOutputContract       │         │
│   │  StructuredOutputHandler        │         │
│   │  StructuredOutputResult         │         │
│   │  StructuredOutputFailureCode    │         │
│   └─────────────────────────────────┘         │
│                                               │
│   ┌─────────────────────────────────┐         │
│   │  observation (5 + event/ 7)     │         │
│   │  OperationInterceptor           │         │
│   │  OperationObserver (->Obs.)     │         │
│   │  RuntimeEventCatalogue (event/) │         │
│   └─────────────────────────────────┘         │
│                                               │
│   ┌─────────────────────────────────┐         │
│   │  exception (11 files)           │         │
│   │  TramaiException (sealed)       │         │
│   │  ProviderException              │         │
│   │  StructuredOutputException      │         │
│   │  ConfigurationException         │         │
│   │  TimeoutException               │         │
│   │  ProviderCapabilityException    │         │
│   │  CircuitBreakerOpenException    │         │
│   │  TokenBudgetExceededException   │         │
│   │  ToolInvalidInputException      │         │
│   │  + approval / policy failures   │         │
│   └─────────────────────────────────┘         │
│                                               │
│   ┌─────────────────────────────────┐         │
│   │  other packages (59 files)      │         │
│   │  approval(22+5) policy(7)       │         │
│   │  security(8) memory(6) util(2)  │         │
│   │  workflow(3) observation/       │         │
│   │  secondary(2) coroutines(1)     │         │
│   │  retry(1) secret(1) nativeimage(1)│       │
│   └─────────────────────────────────┘         │
└──────────────────────────────────────────────┘

tramai-core ─── kotlinx-coroutines-core (api)
     │
     ├── tramai-engine          (api)
     │       ├── tramai-security            (implementation)
     │       └── tramai-structured          (test only)
     │
     ├── tramai-openai
     ├── tramai-anthropic
     ├── tramai-ollama
     ├── tramai-standalone
     ├── tramai-spring
     └── tramai-testing

Kotlin annotations (runtime retention, must be documented)
  ├── @AiService              — marks an interface as a Tramai proxy target
  ├── @Operation              — declares one AI-backed method on an @AiService
  ├── @AiTool                 — registers a method as a callable tool (with optional governance metadata)
  ├── @SystemPrompt           — class-level system prompt
  ├── @System                 — method-level system message ({param} interpolation)
  ├── @User                   — method-level user message ({param} interpolation)
  ├── @ConversationId         — marks the conversation-identity parameter
  ├── @AiDescription          — schema hint for structured output properties
  ├── @AiMinItems             — minimum collection size constraint
  └── @AiRange                — numeric range constraint (min, max)

Data classes
  ├── Message(role, content, contentParts, toolCallId, toolCalls)
  ├── ModelRequest(model, messages, tools, maxTokens, temperature, timeoutMillis, ...)
  ├── ModelResponse(content, toolCalls, inputTokens, outputTokens, thinkingTokens, modelUsed, finishReason)
  ├── ToolCall(id, name, argumentsJson)
  ├── ToolDefinition(name, description, inputSchemaJson)
  ├── ToolExecutionContext(operationName, modelName, attemptNumber, conversationId, idempotencyKey, timeout, attributes)
  ├── UsageMetrics(inputTokens, outputTokens, thinkingTokens, imageCount, imageTokensEstimate)
  ├── StructuredOutputContract(targetType, schemaJson)
  ├── ProviderRoute(providerName, effectiveModelName)
  ├── ResolvedProviderRoute(providerName, provider, requestedModelName, effectiveModelName)
  ├── OperationCallContext(serviceInterface, methodName, providerId, requestedModel, attempt)

Sealed classes / interfaces
  ├── StreamChunk — sealed
  │   ├── Token(text)          — incremental text fragment
  │   ├── Complete(fullText, usage) — stream finished
  │   └── Error(cause)         — stream failed
  ├── ToolResult — sealed
  │   ├── Success(value)       — executed successfully
  │   ├── InvalidInput(message) — input rejected, feed back to model
  │   ├── TransientFailure(cause) — retry if idempotent
  │   └── PermanentFailure(message) — surface to caller
  ├── StructuredOutputResult — sealed interface
  │   ├── Success(value, rawResponse)
  │   └── Failure(rawResponse, errorSummary, feedbackMessage)
  └── TramaiException — sealed base for all exceptions

Interfaces
  ├── ModelProvider            — provider SPI: complete(request): ModelResponse, providerId(), supportsCapability(ProviderCapability)
  ├── ProviderCapability       — enum: VISION, TOOL_CALLING, STRUCTURED_OUTPUT, STREAMING
  ├── StreamCapable            — capability interface: stream(request): Flow<StreamChunk>
  ├── TramaiTool<I, O>         — user-facing tool contract (execute(input, context): O)
  ├── ResolvedTool             — engine-facing tool contract (execute(input, context): ToolResult)
  ├── StructuredOutputHandler  — pluggable schema/parse SPI
  ├── OperationObserver        — creates per-call observations
  ├── OperationObservation     — per-attempt callback set
  ├── OperationInterceptor     — request/response inspection + modification
  └── SecretValueResolver      — resolves external secret references

Utility objects / classes
  ├── CompositeOperationInterceptor — chains multiple interceptors
  ├── NoOpOperationInterceptor      — no-op default
  ├── NoOpOperationObserver         — no-op observer
  ├── NoOpOperationObservation      — no-op observation
  ├── EnvironmentSecretValueResolver — resolves "env:VAR" references
  ├── FileSecretValueResolver        — resolves "file:path" references under an allowed directory
  ├── CompositeSecretValueResolver   — chains multiple resolvers
  └── NativeImageProxyConfig         — generates GraalVM proxy metadata

@Operation(model="gpt-4o", provider="")
         │
         ▼
ProviderRoutingPlan.resolveCandidates(operation)   // via ProviderRegistry.resolveCandidates
    │
    ├── @Operation.provider != "" → lookup by provider name
    ├── routes[requestedModel] → mapped routes (primary + fallbacks)
    └── defaultProvider → fallback default
         │
         ▼
    List<ResolvedProviderRoute>(provider, requestedModelName, effectiveModelName)
         │
         ▼
    engine → provider.complete(request)

TramaiException (sealed, extends RuntimeException)
  ├── StructuredOutputException
  │   └── carries: originalPrompt, lastRawResponse, validationError, attemptCount
  ├── ProviderException
  │   └── carries: statusCode, retryable, retryAfterMillis
  ├── ConfigurationException
  ├── TimeoutException
  ├── ProviderCapabilityException
  │   └── carries: providerId, capability (String, e.g. "VISION" / "streaming")
  ├── CircuitBreakerOpenException
  │   └── carries: providerId, reopenAtEpochMillis
  ├── TokenBudgetExceededException
  │   └── carries: scope, limitTokens, observedTokens, providerId, modelName
  └── ToolInvalidInputException
     └── optional safeModelMessage; use withSafeModelMessage(...) to make text model-visible

fun providerHttpFailure(providerName, statusCode, body, retryAfterHeader): ProviderException
fun providerTransportFailure(providerName, error): ProviderException