feat: add optional You.com search integration

docs/providers/youcom-provider.md

@@ -0,0 +1,246 @@
+# You.com Provider Integration
+
+The YouCom provider integrates You.com's web search and research capabilities into AgentOS, offering agents access to real-time web information, news search, and content extraction.
+
+## Overview
+
+Unlike traditional LLM providers, YouCom specializes in:
+- **Real-time web search** with source URLs and snippets
+- **News search** with timestamps and publication metadata  
+- **Content extraction** from URLs
+- **Research synthesis** with citations
+
+The provider supports both keyless (free tier) and authenticated operation modes.
+
+## Quick Start
+
+```typescript
+import { agent } from '@framers/agentos';
+
+// Basic usage with keyless access
+const researcher = agent({
+  provider: 'youcom',
+  instructions: 'You are a research assistant with access to current web information.',
+});
+
+const session = researcher.session('research-1');
+await session.send('What are the latest developments in AI agent frameworks?');
+```
+
+## Authentication
+
+### Keyless Mode (Default)
+- **100 free searches per day per IP**
+- No API key required
+- Automatic rate limiting
+- Perfect for development and evaluation
+
+### Authenticated Mode  
+Set your You.com API key for higher quotas and enhanced features:
+
+```bash
+export YDC_API_KEY="your_api_key_here"
+```
+
+Get your API key at [you.com/platform/api-keys](https://you.com/platform/api-keys).
+
+Alternative environment variable (legacy support):
+```bash
+export YOUCOM_API_KEY="your_api_key_here"
+```
+
+### Custom Configuration
+
+```typescript
+const agent = agent({
+  provider: 'youcom',
+  providerConfig: {
+    apiKey: 'your-key',
+    searchApiUrl: 'https://api.you.com/v1/agents/search', // default
+    mcpServerUrl: 'https://api.you.com/mcp', // for future MCP integration
+    debug: true
+  }
+});
+```
+
+## Available Models
+
+| Model ID | Description | Use Case |
+|----------|-------------|----------|
+| `youcom-search` | Web search with snippets | General web search queries |
+| `youcom-news` | News-focused search | Recent news and current events |
+
+## Direct Search API
+
+Access You.com search functionality directly:
+
+```typescript
+const provider = new YouComProvider();
+await provider.initialize({ apiKey: 'optional' });
+
+// Web search
+const results = await provider.search('TypeScript frameworks', {
+  count: 5,
+  type: 'web'
+});
+
+// News search  
+const news = await provider.search('AI developments', {
+  count: 3,
+  type: 'news'
+});
+```
+
+## Response Format
+
+### Web Search Results
+```typescript
+{
+  web: [
+    {
+      title: "Page title",
+      url: "https://example.com",
+      snippet: "Relevant excerpt from the page..."
+    }
+  ]
+}
+```
+
+### News Search Results  
+```typescript
+{
+  news: [
+    {
+      title: "Article title",
+      url: "https://news.example.com/article",
+      snippet: "Article excerpt...",
+      published_at: "2026-07-26T10:00:00Z"
+    }
+  ]
+}
+```
+
+## Error Handling
+
+The provider handles common error scenarios gracefully:
+
+- **Rate limiting (429)**: Returns helpful message about API key benefits
+- **Network errors**: Fail-safe with informative error messages  
+- **Invalid queries**: Validation with suggestion prompts
+- **Quota exceeded**: Clear indication of limits and upgrade paths
+
+```typescript
+try {
+  const results = await provider.search('query');
+} catch (error) {
+  if (error.message.includes('rate limit')) {
+    console.log('Consider using an API key for higher quotas');
+  }
+}
+```
+
+## Health Monitoring
+
+Check provider connectivity and configuration:
+
+```typescript
+const health = await provider.checkHealth();
+console.log('Healthy:', health.isHealthy);
+console.log('API Key configured:', health.details.apiKeyConfigured);
+```
+
+## Integration with AgentOS Tools
+
+The YouCom provider exposes search capabilities through AgentOS's tool system:
+
+```typescript
+const agent = agent({
+  provider: 'youcom',
+  tools: ['search'], // Enables search tool access
+  instructions: 'Use search when you need current information'
+});
+```
+
+## MCP Server Integration (Future)
+
+YouCom provider is designed for future integration with You.com's MCP server at `https://api.you.com/mcp`, which will provide:
+- `you-search` tool for web search
+- `you-contents` tool for URL content extraction  
+- `you-research` tool for research synthesis
+
+## Limitations
+
+- **No LLM generation**: YouCom focuses on search/tools, not text generation
+- **No embeddings**: Use other providers for embedding models
+- **No streaming**: Search results are returned as complete responses
+- **Rate limits**: Keyless tier has daily quotas (overcome with API key)
+
+## Provider Registry
+
+YouCom is automatically registered in AgentOS's provider system:
+
+```typescript
+// Auto-detection via environment variables
+// Priority: YDC_API_KEY > YOUCOM_API_KEY
+
+const config = {
+  providers: [
+    {
+      providerId: 'youcom',
+      enabled: true,
+      config: {
+        apiKey: process.env.YDC_API_KEY,
+        debug: false
+      }
+    }
+  ]
+};
+```
+
+## Best Practices
+
+1. **Use for current information**: YouCom excels at real-time web data
+2. **Combine with LLM providers**: Use YouCom for search, other providers for generation  
+3. **Cache results**: Avoid repeated identical searches
+4. **Respect rate limits**: Monitor quota usage in production
+5. **Cite sources**: Always include URLs in agent responses
+
+## Examples
+
+See `examples/youcom-search-example.mjs` for a complete working example demonstrating:
+- Agent configuration with YouCom provider
+- Multiple search query types
+- Direct API access
+- Error handling patterns
+- Configuration examples
+
+## Troubleshooting
+
+### "Provider not initialized" 
+- Ensure `initialize()` is called before use
+- Check network connectivity
+
+### "Rate limit exceeded"
+- Set `YDC_API_KEY` environment variable  
+- Implement request throttling
+- Consider caching search results
+
+### "Search API connectivity test failed"
+- Check internet connection
+- Verify You.com API endpoint accessibility
+- Review firewall/proxy settings
+
+### Integration Issues
+- Confirm YouCom is registered in `AIModelProviderManager`
+- Check provider configuration in AgentOS config
+- Enable debug logging: `debug: true`
+
+## Contributing
+
+YouCom provider follows AgentOS provider standards:
+- Implements full `IProvider` interface
+- Comprehensive error handling
+- Unit test coverage
+- Documentation and examples
+
+See [Provider Integration Guide](../contributing/new-provider.md) for details.

examples/youcom-search-example.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview YouCom Provider Example - Demonstrates You.com integration with AgentOS
+ * 
+ * This example shows how to use AgentOS with the YouCom provider for web search capabilities.
+ * The YouCom provider offers both keyless (free tier) and authenticated search access.
+ * 
+ * Usage:
+ *   node examples/youcom-search-example.mjs
+ *   
+ * Environment variables:
+ *   YDC_API_KEY - Optional You.com API key for authenticated access
+ *   YOUCOM_API_KEY - Alternative env var (fallback for legacy setups)
+ */
+
+import { agent } from '@framers/agentos';
+
+async function runYouComExample() {
+  console.log('🔍 YouCom Provider Example - Web Search with AgentOS\n');
+
+  try {
+    // Create an agent using the YouCom provider
+    const searchAgent = agent({
+      provider: 'youcom',
+      instructions: `You are a research assistant with access to current web information through You.com search.
+
+When users ask questions that require current information, use your search capabilities to find relevant results.
+Always cite your sources with URLs and provide a balanced view from multiple sources when possible.`,
+      tools: ['search'], // YouCom provider exposes search as a core capability
+      memory: { types: ['episodic'], working: { enabled: true } },
+    });
+
+    const session = searchAgent.session('youcom-demo');
+
+    console.log('Creating agent session with YouCom provider...');
+
+    // Example queries demonstrating different search capabilities
+    const queries = [
+      "What are the latest developments in AI agent frameworks?",
+      "Find recent news about TypeScript 5.7 features",
+      "Search for information about MCP (Model Context Protocol) adoption"
+    ];
+
+    for (const query of queries) {
+      console.log(`\n📋 Query: ${query}`);
+      console.log('🔄 Searching...\n');
+
+      try {
+        const response = await session.send(query);
+        console.log(`📖 Response:\n${response}\n`);
+        console.log('─'.repeat(80));
+      } catch (error) {
+        console.error(`❌ Error processing query: ${error.message}`);
+
+        if (error.message.includes('rate limit')) {
+          console.log('💡 Tip: Set YDC_API_KEY environment variable for higher search quotas');
+        }
+      }
+    }
+
+    // Demonstrate direct search API access
+    console.log('\n🔧 Direct YouCom Search API Example:\n');
+
+    const provider = searchAgent.provider; // Access the YouCom provider directly
+    if (provider && typeof provider.search === 'function') {
+      try {
+        const searchResult = await provider.search('AgentOS framework features', { count: 3 });
+
+        console.log('Direct search results:');
+        if (searchResult.web) {
+          searchResult.web.forEach((result, index) => {
+            console.log(`${index + 1}. ${result.title}`);
+            console.log(`   ${result.url}`);
+            console.log(`   ${result.snippet}\n`);
+          });
+        }
+      } catch (error) {
+        console.log(`Direct search failed: ${error.message}`);
+      }
+    }
+
+  } catch (error) {
+    console.error('❌ Failed to initialize YouCom provider:', error.message);
+
+    if (error.message.includes('not initialized')) {
+      console.log('\n💡 Troubleshooting:');
+      console.log('   - Make sure you have network connectivity');
+      console.log('   - For higher quotas, set YDC_API_KEY environment variable');
+      console.log('   - Check https://you.com/platform/api-keys for API keys');
+    }
+  }
+}
+
+// Configuration examples for different authentication modes
+function printConfigurationExamples() {
+  console.log('\n📚 Configuration Examples:\n');
+
+  console.log('1. Keyless mode (100 free searches/day per IP):');
+  console.log('   No configuration needed - just use provider: "youcom"\n');
+
+  console.log('2. Authenticated mode (higher quotas):');
+  console.log('   export YDC_API_KEY="your-api-key-here"');
+  console.log('   # Get API keys at: https://you.com/platform/api-keys\n');
+
+  console.log('3. Custom configuration:');
+  console.log(`   const agent = agent({
+     provider: 'youcom',
+     providerConfig: {
+       apiKey: 'your-key',
+       debug: true
+     }
+   });\n`);
+}
+
+// Check if running directly vs imported
+if (import.meta.url === `file://${process.argv[1]}`) {
+  printConfigurationExamples();
+  runYouComExample().catch(console.error);
+}

pnpm-workspace.yaml

@@ -0,0 +1,13 @@
+allowBuilds:
+  '@matrix-org/matrix-sdk-crypto-nodejs': set this to true or false
+  '@whiskeysockets/baileys': set this to true or false
+  bcrypt: set this to true or false
+  better-sqlite3: set this to true or false
+  esbuild: set this to true or false
+  ffi-napi: set this to true or false
+  hnswlib-node: set this to true or false
+  onnxruntime-node: set this to true or false
+  protobufjs: set this to true or false
+  ref-napi: set this to true or false
+  sharp: set this to true or false
+  tesseract.js: set this to true or false