solana-agent 11.3.0__py3-none-any.whl → 14.0.0__py3-none-any.whl

solana_agent/__init__.py

@@ -1 +1,33 @@
-from .ai import *
+"""
+Solana Agent - An AI agent framework with routing, memory, and specialized agents.
+
+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
+
+# Factory for creating agent systems
+from solana_agent.factories.agent_factory import SolanaAgentFactory
+
+# Useful tools and utilities
+from solana_agent.plugins.manager import PluginManager
+from solana_agent.plugins.registry import ToolRegistry
+from solana_agent.plugins.tools import AutoTool
+
+# Package metadata
+__all__ = [
+    # Main client interfaces
+    "SolanaAgent",
+
+    # Factories
+    "SolanaAgentFactory",
+
+    # Tools
+    "PluginManager",
+    "ToolRegistry",
+    "AutoTool",
+]

solana_agent/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""
+Adapters for external systems and services.
+
+These adapters implement the interfaces defined in solana_agent.interfaces
+and provide concrete implementations for interacting with external systems.
+"""

solana_agent/adapters/llm_adapter.py

@@ -0,0 +1,123 @@
+"""
+LLM provider adapters for the Solana Agent system.
+
+These adapters implement the LLMProvider interface for different LLM services.
+"""
+from typing import AsyncGenerator, List, Type, TypeVar
+
+from openai import OpenAI
+from pydantic import BaseModel
+
+from solana_agent.interfaces.providers.llm import LLMProvider
+
+T = TypeVar('T', bound=BaseModel)
+
+
+class OpenAIAdapter(LLMProvider):
+    """OpenAI implementation of LLMProvider with web search capabilities."""
+
+    def __init__(self, api_key: str, model: str = "gpt-4o-mini"):
+        self.client = OpenAI(api_key=api_key)
+        self.model = model
+        # Add search-enabled model variants
+        self.search_models = {
+            "gpt-4o": "gpt-4o-search-preview",
+            "gpt-4o-mini": "gpt-4o-mini-search-preview"
+        }
+
+    async def generate_text(
+        self,
+        prompt: str,
+        system_prompt: str = "",
+        needs_search: bool = False,
+        **kwargs,
+    ) -> AsyncGenerator[str, None]:
+        """Generate text from OpenAI models with web search capability."""
+        messages = []
+
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+
+        messages.append({"role": "user", "content": prompt})
+
+        # Prepare request parameters
+        request_params = {
+            "messages": messages,
+            "stream": kwargs.get("stream", True),
+            "response_format": kwargs.get("response_format", None),
+        }
+
+        # If search is needed, update model and add search options
+        if needs_search:
+            base_model = kwargs.get("model", self.model)
+            request_params["model"] = self.search_models.get(
+                base_model, "gpt-4o-mini-search-preview")
+            request_params["web_search_options"] = {
+                "search_context_size": "medium",
+                "user_location": {
+                    "type": "approximate",
+                    "approximate": {
+                        "country": "US",
+                        "timezone": "America/Los_Angeles"
+                    }
+                }
+            }
+        else:
+            request_params["model"] = kwargs.get("model", self.model)
+
+        try:
+            response = self.client.chat.completions.create(**request_params)
+            current_text = ""
+
+            for chunk in response:
+                if chunk.choices:
+                    # Handle content
+                    if chunk.choices[0].delta.content:
+                        text = chunk.choices[0].delta.content
+                        current_text += text
+                        yield text
+
+        except Exception as e:
+            print(f"Error in generate_text: {str(e)}")
+            import traceback
+            print(traceback.format_exc())
+            yield f"I apologize, but I encountered an error: {str(e)}"
+
+    def generate_embedding(self, text: str) -> List[float]:
+        """Generate embeddings for a given text using OpenAI's embedding model."""
+        try:
+            response = self.client.embeddings.create(
+                model="text-embedding-3-small",
+                input=text
+            )
+            return response.data[0].embedding
+        except Exception as e:
+            print(f"Error generating embedding: {e}")
+            # Return a zero vector as fallback (not ideal but prevents crashing)
+            return [0.0] * 1536  # Standard size for text-embedding-3-small
+
+    async def parse_structured_output(
+        self,
+        prompt: str,
+        system_prompt: str,
+        model_class: Type[T],
+        **kwargs
+    ) -> T:
+        """Generate structured output using Pydantic model parsing."""
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+
+        messages.append({"role": "user", "content": prompt})
+
+        try:
+            # First try the beta parsing API
+            completion = self.client.beta.chat.completions.parse(
+                model=kwargs.get("model", self.model),
+                messages=messages,
+                response_format=model_class,
+                temperature=kwargs.get("temperature", 0.2),
+            )
+            return completion.choices[0].message.parsed
+        except Exception as e:
+            print(f"Error with beta.parse method: {e}")

solana_agent/adapters/mongodb_adapter.py

@@ -0,0 +1,69 @@
+"""
+MongoDB adapter for the Solana Agent system.
+
+This adapter implements the DataStorageProvider interface for MongoDB.
+"""
+import uuid
+from typing import Dict, List, Tuple, Optional
+
+from pymongo import MongoClient
+
+from solana_agent.interfaces.providers.data_storage import DataStorageProvider
+
+
+class MongoDBAdapter(DataStorageProvider):
+    """MongoDB implementation of DataStorageProvider."""
+
+    def __init__(self, connection_string: str, database_name: str):
+        self.client = MongoClient(connection_string)
+        self.db = self.client[database_name]
+
+    def create_collection(self, name: str) -> None:
+        if name not in self.db.list_collection_names():
+            self.db.create_collection(name)
+
+    def collection_exists(self, name: str) -> bool:
+        return name in self.db.list_collection_names()
+
+    def insert_one(self, collection: str, document: Dict) -> str:
+        if "_id" not in document:
+            document["_id"] = str(uuid.uuid4())
+        self.db[collection].insert_one(document)
+        return document["_id"]
+
+    def find_one(self, collection: str, query: Dict) -> Optional[Dict]:
+        return self.db[collection].find_one(query)
+
+    def find(
+        self,
+        collection: str,
+        query: Dict,
+        sort: Optional[List[Tuple]] = None,
+        limit: int = 0,
+        skip: int = 0
+    ) -> List[Dict]:
+        cursor = self.db[collection].find(query)
+        if sort:
+            cursor = cursor.sort(sort)
+        if limit > 0:
+            cursor = cursor.limit(limit)
+        if skip > 0:
+            cursor = cursor.skip(skip)
+        return list(cursor)
+
+    def update_one(self, collection: str, query: Dict, update: Dict, upsert: bool = False) -> bool:
+        result = self.db[collection].update_one(query, update, upsert=upsert)
+        return result.modified_count > 0 or (upsert and result.upserted_id is not None)
+
+    def delete_one(self, collection: str, query: Dict) -> bool:
+        result = self.db[collection].delete_one(query)
+        return result.deleted_count > 0
+
+    def count_documents(self, collection: str, query: Dict) -> int:
+        return self.db[collection].count_documents(query)
+
+    def aggregate(self, collection: str, pipeline: List[Dict]) -> List[Dict]:
+        return list(self.db[collection].aggregate(pipeline))
+
+    def create_index(self, collection: str, keys: List[Tuple], **kwargs) -> None:
+        self.db[collection].create_index(keys, **kwargs)

solana_agent/client/solana_agent.py

@@ -0,0 +1,75 @@
+"""
+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
+
+from solana_agent.factories.agent_factory import SolanaAgentFactory
+
+
+class SolanaAgent:
+    """Simplified client interface for interacting with the agent system."""
+
+    def __init__(self, config_path: str = None, config: Dict[str, Any] = None):
+        """Initialize the agent system from config file or dictionary.
+
+        Args:
+            config_path: Path to configuration file (JSON or Python)
+            config: Configuration dictionary
+        """
+        if not config and not config_path:
+            raise ValueError("Either config or config_path must be provided")
+
+        if config_path:
+            with open(config_path, "r") as f:
+                if config_path.endswith(".json"):
+                    config = json.load(f)
+                else:
+                    # Assume it's a Python file
+                    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
+
+        self.query_service = SolanaAgentFactory.create_from_config(config)
+
+    async def process(self, user_id: str, message: str) -> AsyncGenerator[str, None]:
+        """Process a user message and return the response stream.
+
+        Args:
+            user_id: User ID
+            message: User message
+
+        Returns:
+            Async generator yielding response chunks
+        """
+        async for chunk in self.query_service.process(user_id, message):
+            yield chunk
+
+    async def get_user_history(
+        self,
+        user_id: str,
+        page_num: int = 1,
+        page_size: int = 20,
+        sort_order: str = "asc"  # "asc" for oldest-first, "desc" for newest-first
+    ) -> Dict[str, Any]:
+        """
+        Get paginated message history for a user.
+
+        Args:
+            user_id: User ID
+            page_num: Page number (starting from 1)
+            page_size: Number of messages per page
+            sort_order: Sort order ("asc" or "desc")
+
+        Returns:
+            Dictionary with paginated results and metadata
+        """
+        return await self.query_service.get_user_history(
+            user_id, page_num, page_size, sort_order
+        )

solana_agent/domains/__init__.py

@@ -0,0 +1,6 @@
+"""
+Domain models for the Solana Agent system.
+
+This package contains all the core domain models that represent the
+business objects and value types in the system.
+"""

solana_agent/domains/agents.py

@@ -0,0 +1,80 @@
+"""
+Domain models for AI and human agents.
+
+This module defines the core domain models for representing
+AI agents, human agents, and organization mission/values.
+"""
+from typing import List, Optional, Dict, Any, Union
+# Import the class directly, not the module
+from datetime import datetime
+from pydantic import BaseModel, Field, field_validator
+
+
+class OrganizationMission(BaseModel):
+    """Organization mission and values to guide agent behavior."""
+
+    mission_statement: str = Field(...,
+                                   description="Organization mission statement")
+    values: List[Dict[str, str]] = Field(
+        default_factory=list,
+        description="Organization values as name-description pairs"
+    )
+    goals: List[str] = Field(
+        default_factory=list,
+        description="Organization goals"
+    )
+    guidance: Optional[str] = Field(
+        None, description="Additional guidance for agents")
+
+    @field_validator("mission_statement")
+    @classmethod
+    def mission_statement_not_empty(cls, v: str) -> str:
+        """Validate that mission statement is not empty."""
+        if not v.strip():
+            raise ValueError("Mission statement cannot be empty")
+        return v
+
+    @field_validator("values")
+    @classmethod
+    def validate_values(cls, values: List[Dict[str, str]]) -> List[Dict[str, str]]:
+        """Validate that values have proper format."""
+        for value in values:
+            if "name" not in value or "description" not in value:
+                raise ValueError("Each value must have a name and description")
+        return values
+
+
+class AIAgent(BaseModel):
+    """AI agent with specialized capabilities."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    name: str = Field(..., description="Unique agent identifier name")
+    instructions: str = Field(...,
+                              description="Base instructions for the agent")
+    specialization: str = Field(..., description="Agent's specialized domain")
+    model: str = Field("gpt-4o-mini", description="Language model to use")
+    created_at: datetime = Field(
+        default_factory=datetime.now, description="Creation timestamp")
+    updated_at: datetime = Field(
+        default_factory=datetime.now, description="Last update timestamp")
+    description: Optional[str] = Field(
+        None, description="Agent description or summary")
+
+    @field_validator("name", "specialization")
+    @classmethod
+    def not_empty(cls, v: str) -> str:
+        """Validate that string fields are not empty."""
+        if not v.strip():
+            raise ValueError("Field cannot be empty")
+        return v
+
+    @field_validator("instructions")
+    @classmethod
+    def instructions_not_empty(cls, v: str) -> str:
+        """Validate that instructions are not empty."""
+        if not v.strip():
+            raise ValueError("Instructions cannot be empty")
+        if len(v) < 10:
+            raise ValueError("Instructions must be at least 10 characters")
+        return v

solana_agent/domains/routing.py

@@ -0,0 +1,14 @@
+from typing import List
+from pydantic import BaseModel, Field
+
+
+class QueryAnalysis(BaseModel):
+    """Analysis of a user query for routing purposes."""
+    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)")
+    topics: List[str] = Field(..., description="Key topics in the query")
+    confidence: float = Field(..., description="Confidence in the analysis")

solana_agent/factories/agent_factory.py

@@ -0,0 +1,148 @@
+"""
+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
+from solana_agent.services.query import QueryService
+from solana_agent.services.agent import AgentService
+from solana_agent.services.routing import RoutingService
+
+# Repository imports
+from solana_agent.repositories.memory import MemoryRepository
+from solana_agent.repositories.agent import MongoAgentRepository
+
+# Adapter imports
+from solana_agent.adapters.llm_adapter import OpenAIAdapter
+from solana_agent.adapters.mongodb_adapter import MongoDBAdapter
+
+# Domain and plugin imports
+from solana_agent.domains.agents import OrganizationMission
+from solana_agent.plugins.manager import PluginManager
+
+
+class SolanaAgentFactory:
+    """Factory for creating and wiring components of the Solana Agent system."""
+
+    @staticmethod
+    def create_from_config(config: Dict[str, Any]) -> QueryService:
+        """Create the agent system from configuration.
+
+        Args:
+            config: Configuration dictionary
+
+        Returns:
+            Configured QueryService instance
+        """
+        # Create adapters
+        db_adapter = MongoDBAdapter(
+            connection_string=config["mongo"]["connection_string"],
+            database_name=config["mongo"]["database"],
+        )
+
+        llm_adapter = OpenAIAdapter(
+            api_key=config["openai"]["api_key"],
+            model=config.get("openai", {}).get("default_model", "gpt-4o-mini"),
+        )
+
+        # Create organization mission if specified in config
+        organization_mission = None
+        if "organization" in config:
+            org_config = config["organization"]
+            organization_mission = OrganizationMission(
+                mission_statement=org_config.get("mission_statement", ""),
+                values=[{"name": k, "description": v}
+                        for k, v in org_config.get("values", {}).items()],
+                goals=org_config.get("goals", []),
+                guidance=org_config.get("guidance", "")
+            )
+
+        # Create repositories
+        memory_provider = MemoryRepository(
+            db_adapter, config["zep"].get("api_key"), config["zep"].get("base_url"))
+        agent_repo = MongoAgentRepository(db_adapter)
+
+        # Create primary services
+        agent_service = AgentService(
+            agent_repository=agent_repo,
+            llm_provider=llm_adapter,
+            organization_mission=organization_mission,
+        )
+
+        # Debug the agent service tool registry
+        print(
+            f"Agent service tools after initialization: {agent_service.tool_registry.list_all_tools()}")
+
+        # Create routing service
+        routing_service = RoutingService(
+            llm_provider=llm_adapter,
+            agent_service=agent_service,
+        )
+
+        # Initialize plugin system
+        agent_service.plugin_manager = PluginManager(
+            config=config,
+            tool_registry=agent_service.tool_registry
+        )
+        loaded_plugins = agent_service.plugin_manager.load_plugins()
+        print(f"Loaded {loaded_plugins} plugins")
+
+        # Sync MongoDB with config-defined agents
+        config_defined_agents = [agent["name"]
+                                 for agent in config.get("agents", [])]
+        all_db_agents = agent_repo.get_all_ai_agents()
+        db_agent_names = [agent.name for agent in all_db_agents]
+
+        # Delete agents not in config
+        agents_to_delete = [
+            name for name in db_agent_names if name not in config_defined_agents]
+        for agent_name in agents_to_delete:
+            print(
+                f"Deleting agent '{agent_name}' from MongoDB - no longer defined in config")
+            agent_repo.delete_ai_agent(agent_name)
+
+        # Register predefined agents
+        for agent_config in config.get("ai_agents", []):
+            agent_service.register_ai_agent(
+                name=agent_config["name"],
+                instructions=agent_config["instructions"],
+                specialization=agent_config["specialization"],
+                model=agent_config.get("model", "gpt-4o-mini"),
+            )
+
+            # 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()}")
+                    try:
+                        agent_service.assign_tool_for_agent(
+                            agent_config["name"], tool_name
+                        )
+                        print(
+                            f"Successfully registered {tool_name} for agent {agent_config['name']}")
+                    except ValueError as e:
+                        print(
+                            f"Error registering tool {tool_name} for agent {agent_config['name']}: {e}")
+
+        # Global tool registrations
+        if "agent_tools" in config:
+            for agent_name, tools in config["agent_tools"].items():
+                for tool_name in tools:
+                    try:
+                        agent_service.assign_tool_for_agent(
+                            agent_name, tool_name)
+                    except ValueError as e:
+                        print(f"Error registering tool: {e}")
+
+        # Create and return the query service
+        query_service = QueryService(
+            agent_service=agent_service,
+            routing_service=routing_service,
+            memory_provider=memory_provider,
+        )
+
+        return query_service

solana_agent/interfaces/__init__.py

@@ -0,0 +1,11 @@
+"""
+Abstract interfaces for the Solana Agent system.
+
+These interfaces define the contracts that concrete implementations
+must adhere to, following the Dependency Inversion Principle.
+
+This package contains:
+- Repository interfaces for data access
+- Provider interfaces for external service adapters
+- Service interfaces for business logic components
+"""