connectonion 0.5.8__py3-none-any.whl

connectonion/useful_tools/todo_list.py

@@ -0,0 +1,241 @@
+"""
+Purpose: Task tracking tool for agents to manage multi-step task progress with visual display
+LLM-Note:
+  Dependencies: imports from [typing, dataclasses, rich.console, rich.table, rich.panel] | imported by [useful_tools/__init__.py] | tested by [tests/unit/test_todo_list_tool.py]
+  Data flow: Agent calls TodoList methods → modifies internal _todos list → _display() renders Rich table with status indicators → returns confirmation string
+  State/Effects: maintains in-memory list of TodoItem objects | displays Rich-formatted table in terminal | no file persistence | no network I/O
+  Integration: exposes TodoList class with add(content, active_form), start(content), complete(content), remove(content), list_todos() | used as agent tool via Agent(tools=[TodoList()])
+  Performance: O(n) list operations | Rich rendering per state change | no caching
+  Errors: returns "Not found" if todo doesn't exist | no exceptions raised
+
+TodoList - Task tracking for agents."""
+
+from typing import List, Literal, Optional
+from dataclasses import dataclass, field
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+
+
+@dataclass
+class TodoItem:
+    """A single todo item."""
+    content: str
+    status: Literal["pending", "in_progress", "completed"]
+    active_form: str
+
+
+class TodoList:
+    """Task tracking tool for agents.
+
+    Helps agents track progress on complex, multi-step tasks.
+    Shows visual progress to the user.
+
+    Example:
+        todo = TodoList()
+        agent = Agent("worker", tools=[todo])
+
+        # Agent can call:
+        # todo.add("Fix authentication bug", "Fixing authentication bug")
+        # todo.start("Fix authentication bug")
+        # todo.complete("Fix authentication bug")
+    """
+
+    def __init__(self, console: Optional[Console] = None):
+        self._todos: List[TodoItem] = []
+        self._console = console or Console()
+
+    def add(self, content: str, active_form: str) -> str:
+        """Add a new todo item.
+
+        Args:
+            content: What needs to be done (imperative form, e.g., "Fix bug")
+            active_form: Present continuous form (e.g., "Fixing bug")
+
+        Returns:
+            Confirmation message
+        """
+        if self._find(content):
+            return f"Todo already exists: {content}"
+
+        self._todos.append(TodoItem(
+            content=content,
+            status="pending",
+            active_form=active_form
+        ))
+        self._display()
+        return f"Added: {content}"
+
+    def start(self, content: str) -> str:
+        """Mark a todo as in_progress.
+
+        Args:
+            content: The todo content to start
+
+        Returns:
+            Confirmation or error message
+        """
+        item = self._find(content)
+        if not item:
+            return f"Todo not found: {content}"
+
+        if item.status == "completed":
+            return f"Cannot start completed todo: {content}"
+
+        # Check if another task is in_progress
+        in_progress = [t for t in self._todos if t.status == "in_progress"]
+        if in_progress and in_progress[0].content != content:
+            return f"Another task is in progress: {in_progress[0].content}. Complete it first."
+
+        item.status = "in_progress"
+        self._display()
+        return f"Started: {item.active_form}"
+
+    def complete(self, content: str) -> str:
+        """Mark a todo as completed.
+
+        Args:
+            content: The todo content to complete
+
+        Returns:
+            Confirmation or error message
+        """
+        item = self._find(content)
+        if not item:
+            return f"Todo not found: {content}"
+
+        item.status = "completed"
+        self._display()
+        return f"Completed: {content}"
+
+    def remove(self, content: str) -> str:
+        """Remove a todo from the list.
+
+        Args:
+            content: The todo content to remove
+
+        Returns:
+            Confirmation or error message
+        """
+        item = self._find(content)
+        if not item:
+            return f"Todo not found: {content}"
+
+        self._todos.remove(item)
+        self._display()
+        return f"Removed: {content}"
+
+    def list(self) -> str:
+        """Get all todos as formatted text.
+
+        Returns:
+            Formatted list of all todos
+        """
+        if not self._todos:
+            return "No todos"
+
+        lines = []
+        for item in self._todos:
+            status_icon = self._status_icon(item.status)
+            lines.append(f"{status_icon} {item.content}")
+
+        return "\n".join(lines)
+
+    def update(self, todos: List[dict]) -> str:
+        """Replace entire todo list (for bulk updates).
+
+        Args:
+            todos: List of dicts with content, status, active_form keys
+
+        Returns:
+            Confirmation message
+        """
+        self._todos = []
+        for t in todos:
+            self._todos.append(TodoItem(
+                content=t["content"],
+                status=t["status"],
+                active_form=t.get("active_form", t["content"] + "...")
+            ))
+        self._display()
+        return f"Updated {len(self._todos)} todos"
+
+    def clear(self) -> str:
+        """Clear all todos.
+
+        Returns:
+            Confirmation message
+        """
+        count = len(self._todos)
+        self._todos = []
+        return f"Cleared {count} todos"
+
+    def _find(self, content: str) -> Optional[TodoItem]:
+        """Find todo by content."""
+        for item in self._todos:
+            if item.content == content:
+                return item
+        return None
+
+    def _status_icon(self, status: str) -> str:
+        """Get icon for status."""
+        return {
+            "pending": "○",
+            "in_progress": "◐",
+            "completed": "●"
+        }.get(status, "○")
+
+    def _status_style(self, status: str) -> str:
+        """Get style for status."""
+        return {
+            "pending": "dim",
+            "in_progress": "cyan bold",
+            "completed": "green"
+        }.get(status, "")
+
+    def _display(self):
+        """Display todos in a nice table."""
+        if not self._todos:
+            return
+
+        table = Table(show_header=False, box=None, padding=(0, 1))
+        table.add_column("Status", width=2)
+        table.add_column("Task")
+
+        for item in self._todos:
+            icon = self._status_icon(item.status)
+            style = self._status_style(item.status)
+
+            if item.status == "in_progress":
+                text = item.active_form
+            else:
+                text = item.content
+
+            table.add_row(f"[{style}]{icon}[/]", f"[{style}]{text}[/]")
+
+        # Count stats
+        completed = sum(1 for t in self._todos if t.status == "completed")
+        total = len(self._todos)
+
+        self._console.print(Panel(
+            table,
+            title=f"[bold]Tasks[/] ({completed}/{total})",
+            border_style="blue",
+            padding=(0, 1)
+        ))
+
+    @property
+    def progress(self) -> float:
+        """Get progress as percentage (0.0 to 1.0)."""
+        if not self._todos:
+            return 1.0
+        completed = sum(1 for t in self._todos if t.status == "completed")
+        return completed / len(self._todos)
+
+    @property
+    def current_task(self) -> Optional[str]:
+        """Get the currently in_progress task."""
+        for item in self._todos:
+            if item.status == "in_progress":
+                return item.active_form
+        return None

connectonion/useful_tools/web_fetch.py

@@ -0,0 +1,216 @@
+"""
+Purpose: Web page fetching and parsing tool for HTTP requests and HTML analysis
+LLM-Note:
+  Dependencies: imports from [httpx] | imported by [useful_tools/__init__.py] | tested by [tests/unit/test_web_fetch.py]
+  Data flow: Agent calls WebFetch methods → httpx.get() fetches URL → returns raw HTML or parsed content (title, links, emails, social links) | analyze_page() and get_contact_info() use LLM for interpretation
+  State/Effects: makes HTTP GET requests | no local file persistence | no authentication required | respects timeout setting
+  Integration: exposes WebFetch class with fetch(url), strip_tags(html), get_title(html), get_links(html), get_emails(html), get_social_links(html), analyze_page(url), get_contact_info(url) | used as agent tool via Agent(tools=[WebFetch()])
+  Performance: network I/O per request | configurable timeout (default 15s) | no caching | high-level methods may call LLM
+  Errors: httpx exceptions propagate on network errors | returns error strings for display to user
+
+WebFetch tool for fetching web pages.
+
+Usage:
+    from connectonion import Agent, WebFetch
+
+    web = WebFetch()
+    agent = Agent("assistant", tools=[web])
+
+    # Agent can now use:
+    # Low-level:
+    # - fetch(url) - HTTP GET, returns raw HTML
+    # - strip_tags(html) - Strip HTML tags, returns body text only
+    # - get_title(html) - Get page title
+    # - get_links(html) - Extract all links
+    # - get_emails(html) - Extract email addresses
+    # - get_social_links(html) - Extract social media links
+    # High-level (with LLM):
+    # - analyze_page(url) - What does this page/company do
+    # - get_contact_info(url) - Extract contact information (email, phone, address)
+"""
+
+import httpx
+
+
+class WebFetch:
+    """Web fetching tool with single-responsibility functions."""
+
+    def __init__(self, timeout: int = 15):
+        """Initialize WebFetch tool.
+
+        Args:
+            timeout: Request timeout in seconds (default: 15)
+        """
+        self.timeout = timeout
+
+    def fetch(self, url: str) -> str:
+        """HTTP GET request, returns raw HTML.
+
+        Args:
+            url: URL to fetch (e.g., "https://example.com" or "example.com")
+
+        Returns:
+            Raw HTML response text
+        """
+        # Ensure URL has scheme
+        if not url.startswith(('http://', 'https://')):
+            url = 'https://' + url
+
+        response = httpx.get(
+            url,
+            follow_redirects=True,
+            timeout=self.timeout,
+            headers={'User-Agent': 'Mozilla/5.0 (compatible; ResearchBot/1.0)'}
+        )
+        response.raise_for_status()
+        return response.text
+
+    def strip_tags(self, html: str, max_chars: int = 10000) -> str:
+        """Strip HTML tags and return plain text from body only.
+
+        Args:
+            html: Raw HTML string
+            max_chars: Maximum characters to return (default: 10000)
+
+        Returns:
+            Clean plain text (body content only)
+        """
+        from bs4 import BeautifulSoup
+        import re
+
+        soup = BeautifulSoup(html, 'html.parser')
+
+        # Only get body content
+        body = soup.body if soup.body else soup
+
+        # Remove all non-text elements
+        for tag in body(['script', 'style', 'meta', 'link', 'nav', 'footer', 'header', 'aside', 'noscript', 'iframe', 'svg', 'img', 'video', 'audio']):
+            tag.decompose()
+
+        # Get text
+        text = body.get_text(separator='\n', strip=True)
+
+        # Clean up multiple newlines
+        text = re.sub(r'\n{3,}', '\n\n', text)
+
+        return text[:max_chars]
+
+    def get_title(self, html: str) -> str:
+        """Get page title from HTML.
+
+        Args:
+            html: Raw HTML string
+
+        Returns:
+            Page title or empty string if not found
+        """
+        from bs4 import BeautifulSoup
+
+        soup = BeautifulSoup(html, 'html.parser')
+        title_tag = soup.find('title')
+        return title_tag.get_text(strip=True) if title_tag else ''
+
+    def get_links(self, html: str) -> list:
+        """Extract all links from HTML.
+
+        Args:
+            html: Raw HTML string
+
+        Returns:
+            List of dicts with 'text' and 'href' keys
+        """
+        from bs4 import BeautifulSoup
+
+        soup = BeautifulSoup(html, 'html.parser')
+        links = []
+        for a in soup.find_all('a', href=True):
+            href = a['href']
+            text = a.get_text(strip=True)
+            if href and not href.startswith('#') and not href.startswith('javascript:'):
+                links.append({'text': text, 'href': href})
+        return links
+
+    def get_emails(self, html: str) -> list:
+        """Extract email addresses from HTML.
+
+        Args:
+            html: Raw HTML string
+
+        Returns:
+            List of unique email addresses found
+        """
+        import re
+
+        email_pattern = r'[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
+        emails = re.findall(email_pattern, html)
+        return list(set(emails))
+
+    def get_social_links(self, html: str) -> dict:
+        """Extract social media links from HTML.
+
+        Args:
+            html: Raw HTML string
+
+        Returns:
+            Dict with social platform names as keys and URLs as values
+        """
+        links = self.get_links(html)
+        social_patterns = {
+            'twitter': ['twitter.com', 'x.com'],
+            'linkedin': ['linkedin.com'],
+            'facebook': ['facebook.com'],
+            'instagram': ['instagram.com'],
+            'youtube': ['youtube.com'],
+            'github': ['github.com'],
+            'discord': ['discord.gg', 'discord.com'],
+        }
+
+        social = {}
+        for link in links:
+            href = link['href'].lower()
+            for platform, patterns in social_patterns.items():
+                if any(p in href for p in patterns):
+                    social[platform] = link['href']
+                    break
+        return social
+
+    # === High-level APIs (with LLM) ===
+
+    def analyze_page(self, url: str) -> str:
+        """Analyze what a webpage/company does.
+
+        Args:
+            url: URL to analyze
+
+        Returns:
+            Brief description of what this page/company does
+        """
+        from connectonion.llm_do import llm_do
+
+        html = self.fetch(url)
+        title = self.get_title(html)
+        content = self.strip_tags(html, max_chars=6000)
+
+        return llm_do(
+            f"Title: {title}\n\nContent:\n{content}",
+            system_prompt="Briefly describe what this website/company does in 2-3 sentences. Be concise and factual."
+        )
+
+    def get_contact_info(self, url: str) -> str:
+        """Extract contact information from a webpage.
+
+        Args:
+            url: URL to extract contact info from
+
+        Returns:
+            Contact information (email, phone, address, social links)
+        """
+        from connectonion.llm_do import llm_do
+
+        html = self.fetch(url)
+        content = self.strip_tags(html, max_chars=8000)
+
+        return llm_do(
+            content,
+            system_prompt="Extract any contact information from this page: email addresses, phone numbers, physical addresses, social media links. Return only what you find, or 'No contact info found' if none."
+        )