v31.5.0 (#136)

Author: truemagic-coder

README.md

@@ -87,6 +87,7 @@ Smart workflows are as easy as combining your tools and prompts.
 * [Python](https://python.org) - Programming Language
 * [OpenAI](https://openai.com) - AI Model Provider
 * [Grok](https://x.ai) - Alternative AI Model Provider (optional)
+* [Groq](https://groq.com) - Alternative AI Model Provider (optional)
 * [MongoDB](https://mongodb.com) - Conversational History (optional)
 * [Zep Cloud](https://getzep.com) - Conversational Memory (optional)
 * [Pinecone](https://pinecone.io) - Knowledge Base (optional)
@@ -571,6 +572,40 @@ config = {
 - ✅ Structured outputs (via Instructor TOOLS_STRICT and JSON modes)
 - ✅ Native JSON mode
 
+### Groq
+
+Solana Agent supports using Groq as an alternative to OpenAI. When Groq is configured, it will be used for all LLM operations except embeddings, TTS, and STT (which still require OpenAI).
+
+**Note:** Grok configuration takes priority over Groq, and Groq takes priority over OpenAI. If multiple are present, the highest priority provider will be used.
+
+```python
+config = {
+    "groq": {
+        "api_key": "your-groq-api-key",
+        "base_url": "https://api.groq.com/openai/v1",  # Optional, defaults to https://api.groq.com/openai/v1
+        "model": "openai/gpt-oss-120b"  # Optional, defaults to openai/gpt-oss-120b
+    },
+    # You can still include OpenAI for embeddings, TTS, and STT
+    "openai": {
+        "api_key": "your-openai-api-key"
+    },
+    "agents": [
+        {
+            "name": "research_specialist",
+            "instructions": "You are an expert researcher.",
+            "specialization": "Research",
+        }
+    ],
+}
+```
+
+**Verified Capabilities:**
+- ✅ Chat completions
+- ✅ Streaming responses
+- ✅ Function calling/Tool usage
+- ✅ Structured outputs (via Instructor TOOLS_STRICT and JSON modes)
+- ✅ Native JSON mode
+
 ### Business Alignment
 
 ```python

poetry.lock

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "solana-agent"
-version = "31.4.0"
+version = "31.5.0"
 description = "AI Agents for Solana"
 authors = ["Bevan Hunt <bevan@bevanhunt.com>"]
 license = "MIT"
@@ -24,17 +24,17 @@ testpaths = ["tests"]
 
 [tool.poetry.dependencies]
 python = ">=3.12,<4.0"
-openai = "2.8.1"
+openai = "2.9.0"
 pydantic = ">=2"
-pymongo = "4.15.4"
+pymongo = "4.15.5"
 zep-cloud = "3.13.0"
 instructor = "1.13.0"
 pinecone = { version = "8.0.0", extras = ["asyncio"] }
-llama-index-core = "0.14.8"
+llama-index-core = "0.14.10"
 llama-index-embeddings-openai = "0.5.1"
 pypdf = "6.4.0"
 scrubadub = "2.0.1"
-logfire = "4.15.1"
+logfire = "4.16.0"
 typer = "0.20.0"
 rich = ">=13,<14.0"
 pillow = "12.0.0"

pyproject.toml

@@ -65,7 +65,7 @@ def __init__(
         self.api_key = api_key
         self.base_url = base_url
 
-        # Create client with base_url if provided (for Grok support)
+        # Create client with base_url if provided (for Grok/Groq support)
         if base_url:
             self.client = AsyncOpenAI(api_key=api_key, base_url=base_url)
         else:
@@ -85,9 +85,9 @@ def __init__(
                 logger.error(f"Failed to configure Logfire: {e}")
                 self.logfire = False
 
-        # Use provided model or defaults (for Grok or OpenAI)
+        # Use provided model or defaults (for Grok/Groq or OpenAI)
         if model:
-            # Custom model provided (e.g., from Grok config)
+            # Custom model provided (e.g., from Grok or Groq config)
             self.parse_model = model
             self.text_model = model
             self.vision_model = model

solana_agent/adapters/openai_adapter.py

@@ -104,8 +104,8 @@ def create_from_config(config: Dict[str, Any]) -> QueryService:  # pragma: no co
         else:
             db_adapter = None
 
-        # Determine which LLM provider to use (Grok or OpenAI)
-        # Priority: grok > openai
+        # Determine which LLM provider to use (Grok, Groq, or OpenAI)
+        # Priority: grok > groq > openai
         llm_api_key = None
         llm_base_url = None
         llm_model = None
@@ -115,13 +115,22 @@ def create_from_config(config: Dict[str, Any]) -> QueryService:  # pragma: no co
             llm_base_url = config["grok"].get("base_url", "https://api.x.ai/v1")
             llm_model = config["grok"].get("model", "grok-4-1-fast-non-reasoning")
             logger.info(f"Using Grok as LLM provider with model: {llm_model}")
+        elif "groq" in config and "api_key" in config["groq"]:
+            llm_api_key = config["groq"]["api_key"]
+            llm_base_url = config["groq"].get(
+                "base_url", "https://api.groq.com/openai/v1"
+            )
+            llm_model = config["groq"].get("model", "openai/gpt-oss-120b")
+            logger.info(f"Using Groq as LLM provider with model: {llm_model}")
         elif "openai" in config and "api_key" in config["openai"]:
             llm_api_key = config["openai"]["api_key"]
             llm_base_url = None  # Use default OpenAI endpoint
             llm_model = None  # Will use OpenAI adapter defaults
             logger.info("Using OpenAI as LLM provider")
         else:
-            raise ValueError("Either OpenAI or Grok API key is required in config.")
+            raise ValueError(
+                "Either OpenAI, Grok, or Groq API key is required in config."
+            )
 
         if "logfire" in config:
             if "api_key" not in config["logfire"]:
@@ -198,10 +207,10 @@ def create_from_config(config: Dict[str, Any]) -> QueryService:  # pragma: no co
         )
 
         # Create routing service
-        # Use Grok model if configured, otherwise check for OpenAI routing_model override
+        # Use Grok/Groq model if configured, otherwise check for OpenAI routing_model override
         routing_model = llm_model  # Use the same model as the main LLM by default
         if not routing_model:
-            # Fall back to OpenAI routing_model config if no Grok model
+            # Fall back to OpenAI routing_model config if no Grok/Groq model
             routing_model = (
                 config.get("openai", {}).get("routing_model")
                 if isinstance(config.get("openai"), dict)

solana_agent/factories/agent_factory.py

@@ -39,7 +39,7 @@ def __init__(
         if model:
             self.model = model
         elif base_url:
-            # Using custom provider (e.g., Grok) but no model specified - use provider's default
+            # Using custom provider (e.g., Grok or Groq) but no model specified - use provider's default
             self.model = None  # Will use adapter's default
         else:
             # Using OpenAI - default to small, cheap model for routing

solana_agent/services/routing.py

@@ -223,6 +223,33 @@ def grok_with_logfire_config(grok_config):
     return config
 
 
+@pytest.fixture
+def groq_config():
+    """Config with Groq as the LLM provider."""
+    return {
+        "groq": {
+            "api_key": "test-groq-key",
+            "base_url": "https://api.groq.com/openai/v1",
+            "model": "llama-3.3-70b-versatile",
+        },
+        "agents": [
+            {
+                "name": "test_agent",
+                "instructions": "You are a test agent.",
+                "specialization": "Testing",
+            }
+        ],
+    }
+
+
+@pytest.fixture
+def groq_with_logfire_config(groq_config):
+    """Config with Groq and Logfire enabled."""
+    config = deepcopy(groq_config)
+    config["logfire"] = {"api_key": "test-logfire-key"}
+    return config
+
+
 @pytest.fixture
 def invalid_logfire_config_missing_key(base_config):
     """Config with logfire section missing api_key."""
@@ -294,9 +321,10 @@ def test_create_from_config_minimal(
 
     def test_missing_openai_section(self, config_missing_openai_section):
         """Test factory creation when the entire openai section is missing."""
-        # This should raise ValueError since OpenAI or Grok API key is required
+        # This should raise ValueError since OpenAI, Grok, or Groq API key is required
         with pytest.raises(
-            ValueError, match="Either OpenAI or Grok API key is required in config."
+            ValueError,
+            match="Either OpenAI, Grok, or Groq API key is required in config.",
         ):
             SolanaAgentFactory.create_from_config(config_missing_openai_section)
 
@@ -1618,7 +1646,8 @@ def test_logfire_config_missing_openai_key(self, logfire_config_missing_openai):
         """Test handling of Logfire config when OpenAI key is missing."""
         # Based on the current factory code, this should raise a ValueError
         with pytest.raises(
-            ValueError, match="Either OpenAI or Grok API key is required in config."
+            ValueError,
+            match="Either OpenAI, Grok, or Groq API key is required in config.",
         ):
             SolanaAgentFactory.create_from_config(logfire_config_missing_openai)
 
@@ -1743,3 +1772,86 @@ def test_create_grok_without_logfire(
         mock_routing_service.assert_called_once()
         mock_query_service.assert_called_once()
         assert result == mock_query_instance
+
+    @patch("solana_agent.factories.agent_factory.MongoDBAdapter")
+    @patch("solana_agent.factories.agent_factory.OpenAIAdapter")
+    @patch("solana_agent.factories.agent_factory.AgentService")
+    @patch("solana_agent.factories.agent_factory.RoutingService")
+    @patch("solana_agent.factories.agent_factory.QueryService")
+    def test_create_groq_with_logfire(
+        self,
+        mock_query_service,
+        mock_routing_service,
+        mock_agent_service,
+        mock_openai_adapter,
+        mock_mongo_adapter,
+        groq_with_logfire_config,
+    ):
+        """Test creating services with Groq and Logfire configuration."""
+        # Setup mocks
+        mock_openai_instance = MagicMock()
+        mock_openai_adapter.return_value = mock_openai_instance
+        mock_agent_instance = MagicMock()
+        mock_agent_service.return_value = mock_agent_instance
+        mock_agent_instance.tool_registry.list_all_tools.return_value = []
+        mock_routing_instance = MagicMock()
+        mock_routing_service.return_value = mock_routing_instance
+        mock_query_instance = MagicMock()
+        mock_query_service.return_value = mock_query_instance
+
+        # Call the factory
+        result = SolanaAgentFactory.create_from_config(groq_with_logfire_config)
+
+        # Verify OpenAIAdapter was called with Groq config and logfire key
+        mock_openai_adapter.assert_called_once_with(
+            api_key="test-groq-key",
+            base_url="https://api.groq.com/openai/v1",
+            model="llama-3.3-70b-versatile",
+            logfire_api_key="test-logfire-key",
+        )
+        # Verify other services were called
+        mock_agent_service.assert_called_once()
+        mock_routing_service.assert_called_once()
+        mock_query_service.assert_called_once()
+        assert result == mock_query_instance
+
+    @patch("solana_agent.factories.agent_factory.MongoDBAdapter")
+    @patch("solana_agent.factories.agent_factory.OpenAIAdapter")
+    @patch("solana_agent.factories.agent_factory.AgentService")
+    @patch("solana_agent.factories.agent_factory.RoutingService")
+    @patch("solana_agent.factories.agent_factory.QueryService")
+    def test_create_groq_without_logfire(
+        self,
+        mock_query_service,
+        mock_routing_service,
+        mock_agent_service,
+        mock_openai_adapter,
+        mock_mongo_adapter,
+        groq_config,
+    ):
+        """Test creating services with Groq but no Logfire configuration."""
+        # Setup mocks
+        mock_openai_instance = MagicMock()
+        mock_openai_adapter.return_value = mock_openai_instance
+        mock_agent_instance = MagicMock()
+        mock_agent_service.return_value = mock_agent_instance
+        mock_agent_instance.tool_registry.list_all_tools.return_value = []
+        mock_routing_instance = MagicMock()
+        mock_routing_service.return_value = mock_routing_instance
+        mock_query_instance = MagicMock()
+        mock_query_service.return_value = mock_query_instance
+
+        # Call the factory
+        result = SolanaAgentFactory.create_from_config(groq_config)
+
+        # Verify OpenAIAdapter was called with Groq config but no logfire key
+        mock_openai_adapter.assert_called_once_with(
+            api_key="test-groq-key",
+            base_url="https://api.groq.com/openai/v1",
+            model="llama-3.3-70b-versatile",
+        )
+        # Verify other services were called
+        mock_agent_service.assert_called_once()
+        mock_routing_service.assert_called_once()
+        mock_query_service.assert_called_once()
+        assert result == mock_query_instance