solana-agent 12.0.0__tar.gz → 14.0.1__tar.gz

solana_agent-14.0.1/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.3
+Name: solana-agent
+Version: 14.0.1
+Summary: The Future of Work
+License: MIT
+Keywords: ai,openai,ai agents,agi
+Author: Bevan Hunt
+Author-email: bevan@bevanhunt.com
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: openai (>=1.68.0,<2.0.0)
+Requires-Dist: pydantic (>=2.10.6,<3.0.0)
+Requires-Dist: pymongo (>=4.11.3,<5.0.0)
+Requires-Dist: zep-cloud (>=2.7.0,<3.0.0)
+Requires-Dist: zep-python (>=2.0.2,<3.0.0)
+Project-URL: Repository, https://github.com/truemagic-coder/solana-agent
+Description-Content-Type: text/markdown
+
+# Solana Agent
+
+[![PyPI - Version](https://img.shields.io/pypi/v/solana-agent)](https://pypi.org/project/solana-agent/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/solana-agent?color=yellow)](https://pypi.org/project/solana-agent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-orange.svg)](https://www.python.org/downloads/)
+[![codecov](https://img.shields.io/codecov/c/github/truemagic-coder/solana-agent/main.svg)](https://codecov.io/gh/truemagic-coder/solana-agent)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/truemagic-coder/solana-agent/test.yml?branch=main)](https://github.com/truemagic-coder/solana-agent/actions/workflows/test.yml)
+
+![Solana Agent Logo](https://dl.walletbubbles.com/solana-agent-logo.png?width=200)
+
+## Features
+
+* Text streaming messages by AI Agents
+* Conversational memory per user shared by all AI Agents
+* Routing based on AI Agent specializations
+* Built-in Internet Search for all AI Agents
+* Organizational mission, values, goals, and guidance for all AI Agents
+* Robust AI Agent tool plugins based on standard python packages
+
+## Stack
+
+* [Python](https://python.org) - programming language
+* [OpenAI](https://openai.com) - LLMs
+* [MongoDB](https://mongodb.com) - database
+* [Zep](https://getzep.com) - conversational memory
+
+## Installation
+
+You can install Solana Agent using pip:
+
+`pip install solana-agent`
+
+## Documentation
+
+Each public method has a docstring for real-time IDE hinting.
+
+## Example App
+
+```python
+from solana_agent import SolanaAgent
+
+config = {
+    "organization": {
+        "mission_statement": "To revolutionize knowledge work through AI-human collaboration that puts people first.",
+        "values": {
+            "Human-Centered": "Always prioritize human well-being and augmentation over replacement.",
+            "Transparency": "Provide clear explanations for decisions and never hide information.",
+            "Collective Intelligence": "Value diverse perspectives and combine human and AI strengths.",
+            "Continuous Learning": "Embrace feedback and continuously improve based on experience."
+        },
+        "goals": [
+            "Enable human experts to focus on high-value creative work",
+            "Reduce administrative overhead through intelligent automation",
+            "Create seamless knowledge flow across the organization"
+        ],
+        "guidance": "When making decisions, prioritize long-term user success over short-term efficiency."
+    },
+    "mongo": {
+        "connection_string": "mongodb://localhost:27017",
+        "database": "solana_agent"
+    },
+    "openai": {
+        "api_key": "your-openai-key",
+        "default_model": "gpt-4o-mini"
+    },
+    "agents": [
+        {
+            "name": "research_specialist",
+            "instructions": "You are an expert researcher who synthesizes complex information clearly.",
+            "specialization": "Research and knowledge synthesis",
+            "model": "o3-mini",
+            "tools": ["some_tool"]
+        },
+        {
+            "name": "customer_support",
+            "instructions": "You provide friendly, helpful customer support responses.",
+            "specialization": "Customer inquiries",
+            "model": "gpt-4o-mini"
+        }
+    ],
+}
+
+# Create agent with configuration
+solana_agent = SolanaAgent(config=config)
+
+# Process a query that can use tools
+async for response in solana_agent.process("user123", "What are the latest AI developments?"):
+    print(response, end="")
+```
+
+## Solana Agent Kit
+
+[Solana Agent Kit](https://github.com/truemagic-coder/solana-agent-kit)
+
+## Example App
+
+[Solana Agent Example App](https://github.com/truemagic-coder/solana-agent-app)
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+

solana_agent-14.0.1/README.md

@@ -0,0 +1,102 @@
+# Solana Agent
+
+[![PyPI - Version](https://img.shields.io/pypi/v/solana-agent)](https://pypi.org/project/solana-agent/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/solana-agent?color=yellow)](https://pypi.org/project/solana-agent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-orange.svg)](https://www.python.org/downloads/)
+[![codecov](https://img.shields.io/codecov/c/github/truemagic-coder/solana-agent/main.svg)](https://codecov.io/gh/truemagic-coder/solana-agent)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/truemagic-coder/solana-agent/test.yml?branch=main)](https://github.com/truemagic-coder/solana-agent/actions/workflows/test.yml)
+
+![Solana Agent Logo](https://dl.walletbubbles.com/solana-agent-logo.png?width=200)
+
+## Features
+
+* Text streaming messages by AI Agents
+* Conversational memory per user shared by all AI Agents
+* Routing based on AI Agent specializations
+* Built-in Internet Search for all AI Agents
+* Organizational mission, values, goals, and guidance for all AI Agents
+* Robust AI Agent tool plugins based on standard python packages
+
+## Stack
+
+* [Python](https://python.org) - programming language
+* [OpenAI](https://openai.com) - LLMs
+* [MongoDB](https://mongodb.com) - database
+* [Zep](https://getzep.com) - conversational memory
+
+## Installation
+
+You can install Solana Agent using pip:
+
+`pip install solana-agent`
+
+## Documentation
+
+Each public method has a docstring for real-time IDE hinting.
+
+## Example App
+
+```python
+from solana_agent import SolanaAgent
+
+config = {
+    "organization": {
+        "mission_statement": "To revolutionize knowledge work through AI-human collaboration that puts people first.",
+        "values": {
+            "Human-Centered": "Always prioritize human well-being and augmentation over replacement.",
+            "Transparency": "Provide clear explanations for decisions and never hide information.",
+            "Collective Intelligence": "Value diverse perspectives and combine human and AI strengths.",
+            "Continuous Learning": "Embrace feedback and continuously improve based on experience."
+        },
+        "goals": [
+            "Enable human experts to focus on high-value creative work",
+            "Reduce administrative overhead through intelligent automation",
+            "Create seamless knowledge flow across the organization"
+        ],
+        "guidance": "When making decisions, prioritize long-term user success over short-term efficiency."
+    },
+    "mongo": {
+        "connection_string": "mongodb://localhost:27017",
+        "database": "solana_agent"
+    },
+    "openai": {
+        "api_key": "your-openai-key",
+        "default_model": "gpt-4o-mini"
+    },
+    "agents": [
+        {
+            "name": "research_specialist",
+            "instructions": "You are an expert researcher who synthesizes complex information clearly.",
+            "specialization": "Research and knowledge synthesis",
+            "model": "o3-mini",
+            "tools": ["some_tool"]
+        },
+        {
+            "name": "customer_support",
+            "instructions": "You provide friendly, helpful customer support responses.",
+            "specialization": "Customer inquiries",
+            "model": "gpt-4o-mini"
+        }
+    ],
+}
+
+# Create agent with configuration
+solana_agent = SolanaAgent(config=config)
+
+# Process a query that can use tools
+async for response in solana_agent.process("user123", "What are the latest AI developments?"):
+    print(response, end="")
+```
+
+## Solana Agent Kit
+
+[Solana Agent Kit](https://github.com/truemagic-coder/solana-agent-kit)
+
+## Example App
+
+[Solana Agent Example App](https://github.com/truemagic-coder/solana-agent-app)
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

{solana_agent-12.0.0 → solana_agent-14.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "solana-agent"
-version = "12.0.0"
+version = "14.0.1"
 description = "The Future of Work"
 authors = ["Bevan Hunt <bevan@bevanhunt.com>"]
 license = "MIT"
@@ -18,22 +18,16 @@ python_paths = [".", "tests"]
 
 [tool.poetry.dependencies]
 python = ">=3.12,<4.0"
-openai = "^1.66.3"
+openai = "^1.68.0"
 pydantic = "^2.10.6"
-pymongo = "^4.11.2"
+pymongo = "^4.11.3"
 zep-cloud = "^2.7.0"
 zep-python = "^2.0.2"
-requests = "^2.32.3"
-pinecone = "^6.0.2"
-pandas = "^2.2.3"
-ntplib = "^0.4.0"
-qdrant-client = "^1.13.3"
 
 [tool.poetry.dev-dependencies]
 pytest = "^8.3.5"
 pytest-cov = "^6.0.0"
 pytest-asyncio = "^0.25.3"
-uv = "^0.6.6"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

solana_agent-14.0.1/solana_agent/__init__.py

@@ -0,0 +1,33 @@
+"""
+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-14.0.1/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-14.0.1/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-14.0.1/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-14.0.1/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-14.0.1/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-14.0.1/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-14.0.1/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")