solana-agent 27.3.6__py3-none-any.whl → 27.3.7__py3-none-any.whl

solana_agent/client/solana_agent.py

@@ -4,6 +4,7 @@ Simplified client interface for interacting with the Solana Agent system.
 This module provides a clean API for end users to interact with
 the agent system without dealing with internal implementation details.
 """
+
 import json
 import importlib.util
 from typing import AsyncGenerator, Dict, Any, List, Literal, Optional, Union
@@ -34,8 +35,7 @@ class SolanaAgent(SolanaAgentInterface):
                     config = json.load(f)
                 else:
                     # Assume it's a Python file
-                    spec = importlib.util.spec_from_file_location(
-                        "config", config_path)
+                    spec = importlib.util.spec_from_file_location("config", config_path)
                     config_module = importlib.util.module_from_spec(spec)
                     spec.loader.exec_module(config_module)
                     config = config_module.config
@@ -48,11 +48,22 @@ class SolanaAgent(SolanaAgentInterface):
         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_voice: Literal[
+            "alloy",
+            "ash",
+            "ballad",
+            "coral",
+            "echo",
+            "fable",
+            "onyx",
+            "nova",
+            "sage",
+            "shimmer",
+        ] = "nova",
         audio_instructions: str = "You speak in a friendly and helpful manner.",
-        audio_output_format: Literal['mp3', 'opus',
-                                     'aac', 'flac', 'wav', 'pcm'] = "aac",
+        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",
@@ -101,7 +112,7 @@ class SolanaAgent(SolanaAgentInterface):
         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",  # "asc" for oldest-first, "desc" for newest-first
     ) -> Dict[str, Any]:  # pragma: no cover
         """
         Get paginated message history for a user.
@@ -130,27 +141,29 @@ class SolanaAgent(SolanaAgentInterface):
         Returns:
             True if successful, False
         """
-        success = self.query_service.agent_service.tool_registry.register_tool(
-            tool)
+        success = self.query_service.agent_service.tool_registry.register_tool(tool)
         if success:
             self.query_service.agent_service.assign_tool_for_agent(
-                agent_name, tool.name)
+                agent_name, tool.name
+            )
         return success
 
     def _ensure_kb(self) -> KnowledgeBaseService:
         """Checks if the knowledge base service is available and returns it."""
-        if hasattr(self.query_service, 'knowledge_base') and self.query_service.knowledge_base:
+        if (
+            hasattr(self.query_service, "knowledge_base")
+            and self.query_service.knowledge_base
+        ):
             return self.query_service.knowledge_base
         else:
-            raise AttributeError(
-                "Knowledge base service not configured or available.")
+            raise AttributeError("Knowledge base service not configured or available.")
 
     async def kb_add_document(
         self,
         text: str,
         metadata: Dict[str, Any],
         document_id: Optional[str] = None,
-        namespace: Optional[str] = None
+        namespace: Optional[str] = None,
     ) -> str:
         """
         Add a document to the knowledge base.
@@ -174,7 +187,7 @@ class SolanaAgent(SolanaAgentInterface):
         top_k: int = 5,
         namespace: Optional[str] = None,
         include_content: bool = True,
-        include_metadata: bool = True
+        include_metadata: bool = True,
     ) -> List[Dict[str, Any]]:
         """
         Query the knowledge base.
@@ -191,12 +204,12 @@ class SolanaAgent(SolanaAgentInterface):
             List of matching documents.
         """
         kb = self._ensure_kb()
-        return await kb.query(query_text, filter, top_k, namespace, include_content, include_metadata)
+        return await kb.query(
+            query_text, filter, top_k, namespace, include_content, include_metadata
+        )
 
     async def kb_delete_document(
-        self,
-        document_id: str,
-        namespace: Optional[str] = None
+        self, document_id: str, namespace: Optional[str] = None
     ) -> bool:
         """
         Delete a document from the knowledge base.
@@ -216,7 +229,7 @@ class SolanaAgent(SolanaAgentInterface):
         document_id: str,
         text: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
-        namespace: Optional[str] = None
+        namespace: Optional[str] = None,
     ) -> bool:
         """
         Update an existing document in the knowledge base.
@@ -237,7 +250,7 @@ class SolanaAgent(SolanaAgentInterface):
         self,
         documents: List[Dict[str, Any]],
         namespace: Optional[str] = None,
-        batch_size: int = 50
+        batch_size: int = 50,
     ) -> List[str]:
         """
         Add multiple documents to the knowledge base in batches.
@@ -259,7 +272,7 @@ class SolanaAgent(SolanaAgentInterface):
         metadata: Dict[str, Any],
         document_id: Optional[str] = None,
         namespace: Optional[str] = None,
-        chunk_batch_size: int = 50
+        chunk_batch_size: int = 50,
     ) -> str:
         """
         Add a PDF document to the knowledge base via the client.
@@ -278,4 +291,6 @@ class SolanaAgent(SolanaAgentInterface):
         # Type check added for clarity, though handled in service
         if not isinstance(pdf_data, (bytes, str)):
             raise TypeError("pdf_data must be bytes or a file path string.")
-        return await kb.add_pdf_document(pdf_data, metadata, document_id, namespace, chunk_batch_size)
+        return await kb.add_pdf_document(
+            pdf_data, metadata, document_id, namespace, chunk_batch_size
+        )

solana_agent/domains/agent.py

@@ -4,25 +4,20 @@ Domain models for AI and human agents.
 This module defines the core domain models for representing
 AI agents, human agents, and business mission/values.
 """
-from typing import List, Dict, Any
+
+from typing import List, Dict
 from pydantic import BaseModel, Field, field_validator
 
 
 class BusinessMission(BaseModel):
     """Business mission and values to guide agent behavior."""
 
-    mission: str = Field(...,
-                         description="Business mission statement")
+    mission: str = Field(..., description="Business mission statement")
     values: List[Dict[str, str]] = Field(
-        default_factory=list,
-        description="Business values as name-description pairs"
-    )
-    goals: List[str] = Field(
-        default_factory=list,
-        description="Business goals"
+        default_factory=list, description="Business values as name-description pairs"
     )
-    voice: str = Field(
-        None, description="Business voice or tone")
+    goals: List[str] = Field(default_factory=list, description="Business goals")
+    voice: str = Field(None, description="Business voice or tone")
 
     @field_validator("mission")
     @classmethod
@@ -56,8 +51,7 @@ class AIAgent(BaseModel):
     model_config = {"arbitrary_types_allowed": True}
 
     name: str = Field(..., description="Unique agent identifier name")
-    instructions: str = Field(...,
-                              description="Base instructions for the agent")
+    instructions: str = Field(..., description="Base instructions for the agent")
     specialization: str = Field(..., description="Agent's specialized domain")
 
     @field_validator("name", "specialization")

solana_agent/domains/routing.py

@@ -4,11 +4,11 @@ from pydantic import BaseModel, Field
 
 class QueryAnalysis(BaseModel):
     """Analysis of a user query for routing purposes."""
-    primary_specialization: str = Field(...,
-                                        description="Main specialization needed")
+
+    primary_specialization: str = Field(..., description="Main specialization needed")
     secondary_specializations: List[str] = Field(
-        ..., description="Other helpful specializations")
-    complexity_level: int = Field(...,
-                                  description="Complexity level (1-5)")
+        ..., description="Other helpful specializations"
+    )
+    complexity_level: int = Field(..., description="Complexity level (1-5)")
     topics: List[str] = Field(..., description="Key topics in the query")
     confidence: float = Field(..., description="Confidence in the analysis")

solana_agent/factories/agent_factory.py

@@ -4,6 +4,7 @@ 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
 
 # Service imports
@@ -58,10 +59,12 @@ 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", ""),
             )
 
         # Create repositories
@@ -69,19 +72,22 @@ class SolanaAgentFactory:
 
         if "zep" in config and "mongo" in config:
             memory_provider = MemoryRepository(
-                mongo_adapter=db_adapter, zep_api_key=config["zep"].get("api_key"))
+                mongo_adapter=db_adapter, zep_api_key=config["zep"].get("api_key")
+            )
 
-        if "mongo" in config and not "zep" in config:
+        if "mongo" in config and "zep" not in config:
             memory_provider = MemoryRepository(mongo_adapter=db_adapter)
 
-        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")
-            )
+            memory_provider = MemoryRepository(zep_api_key=config["zep"].get("api_key"))
 
-        if "gemini" in config and "api_key" in config["gemini"] and not "grok" in config:
+        if (
+            "gemini" in config
+            and "api_key" in config["gemini"]
+            and "grok" not in config
+        ):
             # Create primary services
             agent_service = AgentService(
                 llm_provider=llm_adapter,
@@ -101,7 +107,12 @@ class SolanaAgentFactory:
                 model="gemini-2.0-flash",
             )
 
-        elif "gemini" in config and "api_key" in config["gemini"] and "grok" in config and "api_key" in config["grok"]:
+        elif (
+            "gemini" in config
+            and "api_key" in config["gemini"]
+            and "grok" in config
+            and "api_key" in config["grok"]
+        ):
             # Create primary services
             agent_service = AgentService(
                 llm_provider=llm_adapter,
@@ -120,7 +131,9 @@ class SolanaAgentFactory:
                 model="gemini-2.0-flash",
             )
 
-        elif "grok" in config and "api_key" in config["grok"] and not "gemini" in config:
+        elif (
+            "grok" in config and "api_key" in config["grok"] and "gemini" not in config
+        ):
             # Create primary services
             agent_service = AgentService(
                 llm_provider=llm_adapter,
@@ -153,12 +166,12 @@ class SolanaAgentFactory:
 
         # Debug the agent service tool registry
         print(
-            f"Agent service tools after initialization: {agent_service.tool_registry.list_all_tools()}")
+            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()
@@ -179,19 +192,18 @@ class SolanaAgentFactory:
             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
+                        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)
                     print(
-                        f"Successfully registered {tool_name} for agent {agent_config['name']}")
+                        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
@@ -206,7 +218,8 @@ class SolanaAgentFactory:
 
                 # Determine OpenAI model and dimensions for KBService
                 openai_model_name = openai_embed_config.get(
-                    "model_name", "text-embedding-3-large")
+                    "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
@@ -219,20 +232,20 @@ class SolanaAgentFactory:
                     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"),
+                    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),
+                        "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"),
+                        "initial_query_top_k_multiplier", 5
+                    ),
+                    rerank_text_field=pinecone_config.get("rerank_text_field", "text"),
                 )
 
                 # Create the KB service using OpenAI embeddings
@@ -240,24 +253,27 @@ class SolanaAgentFactory:
                     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_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"),
+                        "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)
+                        "breakpoint_percentile", 95
+                    ),
                 )
                 print("Knowledge Base Service initialized successfully.")
 
             except Exception as e:
                 print(f"Failed to initialize Knowledge Base: {e}")
                 import traceback
+
                 print(traceback.format_exc())
                 knowledge_base = None  # Ensure KB is None if init fails
 
@@ -267,8 +283,7 @@ class SolanaAgentFactory:
             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
+            kb_results_count=kb_config.get("results_count", 3) if kb_config else 3,
         )
 
         return query_service

solana_agent/interfaces/client/client.py

@@ -14,11 +14,22 @@ class SolanaAgent(ABC):
         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_voice: Literal[
+            "alloy",
+            "ash",
+            "ballad",
+            "coral",
+            "echo",
+            "fable",
+            "onyx",
+            "nova",
+            "sage",
+            "shimmer",
+        ] = "nova",
         audio_instructions: str = "You speak in a friendly and helpful manner.",
-        audio_output_format: Literal['mp3', 'opus',
-                                     'aac', 'flac', 'wav', 'pcm'] = "aac",
+        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",
@@ -38,7 +49,7 @@ class SolanaAgent(ABC):
         user_id: str,
         page_num: int = 1,
         page_size: int = 20,
-        sort_order: str = "desc"
+        sort_order: str = "desc",
     ) -> Dict[str, Any]:
         """Get paginated message history for a user."""
         pass
@@ -54,7 +65,7 @@ class SolanaAgent(ABC):
         text: str,
         metadata: Dict[str, Any],
         document_id: Optional[str] = None,
-        namespace: Optional[str] = None
+        namespace: Optional[str] = None,
     ) -> str:
         """Add a document to the knowledge base."""
         pass
@@ -67,16 +78,14 @@ class SolanaAgent(ABC):
         top_k: int = 5,
         namespace: Optional[str] = None,
         include_content: bool = True,
-        include_metadata: 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
+        self, document_id: str, namespace: Optional[str] = None
     ) -> bool:
         """Delete a document from the knowledge base."""
         pass
@@ -87,7 +96,7 @@ class SolanaAgent(ABC):
         document_id: str,
         text: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
-        namespace: Optional[str] = None
+        namespace: Optional[str] = None,
     ) -> bool:
         """Update an existing document in the knowledge base."""
         pass
@@ -97,7 +106,7 @@ class SolanaAgent(ABC):
         self,
         documents: List[Dict[str, Any]],
         namespace: Optional[str] = None,
-        batch_size: int = 50
+        batch_size: int = 50,
     ) -> List[str]:
         """Add multiple documents to the knowledge base in batches."""
         pass
@@ -109,7 +118,7 @@ class SolanaAgent(ABC):
         metadata: Dict[str, Any],
         document_id: Optional[str] = None,
         namespace: Optional[str] = None,
-        chunk_batch_size: int = 50
+        chunk_batch_size: int = 50,
     ) -> str:
         """Add a PDF document to the knowledge base."""
         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):

solana_agent/interfaces/providers/data_storage.py

@@ -27,13 +27,20 @@ class DataStorageProvider(ABC):
 
     @abstractmethod
     def find(
-        self, collection: str, query: Dict, sort: Optional[List] = None, limit: int = 0, skip: int = 0
+        self,
+        collection: str,
+        query: Dict,
+        sort: Optional[List] = None,
+        limit: int = 0,
+        skip: int = 0,
     ) -> List[Dict]:
         """Find documents matching query."""
         pass
 
     @abstractmethod
-    def update_one(self, collection: str, query: Dict, update: Dict, upsert: bool = False) -> bool:
+    def update_one(
+        self, collection: str, query: Dict, update: Dict, upsert: bool = False
+    ) -> bool:
         """Update a document."""
         pass
 

solana_agent/interfaces/providers/llm.py

@@ -1,10 +1,17 @@
 from abc import ABC, abstractmethod
-from typing import Any, AsyncGenerator, Callable, Dict, List, Literal, Optional, Type, TypeVar, Union
+from typing import (
+    AsyncGenerator,
+    List,
+    Literal,
+    Optional,
+    Type,
+    TypeVar,
+)
 
 from pydantic import BaseModel
 
 
-T = TypeVar('T', bound=BaseModel)
+T = TypeVar("T", bound=BaseModel)
 
 
 class LLMProvider(ABC):
@@ -24,12 +31,13 @@ class LLMProvider(ABC):
 
     @abstractmethod
     async def parse_structured_output(
-        self, prompt: str,
+        self,
+        prompt: str,
         system_prompt: str,
         model_class: Type[T],
         api_key: Optional[str] = None,
         base_url: Optional[str] = None,
-        model: Optional[str] = None
+        model: Optional[str] = None,
     ) -> T:
         """Generate structured output using a specific model class."""
         pass
@@ -39,10 +47,19 @@ class LLMProvider(ABC):
         self,
         text: str,
         instructions: str = "You speak in a friendly and helpful manner.",
-        voice: Literal["alloy", "ash", "ballad", "coral", "echo",
-                       "fable", "onyx", "nova", "sage", "shimmer"] = "nova",
-        response_format: Literal['mp3', 'opus',
-                                 'aac', 'flac', 'wav', 'pcm'] = "aac",
+        voice: Literal[
+            "alloy",
+            "ash",
+            "ballad",
+            "coral",
+            "echo",
+            "fable",
+            "onyx",
+            "nova",
+            "sage",
+            "shimmer",
+        ] = "nova",
+        response_format: Literal["mp3", "opus", "aac", "flac", "wav", "pcm"] = "aac",
     ) -> AsyncGenerator[bytes, None]:
         """Stream text-to-speech audio from the language model."""
         pass
@@ -60,10 +77,7 @@ class LLMProvider(ABC):
 
     @abstractmethod
     async def embed_text(
-        self,
-        text: str,
-        model: Optional[str] = None,
-        dimensions: Optional[int] = None
+        self, text: str, model: Optional[str] = None, dimensions: Optional[int] = None
     ) -> List[float]:
         """
         Generate an embedding for the given text.

solana_agent/interfaces/providers/memory.py

@@ -27,7 +27,7 @@ class MemoryProvider(ABC):
         query: Dict,
         sort: Optional[List[Tuple]] = None,
         limit: int = 0,
-        skip: int = 0
+        skip: int = 0,
     ) -> List[Dict]:
         """Find documents matching query."""
         pass

solana_agent/interfaces/providers/vector_storage.py

@@ -5,9 +5,7 @@ class VectorStorageProvider:
     """Interface for Vector Storage Providers."""
 
     async def upsert(
-        self,
-        vectors: List[Dict[str, Any]],
-        namespace: Optional[str] = None
+        self, vectors: List[Dict[str, Any]], namespace: Optional[str] = None
     ) -> None:
         """Upsert vectors into the storage."""
         pass
@@ -17,7 +15,7 @@ class VectorStorageProvider:
         texts: List[str],
         ids: List[str],
         metadatas: Optional[List[Dict[str, Any]]] = None,
-        namespace: Optional[str] = None
+        namespace: Optional[str] = None,
     ) -> None:
         """Embeds texts and upserts them into the storage."""
         pass
@@ -46,11 +44,7 @@ class VectorStorageProvider:
         """Embeds query text and queries the storage."""
         pass
 
-    async def delete(
-        self,
-        ids: List[str],
-        namespace: Optional[str] = None
-    ) -> None:
+    async def delete(self, ids: List[str], namespace: Optional[str] = None) -> None:
         """Delete vectors by IDs."""
         pass