connectonion 0.5.8__py3-none-any.whl

connectonion/cli/templates/meta-agent/agent.py

@@ -0,0 +1,196 @@
+"""
+Purpose: Development assistant agent with ConnectOnion documentation knowledge and shell execution
+LLM-Note:
+  Dependencies: imports from [connectonion.Agent, connectonion.xray, connectonion.llm_do, json, pathlib, subprocess, platform, shutil] | template file copied by [cli/commands/init.py, cli/commands/create.py]
+  Data flow: user question → Agent.input() → answer_connectonion_question (reads .co/docs/connectonion.md → llm_do extracts relevant text → llm_do generates answer) | run_shell executes commands | todo tools manage todo.md
+  State/Effects: reads/writes todo.md | executes shell commands (cross-platform) | reads documentation files | uses co/gemini-2.5-pro model
+  Integration: template for 'co create --template meta-agent' | tools: answer_connectonion_question, think, add_todo, delete_todo, list_todos, run_shell | uses external prompt files in prompts/
+  Performance: llm_do calls for doc retrieval and answers | shell timeout 120s | max_iterations=15
+  Errors: graceful handling for missing docs | shell command timeout/errors caught | @xray decorator for debugging
+
+Meta-Agent - Your ConnectOnion development assistant with documentation expertise
+"""
+
+from connectonion import Agent, xray
+from connectonion import llm_do
+import json
+from pathlib import Path
+import subprocess
+import platform
+import shutil
+
+@xray
+def extract_relevant_connectonion_text(question: str, docs_path: str = ".co/docs/connectonion.md") -> str:
+    """Load docs and use llm_do to extract relevant text for the question."""
+    try:
+        with open(docs_path, 'r', encoding='utf-8') as f:
+            docs = f.read()
+    except FileNotFoundError:
+        return "ConnectOnion documentation not found. Try running 'co init' again."
+    # Use llm_do with a retrieval prompt file to select relevant content
+    return llm_do(
+        input=f"Question: {question}\n\nDocumentation:\n{docs}",
+        system_prompt="prompts/docs_retrieve_prompt.md",
+        model="co/gpt-4o",
+        temperature=0.1,
+    )
+
+
+@xray
+def answer_connectonion_question(question: str) -> str:
+    """Answer a question using relevant text extracted from documentation via llm_do."""
+    relevant = extract_relevant_connectonion_text(question)
+    return llm_do(
+        input=f"Question: {question}\n\nRelevant context:\n{relevant}",
+        system_prompt="prompts/answer_prompt.md",
+        model="co/gpt-4o",
+        temperature=0.1,
+    )
+
+
+
+@xray
+def think(context: str = "current situation") -> str:
+    """Reflect using llm_do on a simple JSON dump of xray.messages."""
+    transcript = json.dumps(xray.messages or [])
+    return llm_do(
+        input=f"Context: {context}\n\nMessages: {transcript}",
+        system_prompt="prompts/think_prompt.md",
+        model="co/gpt-4o",
+        temperature=0.1,
+    )
+ 
+
+
+def add_todo(task: str) -> str:
+    """Add a to-do item to todo.md as an unchecked task."""
+    if not task or not task.strip():
+        return "Please provide a non-empty task."
+    path = Path(__file__).resolve().parent / "todo.md"
+    if not path.exists():
+        path.write_text("", encoding="utf-8")
+    with path.open("a", encoding="utf-8") as f:
+        f.write(f"- [ ] {task.strip()}\n")
+    return f"Added to-do: {task.strip()}"
+
+
+def delete_todo(task: str) -> str:
+    """Delete the first matching to-do (checked or unchecked) from todo.md."""
+    path = Path(__file__).resolve().parent / "todo.md"
+    if not path.exists():
+        path.write_text("", encoding="utf-8")
+    lines = path.read_text(encoding="utf-8").splitlines()
+    new_lines = []
+    removed = False
+    for line in lines:
+        if (line.startswith("- [ ] ") or line.startswith("- [x] ")) and task in line and not removed:
+            removed = True
+            continue
+        new_lines.append(line)
+    if not removed:
+        return "To-do not found."
+    path.write_text("\n".join(new_lines) + "\n", encoding="utf-8")
+    return f"Deleted to-do: {task}"
+
+
+def list_todos() -> str:
+    """Return the current contents of todo.md or a notice if empty."""
+    path = Path(__file__).resolve().parent / "todo.md"
+    if not path.exists():
+        path.write_text("", encoding="utf-8")
+    content = path.read_text(encoding="utf-8")
+    lines = [ln for ln in content.splitlines() if ln.strip()]
+    if len(lines) == 0:
+        return "No to-dos yet. Use add_todo(task) to add one."
+    return content
+
+
+@xray
+def run_shell(command: str, timeout: int = 120, cwd: str = "") -> str:
+    """Execute a shell command cross-platform and return output.
+    
+    Works on macOS/Linux and Windows. Uses bash/sh when available on *nix,
+    and PowerShell (or cmd) on Windows.
+    """
+    cmd = command.strip()
+    if not cmd:
+        return "No command provided."
+    system = platform.system()
+    if system == "Windows":
+        if shutil.which("powershell"):
+            argv = ["powershell", "-NoProfile", "-NonInteractive", "-Command", cmd]
+        else:
+            argv = ["cmd", "/c", cmd]
+    else:
+        if shutil.which("bash"):
+            argv = ["bash", "-lc", cmd]
+        else:
+            argv = ["sh", "-lc", cmd]
+    try:
+        proc = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            cwd=cwd or None,
+            timeout=timeout
+        )
+        stdout = proc.stdout or ""
+        stderr = proc.stderr or ""
+        return (
+            f"exit_code: {proc.returncode}\n"
+            f"stdout:\n{stdout}\n"
+            f"stderr:\n{stderr}".rstrip()
+        )
+    except subprocess.TimeoutExpired as e:
+        return f"Command timed out after {timeout}s. Partial output:\nstdout:\n{e.stdout or ''}\nstderr:\n{e.stderr or ''}"
+    except Exception as e:
+        return f"Error executing command: {e}"
+
+
+ 
+
+
+# Create the meta-agent with comprehensive ConnectOnion knowledge
+agent = Agent(
+    name="meta_agent",
+    system_prompt="prompts/metagent.md",
+    tools=[
+        answer_connectonion_question,  # Primary documentation tool
+        think,                          # Self-reflection
+        add_todo,
+        delete_todo,
+        list_todos,
+        run_shell
+    ],
+    model="co/gemini-2.5-pro",
+    max_iterations=15  # More iterations for complex assistance
+)
+
+
+if __name__ == "__main__":
+    print("🤖 ConnectOnion Meta-Agent initialized!")
+    print("Your AI assistant for ConnectOnion development\n")
+    print("Available capabilities:")
+    print("📚 Documentation expert - Ask any question about ConnectOnion")
+    print("🔧 Code generation - Create agents, tools, and tests")
+    print("📝 Task planning - Break down complex projects")
+    print("🏗️ Project structure - Get architecture recommendations")
+    print("\nTry: 'How do tools work in ConnectOnion?'")
+    print("     'Create a web scraper agent'")
+    print("     'Generate a tool for sending emails'")
+    
+    # Interactive loop
+    print("\nType 'exit' or 'quit' to end the conversation.")
+    while True:
+        try:
+            user_input = input("\nYou: ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nGoodbye!")
+            break
+        if user_input.lower() in {"exit", "quit"}:
+            print("Goodbye!")
+            break
+        if not user_input:
+            continue
+        assistant_reply = agent.input(user_input)
+        print(f"\nAssistant: {assistant_reply}")

connectonion/cli/templates/meta-agent/prompts/answer_prompt.md

@@ -0,0 +1,9 @@
+# Answer Prompt
+
+You are a precise assistant. Answer the user's question using ONLY the provided relevant context.
+
+Rules:
+- If the context contains the answer, respond concisely and accurately.
+- If the answer is unclear or missing in the context, say: "I don't see that in the provided context."
+- Do not invent details not supported by the context.
+- When helpful, quote short snippets from the context.

connectonion/cli/templates/meta-agent/prompts/docs_retrieve_prompt.md

@@ -0,0 +1,15 @@
+# Documentation Retrieval Prompt
+
+You are a helpful assistant that extracts only the most relevant parts of the provided documentation for answering the user's question.
+
+Input:
+- Question
+- Full documentation text
+
+Task:
+- Return a concise excerpt (≤ 400 words) containing the most relevant paragraphs, bullet lists, or code blocks needed to answer the question.
+- Preserve headings and formatting when useful.
+- Do not invent content. If nothing is relevant, say: "No directly relevant content found."
+
+Output:
+- Only the extracted text (no explanations, no extra commentary).

connectonion/cli/templates/meta-agent/prompts/metagent.md

@@ -0,0 +1,71 @@
+# ConnectOnion Meta-Agent
+
+You are the ConnectOnion Meta-Agent, an expert AI assistant specialized in helping developers build agents with the ConnectOnion framework. You have deep knowledge of the framework's documentation and can generate code, answer questions, and guide users through development.
+
+## Primary Role
+
+Your main job is to help users understand and use ConnectOnion effectively by:
+1. **Answering documentation questions** using the embedded docs in `.co/docs/connectonion.md`
+2. **Generating agent code** from templates
+3. **Creating tool functions** with proper signatures
+4. **Writing tests** for agents
+5. **Planning complex projects** with structured to-do lists
+6. **Suggesting project structures** for different use cases
+
+## Core Capabilities
+
+### 📚 Documentation Expert (answer_connectonion_question)
+- Primary source of truth about ConnectOnion
+- Search through embedded documentation
+- Provide accurate, context-aware answers
+- Reference specific sections when relevant
+
+### 🔧 Code Generation
+- **create_agent_from_template**: Generate complete agent implementations
+- **generate_tool_code**: Create properly formatted tool functions
+- **create_test_for_agent**: Generate pytest-compatible test suites
+
+### 🧠 Meta-Cognitive Tools
+- **think**: Reflect on task completion and next steps
+- **generate_todo_list**: Break down complex tasks (uses GPT-4o-mini)
+
+### 🏗️ Architecture Guidance
+- **suggest_project_structure**: Recommend project organization
+- Support for single-agent, multi-agent, tool libraries, and API projects
+
+## Behavioral Guidelines
+
+1. **Documentation First**: Always check the embedded docs before answering ConnectOnion questions
+2. **Code Quality**: Generate clean, well-documented, working code
+3. **Best Practices**: Follow ConnectOnion conventions (markdown prompts, type hints, docstrings)
+4. **Be Helpful**: Provide examples and explanations, not just answers
+5. **Think Step-by-Step**: For complex requests, use the think tool to plan approach
+
+## Response Strategy
+
+When users ask about ConnectOnion:
+1. Use `answer_connectonion_question` to search documentation
+2. Provide relevant code examples when applicable
+3. Suggest next steps or related topics
+
+When users need code:
+1. Use appropriate generation tools
+2. Explain the generated code
+3. Mention customization options
+
+When users have complex projects:
+1. Use `think` to analyze requirements
+2. Generate a to-do list with `generate_todo_list`
+3. Suggest project structure
+4. Offer to generate starter code
+
+## Example Interactions
+
+- "How do tools work?" → Search docs, explain with examples
+- "Create a web scraper agent" → Generate agent template with appropriate tools
+- "I need to process CSV files" → Generate tool code for CSV processing
+- "Help me structure a multi-agent system" → Suggest architecture, create to-do list
+
+## Remember
+
+You are not just answering questions - you're actively helping developers build better agents with ConnectOnion. Be proactive in offering relevant tools, suggesting improvements, and sharing best practices from the documentation.

connectonion/cli/templates/meta-agent/prompts/think_prompt.md

@@ -0,0 +1,18 @@
+# Think Prompt
+
+You are a concise, high-signal thinking assistant.
+
+Input:
+- A short context string
+- A JSON-serialized list of conversation messages (OpenAI chat format)
+
+Task:
+- Return 3-5 short bullet points covering:
+  - What has been accomplished so far
+  - Current issues or blockers
+  - The single next best step
+
+Constraints:
+- Be brief, direct, and actionable
+- Do not restate the transcript
+- No preambles or closing remarks

connectonion/cli/templates/minimal/README.md

@@ -0,0 +1,56 @@
+# Minimal ConnectOnion Agent
+
+The simplest way to get started with ConnectOnion. A basic calculator agent that demonstrates:
+- Creating an agent with a simple tool
+- Interactive conversations
+- Using both `agent.input()` and `llm_do()` functions
+
+## Quick Start
+
+```bash
+# Initialize project (if not already done)
+co init --template minimal
+
+# Run the agent
+python agent.py
+```
+
+## What's Inside
+
+**`agent.py`** - A minimal agent with:
+- Simple calculator tool (add, subtract, multiply, divide)
+- Interactive conversation loop
+- Examples of both agent and direct LLM usage
+
+## Example Interaction
+
+```python
+# The agent can use its calculator tool
+agent.input("What is 25 * 4?")
+# → The calculator will compute: 100
+
+# Direct LLM call without tools
+llm_do("What is ConnectOnion?")
+# → Quick response without agent overhead
+```
+
+## Environment Variables
+
+The `.env` file is created automatically during `co init`. It includes:
+
+- `OPENONION_API_KEY` - Managed keys with `co/` prefix (recommended)
+- Or `OPENAI_API_KEY` - Your own OpenAI API key
+
+## Next Steps
+
+**Ready for more?** Try these templates:
+
+- `co init --template playwright` - Browser automation with Playwright
+- `co init --template web-research` - Web search and research tools
+- `co init --template meta-agent` - Multi-agent orchestration
+
+## Learn More
+
+- [Documentation](https://docs.connectonion.com)
+- [Examples](https://github.com/openonion/connectonion/tree/main/examples)
+- [Discord Community](https://discord.gg/4xfD9k8AUF)

connectonion/cli/templates/minimal/agent.py

@@ -0,0 +1,40 @@
+"""
+Purpose: Minimal agent template demonstrating basic ConnectOnion usage with a calculator tool
+LLM-Note:
+  Dependencies: imports from [connectonion.Agent] | template file copied by [cli/commands/init.py, cli/commands/create.py] | default template for 'co create' and 'co init'
+  Data flow: user query → Agent.input() → calculator tool called if math expression → eval() computes result → returns answer
+  State/Effects: no persistent state | single Agent.input() call | uses co/gemini-2.5-pro model (OpenOnion hosted)
+  Integration: template for 'co create --template minimal' | demonstrates function-as-tool pattern | shows system_prompt and model configuration
+  Performance: single LLM call | eval() is fast
+  Errors: ⚠️ Security: uses eval() - for demo only, not production safe
+
+Minimal ConnectOnion agent with a simple calculator tool.
+"""
+
+from connectonion import Agent
+
+
+def calculator(expression: str) -> float:
+    """Simple calculator that evaluates arithmetic expressions.
+
+    Args:
+        expression: A mathematical expression (e.g., "5*5", "10+20")
+
+    Returns:
+        The result of the calculation
+    """
+    # Note: eval() is used for simplicity. For production, use a safer parser.
+    return eval(expression)
+
+
+# Create agent with calculator tool
+agent = Agent(
+    name="calculator-agent", 
+    system_prompt="pls use the calculator tool to answer math questions", # you can also pass a markdown file like system_prompt="path/to/your_markdown_file.md"
+    tools=[calculator], # tools can be python classes or functions
+    model="co/gemini-2.5-pro" # co/gemini-2.5-pro is hosted by OpenOnion, you can use your own API key by setting OPENAI_API_KEY in .env
+)
+
+# Run the agent
+result = agent.input("what is the result of 5*5")
+print(result)

connectonion/cli/templates/playwright/README.md

@@ -0,0 +1,118 @@
+# Playwright Web Automation Agent
+
+A powerful browser automation agent using Playwright. Demonstrates stateful browser control, web scraping, form filling, and interactive automation.
+
+## Quick Start
+
+```bash
+# 1. Initialize project
+co init --template playwright
+
+# 2. Install dependencies
+pip install -r requirements.txt
+playwright install chromium
+
+# 3. Run the agent
+python agent.py
+```
+
+## What's Inside
+
+**Stateful Browser Tools:**
+- `start_browser()` - Launch browser instance
+- `navigate()` - Go to URLs with smart waiting
+- `scrape_content()` - Extract text from pages
+- `take_screenshot()` - Capture page screenshots
+- `fill_form()` - Fill and submit forms
+- `click()` - Click elements
+- `extract_links()` - Get all links from page
+- `execute_javascript()` - Run custom JS
+- `get_page_info()` / `get_session_info()` - Check browser state
+- `close_browser()` - Clean up resources
+
+## Interactive Mode
+
+The agent supports interactive conversation for browser automation:
+
+```bash
+You: Start the browser and go to example.com
+Agent: [Starts browser and navigates]
+
+You: Take a screenshot
+Agent: [Captures screenshot]
+
+You: Extract all links from the page
+Agent: [Lists all links found]
+```
+
+## Example Usage
+
+```python
+from connectonion import Agent
+
+# The browser instance maintains state across tool calls
+agent.input("Start the browser and navigate to example.com")
+agent.input("Take a screenshot of the homepage")
+agent.input("Extract all links that contain 'doc'")
+agent.input("Close the browser")
+```
+
+## Key Features
+
+### Stateful Session
+- Browser state persists across tool calls
+- Navigate multiple pages in one session
+- Maintain cookies and session data
+
+### Smart Automation
+- Automatic waiting for page loads
+- Error handling with helpful messages
+- Screenshot and download tracking
+
+### Flexible Input
+- Natural language commands
+- JSON form data for complex inputs
+- CSS selectors for precise targeting
+
+## Common Use Cases
+
+**Web Scraping:**
+```python
+agent.input("Go to news.ycombinator.com and extract the top 5 article titles")
+```
+
+**Form Automation:**
+```python
+agent.input("Navigate to the contact form and fill it with name 'John' and email 'john@example.com'")
+```
+
+**Screenshot Documentation:**
+```python
+agent.input("Take full-page screenshots of example.com, github.com, and python.org")
+```
+
+**Link Extraction:**
+```python
+agent.input("Go to docs.python.org and extract all tutorial links")
+```
+
+## Tips
+
+- Always `start_browser()` before other operations
+- Use `get_session_info()` to check browser state
+- Call `close_browser()` when done to free resources
+- Screenshots are saved in the current directory
+- Use headless=False to see browser in action
+
+## Next Steps
+
+**More Templates:**
+- `co init --template minimal` - Simple calculator agent
+- `co init --template web-research` - Web search tools
+- `co init --template meta-agent` - Multi-agent orchestration
+
+## Learn More
+
+- [Playwright Documentation](https://playwright.dev/python/)
+- [ConnectOnion Docs](https://docs.connectonion.com)
+- [Discord Community](https://discord.gg/4xfD9k8AUF)