# 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
```bash
pip install mosaia
```
## Quick Start
### Basic Usage
```python
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
```python
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.ts` file.
### Quick Setup
1. **Install the SDK in development mode**:
```bash
pip install -e .
```
2. **Set up environment variables** (choose one option):
**Option 1: Using .env file (recommended)**
```bash
# 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**
```bash
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**:
```bash
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**:
```python
# 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**:
```python
# 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
```python
from mosaia import MosaiaClient
client = MosaiaClient({
"api_key": "your-api-key",
"api_url": "https://api.mosaia.ai",
"version": "1"
})
```
### OAuth2 Authentication
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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:
```bash
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
```python
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
```python
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
```bash
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:
```bash
# 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:
```bash
# Run linting
flake8 mosaia/ tests/
# Run code formatting
black mosaia/ tests/
isort mosaia/ tests/
# Run type checking
mypy mosaia/
```
## Building and Deployment
### Local Build
```bash
# 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](https://docs.mosaia.ai/python-sdk)
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## Support
- Documentation: [https://docs.mosaia.ai/python-sdk](https://docs.mosaia.ai/python-sdk)
- Issues: [https://github.com/mosaia-development/mosaia-python-sdk/issues](https://github.com/mosaia-development/mosaia-python-sdk/issues)
- Email: support@mosaia.ai
Raw data
{
"_id": null,
"home_page": "https://github.com/mosaia-development/mosaia-python-sdk",
"name": "mosaia",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Mosaia Team <support@mosaia.ai>",
"keywords": "ai, artificial intelligence, api, sdk, mosaia, agents, tools, applications",
"author": "Mosaia Team",
"author_email": "Mosaia Team <support@mosaia.ai>",
"download_url": "https://files.pythonhosted.org/packages/15/b1/29558c0f0be6322f4bb988ca4dcff526842349edd8af9e72615f1216adf8/mosaia-0.0.4.tar.gz",
"platform": null,
"description": "# Mosaia Python SDK\n\nA 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.\n\n## Features\n\n- **Complete API Coverage**: Access to all Mosaia platform APIs\n- **Authentication Support**: API key and OAuth2 authentication\n- **Type Safety**: Full type hints and dataclass support\n- **Pythonic Design**: Follows Python best practices and conventions\n- **Async Support**: Built-in async/await support for all operations\n- **Error Handling**: Comprehensive error handling and validation\n- **Documentation**: Extensive docstrings and examples\n- **Robust URL Construction**: Proper API version injection and URL formatting\n- **Comprehensive Testing**: Extensive test coverage with 20+ test cases\n\n## Installation\n\n```bash\npip install mosaia\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom mosaia import MosaiaClient\n\n# Initialize with API key and version\nclient = MosaiaClient({\n \"api_key\": \"your-api-key\",\n \"api_url\": \"https://api.mosaia.ai\",\n \"version\": \"1\" # API version (defaults to \"1\")\n})\n\n# Get all users\nusers = await client.users.get()\n\n# Create a new agent\nagent = await client.agents.create({\n \"name\": \"My Agent\",\n \"short_description\": \"A helpful AI agent\"\n})\n```\n\n### Using Individual Collections\n\n```python\nfrom mosaia import MosaiaClient\n\n# Initialize the client first\nclient = MosaiaClient({\n \"api_key\": \"your-api-key\",\n \"api_url\": \"https://api.mosaia.ai\",\n \"version\": \"1\"\n})\n\n# Access collections through the client\nusers = client.users\nagents = client.agents\napps = client.apps\n\n# Perform operations\nall_users = await users.get()\nagent = await agents.get(id=\"agent-id\")\nnew_app = await apps.create({\n \"name\": \"My App\",\n \"short_description\": \"Description\"\n})\n```\n\n## Sandbox Testing\n\nThe SDK includes a sandbox environment for testing and experimentation, similar to the Node.js `sandbox.ts` file.\n\n### Quick Setup\n\n1. **Install the SDK in development mode**:\n ```bash\n pip install -e .\n ```\n\n2. **Set up environment variables** (choose one option):\n\n **Option 1: Using .env file (recommended)**\n ```bash\n # Install python-dotenv\n pip install python-dotenv\n \n # Create .env file in project root\n echo \"API_URL=https://api.mosaia.ai\n CLIENT_ID=your-client-id\n USER_EMAIL=user@example.com\n USER_PASSWORD=your-password\" > .env\n ```\n\n **Option 2: Set environment variables manually**\n ```bash\n export API_URL=\"https://api.mosaia.ai\"\n export CLIENT_ID=\"your-client-id\"\n export USER_EMAIL=\"user@example.com\"\n export USER_PASSWORD=\"your-password\"\n ```\n\n3. **Run the sandbox**:\n ```bash\n python sandbox.py\n ```\n\n### Sandbox Features\n\nThe sandbox tests the following functionality:\n- \u2705 **Authentication** - Email/password authentication with proper API versioning\n- \u2705 **Agents** - Agent listing and chat completions\n- \u2705 **Users** - User session and user-related operations\n- \u2705 **Organizations** - Organization listing and details\n- \u2705 **Tools** - Tool listing and details\n\n### Example Output\n\n```\n\ud83e\uddea Mosaia Python SDK Sandbox\n========================================\n\ud83d\ude80 Initializing Mosaia SDK...\n Attempting to sign in...\n\u2705 Authentication successful!\n Session user: John Doe\n Session org: My Organization\n\n\ud83d\udd0d Testing agents functionality...\n Found 3 agents\n First agent: Cafe Assistant\n Description: AI assistant for cafe operations\n Testing chat completion...\n Agent response: Hello! I'm the Cafe Assistant, an AI designed to help with cafe operations...\n\n\ud83d\udc65 Testing users functionality...\n Current user: John Doe (john@example.com)\n User agents: 2 found\n User organizations: 1 found\n\n\ud83c\udfe2 Testing organizations functionality...\n Found 1 organizations\n First organization: My Organization\n Description: Main organization for development\n\n\ud83d\udee0\ufe0f Testing tools functionality...\n Found 5 tools\n First tool: Weather Tool\n Description: Get current weather information\n\n\u2705 Sandbox tests completed successfully!\n```\n\n## Recent Updates\n\n### Initial Release (v0.0.1)\n\nThe SDK is now ready for production use with the following features:\n\n- \u2705 **Complete Package Structure**: Modern Python packaging with pyproject.toml\n- \u2705 **Automated CI/CD**: GitHub Actions workflow for testing and deployment\n- \u2705 **Quality Assurance**: Comprehensive linting and code quality checks\n- \u2705 **Test Coverage**: Full test suite covering all major functionality\n- \u2705 **Documentation**: Complete API documentation and examples\n- \u2705 **Type Safety**: Full type hints and dataclass support\n\n### API Response Handling Improvements\n\nThe SDK includes improved API response handling and model instantiation:\n\n- \u2705 **Standardized Response Structure**: All API responses follow a consistent structure with a `data` field\n- \u2705 **Enhanced Model Instantiation**: Models receive proper URI context for resource identification\n- \u2705 **Improved Error Handling**: Better error messages for invalid API responses\n- \u2705 **Collection URI Support**: Collections properly pass URIs to models for resource operations\n\n**Example Response Handling**:\n```python\n# Standardized response structure\nresponse = {'data': {'id': '1', 'name': 'Test'}} # \u2705 Proper data wrapper\nmodel = Model(response['data'], '/resource') # \u2705 With URI context\n\n# Proper error handling\nif not isinstance(response, dict) or 'data' not in response:\n raise Exception('Invalid response from API')\n```\n\n### URL Construction Improvements\n\nThe SDK includes improved URL construction that properly handles API versioning:\n\n- \u2705 **Proper API Version Injection**: URLs correctly include the API version (e.g., `/v1/auth/signin`)\n- \u2705 **Leading Slash Handling**: Automatic removal of leading slashes for consistent URL formatting\n- \u2705 **Query Parameter Support**: Proper query string construction and encoding\n- \u2705 **Complex Path Support**: Handles complex nested paths correctly\n\n**Example URL Construction**:\n```python\n# URLs now include proper API version\n# https://api.mosaia.ai/v1/auth/signin # \u2705 Correct\n# https://api.mosaia.ai/v1/users/123/agents/456 # \u2705 Complex paths\n# https://api.mosaia.ai/v1/users?limit=10&offset=0 # \u2705 Query params\n```\n\n## Authentication\n\n### API Key Authentication\n\n```python\nfrom mosaia import MosaiaClient\n\nclient = MosaiaClient({\n \"api_key\": \"your-api-key\",\n \"api_url\": \"https://api.mosaia.ai\",\n \"version\": \"1\"\n})\n```\n\n### OAuth2 Authentication\n\n```python\nfrom mosaia import MosaiaClient\n\n# Initialize client with OAuth support\nclient = MosaiaClient({\n \"client_id\": \"your-client-id\",\n \"client_secret\": \"your-client-secret\",\n \"api_url\": \"https://api.mosaia.ai\",\n \"version\": \"1\"\n})\n\n# Create OAuth instance\noauth = client.oauth({\n \"redirect_uri\": \"https://your-app.com/callback\",\n \"scopes\": [\"read\", \"write\"]\n})\n\n# Get authorization URL and code verifier\nauth_url, code_verifier = oauth.get_authorization_url_and_code_verifier()\n\n# Redirect user to auth_url\n# After user authorizes, you'll receive a code in your callback\n\n# Exchange code for tokens\ntokens = await oauth.authenticate_with_code_and_verifier(code, code_verifier)\n```\n\n## API Collections\n\n### Users\n\n```python\nfrom mosaia import MosaiaClient\n\n# Initialize the client first\nclient = MosaiaClient({\n \"api_key\": \"your-api-key\",\n \"api_url\": \"https://api.mosaia.ai\",\n \"version\": \"1\"\n})\n\n# Access users collection\nusers = client.users\n\n# Get all users\nall_users = await users.get()\n\n# Get users with pagination\nusers_page = await users.get({\"limit\": 10, \"offset\": 0})\n\n# Get specific user\nuser = await users.get(id=\"user-id\")\n\n# Create new user\nnew_user = await users.create({\n \"email\": \"user@example.com\",\n \"name\": \"John Doe\"\n})\n\n# Update user\nupdated_user = await users.update(\"user-id\", {\n \"name\": \"John Smith\"\n})\n\n# Delete user\nawait users.delete(\"user-id\")\n\n# Search users\nresults = await users.search(\"john\", limit=10)\n\n# Get active users\nactive_users = await users.get_active_users(limit=50)\n```\n\n### Agents\n\n```python\nfrom mosaia import MosaiaClient\n\n# Initialize the client first\nclient = MosaiaClient({\n \"api_key\": \"your-api-key\",\n \"api_url\": \"https://api.mosaia.ai\",\n \"version\": \"1\"\n})\n\n# Access agents collection\nagents = client.agents\n\n# Get all agents\nall_agents = await agents.get()\n\n# Get specific agent\nagent = await agents.get(id=\"agent-id\")\n\n# Create new agent\nnew_agent = await agents.create({\n \"name\": \"My Agent\",\n \"short_description\": \"A helpful AI agent\",\n \"model\": \"gpt-4\"\n})\n\n# Chat completion\ncompletion = await agents.chat_completion(\"agent-id\", {\n \"model\": \"gpt-4\",\n \"messages\": [{\"role\": \"user\", \"content\": \"Hello\"}]\n})\n```\n\n### Applications\n\n```python\nfrom mosaia import MosaiaClient\n\n# Initialize the client first\nclient = MosaiaClient({\n \"api_key\": \"your-api-key\",\n \"api_url\": \"https://api.mosaia.ai\",\n \"version\": \"1\"\n})\n\n# Access apps collection\napps = client.apps\n\n# Get all applications\nall_apps = await apps.get()\n\n# Get specific application\napp = await apps.get(id=\"app-id\")\n\n# Create new application\nnew_app = await apps.create({\n \"name\": \"My App\",\n \"short_description\": \"Description\"\n})\n```\n\n### Organizations\n\n```python\nfrom mosaia import MosaiaClient\n\n# Initialize the client first\nclient = MosaiaClient({\n \"api_key\": \"your-api-key\",\n \"api_url\": \"https://api.mosaia.ai\",\n \"version\": \"1\"\n})\n\n# Access organizations collection\norgs = client.organizations\n\n# Get all organizations\nall_orgs = await orgs.get()\n\n# Get specific organization\norg = await orgs.get(id=\"org-id\")\n\n# Create new organization\nnew_org = await orgs.create({\n \"name\": \"My Organization\",\n \"short_description\": \"Description\"\n})\n```\n\n## Models\n\n### User Model\n\n```python\nfrom mosaia.models import User\n\n# Create user instance\nuser = User({\n \"email\": \"john@example.com\",\n \"name\": \"John Doe\",\n \"username\": \"johndoe\"\n})\n\n# Access properties\nprint(user.email) # john@example.com\nprint(user.name) # John Doe\n\n# Update user\nuser.update({\"name\": \"John Smith\"})\nawait user.save()\n\n# Convert to JSON\nuser_data = user.to_json()\n```\n\n### Session Model\n\n```python\nfrom mosaia import MosaiaClient\n\nclient = MosaiaClient({\"api_key\": \"your-api-key\"})\n\n# Get current session\nsession = await client.session()\n\n# Access user and organization\nif session.user:\n print(f\"User: {session.user.email}\")\n\nif session.org:\n print(f\"Organization: {session.org.name}\")\n\n# Check permissions\nif session.has_permission(\"read\", \"users\"):\n print(\"User can read users\")\n```\n\n## Configuration\n\n### Configuration Manager\n\n```python\nfrom mosaia import ConfigurationManager\n\n# Get singleton instance\nconfig_manager = ConfigurationManager.get_instance()\n\n# Initialize with configuration\nconfig_manager.initialize({\n \"api_key\": \"your-api-key\",\n \"api_url\": \"https://api.mosaia.ai\",\n \"version\": \"1\",\n \"client_id\": \"your-client-id\",\n \"client_secret\": \"your-client-secret\",\n \"verbose\": True\n})\n\n# Access configuration\nconfig = config_manager.get_config()\nprint(config.api_key) # your-api-key\n```\n\n### Environment Variables\n\nYou can also use environment variables for configuration:\n\n```bash\nexport MOSAIA_API_KEY=\"your-api-key\"\nexport MOSAIA_API_URL=\"https://api.mosaia.ai\"\nexport MOSAIA_CLIENT_ID=\"your-client-id\"\nexport MOSAIA_CLIENT_SECRET=\"your-client-secret\"\n```\n\n## Error Handling\n\n```python\nfrom mosaia import MosaiaClient\n\nclient = MosaiaClient({\"api_key\": \"your-api-key\"})\n\ntry:\n users = await client.users.get()\nexcept Exception as e:\n print(f\"Error: {e}\")\n # Handle error appropriately\n```\n\n## Utilities\n\n```python\nfrom mosaia.utils import (\n is_valid_object_id,\n parse_error,\n query_generator,\n is_timestamp_expired\n)\n\n# Validate ObjectId\nis_valid = is_valid_object_id(\"507f1f77bcf86cd799439011\")\n\n# Parse error\nerror_info = parse_error(exception)\n\n# Generate query string\nquery_string = query_generator({\n \"limit\": 10,\n \"offset\": 0,\n \"search\": \"john\"\n})\n\n# Check if timestamp is expired\nis_expired = is_timestamp_expired(\"2024-01-01T00:00:00Z\")\n```\n\n## Development\n\n### Installation for Development\n\n```bash\ngit clone https://github.com/mosaia-development/mosaia-python-sdk.git\ncd mosaia-python-sdk\npip install -e .[dev]\n```\n\n### Running Tests\n\nThe SDK includes comprehensive test coverage with 20+ test cases:\n\n```bash\n# Run all tests\npytest\n\n# Run specific test categories\npytest tests/unit/test_api_client.py -v # API client tests\npytest tests/unit/test_basic.py -v # Basic functionality tests\n\n# Run tests with coverage\npytest --cov=mosaia tests/\n```\n\n#### Test Coverage\n\nThe test suite covers:\n\n- \u2705 **Basic APIClient Functionality** (6 tests)\n - Client creation with configuration\n - Header construction (Authorization, Content-Type)\n - Base URL construction with version injection\n - Base URL with different versions\n - Base URL with default version\n - Base URL with custom API URL\n\n- \u2705 **URL Construction** (3 tests)\n - URL construction with leading slash removal\n - URL construction with query parameters\n - URL construction with different API versions\n\n- \u2705 **Request Methods** (4 tests)\n - GET, POST, PUT, DELETE request methods\n\n- \u2705 **Error Handling** (2 tests)\n - Error response creation\n - Error handling with custom status codes\n\n### Code Quality\n\nThe project includes comprehensive code quality tools:\n\n```bash\n# Run linting\nflake8 mosaia/ tests/\n\n# Run code formatting\nblack mosaia/ tests/\nisort mosaia/ tests/\n\n# Run type checking\nmypy mosaia/\n```\n\n## Building and Deployment\n\n### Local Build\n\n```bash\n# Clean previous builds\nmake clean\n\n# Build package\nmake build\n\n# Test the built package\npip install dist/mosaia-0.0.1-py3-none-any.whl\n```\n\n### Automated Deployment\n\nThe project uses GitHub Actions for automated CI/CD:\n\n- **Testing**: Runs on Python 3.8-3.12\n- **Quality Checks**: Linting, formatting, and type checking\n- **Build**: Automated package building\n- **Deployment**: Automatic PyPI deployment on releases\n\n## Documentation\n\nFor detailed documentation, visit [https://docs.mosaia.ai/python-sdk](https://docs.mosaia.ai/python-sdk)\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- Documentation: [https://docs.mosaia.ai/python-sdk](https://docs.mosaia.ai/python-sdk)\n- Issues: [https://github.com/mosaia-development/mosaia-python-sdk/issues](https://github.com/mosaia-development/mosaia-python-sdk/issues)\n- Email: support@mosaia.ai \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive Python SDK for the Mosaia AI platform",
"version": "0.0.4",
"project_urls": {
"Bug Tracker": "https://github.com/mosaia-development/mosaia-python-sdk/issues",
"Documentation": "https://docs.mosaia.ai/python-sdk",
"Homepage": "https://github.com/mosaia-development/mosaia-python-sdk",
"Repository": "https://github.com/mosaia-development/mosaia-python-sdk"
},
"split_keywords": [
"ai",
" artificial intelligence",
" api",
" sdk",
" mosaia",
" agents",
" tools",
" applications"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "64cd486edb610fefa9808ef58ff3fa3566b4075d3cc720e8ab424d0e81117956",
"md5": "b945c32e840001511cb11824a7591f5f",
"sha256": "63f7279a73bb82365ea0a979c5fce55c0072d7b9d38a0cf6f66ddf45d40b7ef6"
},
"downloads": -1,
"filename": "mosaia-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b945c32e840001511cb11824a7591f5f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 88121,
"upload_time": "2025-08-11T17:13:28",
"upload_time_iso_8601": "2025-08-11T17:13:28.782981Z",
"url": "https://files.pythonhosted.org/packages/64/cd/486edb610fefa9808ef58ff3fa3566b4075d3cc720e8ab424d0e81117956/mosaia-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "15b129558c0f0be6322f4bb988ca4dcff526842349edd8af9e72615f1216adf8",
"md5": "321eb59a23dd9f2802f2a77ea37eec46",
"sha256": "5280c744fcd0950ec1d0e906bcdf86e5816a20a27c98110d7ee28c49e85703b7"
},
"downloads": -1,
"filename": "mosaia-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "321eb59a23dd9f2802f2a77ea37eec46",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 93860,
"upload_time": "2025-08-11T17:13:29",
"upload_time_iso_8601": "2025-08-11T17:13:29.881289Z",
"url": "https://files.pythonhosted.org/packages/15/b1/29558c0f0be6322f4bb988ca4dcff526842349edd8af9e72615f1216adf8/mosaia-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 17:13:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mosaia-development",
"github_project": "mosaia-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.0"
]
]
},
{
"name": "dataclasses-json",
"specs": [
[
">=",
"0.5.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"0.19.0"
]
]
}
],
"lcname": "mosaia"
}
JSON
