
Provider-neutral AI connector for model discovery, deterministic local mode, typed responses and streams, exact-model selection, cancellation, and host-owned credential handling across multiple backends.
One AI client for Kotlin and Swift, across OpenAI, Anthropic, OpenRouter, and OpenAI-compatible gateways.
Universal AI Connector gives Android, iOS, JVM, and desktop applications one provider-neutral API for model discovery, text generation, structured output, and streaming—without leaking provider DTOs into application code.
Why it exists · Try it · Providers · Host APIs · Status · Roadmap · Documentation
[!IMPORTANT] The Kotlin libraries remain a source preview while Maven Central publication is pending. iOS 17+ applications can use the exact unsigned
0.1.0-alpha.0.p8.1SwiftPM prerelease. Packaged desktop applications, physical-device execution, and the immutable0.1.0-alpha.1release remain future work.
Most multi-provider integrations spread provider-specific requests, responses, errors, and streaming rules throughout the app. Universal AI Connector keeps that variation behind one canonical contract:
suspend and Flow; Swift uses async and AsyncThrowingStream.Android (Kotlin) · iOS (Swift)
Linux · Windows · macOS (Kotlin/JVM · Compose Desktop)
│
▼
Universal AI Connector
request · stream · models
│
┌───────┼──────────┬───────────────┐
▼ ▼ ▼ ▼
OpenAI Anthropic OpenRouter OpenAI-compatible
│
▼
canonical responses · errors · stream events
The fastest path needs only JDK 21. It runs a deterministic request, ordered stream, typed failure, response cancellation, and stream cancellation:
git clone https://github.com/maneesh888/universal-ai-connector.git
cd universal-ai-connector
./gradlew :samples:jvm-console:runPrefer a UI? Launch the Compose desktop sample on macOS, Windows, or Linux:
./gradlew :samples:desktop:runBoth commands start without API keys or network access. The Android, iOS, JVM, and desktop samples also include an explicit live workflow for delivered providers.
The provider is configuration. The request and response model stay the same:
val connector = UniversalAiConnector(
UniversalAiConnectorConfiguration(
providers = listOf(
UniversalAiProviderConfiguration(
providerId = ProviderId.of("openai"),
baseUrl = "https://api.openai.com/v1",
credentialSupplier = loadCredential,
),
),
),
)
val request = UniversalAiRequest(
target = UniversalAiTarget(
providerId = ProviderId.of("openai"),
modelId = ModelId.of(selectedModel),
),
input = listOf(
UniversalAiTextInput(
role = UniversalAiInputRole.User,
content = "Explain Kotlin Multiplatform in three sentences.",
),
),
)
try {
val response = connector.respond(request)
println(response.outputs.single().text)
connector.stream(request).collect { event ->
print(event.delta.orEmpty())
}
} finally {
connector.close()
}The same boundary is Swift-native:
let connector = UniversalAiConnector()
defer { connector.close() }
let response = try await connector.respond(to: request)
for try await event in connector.stream(request: request) {
print(event.delta ?? "", terminator: "")
}The snippets focus on the public API shape. Kotlin consumers use the tested source-revision setup in the production consumption contract until Maven Central publication. iOS applications can resolve the exact 0.1.0-alpha.0.p8.1 SwiftPM prerelease.
| Provider ID | Protocol | Model discovery | Generation |
|---|---|---|---|
openai |
Responses API | Yes | Response, structured output, stream |
anthropic |
Messages API | Yes, including bounded pagination | Response, structured output, stream |
openrouter |
Chat Completions | Yes | Response, structured output, stream |
openai-compatible |
Conservative Chat Completions intersection | When the endpoint supports it | Response, structured output, stream |
deterministic |
Local test implementation | Not required | Response, typed error, stream, cancellation |
Provider adapters stay internal. Public callers work with canonical requests, responses, output parts, usage, metadata, errors, capabilities, and stream events.
| Host | Public experience | Reference app |
|---|---|---|
| Android 24+ | Kotlin client with coroutines and Flow
|
Jetpack Compose sample |
| iOS 17+ | Swift façade with async, AsyncThrowingStream, Swift errors, and Swift cancellation |
SwiftUI sample |
| JVM on Linux, Windows, and macOS | Kotlin client with coroutines and Flow
|
Console sample |
| Desktop on Linux, Windows, and macOS | Kotlin/JVM client in Compose Multiplatform | Desktop sample |
All four sample paths offer:
Universal AI Connector is designed around the details that become expensive when each provider is integrated separately:
close();There is no implicit retry, model substitution, or silent fallback. A request either uses the exact provider and model selected by the host or fails explicitly.
See Security Policy and Live Provider Testing for the full boundaries.
Universal AI Connector has completed its cross-platform foundation, canonical contracts, HTTP transport, delivered provider adapters, gateway compatibility, and source-based live samples for iOS, Android, JVM, and desktop.
0.1.0-alpha.1 releaseThe V2 roadmap is the source of truth for milestone status, scope, and proof limits.
Today's delivered providers and gateways use remote HTTP APIs. On-device inference is a separate future path: it will be explicit, capability-gated, and will never silently fall back to a cloud provider.
| Track | Goal | Boundary |
|---|---|---|
| P10 image and audio inputs | Add ordered, provider-neutral image and audio input parts with bounded validation, conservative capabilities, cancellation, cleanup, and redaction. | Capture, playback, transcoding, DSP, storage, documents, video, and realtime sessions remain outside the initial scope. |
| P11 native on-device AI | Integrate OS-managed models, starting with Apple Foundation Models and Android ML Kit GenAI, behind the existing Kotlin client and Swift façade. | Planned only; current builds do not include these runtimes or claim offline inference. |
| P12 downloaded local models | Evaluate optional in-app backends for host-provided models, beginning with llama.cpp and LiteRT-LM. | No engine or model format is selected, no model weights will be bundled by default, and remote/OS-native consumers must not acquire a runtime transitively. |
Each track requires separate activation and acceptance work. Adding these goals to the roadmap does not activate a milestone or change the current text-and-HTTP implementation.
./gradlew :samples:jvm-console:run./gradlew :samples:desktop:run./gradlew :samples:android:consumerCheck
./scripts/run-android-sample.sh./scripts/build-xcframework.sh
open samples/ios/UniversalAiConnectorSample.xcodeprojLive-provider setup is intentionally separate from the zero-key first run. Follow Live Provider Testing when you are ready to connect a real account or gateway.
Run the documentation and repository hygiene gate:
./scripts/check.sh --hygieneRun the normal deterministic development suite:
./scripts/check.sh --quickRun the complete local matrix on a fully configured macOS development host:
./scripts/check.sh --fullThe full matrix adds the combined iOS device/simulator XCFramework, Swift Package tests, app-extension consumer, iOS Simulator sample, and generic iOS-device link verification. It does not claim physical-device execution or published-artifact resolution.
See Development Workflow for prerequisites, targeted checks, hooks, CI behavior, and proof levels.
bridge/ Kotlin Multiplatform client, adapters, and tests
contracts/ Versioned JSON Schemas and compatibility fixtures
swift-package/ Supported Swift façade and Swift tests
samples/android/ Jetpack Compose Android consumer
samples/ios/ SwiftUI and app-extension consumers
samples/jvm-console/ Headless Kotlin/JVM consumer
samples/desktop/ Compose Multiplatform desktop consumer
scripts/ Deterministic and live verification commands
docs/ Consumption, security, verification, and roadmap docs
Issues and focused pull requests are welcome. Start with the development workflow, keep provider-specific behavior behind internal adapters, and include the smallest verification that proves your change.
For security-sensitive reports, follow SECURITY.md instead of opening a public issue.
Universal AI Connector is available under the MIT License.
One AI client for Kotlin and Swift, across OpenAI, Anthropic, OpenRouter, and OpenAI-compatible gateways.
Universal AI Connector gives Android, iOS, JVM, and desktop applications one provider-neutral API for model discovery, text generation, structured output, and streaming—without leaking provider DTOs into application code.
Why it exists · Try it · Providers · Host APIs · Status · Roadmap · Documentation
[!IMPORTANT] The Kotlin libraries remain a source preview while Maven Central publication is pending. iOS 17+ applications can use the exact unsigned
0.1.0-alpha.0.p8.1SwiftPM prerelease. Packaged desktop applications, physical-device execution, and the immutable0.1.0-alpha.1release remain future work.
Most multi-provider integrations spread provider-specific requests, responses, errors, and streaming rules throughout the app. Universal AI Connector keeps that variation behind one canonical contract:
suspend and Flow; Swift uses async and AsyncThrowingStream.Android (Kotlin) · iOS (Swift)
Linux · Windows · macOS (Kotlin/JVM · Compose Desktop)
│
▼
Universal AI Connector
request · stream · models
│
┌───────┼──────────┬───────────────┐
▼ ▼ ▼ ▼
OpenAI Anthropic OpenRouter OpenAI-compatible
│
▼
canonical responses · errors · stream events
The fastest path needs only JDK 21. It runs a deterministic request, ordered stream, typed failure, response cancellation, and stream cancellation:
git clone https://github.com/maneesh888/universal-ai-connector.git
cd universal-ai-connector
./gradlew :samples:jvm-console:runPrefer a UI? Launch the Compose desktop sample on macOS, Windows, or Linux:
./gradlew :samples:desktop:runBoth commands start without API keys or network access. The Android, iOS, JVM, and desktop samples also include an explicit live workflow for delivered providers.
The provider is configuration. The request and response model stay the same:
val connector = UniversalAiConnector(
UniversalAiConnectorConfiguration(
providers = listOf(
UniversalAiProviderConfiguration(
providerId = ProviderId.of("openai"),
baseUrl = "https://api.openai.com/v1",
credentialSupplier = loadCredential,
),
),
),
)
val request = UniversalAiRequest(
target = UniversalAiTarget(
providerId = ProviderId.of("openai"),
modelId = ModelId.of(selectedModel),
),
input = listOf(
UniversalAiTextInput(
role = UniversalAiInputRole.User,
content = "Explain Kotlin Multiplatform in three sentences.",
),
),
)
try {
val response = connector.respond(request)
println(response.outputs.single().text)
connector.stream(request).collect { event ->
print(event.delta.orEmpty())
}
} finally {
connector.close()
}The same boundary is Swift-native:
let connector = UniversalAiConnector()
defer { connector.close() }
let response = try await connector.respond(to: request)
for try await event in connector.stream(request: request) {
print(event.delta ?? "", terminator: "")
}The snippets focus on the public API shape. Kotlin consumers use the tested source-revision setup in the production consumption contract until Maven Central publication. iOS applications can resolve the exact 0.1.0-alpha.0.p8.1 SwiftPM prerelease.
| Provider ID | Protocol | Model discovery | Generation |
|---|---|---|---|
openai |
Responses API | Yes | Response, structured output, stream |
anthropic |
Messages API | Yes, including bounded pagination | Response, structured output, stream |
openrouter |
Chat Completions | Yes | Response, structured output, stream |
openai-compatible |
Conservative Chat Completions intersection | When the endpoint supports it | Response, structured output, stream |
deterministic |
Local test implementation | Not required | Response, typed error, stream, cancellation |
Provider adapters stay internal. Public callers work with canonical requests, responses, output parts, usage, metadata, errors, capabilities, and stream events.
| Host | Public experience | Reference app |
|---|---|---|
| Android 24+ | Kotlin client with coroutines and Flow
|
Jetpack Compose sample |
| iOS 17+ | Swift façade with async, AsyncThrowingStream, Swift errors, and Swift cancellation |
SwiftUI sample |
| JVM on Linux, Windows, and macOS | Kotlin client with coroutines and Flow
|
Console sample |
| Desktop on Linux, Windows, and macOS | Kotlin/JVM client in Compose Multiplatform | Desktop sample |
All four sample paths offer:
Universal AI Connector is designed around the details that become expensive when each provider is integrated separately:
close();There is no implicit retry, model substitution, or silent fallback. A request either uses the exact provider and model selected by the host or fails explicitly.
See Security Policy and Live Provider Testing for the full boundaries.
Universal AI Connector has completed its cross-platform foundation, canonical contracts, HTTP transport, delivered provider adapters, gateway compatibility, and source-based live samples for iOS, Android, JVM, and desktop.
0.1.0-alpha.1 releaseThe V2 roadmap is the source of truth for milestone status, scope, and proof limits.
Today's delivered providers and gateways use remote HTTP APIs. On-device inference is a separate future path: it will be explicit, capability-gated, and will never silently fall back to a cloud provider.
| Track | Goal | Boundary |
|---|---|---|
| P10 image and audio inputs | Add ordered, provider-neutral image and audio input parts with bounded validation, conservative capabilities, cancellation, cleanup, and redaction. | Capture, playback, transcoding, DSP, storage, documents, video, and realtime sessions remain outside the initial scope. |
| P11 native on-device AI | Integrate OS-managed models, starting with Apple Foundation Models and Android ML Kit GenAI, behind the existing Kotlin client and Swift façade. | Planned only; current builds do not include these runtimes or claim offline inference. |
| P12 downloaded local models | Evaluate optional in-app backends for host-provided models, beginning with llama.cpp and LiteRT-LM. | No engine or model format is selected, no model weights will be bundled by default, and remote/OS-native consumers must not acquire a runtime transitively. |
Each track requires separate activation and acceptance work. Adding these goals to the roadmap does not activate a milestone or change the current text-and-HTTP implementation.
./gradlew :samples:jvm-console:run./gradlew :samples:desktop:run./gradlew :samples:android:consumerCheck
./scripts/run-android-sample.sh./scripts/build-xcframework.sh
open samples/ios/UniversalAiConnectorSample.xcodeprojLive-provider setup is intentionally separate from the zero-key first run. Follow Live Provider Testing when you are ready to connect a real account or gateway.
Run the documentation and repository hygiene gate:
./scripts/check.sh --hygieneRun the normal deterministic development suite:
./scripts/check.sh --quickRun the complete local matrix on a fully configured macOS development host:
./scripts/check.sh --fullThe full matrix adds the combined iOS device/simulator XCFramework, Swift Package tests, app-extension consumer, iOS Simulator sample, and generic iOS-device link verification. It does not claim physical-device execution or published-artifact resolution.
See Development Workflow for prerequisites, targeted checks, hooks, CI behavior, and proof levels.
bridge/ Kotlin Multiplatform client, adapters, and tests
contracts/ Versioned JSON Schemas and compatibility fixtures
swift-package/ Supported Swift façade and Swift tests
samples/android/ Jetpack Compose Android consumer
samples/ios/ SwiftUI and app-extension consumers
samples/jvm-console/ Headless Kotlin/JVM consumer
samples/desktop/ Compose Multiplatform desktop consumer
scripts/ Deterministic and live verification commands
docs/ Consumption, security, verification, and roadmap docs
Issues and focused pull requests are welcome. Start with the development workflow, keep provider-specific behavior behind internal adapters, and include the smallest verification that proves your change.
For security-sensitive reports, follow SECURITY.md instead of opening a public issue.
Universal AI Connector is available under the MIT License.