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

connectonion/docs/useful_tools/README.md

@@ -0,0 +1,81 @@
+# Built-in Tools
+
+Pre-built tools for common agent tasks.
+
+## Quick Reference
+
+| Tool | Purpose | Import |
+|------|---------|--------|
+| [Shell](shell.md) | Execute shell commands | `from connectonion import Shell` |
+| [DiffWriter](diff_writer.md) | Edit files with diffs | `from connectonion import DiffWriter` |
+| [TodoList](todo_list.md) | Track task progress | `from connectonion import TodoList` |
+| [WebFetch](web_fetch.md) | Fetch web content | `from connectonion import WebFetch` |
+| [Gmail](gmail.md) | Gmail integration | `from connectonion import Gmail` |
+| [get_emails](get_emails.md) | Email parsing utilities | `from connectonion import get_emails` |
+| [send_email](send_email.md) | Send emails via API | `from connectonion import send_email` |
+| [Outlook](outlook.md) | Outlook integration | `from connectonion import Outlook` |
+| [GoogleCalendar](google_calendar.md) | Google Calendar | `from connectonion import GoogleCalendar` |
+| [MicrosoftCalendar](microsoft_calendar.md) | Microsoft Calendar | `from connectonion import MicrosoftCalendar` |
+| [Memory](memory.md) | Persistent memory | `from connectonion import Memory` |
+| [Terminal](terminal.md) | Interactive terminal | `from connectonion import Terminal` |
+| [SlashCommand](slash_command.md) | Custom commands | `from connectonion import SlashCommand` |
+
+## Usage Pattern
+
+```python
+from connectonion import Agent, Shell, DiffWriter
+
+# Create tool instances
+shell = Shell()
+writer = DiffWriter()
+
+# Pass to agent
+agent = Agent("coder", tools=[shell, writer])
+
+agent.input("Create a hello.py file that prints 'Hello World'")
+```
+
+## Customizing Tools
+
+Need to modify a built-in tool? Copy it to your project:
+
+```bash
+# Copy tool source to ./tools/
+co copy Gmail
+
+# Copy multiple tools
+co copy Gmail Shell memory
+```
+
+Then import from your local copy:
+
+```python
+# Before (from package)
+from connectonion import Gmail
+
+# After (from your copy)
+from tools.gmail import Gmail  # Customize freely!
+```
+
+See [co copy](../cli/copy.md) for full details.
+
+## Categories
+
+### File Operations
+- **Shell** - Run commands, scripts, git
+- **DiffWriter** - Edit files with visual diffs
+
+### Communication
+- **Gmail** - Send/read Gmail
+- **Outlook** - Send/read Outlook
+
+### Calendar
+- **GoogleCalendar** - Google Calendar events
+- **MicrosoftCalendar** - Microsoft Calendar events
+
+### Utilities
+- **WebFetch** - Fetch and parse web pages
+- **Memory** - Store/retrieve persistent data
+- **TodoList** - Track tasks and progress
+- **Terminal** - Interactive terminal UI
+- **SlashCommand** - Define custom commands

connectonion/docs/useful_tools/ask_user.md

@@ -0,0 +1,103 @@
+# ask_user
+
+Ask the user a question during agent execution via connection.
+
+## Usage
+
+**Option 1: Import directly**
+
+```python
+from connectonion.useful_tools import ask_user
+
+agent = Agent("assistant", tools=[ask_user])
+```
+
+**Option 2: Copy and customize**
+
+```bash
+co copy ask_user
+```
+
+```python
+from tools.ask_user import ask_user  # Your local copy
+
+agent = Agent("assistant", tools=[ask_user])
+```
+
+## Quick Start
+
+```python
+from connectonion.useful_tools import ask_user
+
+agent = Agent("assistant", tools=[ask_user])
+agent.input("Help me choose a programming language")
+# Agent can now ask user questions mid-execution
+```
+
+## How It Works
+
+When the agent calls `ask_user`, it:
+1. Sends an `ask_user` event via `agent.connection`
+2. Waits for user response
+3. Returns the answer to the agent
+
+```
+Agent calls ask_user("What color?", ["red", "blue"])
+    ↓
+connection.send({ type: "ask_user", question: "...", options: [...] })
+    ↓
+connection.receive() ← waits for response
+    ↓
+Returns answer to agent
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `question` | `str` | The question to ask |
+| `options` | `list[str]` | Optional list of choices |
+| `multi_select` | `bool` | Allow multiple selections (default: False) |
+
+## Examples
+
+```python
+# Free-form question
+answer = ask_user("What is your project name?")
+
+# Single choice
+color = ask_user("Pick a color", options=["Red", "Green", "Blue"])
+
+# Multiple choice
+languages = ask_user(
+    "Which languages do you know?",
+    options=["Python", "JavaScript", "Rust", "Go"],
+    multi_select=True
+)
+```
+
+## Frontend Integration
+
+The frontend receives this event:
+
+```json
+{
+  "type": "ask_user",
+  "question": "Pick a color",
+  "options": ["Red", "Green", "Blue"],
+  "multi_select": false
+}
+```
+
+And responds with:
+
+```json
+{
+  "answer": "Blue"
+}
+```
+
+## Requirements
+
+- Requires `agent.connection` to be set (works with hosted agents)
+- Frontend must handle `ask_user` event type

connectonion/docs/useful_tools/diff_writer.md

@@ -0,0 +1,158 @@
+# DiffWriter
+
+Human-in-the-loop file writing with diff display and approval.
+
+## Usage
+
+**Option 1: Import directly**
+
+```python
+from connectonion import DiffWriter
+
+agent = Agent("coder", tools=[DiffWriter()])
+```
+
+**Option 2: Copy and customize**
+
+```bash
+co copy diff_writer
+```
+
+```python
+from tools.diff_writer import DiffWriter  # Your local copy
+```
+
+## Installation
+
+```python
+from connectonion import DiffWriter
+
+writer = DiffWriter()
+```
+
+## API
+
+### write(path, content)
+
+Write content to a file with diff display and user approval.
+
+```python
+result = writer.write("hello.py", "print('hello')")
+# Shows colorized diff
+# Asks user to choose: 1=Yes, 2=Yes to all, 3=No + feedback
+# Returns: "Wrote 15 bytes to hello.py" or feedback message
+```
+
+### diff(path, content)
+
+Show diff without writing (preview mode).
+
+```python
+diff_text = writer.diff("hello.py", "print('hello')")
+# Returns the diff string without writing
+```
+
+### read(path)
+
+Read file contents.
+
+```python
+content = writer.read("hello.py")
+# Returns: "print('hello')"
+```
+
+## Approval Options
+
+When a file change is proposed, user sees:
+
+```
+╭─── Changes to hello.py ────────────────────────╮
+│ --- a/hello.py                                 │
+│ +++ b/hello.py                                 │
+│ @@ -1,2 +1,3 @@                                │
+│  def hello():                                  │
+│ -    pass                                      │
+│ +    print("Hello!")                           │
+╰────────────────────────────────────────────────╯
+
+Choose an option:
+  1 - Yes, apply this change
+  2 - Yes to all (auto-approve for this session)
+  3 - No, and tell agent what to do instead
+
+Apply changes to hello.py? [1/2/3]:
+```
+
+| Option | Effect |
+|--------|--------|
+| **1** | Apply this change, ask again for next change |
+| **2** | Apply this and all future changes (session-wide) |
+| **3** | Reject + provide feedback for agent to try again |
+
+## Options
+
+### auto_approve
+
+Skip approval prompts (for automation).
+
+```python
+# Ask for approval (default)
+writer = DiffWriter(auto_approve=False)
+
+# Auto-approve all writes
+writer = DiffWriter(auto_approve=True)
+```
+
+## Use with Agent
+
+```python
+from connectonion import Agent, DiffWriter
+
+writer = DiffWriter()
+agent = Agent("coder", tools=[writer])
+
+agent.input("create a hello.py file with a hello world function")
+# Agent calls writer.write()
+# User sees diff and chooses 1, 2, or 3
+# If 3: User provides feedback, agent receives it and tries again
+```
+
+## Feedback Flow
+
+When user chooses option 3 (reject):
+
+1. User is prompted: "What should the agent do instead?"
+2. User types feedback, e.g., "use snake_case for function names"
+3. Agent receives: `"User rejected changes to hello.py. Feedback: use snake_case for function names"`
+4. Agent can retry with the feedback
+
+## Common Use Cases
+
+```python
+# Interactive coding with approval
+writer = DiffWriter()
+agent = Agent("coder", tools=[writer])
+
+# CI/CD automation - skip prompts
+writer = DiffWriter(auto_approve=True)
+agent = Agent("automation", tools=[writer])
+
+# Preview changes only
+diff = writer.diff("config.py", new_config)
+print(diff)
+```
+
+## Customizing
+
+Need to modify DiffWriter's behavior? Copy the source to your project:
+
+```bash
+co copy diff_writer
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion import DiffWriter  # Before
+from tools.diff_writer import DiffWriter  # After - customize freely!
+```