Model Classes
Rich model classes provide convenient methods for working with API resources.
File Models
Synchronous File Model
- class moderatelyai_sdk.models.FileModel(data, client)[source]
Bases:
BaseModelModel representing a file with rich file operations.
FileModel provides a high-level interface for working with files in the Moderately AI platform. Instead of working with raw dictionaries, you get a rich object with methods for common file operations.
This class is returned by file operations like: - client.files.upload() - client.files.retrieve() - client.files.list() (returns list of FileModel instances)
- file_id
Unique identifier for the file
- name
Display name of the file
- original_name
Original filename when uploaded
- mime_type
MIME type (e.g., “text/csv”, “application/pdf”)
- file_size
Size in bytes
- file_hash
SHA256 hash of file content
- team_id
Team that owns this file
- dataset_id
Associated dataset ID (if any)
- status
Upload/processing status
- metadata
Additional file metadata
- created_at
Creation timestamp
- updated_at
Last update timestamp
Example
```python # Get a file and check its properties file = client.files.retrieve(“file_123”)
- if file.is_csv() and file.is_ready():
print(f”Ready CSV file: {file.name} ({file.file_size} bytes)”)
# Download to memory content = file.download()
# Or download to disk file.download(path=”./data.csv”)
- download(*, path=None)[source]
Download the file content.
Downloads the file content either to memory or to a local file. This method handles the presigned URL workflow automatically and creates parent directories as needed when saving to disk.
- Parameters:
path (
Union[str,Path,None]) – Optional path to save the file. If provided, saves to this location and creates parent directories if they don’t exist. If not provided, returns the file content as bytes.- Returns:
None (file is saved to disk) If path is not provided: The file content as bytes
- Return type:
If path is provided
- Raises:
Example
```python # Download to memory content = file.download() print(f”Downloaded {len(content)} bytes”)
# Download to disk file.download(path=”./downloads/myfile.pdf”)
# Download with automatic directory creation file.download(path=”./new_folder/subfolder/file.csv”) ```
- delete()[source]
Delete this file permanently.
This operation cannot be undone. The file will be removed from both the database and cloud storage.
- Raises:
APIError – If the deletion fails
NotFoundError – If the file doesn’t exist
- Return type:
Example
`python # Delete a file file.delete() # File is now permanently deleted `
- is_ready()[source]
Check if the file is ready for use (processing complete).
Files may need processing after upload. Use this method to check if a file is ready for operations like downloading or analysis.
- Return type:
- Returns:
True if the file status is ‘ready’ or ‘completed’, False otherwise.
Example
content = file.download() print(“File is ready and downloaded!”)
- else:
print(“File is still processing…”)
- is_processing()[source]
Check if the file is currently being processed.
- Return type:
- Returns:
True if the file status is ‘processing’, False otherwise.
Example
```python if file.is_processing():
print(“Please wait, file is being processed…”)
- has_error()[source]
Check if the file has an error status.
- Return type:
- Returns:
True if the file status is ‘error’, False otherwise.
Example
```python if file.has_error():
print(f”File {file.name} failed to process”) # Handle error case
- get_extension()[source]
Get the file extension from the filename.
- Return type:
- Returns:
The file extension (including the dot), or empty string if none.
Example
```python ext = file.get_extension() if ext == ‘.pdf’:
print(“This is a PDF file”)
- is_image()[source]
Check if this file is an image based on MIME type.
Detects common image formats like JPEG, PNG, GIF, SVG, etc.
- Return type:
- Returns:
True if the MIME type indicates an image.
Example
print(f”Image file: {file.name} ({file.mime_type})”) # Handle image-specific logic
- is_document()[source]
Check if this file is a document (PDF, Word, etc.).
Detects common document formats including: - PDF files - Microsoft Word documents (.doc, .docx) - Microsoft Excel spreadsheets (.xls, .xlsx) - Microsoft PowerPoint presentations (.ppt, .pptx)
- Return type:
- Returns:
True if the MIME type indicates a document.
Example
```python if file.is_document():
print(f”Document: {file.name}”) # Process document
- is_text()[source]
Check if this file is a text file.
Detects all text-based files including plain text, CSV, JSON, XML, etc.
- Return type:
- Returns:
True if the MIME type indicates a text file.
Example
content = file.download().decode(‘utf-8’) print(f”Text content: {content[:100]}…”)
- is_csv()[source]
Check if this file is a CSV file.
Specifically detects CSV (Comma-Separated Values) files, which are commonly used for tabular data.
- Return type:
- Returns:
True if the MIME type indicates a CSV file.
Example
print(f”CSV file with {file.file_size} bytes of data”) # Process as structured data
Asynchronous File Model
- class moderatelyai_sdk.models.FileAsyncModel(data, client)[source]
Bases:
BaseAsyncModelAsync model representing a file with rich file operations.
FileAsyncModel provides a high-level async interface for working with files in the Moderately AI platform. Instead of working with raw dictionaries, you get a rich object with async methods for common file operations.
This class is returned by async file operations like: - await client.files.upload() - await client.files.retrieve() - await client.files.list() (returns list of FileAsyncModel instances)
- file_id
Unique identifier for the file
- name
Display name of the file
- original_name
Original filename when uploaded
- mime_type
MIME type (e.g., “text/csv”, “application/pdf”)
- file_size
Size in bytes
- file_hash
SHA256 hash of file content
- team_id
Team that owns this file
- dataset_id
Associated dataset ID (if any)
- status
Upload/processing status
- metadata
Additional file metadata
- created_at
Creation timestamp
- updated_at
Last update timestamp
Example
```python # Get a file and check its properties file = await client.files.retrieve(“file_123”)
- if file.is_csv() and file.is_ready():
print(f”Ready CSV file: {file.name} ({file.file_size} bytes)”)
# Download to memory content = await file.download()
# Or download to disk await file.download(path=”./data.csv”)
- async download(*, path=None)[source]
Download the file content (async).
Downloads the file content either to memory or to a local file. This method handles the presigned URL workflow automatically and creates parent directories as needed when saving to disk.
- Parameters:
path (
Union[str,Path,None]) – Optional path to save the file. If provided, saves to this location and creates parent directories if they don’t exist. If not provided, returns the file content as bytes.- Returns:
None (file is saved to disk) If path is not provided: The file content as bytes
- Return type:
If path is provided
- Raises:
Example
```python # Download to memory content = await file.download() print(f”Downloaded {len(content)} bytes”)
# Download to disk await file.download(path=”./downloads/myfile.pdf”)
# Download with automatic directory creation await file.download(path=”./new_folder/subfolder/file.csv”) ```
- async delete()[source]
Delete this file permanently (async).
This operation cannot be undone. The file will be removed from both the database and cloud storage.
- Raises:
APIError – If the deletion fails
NotFoundError – If the file doesn’t exist
- Return type:
Example
`python # Delete a file await file.delete() # File is now permanently deleted `
- is_ready()[source]
Check if the file is ready for use (processing complete).
Files may need processing after upload. Use this method to check if a file is ready for operations like downloading or analysis.
- Return type:
- Returns:
True if the file status is ‘ready’ or ‘completed’, False otherwise.
Example
content = await file.download() print(“File is ready and downloaded!”)
- else:
print(“File is still processing…”)
- is_processing()[source]
Check if the file is currently being processed.
- Return type:
- Returns:
True if the file status is ‘processing’, False otherwise.
Example
```python if file.is_processing():
print(“Please wait, file is being processed…”)
- has_error()[source]
Check if the file has an error status.
- Return type:
- Returns:
True if the file status is ‘error’, False otherwise.
Example
```python if file.has_error():
print(f”File {file.name} failed to process”) # Handle error case
- get_extension()[source]
Get the file extension from the filename.
- Return type:
- Returns:
The file extension (including the dot), or empty string if none.
Example
```python ext = file.get_extension() if ext == ‘.pdf’:
print(“This is a PDF file”)
- is_image()[source]
Check if this file is an image based on MIME type.
Detects common image formats like JPEG, PNG, GIF, SVG, etc.
- Return type:
- Returns:
True if the MIME type indicates an image.
Example
print(f”Image file: {file.name} ({file.mime_type})”) # Handle image-specific logic
- is_document()[source]
Check if this file is a document (PDF, Word, etc.).
Detects common document formats including: - PDF files - Microsoft Word documents (.doc, .docx) - Microsoft Excel spreadsheets (.xls, .xlsx) - Microsoft PowerPoint presentations (.ppt, .pptx)
- Return type:
- Returns:
True if the MIME type indicates a document.
Example
```python if file.is_document():
print(f”Document: {file.name}”) # Process document
- is_text()[source]
Check if this file is a text file.
Detects all text-based files including plain text, CSV, JSON, XML, etc.
- Return type:
- Returns:
True if the MIME type indicates a text file.
Example
content = await file.download() text_content = content.decode(‘utf-8’) print(f”Text content: {text_content[:100]}…”)
- is_csv()[source]
Check if this file is a CSV file.
Specifically detects CSV (Comma-Separated Values) files, which are commonly used for tabular data.
- Return type:
- Returns:
True if the MIME type indicates a CSV file.
Example
print(f”CSV file with {file.file_size} bytes of data”) # Process as structured data
User Models
Synchronous User Model
- class moderatelyai_sdk.models.UserModel(data, client)[source]
Bases:
BaseModelModel representing a user with rich functionality.
UserModel provides a high-level interface for working with users in the Moderately AI platform. Instead of working with raw dictionaries, you get a rich object with methods for common user operations.
This class is returned by user operations like: - client.users.retrieve() - client.users.update()
Note: User creation and deletion are not supported by the API.
- user_id
Unique identifier for the user
- full_name
User’s full name
- nickname
User’s nickname (optional)
- created_at
Creation timestamp
- updated_at
Last update timestamp
Example
```python # Get a user and check properties user = client.users.retrieve(“user_123”)
print(f”User: {user.display_name()} ({user.full_name})”) print(f”Member since: {user.formatted_created_at()}”)
# Update user profile if not user.has_nickname():
user.update_profile(nickname=”Cool Nickname”)
# Check if user is recently created if user.is_recent(days=30):
print(“Welcome new user!”)
- display_name()[source]
Get the user’s display name, using nickname or full name.
- Return type:
- Returns:
The user’s nickname if available, otherwise their full name.
Example
`python print(f"Welcome, {user.display_name()}!") `
- has_nickname()[source]
Check if the user has a nickname set.
- Return type:
- Returns:
True if the user has a nickname, False if only full name is available.
Example
```python if not user.has_nickname():
user.update_profile(nickname=”Cool Nickname”)
- formatted_created_at(format_str='%Y-%m-%d %H:%M:%S')[source]
Get a formatted version of the creation timestamp.
- Parameters:
format_str (
str) – Python datetime format string. Defaults to “%Y-%m-%d %H:%M:%S”.- Return type:
- Returns:
Formatted creation timestamp.
Example
```python # Default format print(f”Created: {user.formatted_created_at()}”)
# Custom format print(f”Joined: {user.formatted_created_at(‘%B %d, %Y’)}”) ```
- is_recent(days=7)[source]
Check if the user was created recently.
- Parameters:
days (
int) – Number of days to consider as “recent”. Defaults to 7.- Return type:
- Returns:
True if the user was created within the specified number of days.
Example
```python # Check if user joined in the last week if user.is_recent():
send_welcome_email(user)
# Check if user joined in the last month if user.is_recent(days=30):
show_onboarding_tips(user)
- update_profile(*, full_name=None, nickname=None, **kwargs)[source]
Update this user’s profile information.
- Parameters:
- Return type:
- Returns:
Updated user model.
Example
```python # Update user’s full name user = user.update_profile(full_name=”John Smith”)
# Update nickname user = user.update_profile(nickname=”Johnny”)
# Update multiple properties user = user.update_profile(
full_name=”Jane Doe”, nickname=”Janie”
)
Asynchronous User Model
- class moderatelyai_sdk.models.UserAsyncModel(data, client)[source]
Bases:
BaseAsyncModelAsync model representing a user with rich functionality.
UserAsyncModel provides a high-level async interface for working with users in the Moderately AI platform. Instead of working with raw dictionaries, you get a rich object with async methods for common user operations.
This class is returned by async user operations like: - await client.users.retrieve() - await client.users.update()
Note: User creation and deletion are not supported by the API.
- user_id
Unique identifier for the user
- full_name
User’s full name
- nickname
User’s nickname (optional)
- created_at
Creation timestamp
- updated_at
Last update timestamp
Example
```python # Get a user and check properties user = await client.users.retrieve(“user_123”)
print(f”User: {user.display_name()} ({user.full_name})”) print(f”Member since: {user.formatted_created_at()}”)
# Update user profile if not user.has_nickname():
await user.update_profile(nickname=”Cool Nickname”)
# Check if user is recently created if user.is_recent(days=30):
print(“Welcome new user!”)
- display_name()[source]
Get the user’s display name, using nickname or full name.
- Return type:
- Returns:
The user’s nickname if available, otherwise their full name.
Example
`python print(f"Welcome, {user.display_name()}!") `
- has_nickname()[source]
Check if the user has a nickname set.
- Return type:
- Returns:
True if the user has a nickname, False if only full name is available.
Example
```python if not user.has_nickname():
await user.update_profile(nickname=”Cool Nickname”)
- formatted_created_at(format_str='%Y-%m-%d %H:%M:%S')[source]
Get a formatted version of the creation timestamp.
- Parameters:
format_str (
str) – Python datetime format string. Defaults to “%Y-%m-%d %H:%M:%S”.- Return type:
- Returns:
Formatted creation timestamp.
Example
```python # Default format print(f”Created: {user.formatted_created_at()}”)
# Custom format print(f”Joined: {user.formatted_created_at(‘%B %d, %Y’)}”) ```
- is_recent(days=7)[source]
Check if the user was created recently.
- Parameters:
days (
int) – Number of days to consider as “recent”. Defaults to 7.- Return type:
- Returns:
True if the user was created within the specified number of days.
Example
```python # Check if user joined in the last week if user.is_recent():
await send_welcome_email(user)
# Check if user joined in the last month if user.is_recent(days=30):
await show_onboarding_tips(user)
- async update_profile(*, full_name=None, nickname=None, **kwargs)[source]
Update this user’s profile information (async).
- Parameters:
- Return type:
- Returns:
Updated user model.
Example
```python # Update user’s full name user = await user.update_profile(full_name=”John Smith”)
# Update nickname user = await user.update_profile(nickname=”Johnny”)
# Update multiple properties user = await user.update_profile(
full_name=”Jane Doe”, nickname=”Janie”
)
Dataset Models
Synchronous Dataset Model
- class moderatelyai_sdk.models.DatasetModel(data, client)[source]
Bases:
BaseModelModel representing a dataset with rich data operations.
DatasetModel provides a high-level interface for working with datasets in the Moderately AI platform. It offers rich functionality for data upload, schema management, and version control.
Key Features: - Upload data in various formats (CSV, Excel) - Automatic schema inference from sample data - Schema builder with fluent API - Data version management and downloads - Rich metadata access
This class is returned by dataset operations like: - client.datasets.create() - client.datasets.retrieve() - client.datasets.list() (returns list of DatasetModel instances)
- dataset_id
Unique identifier for the dataset
- name
Dataset display name
- description
Optional dataset description
- team_id
Team that owns this dataset
- record_count
Number of records in current data version
- total_size_bytes
Total size of dataset data
- current_schema_version_id
ID of current schema version
- current_data_version_id
ID of current data version
- processing_status
Data processing status
- created_at
Creation timestamp
- updated_at
Last update timestamp
Example
```python # Create a dataset dataset = client.datasets.create(
name=”Customer Data”, description=”Customer information and metrics”
)
# Upload data with automatic schema inference data_version = dataset.upload_data(“customers.csv”) schema = dataset.create_schema_from_sample(“customers.csv”)
# Use schema builder for complex schemas schema = (dataset.schema_builder()
.add_column(“id”, “int”, required=True) .add_column(“name”, “string”) .add_column(“signup_date”, “datetime”) .as_current() .create())
# Access dataset information print(f”Dataset: {dataset.name} ({dataset.record_count} records)”)
# Download current data content = dataset.download_data() ```
- property processing_status: str | None
completed, failed, in_progress, needs-processing.
- Type:
Processing status
- upload_data(file, *, file_type=None, status='current', **kwargs)[source]
Upload data to this dataset, creating a new data version.
- Parameters:
file (
Union[str,Path,bytes,Any]) – The file to upload - can be a path, bytes, or file-like objectfile_type (
Optional[str]) – File type (‘csv’ or ‘xlsx’). Auto-detected if not provided.status (
str) – Version status (‘draft’ or ‘current’). Defaults to ‘current’.**kwargs (
Any) – Additional upload options.
- Return type:
- Returns:
The created data version model.
- Raises:
ValueError – If file is invalid or not found.
APIError – If upload process fails.
- download_data(*, version_id=None, path=None)[source]
Download data from this dataset.
- Parameters:
- Returns:
None (file is saved to disk) If path is not provided: The file content as bytes
- Return type:
If path is provided
- Raises:
ValueError – If no data version exists.
APIError – If download fails.
- list_data_versions(*, page=1, page_size=10, status=None)[source]
List data versions for this dataset.
- get_data_version(version_id)[source]
Get a specific data version by ID.
- Parameters:
version_id (
str) – The data version ID to retrieve.- Return type:
- Returns:
The data version model.
- create_schema(columns, *, status='draft', parsing_options=None)[source]
Create a schema version with simple column definitions.
- Parameters:
columns (
List[Dict[str,Any]]) – List of column definitions. Each dict should have: - name: Column name (required) - type: Column type (required) - ‘string’, ‘int’, ‘float’, ‘datetime’, ‘bool’ - required: Whether column is required (optional, defaults to True) - description: Column description (optional)status (
str) – Initial status (‘draft’ or ‘current’). Defaults to ‘draft’.parsing_options (
Optional[Dict[str,Any]]) – Optional parsing configuration.
- Return type:
- Returns:
The created schema version model.
Example
```python schema = dataset.create_schema([
{“name”: “user_id”, “type”: “int”, “required”: True}, {“name”: “email”, “type”: “string”, “description”: “User email address”}, {“name”: “signup_date”, “type”: “datetime”},
])
- create_schema_from_sample(sample_file, *, status='draft', header_row=1, sample_size=100)[source]
Create a schema by analyzing a sample data file.
- Parameters:
sample_file (
Union[str,Path,bytes]) – Sample data to analyze. Can be: - str/Path: Path to CSV file - bytes: Raw CSV data as bytesstatus (
str) – Initial status (‘draft’ or ‘current’). Defaults to ‘draft’.header_row (
int) – Row containing column headers (1-based). Defaults to 1.sample_size (
int) – Number of rows to sample for type inference. Defaults to 100.
- Return type:
- Returns:
The created schema version model.
- Raises:
ValueError – If file format is not supported or file is invalid.
- schema_builder()[source]
Get a schema builder for creating complex schemas with fluent API.
- Return type:
- Returns:
Schema builder instance for this dataset.
Example
```python schema = (dataset.schema_builder()
.add_column(“id”, “int”, required=True) .add_column(“name”, “string”) .with_parsing(delimiter=”,”, header_row=1) .as_current() .create())
- list_schema_versions(*, status=None, page=1, page_size=10)[source]
List schema versions for this dataset.
- get_current_schema()[source]
Get the current (active) schema version for this dataset.
- Return type:
- Returns:
The current schema version model, or None if no current schema exists.
- class moderatelyai_sdk.models.DatasetDataVersionModel(data, client)[source]
Bases:
BaseModelModel representing a dataset data version.
A data version represents a specific upload of data to a dataset. Each time you upload new data to a dataset, a new data version is created. This model provides access to version metadata and download functionality.
- dataset_data_version_id
Unique identifier for this data version
- dataset_id
ID of the parent dataset
- version_no
Version number (incremental)
- file_type
Type of uploaded file (csv, xlsx)
- file_hash
SHA256 hash of the uploaded file
- row_count
Number of data rows
- file_size_bytes
Size of the uploaded file
- status
Processing status (draft, current, archived)
- created_at
Creation timestamp
- updated_at
Last update timestamp
Example
```python # Get the current data version data_version = dataset.get_data_version(“version_id”)
print(f”Version {data_version.version_no}: {data_version.file_type}”) print(f”Rows: {data_version.row_count}, Size: {data_version.file_size_bytes}”)
# Download the data content = data_version.download() data_version.download(path=”./local_data.csv”) ```
- class moderatelyai_sdk.models.DatasetSchemaVersionModel(data, client)[source]
Bases:
BaseModelModel representing a dataset schema version with rich functionality.
A schema version defines the structure and data types for a dataset’s columns. This model provides methods for managing schema versions, including activation, column manipulation, and updates.
Key Features: - Activate/archive schema versions - Add/remove columns dynamically - Update schema properties - Rich column access and validation
- dataset_schema_version_id
Unique identifier for this schema version
- dataset_id
ID of the parent dataset
- version_no
Version number (incremental)
- columns
List of column definitions
- status
Schema status (draft, current, archived)
- parsing_options
Data parsing configuration
- created_at
Creation timestamp
- updated_at
Last update timestamp
Example
```python # Get current schema schema = dataset.get_current_schema()
# Add a new column schema.add_column(“new_field”, “string”, required=False)
# Activate the schema schema.activate()
# Access column information user_id_col = schema.get_column(“user_id”) print(f”Column: {user_id_col[‘name’]} ({user_id_col[‘type’]})”) ```
- activate()[source]
Make this schema version the current/active one.
- Return type:
- Returns:
Updated schema version model.
- update(*, status=None, columns=None, parsing_options=None)[source]
Update this schema version.
- Parameters:
- Return type:
- Returns:
Updated schema version model.
- add_column(name, column_type, *, required=True, description=None, position=None, **kwargs)[source]
Add a new column to this schema version.
- Parameters:
name (
str) – Column name.column_type (
str) – Column type (‘string’, ‘integer’, ‘float’, ‘datetime’, ‘boolean’).required (
bool) – Whether the column is required (not nullable).position (
Optional[int]) – Position in the schema (1-based). If None, adds to end.**kwargs (
Any) – Additional column properties.
- Return type:
- Returns:
Updated schema version model.
- remove_column(name)[source]
Remove a column from this schema version.
- Parameters:
name (
str) – Name of the column to remove.- Return type:
- Returns:
Updated schema version model.
- Raises:
ValueError – If column doesn’t exist.
- class moderatelyai_sdk.models.SchemaBuilder(dataset_id, client)[source]
Bases:
objectFluent API builder for creating dataset schema versions.
SchemaBuilder provides a chainable interface for constructing complex dataset schemas with parsing options and validation. It offers the most advanced level of schema creation with full control over column properties and data processing.
The builder pattern allows you to: - Add columns with detailed specifications - Configure parsing options (delimiters, headers, encoding) - Set schema status (draft/current) - Create the final schema version
Example
```python # Build a comprehensive schema schema = (dataset.schema_builder()
.add_column(“id”, “int”, required=True, description=”Primary key”) .add_column(“email”, “string”, required=True) .add_column(“signup_date”, “datetime”, required=False) .add_column(“is_active”, “bool”, required=True) .with_parsing(
delimiter=”,”, header_row=1, encoding=”utf-8”
) .as_current() # Mark as active schema .create()) # Execute the creation
print(f”Created schema version {schema.version_no}”) ```
- Parameters:
dataset_id (
str)
- __init__(dataset_id, client)[source]
Initialize schema builder.
- Parameters:
dataset_id (
str) – The dataset to create schema for.client – The API client instance.
- add_column(name, column_type, *, required=True, description=None, operations=None, **kwargs)[source]
Add a column to the schema being built.
- Parameters:
name (
str) – Column name.column_type (
str) – Column type (‘string’, ‘integer’, ‘float’, ‘datetime’, ‘boolean’).required (
bool) – Whether the column is required (not nullable).operations (
Optional[List[Dict[str,Any]]]) – List of column operations (advanced).**kwargs (
Any) – Additional column properties.
- Return type:
- Returns:
This builder for method chaining.
- with_parsing(*, skip_rows=None, header_row=None, delimiter=None, encoding=None)[source]
Set parsing options for the schema.
- Parameters:
- Return type:
- Returns:
This builder for method chaining.
- as_draft()[source]
Set the schema status to draft.
- Return type:
- Returns:
This builder for method chaining.
- as_current()[source]
Set the schema status to current (active).
- Return type:
- Returns:
This builder for method chaining.
- create()[source]
Create the schema version with the configured settings.
- Return type:
- Returns:
The created schema version model.
- Raises:
ValueError – If no columns have been added.
APIError – If creation fails.