connectonion 0.6.2__py3-none-any.whl → 0.6.4__py3-none-any.whl

connectonion/docs/useful_plugins/README.md

@@ -0,0 +1,160 @@
+# Built-in Plugins
+
+Pre-built plugins that extend agent behavior via event hooks.
+
+## Quick Reference
+
+| Plugin | Purpose | Import |
+|--------|---------|--------|
+| [re_act](re_act.md) | ReAct reasoning pattern | `from connectonion.useful_plugins import re_act` |
+| [eval](eval.md) | Task evaluation/debugging | `from connectonion.useful_plugins import eval` |
+| [system_reminder](system_reminder.md) | Inject contextual guidance | `from connectonion.useful_plugins import system_reminder` |
+| [image_result_formatter](image_result_formatter.md) | Format images for vision | `from connectonion.useful_plugins import image_result_formatter` |
+| [shell_approval](shell_approval.md) | Shell command approval | `from connectonion.useful_plugins import shell_approval` |
+| [gmail_plugin](gmail_plugin.md) | Gmail OAuth flow | `from connectonion.useful_plugins import gmail_plugin` |
+| [calendar_plugin](calendar_plugin.md) | Calendar OAuth flow | `from connectonion.useful_plugins import calendar_plugin` |
+
+## Usage Pattern
+
+```python
+from connectonion import Agent
+from connectonion.useful_plugins import re_act, eval
+
+agent = Agent(
+    "assistant",
+    tools=[search],
+    plugins=[re_act, eval]  # List of plugins
+)
+```
+
+## Customizing Plugins
+
+Need to modify a built-in plugin? Copy it to your project:
+
+```bash
+# Copy plugin source to ./plugins/
+co copy re_act
+
+# Copy multiple plugins
+co copy re_act shell_approval
+```
+
+Then import from your local copy:
+
+```python
+# Before (from package)
+from connectonion.useful_plugins import re_act
+
+# After (from your copy)
+from plugins.re_act import re_act  # Customize freely!
+```
+
+See [co copy](../cli/copy.md) for full details.
+
+## Categories
+
+### Reasoning
+- **re_act** - Plan before acting, reflect after tools
+
+### Debugging
+- **eval** - Generate expected outcomes, evaluate completion
+
+### Guidance
+- **system_reminder** - Inject contextual reminders into tool results
+
+### Media
+- **image_result_formatter** - Convert base64 images for vision models
+
+### Security
+- **shell_approval** - Require approval for shell commands
+
+### OAuth
+- **gmail_plugin** - Handle Gmail authentication flow
+- **calendar_plugin** - Handle Calendar authentication flow
+
+## Event Lifecycle
+
+Understanding when events fire is key to writing plugins.
+
+```
+User Input
+    │
+    ▼
+┌─────────────────────────────────────────────────────┐
+│  after_user_input                                   │
+│  (re_act: plan_task, eval: generate_expected)       │
+└─────────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────── ITERATION LOOP ──────────────────┐
+│                                                     │
+│  before_llm → LLM Call → after_llm                  │
+│                   │                                 │
+│                   ▼                                 │
+│        ┌─────────────────────┐                      │
+│        │ Tool Calls (if any) │                      │
+│        └─────────────────────┘                      │
+│                   │                                 │
+│                   ▼                                 │
+│  ┌─────────────────────────────────────────────┐    │
+│  │ before_tools (fires ONCE before all tools)  │    │
+│  └─────────────────────────────────────────────┘    │
+│                   │                                 │
+│                   ▼                                 │
+│  ┌─────────────────────────────────────────────┐    │
+│  │ For EACH tool in parallel:                  │    │
+│  │   before_each_tool → Execute → after_each_tool  │
+│  │   (shell_approval)         (logging only!)      │
+│  └─────────────────────────────────────────────┘    │
+│                   │                                 │
+│                   ▼                                 │
+│  ┌─────────────────────────────────────────────┐    │
+│  │ after_tools (fires ONCE after ALL tools)    │    │
+│  │ (re_act: reflect, image_result_formatter)   │    │
+│  │ ⚠️  ONLY place safe to modify messages       │    │
+│  └─────────────────────────────────────────────┘    │
+│                   │                                 │
+│           Continue or Exit Loop                     │
+└─────────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────────────────────┐
+│  on_complete                                        │
+│  (eval: evaluate_completion)                        │
+└─────────────────────────────────────────────────────┘
+```
+
+### Key Distinction
+
+- **`after_each_tool`**: Fires for EACH tool individually. Use for logging, monitoring, side effects. **DO NOT modify messages here.**
+- **`after_tools`**: Fires ONCE after ALL tools complete. **ONLY place safe to modify messages.**
+
+### Why This Matters
+
+LLM APIs require tool results to match tool calls exactly. If you modify messages in `after_each_tool`, you'll break the tool_call_id sequence.
+
+```
+❌ WRONG - modifying messages in after_each_tool:
+tool_1 result → modify messages → tool_2 result → API ERROR!
+
+✅ CORRECT - modifying messages in after_tools:
+tool_1 result → tool_2 result → tool_3 result → after_tools → modify messages → OK
+```
+
+**Rule:** If your plugin modifies `agent.current_session['messages']`, use `after_tools`.
+
+### Error You'll See If You Get This Wrong
+
+```
+BadRequestError: 400 An assistant message with 'tool_calls' must be
+followed by tool messages responding to each 'tool_call_id'.
+The following tool_call_ids did not have response messages: call_xxx
+```
+
+If you see this error, check if any plugin is modifying messages in `after_each_tool` - move that logic to `after_tools`.
+
+Example: If LLM calls 3 tools in one round:
+- `before_tools` fires 1 time
+- `before_each_tool` fires 3 times (logging only!)
+- `after_each_tool` fires 3 times (logging only!)
+- `after_tools` fires 1 time (safe to modify messages)

connectonion/docs/useful_plugins/calendar_plugin.md

@@ -0,0 +1,68 @@
+# calendar_plugin
+
+Approval for Google Calendar operations.
+
+## Quick Start
+
+```python
+from connectonion import Agent, GoogleCalendar
+from connectonion.useful_plugins import calendar_plugin
+
+calendar = GoogleCalendar()
+agent = Agent("assistant", tools=[calendar], plugins=[calendar_plugin])
+
+agent.input("Schedule a meeting tomorrow at 2pm")
+# ┌─ Create Event ──────────────────┐
+# │ Title: Meeting                  │
+# │ Start: 2024-01-02 14:00         │
+# │ End: 2024-01-02 15:00           │
+# │ Attendees: alice@example.com    │
+# └─────────────────────────────────┘
+# Proceed with create event?
+```
+
+## Protected Operations
+
+Requires approval for:
+- `create_event` - Create new events
+- `create_meet` - Create Google Meet meetings
+- `update_event` - Modify existing events
+- `delete_event` - Delete events
+
+## Approval Options
+
+- **Yes, {action}** - Proceed once
+- **Auto approve all calendar actions** - Auto-approve for session
+- **No, tell agent what I want** - Provide feedback
+
+## Events
+
+| Handler | Event | Purpose |
+|---------|-------|---------|
+| `check_calendar_approval` | `before_each_tool` | Prompt approval before action |
+
+## Session Data
+
+- `agent.current_session['calendar_approve_all']` - Auto-approve flag
+
+## Warnings
+
+The plugin highlights when attendees will be notified:
+```
+Attendees: alice@example.com (will receive invite!)
+```
+
+## Customizing
+
+Need to modify calendar_plugin's behavior? Copy the source to your project:
+
+```bash
+co copy calendar_plugin
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion.useful_plugins import calendar_plugin  # Before
+from plugins.calendar_plugin import calendar_plugin        # After - customize freely!
+```

connectonion/docs/useful_plugins/eval.md

@@ -0,0 +1,89 @@
+# eval
+
+Debug and test AI agent prompts and tools during development.
+
+## Quick Start
+
+```python
+from connectonion import Agent
+from connectonion.useful_plugins import eval
+
+agent = Agent("assistant", tools=[search], plugins=[eval])
+
+agent.input("Search for Python docs")
+# ... agent executes ...
+# /evaluating...
+# ✓ Task completed successfully
+```
+
+## How It Works
+
+The plugin hooks into two lifecycle events:
+
+1. **`after_user_input`**: Generates expected outcome (if not already set)
+2. **`on_complete`**: Evaluates if task completed correctly
+
+### Why `on_complete`?
+
+The evaluation needs to see the **entire execution** - all iterations, all tool calls, and the final response.
+
+```
+User Input
+    ↓
+📝 Generate Expected (after_user_input)
+    ↓
+┌─────────────────── ITERATIONS ──────────────────┐
+│ LLM → Tools → LLM → Tools → ... → Final Response│
+└─────────────────────────────────────────────────┘
+    ↓
+✓ Evaluate (on_complete) - sees full trace + result
+```
+
+The `on_complete` event fires once after the agent finishes all iterations
+
+## Events
+
+| Handler | Event | Purpose |
+|---------|-------|---------|
+| `generate_expected` | `after_user_input` | Generate expected outcome |
+| `evaluate_completion` | `on_complete` | Evaluate actual vs expected |
+
+## Combine with re_act
+
+Best used with re_act for full debugging:
+
+```python
+from connectonion.useful_plugins import re_act, eval
+
+agent = Agent("assistant", tools=[search], plugins=[re_act, eval])
+# re_act sets expected during planning
+# eval evaluates completion against that expected
+```
+
+## Session Data
+
+The plugin stores:
+- `agent.current_session['expected']` - Expected outcome
+- `agent.current_session['evaluation']` - Evaluation result
+
+## When to Use
+
+- Testing new prompts or tools
+- Debugging agent behavior
+- Validating task completion
+- Development and experimentation
+
+## Customizing
+
+Need to modify eval's behavior? Copy the source to your project:
+
+```bash
+co copy eval
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion.useful_plugins import eval  # Before
+from plugins.eval import eval                    # After - customize freely!
+```

connectonion/docs/useful_plugins/gmail_plugin.md

@@ -0,0 +1,68 @@
+# gmail_plugin
+
+Email approval and CRM sync for Gmail operations.
+
+## Quick Start
+
+```python
+from connectonion import Agent, Gmail
+from connectonion.useful_plugins import gmail_plugin
+
+gmail = Gmail()
+agent = Agent("assistant", tools=[gmail], plugins=[gmail_plugin])
+
+agent.input("Send email to alice@example.com")
+# ┌─ Email to Send ─────────────────┐
+# │ To: alice@example.com           │
+# │ Subject: Hello                  │
+# │                                 │
+# │ Message body...                 │
+# └─────────────────────────────────┘
+# Send this email?
+```
+
+## Features
+
+1. **Email Approval** - Preview and approve before sending
+2. **CRM Sync** - Auto-update contact's last_contact date
+
+## Approval Options
+
+- **Yes, send it** - Send once
+- **Auto approve emails to '{recipient}'** - Auto-approve this recipient
+- **Auto approve all replies this session** - Auto-approve replies
+- **Auto approve all emails this session** - Auto-approve everything
+
+## Events
+
+| Handler | Event | Purpose |
+|---------|-------|---------|
+| `check_email_approval` | `before_each_tool` | Prompt approval before send |
+| `sync_crm_after_send` | `after_each_tool` | Update CRM after send |
+
+## Session Data
+
+- `agent.current_session['gmail_approved_recipients']` - Set of approved recipients
+- `agent.current_session['gmail_approve_replies']` - Auto-approve replies flag
+- `agent.current_session['gmail_approve_all']` - Auto-approve all flag
+
+## CRM Integration
+
+After sending, the plugin auto-updates:
+- `last_contact` → Today's date
+- `next_contact_date` → Cleared
+
+## Customizing
+
+Need to modify gmail_plugin's behavior? Copy the source to your project:
+
+```bash
+co copy gmail_plugin
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion.useful_plugins import gmail_plugin  # Before
+from plugins.gmail_plugin import gmail_plugin            # After - customize freely!
+```

connectonion/docs/useful_plugins/image_result_formatter.md

@@ -0,0 +1,74 @@
+# image_result_formatter
+
+Automatically formats base64 image results for vision models.
+
+## Quick Start
+
+```python
+from connectonion import Agent
+from connectonion.useful_plugins import image_result_formatter
+
+agent = Agent("assistant", tools=[take_screenshot], plugins=[image_result_formatter])
+
+agent.input("Take a screenshot and describe what you see")
+# 🖼️  Formatted 'take_screenshot' result as image
+# Agent can now see and analyze the image visually
+```
+
+## How It Works
+
+When a tool returns base64 encoded image data:
+
+1. Detects base64 image in tool result
+2. Converts to OpenAI vision format
+3. Allows LLM to see image visually (not as text)
+
+## Supported Formats
+
+- PNG
+- JPEG/JPG
+- WebP
+- GIF
+
+## Detection Patterns
+
+The plugin detects:
+
+```python
+# Data URL format
+"data:image/png;base64,iVBORw0KGgo..."
+
+# Plain base64 (defaults to PNG)
+"iVBORw0KGgoAAAANSUhEUgAA..."
+```
+
+## Events
+
+| Handler | Event | Purpose |
+|---------|-------|---------|
+| `_format_image_result` | `after_tools` | Format base64 images after all tools complete |
+
+Uses `after_tools` because it modifies messages (see [Event Lifecycle](README.md#why-this-matters)).
+
+## Use Cases
+
+- Screenshot tools
+- Image generation tools
+- Camera/webcam capture
+- PDF to image conversion
+- Any tool returning visual data
+
+## Customizing
+
+Need to modify image_result_formatter's behavior? Copy the source to your project:
+
+```bash
+co copy image_result_formatter
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion.useful_plugins import image_result_formatter  # Before
+from plugins.image_result_formatter import image_result_formatter  # After
+```

connectonion/docs/useful_plugins/re_act.md

@@ -0,0 +1,86 @@
+# re_act
+
+ReAct (Reason + Act) plugin - Adds planning and reflection to agents.
+
+## Quick Start
+
+```python
+from connectonion import Agent
+from connectonion.useful_plugins import re_act
+
+agent = Agent("assistant", tools=[search], plugins=[re_act])
+
+agent.input("Search for Python tutorials")
+# /planning...
+# 💭 Will search for Python tutorials first.
+# ... tool executes ...
+# /reflecting...
+# 🤔 Found Python basics, task complete.
+```
+
+## How It Works
+
+The plugin hooks into two points in the agent lifecycle:
+
+1. **`after_user_input`**: Plans what to do (💭)
+2. **`after_tools`**: Reflects on results and plans next step (🤔)
+
+### Why `after_tools`?
+
+Each LLM call may trigger **multiple tools in parallel**. The reflection needs to see ALL tool results before deciding next steps.
+
+```
+User Input
+    ↓
+💭 Plan (after_user_input)
+    ↓
+LLM decides to call 3 tools
+    ↓
+┌─────────────────────────────────────┐
+│ tool_1 executes ──┐                 │
+│ tool_2 executes ──┼── all complete  │
+│ tool_3 executes ──┘                 │
+└─────────────────────────────────────┘
+    ↓
+🤔 Reflect (after_tools) - sees all 3 results
+    ↓
+LLM decides next action or responds
+```
+
+If we used `after_each_tool`, reflection would fire 3 times with partial information.
+
+## Events
+
+| Handler | Event | Purpose |
+|---------|-------|---------|
+| `plan_task` | `after_user_input` | Generate initial plan |
+| `reflect` | `after_tools` | Reflect on tool results |
+
+## Combine with eval
+
+For debugging, combine with the eval plugin:
+
+```python
+from connectonion.useful_plugins import re_act, eval
+
+agent = Agent("assistant", tools=[search], plugins=[re_act, eval])
+# re_act provides plan as expected outcome
+# eval evaluates if task completed correctly
+```
+
+## Customizing
+
+Need to modify re_act's behavior? Copy the source to your project:
+
+```bash
+co copy re_act
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion.useful_plugins import re_act  # Before
+from plugins.re_act import re_act                  # After - customize freely!
+```
+
+The plan is stored in `agent.current_session['expected']` and can be used by other plugins.

connectonion/docs/useful_plugins/shell_approval.md

@@ -0,0 +1,69 @@
+# shell_approval
+
+Prompts for user approval before executing shell commands.
+
+## Quick Start
+
+```python
+from connectonion import Agent, Shell
+from connectonion.useful_plugins import shell_approval
+
+shell = Shell()
+agent = Agent("assistant", tools=[shell], plugins=[shell_approval])
+
+agent.input("Clean up temp files")
+# ┌─ Shell Command ─────────────────┐
+# │ rm -rf /tmp/test                │
+# └─────────────────────────────────┘
+# Execute this command?
+#   ❯ Yes, execute
+#     Auto approve 'rm' in this session
+#     No, tell agent what I want
+```
+
+## Safe Commands (No Approval)
+
+Read-only commands are auto-approved:
+
+```
+ls, ll, cat, head, tail, less, more
+grep, rg, find, fd, which, whereis
+file, stat, wc, pwd, echo, date
+whoami, id, env, uname, hostname
+df, du, free, ps, top, tree
+git status, git log, git diff, git show
+npm list, pip list, python --version
+```
+
+## Approval Options
+
+When prompted, you can:
+
+1. **Yes, execute** - Run once
+2. **Auto approve '{cmd}'** - Auto-approve this command type for session
+3. **No, tell agent what I want** - Provide feedback
+
+## Events
+
+| Handler | Event | Purpose |
+|---------|-------|---------|
+| `_check_approval` | `before_each_tool` | Check and prompt for approval |
+
+## Session Data
+
+- `agent.current_session['shell_approved_cmds']` - Set of auto-approved command types
+
+## Customizing
+
+Need to modify shell_approval's behavior? Copy the source to your project:
+
+```bash
+co copy shell_approval
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion.useful_plugins import shell_approval  # Before
+from plugins.shell_approval import shell_approval          # After - customize freely!
+```