connectonion 0.5.8__py3-none-any.whl

connectonion/tui/status_bar.py

@@ -0,0 +1,163 @@
+"""StatusBar - Powerline-style info bar with segments.
+
+Creates a professional terminal prompt bar like powerlevel10k.
+"""
+
+from dataclasses import dataclass
+from rich.text import Text
+
+
+# Powerline characters
+ARROW_RIGHT = ""  # U+E0B0 - requires powerline font
+ARROW_RIGHT_THIN = ""  # U+E0B1
+ARROW_LEFT = ""  # U+E0B2
+ARROW_LEFT_THIN = ""  # U+E0B3
+
+# Fallback for terminals without powerline fonts
+ARROW_FALLBACK = "▶"
+
+# Progress bar characters
+PROGRESS_FILLED = "█"
+PROGRESS_EMPTY = "░"
+
+
+@dataclass
+class ProgressSegment:
+    """A progress bar segment for StatusBar.
+
+    Usage:
+        from connectonion.tui import StatusBar, ProgressSegment
+
+        status = StatusBar([
+            ("🤖", "co/gemini-2.5-pro", "magenta"),
+            ProgressSegment(percent=78, bg_color="green"),
+        ])
+    """
+    percent: float  # 0-100, how much is USED
+    bg_color: str = "green"
+    width: int = 10
+    show_percent: bool = True
+
+    def render(self) -> str:
+        """Render progress bar text."""
+        pct = max(0, min(100, self.percent))
+        filled = int(self.width * pct / 100)
+        empty = self.width - filled
+        bar = PROGRESS_FILLED * filled + PROGRESS_EMPTY * empty
+        if self.show_percent:
+            return f"{bar} {int(pct)}%"
+        return bar
+
+
+class StatusBar:
+    """Powerline-style status bar with colored segments.
+
+    Supports both text segments and progress bar segments.
+
+    Usage:
+        from connectonion.tui import StatusBar, ProgressSegment
+
+        # Text segments only
+        bar = StatusBar([
+            ("🤖", "co/gemini-2.5-pro", "magenta"),
+            ("", "main", "blue"),
+        ])
+
+        # With progress bar for context window
+        bar = StatusBar([
+            ("🤖", "co/gemini-2.5-pro", "magenta"),
+            ProgressSegment(percent=78, bg_color="green"),
+        ])
+        console.print(bar.render())
+
+    Output (with powerline font):
+        🤖 co/gemini-2.5-pro  ███████░░░ 78%
+    """
+
+    def __init__(
+        self,
+        segments: list,
+        use_powerline: bool = True,
+    ):
+        """
+        Args:
+            segments: List of (icon, text, bg_color) tuples or ProgressSegment
+            use_powerline: Use powerline arrow chars (requires font)
+        """
+        self.segments = segments
+        self.use_powerline = use_powerline
+
+    def _get_bg_color(self, segment) -> str:
+        """Get background color from segment."""
+        if isinstance(segment, ProgressSegment):
+            return segment.bg_color
+        return segment[2]
+
+    def _render_segment_content(self, segment) -> str:
+        """Render segment content text."""
+        if isinstance(segment, ProgressSegment):
+            return f" {segment.render()} "
+        icon, text, _ = segment
+        return f" {icon} {text} " if icon else f" {text} "
+
+    def render(self) -> Text:
+        """Render the status bar."""
+        result = Text()
+
+        for i, segment in enumerate(self.segments):
+            bg_color = self._get_bg_color(segment)
+            content = self._render_segment_content(segment)
+
+            # Add segment with background
+            result.append(content, style=f"bold white on {bg_color}")
+
+            # Add arrow separator
+            if i < len(self.segments) - 1:
+                next_bg = self._get_bg_color(self.segments[i + 1])
+                if self.use_powerline:
+                    result.append(ARROW_RIGHT, style=f"{bg_color} on {next_bg}")
+                else:
+                    result.append(ARROW_FALLBACK, style=f"{bg_color} on {next_bg}")
+            else:
+                # Final arrow to terminal background
+                if self.use_powerline:
+                    result.append(ARROW_RIGHT, style=f"{bg_color}")
+                else:
+                    result.append(ARROW_FALLBACK, style=f"{bg_color}")
+
+        return result
+
+
+class SimpleStatusBar:
+    """Simpler status bar without powerline fonts.
+
+    Uses brackets and pipes instead of arrows.
+
+    Usage:
+        bar = SimpleStatusBar([
+            ("🤖", "co/gemini-2.5-pro", "magenta"),
+            ("📊", "50%", "green"),
+        ])
+        console.print(bar.render())
+
+    Output:
+        [🤖 co/gemini-2.5-pro] [📊 50%]
+    """
+
+    def __init__(self, segments: list[tuple[str, str, str]]):
+        self.segments = segments
+
+    def render(self) -> Text:
+        result = Text()
+
+        for i, (icon, text, color) in enumerate(self.segments):
+            if i > 0:
+                result.append(" ")
+
+            result.append("[", style="dim")
+            if icon:
+                result.append(f"{icon} ", style=color)
+            result.append(text, style=f"bold {color}")
+            result.append("]", style="dim")
+
+        return result

connectonion/usage.py

@@ -0,0 +1,161 @@
+"""
+Purpose: Token usage tracking and cost calculation for LLM calls
+LLM-Note:
+  Dependencies: pydantic | imported by [llm.py, agent.py]
+  Data flow: receives model name + token counts → returns cost in USD
+  Integration: exposes TokenUsage, MODEL_PRICING, MODEL_CONTEXT_LIMITS, calculate_cost(), get_context_limit()
+"""
+
+from pydantic import BaseModel
+
+
+class TokenUsage(BaseModel):
+    """Token usage from a single LLM call.
+
+    Uses Pydantic BaseModel for:
+    - Native JSON serialization via .model_dump()
+    - Type validation at runtime
+    - Future-proof API response compatibility
+    """
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cached_tokens: int = 0      # Tokens read from cache (subset of input_tokens)
+    cache_write_tokens: int = 0  # Tokens written to cache (Anthropic only)
+    cost: float = 0.0           # USD cost for this call
+
+
+# Pricing per 1M tokens (USD)
+# Format: {"input": $, "output": $, "cached": $, "cache_write": $}
+MODEL_PRICING = {
+    # OpenAI models - cached = 50% of input
+    "gpt-4o": {"input": 2.50, "output": 10.00, "cached": 1.25},
+    "gpt-4o-mini": {"input": 0.15, "output": 0.60, "cached": 0.075},
+    "gpt-4-turbo": {"input": 10.00, "output": 30.00, "cached": 5.00},
+    "o1": {"input": 15.00, "output": 60.00, "cached": 7.50},
+    "o1-mini": {"input": 3.00, "output": 12.00, "cached": 1.50},
+    "o1-preview": {"input": 15.00, "output": 60.00, "cached": 7.50},
+    "o3-mini": {"input": 1.10, "output": 4.40, "cached": 0.55},
+    "o4-mini": {"input": 1.10, "output": 4.40, "cached": 0.55},
+
+    # Anthropic Claude models - cached = 10% of input, cache_write = 125% of input
+    "claude-3-5-sonnet-20241022": {"input": 3.00, "output": 15.00, "cached": 0.30, "cache_write": 3.75},
+    "claude-3-5-sonnet-latest": {"input": 3.00, "output": 15.00, "cached": 0.30, "cache_write": 3.75},
+    "claude-3-5-haiku-20241022": {"input": 0.80, "output": 4.00, "cached": 0.08, "cache_write": 1.00},
+    "claude-3-5-haiku-latest": {"input": 0.80, "output": 4.00, "cached": 0.08, "cache_write": 1.00},
+    "claude-3-opus-20240229": {"input": 15.00, "output": 75.00, "cached": 1.50, "cache_write": 18.75},
+    "claude-3-sonnet-20240229": {"input": 3.00, "output": 15.00, "cached": 0.30, "cache_write": 3.75},
+    "claude-3-haiku-20240307": {"input": 0.25, "output": 1.25, "cached": 0.025, "cache_write": 0.3125},
+
+    # Claude 4 models
+    "claude-sonnet-4-20250514": {"input": 3.00, "output": 15.00, "cached": 0.30, "cache_write": 3.75},
+    "claude-opus-4-20250514": {"input": 15.00, "output": 75.00, "cached": 1.50, "cache_write": 18.75},
+
+    # Google Gemini models - cached = 25% of input (75% discount)
+    "gemini-3-pro-preview": {"input": 2.00, "output": 12.00, "cached": 0.50},
+    "gemini-3-pro-image-preview": {"input": 2.00, "output": 0.134},
+    "gemini-2.5-pro": {"input": 1.25, "output": 10.00, "cached": 0.3125},
+    "gemini-2.5-flash": {"input": 0.15, "output": 0.60, "cached": 0.0375},
+    "gemini-2.0-flash": {"input": 0.10, "output": 0.40, "cached": 0.025},
+    "gemini-1.5-pro": {"input": 1.25, "output": 5.00, "cached": 0.3125},
+    "gemini-1.5-flash": {"input": 0.075, "output": 0.30, "cached": 0.01875},
+}
+
+# Context window limits (tokens)
+MODEL_CONTEXT_LIMITS = {
+    # OpenAI
+    "gpt-4o": 128000,
+    "gpt-4o-mini": 128000,
+    "gpt-4-turbo": 128000,
+    "o1": 200000,
+    "o1-mini": 128000,
+    "o1-preview": 128000,
+    "o3-mini": 200000,
+    "o4-mini": 200000,
+
+    # Anthropic
+    "claude-3-5-sonnet-20241022": 200000,
+    "claude-3-5-sonnet-latest": 200000,
+    "claude-3-5-haiku-20241022": 200000,
+    "claude-3-5-haiku-latest": 200000,
+    "claude-3-opus-20240229": 200000,
+    "claude-3-sonnet-20240229": 200000,
+    "claude-3-haiku-20240307": 200000,
+    "claude-sonnet-4-20250514": 200000,
+    "claude-opus-4-20250514": 200000,
+
+    # Gemini
+    "gemini-3-pro-preview": 1000000,
+    "gemini-3-pro-image-preview": 65000,
+    "gemini-2.5-pro": 1000000,
+    "gemini-2.5-flash": 1000000,
+    "gemini-2.0-flash": 1000000,
+    "gemini-1.5-pro": 2000000,
+    "gemini-1.5-flash": 1000000,
+}
+
+# Default values for unknown models
+DEFAULT_PRICING = {"input": 1.00, "output": 3.00, "cached": 0.50}
+DEFAULT_CONTEXT_LIMIT = 128000
+
+
+def get_pricing(model: str) -> dict:
+    """Get pricing for a model, with fallback to default."""
+    # Try exact match
+    if model in MODEL_PRICING:
+        return MODEL_PRICING[model]
+
+    # Try prefix match (e.g., "gpt-4o-2024-08-06" -> "gpt-4o")
+    for known_model in MODEL_PRICING:
+        if model.startswith(known_model):
+            return MODEL_PRICING[known_model]
+
+    return DEFAULT_PRICING
+
+
+def get_context_limit(model: str) -> int:
+    """Get context limit for a model, with fallback to default."""
+    if model in MODEL_CONTEXT_LIMITS:
+        return MODEL_CONTEXT_LIMITS[model]
+
+    for known_model in MODEL_CONTEXT_LIMITS:
+        if model.startswith(known_model):
+            return MODEL_CONTEXT_LIMITS[known_model]
+
+    return DEFAULT_CONTEXT_LIMIT
+
+
+def calculate_cost(
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+    cached_tokens: int = 0,
+    cache_write_tokens: int = 0,
+) -> float:
+    """Calculate USD cost for token usage.
+
+    Args:
+        model: Model name
+        input_tokens: Total input tokens (includes cached)
+        output_tokens: Output/completion tokens
+        cached_tokens: Tokens read from cache (subset of input_tokens)
+        cache_write_tokens: Tokens written to cache (Anthropic)
+
+    Returns:
+        Cost in USD
+    """
+    pricing = get_pricing(model)
+
+    # Non-cached input tokens = total input - cached
+    non_cached_input = max(0, input_tokens - cached_tokens)
+
+    # Calculate costs (pricing is per 1M tokens)
+    input_cost = (non_cached_input / 1_000_000) * pricing["input"]
+    output_cost = (output_tokens / 1_000_000) * pricing["output"]
+    cached_cost = (cached_tokens / 1_000_000) * pricing.get("cached", pricing["input"] * 0.5)
+
+    # Cache write cost (Anthropic only)
+    cache_write_cost = 0.0
+    if cache_write_tokens > 0 and "cache_write" in pricing:
+        cache_write_cost = (cache_write_tokens / 1_000_000) * pricing["cache_write"]
+
+    return input_cost + output_cost + cached_cost + cache_write_cost

connectonion/useful_events_handlers/__init__.py

@@ -0,0 +1,16 @@
+"""
+Useful event handlers for ConnectOnion agents.
+
+Event handlers fire at specific points in the agent lifecycle.
+Use on_events parameter to register them with your agent.
+
+Usage:
+    from connectonion import Agent
+    from connectonion.useful_events_handlers import reflect
+
+    agent = Agent("assistant", on_events=[reflect])
+"""
+
+from .reflect import reflect
+
+__all__ = ['reflect']

connectonion/useful_events_handlers/reflect.py

@@ -0,0 +1,116 @@
+"""
+Reflect event handler - Adds reflection after tool execution.
+
+Fires ONCE after ALL tools in a batch complete (when LLM returns multiple tool_calls).
+Generates reasoning about what we learned and what to do next.
+
+This uses `after_tools` (not `after_each_tool`) intentionally because:
+1. Adding messages after EACH tool breaks Anthropic Claude's message ordering
+2. Reflecting once after all tools provides better context for next steps
+3. Fewer LLM calls = faster execution
+
+Usage:
+    from connectonion import Agent
+    from connectonion.useful_events_handlers import reflect
+
+    agent = Agent("assistant", tools=[search], on_events=[reflect])
+"""
+
+from pathlib import Path
+from typing import TYPE_CHECKING, List, Dict
+from ..events import after_tools
+from ..llm_do import llm_do
+
+if TYPE_CHECKING:
+    from ..agent import Agent
+
+# Path to reflect prompt (inside connectonion package for proper packaging)
+REFLECT_PROMPT = Path(__file__).parent.parent / "prompt_files" / "reflect.md"
+
+
+def _compress_messages(messages: List[Dict], tool_result_limit: int = 150) -> str:
+    """
+    Compress conversation messages with structure:
+    - USER messages → Keep FULL
+    - ASSISTANT tool_calls → Keep parameters FULL
+    - ASSISTANT text → Keep FULL
+    - TOOL results → Truncate to tool_result_limit chars
+    """
+    lines = []
+
+    for msg in messages:
+        role = msg['role']
+
+        if role == 'user':
+            lines.append(f"USER: {msg['content']}")
+
+        elif role == 'assistant':
+            if 'tool_calls' in msg:
+                tools = [f"{tc['function']['name']}({tc['function']['arguments']})"
+                         for tc in msg['tool_calls']]
+                lines.append(f"ASSISTANT: {', '.join(tools)}")
+            else:
+                lines.append(f"ASSISTANT: {msg['content']}")
+
+        elif role == 'tool':
+            result = msg['content']
+            if len(result) > tool_result_limit:
+                result = result[:tool_result_limit] + '...'
+            lines.append(f"TOOL: {result}")
+
+    return "\n".join(lines)
+
+
+@after_tools
+def reflect(agent: 'Agent') -> None:
+    """
+    Reflection after tool execution.
+
+    Fires ONCE after ALL tools in a batch complete. Generates reasoning about:
+    - What we learned from the most recent action
+    - What we should do next
+    """
+    trace = agent.current_session['trace'][-1]
+
+    if trace['type'] != 'tool_execution':
+        return
+
+    user_prompt = agent.current_session.get('user_prompt', '')
+    tool_name = trace['tool_name']
+    tool_args = trace['arguments']
+    status = trace['status']
+
+    conversation = _compress_messages(agent.current_session['messages'])
+
+    if status == 'success':
+        tool_result = trace['result']
+        prompt = f"""Context:
+{conversation}
+
+Current:
+User asked: {user_prompt}
+Action: {tool_name}({tool_args})
+Result: {str(tool_result)[:300]}"""
+    else:
+        error = trace.get('error', 'Unknown error')
+        prompt = f"""Context:
+{conversation}
+
+Current:
+User asked: {user_prompt}
+Action: {tool_name}({tool_args})
+Error: {error}"""
+
+    reasoning = llm_do(
+        prompt,
+        model="co/gemini-2.5-flash",
+        temperature=0.2,
+        system_prompt=REFLECT_PROMPT
+    )
+
+    agent.logger.print("[dim]/reflecting...[/dim]")
+
+    agent.current_session['messages'].append({
+        'role': 'assistant',
+        'content': f"🤔 {reasoning}"
+    })

connectonion/useful_plugins/__init__.py

@@ -0,0 +1,20 @@
+"""
+Purpose: Export pre-built plugins that extend agent behavior via event hooks
+LLM-Note:
+  Dependencies: imports from [re_act, image_result_formatter, shell_approval, gmail_plugin, calendar_plugin] | imported by [__init__.py main package] | re-exports plugins for agent consumption
+  Data flow: agent imports plugin → passes to Agent(plugins=[plugin]) → plugin event handlers fire on agent lifecycle events
+  State/Effects: no state | pure re-exports | plugins modify agent behavior at runtime
+  Integration: exposes re_act (ReAct prompting), image_result_formatter (base64 image handling), shell_approval (user confirmation for shell commands), gmail_plugin (Gmail OAuth flow), calendar_plugin (Google Calendar integration) | plugins are lists of event handlers
+  Errors: ImportError if underlying plugin dependencies not installed
+
+Pre-built plugins that can be easily imported and used across agents.
+"""
+
+from .re_act import re_act
+from .eval import eval
+from .image_result_formatter import image_result_formatter
+from .shell_approval import shell_approval
+from .gmail_plugin import gmail_plugin
+from .calendar_plugin import calendar_plugin
+
+__all__ = ['re_act', 'eval', 'image_result_formatter', 'shell_approval', 'gmail_plugin', 'calendar_plugin']

connectonion/useful_plugins/calendar_plugin.py

@@ -0,0 +1,163 @@
+"""
+Purpose: Human-in-the-loop approval plugin for Google Calendar write operations
+LLM-Note:
+  Dependencies: imports from [typing, events.before_each_tool, tui.pick, rich.console, rich.panel, rich.text] | imported by [useful_plugins/__init__.py] | tested by [tests/unit/test_calendar_plugin.py]
+  Data flow: before_each_tool → check_calendar_approval() checks if tool is create_event/create_meet/update_event/delete_event → displays event preview with Rich panel → pick() prompts for user approval → raises ValueError to cancel if rejected
+  State/Effects: blocks on user input | displays Rich-formatted event preview | raises exception to cancel tool execution | no file I/O | no network
+  Integration: exposes calendar_plugin list with [check_calendar_approval] handler | used via Agent(plugins=[calendar_plugin]) | works with GoogleCalendar tool
+  Performance: instant display | blocks on user input | no LLM calls
+  Errors: raises ValueError on rejection | keyboard interrupts handled gracefully
+
+Calendar plugin - Approval for Google Calendar operations.
+
+Usage:
+    from connectonion import Agent, GoogleCalendar
+    from connectonion.useful_plugins import calendar_plugin
+
+    calendar = GoogleCalendar()
+    agent = Agent("assistant", tools=[calendar], plugins=[calendar_plugin])
+"""
+
+from typing import TYPE_CHECKING
+from ..events import before_each_tool
+from ..tui import pick
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+if TYPE_CHECKING:
+    from ..agent import Agent
+
+_console = Console()
+
+# Calendar methods that create/modify/delete events
+WRITE_METHODS = ('create_event', 'create_meet', 'update_event', 'delete_event')
+
+
+@before_each_tool
+def check_calendar_approval(agent: 'Agent') -> None:
+    """Ask user approval before modifying calendar.
+
+    Raises:
+        ValueError: If user rejects the action
+    """
+    pending = agent.current_session.get('pending_tool')
+    if not pending:
+        return
+
+    tool_name = pending['name']
+    if tool_name not in WRITE_METHODS:
+        return
+
+    args = pending['arguments']
+
+    # Skip if all calendar actions auto-approved
+    if agent.current_session.get('calendar_approve_all', False):
+        return
+
+    preview = Text()
+
+    if tool_name == 'create_event':
+        title = args.get('title', '')
+        start = args.get('start_time', '')
+        end = args.get('end_time', '')
+        attendees = args.get('attendees', '')
+        location = args.get('location', '')
+        description = args.get('description', '')
+
+        preview.append("Title: ", style="bold cyan")
+        preview.append(f"{title}\n")
+        preview.append("Start: ", style="bold cyan")
+        preview.append(f"{start}\n")
+        preview.append("End: ", style="bold cyan")
+        preview.append(f"{end}\n")
+        if attendees:
+            preview.append("Attendees: ", style="bold yellow")
+            preview.append(f"{attendees} (will receive invite!)\n")
+        if location:
+            preview.append("Location: ", style="bold cyan")
+            preview.append(f"{location}\n")
+        if description:
+            preview.append("\n")
+            preview.append(description[:300])
+
+        action = "Create Event"
+
+    elif tool_name == 'create_meet':
+        title = args.get('title', '')
+        start = args.get('start_time', '')
+        end = args.get('end_time', '')
+        attendees = args.get('attendees', '')
+        description = args.get('description', '')
+
+        preview.append("Title: ", style="bold cyan")
+        preview.append(f"{title}\n")
+        preview.append("Start: ", style="bold cyan")
+        preview.append(f"{start}\n")
+        preview.append("End: ", style="bold cyan")
+        preview.append(f"{end}\n")
+        preview.append("Attendees: ", style="bold yellow")
+        preview.append(f"{attendees} (will receive Meet invite!)\n")
+        if description:
+            preview.append("\n")
+            preview.append(description[:300])
+
+        action = "Create Meeting"
+
+    elif tool_name == 'update_event':
+        event_id = args.get('event_id', '')
+        title = args.get('title', '')
+        start = args.get('start_time', '')
+        end = args.get('end_time', '')
+        attendees = args.get('attendees', '')
+
+        preview.append("Event ID: ", style="bold cyan")
+        preview.append(f"{event_id}\n")
+        if title:
+            preview.append("New Title: ", style="bold cyan")
+            preview.append(f"{title}\n")
+        if start:
+            preview.append("New Start: ", style="bold cyan")
+            preview.append(f"{start}\n")
+        if end:
+            preview.append("New End: ", style="bold cyan")
+            preview.append(f"{end}\n")
+        if attendees:
+            preview.append("New Attendees: ", style="bold yellow")
+            preview.append(f"{attendees} (will be notified!)\n")
+
+        action = "Update Event"
+
+    elif tool_name == 'delete_event':
+        event_id = args.get('event_id', '')
+
+        preview.append("Event ID: ", style="bold red")
+        preview.append(f"{event_id}\n")
+        preview.append("\n", style="bold red")
+        preview.append("This will permanently delete the event!", style="red")
+
+        action = "Delete Event"
+
+    _console.print()
+    _console.print(Panel(preview, title=f"[yellow]{action}[/yellow]", border_style="yellow"))
+
+    options = [f"Yes, {action.lower()}"]
+    options.append("Auto approve all calendar actions this session")
+    options.append("No, tell agent what I want")
+
+    choice = pick(f"Proceed with {action.lower()}?", options, console=_console)
+
+    if choice.startswith("Yes"):
+        return
+    elif choice == "Auto approve all calendar actions this session":
+        agent.current_session['calendar_approve_all'] = True
+        return
+    else:
+        feedback = input("What do you want the agent to do instead? ")
+        raise ValueError(f"User feedback: {feedback}")
+
+
+# Bundle as plugin
+calendar_plugin = [
+    check_calendar_approval,
+]