API Reference

Solana Agent

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.

class solana_agent.client.solana_agent.SolanaAgent(config_path=None, config=None)[source]

Bases: SolanaAgent

Simplified client interface for interacting with the agent system.

Parameters:

config_path (str)
config (Dict[str, Any])

async process(user_id, message, prompt=None, output_format='text', audio_voice='nova', audio_instructions='You speak in a friendly and helpful manner.', audio_output_format='aac', audio_input_format='mp4', router=None, images=None, output_model=None)[source]

Process a user message (text or audio) and optional images, returning the response stream.

Parameters:

user_id (str) – User ID
message (str | bytes) – Text message or audio bytes
prompt (str | None) – Optional prompt for the agent
output_format (Literal['text', 'audio']) – Response format (“text” or “audio”)
audio_voice (Literal['alloy', 'ash', 'ballad', 'coral', 'echo', 'fable', 'onyx', 'nova', 'sage', 'shimmer']) – Voice to use for audio output
audio_instructions (str) – Not used in this version
audio_output_format (Literal['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm']) – Audio output format
audio_input_format (Literal['flac', 'mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'ogg', 'wav', 'webm']) – Audio input format
router (RoutingService | None) – Optional routing service for processing
images (List[str | bytes] | None) – Optional list of image URLs (str) or image bytes.
output_model (Type[BaseModel] | None) – Optional Pydantic model for structured output

Returns:

Async generator yielding response chunks (text strings or audio bytes)

Return type:

AsyncGenerator[str | bytes | BaseModel, None]

async delete_user_history(user_id)[source]

Delete the conversation history for a user.

Parameters:: user_id (str) – User ID
Return type:: None

async get_user_history(user_id, page_num=1, page_size=20, sort_order='desc')[source]

Get paginated message history for a user.

Parameters:

user_id (str) – User ID
page_num (int) – Page number (starting from 1)
page_size (int) – Number of messages per page
sort_order (str) – Sort order (“asc” or “desc”)

Returns:

Dictionary with paginated results and metadata

Return type:

Dict[str, Any]

register_tool(agent_name, tool)[source]

Register a tool with the agent system.

Parameters:

agent_name (str) – Name of the agent to register the tool with
tool (Tool) – Tool instance to register

Returns:

True if successful, False

Return type:

bool

async kb_add_document(text, metadata, document_id=None, namespace=None)[source]

Add a document to the knowledge base.

Parameters:

text (str) – Document text content.
metadata (Dict[str, Any]) – Document metadata.
document_id (str | None) – Optional document ID.
namespace (str | None) – Optional Pinecone namespace.

Returns:

The document ID.

Return type:

str

async kb_query(query_text, filter=None, top_k=5, namespace=None, include_content=True, include_metadata=True)[source]

Query the knowledge base.

Parameters:

query_text (str) – Search query text.
filter (Dict[str, Any] | None) – Optional filter criteria.
top_k (int) – Maximum number of results.
namespace (str | None) – Optional Pinecone namespace.
include_content (bool) – Include document content in results.
include_metadata (bool) – Include document metadata in results.

Returns:

List of matching documents.

Return type:

List[Dict[str, Any]]

async kb_delete_document(document_id, namespace=None)[source]

Delete a document from the knowledge base.

Parameters:

document_id (str) – ID of document to delete.
namespace (str | None) – Optional Pinecone namespace.

Returns:

True if successful.

Return type:

bool

async kb_add_pdf_document(pdf_data, metadata, document_id=None, namespace=None, chunk_batch_size=50)[source]

Add a PDF document to the knowledge base via the client.

Parameters:

pdf_data (bytes | str) – PDF content as bytes or a path to the PDF file.
metadata (Dict[str, Any]) – Document metadata.
document_id (str | None) – Optional parent document ID.
namespace (str | None) – Optional Pinecone namespace for chunks.
chunk_batch_size (int) – Batch size for upserting chunks.

Returns:

The parent document ID.

Return type:

str

Tools

Plugin manager for the Solana Agent system.

This module implements the concrete PluginManager that discovers, loads, and manages plugins.

class solana_agent.plugins.manager.PluginManager(config=None, tool_registry=None)[source]

Bases: PluginManager

Manager for discovering and loading plugins.

Parameters:

config (Dict[str, Any] | None)
tool_registry (ToolRegistry | None)

register_plugin(plugin)[source]

Register a plugin in the manager.

Parameters:: plugin (Plugin) – The plugin to register
Returns:: True if registration succeeded, False otherwise
Return type:: bool

load_plugins()[source]

Load all plugins using entry points and apply configuration.

Returns:: List of loaded plugin names
Return type:: List[str]

get_plugin(name)[source]

Get a plugin by name.

Parameters:: name (str) – Name of the plugin to retrieve
Returns:: Plugin instance or None if not found
Return type:: Plugin | None

list_plugins()[source]

List all registered plugins with their details.

Returns:: List of plugin details dictionaries
Return type:: List[Dict[str, Any]]

async execute_tool(tool_name, **kwargs)[source]

Execute a tool with the given parameters.

Parameters:

tool_name (str) – Name of the tool to execute
**kwargs – Parameters to pass to the tool

Returns:

Dictionary with execution results

Return type:

Dict[str, Any]

configure(config)[source]

Configure the plugin manager and all plugins.

Parameters:: config (Dict[str, Any]) – Configuration dictionary
Return type:: None

Tool registry for the Solana Agent system.

This module implements the concrete ToolRegistry that manages tools and their access permissions.

class solana_agent.plugins.registry.ToolRegistry(config=None)[source]

Bases: ToolRegistry

Instance-based registry that manages tools and their access permissions.

Parameters:: config (Dict[str, Any])

register_tool(tool)[source]

Register a tool with this registry.

Parameters:: tool (Tool)
Return type:: bool

get_tool(tool_name)[source]

Get a tool by name.

Parameters:: tool_name (str)
Return type:: Tool | None

assign_tool_to_agent(agent_name, tool_name)[source]

Give an agent access to a specific tool.

Parameters:

agent_name (str)
tool_name (str)

Return type:

bool

get_agent_tools(agent_name)[source]

Get all tools available to an agent.

Parameters:: agent_name (str)
Return type:: List[Dict[str, Any]]

list_all_tools()[source]

List all registered tools.

Return type:: List[str]

configure_all_tools(config)[source]

Configure all registered tools with new configuration.

Parameters:: config (Dict[str, Any]) – Configuration dictionary to apply
Return type:: None

AutoTool implementation for the Solana Agent system.

This module provides the base AutoTool class that implements the Tool interface and can be extended to create custom tools.

class solana_agent.plugins.tools.auto_tool.AutoTool(name, description, registry=None)[source]

Bases: Tool

Base class for tools that automatically register with the system.

Parameters:

name (str)
description (str)

property name: str: Get the name of the tool.

property description: str: Get the description of the tool.

configure(config)[source]

Configure the tool with settings from config.

Parameters:: config (Dict[str, Any])
Return type:: None

get_schema()[source]

Return the JSON schema for this tool’s parameters.

Return type:: Dict[str, Any]

async execute(**params)[source]

Execute the tool with the provided parameters.

Return type:: Dict[str, Any]

Plugin system interfaces.

These interfaces define the contracts for the plugin system, enabling extensibility through tools and plugins.

class solana_agent.interfaces.plugins.plugins.Tool[source]

Bases: ABC

Interface for tools that can be used by agents.

abstract property name: str: Get the name of the tool.

abstract property description: str: Get the description of the tool.

abstractmethod configure(config)[source]

Configure the tool with global configuration.

Parameters:: config (Dict[str, Any])
Return type:: None

abstractmethod get_schema()[source]

Get the schema for the tool parameters.

Return type:: Dict[str, Any]

abstractmethod async execute(**params)[source]

Execute the tool with the given parameters.

Return type:: Dict[str, Any]

class solana_agent.interfaces.plugins.plugins.ToolRegistry[source]

Bases: ABC

Interface for the tool registry.

abstractmethod register_tool(tool)[source]

Register a tool in the registry.

Parameters:: tool (Tool)
Return type:: bool

abstractmethod get_tool(tool_name)[source]

Get a tool by name.

Parameters:: tool_name (str)
Return type:: Tool | None

abstractmethod assign_tool_to_agent(agent_name, tool_name)[source]

Give an agent access to a specific tool.

Parameters:

agent_name (str)
tool_name (str)

Return type:

bool

abstractmethod get_agent_tools(agent_name)[source]

Get all tools available to an agent.

Parameters:: agent_name (str)
Return type:: List[Dict[str, Any]]

abstractmethod list_all_tools()[source]

List all registered tools.

Return type:: List[str]

abstractmethod configure_all_tools(config)[source]

Configure all registered tools with the same config.

Parameters:: config (Dict[str, Any])
Return type:: None

class solana_agent.interfaces.plugins.plugins.Plugin[source]

Bases: ABC

Interface for plugins that can be loaded by the system.

abstract property name: str: Get the name of the plugin.

abstract property description: str: Get the description of the plugin.

abstractmethod initialize(tool_registry)[source]

Initialize the plugin and register its tools.

Parameters:: tool_registry (ToolRegistry)
Return type:: bool

class solana_agent.interfaces.plugins.plugins.PluginManager[source]

Bases: ABC

Interface for the plugin manager.

abstractmethod register_plugin(plugin)[source]

Register a plugin in the manager.

Parameters:: plugin (Plugin)
Return type:: bool

abstractmethod load_plugins()[source]

Load all registered plugins.

Return type:: List[str]

abstractmethod get_plugin(name)[source]

Get a plugin by name.

Parameters:: name (str)
Return type:: Plugin | None

abstractmethod list_plugins()[source]

List all registered plugins with their details.

Return type:: List[Dict[str, Any]]

abstractmethod async execute_tool(tool_name, **kwargs)[source]

Execute a tool with the given parameters.

Parameters:: tool_name (str)
Return type:: Dict[str, Any]

abstractmethod configure(config)[source]

Configure the plugin manager and all plugins.

Parameters:: config (Dict[str, Any])
Return type:: None