connectonion 0.5.8__py3-none-any.whl

connectonion/useful_tools/__init__.py

@@ -0,0 +1,44 @@
+"""
+Purpose: Export all useful tools and utilities for ConnectOnion agents
+LLM-Note:
+  Dependencies: imports from [send_email, get_emails, memory, gmail, google_calendar, outlook, microsoft_calendar, web_fetch, shell, diff_writer, tui.pick, terminal, todo_list, slash_command] | imported by [__init__.py main package] | re-exports tools for agent consumption
+  Data flow: agent imports from useful_tools → accesses tool functions/classes directly
+  State/Effects: no state | pure re-exports | lazy loading for heavy dependencies
+  Integration: exposes send_email, get_emails, mark_read, mark_unread (email functions) | Memory, Gmail, GoogleCalendar, Outlook, MicrosoftCalendar, WebFetch, Shell, DiffWriter, TodoList (tool classes) | pick, yes_no, autocomplete (TUI helpers) | SlashCommand (extension point)
+  Errors: ImportError if dependency not installed (e.g., google-auth for GoogleCalendar, httpx for Outlook/MicrosoftCalendar)
+"""
+
+from .send_email import send_email
+from .get_emails import get_emails, mark_read, mark_unread
+from .memory import Memory
+from .gmail import Gmail
+from .google_calendar import GoogleCalendar
+from .outlook import Outlook
+from .microsoft_calendar import MicrosoftCalendar
+from .web_fetch import WebFetch
+from .shell import Shell
+from .diff_writer import DiffWriter
+from ..tui import pick
+from .terminal import yes_no, autocomplete
+from .todo_list import TodoList
+from .slash_command import SlashCommand
+
+__all__ = [
+    "send_email",
+    "get_emails",
+    "mark_read",
+    "mark_unread",
+    "Memory",
+    "Gmail",
+    "GoogleCalendar",
+    "Outlook",
+    "MicrosoftCalendar",
+    "WebFetch",
+    "Shell",
+    "DiffWriter",
+    "pick",
+    "yes_no",
+    "autocomplete",
+    "TodoList",
+    "SlashCommand"
+]

connectonion/useful_tools/diff_writer.py

@@ -0,0 +1,192 @@
+"""
+Purpose: Human-in-the-loop file writing tool with diff preview and approval workflow
+LLM-Note:
+  Dependencies: imports from [difflib, pathlib, rich.console, rich.panel, rich.text, connectonion.tui.pick] | imported by [useful_tools/__init__.py] | tested by [tests/unit/test_diff_writer.py, tests/unit/test_diff_writer_tool.py]
+  Data flow: Agent calls DiffWriter.write(path, content) → reads existing file → generates unified diff → displays via Rich panel → pick() prompts for approval → writes if approved → returns status string
+  State/Effects: reads and writes files on filesystem | displays Rich-formatted diff in terminal | blocks for user input (unless auto_approve=True) | creates new files if path doesn't exist
+  Integration: exposes DiffWriter class with write(path, content), diff(path, content), read(path) | used as agent tool via Agent(tools=[DiffWriter()]) | auto_approve=True for automation
+  Performance: file I/O per operation | difflib is O(n) for diff generation | Rich rendering is fast | blocks on user input
+  Errors: returns error string if file unreadable | returns "Cancelled" if user rejects | no exceptions raised
+
+DiffWriter - Human-in-the-loop file writing with diff display.
+
+Usage:
+    from connectonion import Agent, DiffWriter
+
+    writer = DiffWriter()
+    agent = Agent("coder", tools=[writer])
+
+    # Agent can now use:
+    # - write(path, content) - Write with diff display and approval
+    # - diff(path, content) - Preview diff without writing
+    # - read(path) - Read file contents
+"""
+
+import difflib
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from connectonion.tui import pick
+
+
+class DiffWriter:
+    """File writer with diff display and human approval."""
+
+    def __init__(self, auto_approve: bool = False):
+        """Initialize DiffWriter.
+
+        Args:
+            auto_approve: If True, skip approval prompts (for automation)
+        """
+        self.auto_approve = auto_approve
+        self._console = Console()
+
+    def write(self, path: str, content: str) -> str:
+        """Write content to a file with diff display and approval.
+
+        Args:
+            path: File path to write to
+            content: Content to write
+
+        Returns:
+            Success message, rejection message, or user feedback for agent
+        """
+        file_path = Path(path)
+
+        if not self.auto_approve:
+            diff_text = self._generate_diff(path, content)
+            if diff_text:
+                self._display_diff(diff_text, path)
+            else:
+                self._display_new_file(path, content)
+
+            choice = self._ask_approval(path)
+
+            if choice == "reject":
+                self._console.print()
+                self._console.print("[bold yellow]What should the agent do instead?[/]")
+                feedback = input("> ")
+                return f"User rejected changes to {path}. Feedback: {feedback}"
+
+            if choice == "approve_all":
+                self.auto_approve = True
+
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(content, encoding='utf-8')
+        return f"Wrote {len(content)} bytes to {path}"
+
+    def diff(self, path: str, content: str) -> str:
+        """Show diff without writing (preview mode).
+
+        Args:
+            path: File path to compare against
+            content: New content to compare
+
+        Returns:
+            Diff string in unified format
+        """
+        diff_text = self._generate_diff(path, content)
+        if diff_text:
+            self._display_diff(diff_text, path)
+            return diff_text
+        return f"No changes to {path}"
+
+    def read(self, path: str) -> str:
+        """Read file contents.
+
+        Args:
+            path: File path to read
+
+        Returns:
+            File contents or error message
+        """
+        file_path = Path(path)
+        if not file_path.exists():
+            return f"Error: File {path} not found"
+        return file_path.read_text(encoding='utf-8')
+
+    def _ask_approval(self, path: str) -> str:
+        """Ask user for approval with single keypress.
+
+        Returns:
+            'approve', 'approve_all', or 'reject'
+        """
+        self._console.print()
+        self._console.print(f"[bold cyan]File:[/] {path}")
+
+        choice = pick(
+            f"Apply changes to {path}?",
+            {
+                "1": "Yes, apply this change",
+                "2": "Yes to all (auto-approve for session)",
+                "3": "No, and tell agent what to do instead",
+            },
+            console=self._console,
+        )
+        return {"1": "approve", "2": "approve_all", "3": "reject"}[choice]
+
+    def _generate_diff(self, path: str, new_content: str) -> str:
+        """Generate unified diff between existing file and new content."""
+        file_path = Path(path)
+
+        if file_path.exists():
+            original_lines = file_path.read_text(encoding='utf-8').splitlines(keepends=True)
+        else:
+            return ""  # New file, no diff
+
+        new_lines = new_content.splitlines(keepends=True)
+
+        diff = difflib.unified_diff(
+            original_lines,
+            new_lines,
+            fromfile=f"a/{path}",
+            tofile=f"b/{path}",
+        )
+
+        return ''.join(diff)
+
+    def _display_diff(self, diff_text: str, path: str):
+        """Display colorized diff."""
+        styled = Text()
+
+        for line in diff_text.splitlines():
+            if line.startswith('+++') or line.startswith('---'):
+                styled.append(line + '\n', style="bold white")
+            elif line.startswith('@@'):
+                styled.append(line + '\n', style="cyan")
+            elif line.startswith('+'):
+                styled.append(line + '\n', style="green")
+            elif line.startswith('-'):
+                styled.append(line + '\n', style="red")
+            else:
+                styled.append(line + '\n', style="dim")
+
+        panel = Panel(
+            styled,
+            title=f"[bold yellow]Changes to {path}[/]",
+            border_style="yellow",
+            padding=(0, 1)
+        )
+        self._console.print(panel)
+
+    def _display_new_file(self, path: str, content: str):
+        """Display preview of new file."""
+        styled = Text()
+
+        lines = content.splitlines()
+        for line in lines[:50]:  # Limit preview to 50 lines
+            styled.append(f"+ {line}\n", style="green")
+
+        if len(lines) > 50:
+            styled.append(f"... ({len(lines) - 50} more lines)\n", style="dim")
+
+        panel = Panel(
+            styled,
+            title=f"[bold yellow]New file: {path}[/]",
+            border_style="yellow",
+            padding=(0, 1)
+        )
+        self._console.print(panel)

connectonion/useful_tools/get_emails.py

@@ -0,0 +1,183 @@
+"""
+Purpose: Retrieve emails from agent's inbox via OpenOnion API with filtering options
+LLM-Note:
+  Dependencies: imports from [os, json, toml, requests, pathlib, typing, dotenv] | imported by [__init__.py, useful_tools/__init__.py] | tested by [tests/test_email_functions.py, tests/test_real_email.py]
+  Data flow: Agent calls get_emails(last=10, unread=False) → searches for .env file → loads OPENONION_API_KEY → GET to oo.openonion.ai/api/email with query params → returns List[Dict] with emails: {id, from, to, subject, body, html_body, date, read} | mark_read(email_id) PUTs to /api/email/{id}/read
+  State/Effects: reads .env files | makes HTTP GET/PUT requests | no local caching | mark_read() modifies server-side read status
+  Integration: exposes get_emails(last, unread), mark_read(email_id) | used as agent tool functions | requires 'co auth' setup | API endpoints: GET /api/email?last=N&unread=true, PUT /api/email/{id}/read
+  Performance: one HTTP request per call | no pagination (uses 'last' param) | synchronous blocking | no local cache
+  Errors: returns empty list [] on failure | HTTP errors caught and wrapped in error dict | missing auth returns error | let-it-crash pattern for API failures
+"""
+
+import os
+import json
+import toml
+import requests
+from pathlib import Path
+from typing import List, Dict, Optional, Union
+
+
+def get_emails(last: int = 10, unread: bool = False) -> List[Dict]:
+    """Get emails sent to the agent's address.
+
+    Args:
+        last: Number of emails to retrieve (default: 10)
+        unread: Only get unread emails (default: False)
+
+    Returns:
+        List of email dictionaries containing:
+            - id: Unique message ID
+            - from: Sender's email address
+            - subject: Email subject
+            - message: Email body content
+            - timestamp: ISO format timestamp
+            - read: Boolean read status
+    """
+    # Get authentication token from environment
+    # Emails are hosted by OpenOnion and require OPENONION_API_KEY for authentication
+    token = os.getenv("OPENONION_API_KEY")
+
+    if not token:
+        raise ValueError(
+            "OPENONION_API_KEY not found in .env file. "
+            "Agent emails are hosted by OpenOnion and require authentication. "
+            "Check your .env file for OPENONION_API_KEY, or run 'co init' to copy "
+            "OPENONION_API_KEY from ~/.co/keys.env to your project."
+        )
+    
+    # Fetch emails from backend API
+    backend_url = os.getenv("CONNECTONION_BACKEND_URL", "https://oo.openonion.ai")
+    endpoint = f"{backend_url}/api/v1/email/received"
+
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json"
+    }
+
+    params = {
+        "limit": last,
+        "unread_only": unread
+    }
+
+    response = requests.get(
+        endpoint,
+        params=params,
+        headers=headers,
+        timeout=10
+    )
+
+    # Raise error if API call failed
+    response.raise_for_status()
+
+    data = response.json()
+    emails = data.get("emails", [])
+
+    # Ensure consistent format
+    formatted_emails = []
+    for email in emails:
+        formatted_emails.append({
+            "id": email.get("id", ""),
+            "from": email.get("from_email", email.get("from", "")),
+            "subject": email.get("subject", ""),
+            "message": email.get("text_body", email.get("html_body", "")),
+            "timestamp": email.get("received_at", ""),
+            "read": email.get("is_read", False)
+        })
+
+    return formatted_emails
+
+
+def mark_read(email_ids: Union[str, List[str]]) -> bool:
+    """Mark email(s) as read.
+
+    Args:
+        email_ids: Single email ID or list of IDs to mark as read
+
+    Returns:
+        True if successful, False otherwise
+    """
+    # Normalize to list
+    if isinstance(email_ids, str):
+        email_ids = [email_ids]
+
+    if not email_ids:
+        raise ValueError("No email IDs provided to mark as read")
+
+    # Get authentication token from environment
+    token = os.getenv("OPENONION_API_KEY")
+
+    if not token:
+        raise ValueError(
+            "OPENONION_API_KEY not found in .env file. "
+            "Check your .env file for OPENONION_API_KEY, or run 'co init' to copy "
+            "OPENONION_API_KEY from ~/.co/keys.env to your project."
+        )
+    
+    # Mark emails as read via backend API
+    backend_url = os.getenv("CONNECTONION_BACKEND_URL", "https://oo.openonion.ai")
+    endpoint = f"{backend_url}/api/v1/email/s/mark-read"
+
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json"
+    }
+
+    # Mark each email as read individually
+    for email_id in email_ids:
+        response = requests.post(
+            f"{endpoint}?email_id={email_id}",
+            headers=headers,
+            timeout=10
+        )
+        # Raise error if API call failed
+        response.raise_for_status()
+
+    return True
+
+
+def mark_unread(email_ids: Union[str, List[str]]) -> bool:
+    """Mark email(s) as unread.
+
+    Args:
+        email_ids: Single email ID or list of IDs to mark as unread
+
+    Returns:
+        True if successful, False otherwise
+    """
+    # Normalize to list
+    if isinstance(email_ids, str):
+        email_ids = [email_ids]
+
+    if not email_ids:
+        raise ValueError("No email IDs provided to mark as unread")
+
+    # Get authentication token from environment
+    token = os.getenv("OPENONION_API_KEY")
+
+    if not token:
+        raise ValueError(
+            "OPENONION_API_KEY not found in .env file. "
+            "Check your .env file for OPENONION_API_KEY, or run 'co init' to copy "
+            "OPENONION_API_KEY from ~/.co/keys.env to your project."
+        )
+
+    # Mark emails as unread via backend API
+    backend_url = os.getenv("CONNECTONION_BACKEND_URL", "https://oo.openonion.ai")
+    endpoint = f"{backend_url}/api/v1/email/s/mark-unread"
+
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json"
+    }
+
+    # Mark each email as unread individually
+    for email_id in email_ids:
+        response = requests.post(
+            f"{endpoint}?email_id={email_id}",
+            headers=headers,
+            timeout=10
+        )
+        # Raise error if API call failed
+        response.raise_for_status()
+
+    return True