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

connectonion/docs/cli/auth.md

@@ -0,0 +1,46 @@
+# ConnectOnion Auth (co auth)
+
+One-time setup for managed models — no provider keys needed.
+
+## Quick Start
+
+```bash
+# Authenticate with OpenOnion (required first)
+co auth
+
+# Optional: Connect your Google account for Gmail & Calendar
+co auth google
+```
+
+What `co auth` does:
+- Authenticates your agent and saves a secure token
+- Token is saved to `~/.co/keys.env` as `OPENONION_API_KEY`
+- If your project has a `.env`, it's updated too
+- `.co/config.toml` gains `agent.email` and `email_active = true`
+
+What `co auth google` does:
+- Connects your Google account for Gmail Send and Calendar Read
+- Opens browser for OAuth authorization
+- Saves credentials to `.env` for your agents to use
+- Running again will switch to a different Google account
+- See [Google Integration](../integrations/google.md) for details
+
+## Use Managed Models (co/ prefix)
+
+```python
+from connectonion import llm_do
+
+response = llm_do("Hello", model="co/gpt-4o")
+```
+
+Works across providers:
+- `co/gpt-4o`, `co/gpt-4o-mini`
+- `co/claude-3-5-sonnet`, `co/claude-3-5-haiku`
+- `co/gemini-1.5-pro`, `co/gemini-1.5-flash`
+
+## Troubleshooting
+
+- Missing token? Run `co auth` again
+- Network issue? Try again or check your connection
+- Global vs project: `co auth` prefers local `.co` if keys exist, otherwise uses `~/.co`
+

connectonion/docs/cli/browser.md

@@ -0,0 +1,235 @@
+# CLI Browser Feature
+
+Quick browser screenshots with one command.
+
+## Overview
+
+The `-b` flag (or `co browser`) takes instant screenshots without writing code. Perfect for debugging, testing, and sharing visual proof.
+
+## Basic Usage
+
+```bash
+co -b "screenshot localhost:3000"
+```
+
+Saves to `.tmp/screenshot_YYYYMMDD_HHMMSS.png` by default.
+
+## Command Format
+
+```bash
+co -b "screenshot [URL] [save to PATH] [size SIZE]"
+```
+
+All parts except URL are optional.
+
+## Examples
+
+### Basic Screenshot
+
+```bash
+# Screenshot local development
+co -b "screenshot localhost:3000"
+
+# With specific port
+co -b "screenshot localhost:8080"
+
+# External site
+co -b "screenshot example.com"
+```
+
+### Save to Specific Path
+
+```bash
+# Save to temp directory
+co -b "screenshot localhost:3000 save to /tmp/debug.png"
+
+# Save to current directory with name
+co -b "screenshot localhost:3000 save to homepage.png"
+
+# Save to subdirectory
+co -b "screenshot localhost:3000 save to screenshots/test.png"
+```
+
+### Device Sizes
+
+```bash
+# iPhone viewport
+co -b "screenshot localhost:3000 size iphone"
+
+# Custom dimensions
+co -b "screenshot localhost:3000 size 390x844"
+
+# Common presets
+co -b "screenshot localhost:3000 size ipad"
+co -b "screenshot localhost:3000 size desktop"
+```
+
+### Complete Examples
+
+```bash
+# Debug mobile checkout flow
+co -b "screenshot localhost:3000/checkout save to /tmp/checkout-mobile.png size iphone"
+
+# Document bug on specific page
+co -b "screenshot localhost:3000/xray save to bug-report.png size 1920x1080"
+
+# Test responsive design
+co -b "screenshot localhost:3000 save to mobile.png size 390x844"
+co -b "screenshot localhost:3000 save to tablet.png size 768x1024"
+co -b "screenshot localhost:3000 save to desktop.png size 1920x1080"
+```
+
+## Device Presets
+
+| Preset | Dimensions | Device |
+|--------|------------|--------|
+| `iphone` | 390x844 | iPhone 14/15 |
+| `android` | 360x800 | Common Android |
+| `ipad` | 768x1024 | iPad |
+| `desktop` | 1920x1080 | Full HD Desktop |
+
+## URL Handling
+
+The command intelligently handles URLs:
+
+- `localhost` → `http://localhost`
+- `localhost:3000` → `http://localhost:3000`
+- `example.com` → `https://example.com`
+- `http://example.com` → `http://example.com` (unchanged)
+
+## Output Files
+
+If no path specified:
+- Saves under `.tmp/`
+- Named `screenshot_YYYYMMDD_HHMMSS.png`
+- Example: `.tmp/screenshot_20240115_143022.png`
+
+## Installation
+
+Browser features require Playwright:
+
+```bash
+pip install playwright
+playwright install chromium
+```
+
+Or install ConnectOnion with browser support:
+
+```bash
+pip install connectonion[browser]
+```
+
+## Use Cases
+
+### 1. Debug Local Development
+
+```bash
+# Quick check of homepage
+co -b "screenshot localhost:3000"
+
+# Debug specific route
+co -b "screenshot localhost:3000/api/status"
+```
+
+### 2. Document Bugs
+
+```bash
+# Capture error state
+co -b "screenshot localhost:3000/error save to bug.png"
+
+# Mobile-specific issue
+co -b "screenshot localhost:3000/mobile-bug save to mobile-issue.png size iphone"
+```
+
+### 3. Test Responsive Design
+
+```bash
+# Test different viewports
+for size in iphone android ipad desktop; do
+  co -b "screenshot localhost:3000 save to view-$size.png size $size"
+done
+```
+
+### 4. CI/CD Integration
+
+```bash
+# In GitHub Actions or similar
+co -b "screenshot $DEPLOY_URL save to artifacts/deployed.png"
+```
+
+## Error Messages
+
+```bash
+# Missing URL
+co -b "screenshot"
+❌ Usage: co -b "screenshot [URL] [save to PATH] [size SIZE]"
+
+# Playwright not installed  
+co -b "screenshot localhost:3000"
+❌ Browser tools not installed
+   Run: pip install playwright && playwright install chromium
+
+# Missing OPENAI_API_KEY
+co -b "screenshot localhost:3000"
+❌ Natural language browser agent unavailable. Set OPENAI_API_KEY and try again.
+
+# Cannot reach URL
+co -b "screenshot localhost:3000"
+❌ Cannot reach http://localhost:3000
+   Is your server running?
+
+# Permission denied
+co -b "screenshot localhost:3000 save to /root/test.png"
+❌ Cannot save to /root/test.png (permission denied)
+```
+
+## Tips
+
+1. **Quick Debug**: Just `co -b "screenshot localhost:3000"` for instant feedback
+2. **Organize Screenshots**: Use descriptive paths like `save to bugs/issue-123.png`
+3. **Test Viewports**: Use device names (`iphone`, `ipad`) for common sizes
+4. **Timestamps**: Default filenames include timestamp for versioning
+
+## Limitations
+
+- Screenshots only (no interaction, clicking, forms)
+- Single page at a time
+- Headless browser only
+- PNG format only
+
+For complex browser automation, use the full ConnectOnion browser agent or Playwright directly.
+
+## Requirements
+
+- `OPENAI_API_KEY` must be set (managed keys are not used here)
+- Playwright installed and set up
+
+## Examples for Common Frameworks
+
+### Next.js
+```bash
+co -b "screenshot localhost:3000"
+co -b "screenshot localhost:3000/_error save to error.png"
+```
+
+### FastAPI
+```bash
+co -b "screenshot localhost:8000"
+co -b "screenshot localhost:8000/docs save to api-docs.png"
+```
+
+### Django
+```bash
+co -b "screenshot localhost:8000"
+co -b "screenshot localhost:8000/admin save to admin.png"
+```
+
+### React Dev Server
+```bash
+co -b "screenshot localhost:3000"
+co -b "screenshot localhost:3000 size iphone"
+```
+
+## Summary
+
+The `-b` flag provides dead-simple browser screenshots. No setup, no complexity - just describe what screenshot you want and where to save it. Perfect for debugging during development.

connectonion/docs/cli/copy.md

@@ -0,0 +1,232 @@
+# co copy - Copy Tools, Plugins & Prompts
+
+Copy built-in tools, plugins, and prompt templates to your project for customization.
+
+## Quick Start
+
+```bash
+# See what's available
+co copy --list
+
+# Copy a tool
+co copy Gmail
+
+# Copy a plugin
+co copy re_act
+
+# Copy a prompt template
+co copy coding_agent
+```
+
+## Why Copy?
+
+Built-in tools work great out of the box. But sometimes you need to:
+
+- **Add features** - Extend functionality for your use case
+- **Modify behavior** - Change how a tool works
+- **Learn** - Study implementation patterns
+- **Debug** - Trace issues in tool code
+
+Copying gives you full control over the source code.
+
+## Usage
+
+### List Available Items
+
+```bash
+co copy --list
+```
+
+Output:
+```
+                    Available Items to Copy
+┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Name                   ┃ Type   ┃ Path                      ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ gmail                  │ tool   │ gmail.py                  │
+│ memory                 │ tool   │ memory.py                 │
+│ shell                  │ tool   │ shell.py                  │
+│ ...                    │        │                           │
+│ re_act                 │ plugin │ re_act.py                 │
+│ shell_approval         │ plugin │ shell_approval.py         │
+│ coding_agent           │ prompt │ coding_agent/             │
+└────────────────────────┴────────┴───────────────────────────┘
+```
+
+### Copy a Tool
+
+```bash
+co copy Gmail
+```
+
+Creates `./tools/gmail.py` in your project.
+
+### Copy a Plugin
+
+```bash
+co copy re_act
+```
+
+Creates `./plugins/re_act.py` in your project.
+
+### Copy a Prompt Template
+
+```bash
+co copy coding_agent
+```
+
+Creates `./prompts/coding_agent/` directory with:
+```
+prompts/coding_agent/
+├── prompts/
+│   ├── main.md           # Core agent behavior
+│   └── tools/            # Per-tool guidance
+│       ├── shell.md
+│       ├── read.md
+│       ├── write.md
+│       └── todo.md
+├── assembler.py          # Prompt assembly utility
+└── README.md
+```
+
+### Copy Multiple Items
+
+```bash
+co copy Gmail Shell memory re_act
+```
+
+### Custom Destination
+
+```bash
+co copy Gmail --path ./my_tools/
+```
+
+### Force Overwrite
+
+```bash
+co copy Gmail --force
+```
+
+## Available Tools
+
+| Name | File | Description |
+|------|------|-------------|
+| gmail | gmail.py | Gmail integration (OAuth, send/receive) |
+| outlook | outlook.py | Outlook/Microsoft email |
+| google_calendar | google_calendar.py | Google Calendar events |
+| microsoft_calendar | microsoft_calendar.py | Microsoft Calendar |
+| memory | memory.py | Persistent agent memory |
+| web_fetch | web_fetch.py | Web scraping tool |
+| shell | shell.py | Shell command execution |
+| diff_writer | diff_writer.py | File editing with diffs |
+| todo_list | todo_list.py | Task list management |
+| slash_command | slash_command.py | Custom command extension |
+
+## Available Plugins
+
+| Name | File | Description |
+|------|------|-------------|
+| re_act | re_act.py | ReAct prompting pattern |
+| eval | eval.py | Evaluation plugin |
+| image_result_formatter | image_result_formatter.py | Base64 image handling |
+| shell_approval | shell_approval.py | User confirmation for shell |
+| gmail_plugin | gmail_plugin.py | Gmail OAuth flow |
+| calendar_plugin | calendar_plugin.py | Google Calendar integration |
+| system_reminder | system_reminder.py | Inject contextual reminders into tool results |
+
+### Plugins with Prompts
+
+Some plugins include prompt files. These are automatically copied together:
+
+```bash
+co copy system_reminder
+```
+
+Creates:
+```
+./plugins/system_reminder.py
+./prompts/system-reminders/
+├── test-reminder.md
+└── security-warning.md
+```
+
+## After Copying
+
+### Update Your Imports
+
+```python
+# Before (from package)
+from connectonion import Gmail
+
+# After (from your copy)
+from tools.gmail import Gmail
+```
+
+### Customize the Code
+
+Now you have full control:
+
+```python
+# tools/gmail.py - Your copy, modify freely!
+
+class Gmail:
+    def send(self, to, subject, body):
+        # Add your custom logic here
+        self.log_to_my_system(to, subject)  # Your addition
+        # ... rest of original code
+```
+
+## Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--list` | `-l` | List available tools and plugins |
+| `--path` | `-p` | Custom destination path |
+| `--force` | `-f` | Overwrite existing files |
+
+## Examples
+
+### Customize Gmail Tool
+
+```bash
+# Copy Gmail tool
+co copy gmail
+
+# Edit your copy
+# tools/gmail.py
+```
+
+```python
+# agent.py
+from tools.gmail import Gmail  # Use your customized version
+
+agent = Agent("emailer", tools=[Gmail()])
+```
+
+### Create Custom Plugin
+
+```bash
+# Copy re_act as starting point
+co copy re_act
+
+# Modify plugins/re_act.py for your needs
+```
+
+### Copy All Email Tools
+
+```bash
+co copy gmail outlook
+```
+
+## Available Prompts
+
+| Name | Directory | Description |
+|------|-----------|-------------|
+| coding_agent | coding_agent/ | Coding Agent Prompt - modular prompt template for coding assistants |
+
+## See Also
+
+- [Built-in Tools](../useful_tools/) - Tool documentation
+- [Built-in Plugins](../useful_plugins/) - Plugin documentation
+- [Prompt Templates](../useful_prompts/) - Prompt documentation
+- [Creating Tools](../concepts/tools.md) - Writing custom tools