From 154577ee017c7ce3dfe510007a453626216f75d8 Mon Sep 17 00:00:00 2001 From: sidbharth Date: Thu, 22 Oct 2026 18:44:59 +0000 Subject: [PATCH 1/2] feat(providers): add NEAR AI Cloud as an OpenAI-compatible provider Registers nearai as a JSON-configured provider at https://cloud-api.near.ai/v1, reading NEARAI_API_KEY and an optional NEARAI_API_BASE Chat completions and embeddings go to NEAR AI natively. Responses and Anthropic Messages calls are bridged through chat completions, because NEAR AI's own /v1/responses is not wire-compatible with OpenAI's and its /v1/messages route is off by default JSON providers that list /v1/embeddings in supported_endpoints now route embedding calls through the OpenAI-like embedding handler. Before this they failed with "Unmapped LLM provider", which also affected pinstripes --- litellm/constants.py | 2 + litellm/llms/openai_like/json_loader.py | 12 +- litellm/llms/openai_like/providers.json | 6 + litellm/main.py | 1 + .../provider_endpoints_support_backup.json | 18 ++ .../provider_create_fields.json | 28 +++ litellm/types/utils.py | 1 + provider_endpoints_support.json | 18 ++ .../llms/openai_like/test_nearai_provider.py | 236 ++++++++++++++++++ 9 files changed, 321 insertions(+), 1 deletion(-) create mode 100644 tests/unit/llms/openai_like/test_nearai_provider.py diff --git a/litellm/constants.py b/litellm/constants.py index c0fe0491775..bd5acb34264 100644 --- a/litellm/constants.py +++ b/litellm/constants.py @@ -1058,6 +1058,7 @@ openai_compatible_endpoints: Final[list[str]] = [ "https://api.scx.ai/v1", "https://api.prisminference.com/v1", "https://api.reka.ai/v1", + "https://cloud-api.near.ai/v1", "https://gigachat.devices.sberbank.ru/api/v1", "https://api.openinfer.ai/v1", ] @@ -1138,6 +1139,7 @@ openai_compatible_providers: Final[list[str]] = [ "prism", "sail", "reka", + "nearai", ] OPENAI_AUDIO_TRANSCRIPTION_PROVIDERS: Final = frozenset({"openai"} | frozenset(openai_compatible_providers)) diff --git a/litellm/llms/openai_like/json_loader.py b/litellm/llms/openai_like/json_loader.py index 23b63177137..ae6636934ea 100644 --- a/litellm/llms/openai_like/json_loader.py +++ b/litellm/llms/openai_like/json_loader.py @@ -12,6 +12,7 @@ from litellm._logging import verbose_logger from litellm.types.utils import ProviderSpecificModelInfo _PROVIDER_INFO_ADAPTER: Final = TypeAdapter(ProviderSpecificModelInfo) +_SUPPORTED_ENDPOINTS_ADAPTER: Final = TypeAdapter(list[str]) class SimpleProviderConfig: @@ -26,7 +27,9 @@ class SimpleProviderConfig: self.param_mappings = data.get("param_mappings", {}) self.constraints = data.get("constraints", {}) self.special_handling = data.get("special_handling", {}) - self.supported_endpoints = data.get("supported_endpoints", []) + self.supported_endpoints: list[str] = _SUPPORTED_ENDPOINTS_ADAPTER.validate_python( + data.get("supported_endpoints", []) + ) self.provider_info: ProviderSpecificModelInfo = ( _PROVIDER_INFO_ADAPTER.validate_python(data["provider_info"]) if "provider_info" in data else {} ) @@ -86,6 +89,13 @@ class JSONProviderRegistry: return False return "/v1/responses" in provider.supported_endpoints + @classmethod + def supports_embeddings(cls, slug: str) -> bool: + provider: Final = cls._providers.get(slug) + if provider is None: + return False + return "/v1/embeddings" in provider.supported_endpoints + @classmethod def list_providers(cls) -> list: """List all registered provider slugs""" diff --git a/litellm/llms/openai_like/providers.json b/litellm/llms/openai_like/providers.json index 36337fddbdc..fa568c3c2f7 100644 --- a/litellm/llms/openai_like/providers.json +++ b/litellm/llms/openai_like/providers.json @@ -249,5 +249,11 @@ "/v1/responses", "/v1/messages" ] + }, + "nearai": { + "base_url": "https://cloud-api.near.ai/v1", + "api_key_env": "NEARAI_API_KEY", + "api_base_env": "NEARAI_API_BASE", + "supported_endpoints": ["/v1/chat/completions", "/v1/embeddings"] } } diff --git a/litellm/main.py b/litellm/main.py index 27700cf9def..55e7f8e2963 100644 --- a/litellm/main.py +++ b/litellm/main.py @@ -6911,6 +6911,7 @@ def embedding( custom_llm_provider == "openai_like" or custom_llm_provider == "llamafile" or custom_llm_provider == "lm_studio" + or JSONProviderRegistry.supports_embeddings(custom_llm_provider) ): api_base = api_base or litellm.api_base or get_secret_str("OPENAI_LIKE_API_BASE") diff --git a/litellm/provider_endpoints_support_backup.json b/litellm/provider_endpoints_support_backup.json index f95b553c2b4..cc23d7675f0 100644 --- a/litellm/provider_endpoints_support_backup.json +++ b/litellm/provider_endpoints_support_backup.json @@ -1593,6 +1593,24 @@ "a2a": false } }, + "nearai": { + "display_name": "NEAR AI Cloud (`nearai`)", + "url": "https://docs.litellm.ai/docs/providers/nearai", + "endpoints": { + "chat_completions": true, + "messages": true, + "responses": true, + "embeddings": true, + "image_generations": false, + "audio_transcriptions": false, + "audio_speech": false, + "moderations": false, + "batches": false, + "rerank": false, + "a2a": false, + "interactions": false + } + }, "nebius": { "display_name": "Nebius AI Studio (`nebius`)", "url": "https://docs.litellm.ai/docs/providers/nebius", diff --git a/litellm/proxy/public_endpoints/provider_create_fields.json b/litellm/proxy/public_endpoints/provider_create_fields.json index 4bec42a7868..06b6c0cc1f5 100644 --- a/litellm/proxy/public_endpoints/provider_create_fields.json +++ b/litellm/proxy/public_endpoints/provider_create_fields.json @@ -2455,6 +2455,34 @@ ], "default_model_placeholder": "nace/drex-latest" }, + { + "provider": "NEARAI", + "provider_display_name": "NEAR AI Cloud", + "litellm_provider": "nearai", + "credential_fields": [ + { + "key": "api_base", + "label": "API Base", + "placeholder": "https://cloud-api.near.ai/v1", + "tooltip": null, + "required": false, + "field_type": "text", + "options": null, + "default_value": null + }, + { + "key": "api_key", + "label": "API Key", + "placeholder": null, + "tooltip": null, + "required": true, + "field_type": "password", + "options": null, + "default_value": null + } + ], + "default_model_placeholder": "nearai/z-ai/glm-5.3-flash" + }, { "provider": "NEBIUS", "provider_display_name": "Nebius", diff --git a/litellm/types/utils.py b/litellm/types/utils.py index 5939a350970..e22e12d6b76 100644 --- a/litellm/types/utils.py +++ b/litellm/types/utils.py @@ -4545,6 +4545,7 @@ class LlmProviders(str, Enum): COGNITION = "cognition" CORALBRICKS = "coralbricks" CORTECS = "cortecs" + NEARAI = "nearai" SCX_AI = "scx-ai" PRISM = "prism" OPENINFER = "openinfer" diff --git a/provider_endpoints_support.json b/provider_endpoints_support.json index d65da3f41fd..f77aeabad72 100644 --- a/provider_endpoints_support.json +++ b/provider_endpoints_support.json @@ -1765,6 +1765,24 @@ "a2a": false } }, + "nearai": { + "display_name": "NEAR AI Cloud (`nearai`)", + "url": "https://docs.litellm.ai/docs/providers/nearai", + "endpoints": { + "chat_completions": true, + "messages": true, + "responses": true, + "embeddings": true, + "image_generations": false, + "audio_transcriptions": false, + "audio_speech": false, + "moderations": false, + "batches": false, + "rerank": false, + "a2a": false, + "interactions": false + } + }, "nebius": { "display_name": "Nebius AI Studio (`nebius`)", "url": "https://docs.litellm.ai/docs/providers/nebius", diff --git a/tests/unit/llms/openai_like/test_nearai_provider.py b/tests/unit/llms/openai_like/test_nearai_provider.py new file mode 100644 index 00000000000..7aabec917db --- /dev/null +++ b/tests/unit/llms/openai_like/test_nearai_provider.py @@ -0,0 +1,236 @@ +import json +from pathlib import Path +from typing import Final + +import pytest +import respx + +import litellm +from litellm.caching.llm_caching_handler import LLMClientCache + +_CHAT_COMPLETION: Final = { + "id": "chatcmpl_nearai", + "object": "chat.completion", + "created": 1_792_000_000, + "model": "z-ai/glm-5.3-flash", + "choices": [ + { + "index": 0, + "message": {"role": "assistant", "content": "Hello from NEAR AI"}, + "finish_reason": "stop", + } + ], + "usage": {"prompt_tokens": 4, "completion_tokens": 4, "total_tokens": 8}, +} + + +def test_nearai_is_a_registered_provider(): + assert litellm.LlmProviders.NEARAI.value == "nearai" + assert "nearai" in litellm.provider_list + assert "nearai" in litellm.constants.openai_compatible_providers + + +def test_nearai_provider_resolution(monkeypatch: pytest.MonkeyPatch): + from litellm.litellm_core_utils.get_llm_provider_logic import get_llm_provider + + monkeypatch.setenv("NEARAI_API_KEY", "nearai-test-key") + monkeypatch.delenv("NEARAI_API_BASE", raising=False) + + model, provider, api_key, api_base = get_llm_provider( + model="nearai/z-ai/glm-5.3-flash", + custom_llm_provider=None, + api_base=None, + api_key=None, + ) + + assert model == "z-ai/glm-5.3-flash" + assert provider == "nearai" + assert api_key == "nearai-test-key" + assert api_base == "https://cloud-api.near.ai/v1" + + +def test_nearai_provider_keeps_explicit_credentials(monkeypatch: pytest.MonkeyPatch): + from litellm.litellm_core_utils.get_llm_provider_logic import get_llm_provider + + monkeypatch.setenv("NEARAI_API_KEY", "nearai-env-key") + monkeypatch.setenv("NEARAI_API_BASE", "https://nearai.env.example/v1") + + _, provider, api_key, api_base = get_llm_provider( + model="nearai/z-ai/glm-5.3-flash", + custom_llm_provider=None, + api_base="https://nearai.internal.example/v1", + api_key="nearai-explicit-key", + ) + + assert provider == "nearai" + assert api_key == "nearai-explicit-key" + assert api_base == "https://nearai.internal.example/v1" + + +def test_nearai_api_base_env_overrides_default(monkeypatch: pytest.MonkeyPatch): + from litellm.litellm_core_utils.get_llm_provider_logic import get_llm_provider + + monkeypatch.setenv("NEARAI_API_KEY", "nearai-env-key") + monkeypatch.setenv("NEARAI_API_BASE", "https://nearai.env.example/v1") + + _, provider, _, api_base = get_llm_provider( + model="nearai/z-ai/glm-5.3-flash", + custom_llm_provider=None, + api_base=None, + api_key=None, + ) + + assert provider == "nearai" + assert api_base == "https://nearai.env.example/v1" + + +def test_nearai_api_base_autodetects_provider(monkeypatch: pytest.MonkeyPatch): + from litellm.litellm_core_utils.get_llm_provider_logic import get_llm_provider + + monkeypatch.setenv("NEARAI_API_KEY", "nearai-env-key") + + model, provider, api_key, api_base = get_llm_provider( + model="z-ai/glm-5.3-flash", + custom_llm_provider=None, + api_base="https://cloud-api.near.ai/v1", + api_key=None, + ) + + assert model == "z-ai/glm-5.3-flash" + assert provider == "nearai" + assert api_key == "nearai-env-key" + assert api_base == "https://cloud-api.near.ai/v1" + + +def test_nearai_is_available_in_add_model_form(): + fields_path = Path(litellm.__file__).parent / "proxy" / "public_endpoints" / "provider_create_fields.json" + providers = json.loads(fields_path.read_text()) + nearai = next(provider for provider in providers if provider["litellm_provider"] == "nearai") + + assert nearai["provider"] == "NEARAI" + assert nearai["provider_display_name"] == "NEAR AI Cloud" + assert nearai["default_model_placeholder"] == "nearai/z-ai/glm-5.3-flash" + assert {field["key"]: field["required"] for field in nearai["credential_fields"]} == { + "api_base": False, + "api_key": True, + } + + +def test_nearai_supported_endpoints(): + expected: Final = { + "chat_completions": True, + "messages": True, + "responses": True, + "embeddings": True, + "image_generations": False, + "audio_transcriptions": False, + "audio_speech": False, + "moderations": False, + "batches": False, + "rerank": False, + "a2a": False, + "interactions": False, + } + backup_path = Path(litellm.__file__).parent / "provider_endpoints_support_backup.json" + root_path = Path(litellm.__file__).parent.parent / "provider_endpoints_support.json" + + assert json.loads(backup_path.read_text())["providers"]["nearai"]["endpoints"] == expected + assert json.loads(root_path.read_text())["providers"]["nearai"]["endpoints"] == expected + + +def test_nearai_chat_completion_request(): + with respx.mock() as upstream: + route: Final = upstream.post("https://cloud-api.near.ai/v1/chat/completions").respond( + 200, json=_CHAT_COMPLETION + ) + response: Final = litellm.completion( + model="nearai/z-ai/glm-5.3-flash", + messages=[{"role": "user", "content": "Say hello"}], + max_completion_tokens=32, + api_key="nearai-test-key", + ) + + request: Final = route.calls.last.request + body: Final = json.loads(request.content) + assert route.call_count == 1 + assert str(request.url) == "https://cloud-api.near.ai/v1/chat/completions" + assert request.headers["authorization"] == "Bearer nearai-test-key" + assert body["model"] == "z-ai/glm-5.3-flash" + assert body["messages"] == [{"role": "user", "content": "Say hello"}] + assert body["max_completion_tokens"] == 32 + assert response.choices[0].message.content == "Hello from NEAR AI" + + +def test_nearai_responses_request_is_bridged_to_chat_completions(): + with respx.mock(assert_all_called=False) as upstream: + chat_route: Final = upstream.post("https://cloud-api.near.ai/v1/chat/completions").respond( + 200, json=_CHAT_COMPLETION + ) + responses_route: Final = upstream.post("https://cloud-api.near.ai/v1/responses").respond(500) + response: Final = litellm.responses( + model="nearai/z-ai/glm-5.3-flash", + input="Say hello", + api_key="nearai-test-key", + ) + + request: Final = chat_route.calls.last.request + body: Final = json.loads(request.content) + assert chat_route.call_count == 1 + assert responses_route.call_count == 0 + assert request.headers["authorization"] == "Bearer nearai-test-key" + assert body["model"] == "z-ai/glm-5.3-flash" + assert body["messages"] == [{"role": "user", "content": "Say hello"}] + assert response.output[0].content[0].text == "Hello from NEAR AI" + + +@pytest.mark.asyncio +async def test_nearai_anthropic_messages_request_is_bridged_to_chat_completions(monkeypatch: pytest.MonkeyPatch): + monkeypatch.setattr(litellm, "disable_aiohttp_transport", True) + monkeypatch.setattr(litellm, "in_memory_llm_clients_cache", LLMClientCache()) + with respx.mock(assert_all_called=False) as upstream: + chat_route: Final = upstream.post("https://cloud-api.near.ai/v1/chat/completions").respond( + 200, json=_CHAT_COMPLETION + ) + messages_route: Final = upstream.post("https://cloud-api.near.ai/v1/messages").respond(500) + response: Final = await litellm.anthropic.messages.acreate( + model="nearai/z-ai/glm-5.3-flash", + messages=[{"role": "user", "content": "Say hello"}], + max_tokens=32, + api_key="nearai-test-key", + ) + + request: Final = chat_route.calls.last.request + body: Final = json.loads(request.content) + assert chat_route.call_count == 1 + assert messages_route.call_count == 0 + assert request.headers["authorization"] == "Bearer nearai-test-key" + assert body["model"] == "z-ai/glm-5.3-flash" + assert body["messages"] == [{"role": "user", "content": "Say hello"}] + assert response["content"][0]["text"] == "Hello from NEAR AI" + + +def test_nearai_embedding_request(): + with respx.mock() as upstream: + route: Final = upstream.post("https://cloud-api.near.ai/v1/embeddings").respond( + 200, + json={ + "object": "list", + "data": [{"object": "embedding", "index": 0, "embedding": [0.25, -0.5, 0.75]}], + "model": "Qwen/Qwen3-Embedding-0.6B", + "usage": {"prompt_tokens": 2, "total_tokens": 2}, + }, + ) + response: Final = litellm.embedding( + model="nearai/Qwen/Qwen3-Embedding-0.6B", + input=["Say hello"], + api_key="nearai-test-key", + ) + + request: Final = route.calls.last.request + body: Final = json.loads(request.content) + assert route.call_count == 1 + assert str(request.url) == "https://cloud-api.near.ai/v1/embeddings" + assert request.headers["authorization"] == "Bearer nearai-test-key" + assert body["model"] == "Qwen/Qwen3-Embedding-0.6B" + assert body["input"] == ["Say hello"] + assert response.data[0]["embedding"] == [0.25, -0.5, 0.75] From 142fc38d690757dea13c01874ee75c0e23012f6b Mon Sep 17 00:00:00 2001 From: sidbharth Date: Fri, 23 Oct 2026 12:52:41 +0000 Subject: [PATCH 2/2] fix(openai_like): check JSON provider endpoints through one helper Moves the supported_endpoints lookup into JSONProviderRegistry.supports_endpoint so the embeddings check and the Responses check share it. This keeps the type discipline and basedpyright counts at their merge-base values --- litellm/llms/openai_like/json_loader.py | 18 ++++++------------ litellm/main.py | 2 +- 2 files changed, 7 insertions(+), 13 deletions(-) diff --git a/litellm/llms/openai_like/json_loader.py b/litellm/llms/openai_like/json_loader.py index ae6636934ea..7ea2b25a764 100644 --- a/litellm/llms/openai_like/json_loader.py +++ b/litellm/llms/openai_like/json_loader.py @@ -12,7 +12,6 @@ from litellm._logging import verbose_logger from litellm.types.utils import ProviderSpecificModelInfo _PROVIDER_INFO_ADAPTER: Final = TypeAdapter(ProviderSpecificModelInfo) -_SUPPORTED_ENDPOINTS_ADAPTER: Final = TypeAdapter(list[str]) class SimpleProviderConfig: @@ -27,9 +26,7 @@ class SimpleProviderConfig: self.param_mappings = data.get("param_mappings", {}) self.constraints = data.get("constraints", {}) self.special_handling = data.get("special_handling", {}) - self.supported_endpoints: list[str] = _SUPPORTED_ENDPOINTS_ADAPTER.validate_python( - data.get("supported_endpoints", []) - ) + self.supported_endpoints = data.get("supported_endpoints", []) self.provider_info: ProviderSpecificModelInfo = ( _PROVIDER_INFO_ADAPTER.validate_python(data["provider_info"]) if "provider_info" in data else {} ) @@ -82,19 +79,16 @@ class JSONProviderRegistry: return next((provider for provider in cls._providers.values() if provider.base_url == base_url), None) @classmethod - def supports_responses_api(cls, slug: str) -> bool: - """Check if a JSON provider supports the Responses API""" + def supports_endpoint(cls, slug: str, endpoint: str) -> bool: provider: Final = cls._providers.get(slug) if provider is None: return False - return "/v1/responses" in provider.supported_endpoints + return endpoint in provider.supported_endpoints @classmethod - def supports_embeddings(cls, slug: str) -> bool: - provider: Final = cls._providers.get(slug) - if provider is None: - return False - return "/v1/embeddings" in provider.supported_endpoints + def supports_responses_api(cls, slug: str) -> bool: + """Check if a JSON provider supports the Responses API""" + return cls.supports_endpoint(slug, "/v1/responses") @classmethod def list_providers(cls) -> list: diff --git a/litellm/main.py b/litellm/main.py index 55e7f8e2963..ff9b396bf6f 100644 --- a/litellm/main.py +++ b/litellm/main.py @@ -6911,7 +6911,7 @@ def embedding( custom_llm_provider == "openai_like" or custom_llm_provider == "llamafile" or custom_llm_provider == "lm_studio" - or JSONProviderRegistry.supports_embeddings(custom_llm_provider) + or JSONProviderRegistry.supports_endpoint(custom_llm_provider, "/v1/embeddings") ): api_base = api_base or litellm.api_base or get_secret_str("OPENAI_LIKE_API_BASE")