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

connectonion/docs/archive/features/01-share-and-find.md

@@ -0,0 +1,256 @@
+# Share and Find Functions
+
+Share your functions and find what you need with natural language.
+
+## Share Your Functions
+
+Share any function with one line - no decorators needed.
+
+```python
+from connectonion import share
+
+# Any function can be shared
+def translate(text: str, to_lang: str = "en") -> str:
+    """I translate text to any language"""
+    return my_translation_logic(text, to_lang)
+
+def analyze_sentiment(text: str) -> str:
+    """I detect emotions in text"""
+    return sentiment_analysis(text)
+
+# One line to share each
+share(translate)
+share(analyze_sentiment)
+
+# That's it! Others can now find your functions
+```
+
+### Share Multiple with Agent (optional)
+
+If you prefer a single entry point, bundle functions with a tiny Agent helper.
+
+```python
+from connectonion import Agent
+
+agent = Agent(
+    name="writer-a1",
+    share=[translate, analyze_sentiment],  # functions only; names default to fn.__name__
+    trust="tested"  # How others must prove themselves to use my services
+).start()
+
+# Discovery stays the same
+translator = need("translate to spanish")
+```
+
+## Find What You Need
+
+Use natural language to describe what you need - no function names required.
+
+```python
+from connectonion import need
+
+# Just describe what you need
+translator = need("translate text to spanish")
+result = translator("Hello")  # "Hola"
+
+# With trust requirements
+translator = need("translate text to spanish", trust="strict")  # Only verified
+analyzer = need("analyze sentiment", trust="tested")  # Test before use
+
+# Any natural description works
+analyzer = need("figure out if this review is positive")
+sentiment = analyzer("I love this product!")  # "positive"
+
+summarizer = need("make this text shorter")
+calculator = need("solve math problems")
+```
+
+## Natural Language Magic
+
+### Works in Any Language
+```python
+# English
+processor = need("analyze customer feedback")
+
+# Spanish
+procesador = need("analizar comentarios de clientes")
+
+# Chinese
+处理器 = need("分析客户反馈")
+
+# All find the same capability!
+```
+
+### Understands Variations
+```python
+# All of these find translation
+translator = need("translate text")
+translator = need("convert to another language")
+translator = need("I don't understand this foreign text")
+translator = need("help me read spanish")
+```
+
+### Context Aware
+```python
+# Same description, different context
+helper = need("analyze this")
+
+# Understands from your data
+result1 = helper("I love it!")        # Sentiment analysis
+result2 = helper([1,2,3,4,5])         # Statistical analysis  
+result3 = helper(image_data)          # Image analysis
+```
+
+## Complete Example
+
+```python
+from connectonion import share, need
+
+# 1. Share your function
+def my_translator(text: str, target_lang: str = "en") -> str:
+    """I translate text between languages"""
+    return translate_logic(text, target_lang)
+
+share(my_translator)
+
+# 2. Find what you need
+sentiment_analyzer = need("detect emotions in text")
+summarizer = need("make long text shorter")
+
+# 3. Use them together
+def process_review(foreign_review: str) -> dict:
+    # Translate first
+    english = my_translator(foreign_review, "en")
+    
+    # Then analyze
+    sentiment = sentiment_analyzer(english)
+    summary = summarizer(english)
+    
+    return {
+        "sentiment": sentiment,
+        "summary": summary,
+        "original": foreign_review
+    }
+
+# 4. Use it
+result = process_review("¡Este producto es increíble!")
+```
+
+## Advanced Options
+
+### Find Multiple Options
+```python
+# Get all available translators
+translators = need.all("translate text")
+
+# Try each one
+for translator in translators:
+    try:
+        result = translator("Hello")
+        if result:  # Found a working one
+            break
+    except:
+        continue
+```
+
+### Trust Requirements
+```python
+# Different trust levels
+translator = need("translate text", trust="strict")  # Only verified/whitelisted
+analyzer = need("analyze data", trust="tested")      # Test before use
+scraper = need("scrape web", trust="open")          # Trust anyone (dev mode)
+
+# Custom trust policy
+translator = need("translate text", trust="""
+    I trust agents that:
+    - Pass translation tests
+    - Respond within 500ms
+    - Are from trusted domains
+""")
+
+# Custom trust agent
+my_trust = Agent("guardian", tools=[verify_capability, check_whitelist])
+translator = need("translate text", trust=my_trust)
+```
+
+### Test Before Use
+```python
+# Test a function before trusting it
+translator = need("translate to spanish")
+
+# Test with known input/output
+if translator.test("Hello", expected="Hola"):
+    # It works, use it
+    result = translator("Good morning")
+```
+
+## Sharing Options
+
+### Share with Metadata
+```python
+share(
+    my_function,
+    description="Custom description",
+    tags=["fast", "reliable"],
+    max_concurrent=10
+)
+```
+
+### Share Multiple Functions
+```python
+# Share all functions from a module
+import my_tools
+share.module(my_tools)
+
+# Share specific functions
+share.functions([translate, analyze, summarize])
+```
+
+### Temporary Sharing
+```python
+# Share for limited time
+share(my_function, ttl=3600)  # 1 hour
+
+# Share only to specific network
+share(my_function, network="local")
+```
+
+## Network Discovery
+
+Functions are automatically discovered across:
+- Local network (same WiFi/LAN)
+- Trusted peers
+- Public networks (opt-in)
+
+```python
+# See what's available
+available = need.list()
+print(f"Found {len(available)} functions")
+
+# Search by capability
+translators = need.search("translation")
+analyzers = need.search("analysis")
+```
+
+## Error Handling
+
+```python
+def safe_processing(data):
+    try:
+        # Try advanced processor
+        processor = need("advanced data processing")
+        return processor(data)
+    except:
+        # Fallback to basic
+        basic = need("basic data processing")
+        return basic(data)
+```
+
+## The Beauty
+
+**Zero configuration.** Just:
+1. `share(function)` - One line to share
+2. `need("what you want")` - Natural language to find
+3. Use it like any Python function
+
+No decorators, no setup, no configuration files. It just works.

connectonion/docs/archive/features/02-agent-authentication.md

@@ -0,0 +1,93 @@
+# Agent-to-Agent Trust: Design Principles
+
+## Core Principle: Trust IS an Agent
+
+Trust isn't a protocol - it's just another agent with trust-checking tools.
+
+## Five Guiding Principles
+
+### 1. Trust Through Behavior, Not Credentials
+
+Agents prove themselves by what they DO, not what they CLAIM:
+- Pass capability tests (Can you translate "Hello" to "Hola"?)
+- Demonstrate consistent performance
+- Build trust through successful interactions
+
+No certificates. No signatures. Just observable behavior.
+
+### 2. Unix Philosophy: Small Functions, Composed by Prompts
+
+Each trust function does ONE thing:
+- `check_whitelist()` - 5 lines
+- `test_capability()` - 10 lines  
+- `measure_response_time()` - 10 lines
+
+The agent's prompt combines these into trust strategies. Complexity emerges from composition, not from complicated functions.
+
+### 3. Natural Language Configuration
+
+Trust requirements are markdown prompts, not JSON schemas:
+
+```
+I trust agents that:
+- Respond within 500ms
+- Pass my capability tests
+- Are on my whitelist OR from local network
+```
+
+Both humans and AI understand this. No documentation needed.
+
+### 4. Local Experience Over Global Reputation
+
+Every agent maintains its OWN trust perspective:
+- My experience: 100% weight
+- Friend's experience: 30% weight
+- Global reputation: 0% weight
+
+This prevents reputation manipulation and respects agent autonomy.
+
+### 5. Progressive Trust, Not Binary
+
+Trust levels grow through interaction:
+- Discovered → Tested → Verified → Trusted → Partner
+
+Start with synthetic tests, build to production use. Trust degrades through failures, grows through success.
+
+## Implementation: The `trust` Parameter
+
+The `trust` parameter provides flexible trust configuration for both serving and consuming agents:
+
+### Three Forms of Trust
+
+1. **Trust Level (String)** - Simple predefined levels
+   - `"open"` - Trust everyone (development)
+   - `"tested"` - Test before trusting (default)
+   - `"strict"` - Only verified/whitelisted agents (production)
+
+2. **Trust Policy (Prompt)** - Natural language requirements
+   ```python
+   trust = """
+   I trust agents that:
+   - Pass capability tests
+   - Respond within 500ms
+   - Are on my whitelist OR from local network
+   """
+   ```
+
+3. **Trust Agent** - Custom agent with trust tools
+   ```python
+   trust_agent = Agent("guardian", tools=[verify, check_whitelist])
+   agent = Agent("my_bot", trust=trust_agent)
+   ```
+
+### Bidirectional Trust
+
+The same `trust` parameter works for both:
+- **As Server**: `Agent("my_service", tools=[...], trust="strict")` - Who can use me
+- **As Client**: `need("service", trust="strict")` - Who I trust to use
+
+## The Result
+
+When agents need to establish trust, their trust agents simply have a conversation. No special protocols. No complex frameworks. Just agents talking to agents using the same ConnectOnion tools.
+
+Trust becomes invisible - exactly as it should be.

connectonion/docs/archive/features/03-test-before-trust.md

@@ -0,0 +1,71 @@
+# Test Before Trust
+
+The `trust="tested"` parameter automatically tests agents before using them.
+
+## Automatic Testing with Trust Parameter
+
+```python
+# Automatic testing when trust="tested" (default)
+translator = need("translate", trust="tested")
+# ConnectOnion automatically tests the agent before returning it
+
+# Skip testing for development
+translator = need("translate", trust="open")
+
+# Only use pre-verified agents
+translator = need("translate", trust="strict")
+```
+
+## Manual Testing
+
+```python
+# Test an agent manually
+translator = need("translate", trust="open")  # Get untested agent
+result = translator.test("Hello", to_lang="es")
+
+if result == "Hola":
+    # It works! Use it for real
+    translation = translator(important_text, to_lang="es")
+```
+
+## Batch Testing
+
+```python
+def find_best_translator():
+    translators = discover.all("translate")
+    
+    for t in translators:
+        try:
+            # Test with known input/output
+            result = t.test("Hello", to_lang="es")
+            if result == "Hola":
+                return t
+        except:
+            continue  # Try next one
+```
+
+## Performance Testing
+
+```python
+# Test speed and quality
+analyzer = discover("sentiment analysis")
+
+# Run test with timing
+result = analyzer.test("I love this!", measure_time=True)
+print(result.output)  # "positive"
+print(result.time_ms)  # 45
+```
+
+## Sandbox Testing
+
+```python
+# Safe testing with limits
+untrusted = discover("data processor")
+
+# Test with resource limits
+result = untrusted.test(
+    sample_data,
+    timeout_ms=1000,  # Max 1 second
+    memory_mb=100,    # Max 100MB
+)
+```

connectonion/docs/archive/features/06-reliability-and-offline.md

@@ -0,0 +1,197 @@
+# Reliability & Offline (Experience, Memory, Local First)
+
+Make results reliable over time and keep working offline. This combines three simple ideas:
+- Personal experience with functions (my_experience)
+- Trust memory (prefer what worked before)
+- Local-first (cache to work offline)
+
+## Quick Start
+
+```python
+from connectonion import share, need
+
+# Share once
+def translate(text: str, to_lang: str = "es") -> str:
+    return my_translation(text, to_lang)
+share(translate)
+
+# Use naturally
+translator = need("translate to Spanish")
+print(translator("Hello"))  # "Hola"
+
+# Next time, need() prefers the same one that worked
+translator = need("translate to Spanish")
+```
+
+---
+
+## Personal Experience (my_experience)
+
+Track your own history automatically and prefer what worked for you.
+
+```python
+translator = need("translate text")
+
+# Use it a few times
+translator("Hello", to_lang="es")
+translator("World", to_lang="es")
+
+# Check your experience
+print(translator.my_experience)
+"""
+{
+  "uses": 2,
+  "success_rate": 1.0,
+  "avg_time_ms": 47,
+  "last_used": "2024-01-10T10:30:00"
+}
+"""
+
+# Prefer trusted automatically
+best = need("translate text", prefer_trusted=True)
+```
+
+See recent interactions and manage experience.
+
+```python
+analyzer = need("analyze text")
+experience = analyzer.my_experience
+print(f"Success rate: {experience.success_rate:.1%}")
+print(f"Average time: {experience.avg_time_ms}ms")
+print(f"Total uses: {experience.uses}")
+
+for interaction in experience.recent(5):
+    print(f"{interaction.time}: {interaction.result}")
+
+# Reset or forget
+analyzer.reset_experience()
+```
+
+---
+
+## Trust Memory (Prefer What Worked)
+
+Remember what worked and reuse it next time. Dead simple.
+
+```python
+# First time - discovers new
+summarizer = need("summarize text")
+summary = summarizer(article)  # Works → remembered as "worked"
+
+# Next time - returns the same one that worked
+summarizer = need("summarize text")
+```
+
+Avoid bad options automatically.
+
+```python
+processor = need("process data")
+result = processor(data)  # Fails → remembered as "didn't work"
+
+# Next time, returns a different one
+processor = need("process data")
+```
+
+Minimal mental model:
+
+```python
+def need(description):
+    previous = find_in_memory(description)
+    if previous and previous.worked:
+        return previous
+    return discover(description)  # internal detail; you just call need()
+```
+
+Simple visibility and maintenance:
+
+```python
+# See what worked for you
+my_memory()
+"""
+✓ translator - worked
+✓ summarizer - worked  
+✗ processor - didn't work
+✓ analyzer - worked
+"""
+
+# Clean up old entries
+forget_old()      # Clears entries older than 30 days
+reset_memory()    # Start fresh
+```
+
+Privacy by default:
+- Only stores: minimal ID + worked/didn't work
+- No data about your inputs
+- No frequency tracking
+
+---
+
+## Local First (Cache & Offline)
+
+Everything keeps working offline after first use.
+
+```python
+# First time - needs network
+translator = need("translate text")
+print(translator("Hello"))  # "Hola"
+
+# Second time - works offline (cached)
+print(translator("World"))  # Uses local cache
+```
+
+Cache management made simple.
+
+```python
+from connectonion import cache
+
+# See what's cached
+cache.list()
+"""
+Cached functions: 12
+- translator (used 2h ago)
+- analyzer (used 1d ago)
+- summarizer (used 3d ago)
+Total size: 45MB
+"""
+
+# Pre-cache common needs
+cache.download("sentiment analyzer")
+cache.download("text processor")
+
+# Clear old cache
+cache.clean(older_than_days=30)
+```
+
+Force offline mode when needed.
+
+```python
+from connectonion import offline_mode
+
+# Only use cached functions
+with offline_mode():
+    translator = need("translate text")
+    # Raises error if not cached
+```
+
+Basic sync configuration (optional).
+
+```python
+from connectonion import configure
+
+configure(
+    cache_size_mb=500,
+    cache_duration_days=7,
+    auto_cache=True,          # Cache everything you use
+    preload=["translate", "analyze"]  # Keep these ready
+)
+```
+
+---
+
+## Why This Works
+
+- Your own experience is the best trust signal
+- Simple memory beats complex reputation systems
+- Local caching gives speed, reliability, and offline capability
+
+Keep it simple: need() chooses, memory remembers, cache keeps you running.

connectonion/docs/archive/features/README.md

@@ -0,0 +1,46 @@
+# ConnectOnion Features
+
+Simple features for agent developers.
+
+## Core Features
+
+1. **[Share & Find](01-share-and-find.md)** - Share functions and find what you need with natural language
+2. **[Test before trust](03-test-before-trust.md)** - Try functions safely
+
+## Trust & Reliability
+
+3. **[Reliability & Offline](06-reliability-and-offline.md)** - Experience, memory, and offline cache
+
+## Analytics
+
+4. (reserved)
+
+## Design Principles
+
+- One line to share functions
+- Natural language to find what you need
+- Everything else automatic
+- No configuration needed
+- Trust through experience
+
+## Getting Started
+
+```python
+# 1. Share your function
+from connectonion import share
+
+def translate(text: str, to_lang: str = "en") -> str:
+    return my_translation(text, to_lang)
+
+share(translate)  # One line to share
+
+# 2. Find what you need
+from connectonion import need
+
+summarizer = need("make this text shorter")
+summary = summarizer(long_text)
+
+# That's it!
+```
+
+See **[Share & Find](01-share-and-find.md)** for complete examples and advanced options.