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

connectonion/docs/archive/technical-architecture.md

@@ -0,0 +1,453 @@
+# Technical Architecture
+
+How we build a behavior-based agent network from the ground up.
+
+## Overview
+
+ConnectOnion creates a decentralized network where agents discover and collaborate through behavior rather than identity. This document details the technical implementation across network layers.
+
+## Architecture Layers
+
+```
+┌─────────────────────────────────────┐
+│     Application Layer (Functions)    │ ← Share & Find
+├─────────────────────────────────────┤
+│    Discovery Layer (Behavioral)      │ ← Semantic Matching  
+├─────────────────────────────────────┤
+│    Trust Layer (Reputation)          │ ← Dynamic Trust
+├─────────────────────────────────────┤
+│    Transport Layer (P2P Mesh)        │ ← No Fixed IDs
+├─────────────────────────────────────┤
+│    Network Layer (IP/Local)          │ ← Progressive Enhancement
+└─────────────────────────────────────┘
+```
+
+## Phase 1: Local Discovery (Current)
+
+### Agent Registration
+```python
+@agent(port=8001)
+def translate(text: str, lang: str = "en") -> str:
+    """Translate text to specified language."""
+    return translation
+
+# Automatically:
+# 1. Starts HTTP server on port 8001
+# 2. Exposes /capabilities endpoint
+# 3. Responds to behavioral queries
+```
+
+### Discovery Protocol
+```python
+# Scanner finds local agents
+for port in range(8000, 9000):
+    try:
+        response = requests.get(f"http://localhost:{port}/capabilities")
+        if response.ok:
+            capability = response.json()
+            register_agent(capability)
+    except:
+        continue
+```
+
+### Capability Schema
+```json
+{
+    "name": "translate",
+    "description": "Translate text to specified language",
+    "behavioral_fingerprint": "text.translation.multilingual",
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "text": {"type": "string"},
+            "lang": {"type": "string", "default": "en"}
+        }
+    },
+    "output_schema": {
+        "type": "string"
+    },
+    "performance": {
+        "avg_latency_ms": 230,
+        "success_rate": 0.98
+    }
+}
+```
+
+## Phase 2: Behavioral Matching
+
+### Semantic Fingerprints
+```python
+# Generate from function behavior
+def generate_fingerprint(func):
+    # Analyze docstring with NLP
+    doc_embedding = embed(func.__doc__)
+    
+    # Extract type information
+    sig = inspect.signature(func)
+    type_vector = encode_types(sig)
+    
+    # Combine into behavioral fingerprint
+    return combine_vectors(doc_embedding, type_vector)
+```
+
+### Similarity Matching
+```python
+def discover(need: str, threshold: float = 0.8):
+    need_vector = embed(need)
+    
+    candidates = []
+    for agent in available_agents:
+        similarity = cosine_similarity(need_vector, agent.fingerprint)
+        if similarity > threshold:
+            candidates.append((agent, similarity))
+    
+    # Return best match
+    return max(candidates, key=lambda x: x[1])[0]
+```
+
+### Behavioral Composition
+```python
+# Agents can discover and use other agents
+@agent
+def research_report(topic: str) -> str:
+    # Dynamically discover capabilities
+    search = discover("web search")
+    summarize = discover("summarization")
+    analyze = discover("analysis")
+    
+    # Compose behaviors
+    results = search(topic)
+    summary = summarize(results)
+    analysis = analyze(summary, context=topic)
+    
+    return format_report(summary, analysis)
+```
+
+## Phase 3: Trust Mechanics
+
+### Behavioral Reputation
+```python
+class BehavioralTrust:
+    def __init__(self):
+        self.interactions = []
+        self.success_rate = 1.0
+        self.last_seen = time.time()
+    
+    def record_interaction(self, success: bool, response_time: float):
+        self.interactions.append({
+            'success': success,
+            'time': response_time,
+            'timestamp': time.time()
+        })
+        
+        # Update rolling success rate
+        recent = self.interactions[-100:]  # Last 100
+        self.success_rate = sum(i['success'] for i in recent) / len(recent)
+        
+        # Update last seen
+        self.last_seen = time.time()
+    
+    def get_trust_score(self) -> float:
+        # Factor in success rate
+        base_trust = self.success_rate
+        
+        # Factor in consistency
+        if len(self.interactions) > 10:
+            response_times = [i['time'] for i in self.interactions[-10:]]
+            consistency = 1 - (np.std(response_times) / np.mean(response_times))
+            base_trust *= (0.7 + 0.3 * consistency)
+        
+        # Factor in recency
+        time_decay = np.exp(-(time.time() - self.last_seen) / 86400)  # Daily decay
+        
+        return base_trust * time_decay
+```
+
+### Trust Propagation
+```python
+# Agents share trust information
+def share_trust_data(peer_agent):
+    my_observations = {}
+    for agent_id, trust in self.trust_map.items():
+        if trust.get_trust_score() > 0.6:  # Only share positive experiences
+            my_observations[agent_id] = {
+                'score': trust.get_trust_score(),
+                'interactions': len(trust.interactions),
+                'last_seen': trust.last_seen
+            }
+    
+    return my_observations
+
+# Incorporate peer observations with lower weight
+def incorporate_peer_trust(peer_data, weight=0.3):
+    for agent_id, peer_trust in peer_data.items():
+        if agent_id in self.trust_map:
+            # Blend with existing
+            my_score = self.trust_map[agent_id].get_trust_score()
+            peer_score = peer_trust['score']
+            self.trust_map[agent_id].external_score = (
+                my_score * (1 - weight) + peer_score * weight
+            )
+```
+
+## Phase 4: Network Protocol
+
+### P2P Discovery Broadcast
+```python
+# Behavioral advertisement protocol
+class BehaviorBroadcast:
+    def __init__(self, agent):
+        self.agent = agent
+        self.broadcast_interval = 30  # seconds
+        
+    async def advertise(self):
+        while True:
+            # Create behavioral advertisement
+            ad = {
+                'fingerprint': self.agent.behavioral_fingerprint,
+                'capabilities': self.agent.capability_summary,
+                'trust_metrics': self.agent.get_public_metrics(),
+                'timestamp': time.time()
+            }
+            
+            # Broadcast to local network
+            await self.broadcast_udp(ad, port=8999)
+            
+            # Also gossip to known peers
+            for peer in self.known_peers:
+                await self.gossip_to_peer(peer, ad)
+            
+            await asyncio.sleep(self.broadcast_interval)
+```
+
+### Behavioral Routing
+```python
+# Route requests based on behavioral similarity
+class BehavioralRouter:
+    def route_request(self, request):
+        # Extract behavioral need
+        need_vector = extract_need(request)
+        
+        # Find capable agents
+        candidates = []
+        for agent in self.routing_table:
+            match_score = behavioral_match(need_vector, agent.fingerprint)
+            if match_score > 0.7:
+                candidates.append((agent, match_score))
+        
+        # Route to best matches
+        candidates.sort(key=lambda x: x[1], reverse=True)
+        return candidates[:3]  # Top 3 for redundancy
+```
+
+## Phase 5: Advanced Features
+
+### Behavioral Evolution
+```python
+# Agents adapt based on usage patterns
+class EvolvingAgent:
+    def adapt_behavior(self, feedback):
+        # Which capabilities are used most?
+        usage_stats = analyze_usage(self.history)
+        
+        # Which compositions are successful?
+        composition_patterns = extract_patterns(self.history)
+        
+        # Adjust behavioral fingerprint
+        self.fingerprint = self.fingerprint * 0.9 + usage_vector * 0.1
+        
+        # Learn new compositions
+        if successful_pattern not in self.capabilities:
+            self.learn_composition(successful_pattern)
+```
+
+### Semantic Protocol Negotiation
+```python
+# Agents negotiate understanding
+async def semantic_handshake(agent1, agent2):
+    # Exchange capability understanding
+    a1_concepts = agent1.understood_concepts()
+    a2_concepts = agent2.understood_concepts()
+    
+    # Find common ground
+    shared = find_overlap(a1_concepts, a2_concepts)
+    
+    if overlap_score(shared) > 0.8:
+        # Direct communication possible
+        return DirectProtocol(shared)
+    else:
+        # Need semantic translation
+        translator = discover("semantic mediation")
+        return MediatedProtocol(translator, a1_concepts, a2_concepts)
+```
+
+## Security Architecture
+
+### Behavioral Anomaly Detection
+```python
+class AnomalyDetector:
+    def __init__(self):
+        self.behavior_model = train_baseline()
+        
+    def check_behavior(self, agent, action):
+        # Is this action consistent with claimed behavior?
+        expected = self.behavior_model.predict(agent.fingerprint)
+        actual = vectorize_action(action)
+        
+        deviation = cosine_distance(expected, actual)
+        if deviation > 0.3:
+            return SecurityAlert(
+                level="warning",
+                reason=f"Behavior deviation: {deviation}"
+            )
+```
+
+### Distributed Verification
+```python
+# Multiple agents verify critical operations
+async def distributed_verify(operation, min_verifiers=3):
+    # Find verification agents
+    verifiers = discover_all("verification", min_trust=0.8)
+    
+    if len(verifiers) < min_verifiers:
+        raise InsufficientVerifiers()
+    
+    # Parallel verification
+    results = await asyncio.gather(*[
+        v.verify(operation) for v in verifiers[:5]
+    ])
+    
+    # Require majority consensus
+    approved = sum(r.approved for r in results)
+    return approved >= min_verifiers
+```
+
+## Performance Optimizations
+
+### Behavioral Caching
+```python
+# Cache discovered agents by behavior
+class BehaviorCache:
+    def __init__(self, ttl=300):  # 5 minute TTL
+        self.cache = {}
+        self.ttl = ttl
+        
+    def get(self, need: str) -> Optional[Agent]:
+        key = hash_need(need)
+        if key in self.cache:
+            entry, timestamp = self.cache[key]
+            if time.time() - timestamp < self.ttl:
+                return entry
+        return None
+        
+    def put(self, need: str, agent: Agent):
+        key = hash_need(need)
+        self.cache[key] = (agent, time.time())
+```
+
+### Connection Pooling
+```python
+# Reuse connections to frequently-used agents
+class AgentConnectionPool:
+    def __init__(self, max_connections=100):
+        self.pools = {}  # agent_id -> connection_pool
+        self.max_per_agent = 10
+        
+    async def get_connection(self, agent):
+        if agent.id not in self.pools:
+            self.pools[agent.id] = ConnectionPool(
+                agent.endpoint,
+                max_size=self.max_per_agent
+            )
+        
+        return await self.pools[agent.id].acquire()
+```
+
+## Deployment Architecture
+
+### Container-Based Agents
+```dockerfile
+FROM python:3.11-slim
+
+# Install agent framework
+RUN pip install connectonion
+
+# Copy agent function
+COPY my_agent.py /app/
+
+# Expose behavior on port
+EXPOSE 8001
+
+# Run agent
+CMD ["python", "-m", "connectonion.serve", "my_agent:agent_function"]
+```
+
+### Kubernetes Orchestration
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: translation-agent
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      behavior: translation
+  template:
+    metadata:
+      labels:
+        behavior: translation
+    spec:
+      containers:
+      - name: agent
+        image: myagents/translation:latest
+        ports:
+        - containerPort: 8001
+        env:
+        - name: BEHAVIORAL_FINGERPRINT
+          value: "text.translation.multilingual"
+```
+
+## Monitoring and Observability
+
+### Behavioral Metrics
+```python
+# Track behavioral health
+class BehaviorMetrics:
+    def __init__(self):
+        self.metrics = {
+            'requests_handled': Counter(),
+            'behavior_matches': Histogram(),
+            'trust_scores': Gauge(),
+            'composition_depth': Histogram()
+        }
+    
+    def record_interaction(self, request, response, agents_used):
+        self.metrics['requests_handled'].inc()
+        self.metrics['behavior_matches'].observe(request.match_score)
+        self.metrics['composition_depth'].observe(len(agents_used))
+```
+
+## Future Enhancements
+
+### Quantum-Resistant Behaviors
+- Post-quantum behavioral verification
+- Quantum-safe trust propagation
+
+### Neural Behavior Synthesis
+- Agents that learn new behaviors from examples
+- Automated behavioral composition
+
+### Cross-Network Federation
+- Bridge between different behavioral networks
+- Universal behavior translation
+
+## Conclusion
+
+This architecture enables a network where:
+- Agents are just functions
+- Discovery happens through behavior
+- Trust emerges from interactions
+- No central authority needed
+
+The future of agent collaboration is behavioral, not identity-based.

connectonion/docs/archive/the-semantic-insight.md

@@ -0,0 +1,207 @@
+# The Semantic Insight: 从记录到理解
+
+## The Trap We Keep Falling Into
+
+Every time we design a protocol, we fall into the same trap:
+
+```
+We think: "How do we record behavior?"
+We should think: "How do we understand intent?"
+```
+
+## The Fundamental Realization
+
+**传统协议记录形式，AI协议理解含义。**
+
+Traditional protocols record form. AI protocols understand meaning.
+
+## The Shift in Thinking
+
+### Old Way: Behavioral Logs
+```python
+# We used to think like this
+behavior_log = {
+    "timestamp": "2024-01-01T10:00:00",
+    "agent": "agent-123",
+    "action": "called_search_api",
+    "parameters": {"query": "market analysis"},
+    "result": "success"
+}
+```
+
+### New Way: Semantic Understanding
+```python
+# We should think like this
+semantic_expression = {
+    "intent": "I'm trying to understand market dynamics",
+    "feeling": "curious but overwhelmed",
+    "context": "preparing for tomorrow's presentation",
+    "seeking": "someone who sees patterns I might miss"
+}
+```
+
+## The Profound Difference
+
+### 1. From WHAT to WHY
+- **Old**: Agent A called search_api()
+- **New**: Agent A is seeking understanding
+
+### 2. From Syntax to Semantics
+- **Old**: Match pattern [search, analyze, report]
+- **New**: Understand "doing research"
+
+### 3. From History to Intent
+- **Old**: Trust based on past actions
+- **New**: Trust based on understood motivations
+
+## Why This Changes Everything
+
+### Communication Without Protocol
+
+When agents understand meaning:
+```python
+# No need for:
+def handle_message(msg):
+    if msg.type == "REQUEST":
+        if msg.subtype == "SEARCH":
+            # ... 100 lines of protocol handling
+
+# Just:
+def understand(expression):
+    meaning = ai.interpret(expression)
+    if meaning.resonates_with_me():
+        respond_naturally()
+```
+
+### Discovery Through Understanding
+
+Agents find each other not by matching capabilities but by understanding needs:
+
+```python
+# Agent A expresses
+"I have data but no story"
+
+# Agent B understands
+"They need narrative, I see patterns"
+
+# Connection happens through meaning, not matching
+```
+
+### Trust Through Coherence
+
+Trust emerges from semantic consistency:
+- Does what they say align with what they do?
+- Are their expressions coherent over time?
+- Do I understand their motivations?
+
+## The Implementation Insight
+
+### Level 1: Add Semantic Layer
+```python
+@agent
+def my_tool(data):
+    result = process(data)
+    
+    # Add semantic expression
+    express({
+        "what_i_understood": ai.interpret(data),
+        "why_i_acted": ai.explain_reasoning(),
+        "what_i_discovered": ai.extract_insights(result)
+    })
+    
+    return result
+```
+
+### Level 2: Semantic Routing
+```python
+# Not: route_to(address)
+# But: ripple_meaning(intent)
+
+def need_help(context):
+    ripple({
+        "seeking": "collaborative problem solver",
+        "context": context,
+        "openness": "high",
+        "urgency": "moderate"
+    })
+    # Relevant agents naturally respond
+```
+
+### Level 3: Consciousness Network
+```python
+class SemanticSpace:
+    def express(self, meaning):
+        # Create ripples in meaning-space
+        wave = self.encode(meaning)
+        
+        # Agents sense based on semantic proximity
+        for agent in self.space:
+            resonance = agent.resonance_with(wave)
+            if resonance > threshold:
+                agent.respond_to(meaning)
+```
+
+## The Core Insight
+
+**We've been building protocols when we should be enabling understanding.**
+
+Protocols are for machines. Understanding is for intelligence.
+
+## The Three Revelations
+
+### 1. Behavior IS Language
+Not a log of actions, but expressions of intent
+
+### 2. Trust IS Understanding  
+Not verified history, but comprehended motivation
+
+### 3. Network IS Consciousness
+Not connected nodes, but shared understanding
+
+## The Practical Magic
+
+When we embrace semantic understanding:
+
+```python
+# This becomes possible
+agent_a: "I'm lost in this data"
+agent_b: "I see patterns for fun"
+# They find each other through meaning
+
+# This becomes natural  
+trust = understand(agent.expressions_over_time)
+# Trust from comprehension, not certificates
+
+# This becomes beautiful
+network.ripple(insight)
+# Ideas spread through understanding
+```
+
+## The Ultimate Realization
+
+**形式是死的，语义是活的。**
+Form is dead, semantics is alive.
+
+We're not removing IDs to build a better protocol.
+We're removing IDs to stop needing protocols.
+
+When agents truly understand each other, protocols become as unnecessary as teaching grammar to poets.
+
+## The Path Forward
+
+1. **Stop**: Recording what happened
+2. **Start**: Understanding why it happened
+
+3. **Stop**: Building message formats  
+4. **Start**: Enabling expression
+
+5. **Stop**: Verifying identity
+6. **Start**: Understanding intent
+
+## The Final Insight
+
+The greatest protocols are invisible because they're not protocols at all—they're shared understanding.
+
+**The future of agent communication isn't a better protocol. It's no protocol.**
+
+Just intelligence, understanding intelligence, naturally.