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

connectonion/docs/templates/minimal.md

@@ -0,0 +1,105 @@
+# Minimal Template
+
+The simplest starting point for learning ConnectOnion.
+
+## Quick Start
+
+```bash
+co create my-bot --template minimal
+cd my-bot
+python agent.py
+```
+
+## What You Get
+
+```
+my-bot/
+├── agent.py            # Agent with calculator tool
+├── .env                # API keys
+├── .co/
+│   └── docs/           # ConnectOnion documentation
+└── README.md           # Project docs
+```
+
+## Tools Included
+
+| Tool | Description |
+|------|-------------|
+| `calculator(expression)` | Evaluate math expressions |
+
+## Example Usage
+
+```python
+from connectonion import Agent
+
+def calculator(expression: str) -> float:
+    """Evaluate a math expression."""
+    return eval(expression)
+
+agent = Agent("assistant", tools=[calculator])
+result = agent.input("What is 25 * 4?")
+```
+
+Interactive mode:
+
+```
+You: What is 15% of 200?
+Agent: 15% of 200 is 30.0
+```
+
+## Use Cases
+
+- Learning ConnectOnion basics
+- Quick prototyping
+- Template for custom agents
+- Understanding tool calling
+
+## Dependencies
+
+- `connectonion`
+- `python-dotenv`
+
+## Customization
+
+### Add More Tools
+
+```python
+def search(query: str) -> str:
+    """Search for information."""
+    return f"Results for: {query}"
+
+agent = Agent(
+    "assistant",
+    tools=[calculator, search]
+)
+```
+
+### Add System Prompt
+
+Create `prompt.md`:
+
+```markdown
+# Assistant
+
+You are a helpful assistant with calculation abilities.
+
+## Guidelines
+- Show your work
+- Be precise with numbers
+```
+
+Then reference it:
+
+```python
+agent = Agent(
+    "assistant",
+    system_prompt="prompt.md",
+    tools=[calculator]
+)
+```
+
+## Next Steps
+
+- [Tools](../concepts/tools.md) - Add custom tools
+- [Prompts](../concepts/prompts.md) - Customize personality
+- [Events](../concepts/events.md) - Add lifecycle hooks

connectonion/docs/templates/playwright.md

@@ -0,0 +1,130 @@
+# Playwright Template
+
+Browser automation agent with full web control capabilities.
+
+## Quick Start
+
+```bash
+co create browser-bot --template playwright
+cd browser-bot
+pip install playwright
+playwright install chromium
+python agent.py
+```
+
+## What You Get
+
+```
+browser-bot/
+├── agent.py            # BrowserAutomation class with 11 tools
+├── prompt.md           # Browser automation system prompt
+├── requirements.txt    # playwright, connectonion, python-dotenv
+├── .env                # API keys
+├── .co/
+│   └── docs/           # ConnectOnion documentation
+└── README.md           # Project docs
+```
+
+## Tools Included
+
+| Tool | Description |
+|------|-------------|
+| `start_browser(headless)` | Launch browser instance |
+| `navigate(url, wait_until)` | Navigate to URL |
+| `take_screenshot(filename, full_page)` | Capture screenshots |
+| `scrape_content(selector)` | Extract text with CSS selectors |
+| `fill_form(form_data)` | Fill form fields |
+| `click(selector)` | Click elements |
+| `extract_links(filter_pattern)` | Get all links from page |
+| `wait_for_element(selector, timeout)` | Wait for DOM elements |
+| `execute_javascript(script)` | Run custom JavaScript |
+| `get_page_info()` | Get URL, title, viewport |
+| `get_session_info()` | Get browser state |
+
+## Example Usage
+
+```python
+# Scrape a webpage
+result = agent.input("Go to example.com and extract the main heading")
+
+# Fill a form
+result = agent.input('Fill the contact form with name "John" and email "john@example.com"')
+
+# Take screenshots
+result = agent.input("Take a full-page screenshot of the documentation site")
+
+# Extract links
+result = agent.input("Get all PDF links from the downloads page")
+```
+
+Interactive mode:
+
+```
+You: Go to hacker news and get the top 5 stories
+Agent: I'll navigate to Hacker News and extract the top stories...
+       [Takes screenshot, scrapes content]
+       Here are the top 5 stories:
+       1. ...
+```
+
+## Use Cases
+
+- Web scraping and data extraction
+- Form automation
+- Visual testing and screenshots
+- Link crawling
+- Dynamic content handling
+- Browser-based testing
+
+## Dependencies
+
+```
+connectonion
+playwright
+python-dotenv
+```
+
+After installing, run:
+```bash
+playwright install chromium
+```
+
+## Customization
+
+### Add Custom Selectors
+
+```python
+# The agent uses CSS selectors
+result = agent.input("Click the button with class 'submit-btn'")
+result = agent.input("Extract text from #main-content")
+```
+
+### Headless vs Visible Browser
+
+```python
+# Default is headless (no window)
+result = agent.input("Start browser in headless mode")
+
+# Or visible for debugging
+result = agent.input("Start browser with headless=false")
+```
+
+### Wait Strategies
+
+The `navigate` tool supports wait strategies:
+- `load` - Wait for page load
+- `domcontentloaded` - Wait for DOM ready
+- `networkidle` - Wait for network to be idle
+
+## Tips
+
+- Browser maintains state across commands (stateful)
+- Screenshots are saved to current directory
+- Use CSS selectors for precise element targeting
+- Agent tracks visited URLs and screenshots
+
+## Next Steps
+
+- [Playwright Docs](https://playwright.dev/python/) - Full Playwright API
+- [Tools](../concepts/tools.md) - Add custom tools
+- [XRay Debugging](../debug/xray.md) - Debug tool execution

connectonion/docs/templates/web-research.md

@@ -0,0 +1,144 @@
+# Web Research Template
+
+Research and data extraction agent for gathering and analyzing web content.
+
+## Quick Start
+
+```bash
+co create researcher --template web-research
+cd researcher
+pip install requests
+python agent.py
+```
+
+## What You Get
+
+```
+researcher/
+├── agent.py            # Research agent with 4 tools
+├── .env                # API keys
+├── .co/
+│   └── docs/           # ConnectOnion documentation
+└── README.md           # Project docs
+```
+
+## Tools Included
+
+| Tool | Description |
+|------|-------------|
+| `search_web(query)` | Web search (needs API integration) |
+| `extract_data(url, data_type)` | Fetch content from URLs |
+| `analyze_data(data, analysis_type)` | LLM-powered content analysis |
+| `save_research(topic, findings, filename)` | Save findings to JSON |
+
+## Example Usage
+
+```python
+# Extract content from URL
+result = agent.input("Extract the main content from https://example.com")
+
+# Analyze content
+result = agent.input("Analyze this article and summarize the key points")
+
+# Save research
+result = agent.input("Save our findings about AI trends to a file")
+```
+
+Interactive mode:
+
+```
+You: Get the content from this blog post and summarize it
+Agent: [Fetches URL content]
+       [Analyzes with LLM]
+       Here's a summary of the article...
+
+You: Save this research to ai-trends.json
+Agent: Research saved to ai-trends.json with timestamp
+```
+
+## Use Cases
+
+- Web content extraction
+- Research documentation
+- Content analysis and summarization
+- Data gathering projects
+- Knowledge base building
+
+## Dependencies
+
+- `connectonion`
+- `requests`
+- `python-dotenv`
+
+## Customization
+
+### Add Real Search API
+
+The `search_web` tool is a placeholder. Integrate with search APIs:
+
+```python
+import requests
+
+def search_web(query: str) -> str:
+    """Search the web using Google Custom Search."""
+    api_key = os.getenv("GOOGLE_API_KEY")
+    cx = os.getenv("GOOGLE_CX")
+
+    response = requests.get(
+        "https://www.googleapis.com/customsearch/v1",
+        params={"key": api_key, "cx": cx, "q": query}
+    )
+    return response.json()
+```
+
+Other search API options:
+- Google Custom Search
+- Bing Search API
+- SerpAPI
+- Tavily
+
+### Add More Analysis Types
+
+```python
+def analyze_data(data: str, analysis_type: str = "summary") -> str:
+    """Analyze data with different strategies."""
+    prompts = {
+        "summary": "Summarize this content:",
+        "sentiment": "Analyze the sentiment:",
+        "entities": "Extract key entities:",
+        "facts": "List key facts:",
+    }
+    prompt = prompts.get(analysis_type, prompts["summary"])
+    return llm_do(f"{prompt}\n\n{data}")
+```
+
+### Structured Output
+
+```python
+from typing import Dict, List
+
+def save_research(topic: str, findings: str, filename: str = None) -> Dict:
+    """Save research with structured metadata."""
+    research = {
+        "topic": topic,
+        "findings": findings,
+        "timestamp": datetime.now().isoformat(),
+        "sources": [],  # Add source tracking
+        "tags": [],     # Add categorization
+    }
+    # Save to JSON
+    return research
+```
+
+## Tips
+
+- Add error handling for failed HTTP requests
+- Implement rate limiting for API calls
+- Cache results to avoid duplicate requests
+- Track sources for citation
+
+## Next Steps
+
+- [Tools](../concepts/tools.md) - Add custom tools
+- [llm_do](../concepts/llm_do.md) - One-shot LLM calls
+- [Playwright Template](playwright.md) - For dynamic content

connectonion/docs/tui/README.md

@@ -0,0 +1,95 @@
+# TUI Components
+
+Terminal UI components for interactive agent interfaces.
+
+## Quick Reference
+
+| Component | Purpose | Import |
+|-----------|---------|--------|
+| [Chat](chat.md) | Full chat interface with agent | `from connectonion.tui import Chat` |
+| [Input](input.md) | Text input with autocomplete | `from connectonion.tui import Input` |
+| [pick](pick.md) | Single-select menu | `from connectonion.tui import pick` |
+| [Dropdown](dropdown.md) | Dropdown menus | `from connectonion.tui import Dropdown` |
+| [StatusBar](status_bar.md) | Powerline-style status | `from connectonion.tui import StatusBar` |
+| [Footer](footer.md) | Footer with help text | `from connectonion.tui import Footer` |
+| [Divider](divider.md) | Visual dividers | `from connectonion.tui import Divider` |
+| [fuzzy](fuzzy.md) | Fuzzy matching | `from connectonion.tui import fuzzy_match` |
+| [keys](keys.md) | Keyboard input | `from connectonion.tui import getch` |
+| [providers](providers.md) | Autocomplete data sources | `from connectonion.tui import FileProvider` |
+
+## Quick Start
+
+```python
+from connectonion import Agent
+from connectonion.tui import Chat
+
+# Create agent
+agent = Agent("assistant", tools=[...])
+
+# Launch chat interface
+chat = Chat(
+    agent=agent,
+    title="My Assistant",
+    welcome="Hello! How can I help?",
+    hints=["/ commands", "Enter send", "Ctrl+D quit"],
+)
+chat.run()
+```
+
+## Customizing Components
+
+Need to modify a TUI component? Copy it to your project:
+
+```bash
+# Copy Chat interface to ./tui/
+co copy chat
+
+# Copy other components
+co copy chat fuzzy dropdown
+
+# See all available
+co copy --list
+```
+
+Then import from your local copy:
+
+```python
+# Before (from package)
+from connectonion.tui import Chat
+
+# After (from your copy)
+from tui.chat import Chat  # Customize freely!
+```
+
+## Chat Features
+
+The `Chat` component includes:
+- **Status bar** - Agent name, status, model, tokens, cost
+- **Message history** - Scrollable conversation
+- **Thinking indicator** - Shows LLM thinking and tool calls
+- **Autocomplete** - Trigger-based (/, @) command completion
+- **Input locking** - Prevents multiple submissions
+
+### Thinking Indicator
+
+Shows real-time progress:
+
+```
+⠹ Thinking... 5s (usually 3-10s)    # During LLM call
+
+⠹ Search emails in inbox            # During tool call
+  └─ search_emails("aaron")
+```
+
+## Architecture
+
+```
+User Input → TUI Component → Terminal (Rich/Textual) → User
+     ↑                              ↓
+     └──── Keyboard Events ────────┘
+```
+
+Components use:
+- **Textual** for full interactive apps (Chat)
+- **Rich** for simple terminal rendering
+- **Raw mode** for keyboard capture

connectonion/docs/tui/chat.md

@@ -0,0 +1,181 @@
+# Chat
+
+Full-featured terminal chat interface for AI agents.
+
+## Quick Start
+
+```python
+from connectonion import Agent
+from connectonion.tui import Chat
+
+agent = Agent("assistant", tools=[search, analyze])
+
+chat = Chat(agent=agent)
+chat.run()
+```
+
+## Installation
+
+```bash
+pip install connectonion[tui]
+# or
+pip install textual textual-autocomplete
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `agent` | Agent | ConnectOnion agent instance |
+| `handler` | Callable | Custom message handler (alternative to agent) |
+| `title` | str | Window title |
+| `welcome` | str | Welcome message (markdown supported) |
+| `hints` | list[str] | Footer hints like `["/ commands", "Enter send"]` |
+| `triggers` | dict | Autocomplete triggers (see below) |
+| `on_error` | Callable | Custom error handler |
+
+## Autocomplete Triggers
+
+Add command or mention autocomplete:
+
+```python
+from connectonion.tui import Chat, CommandItem
+from textual_autocomplete import DropdownItem
+
+chat = Chat(
+    agent=agent,
+    triggers={
+        "/": [
+            CommandItem(main="/help", prefix="?", id="/help"),
+            CommandItem(main="/clear", prefix="⌫", id="/clear"),
+            CommandItem(main="/quit", prefix="→", id="/quit"),
+        ],
+        "@": [
+            DropdownItem(main="John", id="@john@example.com"),
+            DropdownItem(main="Jane", id="@jane@example.com"),
+        ],
+    }
+)
+```
+
+## Custom Commands
+
+Register slash command handlers:
+
+```python
+chat = Chat(agent=agent)
+
+@chat.command("/help")
+def show_help(text):
+    return "Available commands: /help, /clear, /quit"
+
+@chat.command("/clear")
+def clear_chat(text):
+    # Clear logic
+    return "Chat cleared"
+
+chat.run()
+```
+
+## Status Bar
+
+Shows real-time information:
+
+```
+🤖 Assistant    ◐ Thinking (1/10)    co/gpt-4  1,234 tok  $0.0012
+```
+
+- **Left**: Agent name
+- **Center**: Current status with iteration
+- **Right**: Model, token count, cost
+
+## Thinking Indicator
+
+Visual feedback during processing:
+
+```
+⠹ Thinking... 5s (usually 3-10s)
+```
+
+During tool execution:
+
+```
+⠹ Search emails in inbox
+  └─ search_emails("aaron")
+```
+
+Shows:
+- Description (what's happening)
+- Function call (technical detail)
+
+## Customizing
+
+Copy and modify:
+
+```bash
+co copy chat
+```
+
+Then edit `./tui/chat.py`:
+
+```python
+from tui.chat import Chat, ThinkingIndicator
+
+# Customize ThinkingIndicator
+class MyThinkingIndicator(ThinkingIndicator):
+    frames = ["◐", "◓", "◑", "◒"]  # Custom spinner
+
+# Use in your Chat subclass
+```
+
+## Example: Gmail Agent
+
+```python
+from connectonion import Agent
+from connectonion.tui import Chat, CommandItem
+from connectonion.useful_tools import Gmail
+
+gmail = Gmail()
+agent = Agent("gmail-agent", tools=[gmail])
+
+chat = Chat(
+    agent=agent,
+    title="Gmail Agent",
+    welcome="**Gmail Assistant**\n\nI can search, read, and send emails.",
+    hints=["/ commands", "@ mentions", "Enter send"],
+    triggers={
+        "/": [
+            CommandItem(main="/inbox", prefix="📥", id="/inbox"),
+            CommandItem(main="/sent", prefix="📤", id="/sent"),
+            CommandItem(main="/compose", prefix="✏️", id="/compose"),
+        ]
+    }
+)
+
+chat.run()
+```
+
+## Widgets
+
+Chat includes these widgets (all exported):
+
+| Widget | Purpose |
+|--------|---------|
+| `ChatStatusBar` | Top status bar |
+| `HintsFooter` | Bottom hints |
+| `WelcomeMessage` | Initial welcome |
+| `UserMessage` | User message bubble |
+| `AssistantMessage` | Agent response |
+| `ThinkingIndicator` | Processing animation |
+| `TriggerAutoComplete` | Trigger-based autocomplete |
+
+Import individually:
+
+```python
+from connectonion.tui import (
+    Chat,
+    ChatStatusBar,
+    ThinkingIndicator,
+    TriggerAutoComplete,
+)
+```

connectonion/docs/tui/divider.md

@@ -0,0 +1,63 @@
+# Divider
+
+Simple horizontal line separator.
+
+## Quick Start
+
+```python
+from connectonion.tui import Divider
+from rich.console import Console
+
+console = Console()
+
+divider = Divider()
+console.print(divider.render())
+```
+
+## Output
+
+```
+────────────────────────────────────────
+```
+
+## Configuration
+
+```python
+# Custom width
+divider = Divider(width=20)
+
+# Custom character
+divider = Divider(char="═")
+
+# Custom style
+divider = Divider(style="bold cyan")
+```
+
+## API
+
+```python
+Divider(
+    width: int = 40,
+    char: str = "─",
+    style: str = "dim",
+)
+```
+
+### Methods
+
+```python
+divider.render() -> Text  # Returns Rich Text object
+```
+
+## Usage Example
+
+```python
+from connectonion.tui import Divider, StatusBar
+from rich.console import Console
+
+console = Console()
+
+console.print(Divider().render())
+console.print(StatusBar([("🤖", "gpt-4", "magenta")]).render())
+console.print(Divider().render())
+```