fix(llm): correct LiteLLM embed() model override + finish amd#1593 review items (amd#1626)

Closes amd#1625

## Why this matters
After amd#1593 added the LiteLLM provider, `LiteLLMProvider.embed()`
crashed with `TypeError: embedding() got multiple values for keyword
argument 'model'` the moment a caller overrode the model — `model` was
passed both explicitly and inside the spread `**call_kwargs`, and that
path had zero test coverage. Now `embed()` works with and without a
model override, and the rest of the amd#1593 review is closed out: the
provider is documented, the `create_client` docstring lists it, and the
redundant `drop_params` handling is collapsed to a single per-call
default callers can override.

## Test plan
- [x] `pytest tests/unit/test_litellm_provider.py` → 12 passed (incl. 2
new `embed()` tests; the override test reproduced the `TypeError` before
the fix)
- [x] `util/lint.py --black --isort --flake8` → all PASS
- [ ] CI green after maintainer approves the workflow run

---------

Co-authored-by: Tomasz Iniewicz <heaters-nays0p@icloud.com>

Author: itomek

docs/sdk/sdks/llm.mdx

@@ -66,6 +66,10 @@ llm_claude = create_client(use_claude=True)
 # OpenAI API
 llm_openai = create_client(use_openai=True)
 
+# LiteLLM gateway — 100+ providers (Bedrock, Vertex AI, Groq, Azure, ...)
+# Requires: pip install 'gaia[litellm]'
+llm_litellm = create_client("litellm", model="anthropic/claude-sonnet-4-6")
+
 # Use same interface
 response = llm_claude.generate("Explain Python decorators")
 ```

src/gaia/llm/factory.py

@@ -24,7 +24,7 @@ def create_client(
     Create an LLM client, auto-detecting provider from parameters.
 
     Args:
-        provider: Explicit provider name ("lemonade", "openai", or "claude").
+        provider: Explicit provider name ("lemonade", "openai", "claude", or "litellm").
                   If not specified, auto-detected from use_claude/use_openai flags.
         use_claude: If True, use Claude provider (ignored if provider is specified)
         use_openai: If True, use OpenAI provider (ignored if provider is specified)

src/gaia/llm/providers/litellm.py

@@ -17,15 +17,19 @@ def __init__(
         system_prompt: Optional[str] = None,
         **kwargs,
     ):
-        import litellm
-
+        try:
+            import litellm
+        except ImportError as e:
+            raise ImportError(
+                "litellm is not installed. Install it with: pip install 'gaia[litellm]'"
+            ) from e
+
+        self._litellm = litellm
         self._model = model
         self._system_prompt = system_prompt
         self._api_key = api_key
         self._extra_kwargs = kwargs
 
-        litellm.drop_params = True
-
     @property
     def provider_name(self) -> str:
         return "LiteLLM"
@@ -51,39 +55,36 @@ def chat(
         stream: bool = False,
         **kwargs,
     ) -> Union[str, Iterator[str]]:
-        import litellm
-
         if self._system_prompt:
             messages = [{"role": "system", "content": self._system_prompt}] + list(
                 messages
             )
 
         call_kwargs = {**self._extra_kwargs, **kwargs}
+        call_kwargs.setdefault("drop_params", True)
         if self._api_key:
             call_kwargs["api_key"] = self._api_key
 
-        response = litellm.completion(
+        response = self._litellm.completion(
             model=model or self._model,
             messages=messages,
             stream=stream,
-            drop_params=True,
             **call_kwargs,
         )
         if stream:
             return self._handle_stream(response)
         return response.choices[0].message.content
 
     def embed(self, texts: list[str], **kwargs) -> list[list[float]]:
-        import litellm
-
+        model = kwargs.pop("model", self._model)
         call_kwargs = {**self._extra_kwargs, **kwargs}
+        call_kwargs.setdefault("drop_params", True)
         if self._api_key:
             call_kwargs["api_key"] = self._api_key
 
-        response = litellm.embedding(
-            model=kwargs.pop("model", self._model),
+        response = self._litellm.embedding(
+            model=model,
             input=texts,
-            drop_params=True,
             **call_kwargs,
         )
         return [item["embedding"] for item in response.data]

tests/unit/test_litellm_provider.py

@@ -132,6 +132,34 @@ def test_generate_delegates_to_chat(self):
         del sys.modules["litellm"]
 
 
+class TestLiteLLMEmbed:
+    def test_embed_default_model(self):
+        fake = _stub_litellm()
+        fake.embedding.return_value = MagicMock(data=[{"embedding": [0.1, 0.2, 0.3]}])
+        from gaia.llm.providers.litellm import LiteLLMProvider
+
+        provider = LiteLLMProvider(api_key="sk-test", model="text-embedding-3-small")
+        result = provider.embed(["hello"])
+
+        assert result == [[0.1, 0.2, 0.3]]
+        assert fake.embedding.call_args.kwargs["model"] == "text-embedding-3-small"
+        assert fake.embedding.call_args.kwargs["api_key"] == "sk-test"
+        del sys.modules["litellm"]
+
+    def test_embed_uses_override_model(self):
+        fake = _stub_litellm()
+        fake.embedding.return_value = MagicMock(data=[{"embedding": [0.0]}])
+        from gaia.llm.providers.litellm import LiteLLMProvider
+
+        provider = LiteLLMProvider(model="text-embedding-3-small")
+        # Overriding the model must NOT raise TypeError (model previously landed
+        # in both the explicit arg and **call_kwargs).
+        provider.embed(["hello"], model="text-embedding-3-large")
+
+        assert fake.embedding.call_args.kwargs["model"] == "text-embedding-3-large"
+        del sys.modules["litellm"]
+
+
 class TestLiteLLMNotSupported:
     def test_vision_raises_not_supported(self):
         _stub_litellm()