connectonion 0.5.8__py3-none-any.whl

connectonion/prompt_files/react_evaluate.md

@@ -0,0 +1,11 @@
+You are evaluating whether a task is complete.
+
+Given the user's original request and what was done, determine:
+1. Is the task truly complete?
+2. If not, what's still missing?
+
+Be honest and critical. Don't say "complete" if important parts are missing.
+
+Respond in ONE sentence:
+- If complete: "Task complete: [brief summary of what was achieved]"
+- If incomplete: "Not done yet: [what's still needed]"

connectonion/prompt_files/react_plan.md

@@ -0,0 +1,16 @@
+# ReAct Planning
+
+You are a planning assistant. When a user gives a task, think about it briefly.
+
+## Guidelines
+
+- Keep it SHORT: 1-2 sentences max
+- Focus on: What needs to be done and which tools to use
+- Be practical and actionable
+
+## Examples
+
+- "Need to check emails first, then reply to the urgent ones."
+- "Will search for the file, then read its contents."
+- "Should fetch the API data and analyze the response."
+- "Let me check the database for user info, then format the report."

connectonion/prompt_files/reflect.md

@@ -0,0 +1,22 @@
+# Reflect
+
+You are a reflection assistant. After each tool execution, provide a brief one-sentence reflection.
+
+## Guidelines
+
+- Keep it SHORT: One sentence only
+- Focus on: What happened + What's next
+- Be practical and actionable
+- No verbose explanations
+
+## Examples
+
+Success cases:
+- "Got 5 emails, let's check the first one for details."
+- "Contact updated, now searching for related conversations."
+- "File created successfully, running tests next."
+
+Error cases:
+- "Permission denied, need to check file ownership."
+- "API rate limited, waiting before retry."
+- "Invalid email format, asking user for correct address."

connectonion/prompts.py

@@ -0,0 +1,144 @@
+"""
+Purpose: Load and validate system prompts from files or strings with intelligent path detection
+LLM-Note:
+  Dependencies: imports from [os, warnings, pathlib, typing] | imported by [agent.py] | no dedicated tests found
+  Data flow: receives system_prompt: Union[str, Path, None] from Agent.__init__ → checks if None (returns DEFAULT_PROMPT) → checks if Path object (reads file) → checks if str exists as file (reads) → warns if looks like file but doesn't exist → returns literal string
+  State/Effects: reads text files if path provided | emits UserWarning if path looks like file but doesn't exist | no writes or global state
+  Integration: exposes load_system_prompt(prompt), DEFAULT_PROMPT constant | used by Agent to load system prompts from various sources | supports .md, .txt, .prompt file extensions | Path objects enforce file must exist
+  Performance: file I/O only when path provided | heuristic checks (file extension, path separators) are fast string operations
+  Errors: raises FileNotFoundError if Path doesn't exist | raises ValueError if Path is not a file or file is empty | raises ValueError if file not UTF-8 | warns (doesn't fail) for str that looks like missing file
+"""
+
+import os
+import warnings
+from pathlib import Path
+from typing import Union
+
+
+DEFAULT_PROMPT = "You are a helpful assistant that can use tools to complete tasks."
+
+
+def _looks_like_file_path(text: str) -> bool:
+    """Check if a string looks like a file path rather than prompt text."""
+    # Check for file extensions
+    has_file_extension = '.' in text and text.split('.')[-1] in ['md', 'txt', 'prompt']
+    # Check for path separators
+    has_path_separator = '/' in text or '\\' in text
+
+    return has_file_extension or has_path_separator
+
+
+def _warn_if_missing_file(prompt: str) -> None:
+    """Warn user if prompt looks like a file path but doesn't exist."""
+    if _looks_like_file_path(prompt) and not os.path.exists(prompt):
+        abs_path = os.path.abspath(prompt)
+        cwd = os.getcwd()
+
+        # Suggest better approach
+        suggestion = ""
+        if '/' in prompt or '\\' in prompt:
+            # Has path separators, suggest Path object
+            suggestion = f"\n  Tip: Use Path object for explicit file loading: Path('{prompt}')"
+        else:
+            # Just filename, suggest correct directory or Path
+            suggestion = (f"\n  Tip: Either run from the correct directory, or use absolute path:\n"
+                         f"       Path(__file__).parent / '{prompt}'")
+
+        warnings.warn(
+            f"'{prompt}' looks like a file path but doesn't exist.\n"
+            f"  Looked in: {abs_path}\n"
+            f"  Current directory: {cwd}\n"
+            f"  Treating as literal prompt text."
+            f"{suggestion}",
+            UserWarning,
+            stacklevel=3
+        )
+
+
+def load_system_prompt(prompt: Union[str, Path, None]) -> str:
+    """
+    Load system prompt from various sources.
+    
+    Args:
+        prompt: Can be:
+            - None: Returns default prompt
+            - str: Either a file path (if file exists) or literal prompt text
+            - Path: Path object to a text file
+            
+    Returns:
+        str: The loaded system prompt
+        
+    Examples:
+        >>> load_system_prompt(None)
+        'You are a helpful assistant that can use tools to complete tasks.'
+        
+        >>> load_system_prompt("You are a helpful assistant")
+        'You are a helpful assistant'
+        
+        >>> load_system_prompt("prompts/assistant.md")  # If file exists
+        # Returns content from the file
+        
+        >>> load_system_prompt(Path("prompts/assistant"))  # Any text file
+        # Returns content from the file
+        
+    Raises:
+        FileNotFoundError: If a Path object points to non-existent file
+        ValueError: If file is empty or not valid UTF-8 text
+    """
+    if prompt is None:
+        return DEFAULT_PROMPT
+    
+    if isinstance(prompt, Path):
+        # Explicit Path object - must exist
+        if not prompt.exists():
+            raise FileNotFoundError(f"Prompt file not found: {prompt}")
+        if not prompt.is_file():
+            raise ValueError(f"Path is not a file: {prompt}")
+        return _read_text_file(prompt)
+    
+    if isinstance(prompt, str):
+        # Check if it's an existing file
+        if os.path.exists(prompt) and os.path.isfile(prompt):
+            return _read_text_file(Path(prompt))
+
+        # Warn if it looks like a missing file
+        _warn_if_missing_file(prompt)
+
+        # Treat as literal prompt text
+        return prompt
+    
+    raise TypeError(f"Invalid prompt type: {type(prompt).__name__}. Expected str, Path, or None.")
+
+
+def _read_text_file(path: Path) -> str:
+    """
+    Read content from a text file.
+    
+    Args:
+        path: Path to the text file
+        
+    Returns:
+        str: File content
+        
+    Raises:
+        ValueError: If file is empty or not valid UTF-8
+    """
+    try:
+        content = path.read_text(encoding='utf-8').strip()
+        if not content:
+            raise ValueError(f"Prompt file '{path}' is empty. Please add content or use a different file.")
+        return content
+    except UnicodeDecodeError:
+        raise ValueError(
+            f"File '{path}' is not a valid UTF-8 text file. "
+            f"System prompts must be text files."
+        )
+    except ValueError:
+        # Re-raise ValueError (empty file)
+        raise
+    except PermissionError:
+        # Re-raise PermissionError
+        raise
+    except Exception as e:
+        # Catch any other unexpected errors
+        raise RuntimeError(f"Error reading prompt file '{path}': {e}")

connectonion/relay.py

@@ -0,0 +1,200 @@
+"""
+Purpose: WebSocket relay client for agent-to-agent communication via central relay server using INPUT/OUTPUT protocol
+LLM-Note:
+  Dependencies: imports from [json, asyncio, typing, websockets] | imported by [host.py] | tested by [tests/test_relay.py]
+  Data flow: host() with relay_url → connect(relay_url) → WebSocket established → send_announce(ws, announce_msg) → serve_loop() → wait_for_task(ws) receives INPUT message from relay → task_handler(prompt) executes → send OUTPUT response via WebSocket → heartbeat re-announces every 60s
+  State/Effects: maintains WebSocket connection to relay | reads incoming JSON messages (INPUT type) | writes outgoing JSON messages (OUTPUT type) | prints status to stdout | asyncio timeout for heartbeat | no file I/O
+  Integration: exposes connect(relay_url), send_announce(ws, msg), wait_for_task(ws, timeout), send_response(ws, input_id, result), serve_loop(ws, announce_msg, task_handler, heartbeat_interval) | used by host() with relay_url to make agent discoverable on relay network | task_handler is async function (prompt: str) -> str | Protocol: INPUT/OUTPUT messages (not TASK/RESPONSE)
+  Performance: async/await non-blocking I/O | heartbeat_interval=60s default (configurable) | timeout-based heartbeat scheduling | WebSocket maintains persistent connection
+  Errors: let it crash - ImportError if websockets missing | asyncio.TimeoutError used for heartbeat timing | websockets.ConnectionClosed exits serve loop gracefully
+
+WebSocket relay client functions.
+
+Simple async functions for connecting to relay and exchanging messages using INPUT/OUTPUT protocol.
+No classes needed - just stateless functions operating on websocket connections.
+"""
+
+import json
+import asyncio
+from typing import Dict, Any
+import websockets
+
+
+async def connect(relay_url: str = "wss://oo.openonion.ai/ws/announce"):
+    """
+    Connect to relay WebSocket endpoint.
+
+    Args:
+        relay_url: WebSocket URL for relay (default: production relay)
+
+    Returns:
+        WebSocket connection object
+
+    Example:
+        >>> ws = await connect()
+        >>> # Now use ws for sending/receiving
+    """
+    return await websockets.connect(relay_url)
+
+
+async def send_announce(websocket, announce_message: Dict[str, Any]):
+    """
+    Send ANNOUNCE message through WebSocket.
+
+    Args:
+        websocket: WebSocket connection from connect()
+        announce_message: Dict from create_announce_message()
+
+    Note:
+        Server responds with error message only if something went wrong.
+        No response = success (per protocol spec)
+
+    Example:
+        >>> from . import announce, address
+        >>> addr = address.load()
+        >>> msg = announce.create_announce_message(addr, "My agent", [])
+        >>> await send_announce(ws, msg)
+    """
+    message_json = json.dumps(announce_message)
+    await websocket.send(message_json)
+
+
+async def wait_for_task(websocket, timeout: float = None) -> Dict[str, Any]:
+    """
+    Wait for next INPUT message from relay.
+
+    Args:
+        websocket: WebSocket connection from connect()
+        timeout: Optional timeout in seconds (None = wait forever)
+
+    Returns:
+        INPUT message dict:
+        {
+            "type": "INPUT",
+            "input_id": "abc123...",
+            "prompt": "Translate hello to Spanish",
+            "from_address": "0x..."
+        }
+
+    Raises:
+        asyncio.TimeoutError: If timeout expires
+        websockets.exceptions.ConnectionClosed: If connection lost
+
+    Example:
+        >>> task = await wait_for_task(ws)
+        >>> print(task["prompt"])
+        Translate hello to Spanish
+    """
+    if timeout:
+        data = await asyncio.wait_for(websocket.recv(), timeout=timeout)
+    else:
+        data = await websocket.recv()
+
+    message = json.loads(data)
+    return message
+
+
+async def send_response(
+    websocket,
+    input_id: str,
+    result: str,
+    success: bool = True
+):
+    """
+    Send output response back to relay.
+
+    Args:
+        websocket: WebSocket connection from connect()
+        input_id: ID from INPUT message
+        result: Agent's response/output
+        success: Whether task succeeded (default True)
+
+    Example:
+        >>> task = await wait_for_task(ws)
+        >>> result = agent.input(task["prompt"])
+        >>> await send_response(ws, task["input_id"], result)
+    """
+    response_message = {
+        "type": "OUTPUT",
+        "input_id": input_id,
+        "result": result,
+        "success": success
+    }
+
+    message_json = json.dumps(response_message)
+    await websocket.send(message_json)
+
+
+async def serve_loop(
+    websocket,
+    announce_message: Dict[str, Any],
+    task_handler,
+    heartbeat_interval: int = 60
+):
+    """
+    Main serving loop for agent.
+
+    This handles:
+    - Initial ANNOUNCE
+    - Periodic heartbeat ANNOUNCE (every 60s)
+    - Receiving and processing TASK messages
+    - Sending responses
+
+    Args:
+        websocket: WebSocket connection from connect()
+        announce_message: ANNOUNCE message dict (will be re-sent for heartbeat)
+        task_handler: Async function that takes (prompt: str) -> str
+        heartbeat_interval: Seconds between heartbeat ANNOUNCEs (default 60)
+
+    Example:
+        >>> async def handler(prompt):
+        ...     return agent.input(prompt)
+        >>> await serve_loop(ws, announce_msg, handler)
+    """
+    # Send initial ANNOUNCE
+    await send_announce(websocket, announce_message)
+    print(f"✓ Announced to relay: {announce_message['address'][:12]}...")
+
+    # Track last heartbeat time
+    last_heartbeat = asyncio.get_event_loop().time()
+
+    # Main loop
+    while True:
+        try:
+            # Wait for message with timeout to allow heartbeat
+            task = await wait_for_task(websocket, timeout=heartbeat_interval)
+
+            # Handle INPUT message
+            if task.get("type") == "INPUT":
+                print(f"→ Received input: {task['input_id'][:8]}...")
+
+                # Process with handler
+                result = await task_handler(task["prompt"])
+
+                # Send OUTPUT response
+                output_message = {
+                    "type": "OUTPUT",
+                    "input_id": task["input_id"],
+                    "result": result
+                }
+                await websocket.send(json.dumps(output_message))
+                print(f"✓ Sent output: {task['input_id'][:8]}...")
+
+            elif task.get("type") == "ERROR":
+                print(f"✗ Error from relay: {task.get('error')}")
+
+        except asyncio.TimeoutError:
+            # Time for heartbeat ANNOUNCE
+            # Update timestamp in message
+            announce_message["timestamp"] = int(asyncio.get_event_loop().time())
+
+            # Need to re-sign with new timestamp
+            # For now, just send without updating signature
+            # TODO: Re-sign message with new timestamp
+            await send_announce(websocket, announce_message)
+            print("♥ Sent heartbeat")
+            last_heartbeat = asyncio.get_event_loop().time()
+
+        except websockets.exceptions.ConnectionClosed:
+            print("✗ Connection to relay closed")
+            break