connectonion 0.6.1__py3-none-any.whl → 0.6.3__py3-none-any.whl

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!
+```