solana-agent 20.1.2__py3-none-any.whl → 31.4.0__py3-none-any.whl

solana_agent/factories/agent_factory.py

@@ -4,30 +4,84 @@ Factory for creating and wiring components of the Solana Agent system.
 This module handles the creation and dependency injection for all
 services and components used in the system.
 """
-from typing import Dict, Any
+
+import importlib
+import logging
+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
+from solana_agent.services.knowledge_base import KnowledgeBaseService
+# Realtime is now managed per-call in QueryService.process; no factory wiring
 
 # Repository imports
 from solana_agent.repositories.memory import MemoryRepository
 
 # Adapter imports
-from solana_agent.adapters.llm_adapter import OpenAIAdapter
+from solana_agent.adapters.openai_adapter import OpenAIAdapter
 from solana_agent.adapters.mongodb_adapter import MongoDBAdapter
 
 # Domain and plugin imports
 from solana_agent.domains.agent import BusinessMission
 from solana_agent.plugins.manager import PluginManager
 
+# Setup logger for this module
+logger = logging.getLogger(__name__)
+
 
 class SolanaAgentFactory:
     """Factory for creating and wiring components of the Solana Agent system."""
 
     @staticmethod
-    def create_from_config(config: Dict[str, Any]) -> QueryService:
+    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:
+                logger.warning(
+                    f"Guardrail config missing 'class': {config}"
+                )  # Use logger.warning
+                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))
+                    logger.info(
+                        f"Successfully loaded guardrail: {class_path}"
+                    )  # Use logger.info
+                except Exception as init_e:
+                    logger.error(
+                        f"Error initializing guardrail '{class_path}': {init_e}"
+                    )  # Use logger.error
+                    # Optionally re-raise or just skip this guardrail
+
+            except (ImportError, AttributeError, ValueError) as e:
+                logger.error(
+                    f"Error loading guardrail class '{class_path}': {e}"
+                )  # Use logger.error
+            except Exception as e:  # Catch unexpected errors during import/getattr
+                logger.exception(
+                    f"Unexpected error loading guardrail '{class_path}': {e}"
+                )  # Use logger.exception
+        return guardrails
+
+    @staticmethod
+    def create_from_config(config: Dict[str, Any]) -> QueryService:  # pragma: no cover
         """Create the agent system from configuration.
 
         Args:
@@ -39,7 +93,6 @@ class SolanaAgentFactory:
         # Create adapters
 
         if "mongo" in config:
-            # MongoDB connection string and database name
             if "connection_string" not in config["mongo"]:
                 raise ValueError("MongoDB connection string is required.")
             if "database" not in config["mongo"]:
@@ -51,9 +104,40 @@ class SolanaAgentFactory:
         else:
             db_adapter = None
 
-        llm_adapter = OpenAIAdapter(
-            api_key=config["openai"]["api_key"],
-        )
+        # Determine which LLM provider to use (Grok or OpenAI)
+        # Priority: grok > openai
+        llm_api_key = None
+        llm_base_url = None
+        llm_model = None
+
+        if "grok" in config and "api_key" in config["grok"]:
+            llm_api_key = config["grok"]["api_key"]
+            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 "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.")
+
+        if "logfire" in config:
+            if "api_key" not in config["logfire"]:
+                raise ValueError("Pydantic Logfire API key is required.")
+            llm_adapter = OpenAIAdapter(
+                api_key=llm_api_key,
+                base_url=llm_base_url,
+                model=llm_model,
+                logfire_api_key=config["logfire"].get("api_key"),
+            )
+        else:
+            llm_adapter = OpenAIAdapter(
+                api_key=llm_api_key,
+                base_url=llm_base_url,
+                model=llm_model,
+            )
 
         # Create business mission if specified in config
         business_mission = None
@@ -61,92 +145,209 @@ class SolanaAgentFactory:
             org_config = config["business"]
             business_mission = BusinessMission(
                 mission=org_config.get("mission", ""),
-                values=[{"name": k, "description": v}
-                        for k, v in org_config.get("values", {}).items()],
+                values=[
+                    {"name": k, "description": v}
+                    for k, v in org_config.get("values", {}).items()
+                ],
                 goals=org_config.get("goals", []),
-                voice=org_config.get("voice", "")
+                voice=org_config.get("voice", ""),
             )
 
+        # capture_mode removed: repository now always upserts/merges per capture
+
         # Create repositories
         memory_provider = None
 
         if "zep" in config and "mongo" in config:
-            if "api_key" not in config["zep"]:
-                raise ValueError("Zep API key is required.")
-            memory_provider = MemoryRepository(
-                db_adapter, config["zep"].get("api_key"), config["zep"].get("base_url"))
+            mem_kwargs: Dict[str, Any] = {
+                "mongo_adapter": db_adapter,
+                "zep_api_key": config["zep"].get("api_key"),
+            }
+            memory_provider = MemoryRepository(**mem_kwargs)
 
-        if "mongo" in config and not "zep" in config:
-            memory_provider = MemoryRepository(db_adapter)
+        if "mongo" in config and "zep" not in config:
+            mem_kwargs = {"mongo_adapter": db_adapter}
+            memory_provider = MemoryRepository(**mem_kwargs)
 
-        if "zep" in config and not "mongo" in config:
+        if "zep" in config and "mongo" not in config:
             if "api_key" not in config["zep"]:
                 raise ValueError("Zep API key is required.")
-            memory_provider = MemoryRepository(
-                zep_api_key=config["zep"].get("api_key"),
-                zep_base_url=config["zep"].get("base_url")
-            )
+            mem_kwargs = {"zep_api_key": config["zep"].get("api_key")}
+            memory_provider = MemoryRepository(**mem_kwargs)
+
+        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", []))
+        )
+        logger.info(  # Use logger.info
+            f"Loaded {len(input_guardrails)} input guardrails and {len(output_guardrails)} output guardrails."
+        )
 
         # Create primary services
         agent_service = AgentService(
             llm_provider=llm_adapter,
             business_mission=business_mission,
             config=config,
+            api_key=llm_api_key,
+            base_url=llm_base_url,
+            model=llm_model,
+            output_guardrails=output_guardrails,
         )
 
-        # Debug the agent service tool registry
-        print(
-            f"Agent service tools after initialization: {agent_service.tool_registry.list_all_tools()}")
-
         # Create routing service
+        # Use Grok 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
+            routing_model = (
+                config.get("openai", {}).get("routing_model")
+                if isinstance(config.get("openai"), dict)
+                else None
+            )
         routing_service = RoutingService(
             llm_provider=llm_adapter,
             agent_service=agent_service,
+            api_key=llm_api_key,
+            base_url=llm_base_url,
+            model=routing_model,
+        )
+
+        # Debug the agent service tool registry
+        logger.debug(  # Use logger.debug
+            f"Agent service tools after initialization: {agent_service.tool_registry.list_all_tools()}"
         )
 
         # Initialize plugin system
         agent_service.plugin_manager = PluginManager(
-            config=config,
-            tool_registry=agent_service.tool_registry
+            config=config, tool_registry=agent_service.tool_registry
         )
         try:
             loaded_plugins = agent_service.plugin_manager.load_plugins()
-            print(f"Loaded {loaded_plugins} plugins")
+            logger.info(f"Loaded {loaded_plugins} plugins")  # Use logger.info
         except Exception as e:
-            print(f"Error loading plugins: {e}")
+            logger.error(f"Error loading plugins: {e}")  # Use logger.error
             loaded_plugins = 0
 
         # Register predefined agents
-        for agent_config in config.get("agents", []):
+        for agent_config in config.get("agents", []):  # pragma: no cover
+            extra_kwargs = {}
+            if "capture_name" in agent_config:
+                extra_kwargs["capture_name"] = agent_config.get("capture_name")
+            if "capture_schema" in agent_config:
+                extra_kwargs["capture_schema"] = agent_config.get("capture_schema")
+
             agent_service.register_ai_agent(
                 name=agent_config["name"],
                 instructions=agent_config["instructions"],
                 specialization=agent_config["specialization"],
+                **extra_kwargs,
             )
 
             # Register tools for this agent
             if "tools" in agent_config:
                 for tool_name in agent_config["tools"]:
-                    print(
-                        f"Available tools before registering {tool_name}: {agent_service.tool_registry.list_all_tools()}")
-                    agent_service.assign_tool_for_agent(
-                        agent_config["name"], tool_name
+                    logger.debug(  # Use logger.debug
+                        f"Available tools before registering {tool_name}: {agent_service.tool_registry.list_all_tools()}"
+                    )
+                    agent_service.assign_tool_for_agent(agent_config["name"], tool_name)
+                    logger.info(  # Use logger.info
+                        f"Successfully registered {tool_name} for agent {agent_config['name']}"
                     )
-                    print(
-                        f"Successfully registered {tool_name} for agent {agent_config['name']}")
 
         # Global tool registrations
         if "agent_tools" in config:
             for agent_name, tools in config["agent_tools"].items():
                 for tool_name in tools:
-                    agent_service.assign_tool_for_agent(
-                        agent_name, tool_name)
+                    agent_service.assign_tool_for_agent(agent_name, tool_name)
+
+        # Initialize Knowledge Base if configured
+        knowledge_base = None
+        kb_config = config.get("knowledge_base")
+        # Requires both KB config section and MongoDB adapter
+        if kb_config and db_adapter:
+            try:
+                pinecone_config = kb_config.get("pinecone", {})
+                splitter_config = kb_config.get("splitter", {})
+                # Get OpenAI embedding config (used by KBService)
+                openai_embed_config = kb_config.get("openai_embeddings", {})
+
+                # Determine OpenAI model and dimensions for KBService
+                openai_model_name = openai_embed_config.get(
+                    "model_name", "text-embedding-3-large"
+                )
+                if openai_model_name == "text-embedding-3-large":
+                    openai_dimensions = 3072
+                elif openai_model_name == "text-embedding-3-small":  # pragma: no cover
+                    openai_dimensions = 1536  # pragma: no cover
+                else:  # pragma: no cover
+                    logger.warning(
+                        f"Unknown OpenAI embedding model '{openai_model_name}' specified for KB. Defaulting dimensions to 3072."
+                    )  # pragma: no cover
+                    openai_dimensions = 3072  # pragma: no cover
+
+                # Create Pinecone adapter for KB
+                # It now relies on external embeddings, so dimension MUST match OpenAI model
+                pinecone_adapter = PineconeAdapter(
+                    api_key=pinecone_config.get("api_key"),
+                    index_name=pinecone_config.get("index_name"),
+                    # This dimension MUST match the OpenAI model used by KBService
+                    embedding_dimensions=openai_dimensions,
+                    cloud_provider=pinecone_config.get("cloud_provider", "aws"),
+                    region=pinecone_config.get("region", "us-east-1"),
+                    metric=pinecone_config.get("metric", "cosine"),
+                    create_index_if_not_exists=pinecone_config.get(
+                        "create_index", True
+                    ),
+                    # Reranking config
+                    use_reranking=pinecone_config.get("use_reranking", False),
+                    rerank_model=pinecone_config.get("rerank_model"),
+                    rerank_top_k=pinecone_config.get("rerank_top_k", 3),
+                    initial_query_top_k_multiplier=pinecone_config.get(
+                        "initial_query_top_k_multiplier", 5
+                    ),
+                    rerank_text_field=pinecone_config.get("rerank_text_field", "text"),
+                )
+
+                # Create the KB service using OpenAI embeddings
+                knowledge_base = KnowledgeBaseService(
+                    pinecone_adapter=pinecone_adapter,
+                    mongodb_adapter=db_adapter,
+                    # Pass OpenAI config directly
+                    openai_api_key=openai_embed_config.get("api_key")
+                    or config.get("openai", {}).get("api_key"),
+                    openai_model_name=openai_model_name,
+                    collection_name=kb_config.get(
+                        "collection_name", "knowledge_documents"
+                    ),
+                    # Pass rerank config (though PineconeAdapter handles the logic)
+                    rerank_results=pinecone_config.get("use_reranking", False),
+                    rerank_top_k=pinecone_config.get("rerank_top_k", 3),
+                    # Pass splitter config
+                    splitter_buffer_size=splitter_config.get("buffer_size", 1),
+                    splitter_breakpoint_percentile=splitter_config.get(
+                        "breakpoint_percentile", 95
+                    ),
+                )
+                logger.info(
+                    "Knowledge Base Service initialized successfully."
+                )  # Use logger.info
+
+            except Exception as e:
+                # Use logger.exception to include traceback automatically
+                logger.exception(f"Failed to initialize Knowledge Base: {e}")
+                knowledge_base = None  # Ensure KB is None if init fails
 
         # Create and return the query service
         query_service = QueryService(
             agent_service=agent_service,
             routing_service=routing_service,
             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/client/client.py

@@ -1,43 +1,126 @@
 from abc import ABC, abstractmethod
-from typing import Any, AsyncGenerator, Dict, Literal, Optional, Union
+from typing import AsyncGenerator, Dict, Any, List, Literal, Optional, Type, Union
 
+from pydantic import BaseModel
 from solana_agent.interfaces.plugins.plugins import Tool
+from solana_agent.interfaces.services.routing import RoutingService as RoutingInterface
+from solana_agent.interfaces.providers.realtime import RealtimeChunk
 
 
 class SolanaAgent(ABC):
-    """Interface for the Solana agent system."""
+    """Interface for the Solana Agent client."""
 
     @abstractmethod
     async def process(
         self,
         user_id: str,
         message: Union[str, bytes],
+        prompt: Optional[str] = None,
         output_format: Literal["text", "audio"] = "text",
-        audio_voice: Literal["alloy", "ash", "ballad", "coral", "echo",
-                             "fable", "onyx", "nova", "sage", "shimmer"] = "nova",
-        audio_instructions: Optional[str] = None,
-        audio_output_format: Literal['mp3', 'opus',
-                                     'aac', 'flac', 'wav', 'pcm'] = "aac",
+        capture_schema: Optional[Dict[str, Any]] = None,
+        capture_name: Optional[str] = None,
+        realtime: bool = False,
+        vad: bool = False,
+        rt_encode_input: bool = False,
+        rt_encode_output: bool = False,
+        rt_output_modalities: Optional[List[Literal["audio", "text"]]] = None,
+        rt_voice: Literal[
+            "alloy",
+            "ash",
+            "ballad",
+            "cedar",
+            "coral",
+            "echo",
+            "marin",
+            "sage",
+            "shimmer",
+            "verse",
+        ] = "marin",
+        audio_voice: Literal[
+            "alloy",
+            "ash",
+            "ballad",
+            "coral",
+            "echo",
+            "fable",
+            "onyx",
+            "nova",
+            "sage",
+            "shimmer",
+        ] = "nova",
+        audio_output_format: Literal[
+            "mp3", "opus", "aac", "flac", "wav", "pcm"
+        ] = "aac",
         audio_input_format: Literal[
             "flac", "mp3", "mp4", "mpeg", "mpga", "m4a", "ogg", "wav", "webm"
         ] = "mp4",
-        prompt: Optional[str] = None,
-    ) -> AsyncGenerator[Union[str, bytes], None]:
+        router: Optional[RoutingInterface] = None,
+        images: Optional[List[Union[str, bytes]]] = None,
+        output_model: Optional[Type[BaseModel]] = None,
+    ) -> AsyncGenerator[Union[str, bytes, BaseModel, RealtimeChunk], None]:
         """Process a user message and return the response stream."""
         pass
 
+    @abstractmethod
+    async def delete_user_history(self, user_id: str) -> None:
+        """Delete the conversation history for a user."""
+        pass
+
     @abstractmethod
     async def get_user_history(
         self,
         user_id: str,
         page_num: int = 1,
         page_size: int = 20,
-        sort_order: str = "desc"  # "asc" for oldest-first, "desc" for newest-first
+        sort_order: str = "desc",
     ) -> Dict[str, Any]:
         """Get paginated message history for a user."""
         pass
 
     @abstractmethod
-    def register_tool(self, tool: Tool) -> bool:
-        """Register a tool in the registry."""
+    def register_tool(self, agent_name: str, tool: Tool) -> bool:
+        """Register a tool with the agent system."""
+        pass
+
+    @abstractmethod
+    async def kb_add_document(
+        self,
+        text: str,
+        metadata: Dict[str, Any],
+        document_id: Optional[str] = None,
+        namespace: Optional[str] = None,
+    ) -> str:
+        """Add a document to the knowledge base."""
+        pass
+
+    @abstractmethod
+    async def kb_query(
+        self,
+        query_text: str,
+        filter: Optional[Dict[str, Any]] = None,
+        top_k: int = 5,
+        namespace: Optional[str] = None,
+        include_content: bool = True,
+        include_metadata: bool = True,
+    ) -> List[Dict[str, Any]]:
+        """Query the knowledge base."""
+        pass
+
+    @abstractmethod
+    async def kb_delete_document(
+        self, document_id: str, namespace: Optional[str] = None
+    ) -> bool:
+        """Delete a document from the knowledge base."""
+        pass
+
+    @abstractmethod
+    async def kb_add_pdf_document(
+        self,
+        pdf_data: Union[bytes, str],
+        metadata: Dict[str, Any],
+        document_id: Optional[str] = None,
+        namespace: Optional[str] = None,
+        chunk_batch_size: int = 50,
+    ) -> str:
+        """Add a PDF document to the knowledge base."""
         pass

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

solana_agent/interfaces/plugins/plugins.py

@@ -4,8 +4,9 @@ Plugin system interfaces.
 These interfaces define the contracts for the plugin system,
 enabling extensibility through tools and plugins.
 """
+
 from abc import ABC, abstractmethod
-from typing import Dict, List, Any, Optional, Callable
+from typing import Dict, List, Any, Optional
 
 
 class Tool(ABC):