solana-agent 27.4.3__tar.gz → 28.0.0__tar.gz

{solana_agent-27.4.3 → solana_agent-28.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: solana-agent
-Version: 27.4.3
+Version: 28.0.0
 Summary: AI Agents for Solana
 License: MIT
 Keywords: solana,solana ai,solana agent,ai,ai agent,ai agents
@@ -22,6 +22,7 @@ Requires-Dist: pinecone (>=6.0.2,<7.0.0)
 Requires-Dist: pydantic (>=2)
 Requires-Dist: pymongo (>=4.12.0,<5.0.0)
 Requires-Dist: pypdf (>=5.4.0,<6.0.0)
+Requires-Dist: scrubadub (>=2.0.1,<3.0.0)
 Requires-Dist: zep-cloud (>=2.10.1,<3.0.0)
 Project-URL: Documentation, https://docs.solana-agent.com
 Project-URL: Homepage, https://solana-agent.com
@@ -58,11 +59,13 @@ Build your AI agents in three lines of code!
 * Intelligent Routing
 * Business Alignment
 * Extensible Tooling
+* Automatic Tool Workflows
 * Knowledge Base
 * MCP Support
+* Guardrails
 * Tested & Secure
 * Built in Python
-* Powers [CometHeart](https://cometheart.com) & [WalletBubbles](https://walletbubbles.com)
+* Powers [CometHeart](https://cometheart.com)
 
 ## Features
 
@@ -81,26 +84,26 @@ Build your AI agents in three lines of code!
 * Powerful tool integration using standard Python packages and/or inline tools
 * Assigned tools are utilized by agents automatically and effectively
 * Integrated Knowledge Base with semantic search and automatic PDF chunking
+* Input and output guardrails for content filtering, safety, and data sanitization
+* Automatic sequential tool workflows allowing agents to chain multiple tools
 
 ## Stack
 
 ### Tech
 
 * [Python](https://python.org) - Programming Language
-* [OpenAI](https://openai.com), [Google](https://ai.google.dev), [xAI](https://x.ai) - LLM Providers
+* [OpenAI](https://openai.com) - AI Provider
 * [MongoDB](https://mongodb.com) - Conversational History (optional)
 * [Zep Cloud](https://getzep.com) - Conversational Memory (optional)
 * [Pinecone](https://pinecone.io) - Knowledge Base (optional)
 
-### LLMs
+### AI Models Used
 
-* [gpt-4.1-mini](https://platform.openai.com/docs/models/gpt-4.1-mini) (agent)
+* [gpt-4.1](https://platform.openai.com/docs/models/gpt-4.1) (agent)
 * [gpt-4.1-nano](https://platform.openai.com/docs/models/gpt-4.1-nano) (router)
 * [text-embedding-3-large](https://platform.openai.com/docs/models/text-embedding-3-large) or [text-embedding-3-small](https://platform.openai.com/docs/models/text-embedding-3-small) (embedding)
 * [tts-1](https://platform.openai.com/docs/models/tts-1) (audio TTS)
 * [gpt-4o-mini-transcribe](https://platform.openai.com/docs/models/gpt-4o-mini-transcribe) (audio transcription)
-* [gemini-2.5-flash-preview](https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview) (optional)
-* [grok-3-mini-fast-beta](https://docs.x.ai/docs/models#models-and-pricing) (optional)
 
 ## Installation
 
@@ -110,13 +113,13 @@ You can install Solana Agent using pip:
 
 ## Flows
 
-In both flows of single and multiple agents - it is one user query to one agent using one tool (if needed).
+In both flows of single and multiple agents - it is one user query to one agent using one or many tools (if needed).
 
-An agent can have multiple tools and will choose the best one to answer the user query.
+An agent can have multiple tools and will choose the best ones to fulfill the user's query.
 
-Routing is determined by optimal domain expertise of the agent for the user query.
+Routing is determined by optimal domain expertise of the agent for the user's query.
 
-When the agent uses a tool it feeds the tool output back to itself to generate the final response.
+When the agent uses tools it feeds the tools output back to itself to generate the final response.
 
 This is important as tools generally output unstructured and unformatted data that the agent needs to prepare for the user.
 
@@ -125,13 +128,13 @@ Keep this in mind while designing your agentic systems using Solana Agent.
 ```ascii
                        Single Agent                                     
                                                                         
-     ┌────────┐        ┌─────────┐        ┌────────┐                    
-     │        │        │         │        │        │                    
-     │        │        │         │        │        │                    
-     │  User  │◄──────►│  Agent  │◄──────►│  Tool  │                    
-     │        │        │         │        │        │                    
-     │        │        │         │        │        │                    
-     └────────┘        └─────────┘        └────────┘                    
+     ┌────────┐        ┌─────────┐        ┌────────-┐                    
+     │        │        │         │        │         │                    
+     │        │        │         │        │         │                    
+     │  User  │◄──────►│  Agent  │◄──────►│  Tools  │                    
+     │        │        │         │        │         │                    
+     │        │        │         │        │         │                    
+     └────────┘        └─────────┘        └────────-┘                    
                                                                         
                                                                         
                                                                         
@@ -139,13 +142,13 @@ Keep this in mind while designing your agentic systems using Solana Agent.
                                                                         
                       Multiple Agents                                   
                                                                         
-     ┌────────┐        ┌──────────┐        ┌─────────┐        ┌────────┐
-     │        │        │          │        │         │        │        │
-     │        │        │          │        │         │        │        │
-┌───►│  User  ├───────►│  Router  ├───────►│  Agent  │◄──────►│  Tool  │
-│    │        │        │          │        │         │        │        │
-│    │        │        │          │        │         │        │        │
-│    └────────┘        └──────────┘        └────┬────┘        └────────┘
+     ┌────────┐        ┌──────────┐        ┌─────────┐        ┌────────-┐
+     │        │        │          │        │         │        │         │
+     │        │        │          │        │         │        │         │
+┌───►│  User  ├───────►│  Router  ├───────►│  Agent  │◄──────►│  Tools  │
+│    │        │        │          │        │         │        │         │
+│    │        │        │          │        │         │        │         │
+│    └────────┘        └──────────┘        └────┬────┘        └────────-┘
 │                                               │                       
 │                                               │                       
 │                                               │                       
@@ -316,30 +319,6 @@ config = {
 }
 ```
 
-### Gemini
-
-This allows Gemini to replace OpenAI for agent and router.
-
-```python
-config = {
-    "gemini": {
-        "api_key": "your-gemini-api-key",
-    },
-}
-```
-
-### Grok
-
-This allows Grok to replace OpenAI (or Gemini) for agent.
-
-```python
-config = {
-    "grok": {
-        "api_key": "your-grok-api-key",
-    },
-}
-```
-
 ### Knowledge Base
 
 The Knowledge Base (KB) is meant to store text values and/or small PDFs.
@@ -448,12 +427,90 @@ async for response in solana_agent.process("user123", "Summarize the annual repo
     print(response, end="")
 ```
 
+### Guardrails
+
+Guardrails allow you to process and potentially modify user input before it reaches the agent (Input Guardrails) and agent output before it's sent back to the user (Output Guardrails). This is useful for implementing safety checks, content moderation, data sanitization, or custom transformations.
+
+Solana Agent provides a built-in PII scrubber based on [scrubadub](https://github.com/LeapBeyond/scrubadub).
+
+```python
+from solana_agent import SolanaAgent
+
+config = {
+    "guardrails": {
+        "input": [
+            # Example using a custom input guardrail
+            {
+                "class": "MyInputGuardrail",
+                "config": {"setting1": "value1"}
+            },
+            # Example using the built-in PII guardrail for input
+            {
+                "class": "solana_agent.guardrails.pii.PII",
+                "config": {
+                    "locale": "en_GB", # Optional: Specify locale (default: en_US)
+                    "replacement": "[REDACTED]" # Optional: Custom replacement format
+                }
+            }
+        ],
+        "output": [
+            # Example using a custom output guardrail
+            {
+                "class": "MyOutputGuardrail",
+                "config": {"filter_level": "high"}
+            },
+            # Example using the built-in PII guardrail for output (with defaults)
+            {
+                "class": "solana_agent.guardrails.pii.PII"
+                # No config needed to use defaults
+            }
+        ]
+    },
+}
+```
+
+#### Example Custom Guardrails
+
+```python
+from solana_agent import InputGuardrail, OutputGuardrail
+import logging
+
+logger = logging.getLogger(__name__)
+
+class MyInputGuardrail(InputGuardrail):
+    def __init__(self, config=None):
+        super().__init__(config)
+        self.setting1 = self.config.get("setting1", "default_value")
+        logger.info(f"MyInputGuardrail initialized with setting1: {self.setting1}")
+
+    async def process(self, text: str) -> str:
+        # Example: Convert input to lowercase
+        processed_text = text.lower()
+        logger.debug(f"Input Guardrail processed: {text} -> {processed_text}")
+        return processed_text
+
+class MyOutputGuardrail(OutputGuardrail):
+    def __init__(self, config=None):
+        super().__init__(config)
+        self.filter_level = self.config.get("filter_level", "low")
+        logger.info(f"MyOutputGuardrail initialized with filter_level: {self.filter_level}")
+
+    async def process(self, text: str) -> str:
+        # Example: Basic profanity filtering (replace with a real library)
+        if self.filter_level == "high" and "badword" in text:
+             processed_text = text.replace("badword", "*******")
+             logger.warning(f"Output Guardrail filtered content.")
+             return processed_text
+        logger.debug("Output Guardrail passed text through.")
+        return text
+```
+
 ## Tools
 
 Tools can be used from plugins like Solana Agent Kit (sakit) or via inline tools. Tools available via plugins integrate automatically with Solana Agent.
 
-* Agents can only call one tool per response
-* Agents choose the best tool for the job
+* Agents can use multiple tools per response and should apply the right sequential order (like send an email to bob@bob.com with the latest news on Solana)
+* Agents choose the best tools for the job
 * Solana Agent doesn't use OpenAI function calling (tools) as they don't support async functions
 * Solana Agent tools are async functions
 
@@ -528,7 +585,6 @@ Other MCP servers may work but are not supported.
 `pip install sakit`
 
 ```python
-
 from solana_agent import SolanaAgent
 
 config = {

{solana_agent-27.4.3 → solana_agent-28.0.0}/README.md

@@ -28,11 +28,13 @@ Build your AI agents in three lines of code!
 * Intelligent Routing
 * Business Alignment
 * Extensible Tooling
+* Automatic Tool Workflows
 * Knowledge Base
 * MCP Support
+* Guardrails
 * Tested & Secure
 * Built in Python
-* Powers [CometHeart](https://cometheart.com) & [WalletBubbles](https://walletbubbles.com)
+* Powers [CometHeart](https://cometheart.com)
 
 ## Features
 
@@ -51,26 +53,26 @@ Build your AI agents in three lines of code!
 * Powerful tool integration using standard Python packages and/or inline tools
 * Assigned tools are utilized by agents automatically and effectively
 * Integrated Knowledge Base with semantic search and automatic PDF chunking
+* Input and output guardrails for content filtering, safety, and data sanitization
+* Automatic sequential tool workflows allowing agents to chain multiple tools
 
 ## Stack
 
 ### Tech
 
 * [Python](https://python.org) - Programming Language
-* [OpenAI](https://openai.com), [Google](https://ai.google.dev), [xAI](https://x.ai) - LLM Providers
+* [OpenAI](https://openai.com) - AI Provider
 * [MongoDB](https://mongodb.com) - Conversational History (optional)
 * [Zep Cloud](https://getzep.com) - Conversational Memory (optional)
 * [Pinecone](https://pinecone.io) - Knowledge Base (optional)
 
-### LLMs
+### AI Models Used
 
-* [gpt-4.1-mini](https://platform.openai.com/docs/models/gpt-4.1-mini) (agent)
+* [gpt-4.1](https://platform.openai.com/docs/models/gpt-4.1) (agent)
 * [gpt-4.1-nano](https://platform.openai.com/docs/models/gpt-4.1-nano) (router)
 * [text-embedding-3-large](https://platform.openai.com/docs/models/text-embedding-3-large) or [text-embedding-3-small](https://platform.openai.com/docs/models/text-embedding-3-small) (embedding)
 * [tts-1](https://platform.openai.com/docs/models/tts-1) (audio TTS)
 * [gpt-4o-mini-transcribe](https://platform.openai.com/docs/models/gpt-4o-mini-transcribe) (audio transcription)
-* [gemini-2.5-flash-preview](https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash-preview) (optional)
-* [grok-3-mini-fast-beta](https://docs.x.ai/docs/models#models-and-pricing) (optional)
 
 ## Installation
 
@@ -80,13 +82,13 @@ You can install Solana Agent using pip:
 
 ## Flows
 
-In both flows of single and multiple agents - it is one user query to one agent using one tool (if needed).
+In both flows of single and multiple agents - it is one user query to one agent using one or many tools (if needed).
 
-An agent can have multiple tools and will choose the best one to answer the user query.
+An agent can have multiple tools and will choose the best ones to fulfill the user's query.
 
-Routing is determined by optimal domain expertise of the agent for the user query.
+Routing is determined by optimal domain expertise of the agent for the user's query.
 
-When the agent uses a tool it feeds the tool output back to itself to generate the final response.
+When the agent uses tools it feeds the tools output back to itself to generate the final response.
 
 This is important as tools generally output unstructured and unformatted data that the agent needs to prepare for the user.
 
@@ -95,13 +97,13 @@ Keep this in mind while designing your agentic systems using Solana Agent.
 ```ascii
                        Single Agent                                     
                                                                         
-     ┌────────┐        ┌─────────┐        ┌────────┐                    
-     │        │        │         │        │        │                    
-     │        │        │         │        │        │                    
-     │  User  │◄──────►│  Agent  │◄──────►│  Tool  │                    
-     │        │        │         │        │        │                    
-     │        │        │         │        │        │                    
-     └────────┘        └─────────┘        └────────┘                    
+     ┌────────┐        ┌─────────┐        ┌────────-┐                    
+     │        │        │         │        │         │                    
+     │        │        │         │        │         │                    
+     │  User  │◄──────►│  Agent  │◄──────►│  Tools  │                    
+     │        │        │         │        │         │                    
+     │        │        │         │        │         │                    
+     └────────┘        └─────────┘        └────────-┘                    
                                                                         
                                                                         
                                                                         
@@ -109,13 +111,13 @@ Keep this in mind while designing your agentic systems using Solana Agent.
                                                                         
                       Multiple Agents                                   
                                                                         
-     ┌────────┐        ┌──────────┐        ┌─────────┐        ┌────────┐
-     │        │        │          │        │         │        │        │
-     │        │        │          │        │         │        │        │
-┌───►│  User  ├───────►│  Router  ├───────►│  Agent  │◄──────►│  Tool  │
-│    │        │        │          │        │         │        │        │
-│    │        │        │          │        │         │        │        │
-│    └────────┘        └──────────┘        └────┬────┘        └────────┘
+     ┌────────┐        ┌──────────┐        ┌─────────┐        ┌────────-┐
+     │        │        │          │        │         │        │         │
+     │        │        │          │        │         │        │         │
+┌───►│  User  ├───────►│  Router  ├───────►│  Agent  │◄──────►│  Tools  │
+│    │        │        │          │        │         │        │         │
+│    │        │        │          │        │         │        │         │
+│    └────────┘        └──────────┘        └────┬────┘        └────────-┘
 │                                               │                       
 │                                               │                       
 │                                               │                       
@@ -286,30 +288,6 @@ config = {
 }
 ```
 
-### Gemini
-
-This allows Gemini to replace OpenAI for agent and router.
-
-```python
-config = {
-    "gemini": {
-        "api_key": "your-gemini-api-key",
-    },
-}
-```
-
-### Grok
-
-This allows Grok to replace OpenAI (or Gemini) for agent.
-
-```python
-config = {
-    "grok": {
-        "api_key": "your-grok-api-key",
-    },
-}
-```
-
 ### Knowledge Base
 
 The Knowledge Base (KB) is meant to store text values and/or small PDFs.
@@ -418,12 +396,90 @@ async for response in solana_agent.process("user123", "Summarize the annual repo
     print(response, end="")
 ```
 
+### Guardrails
+
+Guardrails allow you to process and potentially modify user input before it reaches the agent (Input Guardrails) and agent output before it's sent back to the user (Output Guardrails). This is useful for implementing safety checks, content moderation, data sanitization, or custom transformations.
+
+Solana Agent provides a built-in PII scrubber based on [scrubadub](https://github.com/LeapBeyond/scrubadub).
+
+```python
+from solana_agent import SolanaAgent
+
+config = {
+    "guardrails": {
+        "input": [
+            # Example using a custom input guardrail
+            {
+                "class": "MyInputGuardrail",
+                "config": {"setting1": "value1"}
+            },
+            # Example using the built-in PII guardrail for input
+            {
+                "class": "solana_agent.guardrails.pii.PII",
+                "config": {
+                    "locale": "en_GB", # Optional: Specify locale (default: en_US)
+                    "replacement": "[REDACTED]" # Optional: Custom replacement format
+                }
+            }
+        ],
+        "output": [
+            # Example using a custom output guardrail
+            {
+                "class": "MyOutputGuardrail",
+                "config": {"filter_level": "high"}
+            },
+            # Example using the built-in PII guardrail for output (with defaults)
+            {
+                "class": "solana_agent.guardrails.pii.PII"
+                # No config needed to use defaults
+            }
+        ]
+    },
+}
+```
+
+#### Example Custom Guardrails
+
+```python
+from solana_agent import InputGuardrail, OutputGuardrail
+import logging
+
+logger = logging.getLogger(__name__)
+
+class MyInputGuardrail(InputGuardrail):
+    def __init__(self, config=None):
+        super().__init__(config)
+        self.setting1 = self.config.get("setting1", "default_value")
+        logger.info(f"MyInputGuardrail initialized with setting1: {self.setting1}")
+
+    async def process(self, text: str) -> str:
+        # Example: Convert input to lowercase
+        processed_text = text.lower()
+        logger.debug(f"Input Guardrail processed: {text} -> {processed_text}")
+        return processed_text
+
+class MyOutputGuardrail(OutputGuardrail):
+    def __init__(self, config=None):
+        super().__init__(config)
+        self.filter_level = self.config.get("filter_level", "low")
+        logger.info(f"MyOutputGuardrail initialized with filter_level: {self.filter_level}")
+
+    async def process(self, text: str) -> str:
+        # Example: Basic profanity filtering (replace with a real library)
+        if self.filter_level == "high" and "badword" in text:
+             processed_text = text.replace("badword", "*******")
+             logger.warning(f"Output Guardrail filtered content.")
+             return processed_text
+        logger.debug("Output Guardrail passed text through.")
+        return text
+```
+
 ## Tools
 
 Tools can be used from plugins like Solana Agent Kit (sakit) or via inline tools. Tools available via plugins integrate automatically with Solana Agent.
 
-* Agents can only call one tool per response
-* Agents choose the best tool for the job
+* Agents can use multiple tools per response and should apply the right sequential order (like send an email to bob@bob.com with the latest news on Solana)
+* Agents choose the best tools for the job
 * Solana Agent doesn't use OpenAI function calling (tools) as they don't support async functions
 * Solana Agent tools are async functions
 
@@ -498,7 +554,6 @@ Other MCP servers may work but are not supported.
 `pip install sakit`
 
 ```python
-
 from solana_agent import SolanaAgent
 
 config = {

{solana_agent-27.4.3 → solana_agent-28.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "solana-agent"
-version = "27.4.3"
+version = "28.0.0"
 description = "AI Agents for Solana"
 authors = ["Bevan Hunt <bevan@bevanhunt.com>"]
 license = "MIT"
@@ -33,6 +33,7 @@ pinecone = "^6.0.2"
 llama-index-core = "^0.12.30"
 llama-index-embeddings-openai = "^0.3.1"
 pypdf = "^5.4.0"
+scrubadub = "^2.0.1"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.3.5"

{solana_agent-27.4.3 → solana_agent-28.0.0}/solana_agent/__init__.py

@@ -5,8 +5,6 @@ This package provides a modular framework for building AI agent systems with
 multiple specialized agents, memory management, and conversation routing.
 """
 
-__version__ = "14.0.0"  # Update with your actual version
-
 # Client interface (main entry point)
 from solana_agent.client.solana_agent import SolanaAgent
 
@@ -17,6 +15,10 @@ from solana_agent.factories.agent_factory import SolanaAgentFactory
 from solana_agent.plugins.manager import PluginManager
 from solana_agent.plugins.registry import ToolRegistry
 from solana_agent.plugins.tools.auto_tool import AutoTool
+from solana_agent.interfaces.guardrails.guardrails import (
+    InputGuardrail,
+    OutputGuardrail,
+)
 
 # Package metadata
 __all__ = [
@@ -28,4 +30,7 @@ __all__ = [
     "PluginManager",
     "ToolRegistry",
     "AutoTool",
+    # Guardrails
+    "InputGuardrail",
+    "OutputGuardrail",
 ]

{solana_agent-27.4.3 → solana_agent-28.0.0}/solana_agent/adapters/openai_adapter.py

@@ -15,7 +15,7 @@ from solana_agent.interfaces.providers.llm import LLMProvider
 
 T = TypeVar("T", bound=BaseModel)
 
-DEFAULT_CHAT_MODEL = "gpt-4.1-mini"
+DEFAULT_CHAT_MODEL = "gpt-4.1"
 DEFAULT_PARSE_MODEL = "gpt-4.1-nano"
 DEFAULT_EMBEDDING_MODEL = "text-embedding-3-large"
 DEFAULT_EMBEDDING_DIMENSIONS = 3072
@@ -129,45 +129,41 @@ class OpenAIAdapter(LLMProvider):
         api_key: Optional[str] = None,
         base_url: Optional[str] = None,
         model: Optional[str] = None,
-    ) -> AsyncGenerator[str, None]:  # pragma: no cover
-        """Generate text from OpenAI models."""
+    ) -> str:  # pragma: no cover
+        """Generate text from OpenAI models as a single string."""
         messages = []
-
         if system_prompt:
             messages.append({"role": "system", "content": system_prompt})
-
         messages.append({"role": "user", "content": prompt})
 
-        # Prepare request parameters
+        # Prepare request parameters - stream is always False now
         request_params = {
             "messages": messages,
-            "stream": True,
-            "model": self.text_model,
+            "stream": False,  # Hardcoded to False
+            "model": model or self.text_model,
         }
 
+        # Determine client based on provided api_key/base_url
         if api_key and base_url:
             client = AsyncOpenAI(api_key=api_key, base_url=base_url)
         else:
             client = self.client
 
-        if model:
-            request_params["model"] = model
-
         try:
+            # Make the non-streaming API call
             response = await client.chat.completions.create(**request_params)
 
-            async for chunk in response:
-                if chunk.choices:
-                    if chunk.choices[0].delta.content:
-                        text = chunk.choices[0].delta.content
-                        yield text
+            # Handle non-streaming response
+            if response.choices and response.choices[0].message.content:
+                full_text = response.choices[0].message.content
+                return full_text  # Return the complete string
+            else:
+                print("Received non-streaming response with no content.")
+                return ""  # Return empty string if no content
 
         except Exception as e:
-            print(f"Error in generate_text: {str(e)}")
-            import traceback
-
-            print(traceback.format_exc())
-            yield f"I apologize, but I encountered an error: {str(e)}"
+            # Log the error and return an error message string
+            print(f"Error in generate_text: {e}")
 
     async def parse_structured_output(
         self,