# Aipype-G Framework

## Introduction

The **aipype-g** framework is a powerful tool designed for seamless integration with Google APIs, enabling developers to create complex workflows that interact with services such as Gmail and Google Sheets. At the heart of this framework is the **PipelineAgent**, which orchestrates tasks in a structured manner. Each task is represented as an instance of a class derived from **BaseTask**, allowing for modular and reusable components. The **PipelineAgent** manages the execution of these tasks, ensuring they run in the correct order based on their dependencies, which are defined using the **TaskDependency** class. This orchestration allows developers to build intricate workflows that can handle various tasks, from sending emails to reading data from spreadsheets.

Data sharing between tasks is facilitated through the **TaskContext**, which acts as a shared space for passing information between tasks. This context allows tasks to access the results of previous tasks, enabling a smooth flow of data throughout the pipeline. Additionally, the **TaskResult** pattern is employed for error handling, providing a standardized way to capture and report errors that may occur during task execution. This ensures that developers can easily identify issues and implement appropriate error handling strategies. The framework also supports parallel execution of tasks, allowing for improved performance and efficiency. Tasks can be grouped into phases, enabling developers to define which tasks can run concurrently and which must wait for others to complete, thus optimizing the overall execution time of the pipeline.

In summary, the aipype-g framework provides a robust architecture for building workflows that integrate with Google services. With its focus on task orchestration, data sharing, error handling, and parallel execution, developers can create efficient and maintainable pipelines that leverage the power of Google APIs to automate and enhance their applications.

## Usage Examples

### Google OAuth Task

```python
import os
from aipype_g import GoogleOAuthTask

# Configuration for Google OAuth
config = {
    "service_types": ["gmail", "sheets"],
    "credentials_file": os.getenv("GOOGLE_CREDENTIALS_FILE", "google_credentials.json"),
    "token_file": os.getenv("GMAIL_TOKEN_FILE", "gmail_token.json"),
}

# Create and run the Google OAuth task
oauth_task = GoogleOAuthTask("gmail_auth", config)
credentials, scopes, auth_info, service_access = oauth_task.run()

print("Authenticated with scopes:", scopes)
```

### Gmail List Emails Task

```python
from aipype_g import GmailListEmailsTask

# Configuration for listing emails
config = {
    "query": "newer_than:7d",
    "max_results": 10,
    "include_spam_trash": False,
    "credentials": credentials,  # Use credentials from OAuth task
}

# Create and run the Gmail list emails task
list_emails_task = GmailListEmailsTask("list_recent_emails", config)
messages, message_ids, search_result = list_emails_task.run()

print(f"Found {len(messages)} messages.")
```

### Gmail Read Email Task

```python
from aipype_g import GmailReadEmailTask

# Configuration for reading a specific email
config = {
    "message_id": message_ids[0],  # Use the first message ID from the previous task
    "format": "full",
    "include_attachments": True,
    "credentials": credentials,  # Use credentials from OAuth task
}

# Create and run the Gmail read email task
read_email_task = GmailReadEmailTask("read_email", config)
email_content = read_email_task.run()

print("Email Subject:", email_content.subject)
```

### Read Google Sheet Task

```python
from aipype_g import ReadGoogleSheetTask

# Configuration for reading a Google Sheet
config = {
    "spreadsheet_id": "your_spreadsheet_id",
    "sheet_name": "Sheet1",
    "include_headers": True,
    "credentials": credentials,  # Use credentials from OAuth task
}

# Create and run the read Google Sheet task
read_sheet_task = ReadGoogleSheetTask("read_google_sheet", config)
sheet_data = read_sheet_task.run()

print("Sheet Data:", sheet_data.values)
```

### Complete Pipeline Example

```python
import os
from aipype import PipelineAgent, task
from aipype_g import GoogleOAuthTask, GmailListEmailsTask, GmailReadEmailTask, ReadGoogleSheetTask

class GmailPipelineAgent(PipelineAgent):
    @task
    def authenticate(self) -> dict:
        """Authenticate with Google APIs."""
        config = {
            "service_types": ["gmail", "sheets"],
            "credentials_file": os.getenv("GOOGLE_CREDENTIALS_FILE", "google_credentials.json"),
            "token_file": os.getenv("GMAIL_TOKEN_FILE", "gmail_token.json"),
        }
        oauth_task = GoogleOAuthTask("google_auth", config)
        return oauth_task.run()

    @task
    def list_emails(self, auth_info: dict) -> list:
        """List recent emails."""
        config = {
            "query": "newer_than:7d",
            "max_results": 5,
            "credentials": auth_info["credentials"],
        }
        list_task = GmailListEmailsTask("list_recent_emails", config)
        return list_task.run()

    @task
    def read_email(self, email_data: dict) -> dict:
        """Read the first email."""
        config = {
            "message_id": email_data["message_ids"][0],
            "format": "full",
            "credentials": email_data["credentials"],
        }
        read_task = GmailReadEmailTask("read_email", config)
        return read_task.run()

    @task
    def read_sheet(self, auth_info: dict) -> dict:
        """Read data from a Google Sheet."""
        config = {
            "spreadsheet_id": "your_spreadsheet_id",
            "sheet_name": "Sheet1",
            "credentials": auth_info["credentials"],
        }
        sheet_task = ReadGoogleSheetTask("read_google_sheet", config)
        return sheet_task.run()

def main():
    agent = GmailPipelineAgent("gmail_pipeline")
    results = agent.run()
    print("Pipeline Results:", results)

if __name__ == "__main__":
    main()
```

### Notes
- Ensure you have the necessary Google API credentials and environment variables set up before running the examples.
- Replace `"your_spreadsheet_id"` with the actual ID of your Google Sheet.
- The pipeline example demonstrates how to authenticate, list emails, read an email, and read data from a Google Sheet in a single workflow.

## API Reference

### PipelineAgent

The `PipelineAgent` class is responsible for managing the execution of a sequence of tasks in a pipeline, coordinating their dependencies and execution order.

**Methods:**
- `run() -> TaskResult` - Executes the pipeline and returns the result of the task execution.

**Attributes:**
- `tasks` - List of tasks to be executed in the pipeline.
- `dependencies` - List of task dependencies.

---

### BaseTask

The `BaseTask` class serves as the base class for all task types, providing common functionality and structure for task execution.

**Methods:**
- `get_dependencies() -> List[TaskDependency]` - Retrieves the list of task dependencies.
- `run() -> TaskResult` - Executes the task and returns the result.

**Attributes:**
- `name` - Name of the task.
- `config` - Configuration dictionary for the task.
- `dependencies` - List of task dependencies.

---

### GoogleOAuthTask

Handles Google OAuth2 authentication for specified services.

**Methods:**
- `__init__(name: str, config: Dict[str, Any], dependencies: Optional[List[TaskDependency]] = None)` - Initializes Google OAuth task.
- `create_combined_auth_config(credentials_file: Optional[str] = None, token_file: Optional[str] = None) -> Dict[str, Any]` - Creates configuration for Gmail + Sheets authentication.
- `create_custom_scopes_config(scopes: List[str], credentials_file: Optional[str] = None, token_file: Optional[str] = None) -> Dict[str, Any]` - Creates configuration with custom scopes.
- `create_gmail_auth_config(credentials_file: Optional[str] = None, token_file: Optional[str] = None) -> Dict[str, Any]` - Creates configuration for Gmail-only authentication.
- `create_sheets_auth_config(credentials_file: Optional[str] = None, token_file: Optional[str] = None) -> Dict[str, Any]` - Creates configuration for Sheets-only authentication.
- `get_dependencies() -> List[TaskDependency]` - Gets the list of task dependencies.
- `run() -> TaskResult` - Performs Google OAuth2 authentication.

**Attributes:**
- `name` - Task name.
- `config` - Configuration dictionary containing OAuth parameters.

**Configuration Parameters:**
- `scopes` (List[str]) - List of Google API scopes (optional).
- `service_types` (List[str]) - List of service types (optional).
- `credentials_file` (str) - Path to OAuth2 credentials file (optional).
- `token_file` (str) - Path to OAuth2 token file (optional).

---

### GmailListEmailsTask

Lists Gmail messages with optional filters and search queries.

**Methods:**
- `__init__(name: str, config: Dict[str, Any], dependencies: Optional[List[TaskDependency]] = None)` - Initializes Gmail list emails task.
- `create_search_query(**kwargs: Any) -> str` - Creates Gmail search queries using common patterns.
- `get_dependencies() -> List[TaskDependency]` - Gets the list of task dependencies.
- `run() -> TaskResult` - Lists Gmail messages based on query and filters.

**Attributes:**
- `name` - Task name.
- `config` - Configuration dictionary containing search parameters.

**Configuration Parameters:**
- `query` (str) - Gmail search query (optional).
- `max_results` (int) - Maximum number of messages to return (default: 10).
- `include_spam_trash` (bool) - Include spam and trash messages (default: False).
- `label_ids` (List[str]) - List of label IDs to filter by (optional).

---

### GmailReadEmailTask

Reads specific Gmail message content by ID.

**Methods:**
- `__init__(name: str, config: Dict[str, Any], dependencies: Optional[List[TaskDependency]] = None)` - Initializes Gmail read email task.
- `create_batch_read_config(message_ids: List[str], format: str = 'full', include_attachments: bool = True, credentials_file: Optional[str] = None, token_file: Optional[str] = None) -> Dict[str, Any]` - Creates configuration for reading multiple messages.
- `extract_message_ids_from_list_result(list_result_data: Dict[str, Any]) -> List[str]` - Extracts message IDs from GmailListEmailsTask result.
- `get_dependencies() -> List[TaskDependency]` - Gets the list of task dependencies.
- `run() -> TaskResult` - Reads Gmail message(s) content.

**Attributes:**
- `name` - Task name.
- `config` - Configuration dictionary containing message read parameters.

**Configuration Parameters:**
- `message_id` (str) - Gmail message ID to read (can be resolved from dependencies).
- `message_ids` (List[str]) - List of message IDs to read (alternative to message_id).
- `format` (str) - Message format (default: "full").
- `include_attachments` (bool) - Whether to include attachment info (default: True).

---

### ReadGoogleSheetTask

Reads data from Google Sheets and returns as 2D arrays.

**Methods:**
- `__init__(name: str, config: Dict[str, Any], dependencies: Optional[List[TaskDependency]] = None)` - Initializes Read Google Sheet task.
- `create_full_sheet_config(spreadsheet_id: str, sheet_name: str, include_headers: bool = True, credentials_file: Optional[str] = None, token_file: Optional[str] = None) -> Dict[str, Any]` - Creates configuration for reading an entire sheet.
- `create_range_config(spreadsheet_id: str, range_a1: str, include_headers: bool = True, credentials_file: Optional[str] = None, token_file: Optional[str] = None) -> Dict[str, Any]` - Creates configuration for reading a specific range.
- `create_sheet_config(spreadsheet_id: str, sheet_name: str, start_row: int = 1, end_row: Optional[int] = None, start_col: int = 1, end_col: Optional[int] = None, include_headers: bool = True, credentials_file: Optional[str] = None, token_file: Optional[str] = None) -> Dict[str, Any]` - Creates configuration for reading a sheet with bounds.
- `get_dependencies() -> List[TaskDependency]` - Gets the list of task dependencies.
- `run() -> TaskResult` - Reads data from Google Sheet.

**Attributes:**
- `name` - Task name.
- `config` - Configuration dictionary containing sheet read parameters.

**Configuration Parameters:**
- `spreadsheet_id` (str) - Google Spreadsheet ID (required).
- `range` (str) - Range in A1 notation (optional).
- `sheet_name` (str) - Name of sheet to read (optional).
- `start_row` (int) - Starting row number (1-based) (default: 1).
- `end_row` (Optional[int]) - Ending row number (1-based) (optional).
- `start_col` (int) - Starting column number (1-based) (default: 1).
- `end_col` (Optional[int]) - Ending column number (1-based) (optional).
- `include_headers` (bool) - Whether first row contains headers (default: True).

---

### GmailService

Gmail API service with OAuth2 authentication and common operations.

**Methods:**
- `__init__(credentials: Optional[Credentials] = None, credentials_file: Optional[str] = None, token_file: Optional[str] = None, scopes: Optional[List[str]] = None, timeout: int = 30)` - Initializes Gmail service.
- `create_label(name: str, message_list_visibility: str = 'show', label_list_visibility: str = 'labelShow') -> GmailLabel` - Creates a new Gmail label.
- `get_message(message_id: str, format: str = 'full', progress_callback: Optional[Callable[[str], None]] = None) -> Dict[str, Any]` - Gets a specific Gmail message by ID.
- `list_labels() -> List[GmailLabel]` - Lists all Gmail labels.
- `list_messages(query: str = '', max_results: int = 10, label_ids: Optional[List[str]] = None, include_spam_trash: bool = False, progress_callback: Optional[Callable[[str], None]] = None) -> List[Dict[str, Any]]` - Lists Gmail messages with optional query and filters.
- `modify_message_labels(message_id: str, add_label_ids: Optional[List[str]] = None, remove_label_ids: Optional[List[str]] = None) -> Dict[str, Any]` - Adds or removes labels from a message.
- `parse_message(message_data: Dict[str, Any]) -> GmailMessage` - Parses Gmail API message data into GmailMessage object.
- `send_message(to: str, subject: str, body: str, html_body: Optional[str] = None, cc: Optional[str] = None, bcc: Optional[str] = None, reply_to_message_id: Optional[str] = None) -> Dict[str, Any]` - Sends an email message.

**Attributes:**
- `credentials` - Pre-authenticated Google credentials.
- `credentials_file` - Path to OAuth2 credentials JSON file.
- `token_file` - Path to store/load OAuth2 tokens.
- `scopes` - List of Gmail API scopes to request.
- `timeout` - Request timeout in seconds.

---

### GoogleSheetsService

Google Sheets API service with OAuth2 authentication and read operations.

**Methods:**
- `__init__(credentials: Optional[Credentials] = None, credentials_file: Optional[str] = None, token_file: Optional[str] = None, timeout: int = 30)` - Initializes Google Sheets service.
- `get_sheet_names(spreadsheet_id: str, progress_callback: Optional[Callable[[str], None]] = None) -> List[str]` - Gets list of sheet names in a spreadsheet.
- `get_spreadsheet_info(spreadsheet_id: str, progress_callback: Optional[Callable[[str], None]] = None) -> SpreadsheetInfo` - Gets information about a spreadsheet.
- `read_all_data(spreadsheet_id: str, sheet_name: str, include_headers: bool = True, progress_callback: Optional[Callable[[str], None]] = None) -> SheetData` - Reads all data from a sheet.
- `read_range(spreadsheet_id: str, range_a1: str, include_headers: bool = True, progress_callback: Optional[Callable[[str], None]] = None) -> SheetData` - Reads data from a specific range in a spreadsheet.
- `read_sheet(spreadsheet_id: str, sheet_name: str, start_row: int = 1, end_row: Optional[int] = None, start_col: int = 1, end_col: Optional[int] = None, include_headers: bool = True, progress_callback: Optional[Callable[[str], None]] = None) -> SheetData` - Reads data from a sheet with row/column bounds.
- `validate_range(spreadsheet_id: str, range_a1: str, progress_callback: Optional[Callable[[str], None]] = None) -> bool` - Validates if a range exists and is accessible.

**Attributes:**
- `credentials` - Pre-authenticated Google credentials.
- `credentials_file` - Path to OAuth2 credentials JSON file.
- `token_file` - Path to store/load OAuth2 tokens.
- `timeout` - Request timeout in seconds.

---

### GoogleAuthService

Unified Google OAuth2 authentication service for multiple Google APIs.

**Methods:**
- `__init__(credentials_file: Optional[str] = None, token_file: Optional[str] = None, scopes: Optional[List[str]] = None)` - Initializes Google authentication service.
- `authenticate() -> Credentials` - Authenticates with Google APIs using OAuth2.
- `create_service_with_scopes(service_types: List[str], credentials_file: Optional[str] = None, token_file: Optional[str] = None) -> GoogleAuthService` - Creates authentication service with scopes for specific service types.
- `get_credentials() -> Credentials` - Gets authenticated credentials, authenticating if necessary.
- `get_scopes() -> List[str]` - Gets the configured scopes.
- `has_gmail_access() -> bool` - Checks if Gmail scopes are included.
- `has_scope(scope: str) -> bool` - Checks if a specific scope is included.
- `has_sheets_access() -> bool` - Checks if Sheets scopes are included.
- `is_authenticated() -> bool` - Checks if already authenticated.
- `to_dict() -> Dict[str, Any]` - Converts authentication info to dictionary.

**Attributes:**
- `credentials_file` - Path to OAuth2 credentials JSON file.
- `token_file` - Path to store/load OAuth2 tokens.
- `scopes` - List of Google API scopes to request.

---

### GmailMessage

Represents a Gmail message with parsed content.

**Methods:**
- `__init__(message_id: str, thread_id: str, label_ids: List[str], snippet: str, subject: str, sender: str, recipient: str, date: str, body: str, history_id: Optional[str] = None, internal_date: Optional[str] = None, size_estimate: int = 0, cc: str = '', bcc: str = '', html_body: str = '', attachments: List[GmailAttachment] = [], headers: Dict[str, str] = {})` - Initializes a Gmail message.

**Attributes:**
- `message_id` - Unique identifier for the message.
- `thread_id` - Identifier for the thread the message belongs to.
- `label_ids` - List of label IDs associated with the message.
- `snippet` - Short snippet of the message content.
- `subject` - Subject of the message.
- `sender` - Sender's email address.
- `recipient` - Recipient's email address.
- `date` - Date the message was sent.
- `body` - Body content of the message.
- `attachments` - List of attachments associated with the message.

---

### GmailThread

Represents a Gmail conversation thread.

**Methods:**
- `__init__(thread_id: str, history_id: str, messages: List[GmailMessage] = [])` - Initializes a Gmail thread.

**Attributes:**
- `thread_id` - Unique identifier for the thread.
- `history_id` - Identifier for the history of the thread.
- `messages` - List of messages in the thread.

---

### GmailLabel

Represents a Gmail label.

**Methods:**
- `__init__(label_id: str, name: str, message_list_visibility: Optional[str] = None, label_list_visibility: Optional[str] = None, label_type: Optional[str] = None, messages_total: Optional[int] = None, messages_unread: Optional[int] = None, threads_total: Optional[int] = None, threads_unread: Optional[int] = None)` - Initializes a Gmail label.

**Attributes:**
- `label_id` - Unique identifier for the label.
- `name` - Name of the label.
- `message_list_visibility` - Visibility of the label in the message list.
- `threads_total` - Total number of threads associated with the label.
- `threads_unread` - Number of unread threads associated with the label.

---

### GmailAttachment

Represents a Gmail message attachment.

**Methods:**
- `__init__(attachment_id: str, filename: str, mime_type: str, size: int)` - Initializes a Gmail attachment.

**Attributes:**
- `attachment_id` - Unique identifier for the attachment.
- `filename` - Name of the attachment file.
- `mime_type` - MIME type of the attachment.
- `size` - Size of the attachment in bytes.

---

### SheetData

Represents data read from a Google Sheet.

**Methods:**
- `__init__(spreadsheet_id: str, sheet_name: str, range_read: str, values: List[List[str]] = [], headers: List[str] = [], metadata: Dict[str, Any] = {})` - Initializes SheetData.
- `filter_rows(condition_func: Callable[[List[str]], bool]) -> SheetData` - Filters rows based on a condition function.
- `get_cell(row_index: int, col_index: int) -> str` - Gets value from a specific cell.
- `get_column(col_index: int) -> List[str]` - Gets values from a specific column.
- `get_row(row_index: int) -> List[str]` - Gets values from a specific row.
- `to_dict() -> Dict[str, Any]` - Converts to dictionary representation.
- `to_dict_list() -> List[Dict[str, str]]` - Converts to list of dictionaries using headers as keys.

**Attributes:**
- `spreadsheet_id` - ID of the spreadsheet.
- `sheet_name` - Name of the sheet.
- `range_read` - Range read from the sheet.
- `values` - 2D array of cell values.
- `headers` - List of header names.

---

### SheetRange

Represents a range within a Google Sheet.

**Methods:**
- `__init__(sheet_name: str, start_row: int, start_col: int, end_row: Optional[int] = None, end_col: Optional[int] = None)` - Initializes SheetRange.
- `from_a1_notation(a1_range: str) -> SheetRange` - Creates SheetRange from A1 notation.

**Attributes:**
- `sheet_name` - Name of the sheet.
- `start_row` - Starting row index.
- `start_col` - Starting column index.
- `end_row` - Ending row index (optional).
- `end_col` - Ending column index (optional).

---

### SpreadsheetInfo

Represents information about a Google Spreadsheet.

**Methods:**
- `__init__(spreadsheet_id: str, title: str, sheet_names: List[str] = [], properties: Dict[str, Any] = {})` - Initializes SpreadsheetInfo.
- `has_sheet(sheet_name: str) -> bool` - Checks if a sheet exists.

**Attributes:**
- `spreadsheet_id` - ID of the spreadsheet.
- `title` - Title of the spreadsheet.
- `sheet_names` - List of sheet names in the spreadsheet.
- `properties` - Additional properties of the spreadsheet.