feat:contrib/model-prism: pluggable LLM backend SPI for ADK Java via ServiceLoader

[svetanis]

Add model-prism: pluggable LLM backend SPI for ADK Java via ServiceLoader

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Related discussion:

• Related: openai api support #350 (OpenAI API support)
• feat: Add support for OpenAI-compatible LLM endpoints (Groq, Ollama, Azure OpenAI, etc.) feat: Add support for OpenAI-compatible LLM endpoints (Groq, Ollama, Azure OpenAI, etc.) #1198

2. Description of change:

This is a working prototype demonstrating one way to add pluggable LLM backends to ADK-Java via ServiceLoader.

Problem

Python ADK gets zero-code provider switching for free — dynamic imports and LiteLLM resolve a model string from config at runtime. This PR demonstrates the Java-idiomatic equivalent: a ServiceLoader-based SPI where a model string in config plus a Maven dependency swap is all it takes.

What goes where

Into google-adk.jar — SPI layer (3 files):

• ModelProvider — SPI interface
• ModelProviderRegistry — ServiceLoader wiring
• OpenAiCompatibleLlm — reusable base class for any POST /v1/chat/completions provider

Into google-adk.jar — HTTP and serialization layer (or replaced by Google's existing implementation):

• OpenAiHttpClient — HTTP client interface (default impl included; could be backed by ADK's existing ChatCompletionsHttpClient)
• OpenAiMessageSerializer — serializer interface (default impl included; could be replaced by AdkChatSerializer using ADK 1.1.0 internal DTOs for richer response mapping)

Into Runner and AdkWebServer.start() (2 lines total):

ModelProviderRegistry.registerAll();

Everything else stays external. Provider JARs (Groq, Ollama, OpenRouter) live outside ADK and self-register via META-INF/services. No ADK PR is needed to add a new provider — dropping a JAR on the classpath in an ADK application is enough.

What's included

Module	Purpose
model-prism-core	ModelProvider SPI + OpenAiCompatibleLlm base class
model-prism-groq	Groq provider (groq/.*)
model-prism-ollama	Ollama provider — no API key, great for local dev
model-prism-openrouter	OpenRouter provider — free tier available
model-prism-demo	11 runnable demos covering tools, streaming, web server

Tests

13 unit tests, all passing. See PR description for full list.

Manual E2E verified with Groq and Ollama.

Proposed core integration (one line)

// In Runner or AdkWebServer.start()
ModelProviderRegistry.registerAll();

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

Tests run: 13, Failures: 0, Errors: 0, Skipped: 0

DefaultOpenAiMessageSerializerTest (9 tests):
  [OK] processStreamLines_textChunks_emitsPartialsThenFinal
  [OK] processStreamLines_emptyStream_emitsFinalEmptyResponse
  [OK] processStreamLines_nonDataLinesIgnored
  [OK] processStreamLines_toolCall_assemblesArgumentsAcrossChunks
  [OK] processStreamLines_multipleToolCalls_assemblesBothByIndex
  [OK] processStreamLines_errorChunk_throwsIllegalArgumentException
  [OK] processStreamLines_malformedJsonChunk_skippedGracefully
  [OK] deserializeResponse_textContent_returnsLlmResponseWithText
  [OK] deserializeResponse_toolCallContent_returnsFunctionCallPart

ModelProviderRegistryTest (4 tests):
  [OK] registerAll_singleProvider_registersPatternWithLlmRegistry
  [OK] registerAll_multipleProviders_registersAll
  [OK] registerAll_noProviders_returnsEmptyListAndNothingRegistered
  [OK] registerAll_calledTwice_registersEachTimeIndependently

Manual End-to-End (E2E) Tests:

The model-prism-demo module includes 11 runnable demo classes. To verify end-to-end:

# Set your key (OpenRouter has a free tier)
export OPENROUTER_API_KEY=your_key_here

# Basic SPI discovery
mvn -pl model-prism-demo exec:java -Dexec.mainClass=com.google.adk.models.demo.DemoApp

# Streaming
mvn -pl model-prism-demo exec:java -Dexec.mainClass=com.google.adk.models.demo.StreamingDemoApp

# Tool calling
mvn -pl model-prism-demo exec:java -Dexec.mainClass=com.google.adk.models.demo.tools.ToolsDemoApp

# ADK dev web server (open http://localhost:8080)
mvn -pl model-prism-demo exec:java -Dexec.mainClass=com.google.adk.models.demo.WebServerDemoApp

For Ollama (no API key required): install Ollama, run ollama pull llama3, then use model name ollama/llama3.

Checklist

• I have read the CONTRIBUTING.md document.
• My pull request contains a single commit.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

Additional context

Modules added under contrib/model-prism/:

Module	Purpose
model-prism-core	ModelProvider SPI, ModelProviderRegistry, OpenAiCompatibleLlm base class
model-prism-groq	Groq provider (groq/.*)
model-prism-ollama	Ollama provider (ollama/.*, no API key)
model-prism-openrouter	OpenRouter provider (openrouter/.*, free tier available)
model-prism-demo	11 demo classes covering all major ADK features

[hemasekhar-p]

Hi @svetanis, thank you for your contribution! We appreciate you taking the time to submit this pull request. Currently this PR is under review by our team, we will keep you posted if any additional information is required. thank you.

[hemasekhar-p]

@tilgalas, Could you please review this PR.

[svetanis]

Closing this PR — some context on why, and where the work goes next:

This PR reflects a snapshot from two months ago, and the ground has shifted under it since.
At the time it was developed, shipping its own HTTP/serialization layer was how the project got
OpenAI-compatible endpoints working end-to-end. Since then, ADK's native
ChatCompletionsHttpClient path has matured into the right foundation for this feature — and
along the way, integrating it into this project's demos helped surface and reproduce the
serializer issue fixed in ADK 1.6.0 (#1265/#1266).

For these reasons, I'm closing this PR today:

1. ADK now has a fully functional native client for OpenAI-compatible endpoints, so the custom
   HTTP client and serializer here are obsolete — the right implementation today simply wraps
   ChatCompletionsHttpClient.
2. The ModelProvider interface itself has evolved past this snapshot (name-aware per-model
   factories, bare wire-format model IDs).
3. The five demo modules bundled here have found a better home in a personal reference repo,
   agentic-jvm/model-prism, where they've been run
   against Groq and OpenRouter endpoints — keeping the upstream proposal down
   to its small core.

Rather than rebase a large diff whose foundations have shifted, I'm closing this in favor of a
small, self-contained follow-up — the SPI interface, the registry, a thin OpenAiCompatibleLlm
over the native client, and tests — already open as #1363 (issue: #1362).

Thanks @hemasekhar-p and @tilgalas for the triage — the follow-up will be a much easier review.