mesh-beta 1.0.3

Official Python SDK for the Mesh API - Secure key management and AI model access

Mesh SDK for Python

A powerful Python SDK for interacting with the Mesh API, featuring key management, Zero-Knowledge Proofs, and AI chat capabilities.

Quick Start

# Install the SDK
pip install mesh-beta

# When you first use the SDK, you'll be prompted to authenticate
# The SDK will display a URL and code for you to complete authentication

import mesh

# First-time use will trigger authentication
# You'll see a URL and code to enter in your browser
response = mesh.chat("Hello, world!")

Authentication

The first time you use the SDK, you'll need to authenticate. The SDK will automatically start the authentication process and display a URL and code for you to enter in your browser.

If automatic authentication fails, you can manually authenticate by running:

mesh-auth

For headless environments (servers without browsers):

mesh-auth --headless

Installation

pip install mesh-beta

For development:

git clone https://github.com/yourusername/mesh.git
cd mesh/sdk/python
pip install -e .

Features

• Authentication: Secure authentication with Auth0, including auto-refresh capabilities
• Key Management: Store and retrieve keys with optional Zero-Knowledge Proof verification
• Chat Integration: Easy-to-use interface for OpenAI and Anthropic models
• Configurability: Extensive configuration options via environment variables

Quick Start

from mesh import MeshClient

# Initialize the client
client = MeshClient()

# Chat with an AI model
response = client.chat("Hello, world!")
print(response['content'])

# Store a key (user_id is automatically extracted from your token)
client.store_key(key_name="api_key", key_value="secret_value")

# Get a key (user_id is automatically extracted from your token)
key_result = client.get_key(key_name="api_key")

Authentication

The SDK supports several authentication methods:

1. Direct token authentication - Provide an auth_token when initializing the client
2. Browser-based authentication - Authentication via Auth0 will be triggered automatically when needed
3. Environment variables - Set MESH_AUTH_TOKEN in your environment

# Direct token
client = MeshClient(auth_token="your_token")

# If no token is provided, browser-based auth will be triggered when needed
client = MeshClient()
response = client.chat("This will trigger auth if needed")

Key Management

The SDK now automatically extracts your user ID from your authentication token, making key management simpler:

# Store a key (user_id is extracted from your token)
client.store_key(key_name="openai_key", key_value="sk-abcdef123456")

# Get a key (user_id is extracted from your token)
key_result = client.get_key(key_name="openai_key")

# List all keys for the current user
keys = client.list_keys()
print(keys)  # ['openai_key', 'anthropic_key', 'api_key', ...]

# You can still provide a user_id manually if needed
client.store_key(user_id="custom-user-id", key_name="api_key", key_value="secret_value")
client.list_keys(user_id="custom-user-id")  # List keys for a specific user

Configuration

The SDK offers extensive configuration options that can be set through environment variables or directly in code.

Environment Variables

Variable	Description	Default Value
AUTH0_DOMAIN	Auth0 domain	(Configure in environment)
AUTH0_CLIENT_ID	Auth0 client ID	(Configure in environment)
AUTH0_CLIENT_SECRET	Auth0 client secret	(Secure value)
AUTH0_AUDIENCE	Auth0 audience	(Configure in environment)
AUTH0_CALLBACK_PORT	Port for Auth0 callback	8000
MESH_API_URL	Mesh API server URL	(Configure in environment)
DEBUG	Enable debug logging	false
AUTO_REFRESH	Enable automatic token refresh	true
DEFAULT_OPENAI_MODEL	Default OpenAI model	gpt-4
DEFAULT_ANTHROPIC_MODEL	Default Anthropic model	claude-3-opus-20240229
DEFAULT_PROVIDER	Default AI provider	openai

Configuration in Code

You can also configure the SDK directly in code:

from mesh import MeshClient

# Override defaults in the constructor
client = MeshClient(
    server_url="https://custom-server.example.com",
    client_id="your-client-id",
    client_secret="your-client-secret",
    audience="your-audience",
    auth0_domain="your-domain.auth0.com",
    original_response=True  # Return raw API responses
)

Auto-Refresh Client

For long-running applications, use the AutoRefreshMeshClient that can automatically refresh authentication tokens:

from mesh.auto_refresh_client import AutoRefreshMeshClient

# Create an auto-refresh client
client = AutoRefreshMeshClient(
    auto_refresh=True,  # Enable auto-refresh (default if not specified)
    refresh_margin=300  # Refresh 5 minutes before expiry
)

Advanced Usage

Using Different Models

You can specify different AI models:

# OpenAI models
response = client.chat("Tell me about quantum computing", model="gpt-4")

# Anthropic models
response = client.chat("Tell me about biology", 
                      model="claude-3-opus-20240229",
                      provider="anthropic")

Zero-Knowledge Proofs

Store and verify keys with zero-knowledge proofs:

# Store with ZKP
client.store_key_zkp("user123", "api_key", "secret_value")

# Verify with ZKP
result = client.verify_key("user123", "api_key", "secret_value")

Error Handling

The SDK provides detailed error information:

response = client.chat("Hello")
if not response.get("success", True):
    print(f"Error: {response.get('error')}")
    print(f"Details: {response.get('details')}")
    
    # For troubleshooting guidance
    if "troubleshooting" in response:
        print("Troubleshooting steps:")
        for step in response["troubleshooting"]:
            print(f"- {step}")

Debugging

Enable debug mode for verbose logging:

# Via environment variable
os.environ["DEBUG"] = "true"

# Or in code
client = MeshClient(debug=True)

Contributing

Contributions 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.

Troubleshooting

Connection Issues

• Verify that the server URL is correct. By default, the SDK uses https://mesh-abh5.onrender.com.
• Check that the server is running and accessible from your network.
• If you're using a custom server, ensure it's properly configured and running.

Endpoint Availability

• The SDK tries multiple endpoints to ensure compatibility with different server configurations.
• If you're getting "All endpoints failed" errors, check that the server has the required endpoints enabled.
• The SDK supports both new API endpoints (under /api/v1/) and legacy endpoints (under /v1/mesh/).

Authentication Errors

• Ensure you have a valid authentication token. Run mesh-auth to authenticate manually.
• Check that your Auth0 credentials are correct if using browser-based authentication.
• Verify that your token hasn't expired. Tokens typically expire after a certain period.

User Registration

• Chat functionality requires the user to be registered in the database.
• The SDK automatically attempts to register the user by calling the profile endpoint before the first chat request.
• If you're getting "User not found" errors, try calling the auth profile endpoint directly first.

Message Format

• When using the chat functionality, ensure your messages are properly formatted.
• The SDK supports both "message" and "prompt" formats for compatibility with different server configurations.
• If you're getting format errors, check the server's expected message format.

Debug Logging

• Enable debug logging by setting debug=True when initializing the client.
• This will provide detailed information about the requests and responses.
• Debug logs can help identify the root cause of issues.

Advanced Configuration

# Environment variables for configuration
# MESH_API_URL - Base server URL
# OPENAI_API_KEY - OpenAI API key
# ANTHROPIC_API_KEY - Anthropic API key
# DEFAULT_PROVIDER - Default AI provider
# DEFAULT_MODEL - Default model to use

# Set default model for a provider
client.set_default_model("openai", "gpt-4")
client.set_default_model("anthropic", "claude-3-7-sonnet-20250219")

# Reset to original defaults
client.reset_default_models()

API Reference

For complete API documentation, please refer to the docstrings in the code.

Chat Functionality

The SDK provides a simple interface to chat with AI models:

# Chat with default model
response = client.chat("Hello, world!")

# Chat with specific model
response = client.chat("Hello, world!", model="gpt-4o", provider="openai")

# Enable thinking mode (Claude 3.7 Sonnet only)
response = client.chat("Solve this complex problem...", model="claude-3-7-sonnet-20250219", thinking=True)

# Get raw API response
response = client.chat("Hello, world!", original_response=True)

Automatic User Registration

The SDK automatically ensures that the user is registered in the database before sending chat requests. This is necessary because the chat endpoints require the user to exist in the database. The registration process happens transparently when you make your first chat request:

# The first chat request will automatically register the user if needed
response = client.chat("Hello, world!")

If the user registration fails, the SDK will return an error with troubleshooting steps:

{
    "success": False,
    "error": "Failed to register user. Chat requires user registration.",
    "troubleshooting": [
        "Try calling the auth profile endpoint directly first",
        "Verify your authentication token is valid",
        "Check that the server URL is correct"
    ]
}

Helper Methods

The SDK also provides helper methods for common chat scenarios:

# Chat with GPT-4o
response = client.chat_with_gpt4o("Hello, world!")

# Chat with Claude
response = client.chat_with_claude("Hello, world!")

# Chat with the best model for a provider
response = client.chat_with_best_model("Hello, world!", provider="openai")

# Chat with the fastest model for a provider
response = client.chat_with_fastest_model("Hello, world!", provider="anthropic")

# Chat with the cheapest model for a provider
response = client.chat_with_cheapest_model("Hello, world!")

Using Claude Models

The Mesh SDK supports Anthropic's Claude models and provides several ways to use them:

from mesh import MeshClient

client = MeshClient()

# Method 1: Use the built-in helper method (recommended)
response = client.chat_with_claude("Write a haiku about programming")

# Specify Claude version
response = client.chat_with_claude("Write a haiku about programming", version="3.7")  # Use Claude 3.7
response = client.chat_with_claude("Write a haiku about programming", version="3")    # Use Claude 3 Opus

# Method 2: Specify the provider and model explicitly
response = client.chat(
    message="Write a haiku about programming",
    model="claude-3-7-sonnet-20250219",
    provider="anthropic"
)

# Method 3: Use a model alias (which maps to a specific version)
response = client.chat(
    message="Write a haiku about programming",
    model="claude-37"  # Aliased to claude-3-7-sonnet-20250219
)

Claude Model Aliases

The SDK provides several aliases for Claude models to make them easier to use:

Alias	Maps to	Description
claude	claude-3-5-sonnet-20241022	Latest stable Claude
claude-37	claude-3-7-sonnet-20250219	Claude 3.7 Sonnet
claude-35	claude-3-5-sonnet-20241022	Claude 3.5 Sonnet
claude-35-haiku	claude-3-5-haiku-20241022	Claude 3.5 Haiku
claude-3	claude-3-opus-20240229	Claude 3 Opus
claude-opus	claude-3-opus-20240229	Claude 3 Opus
claude-sonnet	claude-3-sonnet-20240229	Claude 3 Sonnet
claude-haiku	claude-3-haiku-20240307	Claude 3 Haiku

Note: When using the claude alias directly, it's mapped to a specific version of Claude (currently Claude 3.5 Sonnet) for stability. This may not be the absolute latest Claude model. For the most reliable way to use specific Claude versions:

• Use chat_with_claude(message, version="3.7") to explicitly select the version
• Or specify the full model ID with model="claude-3-7-sonnet-20250219"

Simplified API

The SDK also provides a simplified API that can be used directly without creating a client instance:

import mesh

# Chat with an AI model
response = mesh.chat("Hello, world!")

# Store a key
mesh.store_key(key_name="api_key", key_value="secret_value")

# Get a key
key_value = mesh.get_key(key_name="api_key")

# List all keys for the current user
keys = mesh.list_keys()
print(keys)  # ['api_key', 'openai_key', 'anthropic_key', ...]

# List keys for a specific user
keys = mesh.list_keys(user_id="custom-user-id")

This simplified API is perfect for quick scripts and applications where you don't need the full flexibility of the client instance.

Authentication Troubleshooting

If you encounter authentication issues when using the SDK, here are some common problems and solutions:

Port Already in Use

The SDK uses a local server on port 8000 (by default) to handle the OAuth callback. If this port is already in use, the SDK will now automatically try ports 8000-8009 until it finds an available one.

If all ports are in use, you can:

• Close applications that might be using these ports
• Specify a different port: mesh-auth --port 9000
• Use the headless authentication method: mesh-auth --headless

Browser Not Opening

If the SDK fails to open a browser automatically, it will now display a URL that you can manually copy and paste into your browser.

Authentication Server Errors

If you see "Failed to start authentication server" errors:

• Check if your firewall is blocking the local server
• Try the headless authentication method: mesh-auth --headless
• Ensure you have network connectivity to the Auth0 domain

Headless Environments

For servers or environments without a browser:

# Use the device code flow
mesh-auth --headless

This will display a URL and a code that you can use on another device to authenticate.

Automatic Authentication

The SDK now attempts to authenticate automatically when you first use it:

1. First using device code flow (which doesn't require a local server)
2. Then falling back to browser-based authentication if needed
3. Trying multiple ports if the default port is in use

If automatic authentication fails, you'll need to run mesh-auth manually.

Auth0 Configuration

For the SDK to work properly, you need to configure your Auth0 application correctly:

Device Code Flow Configuration

To enable the device code flow (used for headless authentication):

1. Log in to your Auth0 dashboard
2. Go to "Applications" > Select your application
3. Go to the "Settings" tab
4. Under "Advanced Settings" > "Grant Types"
5. Make sure "Device Code" is checked
6. Under "Advanced Settings" > "Device Settings"
7. Enable "Device Flow with Polling"

API Configuration

1. Go to "APIs" > Select your API
2. Under "Settings"
3. Enable "Allow Offline Access" to get refresh tokens
4. Make sure the appropriate grant types are enabled

Callback URLs

For browser-based authentication, add the following to "Allowed Callback URLs":

http://localhost:45678/callback

The SDK now uses port 45678 by default, which is less likely to conflict with other applications.