feat: add optional You.com search integration

[mouse-value-add]

What Changed

This PR adds You.com as an optional search provider to the Heurist Agent Framework's SearchClient system, following the existing provider abstraction pattern.

Why This Integration

You.com's search API provides high-quality web and news results that can enhance agent research capabilities. The integration adds value to the framework's existing search functionality without disrupting current usage patterns.

Implementation Details

• New Provider: Added YouComClient implementing BaseSearchClient interface
• Unified Interface: Integrates seamlessly with existing SearchClient('youcom') usage
• Dual Mode Support: Works with API key authentication or keyless (100 free searches/day)
• Standard Response Format: Returns results in the same format as other search providers
• Error Handling: Graceful fallback behavior for network/API issues

Files Added/Modified

• core/clients/search/youcom_client.py - New You.com search client implementation
• core/clients/search_client.py - Added 'youcom' to supported client types
• examples/youcom_search_demo.py - Demo script showing usage patterns
• YOUCOM_INTEGRATION.md - Comprehensive integration documentation

Usage Examples

Keyless Mode (100 free searches/day)

search_client = SearchClient('youcom')
results = await search_client.search('AI agent frameworks')

Authenticated Mode

search_client = SearchClient('youcom', api_key=os.getenv('YDC_API_KEY'))
results = await search_client.search('latest AI research')

Configuration

• Optional: YDC_API_KEY environment variable for authenticated access
• Fallback: Works without API key using You.com's free tier
• Rate Limiting: Built-in support for configurable request delays

Validation Performed

• ✅ Code follows existing SearchClient patterns and conventions
• ✅ Maintains backward compatibility (no breaking changes)
• ✅ Error handling tested (network timeouts, auth failures)
• ✅ Both authenticated and keyless modes validated
• ✅ Integration matches project's Python/async architecture
• ✅ Documentation includes setup and usage examples

Integration Points

This change integrates cleanly with:

• Existing agent workflows using SearchClient
• Research workflows that need web search capabilities
• Multi-provider search strategies (can use alongside Exa, Firecrawl, DuckDuckGo)

The integration is optional - existing code continues to work unchanged. Users can opt into You.com search by simply changing the client_type parameter.

---

Tracking Issue: youdotcom-oss/integration-tracking#189