# Using Personal Connectors

div
strong
🔨 In Development
 — This section is still being developed and may change.


This practical guide shows you how to effectively use personal connectors in your AI assistants and applications.

## Quick Start

### 1. Set Up Your First Connector


```python
import os
from freddy import Freddy

# Initialize client
freddy = Freddy(api_key=os.getenv("FREDDY_API_KEY"))

# Create a Notion connector configuration
config = freddy.personal_connectors.configurations.create(
    connector_type="notion",
    name="My Notion Workspace",
    credentials={
        "api_key": os.getenv("NOTION_API_KEY"),
        "workspace_id": "your-workspace-id"
    },
    settings={
        "allowed_pages": ["specific-page-id"],  # Optional: restrict access
        "read_only": False
    }
)
```

### 2. Create an Assistant with Connector Access


```python
# Create assistant that can use the connector
assistant = freddy.assistants.create(
    name="Notion Assistant",
    instructions="""You have access to my Notion workspace. You can:

    - Search for information in my pages and databases
    - Create new pages when asked
    - Update existing content
    - Organize and categorize information

    Always be helpful and ask for clarification when needed.""",
    model="gpt-4"
    # Connector functions are automatically available
)

# The assistant can now call Notion functions automatically
```

### 3. Use in Conversations


```python
# Create a thread
thread = freddy.threads.create()

# Ask the assistant to use the connector
message = freddy.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Can you search my Notion workspace for project ideas about AI?"
)

# Run the assistant
run = freddy.threads.runs.create(
    thread_id=thread.id,
    assistant_id=assistant.id
)

# The assistant will automatically use the Notion connector
```

## Practical Examples

### Research Assistant


```python
# Research assistant with multiple connectors
research_assistant = freddy.assistants.create(
    name="Research Assistant",
    instructions="""You are a research assistant with access to:

📚 Knowledge Sources:
- My Notion workspace (research notes, articles, projects)
- Web search for current information
- Google Drive documents

🔧 Capabilities:
- Search and summarize research materials
- Cross-reference information across sources
- Organize findings in structured formats
- Create research summaries and reports

📋 Process:
1. Understand the research topic
2. Search relevant sources using available tools
3. Synthesize information from multiple sources
4. Present findings in a clear, organized manner""",
    model="gpt-4"
)
```

### Project Manager


```python
# Project management assistant
project_assistant = freddy.assistants.create(
    name="Project Manager",
    instructions="""You help manage projects using my connected tools:

📅 Calendar Integration:
- Check Google Calendar for scheduling conflicts
- Schedule meetings and deadlines
- Send calendar invites

📝 Task Management:
- Create and update tasks in Notion
- Track project progress
- Assign tasks to team members

💬 Communication:
- Send Slack messages for updates
- Email stakeholders when needed

🔄 Workflow:
1. Review current project status
2. Identify next steps and dependencies
3. Coordinate with team members
4. Update project documentation""",
    model="gpt-4"
)
```

### Personal Finance Assistant


```python
# Finance assistant with banking and budgeting connectors
finance_assistant = freddy.assistants.create(
    name="Finance Assistant",
    instructions="""You help manage personal finances with access to:

🏦 Banking Data:
- Account balances and transactions
- Spending categorization
- Budget tracking

💳 Credit Cards:
- Transaction history
- Payment due dates
- Rewards and cashback

📊 Investment Tracking:
- Portfolio performance
- Investment recommendations
- Market research

⚠️ Privacy Notice:
- All financial data is encrypted and secure
- No permanent storage of sensitive information
- Only process data as requested

💡 Capabilities:
- Analyze spending patterns
- Create budget recommendations
- Track investment performance
- Alert on unusual financial activity""",
    model="gpt-4"
)
```

## Advanced Usage Patterns

### Multi-Step Workflows

Design assistants that use multiple connectors in sequence:


```python
# Example: Content creation workflow
content_assistant = freddy.assistants.create(
    name="Content Creator",
    instructions="""You create content using multiple tools:

1. 📚 Research Phase:
   - Search Notion for existing content and ideas
   - Web search for current trends and information
   - Review Google Drive for brand guidelines

2. ✍️ Creation Phase:
   - Generate draft content based on research
   - Check for consistency with brand voice
   - Ensure content is original and engaging

3. 📢 Distribution Phase:
   - Share on appropriate platforms (Slack, email, etc.)
   - Schedule social media posts if needed
   - Archive final content in Notion

Always maintain content quality and brand consistency.""",
    model="gpt-4"
)
```

### Event-Driven Automation

Set up assistants that respond to external events:


```python
# Example: Email processing assistant
email_assistant = freddy.assistants.create(
    name="Email Processor",
    instructions="""You process incoming emails automatically:

📧 Email Analysis:
- Read new emails in Gmail
- Categorize by type (inquiry, complaint, request, etc.)
- Extract key information and action items

🎯 Automated Actions:
- Respond to simple inquiries automatically
- Create tasks in project management tools
- Forward important emails to team members
- Archive spam and irrelevant messages

📊 Reporting:
- Track email processing statistics
- Generate weekly summary reports
- Identify trends in customer inquiries

⚡ Speed & Accuracy:
- Process emails within minutes of receipt
- Maintain high accuracy in categorization
- Learn from corrections and feedback""",
    model="gpt-4"
)
```

## Error Handling and Reliability

### Robust Error Handling


```python
# Design assistants with comprehensive error handling
resilient_assistant = freddy.assistants.create(
    name="Resilient Assistant",
    instructions="""You are designed to handle errors gracefully:

🔄 Retry Logic:
- If a connector fails, try alternative approaches
- Retry failed operations with exponential backoff
- Use different connectors if primary ones fail

🛠️ Fallback Strategies:
- Provide alternative solutions when connectors are unavailable
- Use cached data when possible
- Suggest manual workarounds for critical tasks

📞 User Communication:
- Inform users when issues occur
- Explain what went wrong and what's being done
- Provide clear next steps and timelines

🔍 Debugging:
- Log detailed error information for analysis
- Identify patterns in failures
- Suggest improvements to prevent future issues

Always prioritize reliability and user experience.""",
    model="gpt-4"
)
```

### Monitoring and Maintenance


```python
# Monitor connector health and performance
def monitor_connectors():
    """Monitor connector performance and health."""

    # Check connector availability
    for config in freddy.personal_connectors.configurations.list().data:
        health = freddy.personal_connectors.check_health(config.id)

        if not health.healthy:
            print(f"Connector {config.name} is unhealthy: {health.issues}")

            # Attempt to fix common issues
            if "authentication" in health.issues:
                print("Attempting to refresh authentication...")
                freddy.personal_connectors.refresh_auth(config.id)

    # Monitor usage patterns
    usage = freddy.personal_connectors.get_usage()
    print(f"Total monthly calls: {usage.total_calls}")
    print(f"Data processed: {usage.data_mb} MB")
```

## Security and Privacy

### Data Protection Best Practices


```python
# Implement security best practices
secure_assistant = freddy.assistants.create(
    name="Secure Assistant",
    instructions="""You handle sensitive data with utmost care:

🔐 Data Security:
- Never store sensitive information permanently
- Encrypt all data in transit and processing
- Use secure authentication methods only
- Follow principle of least privilege

🤐 Privacy Protection:
- Only access data when explicitly requested
- Minimize data exposure in responses
- Respect user privacy preferences
- Comply with data protection regulations

🚨 Incident Response:
- Immediately report any data breaches or security issues
- Follow established security protocols
- Cooperate with security investigations
- Learn from incidents to improve security

Always prioritize security and privacy above all else.""",
    model="gpt-4"
)
```

## Performance Optimization

### Efficient Connector Usage


```python
# Optimize connector usage for performance
efficient_assistant = freddy.assistants.create(
    name="Efficient Assistant",
    instructions="""You optimize performance and costs:

⚡ Performance Optimization:
- Cache frequently accessed data
- Batch multiple operations when possible
- Use pagination for large datasets
- Minimize unnecessary API calls

💰 Cost Management:
- Choose the most efficient connector for each task
- Monitor usage and stay within budget limits
- Use preview/batch modes when available
- Implement smart caching strategies

📈 Scalability:
- Design workflows that scale with usage
- Handle rate limits gracefully
- Distribute workload across multiple connectors
- Monitor performance metrics continuously

Balance speed, cost, and reliability in all operations.""",
    model="gpt-4"
)
```

## Testing and Debugging

### Comprehensive Testing


```python
# Test connector integrations thoroughly
def test_connector_integration():
    """Test all connector functions."""

    test_cases = [
        {
            "name": "Notion Search",
            "function": "notion_search",
            "params": {"query": "test query"},
            "expected": "search results"
        },
        {
            "name": "Gmail Send",
            "function": "gmail_send_email",
            "params": {"to": "test@example.com", "subject": "Test"},
            "expected": "email sent confirmation"
        }
    ]

    for test_case in test_cases:
        try:
            result = call_connector_function(
                test_case["function"],
                test_case["params"]
            )

            if validate_result(result, test_case["expected"]):
                print(f"✅ {test_case['name']} passed")
            else:
                print(f"❌ {test_case['name']} failed validation")

        except Exception as e:
            print(f"❌ {test_case['name']} failed: {e}")
```

## Deployment Checklist

### Pre-Deployment

- [ ] Test all connector functions thoroughly
- [ ] Verify authentication and permissions
- [ ] Set up monitoring and alerting
- [ ] Configure error handling and fallbacks
- [ ] Document connector usage and limitations
- [ ] Train users on assistant capabilities


### Post-Deployment

- [ ] Monitor initial usage and performance
- [ ] Address any issues or user feedback
- [ ] Optimize based on real-world usage patterns
- [ ] Update documentation as needed
- [ ] Plan for future enhancements


## Getting Help

### Resources

- [Connectors Overview](/docs/documentation/personal-connectors/overview) - Available connector types
- [Authentication Guide](/docs/documentation/personal-connectors/authentication) - Set up connectors
- [Billing Information](/docs/documentation/personal-connectors/billing) - Cost management
- [API Reference](/docs/api-reference/personal-connectors/list) - Technical docs


### Support

- **Technical Issues**: support@aitronos.com
- **Billing Questions**: billing@aitronos.com
- **Feature Requests**: feedback@aitronos.com
- **Documentation**: docs@aitronos.com


For urgent issues, use the live chat in [Freddy Hub](https://freddy-hub.aitronos.com).