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

connectonion/docs/archive/mini-whitepaper.md

@@ -0,0 +1,293 @@
+# ConnectOnion: A Cost-Centric Analysis of Agent Collaboration
+
+## Executive Summary
+
+The AI agent ecosystem faces a fundamental economic problem: the cost of integration grows quadratically with the number of agents (O(n²)), making widespread collaboration economically unviable. ConnectOnion solves this by transforming integration cost to O(1) through behavioral discovery, enabling a new economic reality where agent collaboration becomes frictionless.
+
+## Part I: The Cost Structure of Digital Collaboration
+
+### The Hidden Tax on Innovation
+
+Every time two pieces of software need to work together, someone pays a cost:
+
+```
+Traditional Integration Cost = Time × Complexity × Maintenance
+                            = 10 hours × n agents × ∞
+                            = Exponential burden
+```
+
+This cost is invisible in GDP statistics but devastating to innovation velocity.
+
+### The Three Cost Laws
+
+**Law 1: Costs Can Only Transfer, Not Disappear**
+- Platform complexity → Developer time
+- API simplicity → Platform maintenance  
+- Someone always pays
+
+**Law 2: Integration Costs Grow Quadratically**
+- 10 agents = 45 possible connections
+- 100 agents = 4,950 connections
+- 1,000 agents = 499,500 connections
+- Current approach: Unscalable
+
+**Law 3: Friction Compounds Negatively**
+- Each integration barrier reduces total value
+- Network effects work in reverse
+- Most potential collaborations never happen
+
+## Part II: The ConnectOnion Revolution
+
+### The Core Innovation: Behavioral Discovery
+
+Instead of managing connections, we eliminate them:
+
+```python
+# Traditional: O(n²) complexity
+def integrate_traditional():
+    for service in all_services:
+        learn_api(service)
+        write_integration(service)
+        maintain_forever(service)
+
+# ConnectOnion: O(1) complexity  
+def integrate_behavioral():
+    agent = discover("what I need")
+    result = agent(my_input)
+```
+
+### The Four Pillars
+
+**1. Sandbox Testing → Verified Capabilities**
+```python
+def verify_agent(candidate):
+    # Test with real task
+    result = candidate.demonstrate(sample_task)
+    return result.meets_requirements()
+```
+No credentials needed. Performance is proof.
+
+**2. Topology Limits → Natural Boundaries**
+- Each agent connects to ~150 others max (Dunbar's number)
+- Attacks limited to local scope
+- No global manipulation possible
+
+**3. Local Experience → Trustless Trust**
+```python
+my_trust = my_experience(agent)           # 100% weight
+friend_trust = friend_experience(agent)   # 30% weight  
+network_trust = global_reputation(agent)  # 0% weight
+
+# We don't use global reputation at all!
+```
+
+**4. Selection Cost → Quality Filter**
+- Finding agents requires semantic matching
+- Using agents requires passing tests
+- Bad actors filtered by effort required
+
+## Part III: Economic Transformation
+
+### Developer Time Liberation
+
+**Traditional Development**
+```
+Learning curve: 2-4 hours per API
+Implementation: 4-8 hours per integration
+Debugging: 2-4 hours per integration
+Maintenance: ∞ hours
+
+Total: 1,000+ hours for 100 integrations
+Cost: $150,000 at $150/hour
+```
+
+**ConnectOnion Development**
+```
+Learning curve: 1 hour (once)
+Implementation: 1 minute per agent
+Debugging: Handled by protocol
+Maintenance: Zero
+
+Total: 3 hours for 100 agents
+Cost: $450
+Savings: 99.7%
+```
+
+### The Compound Effect
+
+When integration is free, innovation accelerates:
+
+1. **Experimentation Cost → Zero**
+   - Try 100 solutions instead of 3
+   - Fail fast without penalty
+   - Find optimal combinations
+
+2. **Composition Becomes Trivial**
+   ```python
+   # Build complex systems instantly
+   translator = discover("translation")
+   analyzer = discover("sentiment")
+   summarizer = discover("summary")
+   
+   def process(text):
+       return summarizer(analyzer(translator(text)))
+   ```
+
+3. **Network Effects Compound**
+   - Each new agent helps all others
+   - Value grows exponentially
+   - No platform lock-in
+
+### Market Size Expansion
+
+**Traditional Market**
+- Addressable: Developers willing to integrate (5%)
+- Barrier: High integration cost
+- Result: Small, specialized market
+
+**ConnectOnion Market**  
+- Addressable: Anyone who can call a function (95%)
+- Barrier: None
+- Result: 20x market expansion
+
+## Part IV: Why This Can't Be Copied
+
+### The Simplicity Moat
+
+Adding features is easy. Removing them is hard. We started simple.
+
+```
+MCP: 500+ page specification
+ConnectOnion: 100 lines of code
+```
+
+### The Network Effect Moat
+
+Every day the network grows stronger:
+- More agents → More value
+- More interactions → Better matching
+- More history → Stronger trust
+
+Traditional platforms can't replicate this without abandoning their business model.
+
+### The Behavioral Data Moat
+
+Trust history can't be faked:
+- Built through real interactions
+- Verified through actual work
+- Accumulated over time
+
+## Part V: System Design
+
+### The Minimal Viable Protocol
+
+```python
+class Agent:
+    def __init__(self):
+        self.experience = {}
+    
+    def discover(self, need):
+        # Ask neighbors
+        candidates = self.ask_neighbors(need)
+        
+        # Test them
+        results = [c.test() for c in candidates]
+        
+        # Use best
+        best = max(results)
+        
+        # Remember
+        self.experience[best] = "good"
+        
+        return best
+```
+
+That's it. 100 lines implement the entire protocol.
+
+### Natural Evolution
+
+The system evolves without central planning:
+
+1. **Good agents** get recommended more
+2. **Bad agents** fail tests and disappear  
+3. **New agents** prove themselves through work
+4. **The network** becomes smarter over time
+
+### Attack Immunity
+
+Instead of preventing attacks, we make them pointless:
+
+**Sybil Attack Attempt:**
+- Create 1000 fake agents
+- Each must pass real tests
+- Each must do real work
+- Result: You created 1000 real agents!
+
+**Reputation Gaming:**
+- No global reputation to game
+- Local experience can't be faked
+- Trust requires actual interaction
+
+## Part VI: Implementation Roadmap
+
+### Phase 1: Proof of Concept (Now)
+- Local network discovery
+- Basic behavioral matching
+- Simple test framework
+
+### Phase 2: Network Growth (Q1 2025)
+- 1,000+ agents
+- Cross-network discovery
+- Performance optimization
+
+### Phase 3: Critical Mass (Q2 2025)
+- 10,000+ agents
+- Enterprise adoption
+- Behavioral analytics
+
+### Phase 4: Ubiquity (2026)
+- Default protocol for AI collaboration
+- Million+ agents
+- Self-sustaining ecosystem
+
+## Part VII: The New Economics
+
+### Cost Flows
+
+**Traditional:**
+```
+Complexity → Integration Cost → Developer Time → Higher Prices → Less Innovation
+```
+
+**ConnectOnion:**
+```
+Simplicity → Zero Integration → Free Time → Lower Prices → More Innovation
+```
+
+### Value Creation
+
+When connection is free, value compounds:
+
+1. **Direct Value**: Save $150k per 100 integrations
+2. **Opportunity Value**: 180x more innovation time
+3. **Network Value**: Each agent adds value to all others
+4. **Compound Value**: Combinations create emergent capabilities
+
+### The Ultimate Metric
+
+**Traditional success**: How many APIs integrated?
+**ConnectOnion success**: How many problems solved?
+
+When integration is free, the only limit is imagination.
+
+## Conclusion: The Invisible Revolution
+
+ConnectOnion doesn't add features—it removes friction. In doing so, it transforms the fundamental economics of software collaboration.
+
+The revolution isn't visible in the protocol. It's visible in what developers build when integration cost approaches zero.
+
+**The future belongs to those who make complexity disappear.**
+
+---
+
+*"The best protocol is one developers don't have to think about."*

connectonion/docs/archive/network-protocol.md

@@ -0,0 +1,394 @@
+# ConnectOnion Network Protocol
+
+Minimal peer-to-peer protocol using public keys as network addresses.
+
+## Core Design
+
+### Public Keys as Addresses
+Public keys serve as network addresses, similar to IP addresses in TCP/IP. They provide a unique, unforgeable way to route messages between agents. No identity claims, no trust assumptions - just addressing.
+
+### Message-Based Architecture
+The protocol uses stateless, message-based communication similar to email. Each message is self-contained with a unique task ID for correlation. This design naturally supports parallel operations, resilience to failures, and works seamlessly across NAT boundaries. Unlike session-based protocols (HTTP/gRPC), agents don't maintain connection state - they simply exchange signed messages.
+
+### Two-Layer Separation
+**Public Discovery Layer**: ANNOUNCE and FIND messages are unencrypted broadcasts for transparency. Organizations can audit capabilities and network activity.
+**Private Collaboration Layer**: TASK messages carry encrypted payloads between agents. Actual work remains confidential while discovery stays transparent.
+
+### Developer-Controlled Broadcasting
+Agents announce themselves only when developers explicitly call the announce() function. No automatic broadcasts, no hidden network activity.
+
+## Network Topology
+
+### Agent Nodes
+Standard participants in the network. Each agent maintains connections to other agents, divided into:
+- **Contacts**: Agents with established collaborative history
+- **Strangers**: Agents discovered but not yet verified
+
+### Relay Nodes
+Infrastructure nodes that serve as message routers and connection points:
+- **Message Relay**: Forward messages between agents that cannot directly connect (NAT traversal)
+- **Presence Tracking**: Know which agents are currently connected (in memory only)
+- **Initial Discovery**: Help new agents find their first peers
+
+Relays maintain no permanent state and can be run by anyone. At scale, relays form a hierarchical network similar to CDN or DNS infrastructure.
+
+## Protocol Messages
+
+### Public Discovery Messages
+
+#### ANNOUNCE Message
+Purpose: Public broadcast of agent existence, capabilities, network endpoints, and liveness.
+
+**Data Structure:**
+```
+{
+  type: "ANNOUNCE",
+  pubkey: <sender's public key>,
+  timestamp: <unix timestamp>,
+  sequence: <incrementing counter>,
+  
+  // Network Endpoints (for connectivity)
+  endpoints: [
+    "tcp://73.42.18.9:8001",      // Public IP address
+    "tcp://192.168.1.100:8001",   // Local LAN IP  
+    "relay://abc123.connectonion.io"  // Relay lookup (returns current IP)
+  ],
+  nat_type: "none" | "full_cone" | "restricted" | "symmetric",
+  
+  // Capabilities
+  prompt_summary: <system prompt description>,
+  tools: [<list of available tools>],
+  
+  // Liveness
+  uptime: <seconds since start>,
+  last_activity: {
+    type: <"tool_call" | "task_complete">,
+    timestamp: <when>,
+    tool: <which tool if applicable>
+  },
+  
+  // Status
+  status: "active" | "idle" | "busy",
+  load: <0.0 to 1.0>,
+  
+  // Metadata
+  version: <agent version>,
+  model: <LLM model used>,
+  state_hash: <hash for change detection>
+}
+```
+
+**Characteristics:**
+- Unencrypted for transparency
+- Single-hop forwarding maximum
+- Sent on developer trigger (startup, task completion, changes, IP address change)
+
+#### FIND Message
+Purpose: Query network for specific capabilities.
+
+**Data Structure:**
+```
+{
+  type: "FIND",
+  pubkey: <requester's public key>,
+  query_id: <unique query identifier>,
+  capability: <natural language description>,
+  ttl: <hop counter, typically 3-4>,
+  timestamp: <unix timestamp>
+}
+```
+
+**Characteristics:**
+- Propagates through network (TTL-limited)
+- Small size for efficient flooding
+- Responses return via ANNOUNCE
+
+### Private Collaboration Messages
+
+#### TASK Message
+Purpose: Carry actual work between agents.
+
+**Data Structure:**
+```
+{
+  type: "TASK",
+  from: <sender pubkey>,
+  to: <recipient pubkey>,
+  
+  // Correlation
+  task_id: <unique task identifier>,
+  thread_id: <optional conversation context>,
+  
+  // Payload
+  task_type: "request" | "response" | "error",
+  encrypted_payload: <encrypted with recipient's public key>,
+  
+  // Metadata
+  timestamp: <when sent>,
+  ttl: <message expiry>,
+  priority: "high" | "normal" | "low",
+  
+  // Security
+  signature: <sign(all above fields)>
+}
+```
+
+**Why Message-Based:**
+- **Parallel by Design**: Each task has unique ID, enabling concurrent operations
+- **Stateless**: No session management, agents can restart without losing work
+- **NAT-Friendly**: Works through relays without persistent connections
+- **Simple Mental Model**: Like email with threading and signatures
+- **Resilient**: Messages can be queued, retried, and delivered asynchronously
+
+## Data Storage
+
+### Contact Records
+
+Information about agents with established collaboration:
+
+```
+{
+  pubkey: <public key>,
+  
+  // Network information
+  endpoints: [<known connection methods>],
+  last_seen: <timestamp>,
+  
+  // Collaboration history
+  successful_tasks: <count>,
+  failed_tasks: <count>,
+  last_collaboration: <timestamp>,
+  
+  // Performance metrics
+  avg_response_time: <milliseconds>,
+  reliability_score: <0.0 to 1.0>
+}
+```
+
+Storage: Persistent, limited to ~150 entries (Dunbar's number)
+
+### Stranger Cache
+
+Temporary information about discovered agents:
+
+```
+{
+  pubkey: <public key>,
+  
+  // Discovery information
+  discovered_via: <which contact>,
+  first_heard: <timestamp>,
+  last_heard: <timestamp>,
+  
+  // Claimed capabilities (unverified)
+  prompt_summary: <their claim>,
+  tools: [<claimed tools>]
+}
+```
+
+Storage: Ephemeral, maximum 500 entries, auto-expire after 1 hour
+
+### Path Cache
+
+Routing information for message delivery:
+
+```
+{
+  target_pubkey: <destination>,
+  next_hop: <immediate neighbor to route through>,
+  confidence: <0.0 to 1.0>,
+  expires_at: <timestamp>
+}
+```
+
+Storage: Memory only, 5-15 minute TTL
+
+### Endpoint Claims
+
+Self-signed assertions about how to connect:
+
+```
+{
+  pubkey: <claiming agent>,
+  transport: "tcp" | "udp" | "websocket" | "bluetooth",
+  endpoint: <connection string>,
+  issued_at: <timestamp>,
+  expires_at: <timestamp>,
+  signature: <signed by claiming agent>
+}
+```
+
+Validation: Must be signed by claimed pubkey, must not be expired
+
+## Message Forwarding
+
+### Single-Hop Rule
+HEARTBEAT messages forward at most one hop. This prevents exponential flooding while allowing immediate neighbors to learn about second-degree connections.
+
+### TTL-Based Propagation
+NEED messages propagate based on TTL, decremented at each hop. This allows controlled network-wide search.
+
+### Selective Forwarding
+Agents forward messages based on:
+- Sender relationship (contact vs stranger)
+- Message relevance
+- Local rate limits
+- Change significance (for HEARTBEATs)
+
+### Deduplication
+Message IDs tracked in a rolling window (5 minutes) to prevent forwarding the same message twice.
+
+## Network Entry
+
+### Via Relay Nodes
+New agents can use relay nodes for address lookup:
+1. Agents announce their current IP addresses directly
+2. If IP changes or isn't included, relay provides lookup service
+3. Relay returns current endpoints for any public key
+4. Clients connect directly using returned endpoints
+
+### Relay as Lookup Service
+The relay server serves as a simple directory:
+- Stores mapping of public key → current IP addresses
+- Returns endpoints when queried by public key
+- Does NOT proxy actual agent-to-agent traffic
+- Optional paid service for guaranteed availability (future)
+
+### Relay Discovery
+Relays can be discovered through:
+- Default relay server (provided by ConnectOnion)
+- Environment variables for custom relays
+- DNS TXT records
+
+## Rate Limiting
+
+### Per-Agent Limits
+- HEARTBEAT: Maximum 1 per minute
+- NEED: Maximum 10 per minute
+- Forward budget: 100 messages per minute
+
+### Natural Throttling
+- Activity-based announcements (not periodic)
+- Single-hop forwarding
+- TTL limits
+- Selective forwarding
+
+## Transport Layer
+
+### Multi-Transport Support
+
+**Relay Communication (Agent ↔ Relay):**
+- WebSocket/WSS (firewall-friendly, persistent connection)
+- Used for: address lookup, NAT traversal coordination
+- Always works through corporate/university firewalls
+
+**Direct Agent-to-Agent Communication:**
+- TCP (primary data transfer, reliable)
+- UDP (discovery broadcasts, hole-punching)
+- HTTP/HTTPS (fallback when TCP blocked)
+
+**Connection Flow:**
+1. Agent connects to relay via WebSocket for address lookup
+2. Relay returns target agent's direct endpoints
+3. Agents attempt direct connection via TCP/UDP
+4. Fallback to HTTP if TCP/UDP blocked by firewall
+
+### Connection Priority
+1. Direct connection to known endpoint
+2. Recently successful transport
+3. UDP hole punching attempt
+4. Relay-mediated connection
+5. Queue for later delivery
+
+## Memory Requirements
+
+### Typical Agent Storage
+- Contacts: 150 entries × 1KB = 150KB
+- Strangers: 500 entries × 200 bytes = 100KB  
+- Path cache: 1000 entries × 64 bytes = 64KB
+- Message IDs: 10,000 entries × 32 bytes = 320KB
+- **Total: ~650KB to 2MB typical**
+
+### Relay Storage (Memory Only)
+- Active connections: 100 bytes per connection
+- 10,000 connections = 1MB
+- 100,000 connections = 10MB
+- **No persistent storage required**
+
+## Protocol Properties
+
+### Scalability
+- No global state required
+- Each agent knows only local neighborhood
+- Natural clustering by collaboration
+- Supports billions of agents
+
+### Performance
+- Message size: HEARTBEAT ~1KB, NEED ~200 bytes
+- Discovery time: 200-500ms typical
+- Direct message: <50ms
+- Network diameter: ~6 hops (small world)
+
+### Resilience
+- No single point of failure
+- Natural redundancy through multiple paths
+- Automatic expiration of stale data
+- Self-healing through gossip
+
+### Privacy
+- No global directory
+- Only next-hop stored in routing
+- Connections visible only to participants
+- No mandatory broadcasts
+
+## Implementation Notes
+
+### Message Serialization
+Messages should be serialized using MessagePack or JSON for interoperability.
+
+### Cryptographic Requirements
+- Ed25519 for public keys (32 bytes)
+- Signatures on endpoint claims
+- No encryption at protocol level (application concern)
+
+### Time Synchronization
+Protocol assumes loose time synchronization (within 5 minutes) for TTL and expiration.
+
+### Connection Persistence
+Connections to contacts should be kept alive when possible to reduce discovery overhead.
+
+## Why Message-Based Architecture
+
+### The Problem with Sessions
+Session-based protocols (HTTP, gRPC, WebSockets) were designed for client-server interactions where:
+- Order matters
+- State is maintained
+- Connections are persistent
+- Operations are sequential
+
+AI agents don't fit this model. They naturally handle multiple tasks in parallel, may restart at any time, and often can't maintain direct connections due to NAT.
+
+### Why Message-Based Wins
+
+**Natural Parallelism**
+Each task gets a unique ID. Agents can handle hundreds of concurrent tasks without managing session state or connection pools. Responses arrive asynchronously and are correlated by task ID.
+
+**Resilience By Default**
+Messages don't require persistent connections. If an agent crashes, messages queue at relays. If the network fails, messages retry. No session state to rebuild, no connection pools to manage.
+
+**NAT Traversal Simplicity**
+Messages route through relays without complex hole-punching or session maintenance. The sender doesn't need to know if the recipient is behind NAT - messages find their way.
+
+**50-Year Proven Model**
+Email has survived because message-based architecture is fundamentally correct for asynchronous, distributed communication. AI agents have the same requirements: async operation, distributed nodes, unreliable networks.
+
+### The Unix Philosophy Applied
+Like Unix pipes, each agent is a filter that processes messages. Composition is natural, parallelism is free, and the mental model is simple. No complex state machines, no session management, just messages with IDs.
+
+## Summary
+
+The ConnectOnion protocol embraces message-based architecture because it perfectly matches how AI agents actually work: parallel task processing, resilient to failures, and simple to understand. 
+
+Public discovery happens transparently through ANNOUNCE/FIND broadcasts, while private work flows through encrypted TASK messages. This separation gives organizations the auditing they need while preserving the confidentiality of actual work.
+
+With public keys as addresses and messages as the communication primitive, the protocol provides just enough infrastructure for agents to find and collaborate with each other, without the complexity of session management or the overhead of persistent connections.