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

solana_agent/services/query.py

@@ -6,16 +6,29 @@ other services to provide comprehensive responses while maintaining
 clean separation of concerns.
 """
 
-from typing import Any, AsyncGenerator, Dict, Literal, Optional, Union
+import logging
+from typing import Any, AsyncGenerator, Dict, List, Literal, Optional, Union
 
+# Interface imports
 from solana_agent.interfaces.services.query import QueryService as QueryServiceInterface
 from solana_agent.interfaces.services.routing import (
     RoutingService as RoutingServiceInterface,
 )
+from solana_agent.interfaces.providers.memory import (
+    MemoryProvider as MemoryProviderInterface,
+)
+from solana_agent.interfaces.services.knowledge_base import (
+    KnowledgeBaseService as KnowledgeBaseInterface,
+)
+from solana_agent.interfaces.guardrails.guardrails import (
+    InputGuardrail,
+)  # <-- Import InputGuardrail
+
+# Service imports (assuming AgentService is the concrete implementation)
 from solana_agent.services.agent import AgentService
 from solana_agent.services.routing import RoutingService
-from solana_agent.services.knowledge_base import KnowledgeBaseService
-from solana_agent.interfaces.providers.memory import MemoryProvider
+
+logger = logging.getLogger(__name__)
 
 
 class QueryService(QueryServiceInterface):
@@ -25,9 +38,10 @@ class QueryService(QueryServiceInterface):
         self,
         agent_service: AgentService,
         routing_service: RoutingService,
-        memory_provider: Optional[MemoryProvider] = None,
-        knowledge_base: Optional[KnowledgeBaseService] = None,
+        memory_provider: Optional[MemoryProviderInterface] = None,
+        knowledge_base: Optional[KnowledgeBaseInterface] = None,
         kb_results_count: int = 3,
+        input_guardrails: List[InputGuardrail] = None,
     ):
         """Initialize the query service.
 
@@ -35,12 +49,16 @@ class QueryService(QueryServiceInterface):
             agent_service: Service for AI agent management
             routing_service: Service for routing queries to appropriate agents
             memory_provider: Optional provider for memory storage and retrieval
+            knowledge_base: Optional provider for knowledge base interactions
+            kb_results_count: Number of results to retrieve from knowledge base
+            input_guardrails: List of input guardrail instances
         """
         self.agent_service = agent_service
         self.routing_service = routing_service
         self.memory_provider = memory_provider
         self.knowledge_base = knowledge_base
         self.kb_results_count = kb_results_count
+        self.input_guardrails = input_guardrails or []  # <-- Store guardrails
 
     async def process(
         self,
@@ -69,7 +87,7 @@ class QueryService(QueryServiceInterface):
         prompt: Optional[str] = None,
         router: Optional[RoutingServiceInterface] = None,
     ) -> AsyncGenerator[Union[str, bytes], None]:  # pragma: no cover
-        """Process the user request with appropriate agent.
+        """Process the user request with appropriate agent and apply input guardrails.
 
         Args:
             user_id: User ID
@@ -86,21 +104,48 @@ class QueryService(QueryServiceInterface):
             Response chunks (text strings or audio bytes)
         """
         try:
-            # Handle audio input if provided
+            # --- 1. Handle Audio Input & Extract Text ---
             user_text = ""
             if not isinstance(query, str):
+                logger.info(
+                    f"Received audio input, transcribing format: {audio_input_format}"
+                )
                 async for (
                     transcript
                 ) in self.agent_service.llm_provider.transcribe_audio(
                     query, audio_input_format
                 ):
                     user_text += transcript
+                logger.info(f"Transcription result length: {len(user_text)}")
             else:
                 user_text = query
+                logger.info(f"Received text input length: {len(user_text)}")
+
+            # --- 2. Apply Input Guardrails ---
+            original_text = user_text
+            processed_text = user_text
+            for guardrail in self.input_guardrails:
+                try:
+                    processed_text = await guardrail.process(processed_text)
+                    logger.debug(
+                        f"Applied input guardrail: {guardrail.__class__.__name__}"
+                    )
+                except Exception as e:
+                    logger.error(
+                        f"Error applying input guardrail {guardrail.__class__.__name__}: {e}",
+                        exc_info=True,
+                    )
+            if processed_text != original_text:
+                logger.info(
+                    f"Input guardrails modified user text. Original length: {len(original_text)}, New length: {len(processed_text)}"
+                )
+            user_text = processed_text  # Use the processed text going forward
+            # --- End Apply Input Guardrails ---
 
-            # Handle simple greetings
+            # --- 3. Handle Simple Greetings ---
             if user_text.strip().lower() in ["test", "hello", "hi", "hey", "ping"]:
                 response = "Hello! How can I help you today?"
+                logger.info("Handling simple greeting.")
                 if output_format == "audio":
                     async for chunk in self.agent_service.llm_provider.tts(
                         text=response,
@@ -112,25 +157,32 @@ class QueryService(QueryServiceInterface):
                 else:
                     yield response
 
-                # Store simple interaction in memory
+                # Store simple interaction in memory (using processed user_text)
                 if self.memory_provider:
                     await self._store_conversation(user_id, user_text, response)
                 return
 
-            # Get memory context if available
+            # --- 4. Get Memory Context ---
             memory_context = ""
             if self.memory_provider:
-                memory_context = await self.memory_provider.retrieve(user_id)
+                try:
+                    memory_context = await self.memory_provider.retrieve(user_id)
+                    logger.info(
+                        f"Retrieved memory context length: {len(memory_context)}"
+                    )
+                except Exception as e:
+                    logger.error(f"Error retrieving memory context: {e}", exc_info=True)
 
-            # Retrieve relevant knowledge from the KB
+            # --- 5. Retrieve Relevant Knowledge ---
             kb_context = ""
             if self.knowledge_base:
                 try:
+                    # Use processed user_text for KB query
                     kb_results = await self.knowledge_base.query(
                         query_text=user_text,
                         top_k=self.kb_results_count,
                         include_content=True,
-                        include_metadata=False,
+                        include_metadata=False,  # Keep metadata minimal for context
                     )
 
                     if kb_results:
@@ -138,36 +190,47 @@ class QueryService(QueryServiceInterface):
                         for i, result in enumerate(kb_results, 1):
                             content = result.get("content", "").strip()
                             kb_context += f"[{i}] {content}\n\n"
+                        logger.info(
+                            f"Retrieved {len(kb_results)} results from Knowledge Base."
+                        )
+                    else:
+                        logger.info("No relevant results found in Knowledge Base.")
                 except Exception as e:
-                    print(f"Error retrieving knowledge: {e}")
+                    logger.error(f"Error retrieving knowledge: {e}", exc_info=True)
 
-            # Route query to appropriate agent
-            if router:
-                agent_name = await router.route_query(user_text)
-            else:
-                agent_name = await self.routing_service.route_query(user_text)
+            # --- 6. Route Query ---
+            agent_name = "default"  # Fallback agent
+            try:
+                # Use processed user_text for routing
+                if router:
+                    agent_name = await router.route_query(user_text)
+                else:
+                    agent_name = await self.routing_service.route_query(user_text)
+                logger.info(f"Routed query to agent: {agent_name}")
+            except Exception as e:
+                logger.error(
+                    f"Error during routing, falling back to default agent: {e}",
+                    exc_info=True,
+                )
 
-            # Combine context from memory and knowledge base
+            # --- 7. Combine Context ---
             combined_context = ""
             if memory_context:
-                # Add a note about memory priority
                 combined_context += f"CONVERSATION HISTORY (Use for context, but prioritize tools/KB for facts):\n{memory_context}\n\n"
             if kb_context:
-                # Keep KB context strong
                 combined_context += f"{kb_context}\n"
 
-            # Add an overall instruction about prioritization if both are present
             if memory_context or kb_context:
                 combined_context += "CRITICAL PRIORITIZATION GUIDE: For factual or current information, prioritize Knowledge Base results and Tool results (if applicable) over Conversation History.\n\n"
+            logger.debug(f"Combined context length: {len(combined_context)}")
 
-            print(f"Routed to agent: {agent_name}")
-
-            # Generate response
+            # --- 8. Generate Response ---
+            # Pass the processed user_text to the agent service
             if output_format == "audio":
                 async for audio_chunk in self.agent_service.generate_response(
                     agent_name=agent_name,
                     user_id=user_id,
-                    query=user_text,
+                    query=user_text,  # Pass processed text
                     memory_context=combined_context,
                     output_format="audio",
                     audio_voice=audio_voice,
@@ -177,6 +240,7 @@ class QueryService(QueryServiceInterface):
                 ):
                     yield audio_chunk
 
+                # Store conversation using processed user_text
                 if self.memory_provider:
                     await self._store_conversation(
                         user_id=user_id,
@@ -188,7 +252,7 @@ class QueryService(QueryServiceInterface):
                 async for chunk in self.agent_service.generate_response(
                     agent_name=agent_name,
                     user_id=user_id,
-                    query=user_text,
+                    query=user_text,  # Pass processed text
                     memory_context=combined_context,
                     output_format="text",
                     prompt=prompt,
@@ -196,6 +260,7 @@ class QueryService(QueryServiceInterface):
                     yield chunk
                     full_text_response += chunk
 
+                # Store conversation using processed user_text
                 if self.memory_provider and full_text_response:
                     await self._store_conversation(
                         user_id=user_id,
@@ -204,22 +269,28 @@ class QueryService(QueryServiceInterface):
                     )
 
         except Exception as e:
-            error_msg = f"I apologize for the technical difficulty. {str(e)}"
+            import traceback
+
+            error_msg = (
+                "I apologize for the technical difficulty. Please try again later."
+            )
+            logger.error(f"Error in query processing: {e}\n{traceback.format_exc()}")
+
             if output_format == "audio":
-                async for chunk in self.agent_service.llm_provider.tts(
-                    text=error_msg,
-                    voice=audio_voice,
-                    response_format=audio_output_format,
-                ):
-                    yield chunk
+                try:
+                    async for chunk in self.agent_service.llm_provider.tts(
+                        text=error_msg,
+                        voice=audio_voice,
+                        response_format=audio_output_format,
+                    ):
+                        yield chunk
+                except Exception as tts_e:
+                    logger.error(f"Error during TTS for error message: {tts_e}")
+                    # Fallback to yielding text error if TTS fails
+                    yield error_msg + f" (TTS Error: {tts_e})"
             else:
                 yield error_msg
 
-            print(f"Error in query processing: {str(e)}")
-            import traceback
-
-            print(traceback.format_exc())
-
     async def delete_user_history(self, user_id: str) -> None:
         """Delete all conversation history for a user.
 
@@ -229,8 +300,15 @@ class QueryService(QueryServiceInterface):
         if self.memory_provider:
             try:
                 await self.memory_provider.delete(user_id)
+                logger.info(f"Deleted conversation history for user: {user_id}")
             except Exception as e:
-                print(f"Error deleting user history: {str(e)}")
+                logger.error(
+                    f"Error deleting user history for {user_id}: {e}", exc_info=True
+                )
+        else:
+            logger.warning(
+                "Attempted to delete user history, but no memory provider is configured."
+            )
 
     async def get_user_history(
         self,
@@ -248,17 +326,12 @@ class QueryService(QueryServiceInterface):
             sort_order: Sort order ("asc" or "desc")
 
         Returns:
-            Dictionary with paginated results and metadata:
-            {
-                "data": List of conversation entries,
-                "total": Total number of entries,
-                "page": Current page number,
-                "page_size": Number of items per page,
-                "total_pages": Total number of pages,
-                "error": Error message if any
-            }
+            Dictionary with paginated results and metadata.
         """
         if not self.memory_provider:
+            logger.warning(
+                "Attempted to get user history, but no memory provider is configured."
+            )
             return {
                 "data": [],
                 "total": 0,
@@ -278,7 +351,7 @@ class QueryService(QueryServiceInterface):
             )
 
             # Calculate total pages
-            total_pages = (total + page_size - 1) // page_size
+            total_pages = (total + page_size - 1) // page_size if total > 0 else 0
 
             # Get paginated results
             conversations = self.memory_provider.find(
@@ -292,13 +365,11 @@ class QueryService(QueryServiceInterface):
             # Format the results
             formatted_conversations = []
             for conv in conversations:
-                # Convert datetime to Unix timestamp (seconds since epoch)
                 timestamp = (
                     int(conv.get("timestamp").timestamp())
                     if conv.get("timestamp")
                     else None
                 )
-
                 formatted_conversations.append(
                     {
                         "id": str(conv.get("_id")),
@@ -308,6 +379,9 @@ class QueryService(QueryServiceInterface):
                     }
                 )
 
+            logger.info(
+                f"Retrieved page {page_num}/{total_pages} of history for user {user_id}"
+            )
             return {
                 "data": formatted_conversations,
                 "total": total,
@@ -318,10 +392,11 @@ class QueryService(QueryServiceInterface):
             }
 
         except Exception as e:
-            print(f"Error retrieving user history: {str(e)}")
             import traceback
 
-            print(traceback.format_exc())
+            logger.error(
+                f"Error retrieving user history for {user_id}: {e}\n{traceback.format_exc()}"
+            )
             return {
                 "data": [],
                 "total": 0,
@@ -338,8 +413,8 @@ class QueryService(QueryServiceInterface):
 
         Args:
             user_id: User ID
-            user_message: User message
-            assistant_message: Assistant message
+            user_message: User message (potentially processed by input guardrails)
+            assistant_message: Assistant message (potentially processed by output guardrails)
         """
         if self.memory_provider:
             try:
@@ -350,5 +425,12 @@ class QueryService(QueryServiceInterface):
                         {"role": "assistant", "content": assistant_message},
                     ],
                 )
+                logger.info(f"Stored conversation for user {user_id}")
             except Exception as e:
-                print(f"Error storing conversation: {e}")
+                logger.error(
+                    f"Error storing conversation for user {user_id}: {e}", exc_info=True
+                )
+        else:
+            logger.debug(
+                "Memory provider not configured, skipping conversation storage."
+            )

{solana_agent-27.4.3.dist-info → solana_agent-27.5.0.dist-info}/METADATA

@@ -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.dist-info → solana_agent-27.5.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-solana_agent/__init__.py,sha256=s_Dq2yqss83jp9DnHgXsxjpf9HWGRmRW2EwqroH0XKk,895
+solana_agent/__init__.py,sha256=g83qhMOCwcWL19V4CYbQwl0Ykpb0xn49OUh05i-pu3g,1001
 solana_agent/adapters/__init__.py,sha256=tiEEuuy0NF3ngc_tGEcRTt71zVI58v3dYY9RvMrF2Cg,204
 solana_agent/adapters/mongodb_adapter.py,sha256=0KWIa6kaFbUFvtKUzuV_0p0RFlPPGKrDVIEU2McVY3k,2734
 solana_agent/adapters/openai_adapter.py,sha256=NZ35mJ80yVWTbdQOAYUh7hDzOFclgfdeJ1Z8v_gfQG8,10922
@@ -9,9 +9,11 @@ solana_agent/domains/__init__.py,sha256=HiC94wVPRy-QDJSSRywCRrhrFfTBeHjfi5z-QfZv
 solana_agent/domains/agent.py,sha256=3Q1wg4eIul0CPpaYBOjEthKTfcdhf1SAiWc2R-IMGO8,2561
 solana_agent/domains/routing.py,sha256=1yR4IswGcmREGgbOOI6TKCfuM7gYGOhQjLkBqnZ-rNo,582
 solana_agent/factories/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-solana_agent/factories/agent_factory.py,sha256=y11a_OiaoWUF-xxjyVkwu6yxIo0zYq8amd3de63INq8,11729
+solana_agent/factories/agent_factory.py,sha256=AsQTS2aMvt25OiQUyYsmIVsp3VLqBbnxD58qcpJ2Urk,14115
+solana_agent/guardrails/pii.py,sha256=FCz1IC3mmkr41QFFf5NaC0fwJrVkwFsxgyOCS2POO5I,4428
 solana_agent/interfaces/__init__.py,sha256=IQs1WIM1FeKP1-kY2FEfyhol_dB-I-VAe2rD6jrVF6k,355
 solana_agent/interfaces/client/client.py,sha256=hsvaQiQdz3MLMNc77oD6ocvvnyl7Ez2n087ptFDA19M,3687
+solana_agent/interfaces/guardrails/guardrails.py,sha256=gZCQ1FrirW-mX6s7FoYrbRs6golsp-x269kk4kQiZzc,572
 solana_agent/interfaces/plugins/plugins.py,sha256=Rz52cWBLdotwf4kV-2mC79tRYlN29zHSu1z9-y1HVPk,3329
 solana_agent/interfaces/providers/data_storage.py,sha256=Y92Cq8BtC55VlsYLD7bo3ofqQabNnlg7Q4H1Q6CDsLU,1713
 solana_agent/interfaces/providers/llm.py,sha256=SPCXsnCXj7p04E24xB0Wj1q36h2Ci4mmcNCkpHGS8LY,2417
@@ -29,11 +31,11 @@ solana_agent/plugins/tools/auto_tool.py,sha256=uihijtlc9CCqCIaRcwPuuN7o1SHIpWL2G
 solana_agent/repositories/__init__.py,sha256=fP83w83CGzXLnSdq-C5wbw9EhWTYtqE2lQTgp46-X_4,163
 solana_agent/repositories/memory.py,sha256=YYpCyiDVi3a5ZOFYFkzBS6MDjo9g2TnwbEZ5KKfKbII,7204
 solana_agent/services/__init__.py,sha256=iko0c2MlF8b_SA_nuBGFllr2E3g_JowOrOzGcnU9tkA,162
-solana_agent/services/agent.py,sha256=2ngtuJucGsEyNPKaWu4axd1pPgKofY-H8FeSY-MPBCU,27229
+solana_agent/services/agent.py,sha256=7JRI8TcZVoVCDeIeGY9el-ingL-lRPrOneJO1uQmWFQ,35652
 solana_agent/services/knowledge_base.py,sha256=J9V8dNoCCcko3EasiGwK2JJ_A_oG_e-Ni9pgNg0T6wA,33486
-solana_agent/services/query.py,sha256=J81IGpy_1xsHFR3tEQkNDNoLcX9mFBJBrUcXz0pTW2w,13279
+solana_agent/services/query.py,sha256=bAoUfe_2EBVEVeh99-2E9KZ0zaHUzf7Lqel3rlHyNX8,17459
 solana_agent/services/routing.py,sha256=-0fNIKDtCn0-TLUYDFYAE4jPLMeI_jCXIpgtgWDpdf8,6986
-solana_agent-27.4.3.dist-info/LICENSE,sha256=BnSRc-NSFuyF2s496l_4EyrwAP6YimvxWcjPiJ0J7g4,1057
-solana_agent-27.4.3.dist-info/METADATA,sha256=SjhvTRk-hLUT6lwnANex4Wlz2I5PjfPbAewpJOGASes,23994
-solana_agent-27.4.3.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
-solana_agent-27.4.3.dist-info/RECORD,,
+solana_agent-27.5.0.dist-info/LICENSE,sha256=BnSRc-NSFuyF2s496l_4EyrwAP6YimvxWcjPiJ0J7g4,1057
+solana_agent-27.5.0.dist-info/METADATA,sha256=3hSaou5hzrEL1jowM6_KsofHg_VnMFnbNf7ORPGFJUM,26977
+solana_agent-27.5.0.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+solana_agent-27.5.0.dist-info/RECORD,,