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

connectonion/useful_plugins/ui_stream.py

@@ -1,20 +1,17 @@
 """
-Purpose: Stream agent activity to UI via Connection API
+Purpose: Plugin for streaming agent completion summaries to WebSocket UI clients
 LLM-Note:
-  Dependencies: imports from [typing, core.events] | imported by [useful_plugins/__init__.py] | tested by [tests/unit/test_ui_stream.py]
-  Data flow: Event handlers check agent.connection → if present, call connection.log() to stream events
-  State/Effects: Streams events to WebSocket client | no file I/O | no blocking
-  Integration: exposes ui_stream list of event handlers | used via Agent(plugins=[ui_stream]) | works with host() WebSocket
-  Performance: O(1) event dispatch | no blocking | no LLM calls
-  Errors: Silently skips if connection is None (local execution)
-
-UI Stream Plugin - Stream agent activity to connected UI clients.
-
-When agent.connection is set (by host() for WebSocket connections), this plugin
-streams real-time events for:
-- LLM responses (thinking, tool_calls)
-- Tool execution (before/after each tool)
-- Errors and completion
+  Dependencies: imports from [core/events.py on_complete, typing] | imported by [useful_plugins/__init__.py, user code] | tested by [tests/plugins/test_ui_stream.py]
+  Data flow: fires on_complete event → extracts trace from current_session → counts tools_used and llm_calls → sends via agent.io.log('complete', tools_used, llm_calls, iterations) → WebSocket client receives completion event
+  State/Effects: sends message via agent.io (if connected) | no persistent state | read-only access to session trace
+  Integration: exposes ui_stream plugin (use via plugins=[ui_stream]) | only fires if agent.io exists (hosted mode) | complements direct events from agent.py/tool_executor.py | stream_complete handler decorated with @on_complete
+  Performance: minimal overhead (just counting trace entries) | single io.log call
+  Errors: returns early if no io connection | no exceptions raised
+UI Stream Plugin - Stream agent completion summary to connected UI clients.
+
+Events (user_input, thinking, tool_result, assistant) are now emitted directly
+from their source (agent.py, tool_executor.py, plugins). This plugin only
+handles the completion summary.
 
 Usage:
     from connectonion import Agent
@@ -25,128 +22,23 @@ Usage:
 """
 
 from typing import TYPE_CHECKING
-from ..core.events import (
-    after_llm,
-    before_each_tool,
-    after_each_tool,
-    on_error,
-    on_complete,
-)
+from ..core.events import on_complete
 
 if TYPE_CHECKING:
     from ..core.agent import Agent
 
 
-@after_llm
-def stream_llm_response(agent: 'Agent') -> None:
-    """Stream LLM response to connected UI."""
-    if not agent.connection:
-        return
-
-    trace = agent.current_session.get('trace', [])
-    if not trace:
-        return
-
-    last = trace[-1]
-    if last.get('type') != 'llm_call':
-        return
-
-    # Stream content if present
-    content = last.get('content', '')
-    if content:
-        agent.connection.log('message', content=content)
-
-    # Stream tool calls if present
-    tool_calls = last.get('tool_calls', [])
-    for tc in tool_calls:
-        agent.connection.log(
-            'tool_pending',
-            name=tc.get('function', {}).get('name', ''),
-            arguments=tc.get('function', {}).get('arguments', {}),
-            id=tc.get('id', ''),
-        )
-
-
-@before_each_tool
-def stream_tool_start(agent: 'Agent') -> None:
-    """Stream tool execution start to connected UI."""
-    if not agent.connection:
-        return
-
-    pending = agent.current_session.get('pending_tool')
-    if not pending:
-        return
-
-    agent.connection.log(
-        'tool_start',
-        name=pending['name'],
-        arguments=pending['arguments'],
-        id=pending.get('id', ''),
-    )
-
-
-@after_each_tool
-def stream_tool_result(agent: 'Agent') -> None:
-    """Stream tool execution result to connected UI."""
-    if not agent.connection:
-        return
-
-    trace = agent.current_session.get('trace', [])
-    if not trace:
-        return
-
-    last = trace[-1]
-    if last.get('type') != 'tool_execution':
-        return
-
-    status = last.get('status', 'unknown')
-    result = last.get('result', '')
-
-    # Truncate large results for UI
-    if isinstance(result, str) and len(result) > 1000:
-        result = result[:1000] + '...'
-
-    agent.connection.log(
-        'tool_result',
-        name=last.get('tool_name', ''),
-        status=status,
-        result=result,
-        timing_ms=last.get('timing', 0),
-    )
-
-
-@on_error
-def stream_error(agent: 'Agent') -> None:
-    """Stream error to connected UI."""
-    if not agent.connection:
-        return
-
-    trace = agent.current_session.get('trace', [])
-    if not trace:
-        return
-
-    last = trace[-1]
-    if last.get('status') != 'error':
-        return
-
-    agent.connection.log(
-        'error',
-        tool_name=last.get('tool_name', ''),
-        error=str(last.get('error', '')),
-    )
-
-
 @on_complete
 def stream_complete(agent: 'Agent') -> None:
-    """Stream completion to connected UI."""
-    if not agent.connection:
+    """Stream completion summary to connected UI."""
+    if not agent.io:
         return
 
     trace = agent.current_session.get('trace', [])
-    tools_used = [t.get('tool_name', '') for t in trace if t.get('type') == 'tool_execution']
+    tools_used = [t.get('name', '') for t in trace if t.get('type') == 'tool_result']
     llm_calls = len([t for t in trace if t.get('type') == 'llm_call'])
 
-    agent.connection.log(
+    agent.io.log(
         'complete',
         tools_used=tools_used,
         llm_calls=llm_calls,
@@ -154,11 +46,4 @@ def stream_complete(agent: 'Agent') -> None:
     )
 
 
-# Bundle as plugin
-ui_stream = [
-    stream_llm_response,
-    stream_tool_start,
-    stream_tool_result,
-    stream_error,
-    stream_complete,
-]
+ui_stream = [stream_complete]

connectonion/useful_prompts/README.md

@@ -0,0 +1,61 @@
+# useful_prompts
+
+Prompt examples and patterns for ConnectOnion agents. Copy what you need to your project.
+
+## Philosophy
+
+These are **examples**, not framework code. You:
+1. Browse the examples
+2. Copy what fits your needs
+3. Modify freely - you own the code now
+
+No lock-in. No rigid structure. Just good patterns.
+
+## Available Examples
+
+### coding_agent/
+A modular prompt structure for coding assistants.
+
+```
+coding_agent/
+├── prompts/
+│   ├── main.md           # Core agent behavior
+│   └── tools/            # Per-tool guidance
+│       ├── shell.md
+│       ├── read.md
+│       ├── write.md
+│       └── todo.md
+├── assembler.py          # Simple prompt assembly
+└── README.md
+```
+
+**Good for:** CLI coding assistants, code review bots, development helpers
+
+## How to Use
+
+```bash
+# Copy the example to your project
+cp -r useful_prompts/coding_agent/ my-project/
+
+# Customize the prompts
+cd my-project/coding_agent
+vim prompts/main.md       # Edit core behavior
+vim prompts/tools/shell.md # Edit shell guidance
+```
+
+## Creating Your Own
+
+1. Start with an existing example
+2. Modify `main.md` for your agent's personality
+3. Add/remove tool files as needed
+4. Customize `assembler.py` for your assembly logic
+
+## Principles
+
+From Claude Code's architecture, we learned:
+
+1. **Modular prompts** - Split by concern (main, per-tool)
+2. **"When NOT to use"** - As important as "when to use"
+3. **Examples with reasoning** - Show good AND bad patterns
+4. **Assembly at runtime** - Combine pieces based on available tools
+5. **User owns the code** - No framework lock-in

connectonion/useful_prompts/__init__.py

@@ -0,0 +1,45 @@
+"""
+Purpose: Prompt templates directory with utility for copying example prompts to user projects
+LLM-Note:
+  Dependencies: imports from [pathlib] | imported by [cli/commands/copy_commands.py, user code] | tested by [tests/prompts/test_useful_prompts.py]
+  Data flow: get_example_path(name) → returns Path to template directory for copying | PROMPTS_DIR constant points to useful_prompts/ directory
+  State/Effects: reads filesystem (Path operations) | no modifications
+  Integration: exposes PROMPTS_DIR constant, get_example_path(name) → Path | used by `co copy coding_agent` command to copy templates | contains coding_agent/ subdirectory with main.md, tools/*.md, assembler.py
+  Performance: trivial (Path operations only)
+  Errors: none (Path returned whether directory exists or not, caller handles)
+useful_prompts - Prompt templates for ConnectOnion agents.
+
+These are PROMPT TEMPLATES to copy to your project, not framework code to import.
+
+Usage:
+    1. Run: co copy coding_agent
+    2. Customize the markdown files in prompts/coding_agent/
+    3. Use assembler.py to build your system prompt
+
+Available prompts:
+    - coding_agent/  : Coding Agent Prompt - modular template for coding assistants
+
+See README.md for details.
+"""
+
+from pathlib import Path
+
+# Path to useful_prompts directory (for copying examples)
+PROMPTS_DIR = Path(__file__).parent
+
+
+def get_example_path(name: str) -> Path:
+    """Get path to an example directory for copying.
+
+    Args:
+        name: Example name (e.g., "coding_agent")
+
+    Returns:
+        Path to the example directory
+
+    Example:
+        >>> from connectonion.useful_prompts import get_example_path
+        >>> import shutil
+        >>> shutil.copytree(get_example_path("coding_agent"), "my_prompts")
+    """
+    return PROMPTS_DIR / name

connectonion/useful_prompts/coding_agent/README.md

@@ -0,0 +1,106 @@
+# Coding Agent Prompt
+
+A modular **prompt template** for building coding agents. This is a prompt (not code) - copy it to your project and customize the markdown files.
+
+## 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 utility
+└── README.md
+```
+
+## Quick Start
+
+1. **Copy to your project:**
+   ```bash
+   cp -r coding_agent/ my-project/
+   cd my-project/coding_agent
+   ```
+
+2. **Use the assembler:**
+   ```python
+   from assembler import assemble_prompt
+   from connectonion import Agent
+   from connectonion.useful_tools import Shell, DiffWriter
+
+   def read_file(path: str) -> str:
+       return open(path).read()
+
+   tools = [Shell(), read_file, DiffWriter()]
+   prompt = assemble_prompt(prompts_dir="prompts", tools=tools)
+
+   agent = Agent("my-agent", system_prompt=prompt, tools=tools)
+   agent.run()
+   ```
+
+## Customization
+
+### Modify main.md
+Edit `prompts/main.md` to change:
+- Agent personality and tone
+- Workflow steps
+- General guidelines
+
+### Add/modify tool descriptions
+Each file in `prompts/tools/` provides guidance for one tool:
+- `shell.md` - When to use shell, when not to
+- `read.md` - File reading best practices
+- `write.md` - File writing guidelines
+- `todo.md` - Task tracking guidance
+
+Add new files for your custom tools:
+```markdown
+# prompts/tools/my_custom_tool.md
+
+# Tool: My Custom Tool
+
+## When to Use
+- Situation A
+- Situation B
+
+## When NOT to Use
+- Situation C
+```
+
+### Add project context
+Create `.co/AGENT.md` in your project root for project-specific instructions:
+```markdown
+# Project: My App
+
+## Tech Stack
+- Python 3.11
+- FastAPI
+- PostgreSQL
+
+## Conventions
+- Use snake_case for functions
+- Type hints required
+```
+
+Then pass it to the assembler:
+```python
+prompt = assemble_prompt(
+    prompts_dir="prompts",
+    tools=tools,
+    context_file=".co/AGENT.md"
+)
+```
+
+## Philosophy
+
+This is NOT a framework. It's an example you own completely.
+
+- Modify any file freely
+- Delete what you don't need
+- Add what you want
+- No dependencies on ConnectOnion internals
+
+The assembler is ~50 lines of simple Python. Read it, understand it, change it.

connectonion/useful_prompts/coding_agent/assembler.py

@@ -0,0 +1,123 @@
+"""
+Purpose: Modular prompt assembly for coding agents from main.md + tool-specific prompts + project context
+LLM-Note:
+  Dependencies: imports from [pathlib, typing] | imported by [examples/coding_agent/, user code] | tested by [tests/prompts/test_assembler.py]
+  Data flow: assemble_prompt(prompts_dir, tools, context_file) → reads prompts/main.md → for each tool reads prompts/tools/{tool_name}.md → optionally reads context_file (.co/AGENT.md) → concatenates with separators → returns assembled prompt
+  State/Effects: reads markdown files from filesystem | no persistent state
+  Integration: exposes assemble_prompt(prompts_dir, tools, context_file) → str | expects directory structure: prompts/main.md, prompts/tools/*.md | tool name extracted from tool.__name__ or tool.name | user customizable (copy to project and modify)
+  Performance: file I/O only (fast for typical prompt files) | lazy loading (only reads requested tool prompts)
+  Errors: skips missing tool prompt files silently | raises if main.md missing | context_file optional
+Prompt Assembler - Copy this to your project and customize!
+
+This is NOT a framework class. It's an example you can modify freely.
+The assembled prompt combines:
+  - Main prompt (core agent behavior)
+  - Tool descriptions (for each tool you use)
+  - Project context (optional .co/AGENT.md)
+
+Usage:
+    from assembler import assemble_prompt
+
+    prompt = assemble_prompt(
+        tools=[shell, read_file, writer],
+        context_file=".co/AGENT.md"  # optional
+    )
+
+    agent = Agent("my-agent", system_prompt=prompt, tools=tools)
+"""
+
+from pathlib import Path
+from typing import List, Any, Optional
+
+
+def assemble_prompt(
+    prompts_dir: str = "prompts",
+    tools: Optional[List[Any]] = None,
+    context_file: Optional[str] = None,
+) -> str:
+    """
+    Assemble a system prompt from modular files.
+
+    Directory structure:
+        prompts/
+        ├── main.md          # Core agent behavior
+        └── tools/           # Tool-specific guidance
+            ├── shell.md
+            ├── read.md
+            └── write.md
+
+    Args:
+        prompts_dir: Path to prompts directory
+        tools: List of tool objects/functions (loads matching .md files)
+        context_file: Optional project-specific context file
+
+    Returns:
+        Assembled prompt string
+    """
+    prompts_path = Path(prompts_dir)
+    parts = []
+
+    # 1. Main prompt (required)
+    main_file = prompts_path / "main.md"
+    if main_file.exists():
+        parts.append(main_file.read_text())
+
+    # 2. Tool descriptions (for each available tool)
+    tools_dir = prompts_path / "tools"
+    if tools_dir.exists() and tools:
+        for tool in tools:
+            tool_name = _get_tool_name(tool).lower()
+            tool_file = tools_dir / f"{tool_name}.md"
+            if tool_file.exists():
+                parts.append(tool_file.read_text())
+
+    # 3. Project context (optional)
+    if context_file:
+        context_path = Path(context_file)
+        if context_path.exists():
+            parts.append(f"# Project Context\n\n{context_path.read_text()}")
+
+    return "\n\n---\n\n".join(parts)
+
+
+def _get_tool_name(tool: Any) -> str:
+    """Extract tool name from function or class instance."""
+    # Function
+    if callable(tool) and hasattr(tool, "__name__"):
+        return tool.__name__
+
+    # Class instance with name attribute
+    if hasattr(tool, "name"):
+        return tool.name
+
+    # Class instance - use class name
+    return tool.__class__.__name__
+
+
+# Example usage
+if __name__ == "__main__":
+    from connectonion import Agent
+    from connectonion.useful_tools import bash, DiffWriter, TodoList
+
+    # Define tools
+    def read_file(path: str) -> str:
+        """Read file contents."""
+        return Path(path).read_text()
+
+    writer = DiffWriter()
+    todo = TodoList()
+    tools = [bash, read_file, writer, todo]
+
+    # Assemble prompt
+    prompt = assemble_prompt(
+        prompts_dir="prompts",
+        tools=tools,
+        context_file=".co/AGENT.md"
+    )
+
+    print(f"Assembled prompt ({len(prompt)} chars):\n")
+    print(prompt[:500] + "...")
+
+    # Create agent
+    # agent = Agent("coding-agent", system_prompt=prompt, tools=tools)
+    # agent.run()