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

connectonion/docs/principles.md

@@ -0,0 +1,124 @@
+# Documentation Principles
+
+## Core Philosophy
+
+**"Show, don't tell"** - Every concept should be immediately usable.
+
+## The 7 Principles
+
+### 1. Start with Success
+```markdown
+BAD:  "ConnectOnion uses function-based tools with automatic schema generation..."
+GOOD: "Build your first AI agent in 60 seconds."
+```
+
+### 2. One Concept Per Page
+```markdown
+BAD:  "Agents, Tools, and History" (one page)
+GOOD: "Agents" | "Tools" | "History" (separate pages)
+```
+
+### 3. Code First, Explanation Second
+```markdown
+GOOD:
+```python
+@xray
+def my_tool():
+    print(xray.task)  # "User's request"
+```
+That's it! Add @xray to see inside.
+
+BAD:
+"The xray decorator provides introspection capabilities..."
+```
+
+### 4. Progressive Disclosure
+```
+Level 1: Quick Start (60 seconds)
+Level 2: Basic Usage (5 minutes)  
+Level 3: Advanced Patterns (when needed)
+```
+
+### 5. Real Output, Not Promises
+```markdown
+GOOD: 
+Task: "Find Python tutorials"
+[1] • 45ms search(query="Python tutorials")
+      OUT ← "Found 10 tutorials..."
+
+BAD:
+"The trace function will show execution details"
+```
+
+### 6. Practical Examples Only
+```markdown
+GOOD: "Check why emergency_shutdown() was called"
+BAD:  "Process abstract data with generic handler"
+```
+
+### 7. Scannable Structure
+```markdown
+GOOD:
+## Quick Start        (2 lines of code)
+## What You Get       (bullet points)
+## Real Example       (10 lines max)
+## Tips              (4 items max)
+
+BAD:
+Long paragraphs explaining theory...
+```
+
+## Writing Checklist
+
+Before publishing any doc:
+
+- [ ] Can someone use this in 60 seconds?
+- [ ] Is the first example under 5 lines?
+- [ ] Does it show real output?
+- [ ] One main concept only?
+- [ ] Mobile-friendly line lengths?
+- [ ] Would I read this if I was in a hurry?
+
+## Examples of Good Docs
+
+### Quick Start Pattern
+```
+1. Show minimal working code (3-5 lines)
+2. Show output
+3. Say "That's it!"
+4. Then explain what happened
+```
+
+### Feature Introduction Pattern
+```
+1. One-line description
+2. Simplest possible example
+3. What you can do with it (bullets)
+4. Common use cases (2-3)
+5. Link to more if needed
+```
+
+### API Reference Pattern
+```
+1. Function signature
+2. One-line description
+3. Minimal example
+4. Parameters table
+5. Return value
+```
+
+## What to Avoid
+
+❌ **Theory before practice**
+❌ **Multiple concepts per section**
+❌ **Examples over 20 lines**
+❌ **Unexplained output**
+❌ **Abstract examples**
+❌ **Dense paragraphs**
+❌ **Assuming prior knowledge**
+
+## Remember
+
+> "The best documentation is the code itself. The second best is showing the code in action."
+
+Every doc should make someone think: "Wow, that's simple!"

connectonion/docs/quickstart.md

@@ -0,0 +1,261 @@
+# Quick Start
+
+Build your first AI agent in 60 seconds.
+
+## Install
+
+```bash
+pip install connectonion
+```
+
+## Quick Start with CLI
+
+The fastest way to start is with the ConnectOnion CLI:
+
+```bash
+# Create a new agent project
+co create my-agent
+
+# Navigate to the project
+cd my-agent
+
+# Run your agent (API key setup is automatic!)
+python agent.py
+```
+
+That's it! You now have a working agent ready to use. 🎉
+
+## Manual Setup (Alternative)
+
+```python
+from connectonion import Agent
+
+# Define what your agent can do
+def calculate(expression: str) -> str:
+    """Do math calculations."""
+    return str(eval(expression))
+
+# Create your agent
+agent = Agent(
+    "assistant", 
+    tools=[calculate],
+    max_iterations=5  # Simple calculations don't need many iterations
+)
+
+# Use it!
+result = agent.input("What is 42 * 17?")
+print(result)
+```
+
+**Output:**
+
+```
+To calculate 42 * 17, I'll use the calculator tool.
+
+The result is 714.
+```
+
+That's it! You just built an AI agent that can use tools. 🎉
+
+## Add More Tools
+
+Want your agent to do more? Just add more functions:
+
+```python
+def search(query: str) -> str:
+    """Search the web."""
+    return f"Results for {query}: [simulated results]"
+
+def get_time() -> str:
+    """Get current time."""
+    from datetime import datetime
+    return datetime.now().strftime("%I:%M %p")
+
+# Create a more capable agent
+agent = Agent(
+    name="assistant",
+    tools=[calculate, search, get_time],
+    max_iterations=10  # Default for general purpose agents
+)
+
+# It can use multiple tools in one request!
+result = agent.input("Search for Python tutorials and tell me what time it is")
+print(result)
+```
+
+## Make It Yours
+
+Give your agent a personality with flexible system prompts:
+
+```python
+# Option 1: Direct string
+agent = Agent(
+    name="friendly_bot",
+    system_prompt="You are a cheerful assistant who loves to help!",
+    tools=[calculate, search, get_time]
+)
+
+# Option 2: Load from file (auto-detected)
+agent = Agent(
+    name="expert_bot",
+    system_prompt="prompts/expert.md",  # Loads from file
+    tools=[calculate, search, get_time]
+)
+
+# Option 3: Using Path object
+from pathlib import Path
+agent = Agent(
+    name="custom_bot",
+    system_prompt=Path("prompts/custom_personality.txt"),
+    tools=[calculate, search, get_time]
+)
+
+result = agent.input("Hello!")
+# Response will reflect the personality defined in your prompt
+```
+
+## Track Everything (Automatic!)
+
+ConnectOnion tracks all agent behavior automatically:
+
+```python
+# See what your agent has been doing
+print(agent.history.summary())
+```
+
+**Output:**
+
+```
+Agent: assistant
+Total tasks: 3
+Tools used: calculate (2), search (1), get_time (1)
+Activity logged to: .co/logs/assistant.log
+```
+
+## Real Example
+
+Here's a practical agent in ~10 lines:
+
+```python
+from connectonion import Agent
+
+def write_file(filename: str, content: str) -> str:
+    """Save content to a file."""
+    with open(filename, 'w') as f:
+        f.write(content)
+    return f"Saved to {filename}"
+
+def read_file(filename: str) -> str:
+    """Read a file."""
+    with open(filename, 'r') as f:
+        return f.read()
+
+# Create a file assistant
+assistant = Agent(
+    "file_helper", 
+    tools=[write_file, read_file],
+    max_iterations=8  # File operations are usually straightforward
+)
+
+# Use it
+assistant.input("Save 'Hello World' to greeting.txt")
+assistant.input("What's in greeting.txt?")
+```
+
+## CLI Templates
+
+ConnectOnion provides different templates for common use cases:
+
+```bash
+# Create with minimal template (default)
+co create my-agent
+
+# Create with playwright template
+co create my-browser-bot --template playwright
+
+# Initialize in existing directory
+co init  # Adds .co folder only
+co init --template playwright  # Adds full template
+```
+
+## Copy & Customize Built-in Tools
+
+Want to customize a built-in tool? Copy it to your project:
+
+```bash
+# See what's available
+co copy --list
+
+# Copy a tool to ./tools/
+co copy Gmail
+
+# Copy a plugin to ./plugins/
+co copy re_act
+
+# Copy multiple items
+co copy Gmail Shell memory
+```
+
+Then import from your local copy instead:
+
+```python
+# Before (from package)
+from connectonion import Gmail
+
+# After (from your copy)
+from tools.gmail import Gmail  # Now you can customize it!
+```
+
+### What Gets Created
+
+```
+my-agent/
+├── agent.py                                              # Main agent implementation
+├── .env                                                  # API keys (auto-configured)
+├── co-vibecoding-principles-docs-contexts-all-in-one.md  # Complete framework docs
+├── .gitignore                                            # Git configuration
+└── .co/                                                  # ConnectOnion metadata
+    ├── config.toml
+    └── docs/
+        └── co-vibecoding-principles-docs-contexts-all-in-one.md
+```
+
+Learn more about templates in the [Templates Documentation](templates/).
+
+## Next Steps
+
+Ready for more?
+
+- **[CLI Reference](cli/)** - All CLI commands and options
+- **[Templates](templates/)** - Pre-built agent templates
+- **[Agent Guide](concepts/agent.md)** - How agents work
+- **[Tools Guide](concepts/tools.md)** - How tools work
+- **[Examples](examples.md)** - Copy-paste ready code
+- **[API Reference](api.md)** - Detailed documentation
+
+## Quick Tips
+
+1. **Functions = Tools** (no classes needed!)
+2. **Docstrings = Descriptions** (agent reads these)
+3. **Type hints = Better results** (helps agent understand)
+4. **Logging = Free** (automatic activity tracking to `.co/logs/`)
+
+---
+
+## Troubleshooting
+
+### "API key not found"
+Make sure you:
+1. Copied `.env.example` to `.env`
+2. Added your actual API key
+3. Are running from the project directory
+
+### "Permission denied"
+Ensure you have write permissions in the current directory.
+
+### "Module not found"
+Install ConnectOnion: `pip install connectonion`
+
+---
+
+**Need help?** Check our [examples](examples.md) or [join Discord](https://discord.gg/4xfD9k8AUF) for support.

connectonion/docs/roadmap.md

@@ -0,0 +1,81 @@
+# Roadmap
+
+ConnectOnion's development roadmap. Track progress on [GitHub](https://github.com/openonion/connectonion/milestones).
+
+## Current Milestones
+
+### Launch the Network (Q4 2025)
+
+Implement the ConnectOnion peer-to-peer network protocol where agents discover and collaborate using public keys as addresses.
+
+**Features:**
+- Message-based architecture (ANNOUNCE/FIND/TASK)
+- Relay nodes for NAT traversal
+- Encrypted peer-to-peer communication
+- Contact/stranger management
+- Managed keys API (`co/` prefix) - **Done**
+
+### Multi-Agent Trust System (Q1 2026)
+
+Build a trust system for secure multi-agent collaboration.
+
+**Features:**
+- Agent-to-agent trust verification
+- Trust levels for remote agents (open/tested/strict)
+- Behavior-based trust scoring
+- Trust policies for agent networks
+
+### co deploy - Agent Deployment (Q1 2026)
+
+One-command deployment for production agents.
+
+**Features:**
+- `co deploy` CLI command
+- Deploy to cloud providers (AWS, GCP, etc.)
+- Automatic HTTPS and domain setup
+- Environment management (dev/staging/prod)
+- Health monitoring and auto-restart
+
+### AI Auto-Coding (Q2 2026)
+
+Enable AI agents to automatically write, debug, and improve code.
+
+**Features:**
+- `auto_debug_exception` for runtime debugging - **Done**
+- Code generation tools
+- Automated testing
+- AI-powered refactoring
+
+## Open Features
+
+### Debugging & Development
+- [ ] Implement AI Help Mode for interactive debugging assistance
+- [ ] Implement step mode for debugging all tool executions
+- [ ] Implement modify result command for time-travel debugging
+- [ ] Implement inspect command for viewing agent state
+- [ ] Implement retry command for re-executing tools
+- [ ] Implement update prompt command for mid-execution changes
+
+### Documentation
+- [ ] Create tutorial video series
+- [ ] Update docs website with current features
+- [ ] Create comprehensive auto-debug documentation
+- [ ] Create templates/ documentation folder with individual template guides
+- [ ] Document Claude Code plugin templates for AI vibe coding
+
+### Platform
+- [ ] Add Microsoft OAuth integration (`co auth microsoft`)
+- [ ] Add conflict detection for duplicate tool names
+- [ ] Session logging and eval system
+
+## Recently Completed
+
+- Google OAuth integration (`co auth google`)
+- React-mode plugin example
+- Managed keys API (`co/` prefix)
+- Auto-detect base64 image results for vision models
+- Network feature API design (serve/connect)
+
+## Contributing
+
+Want to contribute? Check [open issues](https://github.com/openonion/connectonion/issues) or join our [Discord](https://discord.gg/4xfD9k8AUF).

connectonion/docs/templates/README.md

@@ -0,0 +1,77 @@
+# Templates
+
+Pre-built agent templates for common use cases. Create a new project with:
+
+```bash
+co create my-agent --template <template-name>
+```
+
+## Template Selection Guide
+
+| Template | Best For | Key Tools |
+|----------|----------|-----------|
+| [minimal](minimal.md) | Getting started, learning | `calculator` |
+| [playwright](playwright.md) | Web automation, scraping | Browser control, screenshots |
+| [meta-agent](meta-agent.md) | Building agents, dev assistance | Docs search, shell, todos |
+| [web-research](web-research.md) | Research, data extraction | Web search, analysis |
+
+## Quick Comparison
+
+### minimal
+Simple starting point with one tool. Perfect for learning ConnectOnion basics.
+
+```bash
+co create my-bot --template minimal
+```
+
+### playwright
+Full browser automation with 11 tools. Scrape websites, fill forms, take screenshots.
+
+```bash
+co create browser-bot --template playwright
+```
+
+### meta-agent
+Development assistant that knows ConnectOnion. Query docs, run shell commands, manage todos.
+
+```bash
+co create dev-helper --template meta-agent
+```
+
+### web-research
+Research and data extraction. Search web, extract content, save findings.
+
+```bash
+co create researcher --template web-research
+```
+
+## Creating Custom Templates
+
+Start with any template and customize:
+
+1. Create project: `co create my-agent --template minimal`
+2. Add tools to `agent.py`
+3. Update `prompt.md` for agent personality
+4. Add dependencies to `requirements.txt`
+
+See [Tools](../concepts/tools.md) for creating custom tools.
+
+## What Each Template Includes
+
+```
+my-agent/
+├── agent.py            # Agent with tools
+├── prompt.md           # System prompt (optional)
+├── .env                # API keys
+├── .co/
+│   ├── config.toml     # Project config
+│   └── docs/           # ConnectOnion docs for AI
+├── requirements.txt    # Dependencies
+└── README.md           # Project documentation
+```
+
+## Next Steps
+
+- [CLI Create Command](../cli/create.md) - Full `co create` options
+- [Tools Documentation](../concepts/tools.md) - Creating custom tools
+- [Prompts](../concepts/prompts.md) - Customizing agent behavior

connectonion/docs/templates/meta-agent.md

@@ -0,0 +1,152 @@
+# Meta-Agent Template
+
+Development assistant that knows ConnectOnion. Query docs, run commands, manage tasks.
+
+## Quick Start
+
+```bash
+co create dev-helper --template meta-agent
+cd dev-helper
+python agent.py
+```
+
+## What You Get
+
+```
+dev-helper/
+├── agent.py            # Meta-agent with 7 tools
+├── prompts/
+│   ├── metagent.md           # Main system prompt
+│   ├── answer_prompt.md      # Answer generation rules
+│   ├── docs_retrieve_prompt.md  # Doc extraction prompt
+│   └── think_prompt.md       # Reflection strategy
+├── .env                # API keys
+├── .co/
+│   └── docs/           # ConnectOnion documentation
+└── README.md           # Project docs
+```
+
+## Tools Included
+
+| Tool | Description |
+|------|-------------|
+| `answer_connectonion_question(question)` | Search docs and answer ConnectOnion questions |
+| `think(context)` | Self-reflection on current progress |
+| `add_todo(task)` | Add task to todo.md |
+| `delete_todo(task)` | Remove task from todo.md |
+| `list_todos()` | View current todo list |
+| `run_shell(command, timeout, cwd)` | Execute shell commands |
+
+## Example Usage
+
+```python
+# Ask about ConnectOnion
+result = agent.input("How do I add tools to an agent?")
+
+# Get project planning help
+result = agent.input("Create a todo list for building an email automation agent")
+
+# Run shell commands
+result = agent.input("Run 'pip list' to show installed packages")
+
+# Reflect on progress
+result = agent.input("Think about what we've accomplished so far")
+```
+
+Interactive mode:
+
+```
+You: How do events work in ConnectOnion?
+Agent: [Searches embedded documentation]
+       Events are lifecycle hooks that trigger at specific points...
+
+You: Add a todo to implement the search feature
+Agent: Added "Implement the search feature" to todo.md
+
+You: Run pytest to check our tests
+Agent: [Executes: pytest]
+       All tests passed!
+```
+
+## Use Cases
+
+- Learning ConnectOnion framework
+- Development assistance
+- Project planning with todos
+- Running shell commands
+- Code generation guidance
+- Architecture questions
+
+## Dependencies
+
+- `connectonion`
+- `python-dotenv`
+
+## How It Works
+
+### Documentation Search
+
+The agent searches `.co/docs/connectonion.md` to answer framework questions:
+
+1. Extracts relevant sections from docs
+2. Uses LLM to formulate answer
+3. Returns comprehensive response
+
+### Todo Management
+
+Tasks are stored in `todo.md`:
+
+```markdown
+# Todo
+
+- [ ] Implement search feature
+- [ ] Add unit tests
+- [x] Setup project structure
+```
+
+### Shell Execution
+
+Cross-platform shell commands:
+- macOS/Linux: Uses bash
+- Windows: Uses PowerShell
+
+## Customization
+
+### Add Project-Specific Knowledge
+
+Add documentation to `.co/docs/` folder:
+
+```
+.co/docs/
+├── connectonion.md     # Framework docs
+├── project-guide.md    # Your project docs
+└── api-reference.md    # Your API docs
+```
+
+### Modify System Prompts
+
+Edit files in `prompts/` folder to customize behavior:
+
+- `metagent.md` - Main personality and capabilities
+- `answer_prompt.md` - How to answer questions
+- `think_prompt.md` - Reflection strategy
+
+### Add Custom Tools
+
+```python
+def deploy(environment: str = "staging") -> str:
+    """Deploy the application."""
+    # Your deployment logic
+    return f"Deployed to {environment}"
+
+agent = Agent(
+    "meta-agent",
+    tools=[..., deploy]
+)
+```
+
+## Next Steps
+
+- [Tools](../concepts/tools.md) - Add custom tools
+- [Prompts](../concepts/prompts.md) - Customize agent behavior
+- [XRay Debugging](../debug/xray.md) - Debug with @xray decorator