connectonion 0.5.8__py3-none-any.whl

connectonion/cli/docs.md

@@ -0,0 +1,123 @@
+# ConnectOnion Framework - Complete Reference
+
+## What is ConnectOnion?
+
+ConnectOnion is a simple Python framework for creating AI agents that can use tools and track their behavior.
+
+**Key Principles:**
+- Keep simple things simple, make hard things possible
+- Function-based tools are preferred over classes
+- Activity logging to .co/logs/ (Python SDK only)
+- Default settings work for most use cases
+
+## Quick Start
+
+```python
+from connectonion import Agent
+
+# Define tools as regular functions
+def search(query: str) -> str:
+    '''Search for information.'''
+    return f"Found information about {query}"
+
+# Create agent
+agent = Agent(
+    name="my_assistant",
+    system_prompt="prompt.md",  # Always use markdown files for prompts
+    tools=[search]
+)
+
+# Use agent
+result = agent.input("Search for Python tutorials")
+```
+
+## Core Concepts
+
+### Tools
+Tools are just Python functions with type hints:
+```python
+def my_tool(param: str, optional: int = 10) -> str:
+    '''This docstring becomes the tool description.'''
+    return f"Result: {param}"
+```
+
+### System Prompts
+Always use markdown files for system prompts:
+```python
+agent = Agent(
+    name="assistant",
+    system_prompt="prompt.md",  # Best practice
+    tools=[...]
+)
+```
+
+### max_iterations
+Controls how many tool calls the agent can make:
+- Simple tasks: 3-5 iterations
+- Standard workflows: 10-15 iterations
+- Complex analysis: 20-40 iterations
+
+## Common Patterns
+
+### Calculator Bot
+```python
+def calculate(expression: str) -> float:
+    '''Perform math calculations.'''
+    return eval(expression)  # Use safely
+
+agent = Agent("calc", tools=[calculate], max_iterations=5)
+```
+
+### Research Assistant
+```python
+def web_search(query: str) -> str:
+    '''Search the web.'''
+    return f"Results for {query}"
+
+def summarize(text: str) -> str:
+    '''Summarize text.'''
+    return f"Summary: {text[:100]}..."
+
+agent = Agent("researcher", tools=[web_search, summarize], max_iterations=20)
+```
+
+## Debugging with @xray
+
+See inside your agent's mind:
+```python
+from connectonion.decorators import xray
+
+@xray
+def my_tool(text: str) -> str:
+    print(xray.agent.name)    # Agent name
+    print(xray.task)          # Original request
+    print(xray.iteration)     # Current iteration
+    return "Done"
+```
+
+## Best Practices
+
+1. **Use type hints** - Required for all tools
+2. **Write clear docstrings** - They become tool descriptions
+3. **Handle errors gracefully** - Return error messages, don't raise
+4. **Use markdown for prompts** - Keep prompts separate from code
+5. **Set appropriate iterations** - Match complexity of task
+
+## Activity Logging
+
+All agent activities are automatically logged to `.co/logs/{name}.log`:
+```python
+# Logs are written to .co/logs/ directory by default
+# Each agent gets its own log file: .co/logs/{agent_name}.log
+
+# You can customize logging:
+agent = Agent("assistant", log=False)  # Disable logging
+agent = Agent("assistant", log=True)   # Log to {name}.log in current dir
+agent = Agent("assistant", log="custom.log")  # Custom log path
+```
+
+## Full Documentation
+
+For complete documentation, visit: https://github.com/connectonion/connectonion
+
+This embedded reference helps your agent understand and use ConnectOnion effectively.

connectonion/cli/main.py

@@ -0,0 +1,148 @@
+"""
+Purpose: Entry point for ConnectOnion CLI application using Typer framework with Rich formatting
+LLM-Note:
+  Dependencies: imports from [typer, rich.console, typing, __version__] | imported by [setup.py entry_points, __main__.py] | loads commands from [cli/commands/{init, create, deploy, auth, status, reset, doctor, browser}_commands.py] | tested by [tests/cli/test_cli_help.py]
+  Data flow: cli() entry point → creates Typer app → registers command callbacks (init, create, deploy, auth, status, reset, doctor, browser) → Typer parses args → invokes corresponding handle_*() function from commands module → command outputs via rich.Console
+  State/Effects: no persistent state | writes to stdout via rich.Console | lazy imports command handlers on invocation | registers typer.Option and typer.Argument decorators | uses typer.Exit() for early termination
+  Integration: exposes cli() entry point registered in setup.py as 'co' command | app() is the Typer instance | commands: init, create, deploy, auth [google|microsoft], status, reset, doctor, browser | --version flag shows version | -b/--browser flag shortcuts browser command | no args shows custom help via _show_help()
+  Performance: fast startup (lazy imports) | Typer arg parsing is O(n) args | Rich console initialization is lightweight
+  Errors: typer.Exit() on --version or --browser | invalid commands show Typer error with suggestions | command-specific errors handled in respective handlers
+"""
+
+import typer
+from rich.console import Console
+from typing import Optional
+
+from .. import __version__
+
+console = Console()
+app = typer.Typer(add_completion=False, no_args_is_help=False)
+
+
+def version_callback(value: bool):
+    if value:
+        console.print(f"co {__version__}")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(False, "--version", "-v", callback=version_callback, is_eager=True),
+    browser: Optional[str] = typer.Option(None, "-b", "--browser", help="Quick browser command"),
+):
+    """ConnectOnion - A simple Python framework for creating AI agents."""
+    if browser:
+        from .commands.browser_commands import handle_browser
+        handle_browser(browser)
+        raise typer.Exit()
+    if ctx.invoked_subcommand is None:
+        _show_help()
+
+
+def _show_help():
+    """Show help message."""
+    console.print()
+    console.print(f"[bold cyan]co[/bold cyan] - ConnectOnion v{__version__}")
+    console.print()
+    console.print("A simple Python framework for creating AI agents.")
+    console.print()
+    console.print("[bold]Quick Start:[/bold]")
+    console.print("  [cyan]co create my-agent[/cyan]                Create new agent project")
+    console.print("  [cyan]cd my-agent && python agent.py[/cyan]   Run your agent")
+    console.print()
+    console.print("[bold]Commands:[/bold]")
+    console.print("  [green]create[/green]  <name>     Create new project")
+    console.print("  [green]init[/green]              Initialize in current directory")
+    console.print("  [green]deploy[/green]            Deploy to ConnectOnion Cloud")
+    console.print("  [green]auth[/green]              Authenticate for managed keys")
+    console.print("  [green]status[/green]            Check account balance")
+    console.print("  [green]doctor[/green]            Diagnose installation")
+    console.print()
+    console.print("[bold]Docs:[/bold] https://docs.connectonion.com")
+    console.print("[bold]Discord:[/bold] https://discord.gg/4xfD9k8AUF")
+    console.print()
+
+
+@app.command()
+def init(
+    template: Optional[str] = typer.Option(None, "-t", "--template", help="Template: minimal, playwright, custom"),
+    yes: bool = typer.Option(False, "-y", "--yes", help="Skip prompts"),
+    key: Optional[str] = typer.Option(None, "--key", help="API key"),
+    description: Optional[str] = typer.Option(None, "--description", help="Description for custom template"),
+    force: bool = typer.Option(False, "--force", help="Overwrite existing files"),
+):
+    """Initialize project in current directory."""
+    from .commands.init import handle_init
+    handle_init(ai=None, key=key, template=template, description=description, yes=yes, force=force)
+
+
+@app.command()
+def create(
+    name: Optional[str] = typer.Argument(None, help="Project name"),
+    template: Optional[str] = typer.Option(None, "-t", "--template", help="Template: minimal, playwright, custom"),
+    yes: bool = typer.Option(False, "-y", "--yes", help="Skip prompts"),
+    key: Optional[str] = typer.Option(None, "--key", help="API key"),
+    description: Optional[str] = typer.Option(None, "--description", help="Description for custom template"),
+):
+    """Create new project."""
+    from .commands.create import handle_create
+    handle_create(name=name, ai=None, key=key, template=template, description=description, yes=yes)
+
+
+@app.command()
+def deploy():
+    """Deploy to ConnectOnion Cloud."""
+    from .commands.deploy_commands import handle_deploy
+    handle_deploy()
+
+
+@app.command()
+def auth(service: Optional[str] = typer.Argument(None, help="Service: google, microsoft")):
+    """Authenticate with OpenOnion."""
+    if service == "google":
+        from .commands.auth_commands import handle_google_auth
+        handle_google_auth()
+    elif service == "microsoft":
+        from .commands.auth_commands import handle_microsoft_auth
+        handle_microsoft_auth()
+    else:
+        from .commands.auth_commands import handle_auth
+        handle_auth()
+
+
+@app.command()
+def status():
+    """Check account status."""
+    from .commands.status_commands import handle_status
+    handle_status()
+
+
+@app.command()
+def reset():
+    """Reset account (destructive)."""
+    from .commands.reset_commands import handle_reset
+    handle_reset()
+
+
+@app.command()
+def doctor():
+    """Diagnose installation."""
+    from .commands.doctor_commands import handle_doctor
+    handle_doctor()
+
+
+@app.command()
+def browser(command: str = typer.Argument(..., help="Browser command")):
+    """Browser automation."""
+    from .commands.browser_commands import handle_browser
+    handle_browser(command)
+
+
+def cli():
+    """Entry point."""
+    app()
+
+
+if __name__ == "__main__":
+    cli()

connectonion/cli/templates/meta-agent/README.md

@@ -0,0 +1,287 @@
+# ConnectOnion Agent Project
+
+Welcome to your ConnectOnion agent project! This README will guide you through the project structure and how to get started.
+
+## 🚀 Quick Start
+
+1. **Add your OpenAI API key**:
+   ```bash
+   # Edit .env file (already created for you)
+   # Replace 'sk-your-api-key-here' with your actual OpenAI API key
+   nano .env  # or use any text editor
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   pip install connectonion
+   pip install python-dotenv  # For loading .env files
+   ```
+
+3. **Run your agent**:
+   ```bash
+   python agent.py
+   ```
+
+## 📁 Project Structure
+
+```
+your-project/
+├── agent.py                    # Main agent implementation
+├── prompts/                    # System prompts directory
+│   ├── metagent.md            # Main system prompt
+│   ├── docs_retrieve_prompt.md # Documentation retrieval prompt
+│   ├── answer_prompt.md       # Answer generation prompt
+│   └── think_prompt.md        # Reflection/thinking prompt
+├── .env                       # Environment configuration (add your API key here)
+├── .co/                       # ConnectOnion metadata
+│   ├── config.toml           # Project configuration
+│   ├── keys/                 # Agent cryptographic keys (git-ignored)
+│   └── docs/
+│       └── co-vibecoding-principles-docs-contexts-all-in-one.md  # Complete VibeCoding & framework docs
+├── todo.md                    # To-do list (created by agent)
+└── README.md                  # This file
+```
+
+## 🤖 About the Meta-Agent
+
+The Meta-Agent is your AI assistant specialized in ConnectOnion development. It helps you:
+
+- **Answer questions** about ConnectOnion using embedded documentation
+- **Generate code** for agents, tools, and tests  
+- **Plan projects** with structured to-do lists
+- **Execute commands** cross-platform (bash/PowerShell)
+- **Reflect and think** about task progress
+
+## 🛠️ Available Tools
+
+### Core Documentation Tools
+
+- **`answer_connectonion_question(question)`** - Get expert answers about ConnectOnion
+  - Uses `llm_do()` with intelligent document retrieval
+  - Searches embedded documentation for relevant content
+  - Provides accurate, context-aware responses
+
+- **`extract_relevant_connectonion_text(question)`** - Extract relevant documentation
+  - Internal helper for documentation retrieval
+  - Uses GPT-4o-mini for intelligent extraction
+
+### Task Management
+
+- **`add_todo(task)`** - Add tasks to your to-do list
+- **`delete_todo(task)`** - Remove completed tasks
+- **`list_todos()`** - View current to-do list
+
+### Reflection & Planning
+
+- **`think(context)`** - AI reflection on current progress
+  - Analyzes conversation history
+  - Identifies accomplishments and blockers
+  - Suggests next steps
+
+### System Operations
+
+- **`run_shell(command)`** - Execute shell commands
+  - Cross-platform support (macOS/Linux/Windows)
+  - Returns stdout, stderr, and exit codes
+  - Configurable timeout (default: 120s)
+
+## 🎯 How to Use the Agent
+
+### Interactive Mode
+
+Run the agent and interact via the command line:
+
+```bash
+python agent.py
+```
+
+Example interactions:
+```
+You: How do tools work in ConnectOnion?
+Assistant: [Provides detailed explanation from documentation]
+
+You: Create a to-do list for building a web scraper
+Assistant: [Generates structured task list]
+
+You: Run ls -la to see the files
+Assistant: [Executes command and shows output]
+```
+
+### Programmatic Usage
+
+Import and use the agent in your code:
+
+```python
+from agent import agent
+
+# Ask a question
+result = agent.input("How do I create custom tools?")
+print(result)
+
+# Execute multiple tasks
+agent.input("Add todo: Research web scraping libraries")
+agent.input("Add todo: Create prototype scraper")
+todos = agent.input("List all todos")
+print(todos)
+```
+
+## 📖 VibeCoding Documentation
+
+The `.co/docs/co-vibecoding-principles-docs-contexts-all-in-one.md` file contains complete VibeCoding principles and ConnectOnion framework documentation. This comprehensive guide includes:
+
+- **Framework Overview**: Core concepts and architecture
+- **Agent Development**: Building intelligent agents with tools
+- **LLM Integration**: Using `llm_do()` for AI-powered functionality
+- **Tool System**: Creating and using custom tools
+- **Best Practices**: Design patterns and coding guidelines
+- **API Reference**: Complete API documentation
+
+### 🤖 Using with AI Coding Assistants
+
+If you're using AI-powered coding assistants like **Cursor**, **Claude Code**, or **GitHub Copilot**, you can leverage the Vibe Coding documentation for better assistance:
+
+1. **Point your AI assistant to the doc**: Reference `.co/docs/co-vibecoding-principles-docs-contexts-all-in-one.md` when asking questions about ConnectOnion
+2. **Get framework-specific help**: The documentation helps AI assistants understand ConnectOnion's patterns and best practices
+3. **Consistent coding style**: AI assistants will follow the framework's conventions when generating code
+
+Example prompt for your AI assistant:
+```
+Please read .co/docs/co-vibecoding-principles-docs-contexts-all-in-one.md to understand 
+the ConnectOnion framework and VibeCoding principles, then help me create a custom tool for [your task]
+```
+
+This documentation is embedded locally in your project for offline access. The Meta-Agent can also answer questions about ConnectOnion by referencing this documentation.
+
+## 📚 Understanding the Architecture
+
+### LLM Function (`llm_do`)
+
+The Meta-Agent uses ConnectOnion's `llm_do()` function for intelligent operations:
+
+```python
+from connectonion import llm_do
+
+# Simple usage
+answer = llm_do("What's 2+2?")
+
+# With structured output
+from pydantic import BaseModel
+
+class Analysis(BaseModel):
+    sentiment: str
+    confidence: float
+
+result = llm_do(
+    "I love this product!",
+    output=Analysis
+)
+```
+
+### System Prompts
+
+Prompts are stored as markdown files for better maintainability:
+
+- **`metagent.md`** - Main personality and capabilities
+- **`docs_retrieve_prompt.md`** - Instructions for document extraction
+- **`answer_prompt.md`** - Guidelines for answering questions
+- **`think_prompt.md`** - Framework for reflection
+
+### The Agent Loop
+
+1. User provides input
+2. Agent processes with LLM (GPT-4o-mini by default)
+3. LLM decides which tools to call
+4. Tools execute and return results
+5. Process repeats up to `max_iterations` (15 for Meta-Agent)
+6. Final response returned to user
+
+## 🔧 Customization
+
+### Modify Tools
+
+Edit `agent.py` to add your own tools:
+
+```python
+def my_custom_tool(param: str) -> str:
+    """Description for the LLM."""
+    return f"Processed: {param}"
+
+# Add to agent
+agent = Agent(
+    name="meta_agent",
+    tools=[
+        answer_connectonion_question,
+        think,
+        my_custom_tool,  # Your new tool
+        # ... other tools
+    ]
+)
+```
+
+### Adjust Behavior
+
+Modify system prompts in the `prompts/` directory to change agent personality and behavior.
+
+### Change Models
+
+Update the model parameter:
+
+```python
+agent = Agent(
+    name="meta_agent",
+    model="gpt-4",  # Use GPT-4 instead of GPT-4o-mini
+    # ...
+)
+```
+
+## 📖 Documentation Access
+
+The embedded ConnectOnion documentation is available at:
+`.co/docs/co-vibecoding-principles-docs-contexts-all-in-one.md`
+
+This comprehensive reference includes:
+- Framework overview and concepts
+- API reference
+- Code examples
+- Best practices
+- Troubleshooting guide
+
+The Meta-Agent automatically searches this documentation to answer your questions.
+
+## 🐛 Debugging
+
+Use the `@xray` decorator for debugging tools:
+
+```python
+from connectonion import xray
+
+@xray
+def debug_tool(text: str) -> str:
+    print(f"Agent: {xray.agent.name}")
+    print(f"Task: {xray.task}")
+    print(f"Iteration: {xray.iteration}")
+    return "Done"
+```
+
+## 🔗 Resources
+
+- **GitHub**: https://github.com/openonion/connectonion
+- **Documentation**: https://connectonion.com/docs
+- **PyPI**: https://pypi.org/project/connectonion/
+- **Discord**: https://discord.gg/4xfD9k8AUF
+
+## 💡 Tips
+
+1. **Start Simple**: Test basic commands before complex workflows
+2. **Check Documentation**: Use `answer_connectonion_question()` for framework questions
+3. **Track Progress**: Use the to-do tools to manage tasks
+4. **Review Prompts**: Customize prompts for your specific needs
+5. **Monitor Iterations**: Increase `max_iterations` for complex tasks
+
+## 🤝 Contributing
+
+Feel free to extend this agent with your own tools and improvements. Share your creations with the ConnectOnion community!
+
+## 📝 License
+
+This project uses ConnectOnion, which is open source. Check the main repository for license details.