# 🧙 Agent Setup Wizard

The interactive setup wizard makes it easy to configure new agents for the Jetstream-Letta bridge system. It guides you through all the required configuration steps and validates your settings.

## Quick Start

### Option 1: Using the helper script (Recommended)
```bash
./run_agent.sh setup
```

### Option 2: Using the bridge directly
```bash
python src/jetstream_letta_bridge.py --setup
```

### Option 3: Using the standalone script
```bash
python setup_agent.py
```

## What the Wizard Does

### 🤖 **Agent Information**
- Prompts for agent name and description
- Lets you choose from pre-configured templates:
  - **Technical**: Quick responses (batch_size: 1, max_steps: 100)
  - **Creative**: Contextual responses (batch_size: 3, max_steps: 150) 
  - **Analytical**: Deep analysis (batch_size: 5, max_steps: 200)
  - **Custom**: Configure your own settings

### 🦋 **Bluesky Configuration** 
- Collects your Bluesky handle/email
- Prompts for app password (with security reminder)
- Configures PDS URI (defaults to https://bsky.social)
- **Tests authentication** to verify credentials work

### 🧠 **Letta Configuration**
- Collects your Letta API key
- **Automatically fetches and displays your agents** from Letta
- Shows a table with agent details (ID, name, model, tools)
- Lets you select which agent to use
- Configures timeout settings

### 🌊 **Jetstream Monitoring**
- Configures jetstream instance (defaults to official endpoint)
- Optionally lets you specify DIDs to monitor
- Sets up reconnection settings

### 💾 **File Generation**
- Generates a complete YAML configuration file
- Saves to `agents/` directory with descriptive filename
- Shows usage instructions for your new agent

## Prerequisites

Before running the setup wizard, make sure you have:

### 1. Bluesky Account Setup
1. Create a Bluesky account at https://bsky.app
2. Go to Settings → App Passwords
3. Generate a new app password
4. **Important**: Use the app password, not your main account password!

### 2. Letta Agent Setup
1. Create a Letta account and get your API key
2. Create at least one agent in your Letta dashboard
3. Note your agent ID (the wizard can fetch this automatically)

### 3. Python Dependencies
Install required packages:
```bash
pip install click rich pyyaml requests
```

## Usage Examples

### Complete Setup Flow
```bash
$ ./run_agent.sh setup

🤖 Jetstream-Letta Bridge Setup Wizard

This wizard will help you configure a new agent...
Ready to set up your agent? [Y/n]: y

📝 Agent Information
Agent name: TechSupport
Select agent template:
  1. Technical - Quick responses for technical discussions
  2. Creative - Contextual responses for creative content  
  3. Analytical - Deep analysis with larger batches
  4. Custom - Configure your own settings
[1]: 1

🦋 Bluesky Configuration
Bluesky handle: support.mycompany.bsky.social
App password: [hidden]
Test Bluesky connection now? [Y/n]: y
✅ Bluesky authentication successful!

🧠 Letta Configuration
Letta API key: [hidden]
✅ Found 3 agents in your Letta account:
┌─────┬──────────────────────┬─────────────┬────────┬────────────┐
│  #  │      Agent ID        │    Name     │ Model  │   Tools    │
├─────┼──────────────────────┼─────────────┼────────┼────────────┤
│  1  │ agent-tech-uuid-123  │ TechBot     │ gpt-4  │ send_msg..│
│  2  │ agent-create-uuid-45 │ CreativeAI  │ gpt-4  │ send_msg..│
│  3  │ agent-analyze-uuid-78│ DataBot     │ gpt-4  │ send_msg..│
└─────┴──────────────────────┴─────────────┴────────┴────────────┘
Select agent (1-3): 1

🌊 Jetstream Configuration
Monitor specific DIDs only? [y/N]: n

💾 Saving Configuration
Configuration filename [techsupport.yaml]: 
✅ Configuration saved to: agents/techsupport.yaml

🎉 Setup Complete!
Your agent is ready to use!

Start your agent:
  ./run_agent.sh techsupport
```

### Testing Your Configuration
After setup, test your agent:
```bash
# Start with verbose output to see what's happening
./run_agent.sh techsupport --verbose

# Or test the configuration file directly
python src/jetstream_letta_bridge.py --agent agents/techsupport.yaml --verbose
```

## Troubleshooting

### Authentication Issues
- **Bluesky**: Make sure you're using an app password, not your main password
- **Letta**: Verify your API key is correct and has proper permissions
- **Test connections**: The wizard will test connections and show specific error messages

### Agent Issues
- **Agent not found**: Make sure the agent ID exists in your Letta account
- **Permission errors**: Ensure your API key has access to the specified agent

### Configuration Issues  
- **File not saved**: Check that you have write permissions to the `agents/` directory
- **Invalid YAML**: The wizard generates valid YAML, but manual edits might break formatting

### Runtime Issues
```bash
# List available agents to verify your config was created
./run_agent.sh list

# Check the generated configuration file
cat agents/your-agent.yaml

# Test with minimal monitoring (no DIDs specified)
python src/jetstream_letta_bridge.py --agent agents/your-agent.yaml --wanted-dids ""
```

## Advanced Configuration

The wizard creates a complete configuration file, but you can manually edit it afterwards for advanced settings:

```yaml
# Edit agents/your-agent.yaml
agent:
  batch_size: 3        # Adjust batch processing
  max_steps: 150       # Increase for complex tasks

jetstream:
  wanted_dids:         # Add specific communities to monitor
    - "did:plc:community1"  
    - "did:plc:community2"

letta:
  timeout: 900         # Increase timeout for slow responses
```

## Next Steps

After setting up your agent:

1. **Test it**: Run with `--verbose` to see activity
2. **Monitor specific communities**: Add DIDs to `wanted_dids` 
3. **Adjust batch size**: Based on your agent's response patterns
4. **Create more agents**: Run the wizard again for different specializations
5. **Schedule agents**: Use cron or similar to run different agents at different times

## Getting Help

- Run `./run_agent.sh help` for usage options
- Check the main README.md for system overview  
- Look at example configurations in `agents/` directory
- Use `--verbose` flag to see detailed activity logs