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

solana_agent/client/solana_agent.py

@@ -4,14 +4,19 @@ 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, Literal, Optional, Union
+from typing import AsyncGenerator, Dict, Any, List, Literal, Optional, Type, Union
+
+from pydantic import BaseModel
 
 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
+from solana_agent.interfaces.providers.realtime import RealtimeChunk
 
 
 class SolanaAgent(SolanaAgentInterface):
@@ -33,8 +38,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
@@ -46,29 +50,72 @@ class SolanaAgent(SolanaAgentInterface):
         user_id: str,
         message: Union[str, bytes],
         prompt: Optional[str] = None,
+        capture_schema: Optional[Dict[str, Any]] = None,
+        capture_name: Optional[str] = None,
         output_format: Literal["text", "audio"] = "text",
-        audio_voice: Literal["alloy", "ash", "ballad", "coral", "echo",
-                             "fable", "onyx", "nova", "sage", "shimmer"] = "nova",
-        audio_instructions: Optional[str] = None,
-        audio_output_format: Literal['mp3', 'opus',
-                                     'aac', 'flac', 'wav', 'pcm'] = "aac",
+        # Realtime (WebSocket) options — used when realtime=True
+        realtime: bool = False,
+        vad: Optional[bool] = False,
+        rt_encode_input: bool = False,
+        rt_encode_output: bool = False,
+        rt_output_modalities: Optional[List[Literal["audio", "text"]]] = None,
+        rt_voice: Literal[
+            "alloy",
+            "ash",
+            "ballad",
+            "cedar",
+            "coral",
+            "echo",
+            "marin",
+            "sage",
+            "shimmer",
+            "verse",
+        ] = "marin",
+        audio_voice: Literal[
+            "alloy",
+            "ash",
+            "ballad",
+            "coral",
+            "echo",
+            "fable",
+            "onyx",
+            "nova",
+            "sage",
+            "shimmer",
+        ] = "nova",
+        audio_output_format: Literal[
+            "mp3", "opus", "aac", "flac", "wav", "pcm"
+        ] = "aac",
         audio_input_format: Literal[
             "flac", "mp3", "mp4", "mpeg", "mpga", "m4a", "ogg", "wav", "webm"
         ] = "mp4",
         router: Optional[RoutingInterface] = None,
-    ) -> AsyncGenerator[Union[str, bytes], None]:  # pragma: no cover
-        """Process a user message and return the response stream.
+        images: Optional[List[Union[str, bytes]]] = None,
+        output_model: Optional[Type[BaseModel]] = None,
+    ) -> AsyncGenerator[
+        Union[str, bytes, BaseModel, RealtimeChunk], None
+    ]:  # pragma: no cover
+        """Process a user message (text or audio) and optional images, returning the response stream.
 
         Args:
             user_id: User ID
             message: Text message or audio bytes
             prompt: Optional prompt for the agent
             output_format: Response format ("text" or "audio")
+            capture_schema: Optional Pydantic schema for structured output
+            capture_name: Optional name for structured output capture
+            realtime: Whether to use realtime (WebSocket) processing
+            vad: Whether to use voice activity detection (for audio input)
+            rt_encode_input: Whether to re-encode input audio for compatibility
+            rt_encode_output: Whether to re-encode output audio for compatibility
+            rt_output_modalities: Modalities to return in realtime (default both if None)
+            rt_voice: Voice to use for realtime audio output
             audio_voice: Voice to use for audio output
-            audio_instructions: Not used currently
             audio_output_format: Audio output format
             audio_input_format: Audio input format
             router: Optional routing service for processing
+            images: Optional list of image URLs (str) or image bytes.
+            output_model: Optional Pydantic model for structured output
 
         Returns:
             Async generator yielding response chunks (text strings or audio bytes)
@@ -76,13 +123,22 @@ class SolanaAgent(SolanaAgentInterface):
         async for chunk in self.query_service.process(
             user_id=user_id,
             query=message,
+            images=images,
             output_format=output_format,
+            realtime=realtime,
+            vad=vad,
+            rt_encode_input=rt_encode_input,
+            rt_encode_output=rt_encode_output,
+            rt_output_modalities=rt_output_modalities,
+            rt_voice=rt_voice,
             audio_voice=audio_voice,
-            audio_instructions=audio_instructions,
             audio_output_format=audio_output_format,
             audio_input_format=audio_input_format,
             prompt=prompt,
             router=router,
+            output_model=output_model,
+            capture_schema=capture_schema,
+            capture_name=capture_name,
         ):
             yield chunk
 
@@ -100,7 +156,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.
@@ -118,21 +174,125 @@ class SolanaAgent(SolanaAgentInterface):
             user_id, page_num, page_size, sort_order
         )
 
-    def register_tool(self, tool: Tool) -> bool:
+    def register_tool(self, agent_name: str, tool: Tool) -> bool:
         """
         Register a tool with the agent system.
 
         Args:
+            agent_name: Name of the agent to register the tool with
             tool: Tool instance to register
 
         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:
-            agents = self.query_service.agent_service.get_all_ai_agents()
-            for agent_name in agents:
-                self.query_service.agent_service.assign_tool_for_agent(
-                    agent_name, tool.name)
+            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_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/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, Optional, Any
 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,9 +51,14 @@ 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")
+    capture_name: Optional[str] = Field(
+        default=None, description="Optional capture name for structured data"
+    )
+    capture_schema: Optional[Dict[str, Any]] = Field(
+        default=None, description="Optional JSON schema for structured capture"
+    )
 
     @field_validator("name", "specialization")
     @classmethod

solana_agent/domains/routing.py

@@ -4,11 +4,21 @@ 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")
+
+    primary_agent: str = Field(
+        ...,
+        description="Name of the primary agent that should handle this query (must be one of the available agent names)",
+    )
+    secondary_agents: List[str] = Field(
+        default_factory=list,
+        description="Names of secondary agents that might be helpful (must be from the available agent names)",
+    )
+    complexity_level: int = Field(
+        default=1, description="Complexity level (1-5)", ge=1, le=5
+    )
+    topics: List[str] = Field(
+        default_factory=list, description="Key topics in the query"
+    )
+    confidence: float = Field(
+        default=0.5, description="Confidence in the analysis", ge=0.0, le=1.0
+    )