🤖 Aivo SDK

// settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

// app/build.gradle.kts
dependencies {
    implementation("io.github.abdallah-elsobky:aivo-sdk:1.0.1")
}

// app/build.gradle.kts
dependencies {
    implementation(libs.aivo.sdk)
}

// shared/build.gradle.kts (or any KMP module)
kotlin {
    androidTarget()
    iosArm64()
    iosSimulatorArm64()
    jvm()

    sourceSets {
        commonMain.dependencies {
            implementation(libs.bundles.aivo.sdk)
        }
    }
}

android {
    buildFeatures { buildConfig = true }

    defaultConfig {
        val localProps = java.util.Properties().apply {
            val file = rootProject.file("local.properties")
            if (file.exists()) load(file.inputStream())
        }

        buildConfigField(
            "String", "OLLAMA_API_KEY",
            "\"${localProps["OLLAMA_API_KEY"] ?: ""}\""
        )
        buildConfigField(
            "String", "GEMINI_API_KEY",
            "\"${localProps["GEMINI_API_KEY"] ?: ""}\""
        )
        buildConfigField(
            "String", "OPENROUTER_API_KEY",
            "\"${localProps["OPENROUTER_API_KEY"] ?: ""}\""
        )
    }
}

import com.example.app.BuildConfig
import com.aivo.sdk.AivoSdk
import com.aivo.sdk.AivoProvider
import com.aivo.sdk.provider.ollama.OllamaModel

private val aivo = AivoSdk.create(
    provider = AivoProvider.OLLAMA,
    model    = OllamaModel.GPT_OSS_120B.modelId,
    apiKey   = BuildConfig.OLLAMA_API_KEY,
)

import com.aivo.sdk.AivoSdk
import com.aivo.sdk.AivoProvider
import com.aivo.sdk.provider.ollama.OllamaModel
import com.aivo.sdk.core.model.ConversationId

// commonMain — shared module accepts the key at runtime
class ChatRepository(private val apiKey: String) {
    private val aivo = AivoSdk.create(
        provider = AivoProvider.OLLAMA,
        model    = OllamaModel.GPT_OSS_120B.modelId,
        apiKey   = apiKey,
    )

    suspend fun chat(message: String): String =
        aivo.chat(ConversationId("session-1"), message).text
}

// androidMain
val repo = ChatRepository(apiKey = BuildConfig.OLLAMA_API_KEY)

// iosMain / jvmMain
val repo = ChatRepository(
    apiKey = NSProcessInfo.processInfo.environment["OLLAMA_API_KEY"] as? String ?: ""
)

import com.aivo.sdk.AivoSdk
import com.aivo.sdk.AivoProvider
import com.aivo.sdk.provider.ollama.OllamaModel
import com.aivo.sdk.core.model.ConversationId

private val aivo = AivoSdk.create(
    provider = AivoProvider.OLLAMA,
    model    = OllamaModel.GPT_OSS_120B.modelId,
    apiKey   = BuildConfig.OLLAMA_API_KEY,  // Android
    // apiKey = System.getenv("OLLAMA_API_KEY"),  // JVM
)

// Non-streaming chat
val result = aivo.chat(ConversationId("session-1"), "What is Kotlin Multiplatform?")
println(result.text)

import com.aivo.sdk.AivoSdk
import com.aivo.sdk.AivoProvider
import com.aivo.sdk.provider.ollama.OllamaModel
import com.aivo.sdk.core.model.ConversationId

val aivo = AivoSdk {
    providers {
        ollama(AivoProvider.OLLAMA.id) { 
            apiKey(BuildConfig.OLLAMA_API_KEY) 
        }
    }
    defaultModel(OllamaModel.GPT_OSS_120B)

    agents {
        define("assistant") {
            name         = "AI Assistant"
            systemPrompt = "You are a helpful, concise assistant."
        }
    }
    entryAgent("assistant")
}

val result = aivo.chat(ConversationId("chat-1"), "Explain coroutines in one paragraph.")
println(result.text)

import com.aivo.sdk.AivoSdk
import com.aivo.sdk.AivoProvider
import com.aivo.sdk.provider.ollama.OllamaModel

val aivo = AivoSdk {
    providers {
        ollama(AivoProvider.OLLAMA.id) { apiKey(BuildConfig.OLLAMA_API_KEY) }
    }
    defaultModel(OllamaModel.GPT_OSS_120B)
}

val response = aivo.llm(OllamaModel.GPT_OSS_120B.toModelRef()).generate("What is 2 + 2?")
println(response.message.content())

// Example 1: Custom model name & custom base URL with AivoSdk.create(...)
val customAivo = AivoSdk.create(
    provider = AivoProvider.OLLAMA,
    model    = "my-custom-fine-tuned-model:v2",        // Custom model string
    baseUrl  = "https://ollama.internal.company.com/api/chat", // Custom base URL string
    apiKey   = BuildConfig.OLLAMA_API_KEY,
)

// Example 2: Fully custom self-hosted OpenAI-compatible endpoint with Builder DSL
val customLlmSdk = AivoSdk {
    providers {
        openAiCompatible("internal-vllm") {            // Custom provider ID string
            baseUrl("https://vllm.internal.corp/v1")    // Custom host URL string
            apiKey(BuildConfig.INTERNAL_API_KEY)
            header("X-Department", "Mobile-AI")
        }
    }
    defaultModel("internal-vllm:custom-llama-3.3-70b")  // Custom "provider:model" string
}

import com.aivo.sdk.AivoProvider
import com.aivo.sdk.provider.ollama.OllamaModel

val aivo = AivoSdk {
    providers {
        ollama(AivoProvider.OLLAMA.id) {
            apiKey(BuildConfig.OLLAMA_API_KEY)
            // Optional: override baseUrl if connecting to a self-hosted instance or custom proxy:
            // baseUrl("http://192.168.1.50:11434")
        }
    }
    defaultModel(OllamaModel.GPT_OSS_120B)
}

import com.aivo.sdk.AivoProvider
import com.aivo.sdk.provider.gemini.GeminiModel

val aivo = AivoSdk {
    providers {
        gemini(AivoProvider.GEMINI.id) {
            apiKey(BuildConfig.GEMINI_API_KEY)
            // Optional: override base URL (e.g. for Vertex AI, custom gateway, or proxy)
            // baseUrl("https://custom-proxy.internal.com")
        }
    }
    defaultModel(GeminiModel.GEMINI_3_8_FLASH)
}

import com.aivo.sdk.AivoProvider
import com.aivo.sdk.provider.openai.OpenRouterModel

val aivo = AivoSdk {
    providers {
        openRouter(AivoProvider.OPEN_ROUTER.id) {
            apiKey(BuildConfig.OPENROUTER_API_KEY)
            referer("https://myapp.com")  // optional: shown in OpenRouter dashboard
            title("My App")               // optional: shown in OpenRouter dashboard
        }
    }
    defaultModel(OpenRouterModel.LING_3_0_FLASH_SANTE_FREE)
}

val aivo = AivoSdk {
    providers {
        openAiCompatible("custom-provider") {
            baseUrl("https://api.myservice.com/v1") // Custom endpoint URL as String
            apiKey(BuildConfig.MY_API_KEY)
            header("X-Custom-Header", "value")      // Optional extra headers
        }
    }
    defaultModel("custom-provider:my-custom-model") // Custom model identifier as String
}

import com.aivo.sdk.AivoSdk
import com.aivo.sdk.AivoProvider
import com.aivo.sdk.provider.ollama.OllamaModel

val aivo = AivoSdk {
    providers {
        ollama(AivoProvider.OLLAMA.id) { apiKey(BuildConfig.OLLAMA_API_KEY) }
    }
    defaultModel(OllamaModel.GPT_OSS_120B)

    tools {
        +getWeatherTool
        +searchWebTool
    }

    agents {
        define("assistant") {
            name         = "Personal Assistant"
            systemPrompt = """
                You are a helpful assistant with access to real-time data.
                Always be concise and accurate.
            """.trimIndent()
            tools("get_weather", "search_web")

            // Optional: override model for this specific agent (strongly typed or custom string)
            model(OllamaModel.GPT_OSS_120B)
            maxSteps = 15
        }
    }
    entryAgent("assistant")
}

val aivo = AivoSdk {
    providers {
        ollama(AivoProvider.OLLAMA.id) { apiKey(BuildConfig.OLLAMA_API_KEY) }
    }
    defaultModel(OllamaModel.GPT_OSS_120B)

    agents {
        // Android: loads from assets/agents/researcher.md
        // JVM: loads from classpath or filesystem path
        fromMarkdownPath("agents/researcher.md")
    }
    entryAgent("researcher")
}

agents {
    fromJsonPath("agents/coding-assistant.json")
    // Or load inline:
    fromJson("""{ "id": "bot", "systemPrompt": "You are a helpful bot." }""")
}

val getWeatherTool = tool("get_weather", "Get current weather for a city") {
    param("city", "The city name", type = ParamType.String, required = true)
    param(
        name     = "unit",
        description = "Temperature unit",
        type     = ParamType.String,
        required = false,
        enum     = listOf("celsius", "fahrenheit")
    )

    execute { args ->
        val city = args.string("city")
        val unit = args.stringOrNull("unit") ?: "celsius"
        // Call your real weather API here
        "Weather in $city: 22°${if (unit == "celsius") "C" else "F"}, sunny"
    }
}

val aivo = AivoSdk {
    providers {
        ollama(AivoProvider.OLLAMA.id) { apiKey(BuildConfig.OLLAMA_API_KEY) }
    }
    defaultModel(OllamaModel.GPT_OSS_120B)
    tools { +getWeatherTool }
    agents {
        define("assistant") {
            systemPrompt = "You are a weather assistant."
            tools("get_weather")
        }
    }
    entryAgent("assistant")
}

val deleteFileTool = tool("delete_file", "Permanently deletes a file from the system") {
    param("path", "Absolute file path to delete", type = ParamType.String, required = true)

    risk(ToolRisk.HIGH)
    requiresConfirmation(true)  // pauses and asks for human approval

    execute { args ->
        val path = args.string("path")
        // Only runs after the ConfirmationHandler approves
        File(path).delete()
        "File deleted: $path"
    }
}

val aivo = AivoSdk {
    // ...
    security {
        confirmationHandler = ConfirmationHandler { toolName, args ->
            // Show your dialog and return true (allow) or false (deny)
            showConfirmationDialog("Allow '$toolName'?", args.toString())
        }
    }
}

val createUserTool = tool("create_user", "Creates a new user account") {
    parameters {
        string("username",    "Unique username",      required = true,  minLength = 3, maxLength = 30)
        string("email",       "Email address",         required = true)
        integer("age",        "User age",              required = false, minimum = 13, maximum = 120)
        boolean("newsletter", "Opt in to newsletter",  required = false)
        string("role",        "User role",             required = true,
               enum = listOf("user", "admin", "moderator"))
    }

    execute { args ->
        val username = args.string("username")
        val email    = args.string("email")
        val role     = args.string("role")
        // Call your user creation API
        """{"id": "usr_123", "username": "$username", "email": "$email", "role": "$role"}"""
    }
}

val aivo = AivoSdk {
    providers {
        ollama(AivoProvider.OLLAMA.id) { apiKey(BuildConfig.OLLAMA_API_KEY) }
    }
    defaultModel(OllamaModel.GPT_OSS_120B)

    tools {
        +searchWebTool
        +writeFileTool
        +readFileTool
    }

    agents {
        // Supervisor — orchestrates the team
        define("supervisor") {
            name         = "Team Supervisor"
            systemPrompt = """
                You coordinate a research and writing team.
                Delegate research tasks to the 'researcher' agent.
                Delegate writing tasks to the 'writer' agent.
                Synthesize results into a final answer.
            """.trimIndent()
            delegates("researcher", "writer")
        }

        // Sub-agent 1 — Research Specialist
        define("researcher") {
            name         = "Research Specialist"
            systemPrompt = "You gather accurate, up-to-date information using tools."
            tools("search_web")
        }

        // Sub-agent 2 — Writing Specialist
        define("writer") {
            name         = "Writing Specialist"
            systemPrompt = "You write polished, professional content based on research notes."
            tools("write_file", "read_file")
        }
    }
    entryAgent("supervisor")
}

// The supervisor delegates automatically
val result = aivo.chat(
    ConversationId("project-1"),
    "Research the history of Kotlin and write a 500-word blog post."
)
println(result.text)

import com.aivo.sdk.AivoSdk
import com.aivo.sdk.AivoProvider
import com.aivo.sdk.provider.ollama.OllamaModel
import com.aivo.sdk.core.model.ConversationId
import com.aivo.sdk.runtime.agent.AgentEvent

private val aivo = AivoSdk.create(
    provider = AivoProvider.OLLAMA,
    model    = OllamaModel.GPT_OSS_120B.modelId,
    apiKey   = BuildConfig.OLLAMA_API_KEY,
)

aivo.stream(ConversationId("stream-1"), "Write a poem about Kotlin coroutines.")
    .collect { event ->
        when (event) {
            is AgentEvent.RunStarted         -> println("▶ Run started")
            is AgentEvent.AgentEntered       -> println("→ Agent: ${event.agentId}")
            is AgentEvent.StepStarted        -> println("\n--- Step ${event.stepIndex} ---")
            is AgentEvent.TextDelta          -> print(event.text)             // live tokens
            is AgentEvent.ReasoningDelta     -> print("[thinking] ${event.text}") // chain-of-thought
            is AgentEvent.ToolCallStarted    -> println("\n⚙ Calling: ${event.toolName}")
            is AgentEvent.ToolCallExecuted   -> println("✓ Tool result received")
            is AgentEvent.StepCompleted      -> {}
            is AgentEvent.RunCompleted       -> println("\n\n✅ Done in ${event.result.steps} steps")
            is AgentEvent.RunFailed          -> println("\n❌ Error: ${event.error.message}")
        }
    }

// ViewModel
class ChatViewModel(private val aivo: AivoSdk) : ViewModel() {
    private val _output = MutableStateFlow("")
    val output: StateFlow<String> = _output.asStateFlow()

    fun send(message: String, conversationId: ConversationId) {
        viewModelScope.launch {
            _output.value = ""
            aivo.stream(conversationId, message).collect { event ->
                if (event is AgentEvent.TextDelta) {
                    _output.update { it + event.text }
                }
            }
        }
    }
}

// Composable
@Composable
fun ChatScreen(viewModel: ChatViewModel = viewModel()) {
    val output by viewModel.output.collectAsState()

    Column(modifier = Modifier.padding(16.dp)) {
        Text(text = output)  // updates in real-time as tokens arrive
        Spacer(modifier = Modifier.height(8.dp))
        Button(onClick = { viewModel.send("Hello!", ConversationId("c1")) }) {
            Text("Send")
        }
    }
}

AivoSdk {
    memory { keepAll() }
}

AivoSdk {
    memory { slidingWindow(maxMessages = 20) }
}

AivoSdk {
    memory {
        tokenBudget(
            maxTokens = 8_000,
            estimator = CharCountEstimator  // or provide your own TokenEstimator
        )
    }
}

class RoomMemoryStore(private val dao: ConversationDao) : MemoryStore {
    override suspend fun load(conversationId: ConversationId): List<Message> =
        dao.getMessages(conversationId.value).map { it.toDomain() }

    override suspend fun append(conversationId: ConversationId, messages: List<Message>) {
        dao.insertAll(messages.map { it.toEntity(conversationId.value) })
    }

    override suspend fun clear(conversationId: ConversationId) {
        dao.deleteAll(conversationId.value)
    }
}

AivoSdk {
    memory {
        store = RoomMemoryStore(dao = myConversationDao)
        slidingWindow(maxMessages = 30)
    }
}

AivoSdk {
    resilience {
        retry {
            maxAttempts = 5
            baseDelayMs = 1_000L     // 1s initial delay
            maxDelayMs  = 30_000L   // cap at 30s
            jitter      = true       // ±20% randomness to avoid thundering-herd
        }

        timeouts {
            connectTimeoutMs    = 10_000L   // 10s to establish connection
            requestTimeoutMs    = 60_000L   // 60s total request timeout
            streamIdleTimeoutMs = 30_000L   // 30s idle stream timeout
        }
    }
}

AivoSdk {
    runtime {
        maxSteps              = 15        // agent loop iteration limit
        maxDelegationDepth    = 3         // supervisor nesting limit
        toolTimeoutMs         = 15_000L   // per-tool execution timeout
        runTimeoutMs          = 90_000L   // total run wall-clock timeout
        parallelToolExecution = true      // execute multiple tools concurrently
    }
}

AivoSdk {
    runtime {
        concurrencyPolicy = ConcurrencyPolicy.QUEUE   // queue new request (default)
        // concurrencyPolicy = ConcurrencyPolicy.REJECT  // throw ConcurrentRunException
        // concurrencyPolicy = ConcurrencyPolicy.CANCEL  // cancel the in-flight request
    }
}

AivoSdk {
    observability {
        logger = object : Logger {
            override fun log(level: LogLevel, tag: String, message: String, throwable: Throwable?) {
                Log.println(level.toAndroidPriority(), tag, message)
                throwable?.let { Log.e(tag, message, it) }
            }
        }
        // Enable payload logging in debug builds only — they are auto-redacted
        logPayloads = BuildConfig.DEBUG
    }
}

AivoSdk {
    observability {
        telemetry = object : Telemetry {
            override fun onRequestStart(providerId: ProviderId, model: String) {
                analytics.track("llm_request_start", mapOf("provider" to providerId.value))
            }
            override fun onRequestEnd(
                providerId: ProviderId, model: String,
                usage: Usage?, durationMs: Long
            ) {
                analytics.track("llm_request_end", mapOf(
                    "provider"    to providerId.value,
                    "tokens_used" to (usage?.totalTokens ?: 0),
                    "duration_ms" to durationMs,
                ))
            }
        }
    }
}

val secret = SecretString("AIzaSy...")
println(secret)          // → [REDACTED]
println(secret.reveal()) // → AIzaSy...  (use only in trusted, non-logged contexts)

import com.aivo.sdk.core.error.*

try {
    val result = aivo.chat(ConversationId("s1"), "Hello")
    println(result.text)

} catch (e: AuthenticationException) {
    // HTTP 401/403 — wrong or expired API key. Never retried.
    showError("Invalid API key for ${e.providerId.value}. Please check your credentials.")

} catch (e: RateLimitException) {
    // HTTP 429 — too many requests. Retried automatically if RetryPolicy is configured.
    val retryIn = e.retryAfterMs?.let { "${it / 1000}s" } ?: "a moment"
    showError("Rate limit reached. Please try again in $retryIn.")

} catch (e: ModelNotFoundException) {
    showError("Model '${e.modelName}' was not found on ${e.providerId.value}.")

} catch (e: MaxStepsExceededException) {
    showError("The agent '${e.agentId}' could not complete in ${e.maxSteps} steps.")

} catch (e: RunTimeoutException) {
    showError("Request timed out after ${e.timeoutMs / 1000}s.")

} catch (e: NetworkException) {
    showError("Network error. Please check your connection.")

} catch (e: ConfigurationException) {
    // Thrown at build time — all config errors reported at once
    e.problems.forEach { System.err.println("Config error: $it") }

} catch (e: SdkException) {
    showError("Unexpected error: ${e.message}")
}

// build.gradle.kts
dependencies {
    testImplementation("io.github.abdallah-elsobky:aivo-sdk-testing:1.0.1")
}

import com.aivo.sdk.testing.FakeLlmProvider

@Test
fun `agent returns scripted greeting`() = runTest {
    val fake = FakeLlmProvider.scripted(
        id       = ProviderId("fake"),
        response = Message.assistant("Hello! How can I help you today?")
    )

    val sdk = AivoSdk {
        providers { register(fake) }
        defaultModel("fake:model")
        agents {
            define("bot") { systemPrompt = "You are a helpful bot." }
        }
        entryAgent("bot")
    }

    val result = sdk.chat(ConversationId("test-1"), "Hi!")
    assertEquals("Hello! How can I help you today?", result.text)
}

import com.aivo.sdk.testing.InMemoryTelemetry

@Test
fun `telemetry records one request`() = runTest {
    val telemetry = InMemoryTelemetry()

    val sdk = AivoSdk {
        // ... (use FakeLlmProvider)
        observability { this.telemetry = telemetry }
    }

    sdk.chat(ConversationId("test-2"), "Ping")

    assertEquals(1, telemetry.requestEndEvents.size)
    assertTrue(telemetry.requestEndEvents.first().durationMs >= 0)
}