A comprehensive Python SDK for the Mosaia AI platform, providing access to all platform features including user management, organization management, AI agents, tools, applications, and more.
- Complete API Coverage: Access to all Mosaia platform APIs
- Authentication Support: API key and OAuth2 authentication
- Type Safety: Full type hints and dataclass support
- Pythonic Design: Follows Python best practices and conventions
- Async Support: Built-in async/await support for all operations
- Error Handling: Comprehensive error handling and validation
- Documentation: Extensive docstrings and examples
- Robust URL Construction: Proper API version injection and URL formatting
- Comprehensive Testing: Extensive test coverage with 20+ test cases
pip install mosaiafrom mosaia import MosaiaClient
# Initialize with API key and version
client = MosaiaClient({
"api_key": "your-api-key",
"api_url": "https://api.mosaia.ai",
"version": "1" # API version (defaults to "1")
})
# Get all users
users = await client.users.get()
# Create a new agent
agent = await client.agents.create({
"name": "My Agent",
"short_description": "A helpful AI agent"
})from mosaia import MosaiaClient
# Initialize the client first
client = MosaiaClient({
"api_key": "your-api-key",
"api_url": "https://api.mosaia.ai",
"version": "1"
})
# Access collections through the client
users = client.users
agents = client.agents
apps = client.apps
# Perform operations
all_users = await users.get()
agent = await agents.get(id="agent-id")
new_app = await apps.create({
"name": "My App",
"short_description": "Description"
})The SDK includes a sandbox environment for testing and experimentation, similar to the Node.js sandbox/index.ts script.
-
Install the SDK in development mode:
pip install -e . -
Set up environment variables (choose one option):
Option 1: Using .env file (recommended)
# Install python-dotenv pip install python-dotenv # Create .env file in project root echo "API_URL=https://api.mosaia.ai CLIENT_ID=your-client-id USER_EMAIL=user@example.com USER_PASSWORD=your-password" > .env
Option 2: Set environment variables manually
export API_URL="https://api.mosaia.ai" export CLIENT_ID="your-client-id" export USER_EMAIL="user@example.com" export USER_PASSWORD="your-password"
-
Run the sandbox:
python sandbox.py
The sandbox tests the following functionality:
- ✅ Authentication - Email/password authentication with proper API versioning
- ✅ Agents - Agent listing and chat completions
- ✅ Users - User session and user-related operations
- ✅ Organizations - Organization listing and details
- ✅ Tools - Tool listing and details
🧪 Mosaia Python SDK Sandbox
========================================
🚀 Initializing Mosaia SDK...
Attempting to sign in...
✅ Authentication successful!
Session user: John Doe
Session org: My Organization
🔍 Testing agents functionality...
Found 3 agents
First agent: Cafe Assistant
Description: AI assistant for cafe operations
Testing chat completion...
Agent response: Hello! I'm the Cafe Assistant, an AI designed to help with cafe operations...
👥 Testing users functionality...
Current user: John Doe (john@example.com)
User agents: 2 found
User organizations: 1 found
🏢 Testing organizations functionality...
Found 1 organizations
First organization: My Organization
Description: Main organization for development
🛠️ Testing tools functionality...
Found 5 tools
First tool: Weather Tool
Description: Get current weather information
✅ Sandbox tests completed successfully!
The SDK is now ready for production use with the following features:
- ✅ Complete Package Structure: Modern Python packaging with pyproject.toml
- ✅ Automated CI/CD: GitHub Actions workflow for testing and deployment
- ✅ Quality Assurance: Comprehensive linting and code quality checks
- ✅ Test Coverage: Full test suite covering all major functionality
- ✅ Documentation: Complete API documentation and examples
- ✅ Type Safety: Full type hints and dataclass support
The SDK includes improved API response handling and model instantiation:
- ✅ Standardized Response Structure: All API responses follow a consistent structure with a
datafield - ✅ Enhanced Model Instantiation: Models receive proper URI context for resource identification
- ✅ Improved Error Handling: Better error messages for invalid API responses
- ✅ Collection URI Support: Collections properly pass URIs to models for resource operations
Example Response Handling:
# Standardized response structure
response = {'data': {'id': '1', 'name': 'Test'}} # ✅ Proper data wrapper
model = Model(response['data'], '/resource') # ✅ With URI context
# Proper error handling
if not isinstance(response, dict) or 'data' not in response:
raise Exception('Invalid response from API')The SDK includes improved URL construction that properly handles API versioning:
- ✅ Proper API Version Injection: URLs correctly include the API version (e.g.,
/v1/auth/signin) - ✅ Leading Slash Handling: Automatic removal of leading slashes for consistent URL formatting
- ✅ Query Parameter Support: Proper query string construction and encoding
- ✅ Complex Path Support: Handles complex nested paths correctly
Example URL Construction:
# URLs now include proper API version
# https://api.mosaia.ai/v1/auth/signin # ✅ Correct
# https://api.mosaia.ai/v1/users/123/agents/456 # ✅ Complex paths
# https://api.mosaia.ai/v1/users?limit=10&offset=0 # ✅ Query paramsfrom mosaia import MosaiaClient
client = MosaiaClient({
"api_key": "your-api-key",
"api_url": "https://api.mosaia.ai",
"version": "1"
})from mosaia import MosaiaClient
# Initialize client with OAuth support
client = MosaiaClient({
"client_id": "your-client-id",
"client_secret": "your-client-secret",
"api_url": "https://api.mosaia.ai",
"version": "1"
})
# Create OAuth instance
oauth = client.oauth({
"redirect_uri": "https://your-app.com/callback",
"scopes": ["read", "write"]
})
# Get authorization URL and code verifier
auth_url, code_verifier = oauth.get_authorization_url_and_code_verifier()
# Redirect user to auth_url
# After user authorizes, you'll receive a code in your callback
# Exchange code for tokens
tokens = await oauth.authenticate_with_code_and_verifier(code, code_verifier)from mosaia import MosaiaClient
# Initialize the client first
client = MosaiaClient({
"api_key": "your-api-key",
"api_url": "https://api.mosaia.ai",
"version": "1"
})
# Access users collection
users = client.users
# Get all users
all_users = await users.get()
# Get users with pagination
users_page = await users.get({"limit": 10, "offset": 0})
# Get specific user
user = await users.get(id="user-id")
# Create new user
new_user = await users.create({
"email": "user@example.com",
"name": "John Doe"
})
# Update user
updated_user = await users.update("user-id", {
"name": "John Smith"
})
# Delete user
await users.delete("user-id")
# Search users
results = await users.search("john", limit=10)
# Get active users
active_users = await users.get_active_users(limit=50)from mosaia import MosaiaClient
# Initialize the client first
client = MosaiaClient({
"api_key": "your-api-key",
"api_url": "https://api.mosaia.ai",
"version": "1"
})
# Access agents collection
agents = client.agents
# Get all agents
all_agents = await agents.get()
# Get specific agent
agent = await agents.get(id="agent-id")
# Create new agent
new_agent = await agents.create({
"name": "My Agent",
"short_description": "A helpful AI agent",
"model": "gpt-4"
})
# Chat completion
completion = await agents.chat_completion("agent-id", {
"model": "gpt-4",
"messages": [{"role": "user", "content": "Hello"}]
})from mosaia import MosaiaClient
# Initialize the client first
client = MosaiaClient({
"api_key": "your-api-key",
"api_url": "https://api.mosaia.ai",
"version": "1"
})
# Access apps collection
apps = client.apps
# Get all applications
all_apps = await apps.get()
# Get specific application
app = await apps.get(id="app-id")
# Create new application
new_app = await apps.create({
"name": "My App",
"short_description": "Description"
})from mosaia import MosaiaClient
# Initialize the client first
client = MosaiaClient({
"api_key": "your-api-key",
"api_url": "https://api.mosaia.ai",
"version": "1"
})
# Access organizations collection
orgs = client.organizations
# Get all organizations
all_orgs = await orgs.get()
# Get specific organization
org = await orgs.get(id="org-id")
# Create new organization
new_org = await orgs.create({
"name": "My Organization",
"short_description": "Description"
})from mosaia.models import User
# Create user instance
user = User({
"email": "john@example.com",
"name": "John Doe",
"username": "johndoe"
})
# Access properties
print(user.email) # john@example.com
print(user.name) # John Doe
# Update user
user.update({"name": "John Smith"})
await user.save()
# Convert to JSON
user_data = user.to_json()from mosaia import MosaiaClient
client = MosaiaClient({"api_key": "your-api-key"})
# Get current session
session = await client.session()
# Access user and organization
if session.user:
print(f"User: {session.user.email}")
if session.org:
print(f"Organization: {session.org.name}")
# Check permissions
if session.has_permission("read", "users"):
print("User can read users")from mosaia import ConfigurationManager
# Get singleton instance
config_manager = ConfigurationManager.get_instance()
# Initialize with configuration
config_manager.initialize({
"api_key": "your-api-key",
"api_url": "https://api.mosaia.ai",
"version": "1",
"client_id": "your-client-id",
"client_secret": "your-client-secret",
"verbose": True
})
# Access configuration
config = config_manager.get_config()
print(config.api_key) # your-api-keyYou can also use environment variables for configuration:
export MOSAIA_API_KEY="your-api-key"
export MOSAIA_API_URL="https://api.mosaia.ai"
export MOSAIA_CLIENT_ID="your-client-id"
export MOSAIA_CLIENT_SECRET="your-client-secret"from mosaia import MosaiaClient
client = MosaiaClient({"api_key": "your-api-key"})
try:
users = await client.users.get()
except Exception as e:
print(f"Error: {e}")
# Handle error appropriatelyfrom mosaia.utils import (
is_valid_object_id,
parse_error,
query_generator,
is_timestamp_expired
)
# Validate ObjectId
is_valid = is_valid_object_id("507f1f77bcf86cd799439011")
# Parse error
error_info = parse_error(exception)
# Generate query string
query_string = query_generator({
"limit": 10,
"offset": 0,
"search": "john"
})
# Check if timestamp is expired
is_expired = is_timestamp_expired("2024-01-01T00:00:00Z")git clone https://github.com/mosaia-development/mosaia-python-sdk.git
cd mosaia-python-sdk
pip install -e .[dev]The SDK includes comprehensive test coverage with 20+ test cases:
# Run all tests
pytest
# Run specific test categories
pytest tests/unit/test_api_client.py -v # API client tests
pytest tests/unit/test_basic.py -v # Basic functionality tests
# Run tests with coverage
pytest --cov=mosaia tests/The test suite covers:
-
✅ Basic APIClient Functionality (6 tests)
- Client creation with configuration
- Header construction (Authorization, Content-Type)
- Base URL construction with version injection
- Base URL with different versions
- Base URL with default version
- Base URL with custom API URL
-
✅ URL Construction (3 tests)
- URL construction with leading slash removal
- URL construction with query parameters
- URL construction with different API versions
-
✅ Request Methods (4 tests)
- GET, POST, PUT, DELETE request methods
-
✅ Error Handling (2 tests)
- Error response creation
- Error handling with custom status codes
The project includes comprehensive code quality tools:
# Run linting
flake8 mosaia/ tests/
# Run code formatting
black mosaia/ tests/
isort mosaia/ tests/
# Run type checking
mypy mosaia/# Clean previous builds
make clean
# Build package
make build
# Test the built package
pip install dist/mosaia-0.0.1-py3-none-any.whlThe project uses GitHub Actions for automated CI/CD:
- Testing: Runs on Python 3.8-3.12
- Quality Checks: Linting, formatting, and type checking
- Build: Automated package building
- Deployment: Automatic PyPI deployment on releases
For detailed documentation, visit https://docs.mosaia.ai/python-sdk
We welcome contributions! Please see our Contributing Guide for details.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- Documentation: https://docs.mosaia.ai/python-sdk
- Issues: https://github.com/mosaia-development/mosaia-python-sdk/issues
- Email: support@mosaia.ai