Skip to content

About

Mosaia's Python SDK for interfacing with the Mosaia Core platform

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Mosaia Python SDK

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.

Features

  • 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

Installation

pip install mosaia

Quick Start

Basic Usage

from 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"
})

Using Individual Collections

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"
})

Sandbox Testing

The SDK includes a sandbox environment for testing and experimentation, similar to the Node.js sandbox/index.ts script.

Quick Setup

  1. Install the SDK in development mode:

    pip install -e .
  2. 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"
  3. Run the sandbox:

    python sandbox.py

Sandbox Features

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

Example Output

🧪 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!

Recent Updates

Initial Release (v0.0.1)

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

API Response Handling Improvements

The SDK includes improved API response handling and model instantiation:

  • ✅ Standardized Response Structure: All API responses follow a consistent structure with a data field
  • ✅ 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')

URL Construction Improvements

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 params

Authentication

API Key Authentication

from mosaia import MosaiaClient

client = MosaiaClient({
    "api_key": "your-api-key",
    "api_url": "https://api.mosaia.ai",
    "version": "1"
})

OAuth2 Authentication

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)

API Collections

Users

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)

Agents

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"}]
})

Applications

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"
})

Organizations

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"
})

Models

User Model

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()

Session Model

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")

Configuration

Configuration Manager

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-key

Environment Variables

You 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"

Error Handling

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 appropriately

Utilities

from 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")

Development

Installation for Development

git clone https://github.com/mosaia-development/mosaia-python-sdk.git
cd mosaia-python-sdk
pip install -e .[dev]

Running Tests

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/

Test Coverage

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

Code Quality

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/

Building and Deployment

Local Build

# Clean previous builds
make clean

# Build package
make build

# Test the built package
pip install dist/mosaia-0.0.1-py3-none-any.whl

Automated Deployment

The 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

Documentation

For detailed documentation, visit https://docs.mosaia.ai/python-sdk

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

About

Mosaia's Python SDK for interfacing with the Mosaia Core platform

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages