solana-agent 27.2.0__tar.gz → 27.3.0__tar.gz

solana_agent-27.2.0/README.md → solana_agent-27.3.0/PKG-INFO

@@ -1,3 +1,32 @@
+Metadata-Version: 2.3
+Name: solana-agent
+Version: 27.3.0
+Summary: Agentic IQ
+License: MIT
+Keywords: ai,openai,ai agents,agi
+Author: Bevan Hunt
+Author-email: bevan@bevanhunt.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: instructor (>=1.7.9,<2.0.0)
+Requires-Dist: llama-index-core (>=0.12.30,<0.13.0)
+Requires-Dist: llama-index-embeddings-openai (>=0.3.1,<0.4.0)
+Requires-Dist: openai (>=1.74.0,<2.0.0)
+Requires-Dist: pinecone (>=6.0.2,<7.0.0)
+Requires-Dist: pydantic (>=2.11.3,<3.0.0)
+Requires-Dist: pymongo (>=4.12.0,<5.0.0)
+Requires-Dist: pypdf (>=5.4.0,<6.0.0)
+Requires-Dist: zep-cloud (>=2.10.1,<3.0.0)
+Project-URL: Documentation, https://docs.solana-agent.com
+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/)
@@ -26,6 +55,7 @@ Build your AI business in three lines of code!
 * Business Alignment
 * Extensible Tooling
 * Simple Business Definition
+* Knowledge Base with PDF support
 * Tested & Secure
 * Built in Python
 * Powers [CometHeart](https://cometheart.com) & [WalletBubbles](https://walletbubbles.com)
@@ -45,6 +75,7 @@ Build your AI business in three lines of code!
 * Powerful tool integration using standard Python packages and/or inline tools
 * Assigned tools are utilized by agents automatically and effectively
 * Simple business definition using JSON
+* Integrated Knowledge Base with semantic search and automatic PDF chunking
 
 ## Stack
 
@@ -54,15 +85,17 @@ Build your AI business in three lines of code!
 * [OpenAI](https://openai.com), [Google](https://ai.google.dev), [xAI](https://x.ai) - LLM Providers
 * [MongoDB](https://mongodb.com) - Conversational History (optional)
 * [Zep Cloud](https://getzep.com) - Conversational Memory (optional)
+* [Pinecone](https://pinecone.io) - Knowledge Base (optional)
 
 ### LLMs
 
 * [gpt-4.1-mini](https://platform.openai.com/docs/models/gpt-4.1-mini) (agent)
 * [gpt-4.1-nano](https://platform.openai.com/docs/models/gpt-4.1-nano) (router)
-* [gemini-2.0-flash](https://ai.google.dev/gemini-api/docs/models#gemini-2.0-flash) (optional)
-* [grok-3-mini-fast-beta](https://docs.x.ai/docs/models#models-and-pricing) (optional)
+* [text-embedding-3-large](https://platform.openai.com/docs/models/text-embedding-3-large) or [text-embedding-3-small](https://platform.openai.com/docs/models/text-embedding-3-small) (embedding)
 * [tts-1](https://platform.openai.com/docs/models/tts-1) (audio TTS)
 * [gpt-4o-mini-transcribe](https://platform.openai.com/docs/models/gpt-4o-mini-transcribe) (audio transcription)
+* [gemini-2.0-flash](https://ai.google.dev/gemini-api/docs/models#gemini-2.0-flash) (optional)
+* [grok-3-mini-fast-beta](https://docs.x.ai/docs/models#models-and-pricing) (optional)
 
 ## Installation
 
@@ -171,7 +204,7 @@ config = {
 
 solana_agent = SolanaAgent(config=config)
 
-audio_content = audio_file.read()
+audio_content = await audio_file.read()
 
 async for response in solana_agent.process("user123", audio_content, output_format="audio", audio_voice="nova", audio_input_format="webm", audio_output_format="aac"):
     print(response, end="")
@@ -231,7 +264,7 @@ config = {
 
 solana_agent = SolanaAgent(config=config)
 
-audio_content = audio_file.read()
+audio_content = await audio_file.read()
 
 async for response in solana_agent.process("user123", audio_content, audio_input_format="aac"):
     print(response, end="")
@@ -302,6 +335,114 @@ config = {
 }
 ```
 
+### Knowledge Base
+
+The Knowledge Base (KB) is meant to store text values and/or small PDFs.
+
+```python
+config = {
+    "knowledge_base": {
+        "pinecone": {
+            "api_key": "your-pinecone-api-key",
+            "index_name": "your-pinecone-index-name",
+        }
+    },
+    "mongo": {
+        "connection_string": "your-mongo-connection-string",
+        "database": "your-database-name"
+    },
+}
+```
+
+#### Example for KB (text)
+
+```python
+from solana_agent import SolanaAgent
+
+config = {
+    "openai": {
+        "api_key": "your-openai-api-key",
+    },
+    "knowledge_base": {
+        "pinecone": {
+            "api_key": "your-pinecone-api-key",
+            "index_name": "your-pinecone-index-name",
+        }
+    },
+    "mongo": {
+        "connection_string": "your-mongo-connection-string",
+        "database": "your-database-name"
+    },
+    "agents": [
+        {
+            "name": "kb_expert",
+            "instructions": "You answer questions based on the provided knowledge base documents.",
+            "specialization": "Company Knowledge",
+        }
+    ]
+}
+
+solana_agent = SolanaAgent(config=config)
+
+doc_text = "Solana Agent is a Python framework for building multi-agent AI systems."
+doc_metadata = {
+    "source": "internal_docs",
+    "version": "1.0",
+    "tags": ["framework", "python", "ai"]
+}
+await solana_agent.kb_add_document(text=doc_text, metadata=doc_metadata)
+
+async for response in solana_agent.process("user123", "What is Solana Agent?"):
+    print(response, end="")
+```
+
+#### Example for KB (pdf)
+
+```python
+from solana_agent import SolanaAgent
+
+config = {
+    "openai": {
+        "api_key": "your-openai-api-key",
+    },
+    "knowledge_base": {
+        "pinecone": {
+            "api_key": "your-pinecone-api-key",
+            "index_name": "your-pinecone-index-name",
+        }
+    },
+    "mongo": {
+        "connection_string": "your-mongo-connection-string",
+        "database": "your-database-name"
+    },
+    "agents": [
+        {
+            "name": "kb_expert",
+            "instructions": "You answer questions based on the provided knowledge base documents.",
+            "specialization": "Company Knowledge",
+        }
+    ]
+}
+
+solana_agent = SolanaAgent(config=config)
+
+pdf_bytes = await pdf_file.read()
+
+pdf_metadata = {
+    "source": "annual_report_2024.pdf",
+    "year": 2024,
+    "tags": ["finance", "report"]
+}
+
+await solana_agent.kb_add_pdf_document(
+    pdf_data=pdf_bytes,
+    metadata=pdf_metadata,
+)
+
+async for response in solana_agent.process("user123", "Summarize the annual report for 2024."):
+    print(response, end="")
+```
+
 ## Tools
 
 Tools can be used from plugins like Solana Agent Kit (sakit) or via inline tools. Tools available via plugins integrate automatically with Solana Agent.
@@ -428,13 +569,9 @@ async for response in solana_agent.process("user123", "What are the latest AI de
     print(response, end="")
 ```
 
-## Agent Training
-
-Many use cases for Solana Agent require training your agents on your company data.
+## Advanced Customization
 
-This can be accomplished via runtime prompt injection. Integrations that work well with this method are vector stores like Pinecone and FAQs.
-
-This knowledge is accessible to all your AI agents.
+### Runtime Prompt Injection
 
 ```python
 from solana_agent import SolanaAgent
@@ -458,7 +595,7 @@ async for response in solana_agent.process("user123", "How do replace the latch
     print(response, end="")
 ```
 
-## Custom Routing
+### Custom Routing
 
 In advanced cases like implementing a ticketing system on-top of Solana Agent - you can use your own router.
 
@@ -544,3 +681,4 @@ To run the test suite locally run `poetry run pytest --cov=solana_agent --cov-re
 ## License
 
 This project is licensed under the MIT License - see the LICENSE file for details.
+

solana_agent-27.2.0/PKG-INFO → solana_agent-27.3.0/README.md

@@ -1,28 +1,3 @@
-Metadata-Version: 2.3
-Name: solana-agent
-Version: 27.2.0
-Summary: Agentic IQ
-License: MIT
-Keywords: ai,openai,ai agents,agi
-Author: Bevan Hunt
-Author-email: bevan@bevanhunt.com
-Requires-Python: >=3.12,<4.0
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Dist: instructor (>=1.7.9,<2.0.0)
-Requires-Dist: openai (>=1.74.0,<2.0.0)
-Requires-Dist: pydantic (>=2.11.3,<3.0.0)
-Requires-Dist: pymongo (>=4.12.0,<5.0.0)
-Requires-Dist: zep-cloud (>=2.10.1,<3.0.0)
-Project-URL: Documentation, https://docs.solana-agent.com
-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/)
@@ -51,6 +26,7 @@ Build your AI business in three lines of code!
 * Business Alignment
 * Extensible Tooling
 * Simple Business Definition
+* Knowledge Base with PDF support
 * Tested & Secure
 * Built in Python
 * Powers [CometHeart](https://cometheart.com) & [WalletBubbles](https://walletbubbles.com)
@@ -70,6 +46,7 @@ Build your AI business in three lines of code!
 * Powerful tool integration using standard Python packages and/or inline tools
 * Assigned tools are utilized by agents automatically and effectively
 * Simple business definition using JSON
+* Integrated Knowledge Base with semantic search and automatic PDF chunking
 
 ## Stack
 
@@ -79,15 +56,17 @@ Build your AI business in three lines of code!
 * [OpenAI](https://openai.com), [Google](https://ai.google.dev), [xAI](https://x.ai) - LLM Providers
 * [MongoDB](https://mongodb.com) - Conversational History (optional)
 * [Zep Cloud](https://getzep.com) - Conversational Memory (optional)
+* [Pinecone](https://pinecone.io) - Knowledge Base (optional)
 
 ### LLMs
 
 * [gpt-4.1-mini](https://platform.openai.com/docs/models/gpt-4.1-mini) (agent)
 * [gpt-4.1-nano](https://platform.openai.com/docs/models/gpt-4.1-nano) (router)
-* [gemini-2.0-flash](https://ai.google.dev/gemini-api/docs/models#gemini-2.0-flash) (optional)
-* [grok-3-mini-fast-beta](https://docs.x.ai/docs/models#models-and-pricing) (optional)
+* [text-embedding-3-large](https://platform.openai.com/docs/models/text-embedding-3-large) or [text-embedding-3-small](https://platform.openai.com/docs/models/text-embedding-3-small) (embedding)
 * [tts-1](https://platform.openai.com/docs/models/tts-1) (audio TTS)
 * [gpt-4o-mini-transcribe](https://platform.openai.com/docs/models/gpt-4o-mini-transcribe) (audio transcription)
+* [gemini-2.0-flash](https://ai.google.dev/gemini-api/docs/models#gemini-2.0-flash) (optional)
+* [grok-3-mini-fast-beta](https://docs.x.ai/docs/models#models-and-pricing) (optional)
 
 ## Installation
 
@@ -196,7 +175,7 @@ config = {
 
 solana_agent = SolanaAgent(config=config)
 
-audio_content = audio_file.read()
+audio_content = await audio_file.read()
 
 async for response in solana_agent.process("user123", audio_content, output_format="audio", audio_voice="nova", audio_input_format="webm", audio_output_format="aac"):
     print(response, end="")
@@ -256,7 +235,7 @@ config = {
 
 solana_agent = SolanaAgent(config=config)
 
-audio_content = audio_file.read()
+audio_content = await audio_file.read()
 
 async for response in solana_agent.process("user123", audio_content, audio_input_format="aac"):
     print(response, end="")
@@ -327,6 +306,114 @@ config = {
 }
 ```
 
+### Knowledge Base
+
+The Knowledge Base (KB) is meant to store text values and/or small PDFs.
+
+```python
+config = {
+    "knowledge_base": {
+        "pinecone": {
+            "api_key": "your-pinecone-api-key",
+            "index_name": "your-pinecone-index-name",
+        }
+    },
+    "mongo": {
+        "connection_string": "your-mongo-connection-string",
+        "database": "your-database-name"
+    },
+}
+```
+
+#### Example for KB (text)
+
+```python
+from solana_agent import SolanaAgent
+
+config = {
+    "openai": {
+        "api_key": "your-openai-api-key",
+    },
+    "knowledge_base": {
+        "pinecone": {
+            "api_key": "your-pinecone-api-key",
+            "index_name": "your-pinecone-index-name",
+        }
+    },
+    "mongo": {
+        "connection_string": "your-mongo-connection-string",
+        "database": "your-database-name"
+    },
+    "agents": [
+        {
+            "name": "kb_expert",
+            "instructions": "You answer questions based on the provided knowledge base documents.",
+            "specialization": "Company Knowledge",
+        }
+    ]
+}
+
+solana_agent = SolanaAgent(config=config)
+
+doc_text = "Solana Agent is a Python framework for building multi-agent AI systems."
+doc_metadata = {
+    "source": "internal_docs",
+    "version": "1.0",
+    "tags": ["framework", "python", "ai"]
+}
+await solana_agent.kb_add_document(text=doc_text, metadata=doc_metadata)
+
+async for response in solana_agent.process("user123", "What is Solana Agent?"):
+    print(response, end="")
+```
+
+#### Example for KB (pdf)
+
+```python
+from solana_agent import SolanaAgent
+
+config = {
+    "openai": {
+        "api_key": "your-openai-api-key",
+    },
+    "knowledge_base": {
+        "pinecone": {
+            "api_key": "your-pinecone-api-key",
+            "index_name": "your-pinecone-index-name",
+        }
+    },
+    "mongo": {
+        "connection_string": "your-mongo-connection-string",
+        "database": "your-database-name"
+    },
+    "agents": [
+        {
+            "name": "kb_expert",
+            "instructions": "You answer questions based on the provided knowledge base documents.",
+            "specialization": "Company Knowledge",
+        }
+    ]
+}
+
+solana_agent = SolanaAgent(config=config)
+
+pdf_bytes = await pdf_file.read()
+
+pdf_metadata = {
+    "source": "annual_report_2024.pdf",
+    "year": 2024,
+    "tags": ["finance", "report"]
+}
+
+await solana_agent.kb_add_pdf_document(
+    pdf_data=pdf_bytes,
+    metadata=pdf_metadata,
+)
+
+async for response in solana_agent.process("user123", "Summarize the annual report for 2024."):
+    print(response, end="")
+```
+
 ## Tools
 
 Tools can be used from plugins like Solana Agent Kit (sakit) or via inline tools. Tools available via plugins integrate automatically with Solana Agent.
@@ -453,13 +540,9 @@ async for response in solana_agent.process("user123", "What are the latest AI de
     print(response, end="")
 ```
 
-## Agent Training
-
-Many use cases for Solana Agent require training your agents on your company data.
+## Advanced Customization
 
-This can be accomplished via runtime prompt injection. Integrations that work well with this method are vector stores like Pinecone and FAQs.
-
-This knowledge is accessible to all your AI agents.
+### Runtime Prompt Injection
 
 ```python
 from solana_agent import SolanaAgent
@@ -483,7 +566,7 @@ async for response in solana_agent.process("user123", "How do replace the latch
     print(response, end="")
 ```
 
-## Custom Routing
+### Custom Routing
 
 In advanced cases like implementing a ticketing system on-top of Solana Agent - you can use your own router.
 
@@ -569,4 +652,3 @@ To run the test suite locally run `poetry run pytest --cov=solana_agent --cov-re
 ## License
 
 This project is licensed under the MIT License - see the LICENSE file for details.
-

{solana_agent-27.2.0 → solana_agent-27.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "solana-agent"
-version = "27.2.0"
+version = "27.3.0"
 description = "Agentic IQ"
 authors = ["Bevan Hunt <bevan@bevanhunt.com>"]
 license = "MIT"
@@ -28,6 +28,10 @@ pydantic = "^2.11.3"
 pymongo = "^4.12.0"
 zep-cloud = "^2.10.1"
 instructor = "^1.7.9"
+pinecone = "^6.0.2"
+llama-index-core = "^0.12.30"
+llama-index-embeddings-openai = "^0.3.1"
+pypdf = "^5.4.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.3.5"

{solana_agent-27.2.0 → solana_agent-27.3.0}/solana_agent/adapters/openai_adapter.py

@@ -3,7 +3,7 @@ LLM provider adapters for the Solana Agent system.
 
 These adapters implement the LLMProvider interface for different LLM services.
 """
-from typing import AsyncGenerator, Literal, Optional, Type, TypeVar
+from typing import AsyncGenerator, List, Literal, Optional, Type, TypeVar
 
 from openai import AsyncOpenAI
 from pydantic import BaseModel
@@ -14,16 +14,25 @@ from solana_agent.interfaces.providers.llm import LLMProvider
 
 T = TypeVar('T', bound=BaseModel)
 
+DEFAULT_CHAT_MODEL = "gpt-4.1-mini"
+DEFAULT_PARSE_MODEL = "gpt-4.1-nano"
+DEFAULT_EMBEDDING_MODEL = "text-embedding-3-large"
+DEFAULT_EMBEDDING_DIMENSIONS = 3072
+DEFAULT_TRANSCRIPTION_MODEL = "gpt-4o-mini-transcribe"
+DEFAULT_TTS_MODEL = "tts-1"
+
 
 class OpenAIAdapter(LLMProvider):
     """OpenAI implementation of LLMProvider with web search capabilities."""
 
     def __init__(self, api_key: str):
         self.client = AsyncOpenAI(api_key=api_key)
-        self.parse_model = "gpt-4.1-nano"
-        self.text_model = "gpt-4.1-mini"
-        self.transcription_model = "gpt-4o-mini-transcribe"
-        self.tts_model = "tts-1"
+        self.parse_model = DEFAULT_PARSE_MODEL
+        self.text_model = DEFAULT_CHAT_MODEL
+        self.transcription_model = DEFAULT_TRANSCRIPTION_MODEL
+        self.tts_model = DEFAULT_TTS_MODEL
+        self.embedding_model = DEFAULT_EMBEDDING_MODEL
+        self.embedding_dimensions = DEFAULT_EMBEDDING_DIMENSIONS
 
     async def tts(
         self,
@@ -248,3 +257,48 @@ class OpenAIAdapter(LLMProvider):
                     raise ValueError(
                         f"Failed to generate structured output: {e}. All fallbacks failed."
                     ) from e
+
+    async def embed_text(
+        self,
+        text: str,
+        model: Optional[str] = None,
+        dimensions: Optional[int] = None
+    ) -> List[float]:  # pragma: no cover
+        """Generate an embedding for the given text using OpenAI.
+
+        Args:
+            text: The text to embed.
+            model: The embedding model to use (defaults to text-embedding-3-large).
+            dimensions: Desired output dimensions for the embedding.
+
+        Returns:
+            A list of floats representing the embedding vector.
+        """
+        if not text:
+            raise ValueError("Text cannot be empty")
+
+        try:
+            # Use provided model/dimensions or fall back to defaults
+            embedding_model = model or self.embedding_model
+            embedding_dimensions = dimensions or self.embedding_dimensions
+
+            # Replace newlines with spaces as recommended by OpenAI
+            text = text.replace("\n", " ")
+
+            response = await self.client.embeddings.create(
+                input=[text],
+                model=embedding_model,
+                dimensions=embedding_dimensions
+            )
+
+            if response.data and response.data[0].embedding:
+                return response.data[0].embedding
+            else:
+                raise ValueError(
+                    "Failed to retrieve embedding from OpenAI response")
+
+        except Exception as e:
+            print(f"Error generating embedding: {e}")
+            import traceback
+            print(traceback.format_exc())
+            raise