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

connectonion/cli/co_ai/prompts/connectonion/useful_tools/slash_command.md

@@ -0,0 +1,96 @@
+# SlashCommand
+
+Load and execute custom commands from markdown files.
+
+## 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/cli/co_ai/prompts/connectonion/useful_tools/terminal.md

@@ -0,0 +1,97 @@
+# Terminal
+
+Interactive terminal utilities: selection menus, file browser, and input with autocomplete.
+
+## 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/cli/co_ai/prompts/connectonion/useful_tools/todo_list.md

@@ -0,0 +1,252 @@
+# TodoList
+
+Task tracking tool for agents to manage complex, multi-step tasks.
+
+## 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!
+```

connectonion/cli/co_ai/prompts/connectonion/useful_tools/web_fetch.md

@@ -0,0 +1,130 @@
+# WebFetch
+
+Web fetching tool with single-responsibility functions.
+
+## Installation
+
+```python
+from connectonion import WebFetch
+
+web = WebFetch()
+```
+
+## Low-level APIs
+
+Each function does ONE thing.
+
+### fetch(url)
+
+HTTP GET request, returns raw HTML.
+
+```python
+html = web.fetch("example.com")
+# Returns: "<!DOCTYPE html>..."
+```
+
+### strip_tags(html)
+
+Strip HTML tags, returns body text only.
+
+```python
+text = web.strip_tags(html)
+# Returns clean text without HTML
+```
+
+### get_title(html)
+
+Get page title.
+
+```python
+title = web.get_title(html)
+# Returns: "Example Domain"
+```
+
+### get_links(html)
+
+Extract all links from HTML.
+
+```python
+links = web.get_links(html)
+# Returns: [{'text': 'Home', 'href': '/'}, {'text': 'About', 'href': '/about'}]
+```
+
+### get_emails(html)
+
+Extract email addresses from HTML.
+
+```python
+emails = web.get_emails(html)
+# Returns: ['support@example.com', 'sales@company.org']
+```
+
+### get_social_links(html)
+
+Extract social media links.
+
+```python
+html = web.fetch("openai.com")
+social = web.get_social_links(html)
+# Returns: {'twitter': 'https://x.com/OpenAI', 'youtube': '...', 'github': '...'}
+```
+
+## High-level APIs
+
+Uses LLM to analyze content.
+
+### analyze_page(url)
+
+Analyze what a webpage/company does.
+
+```python
+result = web.analyze_page("stripe.com")
+# Returns: "Stripe is a technology company that builds economic infrastructure..."
+```
+
+### get_contact_info(url)
+
+Extract contact information.
+
+```python
+result = web.get_contact_info("stripe.com/contact")
+# Returns: "Email: support@stripe.com, Phone: ..."
+```
+
+## Composing Functions
+
+```python
+# Get clean text from a URL
+text = web.strip_tags(web.fetch("example.com"))
+
+# Get title and text
+html = web.fetch("example.com")
+title = web.get_title(html)
+text = web.strip_tags(html)
+```
+
+## Use with Agent
+
+```python
+from connectonion import Agent, WebFetch
+
+web = WebFetch()
+agent = Agent("researcher", tools=[web])
+
+agent.input("What does stripe.com do?")
+```
+
+## Customizing
+
+Need to modify WebFetch's behavior? Copy the source to your project:
+
+```bash
+co copy web_fetch
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion import WebFetch  # Before
+from tools.web_fetch import WebFetch  # After - customize freely!
+```

connectonion/cli/co_ai/prompts/connectonion/vibe-coding-guide.md

@@ -0,0 +1,97 @@
+# Vibe Coding Guide: Build Agents with Cursor AI
+
+> **Quick Start**: Drag our docs into Cursor → Ask AI → Get your agent
+
+## Two Ways to Get Started
+
+### Method 1: Drag & Drop
+1. **Open Cursor AI editor**
+2. **Drag our documentation** into Cursor:
+   - From website: Go to [docs.connectonion.com](https://docs.connectonion.com) → Drag any page
+   - From local: After `co init`, drag `.co/docs/co-vibecoding-principles-docs-contexts-all-in-one.md`
+3. **Ask Cursor**: "Help me create an agent using these docs"
+
+### Method 2: Copy All
+1. **Visit** [docs.connectonion.com](https://docs.connectonion.com)
+2. **Click** "Copy All Docs" (purple button in sidebar)
+3. **Paste** into Cursor chat
+4. **Ask Cursor**: "Help me create an agent using these docs"
+
+## Example: What Cursor Generates
+
+When you ask Cursor: **"Using ConnectOnion docs, create a calculator agent"**
+
+Cursor generates:
+
+```python
+from connectonion import Agent
+
+def add(a: float, b: float) -> float:
+    """Add two numbers."""
+    return a + b
+
+def multiply(a: float, b: float) -> float:
+    """Multiply two numbers."""
+    return a * b
+
+# Create agent
+calculator = Agent(
+    "calculator",
+    tools=[add, multiply],
+    instructions="You are a helpful calculator"
+)
+
+# Use it
+result = calculator.input("What is 5 plus 3?")
+print(result)  # Output: "5 plus 3 equals 8"
+```
+
+## The Magic
+
+The agent automatically:
+- ✅ Understands "plus" means use `add()`
+- ✅ Picks the right tool
+- ✅ Returns natural language
+
+## What to Ask Cursor
+
+**Basic:**
+```
+"Using ConnectOnion docs, create a calculator agent"
+```
+
+**Advanced:**
+```
+"Add more math functions to this agent"
+```
+
+**Custom:**
+```
+"Create an agent that [your specific need]"
+```
+
+## Why It Works
+
+Cursor + Our Docs = Complete Understanding:
+- How to create agents
+- How to add tools  
+- Best practices
+- Natural language processing
+
+## Quick Start
+
+1. **Install**: `pip install connectonion`
+2. **Initialize**: `co init`
+3. **Open in Cursor**
+4. **Drag our docs** into Cursor
+5. **Ask**: "Create an agent"
+6. **Run**: `python agent.py`
+
+## Get Our Docs
+
+- **Website**: [docs.connectonion.com](https://docs.connectonion.com) → Copy All Docs
+- **Local**: `.co/docs/co-vibecoding-principles-docs-contexts-all-in-one.md` (after `co init`)
+
+---
+
+*Drag, drop, ask. Your agent is ready!* 🎉