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

connectonion/docs/design-decisions/022-raw-asgi-implementation.md

@@ -0,0 +1,273 @@
+# HTTP Layer: Why Raw ASGI Instead of Starlette/FastAPI
+
+*December 2025*
+
+When implementing `host()`, we needed to choose how to handle HTTP and WebSocket requests. This document explains why we chose raw ASGI over established frameworks like Starlette or FastAPI.
+
+---
+
+## The Problem
+
+The `host()` function needs to expose an agent over HTTP/WebSocket:
+
+```
+Client                                    Agent
+   │                                        │
+   │── POST /input ────────────────────────▶│
+   │── GET /tasks/{id} ────────────────────▶│
+   │── GET /health ────────────────────────▶│
+   │── WS /ws ─────────────────────────────▶│
+   │                                        │
+```
+
+Requirements:
+1. **Simple for users** - Just `host(agent)`, no config
+2. **Flexible for future** - Streaming, custom protocols, P2P
+3. **Minimal dependencies** - Only uvicorn needed
+4. **Transparent** - Easy to understand what happens
+
+---
+
+## Part I: What Others Do
+
+### Option A: Build on Starlette
+
+Most Python frameworks build on Starlette (FastAPI's foundation):
+
+```python
+from starlette.applications import Starlette
+from starlette.routing import Route
+from starlette.responses import JSONResponse
+
+async def post_input(request):
+    data = await request.json()
+    result = agent.input(data["prompt"])
+    return JSONResponse(result)
+
+app = Starlette(routes=[
+    Route("/input", post_input, methods=["POST"]),
+    Route("/tasks/{task_id}", get_task),
+    # ...
+])
+```
+
+**Pros:**
+- Clean routing syntax
+- Request/Response objects
+- Built-in test client (httpx)
+- Middleware support (CORS, GZip)
+- Industry standard
+
+**Cons:**
+- Additional dependency
+- Framework lock-in
+- Less control over protocol details
+
+### Option B: Own Implementation (Sanic, BlackSheep)
+
+Some frameworks implement their own HTTP layer:
+
+| Framework | Approach | Why |
+|-----------|----------|-----|
+| **Sanic** | Own server + ASGI | Predates Starlette (2016), needed control |
+| **BlackSheep** | Cython-optimized ASGI | Performance, ASP.NET-style patterns |
+| **Litestar** | Custom (Starlette-inspired) | Different design philosophy |
+
+### Option C: Rust Runtime (Robyn)
+
+Robyn bypasses Python ASGI entirely - HTTP is handled in Rust:
+
+```python
+# Robyn: Python handlers, Rust HTTP server
+@app.post("/input")
+async def input(request):
+    return agent.input(request.json()["prompt"])
+```
+
+**Pros:** Maximum performance (15-20% faster)
+**Cons:** Not standard ASGI, different deployment model
+
+---
+
+## Part II: Our Analysis
+
+### Performance Reality
+
+From TechEmpower benchmarks:
+```
+Performance ranking:
+1. Uvicorn (raw server)
+2. Starlette (~same as uvicorn)
+3. FastAPI (Starlette + Pydantic)
+4. ...everything else
+```
+
+**Key insight:** Starlette adds essentially zero overhead.
+
+### What Raw ASGI Gives Us
+
+```python
+async def app(scope, receive, send):
+    # scope = method, path, headers, query_string
+    # receive = get body chunks
+    # send = send response chunks
+```
+
+Full control for:
+- **Streaming responses** - Send chunks as agent thinks
+- **Protocol hijacking** - Custom binary protocols
+- **Server-Sent Events** - Real-time without WebSocket
+- **P2P relay** - Custom agent-to-agent protocol
+- **Early response** - Send headers before body ready
+
+### What Starlette Would Save
+
+Our raw ASGI code (~70 lines):
+```python
+async def handle_http(scope, receive, send, ...):
+    method, path = scope["method"], scope["path"]
+    if method == "POST" and path == "/input":
+        body = await read_body(receive)
+        data = json.loads(body)
+        # ...
+        await send_json(send, result)
+```
+
+With Starlette (~30 lines):
+```python
+async def post_input(request):
+    data = await request.json()
+    # ...
+    return JSONResponse(result)
+```
+
+**Savings:** ~40 lines, cleaner syntax.
+
+---
+
+## Part III: Decision
+
+**Use Raw ASGI**
+
+### Reasons
+
+1. **Full Control for Agent Protocols**
+   - Future: streaming agent responses as they generate
+   - Future: P2P relay connections
+   - Future: agent-to-agent communication
+   - Future: Server-Sent Events
+
+2. **Zero Dependencies**
+   - Only uvicorn (already needed)
+   - Simpler dependency tree
+   - No version conflicts
+
+3. **Precedent**
+   - Sanic chose own implementation
+   - BlackSheep chose own implementation
+   - Both prioritized control over convenience
+
+4. **Transparency**
+   - Code shows exactly what happens
+   - Educational value for agent framework
+   - Easy to debug
+
+5. **Performance Equivalent**
+   - Starlette adds ~zero overhead
+   - No benefit to switching
+
+### Trade-offs Accepted
+
+We give up:
+- Clean `Route("/path", handler)` syntax
+- Built-in test client
+- ~~Middleware helpers (CORS, GZip)~~ (we implemented CORS manually)
+- ~40 lines of code
+
+We gain:
+- Full protocol control
+- No framework lock-in
+- Ability to implement custom protocols
+- Clear understanding of what happens
+
+### CORS Implementation (Added Dec 2025)
+
+We implemented CORS manually in `asgi.py` with ~15 lines:
+
+```python
+CORS_HEADERS = [
+    [b"access-control-allow-origin", b"*"],
+    [b"access-control-allow-methods", b"GET, POST, OPTIONS"],
+    [b"access-control-allow-headers", b"authorization, content-type"],
+]
+
+# Handle OPTIONS preflight
+if method == "OPTIONS":
+    headers = CORS_HEADERS + [[b"content-length", b"0"]]
+    await send({"type": "http.response.start", "status": 204, "headers": headers})
+    await send({"type": "http.response.body", "body": b""})
+    return
+```
+
+This enables cross-origin requests from frontend (o.openonion.ai) to deployed agents (*.agents.openonion.ai).
+
+---
+
+## Part IV: Current Implementation
+
+```
+host.py (~360 lines)
+├── Types           # Task dataclass
+├── Storage         # JSONL persistence
+├── Handlers        # Pure functions (input, task, tasks, health, info)
+├── ASGI App        # create_app, handle_http, handle_websocket
+├── Entry Point     # host()
+└── Helpers         # read_body, send_json, extract_and_authenticate
+```
+
+Key functions:
+
+```python
+async def read_body(receive) -> bytes:
+    """Read complete request body."""
+    body = b""
+    while True:
+        m = await receive()
+        body += m.get("body", b"")
+        if not m.get("more_body"):
+            break
+    return body
+
+async def send_json(send, data: dict, status: int = 200):
+    """Send JSON response."""
+    body = json.dumps(data).encode()
+    await send({"type": "http.response.start", "status": status,
+               "headers": [[b"content-type", b"application/json"]]})
+    await send({"type": "http.response.body", "body": body})
+```
+
+---
+
+## Part V: When We Might Reconsider
+
+| Need | Consider |
+|------|----------|
+| Auto OpenAPI docs | Litestar |
+| Complex middleware | Starlette |
+| Maximum performance | Rust (Robyn/Granian) |
+| Production-grade CORS | Starlette middleware |
+
+But for agent hosting with custom protocols: **Raw ASGI is correct**.
+
+---
+
+## Summary
+
+We chose raw ASGI because:
+
+1. **Control** - Future streaming, P2P, custom protocols
+2. **Simplicity** - One less dependency
+3. **Transparency** - Clear what happens
+4. **Precedent** - Sanic and BlackSheep did the same
+
+The ~70 lines of HTTP/WS handling is a fair trade for full protocol control and zero framework dependencies.

connectonion/docs/hook-system-options.md

@@ -0,0 +1,364 @@
+# Hook System Design Options
+
+Four different API styles for hooks in ConnectOnion.
+
+> **Note:** This document is historical. The final API uses event wrappers (Option 2 style) with updated naming:
+> - `before_each_tool` / `after_each_tool` - per-tool events
+> - `before_tools` / `after_tools` - batch events (fire once per round)
+>
+> See [014-event-api-naming.md](./design-decisions/014-event-api-naming.md) for the rationale.
+
+---
+
+## Option 1: TypedDict Hooks
+
+```python
+from connectonion import Agent, HookEvents
+
+def log_tokens(data):
+    print(f"Tokens: {data['usage']['total_tokens']}")
+
+def add_timestamp(data):
+    from datetime import datetime
+    data['messages'].append({
+        'role': 'system',
+        'content': f'Current time: {datetime.now()}'
+    })
+    return data
+
+def cache_results(data):
+    cache[data['tool_name']] = data['result']
+    return data
+
+agent = Agent(
+    "assistant",
+    tools=[search, analyze],
+
+    # ✨ TypedDict provides IDE autocomplete + type checking
+    on_event=dict(
+        before_llm=[add_timestamp],
+        after_llm=[log_tokens],
+        after_tool=[cache_results],
+    )
+)
+
+agent.input("Find Python info")
+```
+
+**Type Definition (in connectonion):**
+```python
+from typing import TypedDict, List, Callable
+
+class HookEvents(TypedDict, total=False):
+    """Type-safe hook event configuration.
+
+    IDE will autocomplete event names and type checker will validate.
+    All fields are optional - only specify the events you need.
+    """
+    before_llm: List[Callable]
+    after_llm: List[Callable]
+    before_tool: List[Callable]
+    after_tool: List[Callable]
+    on_error: List[Callable]
+```
+
+**With Type Annotation (for IDE hints):**
+```python
+# Option A: Inline annotation
+on_event: HookEvents = dict(
+    before_llm=[add_timestamp],
+    after_llm=[log_tokens]  # ← IDE autocompletes event names!
+)
+
+# Option B: Without annotation (still works, less IDE help)
+on_event=dict(
+    before_llm=[add_timestamp],
+    after_llm=[log_tokens]
+)
+
+agent = Agent("assistant", tools=[search], on_event=on_event)
+```
+
+**Reusable across agents:**
+```python
+from connectonion import HookEvents
+
+common_hooks: HookEvents = dict(
+    after_llm=[log_tokens],
+    after_tool=[cache_results],
+)
+
+agent1 = Agent("assistant", tools=[search], on_event=common_hooks)
+agent2 = Agent("analyst", tools=[analyze], on_event=common_hooks)
+```
+
+---
+
+## Option 2: Event Wrappers
+
+```python
+from connectonion import Agent, before_llm, after_llm, after_tool
+
+def log_tokens(data):
+    print(f"Tokens: {data['usage']['total_tokens']}")
+
+def add_timestamp(agent):
+    from datetime import datetime
+    agent.messages 
+    data['messages'].append({
+        'role': 'system',
+        'content': f'Current time: {datetime.now()}'
+    })
+   
+
+def cache_results(data):
+    cache[data['tool_name']] = data['result']
+    return data
+
+agent = Agent(
+    "assistant",
+    tools=[search, analyze],
+    hooks=[
+        before_llm(add_timestamp),
+        after_llm(log_tokens),
+        after_tool(cache_results),
+    ]
+)
+
+agent.input("Find Python info")
+```
+
+**With lambdas:**
+```python
+from connectonion import Agent, after_llm, after_tool
+
+agent = Agent(
+    "assistant",
+    tools=[search],
+    on_event=[
+        after_llm(lambda d: print(f"Tokens: {d['usage']['total_tokens']}")),
+        after_tool(lambda d: cache.set(d['tool_name'], d['result'])),
+    ]
+)
+```
+
+**Import and use patterns:**
+```python
+# connectonion/thinking.py
+from connectonion import after_tool
+
+def chain_of_thought():
+    def hook(data, agent):
+        thinking = agent.llm.complete([...])
+        agent.current_session['messages'].append({'role': 'assistant', 'content': thinking})
+    return after_tool(hook)
+
+# User code
+from connectonion import Agent
+from connectonion.thinking import chain_of_thought
+
+agent = Agent("assistant", tools=[search], on_event=[
+    chain_of_thought()  # Just import and use!
+])
+```
+
+---
+
+## Option 3: Decorator Pattern
+
+```python
+from connectonion import Agent, hook
+
+@hook('before_llm')
+def add_timestamp(data):
+    from datetime import datetime
+    data['messages'].append({
+        'role': 'system',
+        'content': f'Current time: {datetime.now()}'
+    })
+    return data
+
+@hook('after_llm')
+def log_tokens(data):
+    print(f"Tokens: {data['usage']['total_tokens']}")
+
+@hook('after_tool')
+def cache_results(data):
+    cache[data['tool_name']] = data['result']
+    return data
+
+# Pass decorated hooks to agent
+agent = Agent(
+    "assistant",
+    tools=[search, analyze],
+    hooks=[add_timestamp, log_tokens, cache_results]  # Decorated functions
+)
+
+agent.input("Find Python info")
+```
+
+**Reusable module:**
+```python
+# hooks.py
+from connectonion import hook
+
+@hook('before_llm')
+def add_timestamp(data):
+    from datetime import datetime
+    data['messages'].append({'role': 'system', 'content': f'{datetime.now()}'})
+    return data
+
+@hook('after_llm')
+def log_tokens(data):
+    print(f"Tokens: {data['usage']['total_tokens']}")
+
+# main.py
+from connectonion import Agent
+from .hooks import add_timestamp, log_tokens
+
+agent = Agent(
+    "assistant",
+    tools=[search],
+    hooks=[add_timestamp, log_tokens]  # Import and pass decorated hooks
+)
+```
+
+---
+
+## Option 4: Event Emitter
+
+```python
+from connectonion import Agent
+
+agent = Agent("assistant", tools=[search])
+
+# Simple lambda
+agent.on('after_llm', lambda d: print(f"Tokens: {d['usage']['total_tokens']}"))
+
+# Decorator syntax
+@agent.on('before_llm')
+def add_timestamp(data):
+    from datetime import datetime
+    data['messages'].append({
+        'role': 'system',
+        'content': f'Current time: {datetime.now()}'
+    })
+    return data
+
+@agent.on('after_tool')
+def cache_results(data):
+    cache[data['tool_name']] = data['result']
+    return data
+
+agent.input("Find Python info")
+```
+
+**Dynamic add/remove:**
+```python
+agent = Agent("assistant", tools=[search])
+
+# Add hook
+agent.on('after_llm', log_tokens)
+
+# Later... remove hook
+agent.off('after_llm', log_tokens)
+```
+
+---
+
+## Common Use Cases
+
+### Cost Tracking
+
+```python
+# Option 1: TypedDict
+from connectonion import Agent, HookEvents
+
+agent = Agent(
+    "assistant",
+    tools=[search],
+    on_event=dict(
+        after_llm=[lambda d: print(f"Cost: ${d['usage']['total_tokens'] * 0.00001:.4f}")]
+    )
+)
+
+# Option 2: Event Wrappers
+from connectonion import after_llm
+agent = Agent("assistant", tools=[search], on_event=[
+    after_llm(lambda d: print(f"Cost: ${d['usage']['total_tokens'] * 0.00001:.4f}"))
+])
+
+# Option 3: Decorator
+@hook('after_llm')
+def track_cost(data):
+    print(f"Cost: ${data['usage']['total_tokens'] * 0.00001:.4f}")
+
+# Option 4: Event Emitter
+agent.on('after_llm', lambda d: print(f"Cost: ${d['usage']['total_tokens'] * 0.00001:.4f}"))
+```
+
+### Smart Caching
+
+```python
+cache = {}
+
+def cache_tool(data):
+    key = f"{data['tool_name']}:{hash(str(data['tool_args']))}"
+    cache[key] = data['result']
+    return data
+
+# Option 1: TypedDict
+agent = Agent("assistant", tools=[search], on_event=dict(after_tool=[cache_tool]))
+
+# Option 2: Event Wrappers
+agent = Agent("assistant", tools=[search], on_event=[after_tool(cache_tool)])
+
+# Option 3: Decorator
+@hook('after_tool')
+def cache_tool(data): ...
+
+# Option 4: Event Emitter
+agent.on('after_tool', cache_tool)
+```
+
+### Custom Logging
+
+```python
+# Option 1: TypedDict
+agent = Agent(
+    "assistant",
+    tools=[search],
+    on_event=dict(
+        before_tool=[lambda d: logger.info(f"Tool: {d['tool_name']}")],
+        on_error=[lambda d: logger.error(f"Error: {d['error']}")]
+    )
+)
+
+# Option 2: Event Wrappers
+from connectonion import before_tool, on_error
+agent = Agent("assistant", tools=[search], on_event=[
+    before_tool(lambda d: logger.info(f"Tool: {d['tool_name']}")),
+    on_error(lambda d: logger.error(f"Error: {d['error']}"))
+])
+
+# Option 3: Decorator
+@hook('before_tool')
+def log_tool(data):
+    logger.info(f"Tool: {data['tool_name']}")
+
+@hook('on_error')
+def log_error(data):
+    logger.error(f"Error: {data['error']}")
+
+# Option 4: Event Emitter
+agent.on('before_tool', lambda d: logger.info(f"Tool: {d['tool_name']}"))
+agent.on('on_error', lambda d: logger.error(f"Error: {d['error']}"))
+```
+
+---
+
+## Vote
+
+Which option do you prefer?
+
+👉 https://github.com/openonion/connectonion/issues/31

connectonion/docs/integrations/README.md

@@ -0,0 +1,12 @@
+# Integrations
+
+Connect ConnectOnion to external services.
+
+## Authentication
+
+- [auth.md](auth.md) - Authentication with managed keys (`co auth`)
+
+## OAuth Integrations
+
+- [google.md](google.md) - Google OAuth (Gmail, Calendar)
+- [microsoft.md](microsoft.md) - Microsoft OAuth (Outlook, Calendar)