feat: add optional You.com search integration

[mouse-value-add]

Summary

Adds You.com as a primary web search provider for ATOM agents, with automatic fallback to Tavily. This integration follows the existing provider pattern and maintains full backward compatibility.

Why You.com for ATOM?

You.com provides superior search capabilities for AI agents:

• Real-time web results with current information
• AI-powered summaries and contextual answers
• High-quality citations for reliable sourcing
• Research-focused results ideal for agent workflows

Integration Details

Clean Architecture

• Integrates with existing BYOK system for tenant-specific API keys
• Follows the same pattern as Tavily integration in mcp_service.py
• Uses existing provider configuration system
• No changes to default behavior for existing users

Configuration Options

# Platform-wide (environment variable)
YDC_API_KEY=your_api_key

# Per-tenant (BYOK system)
# Settings > AI Intelligence (BYOK) > Add youcom provider

Priority Order

1. Tenant-specific You.com key (BYOK)
2. Platform You.com key (YDC_API_KEY env var)
3. Tenant-specific Tavily key (BYOK fallback)
4. Platform Tavily key (TAVILY_API_KEY env var)

Implementation

• Modified: backend/integrations/mcp_service.py - Added You.com search with fallback logic
• Modified: backend/api/byok_routes.py - Added You.com to BYOK provider list
• Modified: backend/core/byok_endpoints.py - Added You.com to valid providers
• Modified: .env.example files - Added YDC_API_KEY configuration examples
• Added: docs/integrations/youcom-search.md - Comprehensive setup/troubleshooting guide

Validation

✅ All syntax checks pass
✅ Follows existing Tavily pattern exactly
✅ BYOK provider properly configured
✅ Environment variables documented
✅ Comprehensive documentation included
✅ No breaking changes for existing users

Usage Example

# Automatic usage through existing web search
result = await mcp_service.web_search("AI research trends 2024")

# Response includes provider transparency  
print(result["provider"])  # "you.com" or "tavily"
print(result["answer"])    # AI-generated summary
print(result["results"])  # Cited web results

Fallback Behavior

• If You.com API fails → automatically tries Tavily
• If no API keys configured → clear error message with setup instructions
• Existing Tavily-only setups continue working unchanged

Testing

• Syntax validation passes on all modified files
• Integration tested against ATOM's existing patterns
• Validation script included: validate_youcom_integration.py
• Follows contributor guidelines in CONTRIBUTING.md

Related Issue

Tracking issue: youdotcom-oss/integration-tracking#179

Happy to adjust the integration approach if you prefer a different abstraction or have specific requirements for the provider system!