solana-agent 27.1.0__py3-none-any.whl → 27.3.0__py3-none-any.whl

solana_agent/client/solana_agent.py

@@ -6,11 +6,12 @@ the agent system without dealing with internal implementation details.
 """
 import json
 import importlib.util
-from typing import AsyncGenerator, Dict, Any, Literal, Optional, Union
+from typing import AsyncGenerator, Dict, Any, List, Literal, Optional, Union
 
 from solana_agent.factories.agent_factory import SolanaAgentFactory
 from solana_agent.interfaces.client.client import SolanaAgent as SolanaAgentInterface
 from solana_agent.interfaces.plugins.plugins import Tool
+from solana_agent.services.knowledge_base import KnowledgeBaseService
 from solana_agent.interfaces.services.routing import RoutingService as RoutingInterface
 
 
@@ -135,3 +136,146 @@ class SolanaAgent(SolanaAgentInterface):
             self.query_service.agent_service.assign_tool_for_agent(
                 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:
+            return self.query_service.knowledge_base
+        else:
+            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
+    ) -> str:
+        """
+        Add a document to the knowledge base.
+
+        Args:
+            text: Document text content.
+            metadata: Document metadata.
+            document_id: Optional document ID.
+            namespace: Optional Pinecone namespace.
+
+        Returns:
+            The document ID.
+        """
+        kb = self._ensure_kb()
+        return await kb.add_document(text, metadata, document_id, namespace)
+
+    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.
+
+        Args:
+            query_text: Search query text.
+            filter: Optional filter criteria.
+            top_k: Maximum number of results.
+            namespace: Optional Pinecone namespace.
+            include_content: Include document content in results.
+            include_metadata: Include document metadata in results.
+
+        Returns:
+            List of matching documents.
+        """
+        kb = self._ensure_kb()
+        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
+    ) -> bool:
+        """
+        Delete a document from the knowledge base.
+
+        Args:
+            document_id: ID of document to delete.
+            namespace: Optional Pinecone namespace.
+
+        Returns:
+            True if successful.
+        """
+        kb = self._ensure_kb()
+        return await kb.delete_document(document_id, namespace)
+
+    async def kb_update_document(
+        self,
+        document_id: str,
+        text: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        namespace: Optional[str] = None
+    ) -> bool:
+        """
+        Update an existing document in the knowledge base.
+
+        Args:
+            document_id: ID of document to update.
+            text: Optional new text content.
+            metadata: Optional metadata to update.
+            namespace: Optional Pinecone namespace.
+
+        Returns:
+            True if successful.
+        """
+        kb = self._ensure_kb()
+        return await kb.update_document(document_id, text, metadata, namespace)
+
+    async def kb_add_documents_batch(
+        self,
+        documents: List[Dict[str, Any]],
+        namespace: Optional[str] = None,
+        batch_size: int = 50
+    ) -> List[str]:
+        """
+        Add multiple documents to the knowledge base in batches.
+
+        Args:
+            documents: List of documents ({'text': ..., 'metadata': ...}).
+            namespace: Optional Pinecone namespace.
+            batch_size: Number of documents per batch.
+
+        Returns:
+            List of added document IDs.
+        """
+        kb = self._ensure_kb()
+        return await kb.add_documents_batch(documents, namespace, batch_size)
+
+    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 via the client.
+
+        Args:
+            pdf_data: PDF content as bytes or a path to the PDF file.
+            metadata: Document metadata.
+            document_id: Optional parent document ID.
+            namespace: Optional Pinecone namespace for chunks.
+            chunk_batch_size: Batch size for upserting chunks.
+
+        Returns:
+            The parent document ID.
+        """
+        kb = self._ensure_kb()
+        # 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)

solana_agent/factories/agent_factory.py

@@ -7,15 +7,17 @@ services and components used in the system.
 from typing import Dict, Any
 
 # Service imports
+from solana_agent.adapters.pinecone_adapter import PineconeAdapter
 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
 
 # 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
@@ -39,11 +41,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"]:
-                raise ValueError("MongoDB database name is required.")
             db_adapter = MongoDBAdapter(
                 connection_string=config["mongo"]["connection_string"],
                 database_name=config["mongo"]["database"],
@@ -71,8 +68,6 @@ class SolanaAgentFactory:
         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(
                 mongo_adapter=db_adapter, zep_api_key=config["zep"].get("api_key"))
 
@@ -198,11 +193,82 @@ class SolanaAgentFactory:
                     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
+
+                # 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)
+                )
+                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
+
         # 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
         )
 
         return query_service

solana_agent/interfaces/client/client.py

@@ -1,12 +1,11 @@
 from abc import ABC, abstractmethod
-from typing import Any, AsyncGenerator, Dict, Literal, Optional, Union
-
+from typing import AsyncGenerator, Dict, Any, List, Literal, Optional, Union
 from solana_agent.interfaces.plugins.plugins import Tool
 from solana_agent.interfaces.services.routing import RoutingService as RoutingInterface
 
 
 class SolanaAgent(ABC):
-    """Interface for the Solana agent system."""
+    """Interface for the Solana Agent client."""
 
     @abstractmethod
     async def process(
@@ -28,18 +27,89 @@ class SolanaAgent(ABC):
         """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, agent_name: str, tool: Tool) -> bool:
-        """Register a tool in the registry."""
+        """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_update_document(
+        self,
+        document_id: str,
+        text: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        namespace: Optional[str] = None
+    ) -> bool:
+        """Update an existing document in the knowledge base."""
+        pass
+
+    @abstractmethod
+    async def kb_add_documents_batch(
+        self,
+        documents: List[Dict[str, Any]],
+        namespace: Optional[str] = None,
+        batch_size: int = 50
+    ) -> List[str]:
+        """Add multiple documents to the knowledge base in batches."""
+        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/providers/llm.py

@@ -57,3 +57,23 @@ class LLMProvider(ABC):
     ) -> AsyncGenerator[str, None]:
         """Transcribe audio from the language model."""
         pass
+
+    @abstractmethod
+    async def embed_text(
+        self,
+        text: str,
+        model: Optional[str] = None,
+        dimensions: Optional[int] = None
+    ) -> List[float]:
+        """
+        Generate an embedding for the given text.
+
+        Args:
+            text: The text to embed.
+            model: The embedding model to use.
+            dimensions: Optional desired output dimensions for the embedding.
+
+        Returns:
+            A list of floats representing the embedding vector.
+        """
+        pass

solana_agent/interfaces/providers/vector_storage.py

@@ -0,0 +1,59 @@
+from typing import List, Dict, Any, Optional
+
+
+class VectorStorageProvider:
+    """Interface for Vector Storage Providers."""
+
+    async def upsert(
+        self,
+        vectors: List[Dict[str, Any]],
+        namespace: Optional[str] = None
+    ) -> None:
+        """Upsert vectors into the storage."""
+        pass
+
+    async def upsert_text(
+        self,
+        texts: List[str],
+        ids: List[str],
+        metadatas: Optional[List[Dict[str, Any]]] = None,
+        namespace: Optional[str] = None
+    ) -> None:
+        """Embeds texts and upserts them into the storage."""
+        pass
+
+    async def query(
+        self,
+        vector: List[float],
+        top_k: int = 5,
+        namespace: Optional[str] = None,
+        filter: Optional[Dict[str, Any]] = None,
+        include_values: bool = False,
+        include_metadata: bool = True,
+    ) -> List[Dict[str, Any]]:
+        """Query for similar vectors."""
+        pass
+
+    async def query_text(
+        self,
+        query_text: str,
+        top_k: Optional[int] = None,
+        namespace: Optional[str] = None,
+        filter: Optional[Dict[str, Any]] = None,
+        include_values: bool = False,
+        include_metadata: bool = True,
+    ) -> List[Dict[str, Any]]:
+        """Embeds query text and queries the storage."""
+        pass
+
+    async def delete(
+        self,
+        ids: List[str],
+        namespace: Optional[str] = None
+    ) -> None:
+        """Delete vectors by IDs."""
+        pass
+
+    async def describe_index_stats(self) -> Dict[str, Any]:
+        """Get statistics about the index/collection."""
+        pass

solana_agent/interfaces/services/knowledge_base.py

@@ -0,0 +1,86 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List, Any, Optional, Union
+
+
+class KnowledgeBaseService(ABC):
+    """
+    Interface for a Knowledge Base service.
+    """
+
+    @abstractmethod
+    async def 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 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 with semantic search.
+        """
+        pass
+
+    @abstractmethod
+    async def delete_document(
+        self,
+        document_id: str,
+        namespace: Optional[str] = None
+    ) -> bool:
+        """
+        Delete a document from the knowledge base.
+        """
+        pass
+
+    @abstractmethod
+    async def update_document(
+        self,
+        document_id: str,
+        text: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        namespace: Optional[str] = None
+    ) -> bool:
+        """
+        Update an existing document in the knowledge base.
+        """
+        pass
+
+    @abstractmethod
+    async def add_documents_batch(
+        self,
+        documents: List[Dict[str, Any]],
+        namespace: Optional[str] = None,
+        batch_size: int = 50
+    ) -> List[str]:
+        """
+        Add multiple documents in batches.
+        """
+        pass
+
+    @abstractmethod
+    async def add_pdf_document(
+        self,
+        pdf_data: Union[bytes, str],  # PDF bytes or file path
+        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