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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: solana-agent
-Version: 27.4.3
+Version: 27.5.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
@@ -60,9 +61,10 @@ Build your AI agents in three lines of code!
 * Extensible Tooling
 * 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,6 +83,7 @@ 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
 
 ## Stack
 
@@ -448,6 +451,84 @@ 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.
@@ -528,7 +609,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-27.5.0}/README.md

@@ -30,9 +30,10 @@ Build your AI agents in three lines of code!
 * Extensible Tooling
 * 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,6 +52,7 @@ 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
 
 ## Stack
 
@@ -418,6 +420,84 @@ 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.
@@ -498,7 +578,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-27.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "solana-agent"
-version = "27.4.3"
+version = "27.5.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-27.5.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-27.5.0}/solana_agent/factories/agent_factory.py

@@ -5,10 +5,15 @@ This module handles the creation and dependency injection for all
 services and components used in the system.
 """
 
-from typing import Dict, Any
+import importlib
+from typing import Dict, Any, List
 
 # Service imports
 from solana_agent.adapters.pinecone_adapter import PineconeAdapter
+from solana_agent.interfaces.guardrails.guardrails import (
+    InputGuardrail,
+    OutputGuardrail,
+)
 from solana_agent.services.query import QueryService
 from solana_agent.services.agent import AgentService
 from solana_agent.services.routing import RoutingService
@@ -29,6 +34,37 @@ from solana_agent.plugins.manager import PluginManager
 class SolanaAgentFactory:
     """Factory for creating and wiring components of the Solana Agent system."""
 
+    @staticmethod
+    def _create_guardrails(guardrail_configs: List[Dict[str, Any]]) -> List[Any]:
+        """Instantiates guardrails from configuration."""
+        guardrails = []
+        if not guardrail_configs:
+            return guardrails
+
+        for config in guardrail_configs:
+            class_path = config.get("class")
+            guardrail_config = config.get("config", {})
+            if not class_path:
+                print(f"Guardrail config missing 'class': {config}")
+                continue
+            try:
+                module_path, class_name = class_path.rsplit(".", 1)
+                module = importlib.import_module(module_path)
+                guardrail_class = getattr(module, class_name)
+                # Instantiate the guardrail, handling potential errors during init
+                try:
+                    guardrails.append(guardrail_class(config=guardrail_config))
+                    print(f"Successfully loaded guardrail: {class_path}")
+                except Exception as init_e:
+                    print(f"Error initializing guardrail '{class_path}': {init_e}")
+                    # Optionally re-raise or just skip this guardrail
+
+            except (ImportError, AttributeError, ValueError) as e:
+                print(f"Error loading guardrail class '{class_path}': {e}")
+            except Exception as e:  # Catch unexpected errors during import/getattr
+                print(f"Unexpected error loading guardrail '{class_path}': {e}")
+        return guardrails
+
     @staticmethod
     def create_from_config(config: Dict[str, Any]) -> QueryService:
         """Create the agent system from configuration.
@@ -83,6 +119,17 @@ class SolanaAgentFactory:
                 raise ValueError("Zep API key is required.")
             memory_provider = MemoryRepository(zep_api_key=config["zep"].get("api_key"))
 
+        guardrail_config = config.get("guardrails", {})
+        input_guardrails: List[InputGuardrail] = SolanaAgentFactory._create_guardrails(
+            guardrail_config.get("input", [])
+        )
+        output_guardrails: List[OutputGuardrail] = (
+            SolanaAgentFactory._create_guardrails(guardrail_config.get("output", []))
+        )
+        print(
+            f"Loaded {len(input_guardrails)} input guardrails and {len(output_guardrails)} output guardrails."
+        )
+
         if (
             "gemini" in config
             and "api_key" in config["gemini"]
@@ -96,6 +143,7 @@ class SolanaAgentFactory:
                 api_key=config["gemini"]["api_key"],
                 base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
                 model="gemini-2.5-flash-preview-04-17",
+                output_guardrails=output_guardrails,
             )
 
             # Create routing service
@@ -121,6 +169,7 @@ class SolanaAgentFactory:
                 api_key=config["grok"]["api_key"],
                 base_url="https://api.x.ai/v1",
                 model="grok-3-mini-fast-beta",
+                output_guardrails=output_guardrails,
             )
             # Create routing service
             routing_service = RoutingService(
@@ -142,6 +191,7 @@ class SolanaAgentFactory:
                 api_key=config["grok"]["api_key"],
                 base_url="https://api.x.ai/v1",
                 model="grok-3-mini-fast-beta",
+                output_guardrails=output_guardrails,
             )
 
             # Create routing service
@@ -156,6 +206,7 @@ class SolanaAgentFactory:
                 llm_provider=llm_adapter,
                 business_mission=business_mission,
                 config=config,
+                output_guardrails=output_guardrails,
             )
 
             # Create routing service
@@ -284,6 +335,7 @@ class SolanaAgentFactory:
             memory_provider=memory_provider,
             knowledge_base=knowledge_base,  # Pass the potentially created KB
             kb_results_count=kb_config.get("results_count", 3) if kb_config else 3,
+            input_guardrails=input_guardrails,
         )
 
         return query_service

solana_agent-27.5.0/solana_agent/guardrails/pii.py

@@ -0,0 +1,107 @@
+import logging
+from typing import Dict, Any, Optional, List
+import scrubadub
+from solana_agent.interfaces.guardrails.guardrails import (
+    InputGuardrail,
+    OutputGuardrail,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class PII(InputGuardrail, OutputGuardrail):
+    """
+    A guardrail using Scrubadub to detect and remove PII.
+
+    Requires 'scrubadub'. Install with: pip install solana-agent[guardrails]
+    """
+
+    DEFAULT_REPLACEMENT = "[REDACTED_{detector_name}]"
+    DEFAULT_LANG = "en_US"  # Scrubadub uses locale format
+
+    def __init__(self, config: Dict[str, Any] = None):
+        super().__init__(config)
+        self.replacement_format = self.config.get(
+            "replacement", self.DEFAULT_REPLACEMENT
+        )
+        self.locale = self.config.get("locale", self.DEFAULT_LANG)
+        # Optional: Specify detectors to use, None uses defaults
+        self.detector_list: Optional[List[str]] = self.config.get("detectors")
+        # Optional: Add custom detectors if needed via config
+        self.extra_detector_list = self.config.get(
+            "extra_detectors", []
+        )  # List of detector classes/instances
+
+        try:
+            # Initialize Scrubber
+            # Note: detector_list expects instances, not names. Need mapping or direct instantiation if customizing.
+            # For simplicity, we'll use defaults or allow passing instances via config (advanced).
+            # Using default detectors if self.detector_list is None.
+            if self.detector_list is not None:
+                logger.warning(
+                    "Customizing 'detectors' by name list is not directly supported here yet. Using defaults."
+                )
+                # TODO: Add logic to map names to detector classes if needed.
+                self.scrubber = scrubadub.Scrubber(locale=self.locale)
+            else:
+                self.scrubber = scrubadub.Scrubber(locale=self.locale)
+
+            # Add any extra detectors passed via config (e.g., custom regex detectors)
+            for detector in self.extra_detector_list:
+                # Assuming extra_detectors are already instantiated objects
+                # Or add logic here to instantiate them based on class paths/names
+                if isinstance(detector, scrubadub.detectors.Detector):
+                    self.scrubber.add_detector(detector)
+                else:
+                    logger.warning(f"Invalid item in extra_detectors: {detector}")
+
+            logger.info(f"ScrubadubPIIFilter initialized for locale '{self.locale}'")
+
+        except ImportError:
+            logger.error(
+                "Scrubadub not installed. Please install with 'pip install solana-agent[guardrails]'"
+            )
+            raise
+        except Exception as e:
+            logger.error(f"Failed to initialize Scrubadub: {e}", exc_info=True)
+            raise
+
+    async def process(self, text: str) -> str:
+        """Clean text using Scrubadub."""
+        try:
+            # Scrubadub's clean method handles the replacement logic.
+            # We need to customize the replacement format per detector.
+            # This requires iterating through filth found first.
+
+            clean_text = text
+            filth_list = list(self.scrubber.iter_filth(text))  # Get all findings
+
+            if not filth_list:
+                return text
+
+            # Sort by start index to handle replacements correctly
+            filth_list.sort(key=lambda f: f.beg)
+
+            offset = 0
+            for filth in filth_list:
+                start = filth.beg + offset
+                end = filth.end + offset
+                replacement_text = self.replacement_format.format(
+                    detector_name=filth.detector_name,
+                    text=filth.text,
+                    locale=filth.locale,
+                    # Add other filth attributes if needed in format string
+                )
+
+                clean_text = clean_text[:start] + replacement_text + clean_text[end:]
+                offset += len(replacement_text) - (filth.end - filth.beg)
+
+            if clean_text != text:
+                logger.debug(
+                    f"ScrubadubPIIFilter redacted {len(filth_list)} pieces of filth."
+                )
+            return clean_text
+
+        except Exception as e:
+            logger.error(f"Error during Scrubadub cleaning: {e}", exc_info=True)
+            return text  # Return original text on error

solana_agent-27.5.0/solana_agent/interfaces/guardrails/guardrails.py

@@ -0,0 +1,26 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+
+class Guardrail(ABC):
+    """Base class for all guardrails."""
+
+    def __init__(self, config: Dict[str, Any] = None):
+        self.config = config or {}
+
+    @abstractmethod
+    async def process(self, text: str) -> str:
+        """Process the text and return the modified text."""
+        pass
+
+
+class InputGuardrail(Guardrail):
+    """Interface for guardrails applied to user input."""
+
+    pass
+
+
+class OutputGuardrail(Guardrail):
+    """Interface for guardrails applied to agent output."""
+
+    pass