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

connectonion/docs/design-decisions/008-naming-is-hard.md

@@ -0,0 +1,228 @@
+# Naming is Hard: Why We Chose "Address" Over "Identity"
+
+*September 3, 2025*
+
+There's a famous quote in computer science: "There are only two hard things in Computer Science: cache invalidation and naming things." Today, we're talking about the second one.
+
+## The Naming Dilemma
+
+When implementing key generation for ConnectOnion agents, we had a seemingly simple decision: what do we call this thing that uniquely identifies an agent?
+
+Our first draft:
+```python
+# connectonion/crypto.py
+def generate_agent_identity():
+    """Generate cryptographic identity for agent."""
+    ...
+```
+
+It felt sophisticated. Technical. Important. It also felt... wrong.
+
+## The Options We Considered
+
+### Option 1: Identity
+```python
+identity = generate_agent_identity()
+print(f"Agent identity: {identity}")
+```
+
+**Pros:**
+- Sounds comprehensive
+- Technically accurate (it IS an identity)
+- Used by many identity systems
+
+**Cons:**
+- Abstract and vague
+- Makes users think "identity management" (scary!)
+- Overloaded term in software
+
+### Option 2: ID
+```python
+agent_id = generate_agent_id()
+print(f"Agent ID: {agent_id}")
+```
+
+**Pros:**
+- Short and simple
+- Familiar from databases
+
+**Cons:**
+- Too generic
+- Doesn't convey that it's cryptographic
+- Confusion with database IDs
+
+### Option 3: Key
+```python
+agent_key = generate_agent_key()
+print(f"Agent key: {agent_key}")
+```
+
+**Pros:**
+- Technically accurate
+- Developers understand keys
+
+**Cons:**
+- Which key? Public? Private?
+- Sounds like API keys
+- Implementation detail, not user concept
+
+### Option 4: Address
+```python
+address = generate_address()
+print(f"Agent address: {address}")
+```
+
+**Pros:**
+- Immediately understood
+- Familiar from email, web, crypto
+- Concrete and specific
+- Matches user mental model
+
+**Cons:**
+- ...actually, none?
+
+## The Winner: Address
+
+We chose "address" because it just makes sense. Everyone understands addresses:
+- Email has addresses
+- Websites have addresses  
+- Ethereum has addresses
+- Even physical mail has addresses
+
+When you tell someone "this is your agent's address," they immediately understand it's how others can reach that agent.
+
+## The Ripple Effect
+
+Once we chose "address," everything else fell into place:
+
+```python
+# Before (confusing)
+from connectonion.crypto import generate_agent_identity
+identity = generate_agent_identity()
+save_identity(identity)
+
+# After (clear)
+from connectonion.address import generate
+address = generate()
+save(address)
+```
+
+The file name became obvious too:
+- ❌ `crypto.py` - Scary, too broad
+- ❌ `identity.py` - Abstract
+- ❌ `keys.py` - Implementation detail
+- ✅ `address.py` - Perfect!
+
+## Function Names Got Simpler Too
+
+When the module name provides context, function names can be simpler:
+
+```python
+# connectonion/address.py
+
+def generate() -> dict:
+    """Generate new agent address."""
+    
+def recover(seed_phrase: str) -> dict:
+    """Recover address from seed phrase."""
+    
+def save(address_data: dict, path: Path):
+    """Save address keys."""
+    
+def load(path: Path) -> dict:
+    """Load address keys."""
+    
+def verify(address: str, message: bytes, signature: bytes) -> bool:
+    """Verify signature from address."""
+```
+
+No need to repeat "address" in every function - the module name makes it clear.
+
+## The Lesson: Use Familiar Words
+
+We developers love to invent new terminology. It makes us feel smart. But users don't care about our clever naming - they just want things to make sense.
+
+Consider these transformations:
+- "Cryptographic identity" → "Address"
+- "Mnemonic seed phrase" → "Recovery phrase"  
+- "Ed25519 public key" → "Agent address"
+- "Signing key" → "Private key"
+
+The right side is always clearer.
+
+## A Real Conversation
+
+This actual conversation happened during code review:
+
+"What should we call the thing that identifies an agent?"
+"What does it do?"
+"Other agents use it to send messages to this agent."
+"So... an address?"
+"Oh. Yeah. An address."
+
+Sometimes the obvious answer is the right answer.
+
+## The Bigger Pattern
+
+This decision reflects a broader pattern in ConnectOnion:
+
+1. **Use existing mental models** - Don't make users learn new concepts
+2. **Prefer concrete over abstract** - "Address" not "Identity"
+3. **Choose familiar over precise** - "Recovery phrase" not "BIP39 mnemonic"
+4. **Name from the user's perspective** - Not from the implementation
+
+## The Implementation
+
+Here's what we ended up with:
+
+```python
+from connectonion import address
+
+# Generate new agent (simple!)
+my_address = address.generate()
+print(f"Agent address: {my_address['address']}")
+
+# Save it (obvious!)
+address.save(my_address, Path(".co"))
+
+# Load it later (clear!)
+my_address = address.load(Path(".co"))
+```
+
+No confusion. No abstraction. Just addresses.
+
+## Counter-Examples: When We Got It Wrong
+
+We're not perfect. Here are times we chose poorly:
+
+**Bad:** `llm_do()` - What does "do" mean?
+**Better:** `llm_function()` or `llm_tool()`
+
+**Bad:** `co init` - Init what?
+**Better:** Could have been `co create` or `co new`
+
+We keep these as reminders that naming is hard, and we don't always get it right the first time.
+
+## The Test: Explain It To Someone
+
+The ultimate test for naming: explain it to someone unfamiliar with your project.
+
+"Your agent has an address. Other agents use it to send messages."
+
+vs
+
+"Your agent has a cryptographic identity derived from an Ed25519 keypair that serves as a unique identifier in the network protocol."
+
+Which would you rather hear?
+
+## Conclusion
+
+Good naming isn't about being clever or technically precise. It's about being clear. When in doubt, choose the boring, familiar word that everyone already understands.
+
+That's why every ConnectOnion agent has an address, not an identity. It's why you have a recovery phrase, not a mnemonic seed. It's why you run `co init`, not `co scaffold-project-structure`.
+
+Keep it simple. Use words people know. Save the cleverness for the implementation, not the interface.
+
+---
+
+*P.S. We spent 30 minutes debating "address" vs "identity". Those 30 minutes were worth it. Good naming pays dividends forever.*

connectonion/docs/design-decisions/009-why-connect-function.md

@@ -0,0 +1,167 @@
+# Why We Chose `connect()` for Remote Agents
+
+*The journey to finding the right interface for connecting to remote agents*
+
+## The Problem
+
+When developers want to use a remote AI agent, they need a simple, intuitive way to establish that connection. The challenge was finding the right verb that:
+- Clearly indicates remote interaction
+- Returns an object to interact with
+- Feels familiar to developers
+- Distinguishes from local agent creation
+
+## What We Considered
+
+### Option 1: `RemoteAgent()` Class
+```python
+translator = RemoteAgent("0x3d40...")
+```
+✅ Crystal clear it's remote
+❌ Verbose (11 extra characters)
+❌ Exposes implementation details
+
+### Option 2: `client()` Function
+```python
+translator = client("0x3d40...")
+```
+✅ Follows database patterns (MongoClient, RedisClient)
+❌ It's a noun, not a verb - feels awkward
+❌ Implies client/server architecture
+
+### Option 3: `get()` Function
+```python
+translator = get("0x3d40...")
+```
+✅ Shortest (3 characters)
+✅ Familiar from REST APIs
+❌ Too generic - get what exactly?
+
+### Option 4: `use()` Function
+```python
+translator = use("0x3d40...")
+```
+✅ Natural language
+✅ Very short
+❌ Too vague about what's happening
+
+### Option 5: `reach()` Function
+```python
+translator = reach("0x3d40...")
+```
+✅ Implies remote interaction
+✅ Natural English
+❌ Unfamiliar pattern in programming
+
+## Why `connect()` Won
+
+```python
+from connectonion import connect
+
+translator = connect("0x3d40...")
+result = translator.input("Translate hello")
+```
+
+### 1. Familiar Pattern
+Developers already use `connect()` everywhere:
+```python
+# Databases
+db = psycopg2.connect("postgresql://...")
+redis = redis.connect("redis://...")
+
+# Our pattern
+agent = connect("0x3d40...")
+```
+
+### 2. Clear Semantics
+The word "connect" immediately tells developers:
+- This is a network operation
+- You're establishing a connection to something remote
+- It returns something you can interact with
+
+### 3. No Confusion with Local Agents
+```python
+# Creating local agent - uses class
+my_agent = Agent("translator", tools=[...])
+
+# Connecting to remote - uses function
+their_agent = connect("0x3d40...")
+```
+
+Clear distinction: `Agent` class for creation, `connect` function for remote access.
+
+### 4. Verb Returns Noun
+`connect()` is a verb that returns a connection object - this is a natural pattern:
+- The action (connect) returns the result (connected agent interface)
+- You connect and get back something to use
+- No ambiguity about what you're getting
+
+### 5. Handles Everything Automatically
+When you call `connect()`, the framework:
+1. Connects to relay at `wss://oo.openonion.ai`
+2. Queries agent information
+3. Attempts direct TCP connection
+4. Falls back to relay if needed
+5. Returns ready-to-use interface
+
+The developer doesn't see this complexity - they just get a working agent.
+
+## The Developer Experience
+
+### Simple and Natural
+```python
+# The thought process
+"I need to use that translator agent"
+"I'll connect to it"
+"Now I can use it"
+
+# The code matches the thought
+translator = connect("0x3d40...")
+result = translator.input("Translate this")
+```
+
+### Extensible
+```python
+# Basic usage
+agent = connect("0x3d40...")
+
+# Future extensions feel natural
+agent = connect(find="translator")
+agent = connect(need="something that translates")
+```
+
+### Clear Error Messages
+```python
+# If connection fails
+"Failed to connect to agent at 0x3d40..."
+# Immediately understandable
+```
+
+## What `connect()` Returns
+
+The `connect()` function returns a limited interface - not the full agent:
+
+```python
+class ConnectedAgent:
+    def input(self, prompt: str) -> str:
+        """Send input to remote agent"""
+
+    @property
+    def address(self) -> str:
+        """The agent's address"""
+
+    def is_online(self) -> bool:
+        """Check if agent is reachable"""
+```
+
+This makes it clear you're working with a remote interface, not the agent itself.
+
+## Conclusion
+
+`connect()` strikes the perfect balance:
+- **Familiar**: Developers know this pattern from databases
+- **Clear**: Obviously a network operation
+- **Simple**: Just 7 characters
+- **Accurate**: You're connecting to get an interface
+- **Extensible**: Can grow with the framework
+
+The choice of `connect()` makes ConnectOnion feel instantly familiar while accurately representing what's happening under the hood.

connectonion/docs/design-decisions/010-cli-ux-progressive-disclosure.md

@@ -0,0 +1,176 @@
+# Why We Choose Progressive Disclosure Over Configuration Questionnaires
+
+*Date: 2025-09-04*
+
+## The Problem with Traditional CLI Tools
+
+Most framework CLIs suffer from what we call "initialization fatigue" - they bombard users with questions that don't matter yet:
+- What's your project description? (I don't know, I just started)
+- Choose your testing framework? (Let me build something first)
+- Configure your linter settings? (Please, just let me code)
+- Set up CI/CD pipeline? (It's my first 5 seconds with this tool)
+
+This approach assumes users know everything upfront. Reality: they don't, and they shouldn't have to.
+
+## Our Philosophy: Progressive Disclosure
+
+### Core Principle: Start Fast, Decide Later
+
+We designed ConnectOnion's CLI around three principles:
+1. **Get to working code in < 30 seconds**
+2. **Make smart defaults, not lengthy questionnaires**
+3. **Respect the user's time and intelligence**
+
+### The Two-Command Strategy: Why Both `create` and `init`
+
+We deliberately offer two commands instead of forcing one workflow:
+
+```bash
+co create my-agent  # Creates new directory 
+co init            # Uses current directory
+```
+
+**Why?** Because context matters:
+- **Outside a project**: Users want `co create my-agent` - it's natural to create a new space
+- **Inside a project**: Users want `co init` - they've already decided where to work
+
+This isn't redundancy; it's respecting user intent. Django does this (`django-admin startproject` vs `manage.py startapp`), Rails does this (`rails new` vs `rails generate`), and for good reason.
+
+### Minimal Questions, Maximum Intelligence
+
+Our setup flow asks only what matters RIGHT NOW:
+1. **Enable AI?** - Determines available templates
+2. **API key** - Only if AI enabled, with auto-detection
+3. **Template** - With previews so users know what they get
+
+That's it. Three decisions max.
+
+Compare to typical CLIs:
+- Create-react-app: 5+ questions
+- Vue CLI: 10+ questions  
+- Yeoman generators: Often 15+ questions
+
+### Smart API Key Detection
+
+Instead of asking "Which provider are you using?", we detect it:
+
+```python
+if api_key.startswith('sk-proj-'):
+    # OpenAI project key
+elif api_key.startswith('sk-ant-'):
+    # Anthropic  
+elif api_key.startswith('gsk_'):
+    # Groq
+```
+
+**Why?** The key format already tells us. Why make users answer what we can infer?
+
+This extends to environment variables too. If `OPENAI_API_KEY` is set, we use it. No questions asked.
+
+### Template Preview, Not Template Guessing
+
+Instead of cryptic template names, we show exactly what users get:
+
+```
+📦 Minimal - Simple starting point
+  ├── agent.py (50 lines) - Basic agent with example tool
+  ├── .env - API key configuration
+  └── .co/ - Agent identity & metadata
+```
+
+**Why?** Users shouldn't have to guess. Show them, let them choose, move on.
+
+### Silent Excellence: Auto-Generated Agent Keys
+
+We generate cryptographic keys for agents automatically. No prompt, no explanation, just done.
+
+```python
+# This happens silently during init
+addr_data = address.generate()
+address.save(addr_data, co_dir)
+```
+
+**Why?** 99% of users don't care about Ed25519 vs secp256k1. The 1% who do can read the docs.
+
+## The "No BS" Commitment
+
+### What We Don't Ask
+- Project description (write code first, document later)
+- Author name (use git config if needed)
+- License type (add it when you're ready to share)
+- Version number (it's 0.0.1, always)
+- Test framework (we include examples, you choose)
+- Package manager (pip is fine)
+
+### What We Do Instead
+- Create working code immediately
+- Use sensible defaults everywhere
+- Show clear next steps
+- Get out of the way
+
+### Beautiful by Default
+
+We use colors, emojis, and formatting not for decoration, but for clarity:
+- ✅ Green = Success
+- ⚠️ Yellow = Warning  
+- ❌ Red = Error
+- 📁 Icons = Visual scanning
+
+But we also respect terminal preferences:
+- Works in non-color terminals
+- Copy-paste friendly output
+- No ASCII art or unnecessary flair
+
+## Results: User Delight, Not User Fatigue
+
+Our approach means:
+- **30 seconds** from install to running agent
+- **3 questions** maximum during setup
+- **0 required** configuration files to edit
+- **1 command** to start coding
+
+Users consistently report that our CLI "just works" and "doesn't get in the way."
+
+## Technical Implementation Notes
+
+### Progressive Enhancement Pattern
+```python
+# Start with minimum viable
+if not yes:
+    ai = click.confirm("Enable AI features?", default=True)
+    
+# Enhance if enabled
+if ai:
+    templates.append('custom')
+    
+# But don't block progress
+if not api_key:
+    # Still create project, just remind them later
+```
+
+### Fail Gracefully, Suggest Clearly
+```python
+if project_dir.exists():
+    click.echo(f"❌ Directory '{name}' already exists!")
+    click.echo(f"💡 Suggestions:")
+    click.echo(f"   • Use different name: co create {name}-v2")
+    click.echo(f"   • Remove existing: rm -rf {name}")
+    click.echo(f"   • Initialize existing: cd {name} && co init")
+```
+
+### Environment Intelligence
+```python
+# Check environment first, ask second
+env_result = check_environment_for_api_keys()
+if env_result:
+    click.echo(f"✓ Found {provider} API key in environment")
+    # Use it unless user objects
+```
+
+## Conclusion
+
+Good CLI UX isn't about asking fewer questions - it's about asking the RIGHT questions at the RIGHT time. Everything else should be invisible, automatic, or optional.
+
+Our CLI embodies this philosophy: Start fast, enhance progressively, respect user intelligence.
+
+The best tool is one you forget you're using. That's what we built.