Merge main into feature/skillbook-rename

- Integrate new ACELiteLLM parameters (api_key, base_url, extra_headers, ssl_verify)
- Resolve conflicts keeping both: new API parameters + skillbook terminology
- All 271 tests pass

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: Lanzelot1

ace/integrations/litellm.py

@@ -39,7 +39,7 @@
     agent = ACELiteLLM(model="gpt-4o-mini", skillbook_path="my_agent.json")
 """
 
-from typing import TYPE_CHECKING, List, Optional, Dict, Any, Tuple
+from typing import TYPE_CHECKING, List, Optional, Dict, Any, Tuple, Union
 
 from ..skillbook import Skillbook
 from ..roles import Agent, Reflector, SkillManager, AgentOutput
@@ -103,9 +103,18 @@ def __init__(
         model: str = "gpt-4o-mini",
         max_tokens: int = 2048,
         temperature: float = 0.0,
+        # Authentication & endpoint
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        # HTTP/SSL settings
+        extra_headers: Optional[Dict[str, str]] = None,
+        ssl_verify: Optional[Union[bool, str]] = None,
+        # ACE-specific settings
         skillbook_path: Optional[str] = None,
         is_learning: bool = True,
         dedup_config: Optional["DeduplicationConfig"] = None,
+        # Pass-through for advanced LiteLLM options
+        **llm_kwargs: Any,
     ):
         """
         Initialize ACELiteLLM agent.
@@ -115,9 +124,14 @@ def __init__(
                    Supports 100+ providers: OpenAI, Anthropic, Google, etc.
             max_tokens: Max tokens for responses (default: 2048)
             temperature: Sampling temperature (default: 0.0)
+            api_key: API key for the LLM provider. Falls back to env vars if not set.
+            base_url: Custom API endpoint URL (e.g., http://localhost:1234/v1)
+            extra_headers: Custom HTTP headers dict (e.g., {"X-Tenant-ID": "abc"})
+            ssl_verify: SSL verification. False to disable, or path to CA bundle.
             skillbook_path: Path to existing skillbook (optional)
             is_learning: Enable/disable learning (default: True)
             dedup_config: Optional DeduplicationConfig for skill deduplication
+            **llm_kwargs: Additional LiteLLM parameters (timeout, max_retries, etc.)
 
         Raises:
             ImportError: If LiteLLM is not installed
@@ -132,6 +146,23 @@ def __init__(
             # Google
             agent = ACELiteLLM(model="gemini/gemini-pro")
 
+            # With explicit API key
+            agent = ACELiteLLM(model="gpt-4", api_key="sk-...")
+
+            # Custom endpoint (LM Studio, Ollama)
+            agent = ACELiteLLM(
+                model="openai/local-model",
+                base_url="http://localhost:1234/v1"
+            )
+
+            # Enterprise with custom headers and SSL
+            agent = ACELiteLLM(
+                model="gpt-4",
+                base_url="https://proxy.company.com/v1",
+                extra_headers={"X-Tenant-ID": "team-alpha"},
+                ssl_verify="/path/to/internal-ca.pem"
+            )
+
             # With existing skillbook
             agent = ACELiteLLM(
                 model="gpt-4o-mini",
@@ -165,9 +196,16 @@ def __init__(
         else:
             self.skillbook = Skillbook()
 
-        # Create LLM client
+        # Create LLM client with configuration
         self.llm = LiteLLMClient(
-            model=model, max_tokens=max_tokens, temperature=temperature
+            model=model,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            api_key=api_key,
+            api_base=base_url,  # Map user-friendly name to LiteLLM's api_base
+            extra_headers=extra_headers,
+            ssl_verify=ssl_verify,
+            **llm_kwargs,
         )
 
         # Create ACE components with v2.1 prompts

ace/llm_providers/litellm_client.py

@@ -64,6 +64,10 @@ class LiteLLMConfig:
     # Anthropic API limitation: temperature and top_p cannot both be specified
     sampling_priority: str = "temperature"  # "temperature" | "top_p" | "top_k"
 
+    # HTTP/SSL settings
+    extra_headers: Optional[Dict[str, str]] = None  # Custom HTTP headers
+    ssl_verify: Optional[Union[bool, str]] = None  # True/False or path to CA bundle
+
 
 class LiteLLMClient(LLMClient):
     """
@@ -436,6 +440,12 @@ def complete(
         if self.config.api_base:
             call_params["api_base"] = self.config.api_base
 
+        # Add HTTP/SSL settings
+        if self.config.extra_headers:
+            call_params["extra_headers"] = self.config.extra_headers
+        if self.config.ssl_verify is not None:
+            call_params["ssl_verify"] = self.config.ssl_verify
+
         # Add Opik span association for role-level token aggregation
         if OPIK_SPAN_AVAILABLE and get_current_span_data:
             try:
@@ -560,6 +570,12 @@ async def acomplete(
         if self.config.api_base:
             call_params["api_base"] = self.config.api_base
 
+        # Add HTTP/SSL settings
+        if self.config.extra_headers:
+            call_params["extra_headers"] = self.config.extra_headers
+        if self.config.ssl_verify is not None:
+            call_params["ssl_verify"] = self.config.ssl_verify
+
         # Add Opik span association for role-level token aggregation
         if OPIK_SPAN_AVAILABLE and get_current_span_data:
             try:

examples/local-models/lm_studio_example.py

@@ -9,7 +9,6 @@
 from ace.integrations import ACELiteLLM
 from ace import Sample, SimpleEnvironment
 from pathlib import Path
-import os
 
 
 def main():
@@ -19,17 +18,15 @@ def main():
     lm_studio_url = "http://localhost:1234/v1"
 
     # 1. Create ACELiteLLM agent pointing to LM Studio
-    # Note: Use "openai/" prefix with api_base for LM Studio
+    # Note: Use "openai/" prefix with base_url for LM Studio
     print(f"\n📡 Connecting to LM Studio at {lm_studio_url}...")
 
-    # Set environment variable for LiteLLM to use custom endpoint
-    os.environ["OPENAI_API_BASE"] = lm_studio_url
-
     skillbook_path = Path("lm_studio_learned_strategies.json")
 
     try:
         agent = ACELiteLLM(
             model="openai/local-model",  # LM Studio serves any model as 'local-model'
+            base_url=lm_studio_url,
             max_tokens=512,
             temperature=0.2,
             is_learning=True,

tests/test_litellm_client.py

@@ -247,5 +247,167 @@ def test_config_with_explicit_top_p(self):
         self.assertEqual(config.top_p, 0.9)
 
 
+@pytest.mark.unit
+class TestACELiteLLMConfiguration(unittest.TestCase):
+    """Test ACELiteLLM configuration parameter passing."""
+
+    def _mock_response(self):
+        """Create mock LiteLLM response."""
+        mock = MagicMock()
+        mock.choices = [
+            MagicMock(
+                message=MagicMock(
+                    content='{"reasoning":"test","bullet_ids":[],"final_answer":"ok"}'
+                )
+            )
+        ]
+        mock.usage = None
+        mock.model = "gpt-4"
+        return mock
+
+    @patch("ace.llm_providers.litellm_client.completion")
+    def test_api_key_passed_to_client(self, mock_completion):
+        """Test api_key parameter is passed to LiteLLMClient."""
+        mock_completion.return_value = self._mock_response()
+
+        from ace.integrations import ACELiteLLM
+
+        agent = ACELiteLLM(model="gpt-4", api_key="test-key-123")
+        self.assertEqual(agent.llm.config.api_key, "test-key-123")
+
+    @patch("ace.llm_providers.litellm_client.completion")
+    def test_base_url_maps_to_api_base(self, mock_completion):
+        """Test base_url maps to api_base in config."""
+        mock_completion.return_value = self._mock_response()
+
+        from ace.integrations import ACELiteLLM
+
+        agent = ACELiteLLM(model="openai/local", base_url="http://localhost:1234/v1")
+        self.assertEqual(agent.llm.config.api_base, "http://localhost:1234/v1")
+
+    @patch("ace.llm_providers.litellm_client.completion")
+    def test_extra_headers_passed(self, mock_completion):
+        """Test extra_headers parameter is passed through."""
+        mock_completion.return_value = self._mock_response()
+
+        from ace.integrations import ACELiteLLM
+
+        headers = {"X-Custom": "value", "X-Tenant-ID": "team-alpha"}
+        agent = ACELiteLLM(model="gpt-4", extra_headers=headers)
+        self.assertEqual(agent.llm.config.extra_headers, headers)
+
+    @patch("ace.llm_providers.litellm_client.completion")
+    def test_ssl_verify_false(self, mock_completion):
+        """Test ssl_verify=False is passed through."""
+        mock_completion.return_value = self._mock_response()
+
+        from ace.integrations import ACELiteLLM
+
+        agent = ACELiteLLM(model="gpt-4", ssl_verify=False)
+        self.assertEqual(agent.llm.config.ssl_verify, False)
+
+    @patch("ace.llm_providers.litellm_client.completion")
+    def test_ssl_verify_path(self, mock_completion):
+        """Test ssl_verify with CA bundle path."""
+        mock_completion.return_value = self._mock_response()
+
+        from ace.integrations import ACELiteLLM
+
+        agent = ACELiteLLM(model="gpt-4", ssl_verify="/path/to/ca.pem")
+        self.assertEqual(agent.llm.config.ssl_verify, "/path/to/ca.pem")
+
+    @patch("ace.llm_providers.litellm_client.completion")
+    def test_kwargs_passed_through(self, mock_completion):
+        """Test **llm_kwargs are passed to LiteLLMClient."""
+        mock_completion.return_value = self._mock_response()
+
+        from ace.integrations import ACELiteLLM
+
+        agent = ACELiteLLM(model="gpt-4", timeout=120, max_retries=5)
+        self.assertEqual(agent.llm.config.timeout, 120)
+        self.assertEqual(agent.llm.config.max_retries, 5)
+
+    @patch("ace.llm_providers.litellm_client.completion")
+    def test_backward_compatibility(self, mock_completion):
+        """Test that existing code without new params still works."""
+        mock_completion.return_value = self._mock_response()
+
+        from ace.integrations import ACELiteLLM
+
+        agent = ACELiteLLM(model="gpt-4o-mini", max_tokens=1024, temperature=0.5)
+        self.assertEqual(agent.model, "gpt-4o-mini")
+        self.assertEqual(agent.llm.config.max_tokens, 1024)
+        self.assertEqual(agent.llm.config.temperature, 0.5)
+        # New params should be None by default (api_key may be picked up from env vars)
+        self.assertIsNone(agent.llm.config.extra_headers)
+        self.assertIsNone(agent.llm.config.ssl_verify)
+
+
+@pytest.mark.unit
+class TestLiteLLMClientDirectConfig(unittest.TestCase):
+    """Test LiteLLMClient direct configuration."""
+
+    def _mock_response(self):
+        """Create mock LiteLLM response."""
+        mock = MagicMock()
+        mock.choices = [MagicMock(message=MagicMock(content="Test response"))]
+        mock.usage = None
+        mock.model = "gpt-4"
+        return mock
+
+    @patch("ace.llm_providers.litellm_client.completion")
+    def test_extra_headers_in_call_params(self, mock_completion):
+        """Test extra_headers is included in LiteLLM call_params."""
+        mock_completion.return_value = self._mock_response()
+
+        from ace.llm_providers import LiteLLMClient
+
+        headers = {"X-Custom": "value"}
+        client = LiteLLMClient(model="gpt-4", extra_headers=headers)
+        client.complete("Test prompt")
+
+        call_kwargs = mock_completion.call_args[1]
+        self.assertEqual(call_kwargs["extra_headers"], headers)
+
+    @patch("ace.llm_providers.litellm_client.completion")
+    def test_ssl_verify_false_in_call_params(self, mock_completion):
+        """Test ssl_verify=False is included in LiteLLM call_params."""
+        mock_completion.return_value = self._mock_response()
+
+        from ace.llm_providers import LiteLLMClient
+
+        client = LiteLLMClient(model="gpt-4", ssl_verify=False)
+        client.complete("Test prompt")
+
+        call_kwargs = mock_completion.call_args[1]
+        self.assertEqual(call_kwargs["ssl_verify"], False)
+
+    @patch("ace.llm_providers.litellm_client.completion")
+    def test_ssl_verify_path_in_call_params(self, mock_completion):
+        """Test ssl_verify path is included in LiteLLM call_params."""
+        mock_completion.return_value = self._mock_response()
+
+        from ace.llm_providers import LiteLLMClient
+
+        client = LiteLLMClient(model="gpt-4", ssl_verify="/path/to/ca.pem")
+        client.complete("Test prompt")
+
+        call_kwargs = mock_completion.call_args[1]
+        self.assertEqual(call_kwargs["ssl_verify"], "/path/to/ca.pem")
+
+    @patch("ace.llm_providers.litellm_client.completion")
+    def test_ssl_verify_none_not_in_call_params(self, mock_completion):
+        """Test ssl_verify=None is NOT included in call_params."""
+        mock_completion.return_value = self._mock_response()
+
+        from ace.llm_providers import LiteLLMClient
+
+        client = LiteLLMClient(model="gpt-4")  # ssl_verify defaults to None
+        client.complete("Test prompt")
+
+        call_kwargs = mock_completion.call_args[1]
+        self.assertNotIn("ssl_verify", call_kwargs)
+
+
 if __name__ == "__main__":
     unittest.main()