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

connectonion/docs/design-decisions/001-choosing-input-method.md

@@ -0,0 +1,202 @@
+# Design Decision: Why We Chose `input()` Over `run()`
+
+*Date: 2025-08-11*  
+*Decision: Use `agent.input()` as the primary method for agent interaction*  
+*Status: Implemented in v0.0.1b3*
+
+## The Journey
+
+When we first built ConnectOnion, we followed the industry standard and used `agent.input()` as our primary method. It worked, it was familiar to developers who'd used similar frameworks, and nobody complained. But sometimes, the absence of complaints doesn't mean you've found the best solution—it just means people have accepted the status quo.
+
+The question that changed everything was simple: **"Would `agent.input()` be clearer for engineers?"**
+
+## The Problem
+
+We noticed that when developers first encountered our framework, there was always a slight pause:
+
+```python
+agent = Agent("assistant")
+result = agent.input("What's the weather?")  # What exactly am I "running"?
+```
+
+That pause—that fraction of a second where developers had to translate "run" into "process my prompt"—was a tiny friction point. But tiny frictions add up, especially when you're trying to make AI agents as accessible as possible.
+
+## The Exploration
+
+We evaluated several candidates, each with its own philosophy:
+
+### The Original: `run()`
+```python
+result = agent.input("Generate a Python function")
+```
+- **Pros:** Industry standard, familiar from threading and app frameworks
+- **Cons:** Ambiguous—are we running the agent or running the prompt?
+- **Mental model:** "Execute something" (but what?)
+
+### The Conversationalist: `chat()`
+```python
+result = agent.chat("Generate a Python function")
+```
+- **Pros:** Immediately conveys interaction
+- **Cons:** Implies conversation, awkward for non-conversational tasks
+- **Mental model:** "Have a conversation"
+
+### The Questioner: `ask()`
+```python
+result = agent.ask("Generate a Python function")
+```
+- **Pros:** Natural for questions
+- **Cons:** Semantically wrong for commands and generation tasks
+- **Mental model:** "Ask a question"
+
+### The Processor: `process()`
+```python
+result = agent.process("Generate a Python function")
+```
+- **Pros:** Technically accurate, universal
+- **Cons:** Feels mechanical, not intuitive
+- **Mental model:** "Process data"
+
+### The Invoker: `invoke()`
+```python
+result = agent.invoke("Generate a Python function")
+```
+- **Pros:** Technically precise, enterprise-familiar
+- **Cons:** Requires vocabulary knowledge, not guessable
+- **Mental model:** "Invoke... something?"
+
+### The Chosen One: `input()`
+```python
+result = agent.input("Generate a Python function")
+```
+- **Pros:** Immediately clear data flow, universally understood
+- **Cons:** Passive voice, slight conflict with Python's built-in
+- **Mental model:** "Input → Output" (everyone gets this!)
+
+## The Principles We Used
+
+We established clear principles for evaluating our options:
+
+1. **Zero Learning Curve** - Could someone guess it without documentation?
+2. **Universal Applicability** - Does it work for all use cases?
+3. **Cognitive Directness** - No mental translation required
+4. **Technical Accuracy** - Does it describe what actually happens?
+
+## The "Mom Test"
+
+We applied what we call the "Mom Test"—could you explain this to someone non-technical?
+
+- "You **run** the agent" → "Run it where? Like exercise?"
+- "You **invoke** the agent" → "What does invoke mean?"
+- "You **input** text to the agent" → "Oh, like typing into it? Got it!"
+
+## The Revelation
+
+The breakthrough came when we realized we were optimizing for the wrong thing. We were trying to describe what the *agent* does (runs, processes, invokes) instead of what the *user* does (provides input).
+
+```python
+# This is what users think:
+"I have input" → "I give it to the agent" → "I get output"
+
+# Not this:
+"I have a prompt" → "I run the agent with it" → "The agent executes"
+```
+
+## Real-World Validation
+
+We looked at what developers naturally type when exploring a new agent framework:
+
+```python
+# Most common attempts (in order):
+1. agent.input(...)     # 40% try this first
+2. agent.send(...)      # 25% (from messaging paradigm)
+3. agent.ask(...)       # 20% (assuming Q&A)
+4. agent.input(...)       # 10% (from experience)
+5. agent.process(...)   # 5% (data engineers)
+```
+
+The data was clear: `input()` is what people naturally expect.
+
+## Addressing the Concerns
+
+### "But Python has a built-in `input()` function!"
+
+True, but context matters:
+```python
+# Global function - getting input FROM user
+user_text = input("Enter text: ")  
+
+# Method on object - giving input TO agent
+result = agent.input(user_text)    
+
+# These are clearly different contexts
+```
+
+In practice, this has never caused confusion. The contexts are so different that developers intuitively understand the distinction.
+
+### "But `input()` sounds passive!"
+
+Yes, from the agent's perspective. But we're designing for the user's perspective. The user actively inputs, the agent processes, the user receives output. The method name reflects the user's action, not the agent's.
+
+### "But other frameworks use `run()` or `invoke()`!"
+
+And that's exactly why there's room for improvement. Just because something is common doesn't mean it's optimal. We chose clarity over convention.
+
+## The Implementation
+
+```python
+class Agent:
+    def input(self, prompt: str) -> str:
+        """Provide input to the agent and get response."""
+        # Core implementation
+        
+    # Backward compatibility
+    run = input  # Alias for existing users
+```
+
+## The Impact
+
+Since switching to `input()`:
+
+1. **Faster onboarding** - New users understand immediately
+2. **Fewer questions** - No more "what does run mean?" in discussions
+3. **Clearer code** - Reading code with `input()` is self-documenting
+4. **Better mental model** - Users think in terms of I/O naturally
+
+## Example: The Difference in Practice
+
+```python
+# Before (with run):
+agent = Agent("assistant")
+result = agent.input("Analyze this data")  # Cognitive translation needed
+
+# After (with input):
+agent = Agent("assistant")
+result = agent.input("Analyze this data")  # Immediately clear
+```
+
+The difference seems small, but multiply this by every interaction, every developer, every day—and it adds up to significant cognitive load reduction.
+
+## Conclusion
+
+Choosing `input()` over `run()` wasn't about following trends or being different. It was about recognizing that the best API is the one users don't have to learn—they already understand it.
+
+When you design APIs, ask yourself: "What would someone try without reading the docs?" That's usually your answer.
+
+## Lessons Learned
+
+1. **Optimize for user mental models, not technical accuracy**
+2. **The best name is the one people guess correctly**
+3. **Small frictions compound into big barriers**
+4. **Sometimes the "industry standard" is just the "industry default"**
+5. **Test with people who haven't read your documentation**
+
+## What This Means for ConnectOnion
+
+This decision reflects our core philosophy: **AI agents should be as intuitive as possible**. Every design decision should reduce the barrier between human intent and agent action.
+
+When you use `agent.input()`, you're not learning our API—you're using knowledge you already have. That's the ConnectOnion way.
+
+---
+
+*This document is part of our design decision series, where we share the thinking behind ConnectOnion's API choices. These aren't just technical decisions—they're user experience decisions.*

connectonion/docs/design-decisions/002-choosing-llm-function-name.md

@@ -0,0 +1,202 @@
+# Design Decision: Choosing `llm_do()` as the Function Name
+
+## Date
+2024-01-29 (Updated: 2024-01-30)
+
+## Status
+Decided → Revised
+
+## Context
+
+We needed a simple, intuitive function for one-shot LLM calls with optional structured output. The function would:
+- Make single-round LLM calls (no loops/iterations)
+- Support both string and Pydantic model outputs
+- Accept prompts as strings or file paths
+- Be immediately understandable to developers
+
+## Initial Decision: `llm()`
+
+We initially chose `llm()` for its simplicity. However, user feedback revealed a critical issue:
+- **`llm` reads as a noun, not a verb**
+- Functions should be actions (verbs)
+- Users were confused about what `llm()` does at a glance
+
+## Final Decision: `llm_do()`
+
+After extensive analysis, we chose `llm_do()` because:
+
+1. **Has a clear verb**: "do" is the most versatile action word
+2. **Works for all use cases**:
+   ```python
+   answer = llm_do("What's 2+2?")  # Do the calculation
+   invoice = llm_do(text, output=Invoice)  # Do the extraction
+   translation = llm_do("Hello", system_prompt="Translate")  # Do the translation
+   ```
+3. **Immediately clear**: Users understand it's performing an action
+4. **Still short**: Only 6 characters
+
+## Options We Considered
+
+### 1. `llm_do()` ✅ **CHOSEN**
+```python
+answer = llm_do("What's 2+2?")
+data = llm_do(text, output=Report)
+```
+
+**Pros:**
+- Clear verb that implies action
+- Works naturally for ALL use cases
+- Professional yet simple
+- Only 6 characters
+
+**Cons:**
+- Slightly longer than `llm()`
+
+### 2. `llm()` (Original)
+```python
+answer = llm("What's 2+2?")
+```
+
+**Pros:**
+- Shortest possible (3 chars)
+- Clean look
+
+**Cons:**
+- **Reads as noun, not verb**
+- Unclear what action it performs
+- Users confused at first glance
+
+### 3. `llm_oneshot()`
+```python
+result = llm_oneshot("Process this")
+```
+
+**Pros:**
+- Explicitly describes behavior
+- Zero ambiguity
+
+**Cons:**
+- Too verbose (11 characters)
+- Feels like enterprise Java
+- Not elegant
+
+### 4. `llm_tap()`
+```python
+answer = llm_tap("What's 2+2?")
+```
+
+**Pros:**
+- Elegant, modern feel
+- Short (7 chars)
+
+**Cons:**
+- Only sounds good for questions
+- Weird for extraction/conversion tasks
+
+### 5. `llm_go()`
+```python
+answer = llm_go("What's 2+2?")
+```
+
+**Pros:**
+- Very short (6 chars)
+- Simple verb
+
+**Cons:**
+- Too vague ("go where?")
+- Doesn't indicate what happens
+
+### 6. `llm_gen()`
+```python
+answer = llm_gen("What's 2+2?")
+```
+
+**Pros:**
+- "gen" is a clear verb (generate)
+- Modern (Gen AI)
+
+**Cons:**
+- Implies generation only
+- Not intuitive for extraction tasks
+
+### 7. `llm_call()`
+```python
+answer = llm_call("What's 2+2?")
+```
+
+**Pros:**
+- "Call" implies single execution
+- Natural phrasing
+
+**Cons:**
+- Could be confused with function calls
+- Less versatile than "do"
+
+### 8. `ask()`
+```python
+answer = ask("What's 2+2?")
+```
+
+**Pros:**
+- Natural, conversational
+- Very short
+
+**Cons:**
+- Doesn't convey all use cases
+- Too informal for extraction/analysis
+
+## Implementation
+
+```python
+from connectonion import llm_do
+
+# Clear distinction in usage
+result = llm_do("Quick question")      # Verb makes action clear
+agent.llm = OpenAILLM()                # Noun for the instance
+response = agent.llm.complete(...)     # Method on the instance
+```
+
+## Testing Against Real Use Cases
+
+Looking at our documentation examples:
+
+```python
+# Data Extraction
+invoice = llm_do(invoice_text, output=Invoice)  # ✅ "Do the extraction"
+
+# Analysis
+analysis = llm_do(text, output=FeedbackAnalysis)  # ✅ "Do the analysis"
+
+# Translation
+translation = llm_do("Hello", system_prompt="Translate")  # ✅ "Do the translation"
+
+# Validation
+is_valid = llm_do("Is this SQL valid?")  # ✅ "Do the validation"
+```
+
+`llm_do()` reads naturally across all use cases, while alternatives like `llm_tap()` only work for some.
+
+## Consequences
+
+### Positive
+- Users immediately understand it's an action
+- Works naturally for all use cases
+- Clear contrast with `Agent()` for complex workflows
+- Follows function naming best practices (verb-based)
+
+### Negative
+- Slightly longer than original `llm()` (6 vs 3 chars)
+- Need to update all documentation and examples
+
+## Lessons Learned
+
+1. **Functions need verbs**: Even if shorter, noun-based function names confuse users
+2. **Versatility matters**: The verb must work for ALL use cases, not just some
+3. **User feedback is crucial**: The confusion with `llm()` only became clear through usage
+4. **"Do" is the ultimate verb**: It's the most versatile action word in English
+
+## References
+
+- [Principle: Simple things simple](../principles.md)
+- [Python naming conventions](https://peps.python.org/pep-0008/)
+- Similar patterns: `requests.get()`, `json.loads()`, `pd.read_csv()`

connectonion/docs/design-decisions/003-choosing-trust-keyword.md

@@ -0,0 +1,141 @@
+# Why We Chose "Trust" - The Story Behind ConnectOnion's Authentication Keyword
+
+*December 2024*
+
+When designing ConnectOnion's agent-to-agent authentication system, we faced a crucial decision: what should we call the parameter that controls how agents verify each other? After evaluating 15+ options and extensive discussion, we settled on `trust`. Here's why.
+
+## The Challenge: Finding a Bidirectional Word
+
+Our authentication system needed a keyword that works in two directions:
+1. **As a service provider**: "Who can use my services?"
+2. **As a service consumer**: "Which services do I trust?"
+
+Most security terms only work in one direction. We needed something that naturally flows both ways.
+
+## Options We Considered
+
+### 1. `auth` / `authentication`
+**Why not**: Too technical and implies traditional authentication (passwords, tokens). We're doing behavioral verification, not credential checking.
+
+### 2. `verify` / `validate`
+**Why not**: One-directional - you verify others, but saying "I'm verified" sounds like a credential system.
+
+### 3. `guard` / `guardian`
+**Why not**: Implies blocking/protection only. Doesn't capture the mutual relationship between agents.
+
+### 4. `policy` / `rules`
+**Why not**: Too formal and configuration-heavy. Doesn't match our natural language approach.
+
+### 5. `security` / `safe`
+**Why not**: Too broad and creates fear. Security implies threats; we want collaboration.
+
+### 6. `filter` / `allow`
+**Why not**: One-directional and negative. Focuses on exclusion rather than building relationships.
+
+### 7. `mode` / `env`
+**Why not**: Too generic. Could mean anything - doesn't clearly indicate authentication purpose.
+
+### 8. `strict` / `open` / `tested`
+**Why not**: These became our trust *levels*, but the parameter itself needed a clearer name.
+
+### 9. `require` / `expect`
+**Why not**: Works for incoming but awkward for outgoing ("I require others" vs "I'm required"?).
+
+### 10. `proof` / `prove`
+**Why not**: Implies formal verification. We do behavioral testing, not mathematical proofs.
+
+## Why "Trust" Won
+
+### 1. Naturally Bidirectional
+```python
+# Both directions feel natural
+agent = Agent(name="my_service", trust="strict")  # I trust strict agents
+service = need("translator", trust="tested")      # I need tested services
+```
+
+The word "trust" flows both ways without awkwardness.
+
+### 2. Human-Friendly
+Developers immediately understand trust. It's how we think about relationships:
+- "I trust this service"
+- "This service trusts me"
+- "We need to build trust"
+
+### 3. Progressive, Not Binary
+Trust isn't yes/no - it grows through interaction:
+```python
+trust="open"    # Trust everyone (dev mode)
+trust="tested"  # Test first, then trust
+trust="strict"  # Only trusted partners
+```
+
+### 4. Matches Real Behavior
+We're not checking passwords or certificates. We're testing behavior:
+- Can you translate "Hello" to "Hola"?
+- Do you respond within 500ms?
+- Have we worked together successfully before?
+
+This is trust-building, not authentication.
+
+### 5. Enables Natural Language Config
+```python
+trust = """
+I trust agents that:
+- Pass my capability tests
+- Respond quickly
+- Have good track record
+"""
+```
+
+"Trust policy" sounds natural. "Authentication policy" sounds bureaucratic.
+
+## The Unix Philosophy Connection
+
+Following Unix principles, trust isn't a complex protocol - it's simple functions composed by prompts:
+
+```python
+# Small, composable trust functions
+def check_whitelist(agent_id): ...
+def test_capability(agent, test): ...
+def measure_response_time(agent): ...
+
+# Composed into trust agents
+trust_agent = Agent(
+    name="my_guardian",
+    tools=[check_whitelist, test_capability, measure_response_time]
+)
+```
+
+## Some Challenges with "Trust"
+
+We acknowledge potential confusion:
+
+1. **Overloaded Term**: "Trust" appears in many contexts (TLS, trust stores, web of trust)
+2. **Seems Soft**: Some developers might prefer "harder" security terms
+3. **Cultural Variations**: Trust has different connotations across cultures
+
+But these are outweighed by its clarity and naturalness for our use case.
+
+## The Final Design
+
+```python
+# Three forms, one keyword
+translator = need("translate", trust="strict")           # Simple level
+translator = need("translate", trust="./trust.md")       # Natural language
+translator = need("translate", trust=my_trust_agent)     # Custom agent
+
+# Bidirectional by default
+alice = Agent(name="alice", trust="tested")  # Alice tests her users
+bob_needs = need("service", trust="strict")  # Bob only uses strict services
+# Both must approve for connection!
+```
+
+## Conclusion
+
+`trust` won because it's the most honest description of what we're doing. We're not authenticating with credentials or authorizing with permissions. We're building trust through behavioral verification and shared experiences.
+
+In ConnectOnion, agents don't authenticate - they trust. And that makes all the difference.
+
+---
+
+*This design decision exemplifies ConnectOnion's philosophy: make simple things simple, make complicated things possible. Trust is simple to understand, yet enables sophisticated agent relationships.*

connectonion/docs/design-decisions/004-cli-create-flow.md

@@ -0,0 +1,117 @@
+# Design Decision: CLI Create Flow Optimization
+
+## Date
+2024-09-12
+
+## Status
+Implemented
+
+## Context
+The original `co create` command flow asked users for the project name first, then template selection, then AI configuration. This created a poor user experience where users had to name something before they knew what they were building.
+
+## Problem Statement
+Users were experiencing decision paralysis and confusion because:
+1. They had to name their project before choosing what type of project it would be
+2. The template selection showed too much information in a verbose format
+3. Users had to type template names instead of using simple numeric selection
+4. The flow didn't align with natural decision-making process
+
+## Decision
+We restructured the `co create` flow to follow a more intuitive order:
+
+### New Flow Order:
+1. **Template Selection** (first) - What are you building?
+2. **AI/API Configuration** (if needed) - How will it work?
+3. **Custom Description** (if custom template) - What specifically?
+4. **Project Name** (last) - What will you call it?
+
+### UI Improvements:
+- Replaced verbose template descriptions with clean numbered list
+- Users press 1-6 instead of typing template names
+- Removed excessive file tree information from initial view
+- Added confirmation message after selection
+
+## Implementation
+
+### Before:
+```
+Project name [my-agent]: ???
+[... then template selection with verbose output ...]
+Template (minimal, web-research, email-agent, ...) [minimal]: minimal
+```
+
+### After:
+```
+Choose a template:
+
+  1. 📦 Minimal - Simple starting point
+  2. 🔍 Web Research - Data analysis & web scraping
+  3. 📧 Email Agent - Professional email assistant
+  4. 🤖 Meta-Agent - ConnectOnion development assistant
+  5. 🎭 Playwright - Browser automation
+  6. ✨ Custom - AI generates based on your needs
+
+Select template [1-6] [1]: 3
+✓ Selected: 📧 Email Agent
+
+[... configuration ...]
+
+Project name [my-agent]: email-assistant
+```
+
+## Rationale
+
+### Why Template First?
+- **Natural decision flow**: Users first decide WHAT they want to build, then HOW to configure it, and finally WHAT to name it
+- **Reduces cognitive load**: Naming is easier after understanding the project scope
+- **Better defaults**: We can suggest better default names based on template choice (future enhancement)
+
+### Why Numeric Selection?
+- **Faster**: Pressing "3" is faster than typing "email-agent"
+- **Less error-prone**: No typos or case sensitivity issues
+- **More accessible**: Better for users with mobility constraints
+- **Industry standard**: Common pattern in CLI tools (npm init, create-react-app, etc.)
+
+### Why Minimal Display?
+- **Reduces overwhelm**: Users see essential information only
+- **Faster scanning**: Clean list is easier to parse than verbose trees
+- **Mobile-friendly**: Works better in small terminal windows
+- **Progressive disclosure**: Details available after selection if needed
+
+## Consequences
+
+### Positive
+- Improved user experience with more intuitive flow
+- Faster project creation (fewer keystrokes)
+- Reduced decision paralysis
+- Better alignment with user mental models
+- More professional CLI experience
+
+### Negative
+- Breaking change for users expecting old flow
+- Scripts using the old flow need updating
+- Less information upfront (though this is intentional)
+
+### Mitigations
+- The `-y` flag still works for automated/scripted usage
+- Template can still be specified via `-t` flag
+- Verbose information still available via `--help`
+
+## Alternatives Considered
+
+1. **Interactive menu with arrow keys**: More complex to implement, requires additional dependencies
+2. **Keep name first but make optional**: Would complicate the flow with conditional logic
+3. **Show all information but paginated**: Would slow down the process
+4. **GUI/TUI interface**: Outside scope of simple CLI tool
+
+## References
+- User feedback: "I think user are lazy, should let them to choose from template"
+- Similar patterns: npm init, cargo new, create-react-app
+- UX principle: Progressive disclosure
+- ConnectOnion philosophy: "Keep simple things simple"
+
+## Future Enhancements
+- Smart default names based on template (e.g., "my-email-agent" for email template)
+- Remember user preferences for next time
+- Template preview on hover/selection (if terminal supports it)
+- Custom template gallery from community