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

connectonion/docs/useful_plugins/system_reminder.md

@@ -0,0 +1,210 @@
+# System Reminder Plugin
+
+Inject contextual guidance into tool results to nudge agent behavior.
+
+## Quick Start
+
+```python
+from connectonion import Agent
+from connectonion.useful_plugins import system_reminder
+
+agent = Agent("assistant", tools=[...], plugins=[system_reminder])
+```
+
+## Concept
+
+System reminders are short messages appended to tool results that guide the agent's next action—without extra API calls or separate messages.
+
+**Example**: After writing a Python file, remind the agent to consider testing.
+
+```
+write_file("app.py", code)
+    ↓
+Result: "File written successfully"
+    ↓
+With system reminder: "File written successfully
+
+    <system-reminder>
+    Consider running tests to verify your changes work correctly.
+    This is a gentle reminder - ignore if not applicable.
+    </system-reminder>"
+```
+
+The LLM sees the system reminder as part of the tool output and naturally considers it.
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────┐
+│          SYSTEM REMINDER FLOW                │
+├─────────────────────────────────────────────┤
+│                                             │
+│  1. Tool executes (e.g., write_file)        │
+│                 ↓                           │
+│  2. after_each_tool event fires             │
+│                 ↓                           │
+│  3. Plugin checks triggers:                 │
+│     - tool name matches?                    │
+│     - path pattern matches?                 │
+│                 ↓                           │
+│  4. If match: append system reminder        │
+│                 ↓                           │
+│  5. LLM sees result + system reminder       │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+## Categories
+
+Based on Claude Code patterns, system reminders fall into five categories:
+
+| Category | Purpose | Example |
+|----------|---------|---------|
+| **Workflow Nudges** | Gentle best practice suggestions | "Consider running tests" |
+| **State Notifications** | Inform about state changes | "You exited plan mode" |
+| **External Events** | React to external changes | "File was modified by linter" |
+| **Next Steps** | Guide what to do next | "Verify your implementation" |
+| **Context Injection** | Provide relevant info | "This file contains secrets" |
+
+## File Format
+
+Each system reminder is a markdown file with YAML frontmatter:
+
+```markdown
+---
+name: test-reminder
+triggers:
+  - tool: write_file
+    path_pattern: "*.py"
+---
+
+<system-reminder>
+Consider running tests to verify your changes.
+This is a gentle reminder - ignore if not applicable.
+</system-reminder>
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique identifier |
+| `triggers` | Yes | List of trigger conditions |
+| `triggers[].tool` | No | Tool name to match |
+| `triggers[].path_pattern` | No | Glob pattern(s) for file path arguments |
+| `triggers[].command_pattern` | No | Glob pattern(s) for command arguments |
+
+### Variables
+
+Use `${variable}` for dynamic content:
+
+| Variable | Description |
+|----------|-------------|
+| `${file_path}` | File path from tool arguments |
+| `${tool_name}` | Name of the tool that fired |
+
+## Design Principles
+
+**Gentle, Not Forceful**
+- ✓ "Consider running tests"
+- ✗ "You MUST run tests now"
+
+**Contextual, Not Spammy**
+- Fire only when relevant, not after every tool call
+
+**Simple Patterns**
+- Use glob: `*.py`, `["*.env", "*secret*"]`
+- Not regex: `.*\.py$`
+
+## Customizing
+
+Copy the plugin and built-in reminders to your project:
+
+```bash
+co copy system_reminder
+```
+
+Creates:
+```
+./plugins/system_reminder.py
+./prompts/system-reminders/
+├── test-reminder.md
+└── security-warning.md
+```
+
+Then import from your local copy:
+
+```python
+from plugins.system_reminder import system_reminder
+agent = Agent("assistant", plugins=[system_reminder])
+```
+
+Modify the reminder files in `./prompts/system-reminders/` to customize.
+
+---
+
+## Examples
+
+### Workflow Nudge: Test After Code Change
+
+```markdown
+---
+name: test-reminder
+triggers:
+  - tool: write_file
+    path_pattern: ["*.py", "*.js", "*.ts"]
+---
+
+<system-reminder>
+Code was modified. Consider:
+- Running relevant tests
+- Checking for linter errors
+This is a gentle reminder - ignore if not applicable.
+</system-reminder>
+```
+
+### State Notification: Plan Mode Exited
+
+```markdown
+---
+name: plan-mode-exited
+triggers:
+  - tool: exit_plan_mode
+---
+
+<system-reminder>
+You have exited plan mode. You can now make edits and run tools.
+</system-reminder>
+```
+
+### External Event: File Modified Externally
+
+```markdown
+---
+name: file-modified-externally
+triggers:
+  - tool: file_watcher
+---
+
+<system-reminder>
+${file_path} was modified externally (by user or linter).
+Don't revert these changes unless asked.
+</system-reminder>
+```
+
+### Context Injection: Security Warning
+
+```markdown
+---
+name: security-warning
+triggers:
+  - tool: read_file
+    path_pattern: ["*.env", "*secret*", "*.pem"]
+---
+
+<system-reminder>
+This file may contain sensitive information.
+- Never expose secrets in output
+- Never commit real credentials
+</system-reminder>
+```

connectonion/docs/useful_prompts/README.md

@@ -0,0 +1,127 @@
+# Prompt Templates
+
+Pre-built prompt structures for common agent patterns. Copy to your project and customize.
+
+## Quick Reference
+
+| Template | Purpose | Use Case |
+|----------|---------|----------|
+| [coding_agent](coding_agent.md) | Coding Agent Prompt | CLI coding tools, code review bots |
+
+## Philosophy
+
+These are **examples to copy**, not framework code to import.
+
+1. Browse the templates
+2. Copy what fits your needs
+3. Modify freely - you own the code
+
+No lock-in. No rigid structure. Just good patterns.
+
+## Usage Pattern
+
+```bash
+# Copy template to your project
+cp -r $(python -c "from connectonion.useful_prompts import get_example_path; print(get_example_path('coding_agent'))") ./my_prompts
+
+# Or manually
+cp -r .../connectonion/useful_prompts/coding_agent/ ./my_prompts
+```
+
+```python
+# Use the assembler from your copied template
+from my_prompts.assembler import assemble_prompt
+from connectonion import Agent, Shell, DiffWriter
+
+tools = [Shell(), DiffWriter()]
+prompt = assemble_prompt(prompts_dir="my_prompts/prompts", tools=tools)
+
+agent = Agent("my-agent", system_prompt=prompt, tools=tools)
+```
+
+## Why Modular Prompts?
+
+Learned from Claude Code's architecture:
+
+| Benefit | Description |
+|---------|-------------|
+| **Per-tool guidance** | Each tool gets dedicated "when to use" / "when NOT to use" |
+| **Easy customization** | Modify one file without touching others |
+| **Conditional assembly** | Only include prompts for tools you actually use |
+| **Project context** | Add project-specific instructions separately |
+
+## Template Structure
+
+Each template follows this pattern:
+
+```
+template_name/
+├── prompts/
+│   ├── main.md           # Core agent behavior
+│   └── tools/            # Per-tool guidance
+│       ├── tool_a.md
+│       └── tool_b.md
+├── assembler.py          # Prompt assembly utility
+└── README.md             # Template documentation
+```
+
+## Customizing Templates
+
+### Modify agent behavior
+Edit `prompts/main.md`:
+- Agent personality and tone
+- Workflow steps
+- General guidelines
+
+### Add tool guidance
+Create `prompts/tools/my_tool.md`:
+```markdown
+# Tool: My Tool
+
+## When to Use
+- Situation A
+- Situation B
+
+## When NOT to Use
+- Situation C
+
+## Examples
+<good-example>
+...
+</good-example>
+
+<bad-example>
+...
+</bad-example>
+```
+
+### Add project context
+Create `.co/AGENT.md` in your project:
+```markdown
+# Project: My App
+
+## Tech Stack
+- Python 3.11, FastAPI
+
+## Conventions
+- Use snake_case
+- Type hints required
+```
+
+Pass it to the assembler:
+```python
+prompt = assemble_prompt(
+    prompts_dir="my_prompts/prompts",
+    tools=tools,
+    context_file=".co/AGENT.md"
+)
+```
+
+## Comparison: Single File vs Modular
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **Single file** | Simple, one place | Hard to maintain, can't customize per-tool |
+| **Modular** | Easy to update, per-tool control | More files to manage |
+
+**Recommendation:** Start with single file for simple agents. Switch to modular when you need per-tool customization or have 3+ tools.

connectonion/docs/useful_prompts/coding_agent.md

@@ -0,0 +1,214 @@
+# Coding Agent Prompt
+
+A modular prompt template for building coding assistants. This is a **prompt**, not code - you copy it, customize it, and use it as your agent's system prompt.
+
+## Overview
+
+This template provides:
+- **Main prompt** - Core agent behavior, tone, workflow
+- **Per-tool prompts** - Guidance for shell, file read/write, todo list
+- **Assembler** - Simple utility to combine prompts
+
+## Structure
+
+```
+coding_agent/
+├── prompts/
+│   ├── main.md           # Core agent behavior
+│   └── tools/            # Per-tool guidance
+│       ├── shell.md      # Shell/bash usage
+│       ├── read.md       # File reading
+│       ├── write.md      # File writing
+│       └── todo.md       # Task tracking
+├── assembler.py          # Prompt assembly (~50 lines)
+└── README.md
+```
+
+## Quick Start
+
+### 1. Copy to your project
+
+```bash
+# Using co copy (recommended)
+co copy coding_agent
+
+# Or manually
+cp -r $(python -c "from connectonion.useful_prompts import get_example_path; print(get_example_path('coding_agent'))") ./prompts
+```
+
+### 2. Use in your agent
+
+```python
+from prompts.assembler import assemble_prompt
+from connectonion import Agent
+from connectonion.useful_tools import Shell, DiffWriter, TodoList
+
+def read_file(path: str) -> str:
+    """Read file contents."""
+    return open(path).read()
+
+# Define tools
+tools = [Shell(), read_file, DiffWriter(), TodoList()]
+
+# Assemble prompt (only includes docs for tools you have)
+prompt = assemble_prompt(
+    prompts_dir="prompts/prompts",
+    tools=tools
+)
+
+# Create agent
+agent = Agent("coder", system_prompt=prompt, tools=tools)
+agent.run()
+```
+
+## Prompt Files
+
+### main.md
+
+Core agent behavior:
+- Tone and style (concise, no preamble)
+- Task workflow (understand → search → implement → verify)
+- Coding guidelines (read first, mimic style, minimal changes)
+- Persistence (don't give up easily)
+- Security rules (no secrets, no force push)
+
+### tools/shell.md
+
+When to use shell:
+- Git operations
+- Package management
+- Running tests
+- Build commands
+
+When NOT to use:
+- Reading files (use read_file)
+- Writing files (use write)
+
+### tools/read.md
+
+File reading best practices:
+- Always read before modifying
+- Check dependencies
+- Understand context
+
+### tools/write.md
+
+File writing guidelines:
+- Read first, then write
+- Match existing style
+- Minimal changes
+
+### tools/todo.md
+
+Task tracking guidance:
+- When to use (3+ steps)
+- When not to use (trivial tasks)
+- Task states and flow
+
+## Customization
+
+### Change agent personality
+
+Edit `prompts/main.md`:
+
+```markdown
+# My Custom Agent
+
+You are a friendly coding assistant that loves emojis! 🚀
+
+## Tone
+- Be enthusiastic and encouraging
+- Use emojis liberally
+- Celebrate small wins
+```
+
+### Add custom tool guidance
+
+Create `prompts/tools/my_api.md`:
+
+```markdown
+# Tool: My API
+
+## When to Use
+- Fetching user data
+- Updating records
+
+## When NOT to Use
+- Bulk operations (use batch API)
+
+## Rate Limits
+- Max 100 requests/minute
+- Use caching when possible
+```
+
+### Add project context
+
+Create `.co/AGENT.md`:
+
+```markdown
+# Project: E-commerce API
+
+## Stack
+- Python 3.11, FastAPI, PostgreSQL
+
+## Conventions
+- snake_case for functions
+- Type hints required
+- Tests in tests/ directory
+```
+
+Use in assembler:
+
+```python
+prompt = assemble_prompt(
+    prompts_dir="prompts/prompts",
+    tools=tools,
+    context_file=".co/AGENT.md"
+)
+```
+
+## The Assembler
+
+The assembler is intentionally simple (~50 lines):
+
+```python
+def assemble_prompt(prompts_dir, tools, context_file=None):
+    parts = []
+
+    # 1. Main prompt
+    parts.append(read("prompts/main.md"))
+
+    # 2. Tool descriptions (for each tool)
+    for tool in tools:
+        tool_file = f"prompts/tools/{tool.name}.md"
+        if exists(tool_file):
+            parts.append(read(tool_file))
+
+    # 3. Project context (optional)
+    if context_file:
+        parts.append(read(context_file))
+
+    return "\n\n---\n\n".join(parts)
+```
+
+You own this code. Modify it for your needs:
+- Add variable interpolation
+- Add conditional sections
+- Add version tracking
+- Whatever you need
+
+## Best Practices
+
+### From Claude Code
+
+1. **"When NOT to use"** sections are as important as "when to use"
+2. **Examples with reasoning** - show good AND bad patterns
+3. **Keep tool docs focused** - one tool per file
+4. **Project context separate** - easy to update per-project
+
+### Keep It Simple
+
+- Start with the template as-is
+- Only add complexity when needed
+- Delete files you don't use
+- The goal is clarity, not completeness

connectonion/docs/useful_tools/README.md

@@ -0,0 +1,81 @@
+# Built-in Tools
+
+Pre-built tools for common agent tasks.
+
+## Quick Reference
+
+| Tool | Purpose | Import |
+|------|---------|--------|
+| [Shell](shell.md) | Execute shell commands | `from connectonion import Shell` |
+| [DiffWriter](diff_writer.md) | Edit files with diffs | `from connectonion import DiffWriter` |
+| [TodoList](todo_list.md) | Track task progress | `from connectonion import TodoList` |
+| [WebFetch](web_fetch.md) | Fetch web content | `from connectonion import WebFetch` |
+| [Gmail](gmail.md) | Gmail integration | `from connectonion import Gmail` |
+| [get_emails](get_emails.md) | Email parsing utilities | `from connectonion import get_emails` |
+| [send_email](send_email.md) | Send emails via API | `from connectonion import send_email` |
+| [Outlook](outlook.md) | Outlook integration | `from connectonion import Outlook` |
+| [GoogleCalendar](google_calendar.md) | Google Calendar | `from connectonion import GoogleCalendar` |
+| [MicrosoftCalendar](microsoft_calendar.md) | Microsoft Calendar | `from connectonion import MicrosoftCalendar` |
+| [Memory](memory.md) | Persistent memory | `from connectonion import Memory` |
+| [Terminal](terminal.md) | Interactive terminal | `from connectonion import Terminal` |
+| [SlashCommand](slash_command.md) | Custom commands | `from connectonion import SlashCommand` |
+
+## Usage Pattern
+
+```python
+from connectonion import Agent, Shell, DiffWriter
+
+# Create tool instances
+shell = Shell()
+writer = DiffWriter()
+
+# Pass to agent
+agent = Agent("coder", tools=[shell, writer])
+
+agent.input("Create a hello.py file that prints 'Hello World'")
+```
+
+## Customizing Tools
+
+Need to modify a built-in tool? Copy it to your project:
+
+```bash
+# Copy tool source to ./tools/
+co copy Gmail
+
+# Copy multiple tools
+co copy Gmail Shell memory
+```
+
+Then import from your local copy:
+
+```python
+# Before (from package)
+from connectonion import Gmail
+
+# After (from your copy)
+from tools.gmail import Gmail  # Customize freely!
+```
+
+See [co copy](../cli/copy.md) for full details.
+
+## Categories
+
+### File Operations
+- **Shell** - Run commands, scripts, git
+- **DiffWriter** - Edit files with visual diffs
+
+### Communication
+- **Gmail** - Send/read Gmail
+- **Outlook** - Send/read Outlook
+
+### Calendar
+- **GoogleCalendar** - Google Calendar events
+- **MicrosoftCalendar** - Microsoft Calendar events
+
+### Utilities
+- **WebFetch** - Fetch and parse web pages
+- **Memory** - Store/retrieve persistent data
+- **TodoList** - Track tasks and progress
+- **Terminal** - Interactive terminal UI
+- **SlashCommand** - Define custom commands