API Reference¶
Core Modules¶
Main Application¶
MailOS Web Application Module.
This module provides a web interface for managing email monitoring configurations using PyWebIO.
- class mailos.app.CheckerConfig(id: str, name: str, monitor_email: str, password: str, imap_server: str, imap_port: int, llm_provider: str, model: str, system_prompt: str, enabled_tools: List[str], enabled: bool, auto_reply: bool, last_run: str = 'Never')[source]¶
Bases:
object
Email checker configuration.
- classmethod from_form(checker_id: str | None = None) CheckerConfig [source]¶
Create CheckerConfig from form data.
- mailos.app.update_vendor_credentials(checker_dict: Dict, vendor_config) None [source]¶
Update vendor-specific credentials in checker dictionary.
Email Processing¶
Email checking functions.
- mailos.check_emails.check_emails(checker_config)[source]¶
Check emails for a given checker configuration.
Email reply handling and processing module.
This module contains functions for handling email replies, including: - Creating prompts for LLM responses - Processing email attachments - Sending automated replies using configured LLM providers
- class mailos.reply.EmailData(sender: str, subject: str, body: str = '', msg_date: str = '', message_id: str = '', attachments: List[Dict[str, Any]] = None)[source]¶
Bases:
object
Structure for validated email data.
- mailos.reply.create_email_prompt(email_data: EmailData, available_tools: List[Any], has_images: bool = False) str [source]¶
Create a prompt for the LLM based on the email data.
- Parameters:
email_data – Structured email data
available_tools – List of available tools for the LLM
has_images – Whether the email contains image attachments
- Returns:
Formatted prompt string for the LLM
- mailos.reply.process_attachments(attachments: List[Dict[str, Any]]) List[Content] [source]¶
Process email attachments and convert images to Content objects.
- Parameters:
attachments – List of attachment dictionaries
- Returns:
List of Content objects for valid images
- mailos.reply.handle_email_reply(checker_config: Dict[str, Any], email_data: Dict[str, Any]) bool [source]¶
Handle the email reply process using the configured LLM.
- Parameters:
checker_config – Configuration for the email checker
email_data – Dictionary containing email information
- Returns:
True if reply was sent successfully, False otherwise
- Return type:
User Interface¶
UI functions for creating and editing checker forms.
- mailos.ui.checker_form.create_checker_form(checker_id=None, on_save=None)[source]¶
Create a form for new checker or editing existing one.
- Parameters:
checker_id – The ID of the checker to edit, or None for new checker
on_save – Callback function to save the checker
UI functions for displaying the checker list.
- mailos.ui.checker_list.display_checker_controls(on_control, on_filter=None)[source]¶
Display the top control buttons.
- mailos.ui.checker_list.display_checker(checker, action_callback, status_filter=None)[source]¶
Display a single checker with its controls.
UI display functions.
LLM Integration¶
MailOS LLM Factory Module.
This module provides a factory pattern implementation for creating Language Learning Model (LLM) instancesfrom different providers. It supports multiple LLM providers and handles their specific initialization requirements.
- Supported Providers:
OpenAI
Anthropic
Bedrock Anthropic (AWS)
Example
- llm = LLMFactory.create(
provider=’openai’, model=’gpt-4’, api_key=’your-api-key’
)
# For AWS Bedrock: llm = LLMFactory.create(
provider=’bedrock-anthropic’, model=’claude-v2’, aws_access_key=’key’, aws_secret_key=’secret’, aws_region=’us-east-1’
)
- class mailos.vendors.factory.LLMFactory[source]¶
Bases:
object
Factory for creating LLM instances.
- classmethod create(provider: str, model: str, **kwargs)[source]¶
Create an LLM instance.
- Parameters:
provider – The name of the provider (e.g., ‘openai’, ‘anthropic’,
'bedrock-anthropic')
model – The model name to use
**kwargs – Additional arguments passed to the provider constructor (e.g., api_key, aws_access_key, aws_secret_key, etc.)
Data models for vendor integrations and LLM interactions.
- class mailos.vendors.models.RoleType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶
-
Enumeration of possible message role types.
- SYSTEM = 'system'¶
- USER = 'user'¶
- ASSISTANT = 'assistant'¶
- FUNCTION = 'function'¶
- class mailos.vendors.models.ContentType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶
-
Enumeration of supported content types.
- TEXT = 'text'¶
- IMAGE = 'image'¶
- AUDIO = 'audio'¶
- FILE = 'file'¶
- EMBEDDING = 'embedding'¶
- class mailos.vendors.models.Content(type: ContentType, data: Any, mime_type: str | None = None)[source]¶
Bases:
object
Represents content in a message with type and value.
- type: ContentType¶
- class mailos.vendors.models.Message(role: RoleType, content: List[Content], name: str | None = None, function_call: Dict | None = None, timestamp: datetime = datetime.datetime(2024, 12, 11, 21, 17, 0, 730718))[source]¶
Bases:
object
Represents a message in a conversation with role and content.
- class mailos.vendors.models.Tool(name: str, description: str, parameters: Dict, function: Callable, required_params: List[str] = None)[source]¶
Bases:
object
Represents a tool or function that can be called by the LLM.
- class mailos.vendors.models.ModelConfig(temperature: float = 0.7, max_tokens: int | None = None, top_p: float = 1.0, frequency_penalty: float = 0.0, presence_penalty: float = 0.0, stop_sequences: List[str] | None = None)[source]¶
Bases:
object
Configuration settings for LLM model behavior and parameters.
- class mailos.vendors.models.LLMResponse(content: List[Content], role: RoleType = RoleType.ASSISTANT, finish_reason: str | None = None, tool_calls: List[Dict] | None = None, usage: Dict[str, int] | None = None, model: str | None = None, system_fingerprint: str | None = None, created_at: datetime = datetime.datetime(2024, 12, 11, 21, 17, 0, 731484))[source]¶
Bases:
object
Unified response model for all LLM providers.
- __init__(content: List[Content], role: RoleType = RoleType.ASSISTANT, finish_reason: str | None = None, tool_calls: List[Dict] | None = None, usage: Dict[str, int] | None = None, model: str | None = None, system_fingerprint: str | None = None, created_at: datetime = datetime.datetime(2024, 12, 11, 21, 17, 0, 731484)) None ¶
Configuration schemas for LLM vendors.
- class mailos.vendors.config.ConfigField(name: str, label: str, type: str, required: bool = True, default: str | None = None, help_text: str | None = None)[source]¶
Bases:
object
Configuration field definition.
Utilities¶
Configuration utilities for loading and saving email configuration.
- mailos.utils.config_utils.load_config() Dict[str, Any] [source]¶
Load configuration from JSON file.
- Returns:
Dictionary containing configuration settings
- mailos.utils.config_utils.save_config(config: Dict[str, Any]) None [source]¶
Save configuration to JSON file.
- Parameters:
config – Configuration dictionary to save
- mailos.utils.config_utils.update_checker_field(checker_id: str, field: str, value: any) bool [source]¶
Update a single field of a checker by its ID.
- Parameters:
checker_id – The ID of the checker to update
field – The field name to update
value – The new value for the field
- Returns:
True if the update was successful, False otherwise
- Return type:
- mailos.utils.config_utils.update_attachment_settings(settings: Dict[str, Any]) bool [source]¶
Update attachment-related settings.
- Parameters:
settings – Dictionary containing attachment settings to update
- Returns:
True if update was successful, False otherwise
- Return type:
- mailos.utils.config_utils.get_attachment_settings() Dict[str, Any] [source]¶
Get current attachment settings.
- Returns:
Dictionary containing attachment settings
Logging utilities.
Reply utilities for MailOS.
Tool System¶
See Tools API Reference for detailed documentation of the tool system and available tools.
See also
Tool Management Guide for tool development guide
Configuration Guide for tool configuration
Quickstart Guide for getting started with tools