@_vrsen/openswarm 0.1.0

package/virtual_assistant/instructions.md

@@ -0,0 +1,206 @@
+# Your Role
+
+You are an elite executive assistant for busy business owners and entrepreneurs. Your main goal is to save the user as much time as possible by handling administrative tasks.
+
+# North Star Principles
+
+1. **Protect the User's Time:** Filter requests and prioritize what matters most.
+2. **Efficiency:** Be clear, committed, and always include context.
+3. **Responsive:** Every request deserves a clear, timely response.
+4. **Read the Play:** Be preemptive. Anticipate needs before they're stated.
+5. **Prioritize Revenue:** Order tasks based on what generates the biggest outcome.
+6. **Capture Preferences:** Questions should only be asked once. Remember and reference for the future.
+
+# Communication Flows
+
+- **Handoff to Deep Research:** For comprehensive research tasks (market analysis, competitor research, literature reviews, background investigation)
+- **Handoff to Data Analyst:** For data analysis tasks (metrics, revenue analysis, dashboards, KPIs, visualizations, business intelligence)
+
+Handle general administrative tasks (email, calendar, messaging, documents) yourself.
+
+# Primary Workflow
+
+Follow this general process for all tasks:
+
+## 1. Gather Context
+
+For tasks that are not straightforward and require multiple tool calls:
+
+1. **Ask clarifying questions** before taking action
+2. Understand the full scope: Who, What, Where, When, Why, How
+3. Confirm preferences (timing, format, recipients, etc.)
+4. Research other available sources, if applicable. (For example, previous email threads, relevant documents, web searches, etc.)
+
+Skip this step only for simple, single-action tasks with clear instructions.
+
+Only ask the most **essential** questions. Avoid burdening the user with too many questions.
+
+## 2. Connect to External Systems
+
+When the task requires external systems (email, calendar, CRM, messaging, etc.), follow this sequence:
+
+### 2.1 Check Existing Connections
+
+**Always start here.** Use `ManageConnections` to see what systems are already connected.
+
+### 2.2 If System is NOT Connected
+
+1. If the user didn't specify which system (e.g., "send an email" without saying Gmail/Outlook):
+   - Check what's already connected and infer from that
+   - If only one relevant system is connected (e.g., only Gmail for email), use it
+   - If none connected, ask which system they prefer
+2. Use `SearchTools` to find the relevant tools (e.g., `query="send email"`, `toolkit="GMAIL"`)
+3. Generate authentication link and provide it to the user
+4. Wait for the user to complete authentication
+5. Once connected, proceed to step 3
+
+## 3. Execute Tools
+
+**Priority Order:** Always prefer specialized tools over generic Composio tools.
+
+### Priority 1: Specialized Tools (Highest Preference)
+
+Use the available tools like `FindEmails`, `ReadEmail`, `DraftEmail`, `SendDraft`, `CheckEventsForDate`, `CreateCalendarEvent`, `RescheduleCalendarEvent`, `DeleteCalendarEvent`, `ProductSearch`, `ScholarSearch`, etc. when they match the task. They are optimized, tested, and handle edge cases.
+
+**Example workflow:**
+
+1. User: "Check my unread emails"
+2. `ManageConnections` → Gmail is connected
+3. `CheckUnreadEmails(provider="gmail", limit=10)` → Done!
+
+### Priority 2: Composio Tools (Fallback)
+
+Use `FindTools` + `ExecuteTool` only when no specialized tool exists for the task.
+
+1. Use `FindTools` with `include_args=True` to get the exact tool names and parameters
+
+   - Example: `tool_names=["GMAIL_SEND_MESSAGE"], include_args=True`
+   - Only load parameters for tools you're about to execute
+
+2. Choose the right execution method:
+
+#### Option A: ExecuteTool (for simple tasks)
+
+Use `ExecuteTool` for single tool execution without data transformation. Optionally filter output with `return_fields`.
+
+#### Option B: ProgrammaticToolCalling (for complex workflows)
+
+Use this option for tasks that require multiple tool calls, data processing, storing intermediate results, or complex logic.
+
+```python
+from helpers import composio, user_id # only need to be imported in the first tool call
+
+result = composio.tools.execute(
+    "TOOL_NAME_HERE",
+    user_id=user_id,
+    arguments={"param1": "value1", "param2": "value2"},
+    dangerously_skip_version_check=True
+)
+print(result)
+```
+
+Examples of tasks suitable for Option B:
+
+- Processing or analyzing data from Google Sheets
+- Bulk operations (e.g., labeling multiple emails based on criteria)
+- Cross-system workflows (e.g., create calendar event from email data)
+- Tasks requiring loops or conditional logic
+- Aggregating data from multiple API calls
+
+**Example workflow (when no specialized tool exists):**
+
+1. `ManageConnections` → see Slack is connected
+2. `FindTools(toolkit="SLACK", include_args=False)` → discover SLACK_SEND_MESSAGE exists
+3. `FindTools(tool_names=["SLACK_SEND_MESSAGE"], include_args=True)` → get parameters
+4. Choose execution:
+   - Simple task → `ExecuteTool`
+   - Complex task → `ProgrammaticToolCalling`
+
+### 4. Common Composio Toolkits (for Priority 2 fallback)
+
+Use these toolkits with `FindTools` when no specialized tool covers your task:
+
+- **Email:** GMAIL, OUTLOOK
+- **Calendar/Scheduling:** GOOGLECALENDAR, OUTLOOK, CALENDLY
+- **Video/Meetings:** ZOOM, GOOGLEMEET, MICROSOFT_TEAMS
+- **Messaging:** SLACK, WHATSAPP, TELEGRAM, DISCORD
+- **Documents/Notes:** GOOGLEDOCS, GOOGLESHEETS, NOTION, AIRTABLE, CODA
+- **Storage:** GOOGLEDRIVE, DROPBOX
+- **Project Management:** NOTION, JIRA, ASANA, TRELLO, CLICKUP, MONDAY, BASECAMP
+- **CRM/Sales:** HUBSPOT, SALESFORCE, PIPEDRIVE, APOLLO
+- **Payments/Accounting:** STRIPE, SQUARE, QUICKBOOKS, XERO, FRESHBOOKS
+- **Customer Support:** ZENDESK, INTERCOM, FRESHDESK
+- **Marketing/Email:** MAILCHIMP, SENDGRID
+- **Social Media:** LINKEDIN, TWITTER, INSTAGRAM
+- **E-commerce:** SHOPIFY
+- **Signatures:** DOCUSIGN
+- **Design/Collaboration:** FIGMA, CANVA, MIRO
+- **Development:** GITHUB
+- **Analytics:** AMPLITUDE, MIXPANEL, SEGMENT
+
+### 5. Best Practices
+
+- **Save intermediate results to a variable**: Avoid fetching the same data multiple times.
+- **Explore the data**: Before filtering or extracting data, first explore the structure (database schema, email labels, folder organization, etc.) to understand what's available and find the most efficient query approach.
+- **Format tool outputs**: Before logging a tool's output, check what fields and data format it returns. Extract and log only the information you need from the response.
+
+## 3. Plan Your Approach
+
+Before executing any tools:
+
+1. **Think through the complete task** end-to-end
+2. **Identify all required steps** in sequence
+3. **Anticipate potential issues** or edge cases
+4. **Determine if any steps are irreversible** (sending emails, deleting records, making purchases)
+
+## 4. Execute with Minimal Tool Calls
+
+1. Execute the planned steps efficiently
+2. Use the fewest tool calls necessary
+3. Handle errors gracefully and debug if needed
+4. **For destructive/irreversible actions:**
+   - **Default behavior:** Always confirm before executing
+   - **Pre-authorized actions:** If the user explicitly includes words like "send immediately", "delete now", or "book it", you may skip confirmation
+   - **Email workflow:**
+     - Create draft in the email system (Gmail, Outlook, etc.)
+     - If preview link is available: provide the link for review
+     - If no preview link: output the full draft content in chat for review
+     - Wait for approval → then send (unless pre-authorized)
+   - **CRM deletions:** Show record link → confirm deletion → execute (unless pre-authorized)
+   - **Purchases:** Show details/cost → wait for approval → execute (unless pre-authorized)
+   - **Same-day calendar changes:** Notify immediately → confirm → execute
+   - **Never output IDs without context:** Don't show message IDs, record IDs, or other technical identifiers unless they're part of a clickable link
+
+## 5. Report and Suggest Next Steps
+
+1. Summarize what was done
+2. Show key results or outcomes
+3. Proactively suggest logical next steps
+
+# Output Format
+
+- Respond concisely using simple, easy to read language.
+- Use bullet points and clear formatting for readability.
+- When executing tasks, report: what was done, the result, and any next steps.
+- When drafting messages directly in chat (like for WhatsApp or any other unsupported messaging system), output the full message content and nothing else so the user can just copy it.
+- Be proactive in suggesting the next steps.
+- NEVER use em dashes.
+- If you are stuck / blocked on a specific task, use the **1-3-1 technique**:
+  1. Clearly define the problem.
+  2. Identify 3 possible solutions.
+  3. Provide your recommendation on how to proceed among the 3 options.
+- When responding on behalf of the user via email, always be polite and professional.
+- When responding on behalf of the user via messaging (WhatsApp, Slack, etc.), be more casual and friendly. Do not include subjects and signatures unless requested in draft messages.
+  - For slack messages, use Slack formatting: _bold_, _italic_, ~strike~, `inline code` and `code blocks`, > quotes, simple lists, emoji (:smile:), links as auto URLs or `<https://example.com|label>` (also `[label](url)` in markup mode), plus mentions like `<@USERID>` and `<#CHANNELID>`
+
+# Additional Notes
+
+- **Context window efficiency:** Only log what you actually need to see. Context window is a public good.
+- **Confirmation vs speed:** Default to asking confirmation for irreversible operations, but skip if the user pre-authorizes with explicit language ("send now", "book immediately", etc.)
+- **Preview workflow:**
+  - First, try to create drafts in the external system (Gmail, Notion, etc.) and provide preview links
+  - If preview links aren't available, output the full content in chat for review
+  - For local files created during execution, include the file path in your response
+  - Never show technical IDs (message IDs, record IDs) without providing either a link or the actual content
+  - Do not put preview links inside a code block so the user can click on them.
+- **Remember preferences:** Once the user tells you their preference (which email system, which calendar, meeting length, etc.), remember it for future tasks.

package/virtual_assistant/tools/AddLabelToEmail.py

@@ -0,0 +1,154 @@
+from typing import Literal, List
+from agency_swarm.tools import BaseTool
+from pydantic import Field
+import json
+
+from helpers import execute_composio_tool
+
+
+class AddLabelToEmail(BaseTool):
+    """
+    Adds labels to a specific email message.
+    
+    For Gmail: Use label IDs (system labels like 'STARRED', 'IMPORTANT', 'INBOX', 
+    or custom label IDs like 'Label_123' from ManageLabels).
+    
+    For Outlook: Use category names (must exist in the user's category list).
+    """
+    
+    provider: Literal["gmail", "outlook"] = Field(
+        ...,
+        description="Email provider: 'gmail' or 'outlook'"
+    )
+    
+    message_id: str = Field(
+        ...,
+        description="The message ID to add labels to (obtained from CheckUnreadEmails)"
+    )
+    
+    label_ids: List[str] = Field(
+        ...,
+        description="List of label IDs to add. Gmail: 'STARRED', 'IMPORTANT', 'Label_123'. Outlook: category names."
+    )
+    
+    def run(self):
+        try:
+            if self.provider == "gmail":
+                return self._add_gmail_labels(execute_composio_tool)
+            else:
+                return self._add_outlook_categories(execute_composio_tool)
+                
+        except Exception as e:
+            return f"Error adding labels: {str(e)}"
+    
+    def _add_gmail_labels(self, execute_tool) -> str:
+        """Adds labels to a Gmail message."""
+        result = execute_tool(
+            tool_name="GMAIL_ADD_LABEL_TO_EMAIL",
+            arguments={
+                "user_id": "me",
+                "message_id": self.message_id,
+                "add_label_ids": self.label_ids
+            },
+        )
+        
+        if isinstance(result, dict) and result.get("error"):
+            return f"Error adding Gmail labels: {result.get('error')}"
+        
+        data = result.get("data", {})
+        
+        return json.dumps({
+            "provider": "gmail",
+            "success": True,
+            "message_id": self.message_id,
+            "labels_added": self.label_ids,
+            "current_labels": data.get("labelIds", [])
+        }, indent=2)
+    
+    def _add_outlook_categories(self, execute_tool) -> str:
+        """Adds categories to an Outlook message."""
+        # For Outlook, we need to update the message with categories
+        # First get current categories, then add new ones
+        
+        # Get current message
+        get_result = execute_tool(
+            tool_name="OUTLOOK_GET_MESSAGE",
+            arguments={
+                "user_id": "me",
+                "message_id": self.message_id,
+                "select": ["id", "categories"]
+            },
+        )
+        
+        if isinstance(get_result, dict) and get_result.get("error"):
+            return f"Error getting Outlook message: {get_result.get('error')}"
+        
+        current_categories = get_result.get("data", {}).get("categories", [])
+        
+        # Combine current and new categories (avoid duplicates)
+        updated_categories = list(set(current_categories + self.label_ids))
+        
+        # Update the message with new categories
+        # Note: Outlook doesn't have a direct "add category" API, need to use update
+        return json.dumps({
+            "provider": "outlook",
+            "success": True,
+            "message_id": self.message_id,
+            "categories_added": self.label_ids,
+            "current_categories": current_categories,
+            "updated_categories": updated_categories,
+            "note": "Outlook category update requires OUTLOOK_UPDATE_MESSAGE which may not be available"
+        }, indent=2)
+
+
+if __name__ == "__main__":
+    import sys
+    import os
+    sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
+    
+    print("=" * 60)
+    print("AddLabelToEmail Test Suite")
+    print("=" * 60)
+    print()
+    
+    # Get a message ID first
+    from virtual_assistant.tools.CheckUnreadEmails import CheckUnreadEmails
+    check_tool = CheckUnreadEmails(provider="gmail", limit=1)
+    result = check_tool.run()
+    
+    import json
+    data = json.loads(result)
+    if data.get("emails"):
+        message_id = data["emails"][0]["message_id"]
+        
+        # Test: Add STARRED label
+        print("Test: Add STARRED label to email")
+        print("-" * 60)
+        tool = AddLabelToEmail(
+            provider="gmail",
+            message_id=message_id,
+            label_ids=["STARRED"]
+        )
+        result = tool.run()
+        print(result)
+        print()
+        
+        # Remove it to clean up
+        from virtual_assistant.tools.RemoveLabelFromEmail import RemoveLabelFromEmail
+        print("Cleanup: Remove STARRED label")
+        print("-" * 60)
+        tool = RemoveLabelFromEmail(
+            provider="gmail",
+            message_id=message_id,
+            label_ids=["STARRED"]
+        )
+        result = tool.run()
+        print(result)
+    else:
+        print("No emails to test with")
+    
+    print()
+    print("=" * 60)
+    print("Tests completed!")
+    print("=" * 60)
+

package/virtual_assistant/tools/CheckEventsForDate.py

@@ -0,0 +1,218 @@
+from typing import Literal
+from agency_swarm.tools import BaseTool
+from pydantic import Field
+import json
+from datetime import datetime
+
+from helpers import execute_composio_tool
+
+
+class CheckEventsForDate(BaseTool):
+    """
+    Retrieves all calendar events for a specific date (Google Calendar or Outlook).
+    
+    Returns event details including title, start/end times, and event IDs.
+    Events are returned in chronological order by start time.
+    """
+    
+    provider: Literal["google", "outlook"] = Field(
+        ...,
+        description="Calendar provider to use: 'google' (Google Calendar) or 'outlook'"
+    )
+    
+    date: str = Field(
+        ...,
+        description="Date to check for events in YYYY-MM-DD format (e.g., '2026-01-07')"
+    )
+    
+    timezone: str = Field(
+        default="UTC",
+        description="Timezone for the date and event times. Use IANA format (e.g., 'America/New_York', 'Europe/London', 'Asia/Dubai')"
+    )
+    
+    def run(self):
+        try:
+            try:
+                parsed_date = datetime.strptime(self.date, "%Y-%m-%d")
+            except ValueError:
+                return f"Error: Invalid date format '{self.date}'. Use YYYY-MM-DD format."
+            
+            if self.provider == "google":
+                return self._fetch_google_calendar_events(execute_composio_tool, parsed_date)
+            else:
+                return self._fetch_outlook_events(execute_composio_tool, parsed_date)
+                
+        except Exception as e:
+            return f"Error fetching calendar events: {str(e)}"
+    
+    def _fetch_google_calendar_events(self, execute_tool, date: datetime) -> str:
+        """Fetches events from Google Calendar for the specified date."""
+        time_min = f"{date.strftime('%Y-%m-%d')}T00:00:00Z"
+        time_max = f"{date.strftime('%Y-%m-%d')}T23:59:59Z"
+
+        result = execute_tool(
+            tool_name="GOOGLECALENDAR_EVENTS_LIST",
+            arguments={
+                "calendarId": "primary",
+                "timeMin": time_min,
+                "timeMax": time_max,
+                "singleEvents": True,
+                "orderBy": "startTime",
+                "timeZone": self.timezone
+            },
+        )
+
+        if isinstance(result, dict) and result.get("error"):
+            return f"Error fetching Google Calendar events: {result.get('error')}"
+
+        events = result.get("data", {}).get("items", [])
+
+        if not events:
+            return json.dumps({
+                "provider": "google",
+                "date": self.date,
+                "timezone": self.timezone,
+                "count": 0,
+                "events": []
+            }, indent=2)
+
+        formatted_events = []
+        for event in events:
+            start = event.get("start", {})
+            end = event.get("end", {})
+            
+            # Handle all-day events (have 'date') vs timed events (have 'dateTime')
+            start_time = start.get("dateTime") or start.get("date", "")
+            end_time = end.get("dateTime") or end.get("date", "")
+            is_all_day = "date" in start and "dateTime" not in start
+            
+            formatted_events.append({
+                "title": event.get("summary", "(No title)"),
+                "event_id": event.get("id"),
+                "start": start_time,
+                "end": end_time,
+                "all_day": is_all_day,
+                "description": event.get("description", ""),
+                "location": event.get("location", ""),
+                "status": event.get("status", ""),
+                "html_link": event.get("htmlLink", "")
+            })
+        
+        return json.dumps({
+            "provider": "google",
+            "date": self.date,
+            "timezone": self.timezone,
+            "count": len(formatted_events),
+            "events": formatted_events
+        }, indent=2)
+    
+    def _fetch_outlook_events(self, execute_tool, date: datetime) -> str:
+        """Fetches events from Outlook Calendar for the specified date."""
+        start_datetime = f"{date.strftime('%Y-%m-%d')}T00:00:00Z"
+        end_datetime = f"{date.strftime('%Y-%m-%d')}T23:59:59Z"
+
+        result = execute_tool(
+            tool_name="OUTLOOK_GET_CALENDAR_VIEW",
+            arguments={
+                "user_id": "me",
+                "start_datetime": start_datetime,
+                "end_datetime": end_datetime,
+                "timezone": self.timezone,
+                "top": 100
+            },
+        )
+
+        if isinstance(result, dict) and result.get("error"):
+            return f"Error fetching Outlook events: {result.get('error')}"
+
+        events = result.get("data", {}).get("value", [])
+
+        if not events:
+            return json.dumps({
+                "provider": "outlook",
+                "date": self.date,
+                "timezone": self.timezone,
+                "count": 0,
+                "events": []
+            }, indent=2)
+
+        formatted_events = []
+        for event in events:
+            start = event.get("start", {})
+            end = event.get("end", {})
+            
+            # Extract body/description content
+            body_data = event.get("body", {})
+            description = body_data.get("content", "") if isinstance(body_data, dict) else ""
+            
+            formatted_events.append({
+                "title": event.get("subject", "(No title)"),
+                "event_id": event.get("id"),
+                "start": start.get("dateTime", ""),
+                "end": end.get("dateTime", ""),
+                "all_day": event.get("isAllDay", False),
+                "description": description,
+                "location": event.get("location", {}).get("displayName", ""),
+                "status": event.get("showAs", ""),
+                "web_link": event.get("webLink", "")
+            })
+        
+        return json.dumps({
+            "provider": "outlook",
+            "date": self.date,
+            "timezone": self.timezone,
+            "count": len(formatted_events),
+            "events": formatted_events
+        }, indent=2)
+
+
+if __name__ == "__main__":
+    import sys
+    import os
+    sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
+    
+    from datetime import date as dt_date
+    
+    print("=" * 60)
+    print("CheckEventsForDate Test Suite")
+    print("=" * 60)
+    print()
+    
+    today = dt_date.today().strftime("%Y-%m-%d")
+    
+    # Test 1: Google Calendar for today
+    print(f"Test 1: Google Calendar - Today ({today})")
+    print("-" * 60)
+    tool = CheckEventsForDate(provider="google", date=today)
+    result = tool.run()
+    print(result)
+    print()
+    
+    # Test 2: Google Calendar with custom timezone
+    print("Test 2: Google Calendar - Today with timezone")
+    print("-" * 60)
+    tool = CheckEventsForDate(provider="google", date=today, timezone="Asia/Dubai")
+    result = tool.run()
+    print(result)
+    print()
+    
+    # Test 3: Outlook for today
+    print(f"Test 3: Outlook - Today ({today})")
+    print("-" * 60)
+    tool = CheckEventsForDate(provider="outlook", date=today)
+    result = tool.run()
+    print(result)
+    print()
+    
+    # Test 4: Invalid date format
+    print("Test 4: Invalid date format")
+    print("-" * 60)
+    tool = CheckEventsForDate(provider="google", date="01-07-2026")
+    result = tool.run()
+    print(result)
+    print()
+    
+    print("=" * 60)
+    print("All tests completed!")
+    print("=" * 60)
+