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

connectonion/cli/co_ai/prompts/connectonion/design-decisions/011-global-config-identity-management.md

@@ -0,0 +1,357 @@
+# Design Decision: Global Config and Identity Management
+
+*Date: 2025-09-18*
+*Decision: One global identity (address + email) shared by all projects*
+*Status: Implemented*
+
+## The Problem We Saw
+
+Every Friday, we'd watch developers create their 5th ConnectOnion project of the week. And every time, the same ritual:
+
+```bash
+$ co create another-bot
+✔ Enter your OpenAI API key: sk-proj-xxx...  # Same key as before
+✓ Generated address: 0x4f5a...               # 5th address this week
+✓ Agent email: 0x4f5a@openonion.ai          # 5th email to track
+✓ Created recovery phrase...                 # 5th phrase to backup
+```
+
+By project #10, developers had:
+- Entered the same API key 10 times
+- Generated 10 different addresses they'd never use
+- Created 10 emails they couldn't remember
+- Saved 10 recovery phrases they'd definitely lose
+
+**The breaking point:** A user asked us, "Why does my local test bot need a different email address than my production bot? They're both me."
+
+They were right. We were forcing unnecessary complexity.
+
+## The Core Insight
+
+> "Your laptop has one user account. Your browser has one profile. Why should every agent need its own identity?"
+
+Most developers ARE their agents. The agent's email is effectively the developer's email. The agent's address represents the developer. Creating separate identities for every project is like creating a new email account for every document you write.
+
+## What We Changed
+
+### Before: Every Project Is an Island
+```
+project1/.co/
+├── keys/
+│   ├── agent.key        # Unique keypair
+│   └── recovery.txt     # Unique recovery phrase
+└── config.toml          # address: 0x1234..., email: 0x1234@openonion.ai
+
+project2/.co/
+├── keys/
+│   ├── agent.key        # Different keypair
+│   └── recovery.txt     # Different recovery phrase
+└── config.toml          # address: 0x5678..., email: 0x5678@openonion.ai
+```
+
+### After: One Identity, Many Projects
+```
+~/.co/                          # GLOBAL
+├── config.toml                 # Your identity (address + email)
+├── keys.env                    # Your API keys (one place!)
+└── keys/
+    └── master.key              # Your keypair
+
+project1/.co/
+└── config.toml                 # Uses global address + email
+
+project2/.co/
+└── config.toml                 # Same global address + email
+```
+
+## The Complete Design
+
+### 1. Global Identity (Address + Email)
+
+Every user gets ONE identity when they first run `co create`:
+
+```toml
+# ~/.co/config.toml
+[agent]
+address = "0x7b78b4cf850331c4b26dac089eb9cd84493483eccbf0e067f1c36e1c7f570e6b"
+short_address = "0x7b78...0e6b"
+email = "0x7b78b4cf@openonion.ai"  # Derived from address
+```
+
+This identity is **automatically copied** to every project:
+- Same address for all agents
+- Same email for all agents
+- One identity to rule them all
+
+### 2. Global API Keys
+
+API keys live in ONE place and are copied to all projects:
+
+```bash
+# ~/.co/keys.env (global)
+OPENAI_API_KEY=sk-proj-xxx
+ANTHROPIC_API_KEY=sk-ant-xxx
+
+# Automatically copied to:
+# - project1/.env
+# - project2/.env
+# - project3/.env
+```
+
+**Why `.env` format?** Because it's the universal standard. No JSON parsing, no YAML confusion, just `KEY=value`.
+
+### 3. Progressive Complexity
+
+Start simple, add complexity only when needed:
+
+```bash
+# 99% of projects - use global everything
+$ co create my-bot
+✓ Using global identity: 0x7b78...0e6b
+✓ Using global email: 0x7b78b4cf@openonion.ai
+✓ Copied API keys from ~/.co/keys.env
+
+# 1% of projects - need their own identity
+$ cd special-project
+$ co address
+✓ Generated project-specific address: 0x9c7d...
+✓ Generated project-specific email: 0x9c7d@openonion.ai
+```
+
+## Implementation Principles
+
+### 1. Fail Fast, Fail Loud
+
+```python
+# OLD - Silent failure
+try:
+    addr_data = address.generate()
+except:
+    addr_data = {"address": "0x000..."}  # User wonders why address is zeros
+
+# NEW - Immediate feedback
+addr_data = address.generate()  # Crashes with clear error if PyNaCl missing
+```
+
+### 2. Install Everything by Default
+
+```python
+# setup.py
+requirements = [
+    "PyNaCl>=1.5.0",      # No longer optional
+    "mnemonic>=0.20",     # No longer optional
+    "questionary>=2.0.0",  # No longer optional
+]
+# Only playwright remains optional (it's 100MB+)
+```
+
+**Why?** Because "Module not found" after installation is user-hostile.
+
+### 3. One Source of Truth
+
+```
+~/.co/config.toml    → Global identity (address + email)
+~/.co/keys.env       → API keys
+~/.co/keys/          → Cryptographic keys
+
+Everything else copies from these.
+```
+
+## User Experience Transformation
+
+### First Project (First Time Ever)
+```bash
+$ co create my-first-agent
+
+🚀 Welcome to ConnectOnion!
+✨ Setting up global configuration...
+  ✓ Generated master keypair
+  ✓ Your address: 0x7b78...0e6b
+  ✓ Your email: 0x7b78b4cf@openonion.ai
+  ✓ Created ~/.co/config.toml
+  ✓ Created ~/.co/keys.env
+
+✔ Enter your API key: sk-proj-xxx
+  ✓ Saved to ~/.co/keys.env for all future projects
+
+✅ Project created!
+```
+
+### Every Project After That
+```bash
+$ co create another-agent
+
+✓ Using global identity: 0x7b78...0e6b
+✓ Using global email: 0x7b78b4cf@openonion.ai
+✓ Found OpenAI key in ~/.co/keys.env
+✓ Copied to project .env
+
+✅ Project created in 2 seconds!
+```
+
+### The 50th Project
+```bash
+$ co create yet-another-agent
+
+✓ Using global identity: 0x7b78...0e6b
+✓ Using global email: 0x7b78b4cf@openonion.ai
+✓ Copied API keys from ~/.co/keys.env
+
+✅ Still just 2 seconds!
+```
+
+## Real-World Analogies That Clicked
+
+**Email:** You don't create a new email address for every document you write. You use your one email.
+
+**SSH Keys:** Most developers use one SSH key for all their repositories, not one key per repo.
+
+**Phone Number:** You don't get a new phone number for each app you install.
+
+**Office Building:** You have one keycard that opens all the doors you're authorized for, not 50 different keys.
+
+## The Philosophy
+
+This design embodies our core principle:
+
+> **"Keep simple things simple, make complicated things possible"**
+
+- **Simple:** One identity, one email, one place for API keys
+- **Possible:** Need project-specific identity? Run `co address`
+
+We're not removing capabilities, we're changing defaults. The complex path still exists for those who need it, but the simple path is now the default.
+
+## What This Enables
+
+### Today
+- Zero-friction project creation
+- No more API key repetition
+- One identity to remember
+- One email for all agents
+
+### Tomorrow
+- **Network Features:** Your global identity becomes your network account
+- **Reputation:** One reputation score across all your agents
+- **Discovery:** Find all agents by one developer
+- **Payments:** One wallet for ConnectOnion credits
+
+## Lessons We Learned
+
+1. **Users hate repetition more than they love security**
+   - Theoretical: "Each project should be isolated"
+   - Reality: "Just let me build my bot"
+
+2. **Defaults matter more than options**
+   - Having the option for project keys isn't enough
+   - The default path must be the right path for 99% of users
+
+3. **Explicit is better than magical**
+   - Show "(global)" next to addresses
+   - Tell users they're using global identity
+   - Make the behavior obvious
+
+4. **Directory names matter**
+   - `~/.co/keys/` is clear and concrete
+   - `~/.co/identity/` was abstract and confusing
+   - Users understand "keys", they question "identity"
+
+## The Result
+
+Before: 10 projects = 10 identities, 10 emails, 10 API key entries, 10 recovery phrases
+
+After: 10 projects = 1 identity, 1 email, 0 API key entries (after first), 1 recovery phrase
+
+**Time to create project #10:**
+- Before: 2 minutes (entering API key, saving recovery phrase)
+- After: 2 seconds
+
+## Deeper Philosophical Insights
+
+### The Identity Paradox
+
+We started with a computer science assumption: "Each agent needs its own cryptographic identity for security and isolation." But we discovered a human truth: **Identity isn't about isolation, it's about connection.**
+
+When developers create agents, they're not creating separate entities—they're extending themselves. The agent IS the developer, speaking through code. Forcing separate identities was like forcing someone to use different signatures for every document they sign.
+
+### The Simplicity Gradient
+
+Most systems force you up the complexity mountain immediately:
+```
+Day 1: "Here's your keypair, recovery phrase, wallet address,
+        API configuration, network registration..."
+```
+
+We inverted this. Start at sea level, climb only when you need the altitude:
+```
+Day 1: "Here's your agent. It works."
+Day 1000: "Oh, you need deployment keys? Run 'co address'."
+```
+
+**Insight:** Complexity should be proportional to ambition, not a entry fee.
+
+### The Locality Principle
+
+We observed that trust and identity operate differently at different scales:
+
+- **Local (your machine):** Everything trusts everything. One identity makes sense.
+- **Team (your organization):** Selective trust. Some shared identity, some unique.
+- **Global (the internet):** Zero trust. Every agent needs unique identity.
+
+Our design mirrors this reality. Local development uses global identity (high trust), deployment triggers project identity (low trust).
+
+### The Repetition Revelation
+
+Every time a user enters the same API key again, they're not thinking "good security practice." They're thinking "this tool doesn't respect my time."
+
+**The principle we discovered:** Repetition without purpose is disrespect.
+
+If the API key is the same, if the user is the same, if the purpose is the same—why pretend otherwise?
+
+### The Conservation of Complexity
+
+We realized we couldn't eliminate complexity, only move it:
+
+**Option A:** Complex for users (our old way)
+- Users manage multiple identities
+- Users enter API keys repeatedly
+- Users track which key is which
+
+**Option B:** Complex for us (our new way)
+- We manage global config initialization
+- We handle key copying logic
+- We provide migration paths
+
+We chose to bear the complexity so users don't have to. **This is the fundamental trade-off of good design: the creator suffers so the user doesn't.**
+
+### The YAGNI Principle (You Aren't Gonna Need It)
+
+We asked ourselves: "How many projects actually need separate identities?"
+
+Real data from users:
+- Local experiments: 70% (don't need unique identity)
+- Learning projects: 20% (don't need unique identity)
+- Shared demos: 8% (don't need unique identity)
+- Production deployments: 2% (might need unique identity)
+
+We were optimizing for the 2% while punishing the 98%.
+
+## The Ultimate Principle
+
+After all the analysis, we arrived at a simple truth:
+
+> **"The tool should work the way humans think, not the way computers compute."**
+
+Humans think: "I am creating these agents, they represent me."
+Computers compute: "Each process needs isolated credentials."
+
+We chose the human way.
+
+## Conclusion
+
+By making identity and email global by default, we removed the biggest source of friction in ConnectOnion. Developers can now focus on building agents, not managing identities.
+
+The design follows our core philosophy: **"Keep simple things simple, make complicated things possible."**
+
+But more deeply, it reflects a belief about tools and their users: The best tools disappear. They don't announce their complexity or demand your attention. They quietly do what you expect, so you can focus on what you're creating, not on the tool itself.
+
+Sometimes the best design decision is recognizing that developers don't want to manage infrastructure—they want to build. And sometimes, the most profound technical decision is choosing to be less technical.

connectonion/cli/co_ai/prompts/connectonion/design-decisions/012-tool-execution-separation.md

@@ -0,0 +1,259 @@
+# Design Decision: Why We Split Tool Execution from Agent.py
+
+*Date: 2025-09-26*
+*Status: Implemented*
+*Impact: Major refactoring reducing agent.py from 400+ to 260 lines*
+
+## The Problem: A 150-Line Monster Method
+
+Our `agent.py` had become a jungle. The `input()` method alone was 150+ lines of deeply nested code:
+
+```python
+def input(self, prompt):
+    # Setup messages...
+    # Call LLM...
+    # If tool calls:
+        # For each tool:
+            # Try:
+                # Setup xray context...
+                # Time execution...
+                # Execute tool...
+                # Update history...
+                # Format messages...
+            # Except:
+                # Handle errors...
+                # Clean up context...
+                # More error handling...
+    # Save history...
+    # Return result...
+```
+
+Reading this code was like solving a puzzle. Testing it? Nearly impossible.
+
+## The "Aha!" Moment
+
+We realized we were mixing THREE completely different concerns:
+
+1. **Tool Creation** - Converting functions to tools (compile-time)
+2. **Tool Execution** - Running tools with timing/errors (runtime)
+3. **Agent Orchestration** - Managing the conversation flow
+
+It's like having your recipe book, cooking process, and restaurant management all in the same manual. No wonder it was confusing!
+
+## The Solution: Three Clear Files
+
+```
+tool_factory.py    → Makes tools from functions (recipe book)
+tool_executor.py   → Runs tools with all tracking (cooking process)
+agent.py          → Orchestrates everything (restaurant management)
+```
+
+### Before: Everything Tangled
+
+```python
+# agent.py - A massive file doing everything
+class Agent:
+    def input(self, prompt):
+        # 150 lines of:
+        # - Creating messages
+        # - Calling LLM
+        # - Parsing responses
+        # - Setting up xray context
+        # - Executing tools
+        # - Handling errors
+        # - Tracking timing
+        # - Formatting results
+        # - Updating history
+        # 😵‍💫
+```
+
+### After: Clean Separation
+
+```python
+# agent.py - Just orchestration
+class Agent:
+    def _execute_and_record_tools(self, tool_calls, ...):
+        # One line! Delegate to the expert
+        execute_and_record_tools(
+            tool_calls,
+            self.tools,  # ToolRegistry with O(1) lookup
+            console=self.console if self.debug else None
+        )
+```
+
+## The Clever Bit: Always Collect, Conditionally Display
+
+We had a debate: Should we only collect execution data when debugging is on?
+
+### ❌ The Obvious (Wrong) Approach
+
+```python
+if debug:
+    start_time = time.time()
+    result = execute_tool()
+    duration = time.time() - start_time
+    save_timing(duration)
+else:
+    result = execute_tool()
+```
+
+This creates two code paths. Bugs hide in the path you're not testing.
+
+### ✅ The Smart Approach
+
+```python
+# ALWAYS collect data
+start_time = time.time()
+result = execute_tool()
+duration = time.time() - start_time
+execution_history.append({
+    "tool": name,
+    "duration": duration,
+    "result": result
+})
+
+# CONDITIONALLY display
+if console:  # If console is provided
+    console.print(f"Executed in {duration}ms")
+```
+
+**Why This is Brilliant:**
+- Same code path always = fewer bugs
+- Xray can show history regardless of console settings
+- Tiny performance cost (just dict operations)
+- Can add logging/metrics later without changing execution
+
+## What Each File Does Now
+
+### `tool_factory.py` (was `tools.py`)
+**Purpose:** Convert Python functions → Agent tools
+
+```python
+def search(query: str) -> str:
+    return f"Results for {query}"
+
+# tool_factory converts this to:
+{
+    "name": "search",
+    "parameters": {"query": {"type": "string"}},
+    "run": <function>
+}
+```
+
+### `tool_executor.py` (NEW!)
+**Purpose:** Execute tools with all the complexity
+
+```python
+def execute_single_tool(...):
+    # ✅ Always tracks timing
+    # ✅ Always records history
+    # ✅ Always handles errors
+    # ✅ Manages xray context
+    # ✅ Formats results
+
+    # But only prints if console provided
+    if console:
+        console.print("→ Executing tool...")
+```
+
+### `agent.py` (Simplified)
+**Purpose:** Orchestrate the flow
+
+```python
+def input(prompt):
+    messages = create_messages(prompt)
+
+    for _ in range(max_iterations):
+        response = get_llm_decision(messages)
+        if response.has_tools:
+            execute_tools(response.tool_calls)  # Delegate!
+        else:
+            return response.content
+```
+
+## The Results: Night and Day
+
+### Before
+- 🔴 `agent.py`: 400+ lines, hard to navigate
+- 🔴 `input()` method: 150+ lines of nested complexity
+- 🔴 Testing: "Good luck with that"
+- 🔴 Adding features: Touch everything, break something
+
+### After
+- 🟢 `agent.py`: 260 lines, clean orchestration
+- 🟢 Each method: <20 lines, single purpose
+- 🟢 Testing: Can test execution independently
+- 🟢 Adding features: Clear where code belongs
+
+## Lessons for Your Own Code
+
+### 1. The 50-Line Rule
+If a method is over 50 lines, it's doing too much. Period.
+
+### 2. Definition vs Execution
+These are ALWAYS different concerns:
+- **Definition**: What something IS
+- **Execution**: How something RUNS
+
+### 3. Always Collect, Conditionally Display
+Don't create branching paths based on debug flags. Collect everything, display what's needed.
+
+### 4. Name Your Files Like a Human
+- ❌ `utils.py` (what utilities?)
+- ❌ `helpers.py` (helping with what?)
+- ✅ `tool_factory.py` (makes tools!)
+- ✅ `tool_executor.py` (executes tools!)
+
+## What This Enables
+
+Now that execution is isolated, we can easily add:
+
+```python
+# Parallel execution (future)
+async def execute_tools_parallel(tool_calls):
+    results = await asyncio.gather(*[
+        execute_single_tool(tc) for tc in tool_calls
+    ])
+
+# Execution middleware (future)
+def with_retry(max_retries=3):
+    def execute_with_retry(tool_call):
+        for i in range(max_retries):
+            try:
+                return execute_single_tool(tool_call)
+            except Exception as e:
+                if i == max_retries - 1:
+                    raise
+
+# Execution analytics (future)
+class ExecutionAnalytics:
+    def track(self, execution_history):
+        avg_duration = mean([e["duration"] for e in execution_history])
+        slowest_tool = max(execution_history, key=lambda e: e["duration"])
+```
+
+None of this would be clean without the separation.
+
+## The Philosophy
+
+This refactoring embodies our core principle:
+
+> "Keep simple things simple, make complicated things possible"
+
+- **Simple**: Calling a tool is now one line in agent.py
+- **Complicated**: All the execution complexity is isolated where it can grow without affecting the rest
+
+## Try This Yourself
+
+Next time you have a complex method:
+
+1. **List what it does** (if the list is >3 items, it's too much)
+2. **Group related operations** (these become your modules)
+3. **Name the groups clearly** (these become your filenames)
+4. **Always collect data** (conditionally display)
+
+Your future self will thank you.
+
+---
+
+*"The best code is not the code that works, but the code that clearly shows HOW it works."*