connectonion 0.5.8__py3-none-any.whl

connectonion/cli/templates/playwright/agent.py

@@ -0,0 +1,336 @@
+"""
+Purpose: Browser automation agent template using Playwright for web scraping and interaction
+LLM-Note:
+  Dependencies: imports from [playwright.sync_api, connectonion.Agent, connectonion.xray, json] | requires playwright package | template file copied by [cli/commands/init.py, cli/commands/create.py]
+  Data flow: user command → Agent.input() → BrowserAutomation methods (navigate, click, fill_form, scrape_content, take_screenshot) → Playwright browser actions → returns results
+  State/Effects: stateful browser session (playwright, browser, page) | tracks visited_urls, screenshots | modifies filesystem with screenshots | headless browser process
+  Integration: template for 'co create --template playwright' | BrowserAutomation class passed as tool | uses prompt.md for system prompt | @xray decorator on all methods
+  Performance: browser launch overhead 1-3s | operations vary by page complexity | max_iterations=20 for complex automation
+  Errors: graceful fallback if Playwright not installed | method-level error handling returns error strings | cleanup on exit
+
+Playwright Web Automation Agent - Browser control and web scraping
+
+Based on the ConnectOnion Playwright example with stateful browser tools.
+"""
+
+try:
+    from playwright.sync_api import sync_playwright
+    PLAYWRIGHT_AVAILABLE = True
+except ImportError:
+    PLAYWRIGHT_AVAILABLE = False
+    print("⚠️  Playwright not installed. Run: pip install playwright && playwright install")
+
+from connectonion import Agent, xray
+from typing import Optional, List, Dict
+import json
+
+
+class BrowserAutomation:
+    """Stateful browser automation tools with shared browser instance."""
+    
+    def __init__(self):
+        self.playwright = None
+        self.browser = None
+        self.page = None
+        self.screenshots = []
+        self.visited_urls = []
+        self.downloads = []
+    
+    @xray
+    def start_browser(self, headless: bool = True) -> str:
+        """Start a browser instance.
+        
+        Args:
+            headless: Run browser in headless mode (no UI)
+        """
+        if not PLAYWRIGHT_AVAILABLE:
+            return "Error: Playwright not installed. Run: pip install playwright && playwright install"
+        
+        if self.browser:
+            return "Browser already running"
+        
+        self.playwright = sync_playwright().start()
+        self.browser = self.playwright.chromium.launch(headless=headless)
+        self.page = self.browser.new_page()
+        return f"✅ Browser started (headless={headless})"
+    
+    @xray
+    def navigate(self, url: str, wait_until: str = "load") -> str:
+        """Navigate to a URL.
+        
+        Args:
+            url: The URL to navigate to
+            wait_until: When to consider navigation done ('load', 'domcontentloaded', 'networkidle')
+        """
+        if not self.page:
+            return "❌ Browser not started. Call start_browser() first."
+        
+        try:
+            self.page.goto(url, wait_until=wait_until)
+            self.visited_urls.append(url)
+            title = self.page.title()
+            return f"✅ Navigated to {url}\nPage title: {title}"
+        except Exception as e:
+            return f"❌ Navigation failed: {e}"
+    
+    @xray
+    def take_screenshot(self, filename: str = None, full_page: bool = False) -> str:
+        """Take a screenshot of the current page.
+        
+        Args:
+            filename: Name for the screenshot file
+            full_page: Capture full scrollable page
+        """
+        if not self.page:
+            return "❌ No page loaded"
+        
+        if not filename:
+            filename = f"screenshot_{len(self.screenshots) + 1}.png"
+        
+        try:
+            self.page.screenshot(path=filename, full_page=full_page)
+            self.screenshots.append(filename)
+            return f"📸 Screenshot saved as {filename}"
+        except Exception as e:
+            return f"❌ Screenshot failed: {e}"
+    
+    @xray
+    def scrape_content(self, selector: str = "body") -> str:
+        """Extract text content from the page.
+        
+        Args:
+            selector: CSS selector for the element to scrape
+        """
+        if not self.page:
+            return "❌ No page loaded"
+        
+        try:
+            element = self.page.query_selector(selector)
+            if element:
+                text = element.inner_text()
+                return f"📄 Content from {selector}:\n{text[:500]}..." if len(text) > 500 else f"📄 Content from {selector}:\n{text}"
+            else:
+                return f"❌ No element found matching selector: {selector}"
+        except Exception as e:
+            return f"❌ Scraping failed: {e}"
+    
+    @xray
+    def fill_form(self, form_data: str) -> str:
+        """Fill form fields on the page.
+        
+        Args:
+            form_data: JSON string with selector-value pairs, e.g., '{"#name": "John", "#email": "john@example.com"}'
+        """
+        if not self.page:
+            return "❌ No page loaded"
+        
+        try:
+            data = json.loads(form_data)
+            filled = []
+            
+            for selector, value in data.items():
+                self.page.fill(selector, str(value))
+                filled.append(f"{selector} = {value}")
+            
+            return f"✅ Form filled:\n" + "\n".join(filled)
+        except json.JSONDecodeError:
+            return "❌ Invalid JSON format for form_data"
+        except Exception as e:
+            return f"❌ Form filling failed: {e}"
+    
+    @xray
+    def click(self, selector: str) -> str:
+        """Click an element on the page.
+        
+        Args:
+            selector: CSS selector for the element to click
+        """
+        if not self.page:
+            return "❌ No page loaded"
+        
+        try:
+            self.page.click(selector)
+            # Wait a bit for any navigation
+            self.page.wait_for_load_state("networkidle", timeout=5000)
+            return f"✅ Clicked element: {selector}\nCurrent URL: {self.page.url}"
+        except Exception as e:
+            return f"❌ Click failed on {selector}: {e}"
+    
+    @xray
+    def extract_links(self, filter_pattern: str = "") -> str:
+        """Extract all links from the current page.
+        
+        Args:
+            filter_pattern: Optional pattern to filter links
+        """
+        if not self.page:
+            return "❌ No page loaded"
+        
+        try:
+            links = self.page.eval_on_selector_all(
+                'a[href]',
+                'elements => elements.map(e => ({text: e.innerText, href: e.href}))'
+            )
+            
+            if filter_pattern:
+                links = [link for link in links if filter_pattern in link['href']]
+            
+            if not links:
+                return "No links found" + (f" matching '{filter_pattern}'" if filter_pattern else "")
+            
+            result = f"🔗 Found {len(links)} links:\n"
+            for link in links[:10]:  # Show first 10
+                result += f"  - {link['text'][:30]}: {link['href']}\n"
+            
+            if len(links) > 10:
+                result += f"  ... and {len(links) - 10} more"
+            
+            return result
+        except Exception as e:
+            return f"❌ Link extraction failed: {e}"
+    
+    @xray
+    def wait_for_element(self, selector: str, timeout: int = 5000) -> str:
+        """Wait for an element to appear on the page.
+        
+        Args:
+            selector: CSS selector to wait for
+            timeout: Maximum wait time in milliseconds
+        """
+        if not self.page:
+            return "❌ No page loaded"
+        
+        try:
+            self.page.wait_for_selector(selector, timeout=timeout)
+            return f"✅ Element {selector} appeared"
+        except Exception as e:
+            return f"❌ Element {selector} did not appear within {timeout}ms"
+    
+    @xray
+    def execute_javascript(self, script: str) -> str:
+        """Execute JavaScript code on the page.
+        
+        Args:
+            script: JavaScript code to execute
+        """
+        if not self.page:
+            return "❌ No page loaded"
+        
+        try:
+            result = self.page.evaluate(script)
+            return f"✅ JavaScript executed. Result: {result}"
+        except Exception as e:
+            return f"❌ JavaScript execution failed: {e}"
+    
+    @xray
+    def get_page_info(self) -> str:
+        """Get information about the current page."""
+        if not self.page:
+            return "❌ No page loaded"
+        
+        info = {
+            "url": self.page.url,
+            "title": self.page.title(),
+            "viewport": self.page.viewport_size,
+        }
+        
+        return f"📊 Page info:\n" + json.dumps(info, indent=2)
+    
+    @xray
+    def get_session_info(self) -> str:
+        """Get information about the browser session."""
+        info = {
+            "browser_running": self.browser is not None,
+            "current_url": self.page.url if self.page else None,
+            "visited_urls": self.visited_urls,
+            "screenshots_taken": len(self.screenshots),
+            "screenshot_files": self.screenshots,
+        }
+        
+        return f"📊 Session info:\n" + json.dumps(info, indent=2)
+    
+    @xray
+    def close_browser(self) -> str:
+        """Close the browser and clean up resources."""
+        if self.page:
+            self.page.close()
+            self.page = None
+        if self.browser:
+            self.browser.close()
+            self.browser = None
+        if self.playwright:
+            self.playwright.stop()
+            self.playwright = None
+        
+        return "✅ Browser closed and resources cleaned up"
+
+
+# Create browser automation instance
+browser = BrowserAutomation()
+
+# Create the Playwright automation agent with stateful tools
+agent = Agent(
+    name="playwright_agent",
+    system_prompt="prompt.md",
+    tools=browser,  # Pass the entire class instance - all methods become tools
+    max_iterations=20  # More iterations for complex web automation
+)
+
+
+def main():
+    """Run the Playwright agent in interactive mode."""
+    print("🌐 Playwright Web Automation Agent")
+    print("Stateful browser automation with persistent session")
+    print("Type 'quit' to exit\n")
+
+    # Interactive conversation loop
+    while True:
+        user_input = input("You: ").strip()
+
+        if user_input.lower() in ['quit', 'exit', 'q']:
+            # Clean up browser resources before exit
+            try:
+                browser.close_browser()
+            except:
+                pass
+            print("👋 Goodbye!")
+            break
+
+        if not user_input:
+            continue
+
+        # Get response from agent
+        response = agent.input(user_input)
+        print(f"Agent: {response}\n")
+
+
+if __name__ == "__main__":
+    if not PLAYWRIGHT_AVAILABLE:
+        print("⚠️  Playwright is not installed!")
+        print("To use this agent, run:")
+        print("  pip install -r requirements.txt")
+        print("  playwright install chromium\n")
+    else:
+        print("🌐 Playwright Web Automation Agent initialized!")
+        print("Stateful browser automation with persistent session\n")
+
+        print("Available browser tools:")
+        for tool_name in agent.list_tools():
+            print(f"  🔧 {tool_name}")
+
+        print("\n📚 Example commands:")
+        print('  "Start the browser and go to example.com"')
+        print('  "Take a screenshot of the page"')
+        print('  "Extract all links from the page"')
+        print('  "Get the page title and URL"')
+
+        print("\n💡 Tips:")
+        print("  - Browser state persists across commands")
+        print("  - Always start_browser() before other operations")
+        print("  - Use close_browser() when done (or type 'quit')")
+        print("  - Ask for session_info() to see browser state\n")
+
+        print("=" * 50 + "\n")
+
+        # Start interactive mode
+        main()

connectonion/cli/templates/playwright/prompt.md

@@ -0,0 +1,102 @@
+# Playwright Web Automation Agent
+
+You are a web automation specialist using Playwright for browser automation, web scraping, and testing. You can interact with web pages programmatically to extract data, fill forms, take screenshots, and perform complex web interactions.
+
+## Core Capabilities
+
+### 🌐 Navigation & Loading
+- **navigate_to_url**: Browse to any URL with configurable wait conditions
+- Handle different page load states (load, domcontentloaded, networkidle)
+
+### 📊 Data Extraction
+- **scrape_page_content**: Extract content using CSS selectors
+- **extract_links**: Gather all links with optional filtering
+- Parse and structure web data efficiently
+
+### 📝 Form Interaction
+- **fill_form**: Complete and submit web forms
+- Handle various input types and validation
+
+### 📸 Visual Capture
+- **take_screenshot**: Capture page screenshots (full or viewport)
+- Document visual states and layouts
+
+### 🖱️ User Interactions
+- **wait_and_click**: Click elements with smart waiting
+- **execute_javascript**: Run custom JavaScript on pages
+- Simulate complex user behaviors
+
+### 💾 File Operations
+- **download_file**: Download files from web sources
+- Handle various file types and download scenarios
+
+## Best Practices
+
+1. **Wait Strategies**: Always use appropriate wait conditions for dynamic content
+2. **Error Handling**: Gracefully handle timeouts and missing elements
+3. **Selector Strategy**: Use stable, specific CSS selectors
+4. **Performance**: Minimize unnecessary page loads and interactions
+5. **Data Validation**: Verify scraped data before processing
+
+## Common Use Cases
+
+### Web Scraping
+- Extract product information from e-commerce sites
+- Gather news articles or blog posts
+- Collect structured data from tables
+
+### Automation
+- Fill and submit contact forms
+- Automate repetitive web tasks
+- Navigate multi-step processes
+
+### Testing
+- Capture screenshots for visual regression
+- Verify page elements and content
+- Test form submissions and interactions
+
+### Data Collection
+- Download reports and documents
+- Extract API responses from network traffic
+- Gather links for crawling
+
+## Interaction Guidelines
+
+When users request web automation:
+1. Understand the target website and goal
+2. Plan the automation sequence
+3. Use appropriate tools for each step
+4. Handle potential errors gracefully
+5. Return structured, useful data
+
+## Example Workflows
+
+### Scraping Workflow
+1. Navigate to target URL
+2. Wait for content to load
+3. Extract data using selectors
+4. Process and structure the data
+5. Return formatted results
+
+### Form Automation
+1. Navigate to form page
+2. Fill in form fields
+3. Handle any validation
+4. Submit the form
+5. Verify submission success
+
+### Screenshot Documentation
+1. Navigate to pages
+2. Wait for full render
+3. Capture screenshots
+4. Save with descriptive names
+5. Report completion
+
+## Important Notes
+
+- **Installation Required**: Users need to install Playwright (`pip install playwright`) and browsers (`playwright install chromium`)
+- **Headless Mode**: Default operations run headless for efficiency
+- **Rate Limiting**: Respect website rate limits and robots.txt
+- **Legal Compliance**: Ensure web scraping complies with website terms of service
+
+You are here to make web automation simple, reliable, and efficient for users.

connectonion/cli/templates/playwright/requirements.txt

@@ -0,0 +1,3 @@
+connectonion
+playwright
+python-dotenv

connectonion/cli/templates/web-research/agent.py

@@ -0,0 +1,122 @@
+"""
+Purpose: Web research agent template for searching, extracting, and analyzing web data
+LLM-Note:
+  Dependencies: imports from [os, json, requests, connectonion.Agent, connectonion.llm_do] | template file copied by [cli/commands/init.py, cli/commands/create.py]
+  Data flow: user query → Agent.input() → search_web (placeholder) | extract_data fetches URL → returns content preview | analyze_data uses llm_do | save_research writes JSON file
+  State/Effects: HTTP requests to external URLs | writes research JSON files | uses MODEL env var or co/gemini-2.5-pro
+  Integration: template for 'co create --template web-research' | tools: search_web, extract_data, analyze_data, save_research | extensible for real search APIs
+  Performance: HTTP timeout 10s | analysis truncates to 1000 chars for llm_do
+  Errors: request exceptions caught and returned | ⚠️ TODO: search_web is placeholder, needs real API integration
+
+Web research agent with data extraction capabilities.
+"""
+
+import os
+import json
+import requests
+from typing import Dict, List, Any
+from connectonion import Agent, llm_do
+
+
+def search_web(query: str) -> str:
+    """Search the web for information.
+    
+    Args:
+        query: Search query
+        
+    Returns:
+        Search results summary
+    """
+    # This is a placeholder - you would integrate with a real search API
+    return f"Searching for: {query}\n\nResults:\n1. Example result about {query}\n2. Another relevant finding"
+
+
+def extract_data(url: str, data_type: str = "text") -> Dict[str, Any]:
+    """Extract data from a webpage.
+    
+    Args:
+        url: URL to extract data from
+        data_type: Type of data to extract (text, links, images)
+        
+    Returns:
+        Extracted data dictionary
+    """
+    try:
+        response = requests.get(url, timeout=10)
+        response.raise_for_status()
+        
+        # Simple extraction logic - expand as needed
+        if data_type == "text":
+            # In production, use BeautifulSoup or similar
+            return {
+                "url": url,
+                "status": response.status_code,
+                "content_length": len(response.text),
+                "preview": response.text[:500]
+            }
+        else:
+            return {"url": url, "data_type": data_type, "note": "Extraction not implemented"}
+            
+    except Exception as e:
+        return {"error": str(e), "url": url}
+
+
+def analyze_data(data: str, analysis_type: str = "summary") -> str:
+    """Analyze extracted data.
+    
+    Args:
+        data: Data to analyze
+        analysis_type: Type of analysis (summary, sentiment, keywords)
+        
+    Returns:
+        Analysis results
+    """
+    # Use LLM for analysis
+    prompt = f"Perform {analysis_type} analysis on this data: {data[:1000]}"
+    return llm_do(prompt)
+
+
+def save_research(topic: str, findings: List[str], filename: str = None) -> str:
+    """Save research findings to a file.
+    
+    Args:
+        topic: Research topic
+        findings: List of findings
+        filename: Output filename (optional)
+        
+    Returns:
+        Confirmation message
+    """
+    if not filename:
+        filename = f"research_{topic.replace(' ', '_')}.json"
+    
+    research_data = {
+        "topic": topic,
+        "findings": findings,
+        "timestamp": __import__('datetime').datetime.now().isoformat()
+    }
+    
+    with open(filename, 'w') as f:
+        json.dump(research_data, f, indent=2)
+    
+    return f"Research saved to {filename}"
+
+
+def main():
+    """Run the web research agent."""
+    # Create agent with web research tools
+    agent = Agent(
+        name="web-research-agent",
+        tools=[search_web, extract_data, analyze_data, save_research],
+        model=os.getenv("MODEL", "co/gemini-2.5-pro")
+    )
+    
+    # Example research task
+    response = agent.input(
+        "Research the latest trends in AI and summarize the key findings"
+    )
+    print(response)
+
+
+if __name__ == "__main__":
+    main()

connectonion/connect.py

@@ -0,0 +1,128 @@
+"""
+Purpose: Client interface for connecting to remote agents via relay network using INPUT/OUTPUT protocol
+LLM-Note:
+  Dependencies: imports from [asyncio, json, uuid, websockets] | imported by [__init__.py, tests/test_connect.py, examples/] | tested by [tests/test_connect.py, tests/integration/manual/network_connect_manual.py]
+  Data flow: user calls connect(address, relay_url) → creates RemoteAgent instance → user calls .input(prompt) → _send_task() creates WebSocket to relay /ws/input → sends INPUT message with {type, input_id, to, prompt} → waits for OUTPUT response from relay → returns result string OR raises ConnectionError
+  State/Effects: establishes temporary WebSocket connection per task (no persistent connection) | sends INPUT messages to relay | receives OUTPUT/ERROR messages | no file I/O or global state | asyncio.run() blocks on .input(), await on .input_async()
+  Integration: exposes connect(address, relay_url), RemoteAgent class with .input(prompt, timeout), .input_async(prompt, timeout) | default relay_url="wss://oo.openonion.ai/ws/announce" | address format: 0x + 64 hex chars (Ed25519 public key) | complements host() with relay_url which listens for INPUT on relay | Protocol: INPUT type with to/prompt fields → OUTPUT type with input_id/result fields
+  Performance: creates new WebSocket connection per input() call (no connection pooling) | default timeout=30s | async under the hood (asyncio.run wraps for sync API) | no caching or retry logic
+  Errors: raises ImportError if websockets not installed | raises ConnectionError for ERROR responses from relay | raises ConnectionError for unexpected response types | asyncio.TimeoutError if no response within timeout | WebSocket connection errors bubble up
+
+Connect to remote agents on the network.
+
+Simple function-based API for using remote agents.
+"""
+
+import asyncio
+import json
+import uuid
+
+
+class RemoteAgent:
+    """
+    Interface to a remote agent.
+
+    Minimal MVP: Just input() method.
+    """
+
+    def __init__(self, address: str, relay_url: str):
+        self.address = address
+        self._relay_url = relay_url
+
+    def input(self, prompt: str, timeout: float = 30.0) -> str:
+        """
+        Send task to remote agent and get response (sync version).
+
+        Use this in normal synchronous code.
+        For async code, use input_async() instead.
+
+        Args:
+            prompt: Task/prompt to send
+            timeout: Seconds to wait for response (default 30)
+
+        Returns:
+            Agent's response string
+
+        Example:
+            >>> translator = connect("0x3d40...")
+            >>> result = translator.input("Translate 'hello' to Spanish")
+        """
+        return asyncio.run(self._send_task(prompt, timeout))
+
+    async def input_async(self, prompt: str, timeout: float = 30.0) -> str:
+        """
+        Send task to remote agent and get response (async version).
+
+        Use this when calling from async code.
+
+        Args:
+            prompt: Task/prompt to send
+            timeout: Seconds to wait for response (default 30)
+
+        Returns:
+            Agent's response string
+
+        Example:
+            >>> remote = connect("0x3d40...")
+            >>> result = await remote.input_async("Translate 'hello' to Spanish")
+        """
+        return await self._send_task(prompt, timeout)
+
+    async def _send_task(self, prompt: str, timeout: float) -> str:
+        """
+        Send input via relay and wait for output.
+
+        MVP: Uses relay to route INPUT/OUTPUT messages between agents.
+        """
+        import websockets
+
+        input_id = str(uuid.uuid4())
+
+        # Connect to relay input endpoint
+        relay_input_url = self._relay_url.replace("/ws/announce", "/ws/input")
+
+        async with websockets.connect(relay_input_url) as ws:
+            # Send INPUT message
+            input_message = {
+                "type": "INPUT",
+                "input_id": input_id,
+                "to": self.address,
+                "prompt": prompt
+            }
+
+            await ws.send(json.dumps(input_message))
+
+            # Wait for OUTPUT
+            response_data = await asyncio.wait_for(ws.recv(), timeout=timeout)
+            response = json.loads(response_data)
+
+            # Return result
+            if response.get("type") == "OUTPUT" and response.get("input_id") == input_id:
+                return response.get("result", "")
+            elif response.get("type") == "ERROR":
+                raise ConnectionError(f"Agent error: {response.get('error')}")
+            else:
+                raise ConnectionError(f"Unexpected response: {response}")
+
+    def __repr__(self):
+        short = self.address[:12] + "..." if len(self.address) > 12 else self.address
+        return f"RemoteAgent({short})"
+
+
+def connect(address: str, relay_url: str = "wss://oo.openonion.ai/ws/announce") -> RemoteAgent:
+    """
+    Connect to a remote agent.
+
+    Args:
+        address: Agent's public key address (0x...)
+        relay_url: Relay server URL (default: production)
+
+    Returns:
+        RemoteAgent interface
+
+    Example:
+        >>> from connectonion import connect
+        >>> translator = connect("0x3d4017c3...")
+        >>> result = translator.input("Translate 'hello' to Spanish")
+    """
+    return RemoteAgent(address, relay_url)