solana-agent 0.0.6__py3-none-any.whl → 0.0.7__py3-none-any.whl

solana_agent/ai.py

@@ -2,53 +2,38 @@ import asyncio
 from datetime import datetime
 import json
 from typing import AsyncGenerator, List, Literal, Optional, Dict, Any, Callable
+import uuid
 from pydantic import BaseModel
 from motor.motor_asyncio import AsyncIOMotorClient
 from openai import OpenAI
-import openai
-import aiosqlite
 from openai import AssistantEventHandler
 from openai.types.beta.threads import TextDelta, Text
 from typing_extensions import override
-import sqlite3
 import inspect
 import requests
-from zep_python.client import AsyncZep
-from zep_python.client import Zep
-from zep_python.types import Message, RoleType
+from zep_cloud.client import AsyncZep
+from zep_cloud.client import Zep
+from zep_cloud.types import Message, RoleType
 import pandas as pd
-
-
-def adapt_datetime(ts):
-    return ts.isoformat()
-
-
-# Custom converter for datetime
-def convert_datetime(ts):
-    return datetime.fromisoformat(ts)
-
-
-# Register the adapter and converter
-sqlite3.register_adapter(datetime, adapt_datetime)
-sqlite3.register_converter("timestamp", convert_datetime)
+from pinecone import Pinecone
 
 
 class EventHandler(AssistantEventHandler):
     def __init__(self, tool_handlers, ai_instance):
         super().__init__()
-        self.tool_handlers = tool_handlers
-        self.ai_instance = ai_instance
+        self._tool_handlers = tool_handlers
+        self._ai_instance = ai_instance
 
     @override
     def on_text_delta(self, delta: TextDelta, snapshot: Text):
         asyncio.create_task(
-            self.ai_instance.accumulated_value_queue.put(delta.value))
+            self._ai_instance.accumulated_value_queue.put(delta.value))
 
     @override
     def on_event(self, event):
         if event.event == "thread.run.requires_action":
             run_id = event.data.id
-            self.ai_instance.handle_requires_action(event.data, run_id)
+            self._ai_instance._handle_requires_action(event.data, run_id)
 
 
 class ToolConfig(BaseModel):
@@ -59,108 +44,24 @@ class ToolConfig(BaseModel):
 
 class MongoDatabase:
     def __init__(self, db_url: str, db_name: str):
-        self.client = AsyncIOMotorClient(db_url)
-        self.db = self.client[db_name]
-        self.threads = self.db["threads"]
-        self.messages = self.db["messages"]
+        self._client = AsyncIOMotorClient(db_url)
+        self._db = self.client[db_name]
+        self._threads = self.db["threads"]
+        self._messages = self.db["messages"]
 
     async def save_thread_id(self, user_id: str, thread_id: str):
-        await self.threads.insert_one({"thread_id": thread_id, "user_id": user_id})
+        await self._threads.insert_one({"thread_id": thread_id, "user_id": user_id})
 
     async def get_thread_id(self, user_id: str) -> Optional[str]:
-        document = await self.threads.find_one({"user_id": user_id})
+        document = await self._threads.find_one({"user_id": user_id})
         return document["thread_id"] if document else None
 
     async def save_message(self, user_id: str, metadata: Dict[str, Any]):
         metadata["user_id"] = user_id
-        await self.messages.insert_one(metadata)
-
-    async def delete_thread_id(self, user_id: str):
-        document = await self.threads.find_one({"user_id": user_id})
-        thread_id = document["thread_id"]
-        openai.beta.threads.delete(thread_id)
-        await self.messages.delete_many({"user_id": user_id})
-        await self.threads.delete_one({"user_id": user_id})
+        await self._messages.insert_one(metadata)
 
     async def delete_all_threads(self):
-        await self.threads.delete_many({})
-        await self.messages.delete_many({})
-
-
-class SQLiteDatabase:
-    def __init__(self, db_path: str):
-        self.db_path = db_path
-        self.conn = sqlite3.connect(db_path)
-        self.conn.execute(
-            "CREATE TABLE IF NOT EXISTS threads (user_id TEXT, thread_id TEXT)"
-        )
-        self.conn.execute(
-            "CREATE TABLE IF NOT EXISTS messages (user_id TEXT, message TEXT, response TEXT, timestamp TEXT)"
-        )
-        self.conn.commit()
-        self.conn.close()
-
-    async def save_thread_id(self, user_id: str, thread_id: str):
-        async with aiosqlite.connect(
-            self.db_path, detect_types=sqlite3.PARSE_DECLTYPES
-        ) as db:
-            await db.execute(
-                "INSERT INTO threads (user_id, thread_id) VALUES (?, ?)",
-                (user_id, thread_id),
-            )
-            await db.commit()
-
-    async def get_thread_id(self, user_id: str) -> Optional[str]:
-        async with aiosqlite.connect(
-            self.db_path, detect_types=sqlite3.PARSE_DECLTYPES
-        ) as db:
-            async with db.execute(
-                "SELECT thread_id FROM threads WHERE user_id = ?", (user_id,)
-            ) as cursor:
-                row = await cursor.fetchone()
-                return row[0] if row else None
-
-    async def save_message(self, user_id: str, metadata: Dict[str, Any]):
-        async with aiosqlite.connect(
-            self.db_path, detect_types=sqlite3.PARSE_DECLTYPES
-        ) as db:
-            await db.execute(
-                "INSERT INTO messages (user_id, message, response, timestamp) VALUES (?, ?, ?, ?)",
-                (
-                    user_id,
-                    metadata["message"],
-                    metadata["response"],
-                    metadata["timestamp"],
-                ),
-            )
-            await db.commit()
-
-    async def delete_thread_id(self, user_id: str):
-        async with aiosqlite.connect(
-            self.db_path, detect_types=sqlite3.PARSE_DECLTYPES
-        ) as db:
-            async with db.execute(
-                "SELECT thread_id FROM threads WHERE user_id = ?", (user_id,)
-            ) as cursor:
-                row = await cursor.fetchone()
-                if row:
-                    thread_id = row[0]
-                    openai.beta.threads.delete(thread_id)
-                    await db.execute(
-                        "DELETE FROM messages WHERE user_id = ?", (user_id,)
-                    )
-                    await db.execute(
-                        "DELETE FROM threads WHERE user_id = ?", (user_id,)
-                    )
-                    await db.commit()
-
-    async def delete_all_threads(self):
-        async with aiosqlite.connect(
-            self.db_path, detect_types=sqlite3.PARSE_DECLTYPES
-        ) as db:
-            await db.execute("DELETE FROM messages")
-            await db.execute("DELETE FROM threads")
-            await db.commit()
+        await self._threads.delete_many({})
 
 
 class AI:
@@ -171,49 +72,93 @@ class AI:
         instructions: str,
         database: Any,
         zep_api_key: str = None,
-        zep_base_url: str = None,
         perplexity_api_key: str = None,
         grok_api_key: str = None,
         gemini_api_key: str = None,
+        pinecone_api_key: str = None,
+        pinecone_index_name: str = None,
         code_interpreter: bool = True,
-        model: Literal["gpt-4o-mini", "gpt-4o"] = "gpt-4o-mini",
+        openai_assistant_model: Literal["gpt-4o-mini",
+                                        "gpt-4o"] = "gpt-4o-mini",
+        openai_embedding_model: Literal["text-embedding-3-small",
+                                        "text-embedding-3-large"] = "text-embedding-3-small"
     ):
-        self.client = OpenAI(api_key=openai_api_key)
-        self.name = name
-        self.instructions = instructions
-        self.model = model
-        self.tools = [{"type": "code_interpreter"}] if code_interpreter else []
-        self.tool_handlers = {}
-        self.assistant_id = None
-        self.database = database
-        self.accumulated_value_queue = asyncio.Queue()
-        self.zep = (
-            AsyncZep(api_key=zep_api_key, base_url=zep_base_url)
+        """Initialize a new AI assistant with memory and tool integration capabilities.
+
+        Args:
+            openai_api_key (str): OpenAI API key for core AI functionality
+            name (str): Name identifier for the assistant
+            instructions (str): Base behavioral instructions for the AI
+            database (Any): Database instance for message/thread storage
+            zep_api_key (str, optional): API key for Zep memory integration. Defaults to None
+            perplexity_api_key (str, optional): API key for Perplexity search. Defaults to None
+            grok_api_key (str, optional): API key for X/Twitter search via Grok. Defaults to None
+            gemini_api_key (str, optional): API key for Google Gemini. Defaults to None
+            pinecone_api_key (str, optional): API key for Pinecone. Defaults to None
+            pinecone_index_name (str, optional): Pinecone index name. Defaults to None
+            code_interpreter (bool, optional): Enable code interpretation. Defaults to True
+            openai_assistant_model (Literal["gpt-4o-mini", "gpt-4o"], optional): OpenAI model for assistant. Defaults to "gpt-4o-mini"
+            openai_embedding_model (Literal["text-embedding-3-small", "text-embedding-3-large"], optional): OpenAI model for text embedding. Defaults to "text-embedding-3-small"
+
+        Example:
+            ```python
+            ai = AI(
+                openai_api_key="your-key",
+                name="Assistant",
+                instructions="Be helpful and concise",
+                database=MongoDatabase("mongodb://localhost", "ai_db"),
+            )
+            ```
+        Notes:
+            - Requires valid OpenAI API key for core functionality
+            - Database instance for storing messages and threads
+            - Optional integrations for Zep, Perplexity, Grok, Gemini, Pinecone, and Cohere
+            - Supports code interpretation and custom tool functions
+            - You must create the Pinecone index in the dashboard before using it
+        """
+        self._client = OpenAI(api_key=openai_api_key)
+        self._name = name
+        self._instructions = instructions
+        self._openai_assistant_model = openai_assistant_model
+        self._openai_embedding_model = openai_embedding_model
+        self._tools = [{"type": "code_interpreter"}
+                       ] if code_interpreter else []
+        self._tool_handlers = {}
+        self._assistant_id = None
+        self._database = database
+        self._accumulated_value_queue = asyncio.Queue()
+        self._zep = (
+            AsyncZep(api_key=zep_api_key)
             if zep_api_key
             else None
         )
-        self.sync_zep = (
-            Zep(api_key=zep_api_key, base_url=zep_base_url) if zep_api_key else None
+        self._sync_zep = (
+            Zep(api_key=zep_api_key) if zep_api_key else None
         )
-        self.perplexity_api_key = perplexity_api_key
-        self.grok_api_key = grok_api_key
-        self.gemini_api_key = gemini_api_key
+        self._perplexity_api_key = perplexity_api_key
+        self._grok_api_key = grok_api_key
+        self._gemini_api_key = gemini_api_key
+        self._pinecone = Pinecone(
+            api_key=pinecone_api_key) if pinecone_api_key else None
+        self._pinecone_index_name = pinecone_index_name if pinecone_index_name else None
+        self._pinecone_index = self._pinecone.Index(
+            self._pinecone_index_name) if self._pinecone else None
 
     async def __aenter__(self):
-        assistants = openai.beta.assistants.list()
+        assistants = self._client.beta.assistants.list()
         existing_assistant = next(
-            (a for a in assistants if a.name == self.name), None)
+            (a for a in assistants if a.name == self._name), None)
 
         if existing_assistant:
-            self.assistant_id = existing_assistant.id
+            self._assistant_id = existing_assistant.id
         else:
-            self.assistant_id = openai.beta.assistants.create(
+            self._assistant_id = self._client.beta.assistants.create(
                 name=self.name,
-                instructions=self.instructions,
-                tools=self.tools,
-                model=self.model,
+                instructions=self._instructions,
+                tools=self._tools,
+                model=self._openai_assistant_model,
             ).id
-            await self.database.delete_all_threads()
+            await self._database.delete_all_threads()
 
         return self
 
@@ -221,51 +166,166 @@ class AI:
         # Perform any cleanup actions here
         pass
 
-    async def create_thread(self, user_id: str) -> str:
-        thread_id = await self.database.get_thread_id(user_id)
+    async def _create_thread(self, user_id: str) -> str:
+        thread_id = await self._database.get_thread_id(user_id)
 
         if thread_id is None:
-            thread = openai.beta.threads.create()
+            thread = self._client.beta.threads.create()
             thread_id = thread.id
-            await self.database.save_thread_id(user_id, thread_id)
-            if self.zep:
-                await self.zep.user.add(user_id=user_id)
-                await self.zep.memory.add_session(user_id=user_id, session_id=user_id)
+            await self._database.save_thread_id(user_id, thread_id)
+            if self._zep:
+                await self._zep.user.add(user_id=user_id)
+                await self._zep.memory.add_session(user_id=user_id, session_id=user_id)
 
         return thread_id
 
-    async def cancel_run(self, thread_id: str, run_id: str):
+    async def _cancel_run(self, thread_id: str, run_id: str):
         try:
-            self.client.beta.threads.runs.cancel(
+            self._client.beta.threads.runs.cancel(
                 thread_id=thread_id, run_id=run_id)
         except Exception as e:
             print(f"Error cancelling run: {e}")
 
-    async def get_active_run(self, thread_id: str) -> Optional[str]:
-        runs = self.client.beta.threads.runs.list(thread_id=thread_id, limit=1)
+    async def _get_active_run(self, thread_id: str) -> Optional[str]:
+        runs = self._client.beta.threads.runs.list(
+            thread_id=thread_id, limit=1)
         for run in runs:
             if run.status in ["in_progress"]:
                 return run.id
         return None
 
-    async def get_run_status(self, thread_id: str, run_id: str) -> str:
-        run = self.client.beta.threads.runs.retrieve(
+    async def _get_run_status(self, thread_id: str, run_id: str) -> str:
+        run = self._client.beta.threads.runs.retrieve(
             thread_id=thread_id, run_id=run_id)
         return run.status
 
     # converter tool - has to be sync
     def csv_to_json(self, file_path: str) -> str:
+        """Convert CSV file to JSON string format.
+
+        Args:
+            file_path (str): Path to the CSV file to convert
+
+        Returns:
+            str: JSON string containing the CSV data
+
+        Example:
+            ```python
+            result = ai.csv_to_json("data.csv")
+            # Returns: '[{"column1": "value1", "column2": "value2"}]'
+            ```
+
+        Note:
+            This is a synchronous tool method required for OpenAI function calling.
+        """
         df = pd.read_csv(file_path)
         records = df.to_dict(orient="records")
         return json.dumps(records)
 
+    # search kb tool - has to be sync
+    def search_kb(self, query: str, limit: int = 10) -> str:
+        """Search Pinecone knowledge base using OpenAI embeddings.
+
+        Args:
+            query (str): Search query to find relevant documents
+            limit (int, optional): Maximum number of results to return. Defaults to 10.
+
+        Returns:
+            str: JSON string of matched documents or error message
+
+        Example:
+            ```python
+            results = ai.search_kb("machine learning basics", limit=5)
+            # Returns: '[{"title": "ML Intro", "content": "..."}]'
+            ```
+
+        Note:
+            - Requires configured Pinecone index
+            - Uses OpenAI embeddings for semantic search
+            - Returns JSON-serialized Pinecone match metadata results
+            - Returns error message string if search fails
+        """
+        try:
+            response = self._client.embeddings.create(
+                input=query,
+                model=self._openai_embedding_model,
+            )
+            search_results = self._pinecone_index.query(
+                vector=response.data[0].embedding, top_k=limit, include_metadata=True, include_values=False)
+            matches = search_results.matches
+            metadata = [match.metadata for match in matches]
+            return json.dumps(metadata)
+        except Exception as e:
+            return f"Failed to search KB. Error: {e}"
+
+    # add document to kb tool - has to be sync
+    def add_document_to_kb(self, document: Dict[str, str]):
+        """Add a document to the Pinecone knowledge base with OpenAI embeddings.
+
+        Args:
+            document (Dict[str, str]): Document to add, with string fields as values
+
+        Example:
+            ```python
+            ai.add_document_to_kb({
+                "title": "AI Basics",
+                "content": "Introduction to artificial intelligence...",
+                "author": "John Doe"
+            })
+            ```
+
+        Note:
+            - Requires Pinecone index to be configured
+            - Uses OpenAI embeddings API
+            - Document values must be strings
+            - Automatically generates UUID for document
+        """
+        values: List[str] = []
+        for _, v in document.items():
+            values.append(v)
+        response = self._client.embeddings.create(
+            input=values,
+            model=self._openai_embedding_model,
+        )
+        self._pinecone_index.upsert(
+            vectors=[
+                {
+                    "id": uuid.uuid4().hex,
+                    "values": response.data[0].embedding,
+                    "metadata": document,
+                }
+            ]
+        )
+
     # summarize tool - has to be sync
     def summarize(
-        self, text: str, model: Literal["gemini-2.0-flash"] = "gemini-2.0-flash"
+        self, text: str, model: Literal["gemini-2.0-flash", "gemini-1.5-pro"] = "gemini-1.5-pro"
     ) -> str:
+        """Summarize text using Google's Gemini language model.
+
+        Args:
+            text (str): The text content to be summarized
+            model (Literal["gemini-2.0-flash", "gemini-1.5-pro"], optional): 
+                Gemini model to use. Defaults to "gemini-1.5-pro"
+                - gemini-2.0-flash: Faster, shorter summaries
+                - gemini-1.5-pro: More detailed summaries
+
+        Returns:
+            str: Summarized text or error message if summarization fails
+
+        Example:
+            ```python
+            summary = ai.summarize("Long article text here...", model="gemini-1.5-pro")
+            # Returns: "Concise summary of the article..."
+            ```
+
+        Note:
+            This is a synchronous tool method required for OpenAI function calling.
+            Requires valid Gemini API key to be configured.
+        """
         try:
             client = OpenAI(
-                api_key=self.gemini_api_key,
+                api_key=self._gemini_api_key,
                 base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
             )
 
@@ -291,9 +351,33 @@ class AI:
         query: str,
         limit: int | None = None,
     ) -> List[str] | None:
-        if self.sync_zep:
+        """Search stored conversation facts using Zep memory integration.
+
+        Args:
+            user_id (str): Unique identifier for the user
+            query (str): Search query to find relevant facts
+            limit (int | None, optional): Maximum number of facts to return. Defaults to None.
+
+        Returns:
+            List[str] | None: List of found facts or None if Zep is not configured
+
+        Example:
+            ```python
+            facts = ai.search_facts(
+                user_id="user123",
+                query="project requirements",
+                limit=5
+            )
+            # Returns: ["Fact 1", "Fact 2", ...]
+            ```
+
+        Note:
+            Requires Zep integration to be configured with valid API key and URL.
+            This is a synchronous tool method required for OpenAI function calling.
+        """
+        if self._sync_zep:
             facts = []
-            results = self.sync_zep.memory.search_sessions(
+            results = self._sync_zep.memory.search_sessions(
                 user_id=user_id,
                 text=query,
                 limit=limit,
@@ -313,6 +397,33 @@ class AI:
             "sonar", "sonar-pro", "sonar-reasoning-pro", "sonar-reasoning"
         ] = "sonar",
     ) -> str:
+        """Search the internet using Perplexity AI API.
+
+        Args:
+            query (str): Search query string
+            model (Literal["sonar", "sonar-pro", "sonar-reasoning-pro", "sonar-reasoning"], optional): 
+                Perplexity model to use. Defaults to "sonar"
+                - sonar: Fast, general-purpose search
+                - sonar-pro: Enhanced search capabilities
+                - sonar-reasoning-pro: Advanced reasoning with search
+                - sonar-reasoning: Basic reasoning with search
+
+        Returns:
+            str: Search results or error message if search fails
+
+        Example:
+            ```python
+            result = ai.search_internet(
+                query="Latest AI developments",
+                model="sonar-reasoning-pro"
+            )
+            # Returns: "Detailed search results about AI..."
+            ```
+
+        Note:
+            Requires valid Perplexity API key to be configured.
+            This is a synchronous tool method required for OpenAI function calling.
+        """
         try:
             url = "https://api.perplexity.ai/chat/completions"
 
@@ -330,7 +441,7 @@ class AI:
                 ],
             }
             headers = {
-                "Authorization": f"Bearer {self.perplexity_api_key}",
+                "Authorization": f"Bearer {self._perplexity_api_key}",
                 "Content-Type": "application/json",
             }
 
@@ -354,12 +465,43 @@ class AI:
         use_perplexity: bool = True,
         use_grok: bool = True,
         use_facts: bool = True,
+        use_kb=True,
         perplexity_model: Literal[
             "sonar", "sonar-pro", "sonar-reasoning-pro", "sonar-reasoning"
         ] = "sonar",
         openai_model: Literal["o1", "o3-mini"] = "o3-mini",
         grok_model: Literal["grok-beta"] = "grok-beta",
     ) -> str:
+        """Combine multiple data sources with AI reasoning to answer queries.
+
+        Args:
+            user_id (str): Unique identifier for the user
+            query (str): The question or query to reason about
+            use_perplexity (bool, optional): Include Perplexity search results. Defaults to True
+            use_grok (bool, optional): Include X/Twitter search results. Defaults to True
+            use_facts (bool, optional): Include stored conversation facts. Defaults to True
+            use_kb (bool, optional): Include Pinecone knowledge base search results. Defaults to True
+            perplexity_model (Literal, optional): Perplexity model to use. Defaults to "sonar"
+            openai_model (Literal, optional): OpenAI model for reasoning. Defaults to "o3-mini"
+            grok_model (Literal, optional): Grok model for X search. Defaults to "grok-beta"
+
+        Returns:
+            str: Reasoned response combining all enabled data sources or error message
+
+        Example:
+            ```python
+            result = ai.reason(
+                user_id="user123",
+                query="What are the latest AI trends?",
+            )
+            # Returns: "Based on multiple sources: [comprehensive answer]"
+            ```
+
+        Note:
+            This is a synchronous tool method required for OpenAI function calling.
+            Requires configuration of relevant API keys for enabled data sources.
+            Will gracefully handle missing or failed data sources.
+        """
         try:
             if use_facts:
                 facts = self.search_facts(user_id, query)
@@ -375,8 +517,12 @@ class AI:
                 x_search_results = self.search_x(query, grok_model)
             else:
                 x_search_results = ""
+            if use_kb:
+                kb_results = self.search_kb(query)
+            else:
+                kb_results = ""
 
-            response = self.client.chat.completions.create(
+            response = self._client.chat.completions.create(
                 model=openai_model,
                 messages=[
                     {
@@ -385,7 +531,7 @@ class AI:
                     },
                     {
                         "role": "user",
-                        "content": f"Query: {query}, Facts: {facts}, Internet Search Results: {search_results}, X Search Results: {x_search_results}",
+                        "content": f"Query: {query}, Facts: {facts}, KB Results: {kb_results}, Internet Search Results: {search_results}, X Search Results: {x_search_results}",
                     },
                 ],
             )
@@ -396,7 +542,27 @@ class AI:
     # x search tool - has to be sync
     def search_x(self, query: str, model: Literal["grok-beta"] = "grok-beta") -> str:
         try:
-            client = OpenAI(api_key=self.grok_api_key,
+            """Search X (formerly Twitter) using Grok API integration.
+
+            Args:
+                query (str): Search query to find relevant X posts
+                model (Literal["grok-beta"], optional): Grok model to use. Defaults to "grok-beta"
+
+            Returns:
+                str: Search results from X or error message if search fails
+
+            Example:
+                ```python
+                result = ai.search_x("AI announcements")
+                # Returns: "Recent relevant X posts about AI announcements..."
+                ```
+
+            Note:
+                This is a synchronous tool method required for OpenAI function calling.
+                Requires valid Grok API key to be configured.
+                Returns error message string if API call fails.
+            """
+            client = OpenAI(api_key=self._grok_api_key,
                             base_url="https://api.x.ai/v1")
 
             completion = client.chat.completions.create(
@@ -415,45 +581,83 @@ class AI:
             return f"Failed to search X. Error: {e}"
 
     async def delete_facts(self, user_id: str):
-        if self.zep:
-            await self.zep.memory.delete(session_id=user_id)
-
-    async def listen(self, audio_content: bytes, input_format: str) -> str:
-        transcription = self.client.audio.transcriptions.create(
+        """Delete stored conversation facts for a specific user from Zep memory.
+
+        Args:
+            user_id (str): Unique identifier for the user whose facts should be deleted
+
+        Example:
+            ```python
+            await ai.delete_facts("user123")
+            # Deletes all stored facts for user123
+            ```
+
+        Note:
+            This is an async method and must be awaited.
+            Requires Zep integration to be configured.
+            No-op if Zep is not configured.
+        """
+        if self._zep:
+            await self._zep.memory.delete(session_id=user_id)
+
+    async def _listen(self, audio_content: bytes, input_format: str) -> str:
+        transcription = self._client.audio.transcriptions.create(
             model="whisper-1",
             file=(f"file.{input_format}", audio_content),
         )
         return transcription.text
 
     async def text(self, user_id: str, user_text: str) -> AsyncGenerator[str, None]:
-        self.accumulated_value_queue = asyncio.Queue()
+        """Process text input and stream AI responses asynchronously.
 
-        thread_id = await self.database.get_thread_id(user_id)
+        Args:
+            user_id (str): Unique identifier for the user/conversation
+            user_text (str): Text input from user to process
+
+        Returns:
+            AsyncGenerator[str, None]: Stream of response text chunks
+
+        Example:
+            ```python
+            async for chunk in ai.text("user123", "What is machine learning?"):
+                print(chunk, end="")  # Prints response as it streams
+            ```
+
+        Note:
+            - Maintains conversation thread using OpenAI's thread system
+            - Stores messages in configured database (MongoDB/SQLite)
+            - Integrates with Zep memory if configured
+            - Handles concurrent runs by canceling active ones
+            - Streams responses for real-time interaction
+        """
+        self._accumulated_value_queue = asyncio.Queue()
+
+        thread_id = await self._database.get_thread_id(user_id)
 
         if thread_id is None:
-            thread_id = await self.create_thread(user_id)
+            thread_id = await self._create_thread(user_id)
 
-        self.current_thread_id = thread_id
+        self._current_thread_id = thread_id
 
         # Check for active runs and cancel if necessary
-        active_run_id = await self.get_active_run(thread_id)
+        active_run_id = await self._get_active_run(thread_id)
         if active_run_id:
-            await self.cancel_run(thread_id, active_run_id)
-            while await self.get_run_status(thread_id, active_run_id) != "cancelled":
+            await self._cancel_run(thread_id, active_run_id)
+            while await self._get_run_status(thread_id, active_run_id) != "cancelled":
                 await asyncio.sleep(0.1)
 
         # Create a message in the thread
-        self.client.beta.threads.messages.create(
+        self._client.beta.threads.messages.create(
             thread_id=thread_id,
             role="user",
             content=user_text,
         )
-        event_handler = EventHandler(self.tool_handlers, self)
+        event_handler = EventHandler(self._tool_handlers, self)
 
         async def stream_processor():
-            with self.client.beta.threads.runs.stream(
+            with self._client.beta.threads.runs.stream(
                 thread_id=thread_id,
-                assistant_id=self.assistant_id,
+                assistant_id=self._assistant_id,
                 event_handler=event_handler,
             ) as stream:
                 stream.until_done()
@@ -466,13 +670,13 @@ class AI:
         while True:
             try:
                 value = await asyncio.wait_for(
-                    self.accumulated_value_queue.get(), timeout=0.1
+                    self._accumulated_value_queue.get(), timeout=0.1
                 )
                 if value is not None:
                     full_response += value
                     yield value
             except asyncio.TimeoutError:
-                if self.accumulated_value_queue.empty():
+                if self._accumulated_value_queue.empty():
                     break
 
         # Save the message to the database
@@ -483,8 +687,8 @@ class AI:
             "timestamp": datetime.now(),
         }
 
-        await self.database.save_message(user_id, metadata)
-        if self.zep:
+        await self._database.save_message(user_id, metadata)
+        if self._zep:
             messages = [
                 Message(
                     role="user",
@@ -497,7 +701,7 @@ class AI:
                     content=full_response,
                 ),
             ]
-            await self.zep.memory.add(
+            await self._zep.memory.add(
                 user_id=user_id, session_id=user_id, messages=messages
             )
 
@@ -513,27 +717,62 @@ class AI:
         response_format: Literal["mp3", "opus",
                                  "aac", "flac", "wav", "pcm"] = "aac",
     ) -> AsyncGenerator[bytes, None]:
+        """Process voice conversations and stream AI audio responses asynchronously.
+
+        Args:
+            user_id (str): Unique identifier for the user/conversation
+            audio_bytes (bytes): Raw audio input bytes to process
+            voice (Literal, optional): OpenAI TTS voice to use. Defaults to "nova"
+            input_format (Literal, optional): Input audio format. Defaults to "mp4"
+            response_format (Literal, optional): Output audio format. Defaults to "aac"
+
+        Returns:
+            AsyncGenerator[bytes, None]: Stream of audio response chunks
+
+        Example:
+            ```python
+            async with open('input.mp4', 'rb') as f:
+                audio_data = f.read()
+                async for chunk in ai.conversation(
+                    "user123",
+                    audio_data,
+                    voice="nova",
+                    input_format="mp4",
+                    response_format="aac"
+                ):
+                    # Process or save audio chunks
+                    await process_audio_chunk(chunk)
+            ```
+
+        Note:
+            - Converts audio to text using Whisper
+            - Maintains conversation thread using OpenAI
+            - Stores conversation in database
+            - Integrates with Zep memory if configured
+            - Streams audio response using OpenAI TTS
+        """
+
         # Reset the queue for each new conversation
-        self.accumulated_value_queue = asyncio.Queue()
+        self._accumulated_value_queue = asyncio.Queue()
 
-        thread_id = await self.database.get_thread_id(user_id)
+        thread_id = await self._database.get_thread_id(user_id)
 
         if thread_id is None:
-            thread_id = await self.create_thread(user_id)
+            thread_id = await self._create_thread(user_id)
 
-        self.current_thread_id = thread_id
-        transcript = await self.listen(audio_bytes, input_format)
-        event_handler = EventHandler(self.tool_handlers, self)
-        openai.beta.threads.messages.create(
+        self._current_thread_id = thread_id
+        transcript = await self._listen(audio_bytes, input_format)
+        event_handler = EventHandler(self._tool_handlers, self)
+        self._client.beta.threads.messages.create(
             thread_id=thread_id,
             role="user",
             content=transcript,
         )
 
         async def stream_processor():
-            with openai.beta.threads.runs.stream(
+            with self._client.beta.threads.runs.stream(
                 thread_id=thread_id,
-                assistant_id=self.assistant_id,
+                assistant_id=self._assistant_id,
                 event_handler=event_handler,
             ) as stream:
                 stream.until_done()
@@ -546,12 +785,12 @@ class AI:
         while True:
             try:
                 value = await asyncio.wait_for(
-                    self.accumulated_value_queue.get(), timeout=0.1
+                    self._accumulated_value_queue.get(), timeout=0.1
                 )
                 if value is not None:
                     full_response += value
             except asyncio.TimeoutError:
-                if self.accumulated_value_queue.empty():
+                if self._accumulated_value_queue.empty():
                     break
 
         metadata = {
@@ -561,9 +800,9 @@ class AI:
             "timestamp": datetime.now(),
         }
 
-        await self.database.save_message(user_id, metadata)
+        await self._database.save_message(user_id, metadata)
 
-        if self.zep:
+        if self._zep:
             messages = [
                 Message(
                     role="user",
@@ -576,12 +815,12 @@ class AI:
                     content=full_response,
                 ),
             ]
-            await self.zep.memory.add(
+            await self._zep.memory.add(
                 user_id=user_id, session_id=user_id, messages=messages
             )
 
         # Generate and stream the audio response
-        with self.client.audio.speech.with_streaming_response.create(
+        with self._client.audio.speech.with_streaming_response.create(
             model="tts-1",
             voice=voice,
             input=full_response,
@@ -590,27 +829,56 @@ class AI:
             for chunk in response.iter_bytes(1024):
                 yield chunk
 
-    def handle_requires_action(self, data, run_id):
+    def _handle_requires_action(self, data, run_id):
         tool_outputs = []
 
         for tool in data.required_action.submit_tool_outputs.tool_calls:
-            if tool.function.name in self.tool_handlers:
-                handler = self.tool_handlers[tool.function.name]
+            if tool.function.name in self._tool_handlers:
+                handler = self._tool_handlers[tool.function.name]
                 inputs = json.loads(tool.function.arguments)
                 output = handler(**inputs)
                 tool_outputs.append(
                     {"tool_call_id": tool.id, "output": output})
 
-        self.submit_tool_outputs(tool_outputs, run_id)
+        self._submit_tool_outputs(tool_outputs, run_id)
 
-    def submit_tool_outputs(self, tool_outputs, run_id):
-        with self.client.beta.threads.runs.submit_tool_outputs_stream(
-            thread_id=self.current_thread_id, run_id=run_id, tool_outputs=tool_outputs
+    def _submit_tool_outputs(self, tool_outputs, run_id):
+        with self._client.beta.threads.runs.submit_tool_outputs_stream(
+            thread_id=self._current_thread_id, run_id=run_id, tool_outputs=tool_outputs
         ) as stream:
             for text in stream.text_deltas:
-                asyncio.create_task(self.accumulated_value_queue.put(text))
+                asyncio.create_task(self._accumulated_value_queue.put(text))
 
     def add_tool(self, func: Callable):
+        """Register a custom function as an AI tool using decorator pattern.
+
+        Args:
+            func (Callable): Function to register as a tool. Must have docstring and type hints.
+
+        Returns:
+            Callable: The decorated function
+
+        Example:
+            ```python
+            @ai.add_tool
+            def custom_search(query: str) -> str:
+                '''Search custom data source.
+
+                Args:
+                    query (str): Search query
+
+                Returns:
+                    str: Search results
+                '''
+                return "Custom search results"
+            ```
+
+        Note:
+            - Function must have proper docstring for tool description
+            - Parameters should have type hints
+            - Tool becomes available to AI for function calling
+            - Parameters are automatically converted to JSON schema
+        """
         sig = inspect.signature(func)
         parameters = {"type": "object", "properties": {}, "required": []}
         for name, param in sig.parameters.items():
@@ -626,8 +894,8 @@ class AI:
                 "parameters": parameters,
             },
         }
-        self.tools.append(tool_config)
-        self.tool_handlers[func.__name__] = func
+        self._tools.append(tool_config)
+        self._tool_handlers[func.__name__] = func
         return func
 
 

solana_agent-0.0.7.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.3
+Name: solana-agent
+Version: 0.0.7
+Summary: Build self-learning AI Agents
+License: MIT
+Keywords: ai,openai,ai agents
+Author: Bevan Hunt
+Author-email: bevan@bevanhunt.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+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: motor (>=3.7.0,<4.0.0)
+Requires-Dist: openai (>=1.61.1,<2.0.0)
+Requires-Dist: pandas (>=2.2.3,<3.0.0)
+Requires-Dist: pinecone (>=6.0.1,<7.0.0)
+Requires-Dist: pydantic (>=2.10.6,<3.0.0)
+Requires-Dist: qdrant-client (>=1.13.2,<2.0.0)
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Requires-Dist: zep-cloud (>=2.3.1,<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/)
+
+![Solana Agent Logo](https://dl.walletbubbles.com/solana-agent-logo.png?width=200)
+
+Solana Agent is the first self-learning AI Agent framework.
+
+## Why Solana Agent?
+
+### 🧬 The First Self-Learning AI Agent
+
+Unlike traditional AI assistants that forget conversations after each session, Solana Agent maintains a rich, searchable memory system that grows smarter with every interaction.
+
+**Why This Matters:**
+- 📈 **Continuous Learning**: Evolves with every new interaction
+- 🎯 **Context-Aware**: Recalls past interactions for more relevant responses
+- 🔄 **Self-Improving**: Builds knowledge and improves reasoning automatically
+- 🏢 **Enterprise-Ready**: Scales from personal to organization-wide deployment
+- 🛡️ **Secure**: Secure and private memory and data storage 
+
+**"It's not just an AI assistant - it's your organization's evolving intelligence layer."**
+
+## Benefits
+
+💬 **Enhanced Communication**
+- Engage in natural conversations without typing delays
+- Communicate hands-free with voice interactions
+- Reduce response time with real-time processing
+
+🎯 **Improved Decision Making**
+- Access comprehensive data from multiple trusted sources
+- Get instant answers backed by Internet and social-media research
+- Make informed decisions with cross-referenced information
+
+💪 **Operational Efficiency**
+- Automate repetitive data processing tasks
+- Convert data formats seamlessly
+- Scale knowledge management effortlessly
+
+🔐 **Enterprise Ready**
+- Secure data handling with advanced memory systems
+- Customize functionality through extensible architecture
+- Integrate with existing business tools and APIs
+
+🚀 **Competitive Advantage**
+- Stay current with real-time social media and Internet insights
+- Process and analyze large datasets quickly
+- Transform raw data into actionable intelligence
+
+## Features
+
+🔄 **Real-time AI Interactions**
+- Streaming text-based conversations
+- Real-time voice-to-voice conversations
+
+🧠 **Memory System and Extensibility**
+- Advanced AI memory combining conversational context, conversational facts, and knowledge base
+- Simple custom tool creation for extending capabilities like additional API integrations
+
+🔍 **Multi-Source Search and Reasoning**
+- Internet search via Perplexity
+- Conversational fact search powered by Zep
+- X (Twitter) search using Grok
+- Conversational message history using MongoDB (on-prem or hosted)
+- Knowledge Base search via Pinecone
+- Comprehensive reasoning combining multiple data sources
+
+🛠️ **Data Processing Tools**
+- CSV to JSON conversion for data integration
+- Text summarization powered by Gemini
+- Enterprise-ready knowledge base powered by Pinecone
+
+## Why Choose Solana Agent Over LangChain?
+
+### 🎯 Key Differentiators
+
+🧠 **Advanced Memory Architecture**
+   - Built-in episodic memory vs LangChain's basic memory types
+   - Persistent cross-session knowledge retention
+   - Automatic self-learning from conversations
+
+🏢 **Enterprise Focus**
+   - Production-ready out of the box in a few lines of code
+   - Enterprise-grade deployment options for all components and services
+   - Simple conventions over complex configurations
+
+🛠️ **Simplified Development**
+   - No chain building required
+   - Python plain functions vs complex chaining
+   - Fewer moving parts equals more stable applications
+   - Smaller repo size by 1000x: Solana Agent @ ~500 LOC vs LangChain @ ~500,000 LOC
+
+🚀 **Performance**
+   - Optimized for real-time streaming responses
+   - Built-in voice processing capabilities
+   - Multi-source search with automatic reasoning synthesis
+
+## Installation
+
+You can install Solana Agent using pip:
+
+```bash
+pip install solana-agent
+```
+
+## Documentation
+* All public methods have docstrings for real-time IDE hinting
+
+## Production Apps
+* [Solana Agent Copilot](https://ai.solana-agent.com) - Solana Token AI Copilot using streaming text conversations
+* [CometHeart](https://cometheart.com) - AI Companion and Business Coach on mobile using voice-to-voice conversations
+
+## Example Apps
+* [Solana Agent Example App](https://github.com/truemagic-coder/solana-agent-app) - See as source of documentation
+
+## Contributing
+
+Contributions to Solana Agent are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+

solana_agent-0.0.7.dist-info/RECORD

@@ -0,0 +1,6 @@
+solana_agent/__init__.py,sha256=zpfnWqANd3OHGWm7NCF5Y6m01BWG4NkNk8SK9Ex48nA,18
+solana_agent/ai.py,sha256=nAFDHwEjQqoHZUNv9YW0hzJWRsUKr8Nm7G_wFaW2XnI,33393
+solana_agent-0.0.7.dist-info/LICENSE,sha256=BnSRc-NSFuyF2s496l_4EyrwAP6YimvxWcjPiJ0J7g4,1057
+solana_agent-0.0.7.dist-info/METADATA,sha256=J9JA1qZX8aaxqcqwUuTWQEx0TkCS0x3zHDLXftI5vGQ,5623
+solana_agent-0.0.7.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+solana_agent-0.0.7.dist-info/RECORD,,

solana_agent-0.0.6.dist-info/METADATA

@@ -1,97 +0,0 @@
-Metadata-Version: 2.3
-Name: solana-agent
-Version: 0.0.6
-Summary: The Best AI Agent Framework
-License: MIT
-Keywords: ai,openai,ai agents
-Author: Bevan Hunt
-Author-email: bevan@bevanhunt.com
-Requires-Python: >=3.9,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-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: aiosqlite (>=0.21.0,<0.22.0)
-Requires-Dist: motor (>=3.7.0,<4.0.0)
-Requires-Dist: openai (>=1.61.1,<2.0.0)
-Requires-Dist: pandas (>=2.2.3,<3.0.0)
-Requires-Dist: pydantic (>=2.10.6,<3.0.0)
-Requires-Dist: requests (>=2.32.3,<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/)
-
-![Solana Agent Logo](https://dl.walletbubbles.com/solana-agent-logo.png?width=200)
-
-Solana Agent is the best AI Agent framework.
-
-## Features
-
-- Streaming text-based conversations with AI
-- Audio transcription and streaming text-to-speech conversion
-- Thread management for maintaining conversation context
-- Message persistence using SQLite or MongoDB
-- Custom tool integration for extending AI capabilities
-- The best memory context currently available for AI Agents
-- Zep integration for tracking facts
-- Search Internet with Perplexity tool
-- Search Zep facts tool
-- Search X with Grok tool
-- Reasoning tool that combines OpenAI model reasoning, Zep facts, Internet search, and X search.
-- CSV to JSON tool
-- Summarize text tool using Gemini
-- Solana tools upcoming...
-
-## Installation
-
-You can install Solana Agent using pip:
-
-```bash
-pip install solana-agent
-```
-
-## Usage
-
-Here's a basic example of how to use Solana Agent:
-
-```python
-from solana_agent import AI, SQLiteDatabase
-
-async def main():
-    database = SQLiteDatabase("conversations.db")
-    async with AI("your_openai_api_key", "AI Assistant", "Your instructions here", database) as ai:
-        user_id = "user123"
-        response = await ai.text(user_id, "Hello, AI!")
-        async for chunk in response:
-            print(chunk, end="", flush=True)
-        print()
-
-# Run the async main function
-import asyncio
-asyncio.run(main())
-```
-
-## Production Apps
-* [Solana Agent](https://solana-agent.com) - AI Market Intelligence
-* [CometHeart](https://cometheart.com) - AI Companion
-
-## Example Apps
-* [Solana Agent Example App](https://github.com/truemagic-coder/solana-agent-app)
-
-## Contributing
-
-Contributions to Solana Agent are welcome! Please feel free to submit a Pull Request.
-
-## License
-
-This project is licensed under the MIT License - see the LICENSE file for details.
-

solana_agent-0.0.6.dist-info/RECORD

@@ -1,6 +0,0 @@
-solana_agent/__init__.py,sha256=zpfnWqANd3OHGWm7NCF5Y6m01BWG4NkNk8SK9Ex48nA,18
-solana_agent/ai.py,sha256=a82WmVPwsQEKMojS9DM4-rSHqdoF3XwKdn92I96UQwA,22001
-solana_agent-0.0.6.dist-info/LICENSE,sha256=BnSRc-NSFuyF2s496l_4EyrwAP6YimvxWcjPiJ0J7g4,1057
-solana_agent-0.0.6.dist-info/METADATA,sha256=EBKYqwMaxIz0iR7sz9Ga-5o_lBty3yfNOVezcMMb8HU,3069
-solana_agent-0.0.6.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-solana_agent-0.0.6.dist-info/RECORD,,