solana-agent 27.4.3__py3-none-any.whl → 27.5.0__py3-none-any.whl

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/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/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/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