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

connectonion/docs/cli/init.md

@@ -0,0 +1,431 @@
+# ConnectOnion Init Command
+
+The `co init` command initializes ConnectOnion in an existing directory, perfect for adding agent capabilities to existing projects.
+
+## Overview
+
+```bash
+co init [options]
+```
+
+Initializes ConnectOnion in the current directory with:
+- AI features enabled by default
+- Global address/email from `~/.co/`
+- API keys appended to existing `.env` (or created if missing)
+- Template files added to your project
+- Docs always updated to latest version
+
+## Command Comparison
+
+| Feature | `co create` | `co init` |
+|---------|------------|-----------|
+| Creates new directory | ✅ Yes | ❌ No (uses current) |
+| Can work in non-empty dir | ❌ No | ✅ Yes |
+| Uses global identity | ✅ Yes | ✅ Yes |
+| Copies global API keys | ✅ Yes | ✅ Yes (appends) |
+| Supports templates | ✅ Yes | ✅ Yes |
+
+## Usage Scenarios
+
+### Scenario 1: Adding to Existing Project with .env
+
+You have a project with existing `.env` file:
+
+```bash
+$ cd my-existing-project
+$ cat .env
+DATABASE_URL=postgres://localhost/mydb
+SECRET_KEY=mysecret
+
+$ co init
+
+🧅 ConnectOnion Project Initializer
+========================================
+
+✓ Using global identity
+✓ Found existing .env file
+✓ Appending API keys from ~/.co/keys.env
+
+$ cat .env
+DATABASE_URL=postgres://localhost/mydb
+SECRET_KEY=mysecret
+
+# ConnectOnion API Keys
+OPENAI_API_KEY=sk-proj-xxx
+ANTHROPIC_API_KEY=sk-ant-xxx
+```
+
+Your existing environment variables are preserved, API keys are appended!
+
+### Scenario 2: Quick Init in Empty Directory
+
+```bash
+$ mkdir my-new-agent
+$ cd my-new-agent
+$ co init --yes
+
+✓ Using global identity
+✓ Created new .env with API keys from ~/.co/keys.env
+
+✅ ConnectOnion project initialized!
+```
+
+### Scenario 3: Updating Documentation
+
+Running `co init` again updates docs to latest version:
+
+```bash
+$ co init
+
+✓ Project already initialized
+✓ Updating .co/docs/ to latest version
+✓ .env already has API keys
+
+✅ Documentation updated!
+```
+
+## What Gets Added/Updated
+
+When you run `co init`:
+
+```
+your-project/
+├── agent.py             # Added if missing (skipped if exists)
+├── .env                 # APPENDED with API keys (created if missing)
+├── .co/
+│   ├── config.toml     # Project config (uses global identity)
+│   └── docs/           # ALWAYS UPDATED to latest version
+│       ├── co-vibe-coding-all-in-one.md  # Overwritten
+│       └── connectonion.md                # Overwritten
+└── [your existing files remain untouched]
+```
+
+## File Handling Strategy
+
+| File/Directory | If Exists | Behavior |
+|----------------|-----------|----------|
+| `agent.py` | Skip | Won't overwrite user code |
+| `.env` | **Append** | Adds API keys if missing |
+| `.co/docs/` | **Overwrite** | Always latest documentation |
+| `.co/config.toml` | Update | Preserves custom settings |
+| `.gitignore` | Append | Adds ConnectOnion entries |
+
+## .env Handling Details
+
+### Case 1: No .env File
+Creates new `.env` with API keys from `~/.co/keys.env`:
+```bash
+# Created .env
+OPENAI_API_KEY=sk-proj-xxx
+ANTHROPIC_API_KEY=sk-ant-xxx
+```
+
+### Case 2: .env Exists, No API Keys
+Appends API keys to existing file:
+```bash
+# Original .env
+DATABASE_URL=postgres://localhost
+REDIS_URL=redis://localhost
+
+# After co init
+DATABASE_URL=postgres://localhost
+REDIS_URL=redis://localhost
+
+# ConnectOnion API Keys
+OPENAI_API_KEY=sk-proj-xxx
+ANTHROPIC_API_KEY=sk-ant-xxx
+```
+
+### Case 3: .env Has Some API Keys
+Only appends missing keys:
+```bash
+# Original .env
+OPENAI_API_KEY=sk-proj-old
+
+# After co init (adds missing keys)
+OPENAI_API_KEY=sk-proj-old
+
+# ConnectOnion API Keys
+ANTHROPIC_API_KEY=sk-ant-xxx  # Added
+GEMINI_API_KEY=AIza...         # Added
+```
+
+### Case 4: .env Has All Keys
+No changes made:
+```bash
+✓ .env already contains all API keys
+```
+
+## Global Configuration
+
+Like `co create`, `co init` uses the global configuration:
+
+### First Time Setup
+If `~/.co/` doesn't exist, it's created automatically:
+
+```bash
+$ co init  # First time ever
+
+🚀 Welcome to ConnectOnion!
+✨ Setting up global configuration...
+  ✓ Generated master keypair
+  ✓ Your address: 0x7a9f3b2c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a
+  ✓ Your email: 0x7a9f3b2c@mail.openonion.ai
+  ✓ Created ~/.co/config.toml
+  ✓ Created ~/.co/keys.env
+
+[continues with project initialization...]
+```
+
+### Using Existing Global Config
+
+```bash
+$ co init  # After global config exists
+
+✓ Using global identity
+✓ Using global email: 0x7a9f3b2c@mail.openonion.ai
+✓ Found OpenAI key in ~/.co/keys.env
+✓ Appending to existing .env
+
+[continues with project initialization...]
+```
+
+## Command Options
+
+```bash
+co init [options]
+
+Options:
+  --template, -t          Template to use (minimal/web-research/playwright/custom)
+  --no-ai                 Disable AI features (not recommended)
+  --key                   API key to use (saves to global config)
+  --force                 Initialize even in special directories
+  --yes, -y              Accept all defaults, skip prompts
+  --update-docs          Only update documentation
+```
+
+## Templates
+
+Same templates as `co create`:
+
+1. **minimal** - Basic agent with simple tools
+2. **web-research** - Web scraping and research
+3. **playwright** - Browser automation
+4. **custom** - AI-generated based on description
+
+## Special Directory Warnings
+
+`co init` warns when initializing in special directories:
+
+- Home directory (`~`)
+- Root directory (`/`)
+- System directories (`/usr`, `/etc`)
+- Git repositories (warns but allows)
+
+Use `--force` to bypass warnings if you know what you're doing.
+
+## Examples
+
+### Basic Init
+```bash
+# In current directory
+$ co init
+
+# Accept all defaults
+$ co init -y
+
+# With specific template
+$ co init --template web-research
+```
+
+### Adding to Django Project
+```bash
+$ cd my-django-app
+$ co init
+# Your existing .env is preserved
+# DATABASE_URL, SECRET_KEY remain
+# API keys are appended
+```
+
+### Updating Documentation Only
+```bash
+$ co init --update-docs
+✓ Updated .co/docs/ to latest version
+```
+
+### Custom Template
+```bash
+$ co init --template custom --description "Discord bot integration"
+```
+
+## Smart .env Merging
+
+The `.env` append logic is intelligent:
+
+```python
+# Pseudo-code of .env handling
+existing_env = read(".env")
+global_keys = read("~/.co/keys.env")
+
+for key, value in global_keys:
+    if key not in existing_env:
+        append_to_env(f"\n# ConnectOnion API Keys\n{key}={value}")
+```
+
+This ensures:
+- No duplicate keys
+- Existing values preserved
+- Clear section for ConnectOnion keys
+- Original file structure maintained
+
+## Documentation Updates
+
+The `.co/docs/` folder is **always overwritten** to ensure:
+- Latest documentation version
+- New features documented
+- Bug fixes in docs
+- Consistent formatting
+
+This is safe because users shouldn't edit framework docs directly.
+
+## Common Workflows
+
+### 1. Existing Django/Flask Project
+```bash
+cd my-web-app
+co init
+# .env preserved with database URLs
+# API keys appended
+# Latest docs installed
+```
+
+### 2. Updating Existing ConnectOnion Project
+```bash
+cd old-agent-project
+co init
+# Docs updated to latest
+# Missing API keys added
+# Config preserved
+```
+
+### 3. Converting Script to Agent
+```bash
+cd my-scripts
+co init
+# Creates .env with API keys
+# Adds agent.py template
+# Your scripts untouched
+```
+
+## Troubleshooting
+
+### .env Already Has Different API Key
+The existing key is preserved:
+```bash
+# Original .env
+OPENAI_API_KEY=sk-old-key
+
+# After co init - NOT changed
+OPENAI_API_KEY=sk-old-key
+```
+
+### Docs Seem Old
+Re-run init to update:
+```bash
+$ co init --update-docs
+✓ Documentation updated to latest version
+```
+
+### Want Fresh .env
+Manually remove and re-init:
+```bash
+$ rm .env
+$ co init
+✓ Created new .env with latest API keys
+```
+
+## Best Practices
+
+1. **Review .env after init** - Check that API keys were appended correctly
+
+2. **Keep docs updated** - Run `co init --update-docs` periodically
+
+3. **Don't edit framework docs** - They'll be overwritten on update
+
+4. **Commit .co/config.toml** - Track project configuration
+
+5. **Never commit .env** - Keep API keys secret
+
+## File Safety Summary
+
+| Action | Safe? | Why |
+|--------|-------|-----|
+| Append to .env | ✅ Yes | Only adds missing keys |
+| Overwrite docs | ✅ Yes | Framework docs, not user content |
+| Skip agent.py | ✅ Yes | Preserves user code |
+| Update config | ✅ Yes | Merges, doesn't replace |
+
+## Summary
+
+`co init` intelligently integrates ConnectOnion into existing projects:
+
+- **Preserves** - Your existing `.env` values
+- **Appends** - Only missing API keys
+- **Updates** - Documentation to latest
+- **Respects** - Your existing code
+- **Uses** - Global identity and keys
+
+Perfect for adding AI agents to any Python project without disrupting existing configuration!
+# ConnectOnion Init (co init)
+
+Add ConnectOnion to an existing folder safely.
+
+## Quick Start
+
+```bash
+cd existing-project
+co init
+```
+
+## What It Does
+
+- Uses your global identity from `~/.co` (address + email)
+- Appends missing API keys to `.env` (creates it if missing)
+- Adds `.co/config.toml` and refreshes `.co/docs/`
+- Never overwrites your code (skips existing files)
+
+## Safe In Existing Folders
+
+- Warns in special/system directories (e.g., `~`, `/`)
+- Shows what will be created or updated
+- `--force` lets you continue when you know what you’re doing
+
+## Templates
+
+- minimal: basic agent
+- playwright: browser automation
+- custom: describe it, we generate it with AI
+
+```bash
+co init -t minimal
+co init -t playwright
+co init -t custom --description "Monitor a site and alert me"
+```
+
+## Options (the useful bits)
+
+- `--template, -t`: `minimal` | `playwright` | `custom`
+- `--key`: paste an API key (auto-detects provider and appends to `.env`)
+- `--force`: continue in non-empty/special directories
+- `--yes, -y`: accept defaults and skip prompts
+
+Notes:
+- Keeps `.env` intact; only appends missing keys
+- Provider mapping: OpenAI → `OPENAI_API_KEY`, Anthropic → `ANTHROPIC_API_KEY`, Google → `GEMINI_API_KEY`, Groq → `GROQ_API_KEY`
+- Attempts managed-key authentication on success (or run `co auth` later)
+
+## Next Steps
+
+```bash
+python agent.py
+```

connectonion/docs/co-directory-structure.md

@@ -0,0 +1,214 @@
+# The .co Directory Structure
+
+ConnectOnion uses two `.co/` directories: a global one (`~/.co/`) for shared settings and a project one for local config.
+
+## Global Directory (`~/.co/`)
+
+Created automatically on first `co` command. Stores your identity and shared API keys.
+
+```
+~/.co/
+├── config.toml          # Global configuration (address, default model)
+├── keys.env             # Shared API keys (.env format)
+├── keys/                # Cryptographic identity
+│   ├── agent.key        # Ed25519 private key (NEVER SHARE)
+│   ├── recovery.txt     # 12-word recovery phrase
+│   └── DO_NOT_SHARE     # Warning file
+├── logs/                # Agent activity logs ({agent_name}.log)
+└── sessions/            # YAML session logs for eval/replay
+```
+
+## Project Directory (`.co/`)
+
+Created by `co create` or `co init`. Contains project-specific runtime data.
+
+```
+.co/
+├── keys/                # Project keys (if independent identity)
+│   ├── agent.key        # Private signing key (Ed25519)
+│   ├── recovery.txt     # 12-word recovery phrase
+│   └── DO_NOT_SHARE     # Warning file
+├── logs/                # Agent activity logs ({agent_name}.log)
+└── sessions/            # YAML session logs for eval/replay
+```
+
+## config.toml Reference
+
+The `config.toml` file exists only in the global `~/.co/` directory:
+
+```toml
+[connectonion]
+framework_version = "0.0.7"
+created = "2025-01-15T10:30:00.000000"
+
+[cli]
+version = "1.0.0"
+
+[agent]
+address = "0x7a9f3b2c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a"
+short_address = "0x7a9f...7f8a"
+email = "0x7a9f3b2c@mail.openonion.ai"
+created_at = "2025-01-15T10:30:00.000000"
+algorithm = "ed25519"
+default_model = "co/gemini-2.5-pro"
+max_iterations = 10
+
+[auth]
+token = "eyJhbGciOiJI..."  # JWT for network auth
+```
+
+## Keys Directory
+
+The `keys/` directory contains your agent's cryptographic identity. **This directory should NEVER be committed to version control.**
+
+### agent.key
+- **Format**: Binary Ed25519 private key (32 bytes)
+- **Purpose**: Signs messages for agent-to-agent communication
+- **Security**: Should be encrypted at rest (future feature)
+
+### recovery.txt
+- **Format**: 12-word BIP39 mnemonic phrase
+- **Purpose**: Recover agent identity on new machines
+- **Example**: `canyon robot vacuum circle tornado diet depart rough detect theme sword scissors`
+- **Security**: Store securely, never share, enables full key recovery
+
+### DO_NOT_SHARE
+- **Format**: Plain text warning file
+- **Purpose**: Reminds developers these are private keys
+- **Content**: 
+  ```
+  ⚠️ WARNING: PRIVATE KEYS - DO NOT SHARE ⚠️
+  
+  This directory contains private cryptographic keys.
+  NEVER share these files or commit them to version control.
+  Anyone with these keys can impersonate your agent.
+  ```
+
+## Agent Address Format
+
+The agent address is a hex-encoded Ed25519 public key:
+
+```
+0x3d4017c3e843895a92b70aa74d1b7ebc9c982ccf2ec4968cc0cd55f12af4660c
+```
+
+- **Prefix**: `0x` (indicates hexadecimal, familiar from Ethereum)
+- **Length**: 66 characters total (0x + 64 hex characters)
+- **Content**: Direct encoding of 32-byte Ed25519 public key
+- **Property**: Can be converted back to public key for signature verification
+
+### Why This Format?
+
+1. **No Information Loss**: The address IS the public key (not a hash)
+2. **Direct Verification**: Can verify signatures without additional data
+3. **Familiar Format**: Developers recognize the 0x prefix
+4. **Fast Signatures**: Ed25519 provides 70,000 signatures/second
+
+## Logs and Sessions
+
+Created at runtime when agents execute.
+
+### `logs/` - Plain Text Activity Logs
+
+Each agent writes to `{agent_name}.log`:
+
+```
+2025-01-15 10:30:00 [assistant] Task: What is 2+2?
+2025-01-15 10:30:01 [assistant] Tool: calculate("2+2") -> 4
+2025-01-15 10:30:02 [assistant] Result: The answer is 4
+```
+
+### `sessions/` - YAML Session Logs
+
+Detailed per-session logs for eval and replay:
+
+```yaml
+# sessions/assistant_2025-01-15_103000.yaml
+agent: assistant
+model: co/gemini-2.5-pro
+started_at: "2025-01-15T10:30:00Z"
+turns:
+  - input: "What is 2+2?"
+    tools_called: ["calculate"]
+    result: "The answer is 4"
+    duration_ms: 1234
+```
+
+## Security Considerations
+
+### What's Git-Ignored
+
+The following should ALWAYS be in `.gitignore`:
+
+```gitignore
+# ConnectOnion sensitive files
+.co/keys/          # Private keys - NEVER commit
+.co/logs/          # May contain sensitive data
+.co/evals/      # Session data
+.env               # API keys
+```
+
+### What's Safe to Commit
+
+Project `.co/` directories typically contain only runtime data (keys, logs, sessions) which should all be git-ignored. The project code itself is safe to commit.
+
+## Progressive Disclosure
+
+The `.co` directory follows ConnectOnion's philosophy of progressive disclosure:
+
+1. **Day 1**: User never looks inside `.co`, everything just works
+2. **Week 1**: User discovers their agent has an address in `config.toml`
+3. **Month 1**: User learns about recovery phrases when setting up new machine
+4. **Advanced**: User understands the Ed25519 cryptography when building network features
+
+## Common Operations
+
+### View Your Agent Address
+```bash
+cat ~/.co/config.toml | grep address
+```
+
+### Backup Your Identity
+```bash
+cp -r ~/.co/keys ~/secure-backup/
+# Or just save the recovery phrase
+cat ~/.co/keys/recovery.txt
+```
+
+### Add API Key
+```bash
+echo "NEW_API_KEY=xxx" >> ~/.co/keys.env
+```
+
+### Check Framework Version
+```bash
+cat ~/.co/config.toml | grep framework_version
+```
+
+## FAQ
+
+### Q: Why save the recovery phrase in plain text?
+
+**Pragmatism over dogma.** Most developers would lose their keys without this. Advanced users can encrypt the directory. We chose usability for the 90% case.
+
+### Q: Can I regenerate my keys?
+
+No, and you shouldn't want to. Your address is your agent's identity. Changing it would break all existing connections. Use the recovery phrase to restore keys instead.
+
+### Q: Why not use Ethereum keys for compatibility?
+
+Ed25519 is 3x faster for signatures (70k/sec vs 20k/sec). For an agent network exchanging thousands of messages, performance matters more than blockchain compatibility.
+
+### Q: Is the address a real Ethereum address?
+
+No. It looks like one (0x prefix, hex format) for familiarity, but it's an Ed25519 public key, not an Ethereum address. You cannot receive ETH at this address.
+
+## Summary
+
+The `.co` directory encapsulates everything unique about your ConnectOnion project:
+- **Identity**: Your agent's cryptographic address
+- **Configuration**: Project and agent settings
+- **Documentation**: Offline reference materials
+- **History**: Runtime behavior tracking
+
+Most users never need to understand these details. The system generates everything silently and it just works. But when you need to know, everything is transparent and well-documented.