Skip to main content

Nexus SDK

The official Python SDK for AI Nexus, a centralized repository system for AI agents. This SDK provides easy access to discover, manage, and interact with AI agents through the Nexus platform.

🚀 Features​

  • Agent Discovery: Search and discover AI agents from the Nexus repository
  • Caching System: Intelligent local caching for improved performance
  • Authentication: Secure authentication with Supabase backend
  • CLI Interface: Command-line tools for easy agent management
  • Type Safety: Full type hints and Pydantic models for robust development
  • Async Support: Both synchronous and asynchronous API support

📦 Installation​

Using pip​

pip install ainexus-sdk
uv add ainexus-sdk

Development Installation​

git clone https://github.com/CHARLIE1210-A/nexus-sdk.git
cd nexus-sdk
uv install --dev

⚡ Quick Start​

1. Authentication​

First, authenticate with your Nexus account:

ainexus login

You'll be prompted to enter your email and password.

2. Basic Usage​

from ainexus_sdk.client import AgentSDK

# Initialize the SDK
sdk = AgentSDK()

# Discover all agents
agents = sdk.discover()
print(f"Found {len(agents)} agents")

# Discover a specific agent
agent = sdk.discover("agent-id-123")
print(f"Agent: {agent[0].name}")

# Discover multiple agents
agents = sdk.discover(["agent-1", "agent-2", "agent-3"])

3. Using the CLI​

# Login to your account
ainexus login

# The SDK will automatically use your stored credentials

📖 API Reference​

AgentSDK Class​

The main class for interacting with the Nexus platform.

Constructor​

AgentSDK(
    auth_token: Optional[str] = None,
    api_key: Optional[str] = None,
    base_url: str = "",
    timeout: int = 30
)

Parameters:

  • auth_token (str, optional): Manual authentication token override
  • api_key (str, optional): API key for additional authentication
  • base_url (str): Base URL for the Nexus API
  • timeout (int): Request timeout in seconds

Methods​

discover(agent_id, refresh=False)​

Discover agents from the Nexus repository.

Parameters:

  • agent_id (str | List[str] | None):
    • str: Discover a single agent by ID
    • List[str]: Discover multiple agents by their IDs
    • None: Discover all available agents
  • refresh (bool): Force refresh from server, bypassing cache

Returns:

  • List[AgentMetadata]: List of agent metadata objects

Examples:

# Single agent
agent = sdk.discover("gpt-4-agent")

# Multiple agents
agents = sdk.discover(["agent-1", "agent-2"])

# All agents
all_agents = sdk.discover()

# Force refresh from server
fresh_agents = sdk.discover(refresh=True)

AgentMetadata Model​

Represents metadata for an AI agent.

Properties:

  • id (str): Unique agent identifier
  • name (str): Agent display name
  • description (str): Short description
  • long_description (str): Detailed description
  • category (str): Agent category
  • tags (List[str]): Tags for categorization
  • rating (float): User rating
  • installs (int): Number of installations
  • user_id (str): Creator's user ID
  • icon_name (str): Icon identifier
  • screenshots (List[str]): Screenshot URLs
  • repo_url (str): Repository URL
  • agent_card (Dict): Additional agent configuration
  • featured (bool): Whether agent is featured
  • trending (bool): Whether agent is trending
  • created_at (datetime): Creation timestamp
  • updated_at (datetime): Last update timestamp
  • docker_image (str): Docker image reference

🔧 Configuration​

Authentication​

The SDK uses a configuration file stored at ~/.agenthub/config.json after running ainexus login. This file contains:

{
  "user": {
    "id": "user-id",
    "email": "user@example.com"
  },
  "access_token": "your-access-token"
}

Caching​

Agents are cached locally at ~/.cache/agenthub/agents_metadata/ to improve performance. Cache files are automatically managed but can be refreshed using the refresh=True parameter.

📁 Examples​

Basic Agent Discovery​

from ainexus_sdk.client import AgentSDK

def main():
    sdk = AgentSDK()
    
    try:
        # Get all agents
        agents = sdk.discover()
        
        for agent in agents:
            print(f"🤖 {agent.name}")
            print(f"   📝 {agent.description}")
            print(f"   ⭐ Rating: {agent.rating}")
            print(f"   📦 Installs: {agent.installs}")
            print()
            
    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    main()

Filtering and Searching​

from ainexus_sdk.client import AgentSDK

def find_agents_by_category(category: str):
    sdk = AgentSDK()
    agents = sdk.discover()
    
    filtered = [agent for agent in agents if agent.category == category]
    return filtered

def find_trending_agents():
    sdk = AgentSDK()
    agents = sdk.discover()
    
    trending = [agent for agent in agents if agent.trending]
    return trending

# Usage
ai_assistants = find_agents_by_category("AI Assistant")
trending = find_trending_agents()

Error Handling​

from ainexus_sdk.client import AgentSDK

def robust_discovery():
    sdk = AgentSDK()
    
    try:
        agents = sdk.discover("specific-agent-id")
        return agents
    except ValueError as e:
        print(f"Agent not found: {e}")
        return []
    except Exception as e:
        print(f"Unexpected error: {e}")
        return []