axonnexus-sdk 1.0.0

A flexible Python SDK for the AxonNexus API on Hugging Face Spaces

AxonNexus SDK

A flexible, production-ready Python SDK for the AxonNexus API hosted on Hugging Face Spaces.

Features

✨ Flexible API Usage - Call any endpoint or model without SDK updates
🔐 Easy Authentication - Simple API key-based authentication
⚠️ Rate Limiting - Automatic token usage warnings
🚀 Production Ready - Type hints, docstrings, error handling
🔌 Discord/CLI Compatible - Works with any Python application
📦 PyPI Ready - Install via pip in seconds

Installation

pip install axonnexus_sdk

Quick Start

Basic Chat

from axonnexus_sdk import AxonNexusClient

# Initialize the client
client = AxonNexusClient(api_key="your_api_key_here")

# Send a chat message
response = client.chat("What is machine learning?")
print(response)

Using a Specific Model

# Use a specific model
response = client.chat("Hello!", model="gpt-4")
print(response["message"])

Generic API Requests

# Make a generic request to any endpoint
response = client.request(
    endpoint="/analyze",
    payload={"text": "Sample text to analyze"},
    model="analyzer-v1"
)
print(response)

Track Usage Statistics

# Get usage statistics
stats = client.get_usage_stats()
print(f"Requests made: {stats['request_count']}")
print(f"Tokens used: {stats['token_usage']}")

Using as Context Manager

# Automatically close the connection
with AxonNexusClient(api_key="your_api_key") as client:
    response = client.chat("Hello world!")
    print(response)
# Session is automatically closed

Development Mode

For testing without rate limit warnings:

# Use the test API key
client = AxonNexusClient(api_key="axn_test_123")
response = client.chat("Test message")
# No rate limit warnings will be shown in dev mode

Advanced Usage

Custom Base URL

# Point to a custom API endpoint
client = AxonNexusClient(
    api_key="your_api_key",
    base_url="https://custom-axonnexus-domain.com/api"
)

Request Timeout

# Set custom timeout (in seconds)
client = AxonNexusClient(
    api_key="your_api_key",
    timeout=60
)

Making Different HTTP Methods

# POST request (default)
response = client.request(
    endpoint="/process",
    payload={"data": "value"},
    method="POST"
)

# GET request
response = client.request(
    endpoint="/status",
    method="GET"
)

# PUT request
response = client.request(
    endpoint="/update",
    payload={"id": 1, "status": "active"},
    method="PUT"
)

# DELETE request
response = client.request(
    endpoint="/delete/123",
    method="DELETE"
)

Reset Usage Tracking

# Reset usage statistics
client.reset_usage_stats()
stats = client.get_usage_stats()
print(stats)  # All counts reset to 0

Discord Bot Integration

Here's an example of using the SDK in a Discord bot:

import discord
from discord.ext import commands
from axonnexus_sdk import AxonNexusClient

# Initialize bot and SDK client
bot = commands.Bot(command_prefix="!", intents=discord.Intents.default())
axn_client = AxonNexusClient(api_key="your_api_key")

@bot.command(name="ask")
async def ask_axonnexus(ctx, *, message):
    """Ask AxonNexus a question"""
    try:
        # Send typing indicator
        async with ctx.typing():
            # Make the API request
            response = axn_client.chat(message)
            
            # Format and send response
            reply = response.get("message", "No response received")
            
            # Discord has a 2000 character limit
            if len(reply) > 2000:
                reply = reply[:1997] + "..."
            
            await ctx.send(reply)
    except Exception as e:
        await ctx.send(f"Error: {str(e)}")

@bot.event
async def on_ready():
    print(f"Bot logged in as {bot.user}")

bot.run("your_discord_token")

CLI Tool Integration

Create a simple CLI tool:

#!/usr/bin/env python3
"""Simple CLI tool using AxonNexus SDK"""

import sys
from axonnexus_sdk import AxonNexusClient

def main():
    if len(sys.argv) < 2:
        print("Usage: axonnexus <message>")
        sys.exit(1)
    
    message = " ".join(sys.argv[1:])
    
    # Load API key from environment
    import os
    api_key = os.getenv("AXONNEXUS_API_KEY")
    if not api_key:
        print("Error: AXONNEXUS_API_KEY not set")
        sys.exit(1)
    
    # Make request
    with AxonNexusClient(api_key=api_key) as client:
        try:
            response = client.chat(message)
            print(response.get("message", "No response"))
        except Exception as e:
            print(f"Error: {e}")
            sys.exit(1)

if __name__ == "__main__":
    main()

Adding New Endpoints or Models

The SDK is designed to be future-proof. When AxonNexus adds new endpoints or models, you don't need to update the SDK:

Example: New Endpoint Added to AxonNexus

# Even if AxonNexus adds "/generate-image" endpoint, it works immediately:
response = client.request(
    endpoint="/generate-image",
    payload={"prompt": "a beautiful sunset"},
    model="image-gen-v1"
)

Example: New Model Added

# Just pass the new model name:
response = client.chat("Hello", model="new-powerful-model-v2")

No SDK update required!

Error Handling

from axonnexus_sdk import AxonNexusClient
import requests

client = AxonNexusClient(api_key="your_api_key")

try:
    response = client.chat("Hello")
except ValueError as e:
    # Invalid input
    print(f"Input error: {e}")
except requests.exceptions.RequestException as e:
    # Network or API error
    print(f"API error: {e}")
except Exception as e:
    # Unexpected error
    print(f"Unexpected error: {e}")

Configuration

Environment Variables (Optional)

# Set your API key
export AXONNEXUS_API_KEY="your_api_key"

# Then in your code:
import os
client = AxonNexusClient(api_key=os.getenv("AXONNEXUS_API_KEY"))

Rate Limiting

The SDK tracks token usage and warns when exceeding 10,000 tokens per session:

client = AxonNexusClient(api_key="your_api_key")

# Check if approaching limit
stats = client.get_usage_stats()
if stats['token_usage'] > 8000:
    print("⚠️ Approaching rate limit!")

API Response Format

Typical API responses follow this structure:

{
    "message": "Response from the model",
    "model": "model-name",
    "timestamp": "2026-01-30T12:00:00",
    "usage": {
        "tokens": 150
    }
}

Testing

# Test with development mode (no rate limit warnings)
test_client = AxonNexusClient(api_key="axn_test_123")

# Make test requests
response = test_client.chat("Test message")
print(response)

Troubleshooting

"Connection refused" error

• Check if the API is running on Hugging Face Spaces
• Verify the base_url is correct
• Check your internet connection

"Unauthorized" error

• Verify your API key is correct
• Check if the key has expired

Timeout errors

• Increase the timeout parameter
• Check your network speed
• Try again later if the API is slow

API Key Management

Never hardcode API keys in your source code! Use environment variables:

import os
from axonnexus_sdk import AxonNexusClient

api_key = os.getenv("AXONNEXUS_API_KEY")
if not api_key:
    raise ValueError("AXONNEXUS_API_KEY environment variable not set")

client = AxonNexusClient(api_key=api_key)

Performance Tips

1. Reuse the client - Don't create a new client for each request
2. Use context manager - Automatically handles cleanup
3. Batch requests - Group multiple operations together
4. Monitor usage - Check stats regularly to avoid rate limits

# Good practice
with AxonNexusClient(api_key=api_key) as client:
    response1 = client.chat("Question 1")
    response2 = client.chat("Question 2")
    response3 = client.request("/analyze", {"text": "data"})
    
    stats = client.get_usage_stats()
    print(f"Total requests: {stats['request_count']}")

Community & Support

Join our Discord community to get help, share ideas, and stay updated:

• 💬 Discord Community: https://dsc.gg/axoninnova
• 🐛 Report Issues: GitHub Issues
• 💡 Discussions: GitHub Discussions

About AxonNexus

AxonNexus is a cutting-edge platform for building and deploying AI models with ease.

Creator/Founder: Atharv (Nubprogrammer)

---

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Write tests
5. Submit a pull request

License

MIT License - See LICENSE file for details

Changelog

Version 1.0.0 (2026-01-31)

• Initial release
• Chat functionality
• Generic request method
• Rate limiting and usage tracking
• Full documentation
• Discord bot examples
• CLI integration examples
• Context manager support

Roadmap

• Async/await support
• Streaming responses
• Built-in caching
• Retry logic with exponential backoff
• WebSocket support for real-time interactions
• SDK plugins system
• Type stubs for better IDE support

---

Made with ❤️ by the AxonNexus team