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

connectonion/docs/useful_tools/shell.md

@@ -0,0 +1,115 @@
+# Shell
+
+Shell command execution tool.
+
+## Usage
+
+**Option 1: Import directly**
+
+```python
+from connectonion import Shell
+
+agent = Agent("coder", tools=[Shell()])
+```
+
+**Option 2: Copy and customize**
+
+```bash
+co copy shell
+```
+
+```python
+from tools.shell import Shell  # Your local copy
+```
+
+## Installation
+
+```python
+from connectonion import Shell
+
+shell = Shell()
+```
+
+## API
+
+### run(command)
+
+Execute a shell command, returns output.
+
+```python
+result = shell.run("ls -la")
+# Returns: "total 12\ndrwxr-xr-x  8 user staff..."
+
+result = shell.run("git status")
+# Returns: "On branch main\nnothing to commit..."
+
+result = shell.run("python --version")
+# Returns: "Python 3.11.0"
+```
+
+### run_in_dir(command, directory)
+
+Execute command in a specific directory.
+
+```python
+result = shell.run_in_dir("npm install", "/path/to/project")
+# Returns: "added 100 packages..."
+
+result = shell.run_in_dir("pytest", "/path/to/tests")
+# Returns: "5 passed in 0.5s"
+```
+
+## Use with Agent
+
+```python
+from connectonion import Agent, Shell
+
+shell = Shell()
+agent = Agent("coder", tools=[shell])
+
+agent.input("list all python files in current directory")
+# Agent runs: shell.run("ls *.py")
+
+agent.input("run the tests")
+# Agent runs: shell.run("pytest")
+
+agent.input("install requests package")
+# Agent runs: shell.run("pip install requests")
+```
+
+## Common Use Cases
+
+```python
+# Git operations
+shell.run("git status")
+shell.run("git add .")
+shell.run("git commit -m 'update'")
+
+# Package management
+shell.run("pip install requests")
+shell.run("npm install express")
+
+# Build and test
+shell.run("pytest")
+shell.run("npm run build")
+
+# System info
+shell.run("pwd")
+shell.run("whoami")
+shell.run("df -h")
+```
+
+## Customizing
+
+Need to modify Shell's behavior? Copy the source to your project:
+
+```bash
+co copy shell
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion import Shell  # Before
+from tools.shell import Shell      # After - customize freely!
+```

connectonion/docs/useful_tools/slash_command.md

@@ -0,0 +1,116 @@
+# SlashCommand
+
+Load and execute custom commands from markdown files.
+
+## Usage
+
+**Option 1: Import directly**
+
+```python
+from connectonion import SlashCommand
+
+cmd = SlashCommand.load("today")
+```
+
+**Option 2: Copy and customize**
+
+```bash
+co copy slash_command
+```
+
+```python
+from tools.slash_command import SlashCommand  # Your local copy
+```
+
+## Quick Start
+
+```python
+from connectonion import SlashCommand
+
+# Load command
+cmd = SlashCommand.load("today")
+
+# Get prompt
+prompt = cmd.prompt
+
+# List all commands
+commands = SlashCommand.list_all()
+```
+
+## Command File Format
+
+Create `.co/commands/today.md`:
+
+```markdown
+---
+name: today
+description: Daily email briefing
+tools:
+  - Gmail.search_emails
+  - WebFetch
+---
+Summarize my important emails from today.
+Focus on:
+- Urgent requests
+- Meeting invites
+- Follow-ups needed
+```
+
+## YAML Frontmatter
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Command name |
+| `description` | Yes | Short description |
+| `tools` | No | Allowed tools (all if omitted) |
+
+## Tool Filtering
+
+Limit which tools the command can use:
+
+```yaml
+tools:
+  - Gmail.search_emails    # Specific method
+  - WebFetch               # Whole class
+  - my_function            # Standalone function
+```
+
+## Locations
+
+Commands are loaded from:
+1. `.co/commands/*.md` (user commands - priority)
+2. `commands/*.md` (built-in commands)
+
+## API
+
+```python
+# Load single command
+cmd = SlashCommand.load("today")
+cmd.name          # "today"
+cmd.description   # "Daily email briefing"
+cmd.prompt        # "Summarize my important..."
+cmd.tools         # ["Gmail.search_emails", "WebFetch"]
+
+# Filter tools for command
+filtered = cmd.filter_tools(all_tools)
+
+# List all available commands
+commands = SlashCommand.list_all()
+for cmd in commands:
+    print(f"/{cmd.name} - {cmd.description}")
+```
+
+## Customizing
+
+Need to modify SlashCommand's behavior? Copy the source to your project:
+
+```bash
+co copy slash_command
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion import SlashCommand  # Before
+from tools.slash_command import SlashCommand  # After - customize freely!
+```

connectonion/docs/useful_tools/terminal.md

@@ -0,0 +1,115 @@
+# Terminal
+
+Interactive terminal utilities: selection menus, file browser, and input with autocomplete.
+
+## Usage
+
+**Option 1: Import directly**
+
+```python
+from connectonion import pick, yes_no, browse_files, input_with_at
+```
+
+**Option 2: Copy and customize**
+
+```bash
+co copy terminal
+```
+
+```python
+from tools.terminal import pick, yes_no, browse_files, input_with_at  # Your local copy
+```
+
+## Quick Start
+
+```python
+from connectonion import pick, yes_no, browse_files, input_with_at
+
+# Selection menu
+choice = pick("Pick a color", ["Red", "Green", "Blue"])
+
+# Yes/No confirmation
+ok = yes_no("Are you sure?")
+
+# File browser
+path = browse_files()
+
+# Input with @ file autocomplete
+cmd = input_with_at("> ")
+```
+
+## pick()
+
+Single-select menu with keyboard navigation.
+
+```python
+# List options (press 1, 2, 3 or arrow keys)
+choice = pick("Apply this command?", [
+    "Yes, apply",
+    "Yes for same command",
+    "No, tell agent how"
+])
+
+# Dict options (returns key)
+choice = pick("Continue?", {
+    "y": "Yes, continue",
+    "n": "No, cancel",
+})
+```
+
+## yes_no()
+
+Simple binary confirmation.
+
+```python
+ok = yes_no("Delete this file?")
+# Press y → True, n → False
+```
+
+## browse_files()
+
+Navigate and select files.
+
+```python
+path = browse_files()
+# Arrow keys to navigate
+# Enter on folder to open
+# Enter on file to select
+# Returns: "src/agent.py"
+```
+
+## input_with_at()
+
+Text input with @ file autocomplete.
+
+```python
+cmd = input_with_at("> ")
+# User types: "edit @"
+# File browser opens automatically
+# Returns: "edit src/agent.py"
+```
+
+## Keyboard Controls
+
+| Key | Action |
+|-----|--------|
+| ↑/↓ | Navigate options |
+| 1-9 | Quick select by number |
+| Enter | Confirm selection |
+| Esc | Cancel |
+| @ | Trigger file autocomplete |
+
+## Customizing
+
+Need to modify terminal utilities? Copy the source to your project:
+
+```bash
+co copy terminal
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion import pick, yes_no  # Before
+from tools.terminal import pick, yes_no   # After - customize freely!
+```

connectonion/docs/useful_tools/todo_list.md

@@ -0,0 +1,272 @@
+# TodoList
+
+Task tracking tool for agents to manage complex, multi-step tasks.
+
+## Usage
+
+**Option 1: Import directly**
+
+```python
+from connectonion import TodoList
+
+agent = Agent("worker", tools=[TodoList()])
+```
+
+**Option 2: Copy and customize**
+
+```bash
+co copy todo_list
+```
+
+```python
+from tools.todo_list import TodoList  # Your local copy
+```
+
+## Installation
+
+```python
+from connectonion import TodoList
+
+todo = TodoList()
+```
+
+## Why Use TodoList?
+
+- **Track progress** on complex tasks with multiple steps
+- **Show users** what the agent is working on
+- **Organize** multi-step workflows
+- **Prevent** forgetting steps in complex tasks
+
+## When to Use
+
+Use TodoList when:
+- Task requires **3+ distinct steps**
+- User provides **multiple tasks** (numbered or comma-separated)
+- Task requires **careful planning**
+- You want to show **progress** to the user
+
+Don't use when:
+- Task is **trivial** (1-2 simple steps)
+- Task is **purely conversational**
+
+## API
+
+### add(content, active_form)
+
+Add a new pending task.
+
+```python
+todo.add("Fix authentication bug", "Fixing authentication bug")
+todo.add("Run tests", "Running tests")
+todo.add("Update docs", "Updating docs")
+```
+
+### start(content)
+
+Mark a task as in_progress. Only one task can be in_progress at a time.
+
+```python
+todo.start("Fix authentication bug")
+# Shows: ◐ Fixing authentication bug
+```
+
+### complete(content)
+
+Mark a task as completed.
+
+```python
+todo.complete("Fix authentication bug")
+# Shows: ● Fix authentication bug
+```
+
+### remove(content)
+
+Remove a task from the list.
+
+```python
+todo.remove("Update docs")
+```
+
+### list()
+
+Get all todos as text.
+
+```python
+print(todo.list())
+# ○ Fix authentication bug
+# ◐ Running tests
+# ● Update docs
+```
+
+### update(todos)
+
+Replace entire todo list (for bulk updates).
+
+```python
+todo.update([
+    {"content": "Step 1", "status": "completed", "active_form": "Doing step 1"},
+    {"content": "Step 2", "status": "in_progress", "active_form": "Doing step 2"},
+    {"content": "Step 3", "status": "pending", "active_form": "Doing step 3"},
+])
+```
+
+### clear()
+
+Clear all todos.
+
+```python
+todo.clear()
+```
+
+## Task States
+
+| Icon | Status | Description |
+|------|--------|-------------|
+| ○ | pending | Not yet started |
+| ◐ | in_progress | Currently working on |
+| ● | completed | Finished |
+
+## Visual Display
+
+When tasks change, TodoList shows a panel:
+
+```
+╭─── Tasks (1/3) ───────────────────────────────╮
+│ ● Fix authentication bug                       │
+│ ◐ Running tests                                │
+│ ○ Update docs                                  │
+╰────────────────────────────────────────────────╯
+```
+
+## Properties
+
+### progress
+
+Get completion percentage (0.0 to 1.0).
+
+```python
+print(todo.progress)  # 0.33 (1 of 3 completed)
+```
+
+### current_task
+
+Get the currently in_progress task.
+
+```python
+print(todo.current_task)  # "Running tests"
+```
+
+## Use with Agent
+
+```python
+from connectonion import Agent, TodoList
+
+todo = TodoList()
+agent = Agent("worker", tools=[todo])
+
+agent.input("""
+Implement user authentication:
+1. Create User model
+2. Add login endpoint
+3. Add logout endpoint
+4. Write tests
+""")
+
+# Agent will:
+# 1. Add all tasks to todo list
+# 2. Start each task before working on it
+# 3. Complete each task when done
+# 4. Show progress throughout
+```
+
+## Best Practices
+
+### Task Naming
+
+Use both forms:
+- **content**: Imperative form ("Fix bug", "Run tests")
+- **active_form**: Present continuous ("Fixing bug", "Running tests")
+
+```python
+todo.add("Fix authentication bug", "Fixing authentication bug")
+#         ^-- content              ^-- active_form
+```
+
+### One In-Progress at a Time
+
+Only one task should be in_progress. Complete current before starting next.
+
+```python
+todo.add("Task A", "Doing A")
+todo.add("Task B", "Doing B")
+
+todo.start("Task A")
+todo.start("Task B")  # Error: Another task is in progress
+todo.complete("Task A")
+todo.start("Task B")  # Now works
+```
+
+### Mark Complete Immediately
+
+Complete tasks as soon as done, don't batch:
+
+```python
+# Good
+todo.complete("Step 1")
+# ... do step 2 ...
+todo.complete("Step 2")
+
+# Bad - batching completions
+# ... do all steps ...
+todo.complete("Step 1")
+todo.complete("Step 2")
+todo.complete("Step 3")
+```
+
+## Example: Multi-Step Task
+
+```python
+from connectonion import Agent, TodoList, DiffWriter
+
+todo = TodoList()
+writer = DiffWriter()
+
+agent = Agent(
+    "developer",
+    tools=[todo, writer],
+    system_prompt="""
+    You are a developer. For complex tasks:
+    1. Break into steps using TodoList
+    2. Start each step before working
+    3. Complete each step when done
+    """
+)
+
+agent.input("Create a REST API with user CRUD operations")
+
+# Agent workflow:
+# 1. todo.add("Create User model", "Creating User model")
+# 2. todo.add("Add GET /users endpoint", "Adding GET endpoint")
+# 3. todo.add("Add POST /users endpoint", "Adding POST endpoint")
+# ...
+# 4. todo.start("Create User model")
+# 5. writer.write("models.py", "...")
+# 6. todo.complete("Create User model")
+# 7. todo.start("Add GET /users endpoint")
+# ...
+```
+
+## Customizing
+
+Need to modify TodoList's behavior? Copy the source to your project:
+
+```bash
+co copy todo_list
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion import TodoList  # Before
+from tools.todo_list import TodoList  # After - customize freely!
+```