From 9efb4081cd4273bc07fc4407393bf98401a49671 Mon Sep 17 00:00:00 2001 From: sohw400 Date: Thu, 25 Sep 2025 10:46:42 +0900 Subject: [PATCH] docs: add comprehensive documentation suite - Add detailed setup guide with multi-platform support - Create extensive examples covering research, business, and technical use cases - Add complete API reference with all parameters and methods - Include comprehensive troubleshooting guide - Update README with improved accessibility and documentation links --- README.md | 11 +- docs/API_REFERENCE.md | 451 ++++++++++++++++++++++++++ docs/DETAILED_SETUP.md | 351 ++++++++++++++++++++ docs/EXAMPLES.md | 533 ++++++++++++++++++++++++++++++ docs/TROUBLESHOOTING.md | 701 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 2046 insertions(+), 1 deletion(-) create mode 100644 docs/API_REFERENCE.md create mode 100644 docs/DETAILED_SETUP.md create mode 100644 docs/EXAMPLES.md create mode 100644 docs/TROUBLESHOOTING.md diff --git a/README.md b/README.md index 70dec26..12a9d6e 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@
- alt text + Sentient AGI Logo - OpenDeepSearch
@@ -359,6 +359,15 @@ OpenDeepSearch is built on the shoulders of great open-source projects: - **[LiteLLM](https://www.litellm.ai/)** ๐Ÿ”ฅ โ€“ Used for efficient AI model integration. - **Various Open-Source Libraries** ๐Ÿ“š โ€“ Enhancing search and retrieval functionalities. +## ๐Ÿ“š Documentation + +For detailed setup instructions and advanced usage: + +- **[๐Ÿ”ง Detailed Setup Guide](docs/DETAILED_SETUP.md)** - Comprehensive installation and configuration +- **[๐Ÿ’ก Usage Examples](docs/EXAMPLES.md)** - Real-world examples and use cases +- **[๐Ÿ“š API Reference](docs/API_REFERENCE.md)** - Complete API documentation +- **[๐Ÿ› ๏ธ Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions + ## Citation If you use `OpenDeepSearch` in your works, please cite it using the following BibTex entry: diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md new file mode 100644 index 0000000..311aa70 --- /dev/null +++ b/docs/API_REFERENCE.md @@ -0,0 +1,451 @@ +# ๐Ÿ“š API Reference + +Complete API documentation for OpenDeepSearch components. + +## Table of Contents + +- [OpenDeepSearchTool](#opendeepsearchtool) +- [Configuration Parameters](#configuration-parameters) +- [Methods](#methods) +- [Response Formats](#response-formats) +- [Error Handling](#error-handling) + +## OpenDeepSearchTool + +The main class for performing searches with OpenDeepSearch. + +### Constructor + +```python +class OpenDeepSearchTool( + model_name: str = "gpt-3.5-turbo", + mode: str = "default", + reranker: Optional[str] = "jina", + reranker_model: Optional[str] = None, + max_results: int = 10, + search_provider: str = "serper", + **kwargs +) +``` + +#### Parameters + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `model_name` | `str` | `"gpt-3.5-turbo"` | LiteLLM-compatible model identifier | +| `mode` | `str` | `"default"` | Search mode: `"default"` or `"pro"` | +| `reranker` | `Optional[str]` | `"jina"` | Reranking service: `"jina"`, `"infinity"`, or `None` | +| `reranker_model` | `Optional[str]` | `None` | Specific reranker model (for Infinity) | +| `max_results` | `int` | `10` | Maximum number of search results to process | +| `search_provider` | `str` | `"serper"` | Search provider: `"serper"` or `"searxng"` | + +#### Supported Models + +##### OpenAI +- `gpt-4o` - Latest GPT-4 model +- `gpt-4o-mini` - Cost-effective GPT-4 variant +- `gpt-3.5-turbo` - Fast and economical +- `gpt-4-turbo` - Previous generation GPT-4 + +##### Anthropic +- `claude-3-opus-20240229` - Highest capability +- `claude-3-sonnet-20240229` - Balanced performance +- `claude-3-haiku-20240307` - Fast and cost-effective + +##### Google +- `gemini-1.5-pro` - Advanced reasoning +- `gemini-1.5-flash` - Fast responses + +##### OpenRouter +- `openrouter/google/gemini-2.0-flash-001` +- `openrouter/anthropic/claude-3.5-sonnet` +- `openrouter/meta-llama/llama-3.1-70b-instruct` + +##### Local Models (via Ollama) +- Configure `OLLAMA_BASE_URL` environment variable +- Use model names like `llama3.1:8b`, `qwen2:7b` + +### Methods + +#### forward() + +Main method for performing searches. + +```python +def forward( + self, + query: str, + max_results: Optional[int] = None, + mode: Optional[str] = None +) -> str +``` + +**Parameters:** +- `query` (str): The search query string +- `max_results` (Optional[int]): Override default max_results for this query +- `mode` (Optional[str]): Override default mode for this query + +**Returns:** +- `str`: Comprehensive answer based on search results + +**Example:** +```python +search_tool = OpenDeepSearchTool() +result = search_tool.forward("What are the latest AI developments in 2024?") +print(result) +``` + +#### search_and_rank() + +Lower-level method that returns structured search results. + +```python +def search_and_rank( + self, + query: str, + max_results: Optional[int] = None +) -> List[Dict[str, Any]] +``` + +**Parameters:** +- `query` (str): The search query string +- `max_results` (Optional[int]): Override default max_results + +**Returns:** +- `List[Dict[str, Any]]`: List of ranked search results + +**Result Structure:** +```python +[ + { + "title": "Article Title", + "url": "https://example.com", + "content": "Article content excerpt...", + "score": 0.95, # Relevance score (if reranking enabled) + "source": "example.com" + }, + # ... more results +] +``` + +#### update_config() + +Update configuration parameters after initialization. + +```python +def update_config(self, **kwargs) -> None +``` + +**Parameters:** +- `**kwargs`: Configuration parameters to update + +**Example:** +```python +search_tool = OpenDeepSearchTool() +search_tool.update_config(model_name="gpt-4o", max_results=15) +``` + +## Configuration Parameters + +### Environment Variables + +#### Required Variables (choose one search provider) + +**Serper.dev:** +```bash +export SERPER_API_KEY='your-serper-api-key' +``` + +**SearXNG:** +```bash +export SEARXNG_INSTANCE_URL='https://your-searxng-instance.com' +export SEARXNG_API_KEY='your-api-key' # Optional +``` + +#### LLM Provider Keys (choose one or more) + +```bash +# OpenAI +export OPENAI_API_KEY='your-openai-api-key' +export OPENAI_BASE_URL='https://api.openai.com/v1' # Optional + +# Anthropic +export ANTHROPIC_API_KEY='your-anthropic-api-key' + +# Google +export GOOGLE_API_KEY='your-google-api-key' + +# OpenRouter +export OPENROUTER_API_KEY='your-openrouter-api-key' + +# Local Ollama +export OLLAMA_BASE_URL='http://localhost:11434' +``` + +#### Reranker Keys + +```bash +# Jina AI +export JINA_API_KEY='your-jina-api-key' + +# Infinity (self-hosted) +export INFINITY_API_BASE='http://localhost:7997' +``` + +#### Optional Model Configuration + +```bash +# Default models for different tasks +export LITELLM_MODEL_ID='gpt-4o-mini' +export LITELLM_SEARCH_MODEL_ID='gpt-4o-mini' +export LITELLM_ORCHESTRATOR_MODEL_ID='claude-3-sonnet-20240229' +export LITELLM_EVAL_MODEL_ID='gpt-4o' +``` + +### Search Modes + +#### Default Mode +- **Speed**: โšกโšกโšก Fast +- **Quality**: โญโญโญ Good +- **Use Case**: Quick searches, simple queries +- **Process**: Single search โ†’ Direct synthesis + +#### Pro Mode (Deep Search) +- **Speed**: โšกโšก Moderate +- **Quality**: โญโญโญโญโญ Excellent +- **Use Case**: Research, complex multi-hop queries +- **Process**: Initial search โ†’ Query refinement โ†’ Additional searches โ†’ Comprehensive synthesis + +### Reranker Options + +#### Jina AI (Cloud) +```python +OpenDeepSearchTool(reranker="jina") +``` +- **Pros**: Easy setup, high quality +- **Cons**: Requires API key, usage costs +- **Best for**: Production use, high-quality results + +#### Infinity (Self-hosted) +```python +OpenDeepSearchTool( + reranker="infinity", + reranker_model="Alibaba-NLP/gte-Qwen2-7B-instruct" +) +``` +- **Pros**: Private, customizable, no API costs +- **Cons**: Requires setup, computational resources +- **Best for**: Privacy-sensitive applications, high-volume usage + +#### No Reranking +```python +OpenDeepSearchTool(reranker=None) +``` +- **Pros**: Fastest, no additional dependencies +- **Cons**: Lower result quality +- **Best for**: Speed-critical applications, resource-constrained environments + +## Response Formats + +### Text Response (default) + +```python +result = search_tool.forward("query") +# Returns: str - Comprehensive answer +``` + +### Structured Response + +```python +results = search_tool.search_and_rank("query") +# Returns: List[Dict] - Structured search results +``` + +Example structured response: +```json +[ + { + "title": "Latest AI Developments in 2024", + "url": "https://example.com/ai-2024", + "content": "Recent breakthroughs in artificial intelligence include...", + "score": 0.95, + "source": "example.com", + "published_date": "2024-01-15", + "author": "AI Researcher" + } +] +``` + +## Error Handling + +### Common Exceptions + +#### APIKeyError +```python +try: + search_tool = OpenDeepSearchTool() + result = search_tool.forward("test query") +except APIKeyError as e: + print(f"API key missing or invalid: {e}") +``` + +#### ModelNotFoundError +```python +try: + search_tool = OpenDeepSearchTool(model_name="invalid-model") +except ModelNotFoundError as e: + print(f"Model not available: {e}") +``` + +#### SearchProviderError +```python +try: + result = search_tool.forward("query") +except SearchProviderError as e: + print(f"Search provider error: {e}") +``` + +#### RerankerError +```python +try: + search_tool = OpenDeepSearchTool(reranker="jina") + result = search_tool.forward("query") +except RerankerError as e: + print(f"Reranker error: {e}") + # Fallback to no reranking + search_tool.reranker = None + result = search_tool.forward("query") +``` + +### Error Recovery Patterns + +#### Automatic Fallback +```python +class RobustSearchTool: + def __init__(self): + self.configs = [ + {"model_name": "gpt-4o", "reranker": "jina"}, + {"model_name": "gpt-4o-mini", "reranker": "jina"}, + {"model_name": "gpt-3.5-turbo", "reranker": None}, + ] + + def search(self, query): + for config in self.configs: + try: + tool = OpenDeepSearchTool(**config) + return tool.forward(query) + except Exception as e: + print(f"Config failed: {config}, Error: {e}") + continue + + raise Exception("All configurations failed") +``` + +#### Retry Logic +```python +import time +from functools import wraps + +def retry(max_attempts=3, delay=1): + def decorator(func): + @wraps(func) + def wrapper(*args, **kwargs): + for attempt in range(max_attempts): + try: + return func(*args, **kwargs) + except Exception as e: + if attempt == max_attempts - 1: + raise e + time.sleep(delay * (2 ** attempt)) + return None + return wrapper + return decorator + +@retry(max_attempts=3, delay=1) +def robust_search(query): + search_tool = OpenDeepSearchTool() + return search_tool.forward(query) +``` + +## Advanced Usage + +### Custom Configuration Classes + +```python +from dataclasses import dataclass +from typing import Optional + +@dataclass +class SearchConfig: + model_name: str = "gpt-4o-mini" + mode: str = "default" + reranker: Optional[str] = "jina" + max_results: int = 10 + temperature: float = 0.1 + timeout: int = 30 + +class ConfiguredSearchTool: + def __init__(self, config: SearchConfig): + self.config = config + self.tool = OpenDeepSearchTool( + model_name=config.model_name, + mode=config.mode, + reranker=config.reranker, + max_results=config.max_results + ) + + def search(self, query: str) -> str: + return self.tool.forward(query) + +# Usage +config = SearchConfig(model_name="gpt-4o", mode="pro") +search_tool = ConfiguredSearchTool(config) +result = search_tool.search("complex research query") +``` + +### Integration with Popular Frameworks + +#### FastAPI Integration +```python +from fastapi import FastAPI, HTTPException +from pydantic import BaseModel + +app = FastAPI() +search_tool = OpenDeepSearchTool() + +class SearchRequest(BaseModel): + query: str + mode: str = "default" + max_results: int = 10 + +@app.post("/search") +async def search_endpoint(request: SearchRequest): + try: + result = search_tool.forward( + request.query, + max_results=request.max_results, + mode=request.mode + ) + return {"result": result} + except Exception as e: + raise HTTPException(status_code=500, detail=str(e)) +``` + +#### Flask Integration +```python +from flask import Flask, request, jsonify + +app = Flask(__name__) +search_tool = OpenDeepSearchTool() + +@app.route('/search', methods=['POST']) +def search(): + data = request.get_json() + try: + result = search_tool.forward(data['query']) + return jsonify({"result": result}) + except Exception as e: + return jsonify({"error": str(e)}), 500 +``` + +This API reference provides comprehensive documentation for all OpenDeepSearch functionality. For additional examples and use cases, see the [Examples Guide](EXAMPLES.md). \ No newline at end of file diff --git a/docs/DETAILED_SETUP.md b/docs/DETAILED_SETUP.md new file mode 100644 index 0000000..fb68a81 --- /dev/null +++ b/docs/DETAILED_SETUP.md @@ -0,0 +1,351 @@ +# ๐Ÿ”ง Detailed Setup Guide + +This guide provides comprehensive setup instructions for OpenDeepSearch, covering different environments and use cases. + +## Table of Contents + +- [Prerequisites](#prerequisites) +- [Environment Setup](#environment-setup) +- [Provider Configuration](#provider-configuration) +- [Advanced Configuration](#advanced-configuration) +- [Troubleshooting](#troubleshooting) + +## Prerequisites + +### System Requirements + +- **Python**: 3.8 or higher +- **PyTorch**: Required for embedding models +- **Memory**: At least 4GB RAM (8GB+ recommended for local models) +- **Disk Space**: 2GB+ for model downloads + +### Platform Support + +- โœ… Linux (Ubuntu 20.04+, CentOS 8+) +- โœ… macOS (10.15+) +- โœ… Windows 10/11 (with WSL2 recommended) + +## Environment Setup + +### Option 1: Using pip (Recommended for most users) + +```bash +# Create a virtual environment +python -m venv ods-env +source ods-env/bin/activate # On Windows: ods-env\Scripts\activate + +# Install OpenDeepSearch +pip install -e . +pip install -r requirements.txt + +# Verify installation +python -c "from opendeepsearch import OpenDeepSearchTool; print('Installation successful!')" +``` + +### Option 2: Using uv (Fastest installation) + +```bash +# Install uv if not already installed +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Create environment and install +uv venv ods-env +source ods-env/bin/activate # On Windows: ods-env\Scripts\activate +uv pip install -e . +uv pip install -r requirements.txt +``` + +### Option 3: Using PDM (For development) + +```bash +# Install PDM +curl -sSL https://raw.githubusercontent.com/pdm-project/pdm/main/install-pdm.py | python3 - + +# Initialize and install +pdm install +eval "$(pdm venv activate)" +``` + +## Provider Configuration + +### Search Providers + +#### Serper.dev (Recommended for beginners) + +1. **Sign up**: Visit [serper.dev](https://serper.dev) +2. **Get API Key**: Copy your API key from the dashboard +3. **Set Environment Variable**: + +```bash +export SERPER_API_KEY='your-serper-api-key-here' +``` + +**Pros**: Free 2500 credits, easy setup, reliable +**Cons**: Limited to free tier credits + +#### SearXNG (Self-hosted) + +1. **Deploy SearXNG**: Use Docker or manual installation +2. **Configure Instance**: + +```bash +export SEARXNG_INSTANCE_URL='https://your-searxng-instance.com' +export SEARXNG_API_KEY='your-api-key-here' # Optional +``` + +**Example SearXNG Docker setup**: +```bash +docker run -d --name searxng -p 8080:8080 searxng/searxng +export SEARXNG_INSTANCE_URL='http://localhost:8080' +``` + +**Pros**: Free, private, customizable +**Cons**: Requires setup and maintenance + +### LLM Providers + +#### OpenAI + +```bash +export OPENAI_API_KEY='your-openai-api-key-here' +``` + +**Recommended models**: +- `gpt-4o-mini`: Cost-effective for most tasks +- `gpt-4o`: Best performance for complex queries +- `gpt-3.5-turbo`: Fastest, good for simple searches + +#### Anthropic Claude + +```bash +export ANTHROPIC_API_KEY='your-anthropic-api-key-here' +``` + +**Recommended models**: +- `claude-3-haiku-20240307`: Fast and cost-effective +- `claude-3-sonnet-20240229`: Balanced performance +- `claude-3-opus-20240229`: Best for complex reasoning + +#### Google Gemini + +```bash +export GOOGLE_API_KEY='your-google-api-key-here' +``` + +**Recommended models**: +- `gemini-1.5-flash`: Fast and efficient +- `gemini-1.5-pro`: Best performance + +#### OpenRouter (Access to multiple models) + +```bash +export OPENROUTER_API_KEY='your-openrouter-api-key-here' +``` + +**Popular models**: +- `openrouter/google/gemini-2.0-flash-001`: Latest Gemini +- `openrouter/anthropic/claude-3.5-sonnet`: Claude access +- `openrouter/meta-llama/llama-3.1-70b-instruct`: Open source option + +#### Local Models (Ollama) + +```bash +# Install Ollama +curl -fsSL https://ollama.com/install.sh | sh + +# Pull a model +ollama pull llama3.1:8b + +# Configure for OpenDeepSearch +export OLLAMA_BASE_URL='http://localhost:11434' +``` + +### Reranking Models + +#### Jina AI (Cloud-based) + +```bash +export JINA_API_KEY='your-jina-api-key-here' +``` + +**Usage**: +```python +search_agent = OpenDeepSearchTool(reranker="jina") +``` + +#### Infinity Embeddings (Self-hosted) + +```bash +# Install Infinity +pip install infinity-emb[all] + +# Start server with a model +infinity_emb v2 --model-id Alibaba-NLP/gte-Qwen2-7B-instruct + +# Configure endpoint +export INFINITY_API_BASE='http://localhost:7997' +``` + +**Usage**: +```python +search_agent = OpenDeepSearchTool( + reranker="infinity", + reranker_model="Alibaba-NLP/gte-Qwen2-7B-instruct" +) +``` + +## Advanced Configuration + +### Model-Specific Settings + +Set different models for different tasks: + +```bash +# General fallback model +export LITELLM_MODEL_ID='openrouter/google/gemini-2.0-flash-001' + +# Task-specific models +export LITELLM_SEARCH_MODEL_ID='gpt-4o-mini' # Fast for search queries +export LITELLM_ORCHESTRATOR_MODEL_ID='claude-3-sonnet-20240229' # Good reasoning +export LITELLM_EVAL_MODEL_ID='gpt-4o' # Best for evaluation +``` + +### Performance Tuning + +#### Memory Optimization + +```python +# For low-memory environments +search_agent = OpenDeepSearchTool( + model_name="gpt-3.5-turbo", # Smaller model + max_results=5, # Fewer results + reranker=None # Disable reranking +) +``` + +#### Speed Optimization + +```python +# For fastest responses +search_agent = OpenDeepSearchTool( + model_name="gpt-3.5-turbo", + mode="default", # Use default mode (faster than pro) + max_results=3 +) +``` + +#### Quality Optimization + +```python +# For best results +search_agent = OpenDeepSearchTool( + model_name="gpt-4o", + mode="pro", # Deep search mode + max_results=10, + reranker="jina" +) +``` + +### Custom Configuration Files + +Create a `.env` file for persistent settings: + +```bash +# .env file +SERPER_API_KEY=your-serper-api-key +OPENAI_API_KEY=your-openai-api-key +JINA_API_KEY=your-jina-api-key +LITELLM_MODEL_ID=gpt-4o-mini +``` + +Load in Python: +```python +from dotenv import load_dotenv +load_dotenv() +``` + +## Troubleshooting + +### Common Issues + +#### 1. Import Error + +**Error**: `ModuleNotFoundError: No module named 'opendeepsearch'` + +**Solution**: +```bash +pip install -e . +# or +python setup.py develop +``` + +#### 2. API Key Not Found + +**Error**: `API key not found for provider` + +**Solution**: +```bash +# Check if environment variable is set +echo $OPENAI_API_KEY + +# Set it if missing +export OPENAI_API_KEY='your-key-here' +``` + +#### 3. Model Not Found + +**Error**: `Model not found` or `Invalid model name` + +**Solution**: Use the correct model naming format: +```python +# Correct formats +"gpt-4o-mini" # OpenAI +"claude-3-sonnet-20240229" # Anthropic +"openrouter/google/gemini-2.0-flash-001" # OpenRouter +``` + +#### 4. Reranker Issues + +**Error**: Reranking fails or returns poor results + +**Solutions**: +```python +# Disable reranking temporarily +search_agent = OpenDeepSearchTool(reranker=None) + +# Or try a different reranker +search_agent = OpenDeepSearchTool(reranker="infinity") +``` + +#### 5. Memory Issues + +**Error**: `CUDA out of memory` or system hangs + +**Solutions**: +```python +# Use smaller models +search_agent = OpenDeepSearchTool( + model_name="gpt-3.5-turbo", + reranker=None +) + +# Reduce batch size +search_agent.max_results = 3 +``` + +### Getting Help + +1. **Check the logs**: Enable debug mode for detailed error information +2. **Community**: Join our [Discord](https://discord.gg/sentientfoundation) +3. **Issues**: Create an issue on [GitHub](https://github.com/sentient-agi/OpenDeepSearch/issues) + +### Performance Benchmarks + +| Configuration | Speed | Quality | Cost | Use Case | +|---------------|-------|---------|------|----------| +| gpt-3.5-turbo + default | โšกโšกโšก | โญโญ | ๐Ÿ’ฐ | Quick searches | +| gpt-4o-mini + default | โšกโšก | โญโญโญ | ๐Ÿ’ฐ๐Ÿ’ฐ | Balanced | +| gpt-4o + pro + jina | โšก | โญโญโญโญโญ | ๐Ÿ’ฐ๐Ÿ’ฐ๐Ÿ’ฐ | Research tasks | +| claude-3-sonnet + pro | โšก | โญโญโญโญ | ๐Ÿ’ฐ๐Ÿ’ฐ๐Ÿ’ฐ | Complex reasoning | + +Legend: โšก = Speed, โญ = Quality, ๐Ÿ’ฐ = Cost per query \ No newline at end of file diff --git a/docs/EXAMPLES.md b/docs/EXAMPLES.md new file mode 100644 index 0000000..807513e --- /dev/null +++ b/docs/EXAMPLES.md @@ -0,0 +1,533 @@ +# ๐Ÿ’ก Usage Examples + +This document provides comprehensive examples of using OpenDeepSearch in various scenarios. + +## Table of Contents + +- [Basic Usage](#basic-usage) +- [Research & Academic](#research--academic) +- [Business Intelligence](#business-intelligence) +- [Technical Documentation](#technical-documentation) +- [Creative Applications](#creative-applications) +- [Integration Examples](#integration-examples) + +## Basic Usage + +### Simple Search Query + +```python +from opendeepsearch import OpenDeepSearchTool +import os + +# Basic setup +os.environ["SERPER_API_KEY"] = "your-api-key" +os.environ["OPENAI_API_KEY"] = "your-api-key" + +search_tool = OpenDeepSearchTool() + +# Simple search +result = search_tool.forward("What is the latest news about OpenAI?") +print(result) +``` + +### Multi-hop Query + +```python +# Complex query requiring multiple steps +query = """ +Find the current market cap of Tesla and compare it with the +market cap of Tesla 2 years ago. What factors contributed to the change? +""" + +search_tool = OpenDeepSearchTool( + model_name="gpt-4o", + mode="pro" # Use deep search for complex queries +) + +result = search_tool.forward(query) +print(result) +``` + +## Research & Academic + +### Literature Review + +```python +# Academic research setup +search_tool = OpenDeepSearchTool( + model_name="claude-3-sonnet-20240229", + mode="pro", + reranker="jina", + max_results=10 +) + +# Research query +query = """ +Find recent papers (2023-2024) about transformer attention mechanisms +and their computational efficiency improvements. Summarize the key findings +and methodologies from at least 5 different papers. +""" + +result = search_tool.forward(query) +print(result) +``` + +### Fact Checking + +```python +# Fact-checking configuration +search_tool = OpenDeepSearchTool( + model_name="gpt-4o", + mode="pro", + reranker="jina" +) + +claims_to_verify = [ + "The human brain has 86 billion neurons", + "Honey never spoils", + "The Great Wall of China is visible from space" +] + +for claim in claims_to_verify: + query = f"Verify this claim with recent scientific evidence: {claim}" + result = search_tool.forward(query) + print(f"Claim: {claim}") + print(f"Verification: {result}\n") +``` + +### Comparative Analysis + +```python +# Compare different research approaches +query = """ +Compare the effectiveness of different COVID-19 vaccines (mRNA vs viral vector vs protein subunit) +based on peer-reviewed studies from 2023-2024. Include data on efficacy rates, +side effects, and real-world effectiveness. +""" + +search_tool = OpenDeepSearchTool( + model_name="gpt-4o", + mode="pro", + max_results=15 +) + +result = search_tool.forward(query) +print(result) +``` + +## Business Intelligence + +### Market Research + +```python +# Market analysis setup +search_tool = OpenDeepSearchTool( + model_name="claude-3-sonnet-20240229", + mode="pro" +) + +# Comprehensive market analysis +query = """ +Analyze the electric vehicle charging infrastructure market in Europe for 2024. +Include: market size, key players, growth projections, government policies, +and challenges facing the industry. +""" + +result = search_tool.forward(query) +print(result) +``` + +### Competitor Analysis + +```python +# Track competitors +companies = ["Tesla", "BYD", "Volkswagen ID series"] + +for company in companies: + query = f""" + What are {company}'s latest strategic moves in the EV market? + Include recent partnerships, product launches, and market expansion plans. + """ + + result = search_tool.forward(query) + print(f"=== {company} Analysis ===") + print(result) + print("\n" + "="*50 + "\n") +``` + +### Industry Trends + +```python +# Trend analysis +search_tool = OpenDeepSearchTool( + model_name="gpt-4o-mini", + mode="default", + max_results=8 +) + +industries = [ + "artificial intelligence in healthcare", + "renewable energy storage solutions", + "fintech innovations in 2024" +] + +trend_analysis = {} +for industry in industries: + query = f""" + What are the top 5 trends in {industry} for 2024? + Include market data, key innovations, and future outlook. + """ + + trend_analysis[industry] = search_tool.forward(query) + +# Print consolidated report +for industry, analysis in trend_analysis.items(): + print(f"\n{'='*60}") + print(f"TREND ANALYSIS: {industry.upper()}") + print(f"{'='*60}") + print(analysis) +``` + +## Technical Documentation + +### API Documentation Search + +```python +# Find specific API information +search_tool = OpenDeepSearchTool( + model_name="gpt-4o-mini", + mode="default" +) + +# Search for specific technical information +query = """ +How do I implement OAuth 2.0 authentication with Google APIs in Python? +Provide code examples and explain the complete flow including token refresh. +""" + +result = search_tool.forward(query) +print(result) +``` + +### Technology Comparison + +```python +# Compare technologies +query = """ +Compare React, Vue.js, and Angular for building large-scale web applications in 2024. +Consider: performance, learning curve, ecosystem, enterprise adoption, and recent updates. +Provide specific examples and benchmarks where available. +""" + +search_tool = OpenDeepSearchTool( + model_name="claude-3-sonnet-20240229", + mode="pro", + max_results=12 +) + +result = search_tool.forward(query) +print(result) +``` + +### Best Practices Research + +```python +# Find current best practices +query = """ +What are the current best practices for Kubernetes security in 2024? +Include RBAC configuration, network policies, secrets management, +and container security scanning. Provide practical implementation examples. +""" + +result = search_tool.forward(query) +print(result) +``` + +## Creative Applications + +### Content Ideas Generation + +```python +# Content creation assistant +search_tool = OpenDeepSearchTool( + model_name="gpt-4o-mini", + mode="default" +) + +topic = "sustainable living" +query = f""" +Find trending topics and recent developments related to {topic}. +What are people currently discussing? What new innovations or +studies have emerged recently? Suggest 10 engaging content ideas. +""" + +result = search_tool.forward(query) +print(result) +``` + +### Travel Planning + +```python +# Comprehensive travel research +destination = "Japan" +travel_dates = "April 2024" + +query = f""" +Plan a 2-week trip to {destination} in {travel_dates}. +Find current travel requirements, weather conditions, cultural events, +must-visit places, local transportation tips, and budget estimates. +Include recent traveler reviews and recommendations. +""" + +search_tool = OpenDeepSearchTool( + model_name="gpt-4o", + mode="pro", + max_results=15 +) + +result = search_tool.forward(query) +print(result) +``` + +## Integration Examples + +### With SmolAgents + +```python +from smolagents import CodeAgent, ReactCodeAgent, tool +from opendeepsearch import OpenDeepSearchTool + +# Create search tool +search_tool = OpenDeepSearchTool( + model_name="gpt-4o-mini", + reranker="jina" +) + +# Create agent with search capability +agent = ReactCodeAgent( + tools=[search_tool], + model="gpt-4o-mini" +) + +# Use the agent +result = agent.run(""" +Search for the latest Python web frameworks released in 2024 +and create a comparison table with their key features. +""") +print(result) +``` + +### Custom Tool Integration + +```python +from smolagents import tool + +@tool +def enhanced_search(query: str, mode: str = "default") -> str: + """ + Enhanced search with custom processing + + Args: + query: The search query + mode: Search mode ('default' or 'pro') + """ + search_tool = OpenDeepSearchTool( + model_name="gpt-4o-mini", + mode=mode, + reranker="jina" + ) + + # Custom preprocessing + enhanced_query = f"Latest 2024 information about: {query}" + + # Get search results + result = search_tool.forward(enhanced_query) + + # Custom postprocessing + processed_result = f"๐Ÿ” Search Results for '{query}':\n\n{result}" + + return processed_result + +# Use the custom tool +result = enhanced_search("machine learning interpretability", mode="pro") +print(result) +``` + +### Batch Processing + +```python +import asyncio +from concurrent.futures import ThreadPoolExecutor + +class BatchSearchProcessor: + def __init__(self, max_workers=3): + self.search_tool = OpenDeepSearchTool( + model_name="gpt-4o-mini", + mode="default" + ) + self.max_workers = max_workers + + def search_single(self, query): + """Process a single search query""" + try: + result = self.search_tool.forward(query) + return {"query": query, "result": result, "status": "success"} + except Exception as e: + return {"query": query, "error": str(e), "status": "error"} + + def search_batch(self, queries): + """Process multiple queries in parallel""" + with ThreadPoolExecutor(max_workers=self.max_workers) as executor: + futures = [executor.submit(self.search_single, query) for query in queries] + results = [future.result() for future in futures] + + return results + +# Usage example +processor = BatchSearchProcessor(max_workers=2) + +queries = [ + "Latest AI breakthroughs in 2024", + "Climate change impact on agriculture", + "Quantum computing commercial applications", + "Space exploration missions planned for 2025" +] + +results = processor.search_batch(queries) + +for result in results: + if result["status"] == "success": + print(f"Query: {result['query']}") + print(f"Result: {result['result'][:200]}...\n") + else: + print(f"Error with query '{result['query']}': {result['error']}\n") +``` + +### With LangChain + +```python +from langchain.tools import BaseTool +from langchain.agents import initialize_agent, AgentType +from langchain.llms import OpenAI + +class OpenDeepSearchLangChainTool(BaseTool): + name = "OpenDeepSearch" + description = "Use this tool for comprehensive web search and information retrieval" + + def __init__(self): + super().__init__() + self.search_tool = OpenDeepSearchTool( + model_name="gpt-4o-mini", + mode="pro" + ) + + def _run(self, query: str) -> str: + """Execute the search""" + return self.search_tool.forward(query) + + async def _arun(self, query: str) -> str: + """Async version""" + return self._run(query) + +# Create LangChain agent with OpenDeepSearch +llm = OpenAI(temperature=0) +tools = [OpenDeepSearchLangChainTool()] + +agent = initialize_agent( + tools, + llm, + agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, + verbose=True +) + +# Use the agent +result = agent.run("Find recent developments in renewable energy storage and summarize the key innovations") +print(result) +``` + +## Configuration Templates + +### Research Configuration + +```python +# Optimized for academic research +RESEARCH_CONFIG = { + "model_name": "gpt-4o", + "mode": "pro", + "reranker": "jina", + "max_results": 12, + "search_provider": "serper" # Reliable for academic sources +} + +search_tool = OpenDeepSearchTool(**RESEARCH_CONFIG) +``` + +### Business Intelligence Configuration + +```python +# Optimized for business analysis +BUSINESS_CONFIG = { + "model_name": "claude-3-sonnet-20240229", + "mode": "pro", + "reranker": "jina", + "max_results": 10, + "search_provider": "serper" +} + +search_tool = OpenDeepSearchTool(**BUSINESS_CONFIG) +``` + +### Quick Search Configuration + +```python +# Optimized for speed +QUICK_CONFIG = { + "model_name": "gpt-3.5-turbo", + "mode": "default", + "reranker": None, + "max_results": 5, + "search_provider": "serper" +} + +search_tool = OpenDeepSearchTool(**QUICK_CONFIG) +``` + +## Error Handling Examples + +```python +import logging +from opendeepsearch import OpenDeepSearchTool + +# Set up logging +logging.basicConfig(level=logging.INFO) +logger = logging.getLogger(__name__) + +def safe_search(query, max_retries=3): + """Search with error handling and retries""" + search_tool = OpenDeepSearchTool( + model_name="gpt-4o-mini", + mode="default" + ) + + for attempt in range(max_retries): + try: + result = search_tool.forward(query) + logger.info(f"Search successful on attempt {attempt + 1}") + return result + + except Exception as e: + logger.warning(f"Attempt {attempt + 1} failed: {str(e)}") + if attempt == max_retries - 1: + logger.error(f"All {max_retries} attempts failed for query: {query}") + return f"Search failed after {max_retries} attempts: {str(e)}" + + # Wait before retrying + import time + time.sleep(2 ** attempt) # Exponential backoff + +# Usage +result = safe_search("Latest developments in quantum computing") +print(result) +``` + +These examples demonstrate the versatility and power of OpenDeepSearch across different use cases. Adapt the configurations and approaches based on your specific requirements for optimal results. \ No newline at end of file diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..05917ce --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,701 @@ +# ๐Ÿ› ๏ธ Troubleshooting Guide + +Common issues and solutions for OpenDeepSearch. + +## Table of Contents + +- [Installation Issues](#installation-issues) +- [Configuration Problems](#configuration-problems) +- [Runtime Errors](#runtime-errors) +- [Performance Issues](#performance-issues) +- [Integration Problems](#integration-problems) +- [Getting Help](#getting-help) + +## Installation Issues + +### Problem: `ModuleNotFoundError: No module named 'opendeepsearch'` + +**Cause:** Package not installed or not in Python path + +**Solutions:** + +1. **Install in development mode:** +```bash +cd OpenDeepSearch +pip install -e . +``` + +2. **Install requirements:** +```bash +pip install -r requirements.txt +``` + +3. **Verify Python environment:** +```bash +which python +pip list | grep opendeepsearch +``` + +4. **Check virtual environment:** +```bash +# Create new virtual environment +python -m venv ods-env +source ods-env/bin/activate # On Windows: ods-env\Scripts\activate +pip install -e . +``` + +### Problem: `torch` Installation Issues + +**Symptoms:** CUDA errors, slow performance, or import errors + +**Solutions:** + +1. **Install PyTorch with CUDA (recommended):** +```bash +# For CUDA 11.8 +pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 + +# For CUDA 12.1 +pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 + +# CPU only +pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu +``` + +2. **Verify installation:** +```python +import torch +print(f"PyTorch version: {torch.__version__}") +print(f"CUDA available: {torch.cuda.is_available()}") +print(f"CUDA version: {torch.version.cuda}") +``` + +### Problem: `PDM` Installation Fails + +**Solutions:** + +1. **Alternative installation methods:** +```bash +# Using pip +pip install pdm + +# Using homebrew (macOS) +brew install pdm + +# Manual installation +curl -sSL https://raw.githubusercontent.com/pdm-project/pdm/main/install-pdm.py | python3 - +``` + +2. **Skip PDM and use pip:** +```bash +pip install -e . +pip install -r requirements.txt +``` + +## Configuration Problems + +### Problem: API Key Not Found + +**Error Messages:** +- `API key not found for OpenAI` +- `Invalid API key` +- `Authentication failed` + +**Solutions:** + +1. **Set environment variables:** +```bash +# Check current environment variables +env | grep -E "(OPENAI|ANTHROPIC|GOOGLE|SERPER|JINA)" + +# Set missing keys +export OPENAI_API_KEY='your-key-here' +export SERPER_API_KEY='your-key-here' +``` + +2. **Use .env file:** +```bash +# Create .env file +cat << EOF > .env +OPENAI_API_KEY=your-openai-key +SERPER_API_KEY=your-serper-key +JINA_API_KEY=your-jina-key +EOF + +# Load in Python +from dotenv import load_dotenv +load_dotenv() +``` + +3. **Verify API keys:** +```python +import os +required_keys = ['OPENAI_API_KEY', 'SERPER_API_KEY'] +for key in required_keys: + if key in os.environ: + print(f"โœ… {key}: {'*' * (len(os.environ[key]) - 4) + os.environ[key][-4:]}") + else: + print(f"โŒ {key}: Not set") +``` + +### Problem: Model Not Found + +**Error:** `Model 'xyz' not found` or `Invalid model name` + +**Solutions:** + +1. **Check model name format:** +```python +# Correct formats +"gpt-4o-mini" # OpenAI +"claude-3-sonnet-20240229" # Anthropic +"openrouter/google/gemini-2.0-flash-001" # OpenRouter +"models/gemini-1.5-pro" # Google + +# Common mistakes +"gpt-4o-mini-preview" # โŒ Wrong name +"claude-3-sonnet" # โŒ Missing date +"gemini-2.0-flash" # โŒ Missing provider prefix +``` + +2. **Test model availability:** +```python +import litellm + +# Test model +try: + response = litellm.completion( + model="gpt-4o-mini", + messages=[{"role": "user", "content": "test"}], + max_tokens=1 + ) + print("โœ… Model available") +except Exception as e: + print(f"โŒ Model error: {e}") +``` + +3. **Use fallback models:** +```python +models = ["gpt-4o", "gpt-4o-mini", "gpt-3.5-turbo"] +for model in models: + try: + search_tool = OpenDeepSearchTool(model_name=model) + print(f"โœ… Using model: {model}") + break + except Exception as e: + print(f"โŒ {model}: {e}") +``` + +### Problem: Reranker Configuration Issues + +**Error:** Reranking fails or returns poor results + +**Solutions:** + +1. **Test reranker separately:** +```python +# Test Jina +import requests +headers = {"Authorization": f"Bearer {os.environ['JINA_API_KEY']}"} +response = requests.get("https://api.jina.ai/v1/models", headers=headers) +print(response.json()) + +# Test Infinity +response = requests.get("http://localhost:7997/v1/models") +print(response.json()) +``` + +2. **Disable reranking temporarily:** +```python +search_tool = OpenDeepSearchTool(reranker=None) +result = search_tool.forward("test query") +``` + +3. **Try alternative rerankers:** +```python +rerankers = ["jina", "infinity", None] +for reranker in rerankers: + try: + tool = OpenDeepSearchTool(reranker=reranker) + result = tool.forward("test") + print(f"โœ… {reranker}: Working") + break + except Exception as e: + print(f"โŒ {reranker}: {e}") +``` + +## Runtime Errors + +### Problem: Search Provider Timeouts + +**Error:** `Request timed out` or `Connection error` + +**Solutions:** + +1. **Increase timeout:** +```python +import os +os.environ["REQUESTS_TIMEOUT"] = "60" # 60 seconds + +# Or in code +search_tool = OpenDeepSearchTool(timeout=60) +``` + +2. **Check provider status:** +```bash +# Test Serper API +curl -H "X-API-KEY: your-key" "https://google.serper.dev/search?q=test" + +# Test SearXNG instance +curl "https://your-searxng-instance.com/search?q=test&format=json" +``` + +3. **Switch providers:** +```python +# If Serper fails, try SearXNG +search_tool = OpenDeepSearchTool(search_provider="searxng") +``` + +### Problem: Memory Issues + +**Error:** `CUDA out of memory` or system hangs + +**Solutions:** + +1. **Reduce model size:** +```python +# Use smaller models +search_tool = OpenDeepSearchTool( + model_name="gpt-3.5-turbo", # Instead of gpt-4o + reranker=None # Disable reranking +) +``` + +2. **Limit results:** +```python +search_tool = OpenDeepSearchTool(max_results=5) # Instead of 10+ +``` + +3. **Monitor memory usage:** +```python +import psutil +import gc + +def check_memory(): + process = psutil.Process() + memory_mb = process.memory_info().rss / 1024 / 1024 + print(f"Memory usage: {memory_mb:.1f} MB") + +check_memory() +result = search_tool.forward("query") +check_memory() +gc.collect() # Force garbage collection +``` + +4. **Use CPU-only mode:** +```bash +export CUDA_VISIBLE_DEVICES="" # Disable CUDA +``` + +### Problem: Rate Limit Errors + +**Error:** `Rate limit exceeded` or `429 Too Many Requests` + +**Solutions:** + +1. **Implement retry with backoff:** +```python +import time +import random + +def search_with_retry(search_tool, query, max_retries=3): + for attempt in range(max_retries): + try: + return search_tool.forward(query) + except Exception as e: + if "rate limit" in str(e).lower() or "429" in str(e): + wait_time = (2 ** attempt) + random.uniform(0, 1) + print(f"Rate limited, waiting {wait_time:.1f}s...") + time.sleep(wait_time) + else: + raise e + + raise Exception("Max retries exceeded") +``` + +2. **Use different API keys:** +```python +api_keys = [ + "key1", + "key2", + "key3" +] + +for key in api_keys: + os.environ["OPENAI_API_KEY"] = key + try: + result = search_tool.forward(query) + break + except Exception as e: + print(f"Key failed: {e}") +``` + +3. **Switch to different models/providers:** +```python +configs = [ + {"model_name": "gpt-4o-mini", "provider": "openai"}, + {"model_name": "claude-3-haiku-20240307", "provider": "anthropic"}, + {"model_name": "gemini-1.5-flash", "provider": "google"}, +] +``` + +## Performance Issues + +### Problem: Slow Response Times + +**Symptoms:** Searches taking more than 30 seconds + +**Diagnostics:** + +1. **Time components:** +```python +import time + +def timed_search(search_tool, query): + start_time = time.time() + + # Time search + search_start = time.time() + results = search_tool.search_and_rank(query) + search_time = time.time() - search_start + + # Time synthesis + synthesis_start = time.time() + result = search_tool.synthesize_results(results, query) + synthesis_time = time.time() - synthesis_start + + total_time = time.time() - start_time + + print(f"Search: {search_time:.1f}s") + print(f"Synthesis: {synthesis_time:.1f}s") + print(f"Total: {total_time:.1f}s") + + return result +``` + +**Solutions:** + +1. **Use faster configurations:** +```python +# Fast config +fast_config = { + "model_name": "gpt-3.5-turbo", + "mode": "default", # Instead of "pro" + "reranker": None, # Disable reranking + "max_results": 5 # Fewer results +} + +search_tool = OpenDeepSearchTool(**fast_config) +``` + +2. **Optimize queries:** +```python +# Instead of complex queries +"Find comprehensive analysis of renewable energy trends, market data, policy impacts..." + +# Use focused queries +"Renewable energy market trends 2024" +``` + +3. **Parallel processing:** +```python +from concurrent.futures import ThreadPoolExecutor +import asyncio + +async def parallel_search(queries): + def single_search(query): + tool = OpenDeepSearchTool() + return tool.forward(query) + + with ThreadPoolExecutor(max_workers=3) as executor: + futures = [executor.submit(single_search, q) for q in queries] + results = [future.result() for future in futures] + + return results +``` + +### Problem: Poor Result Quality + +**Symptoms:** Irrelevant or incomplete answers + +**Solutions:** + +1. **Use Pro mode:** +```python +search_tool = OpenDeepSearchTool(mode="pro") +``` + +2. **Enable reranking:** +```python +search_tool = OpenDeepSearchTool(reranker="jina") +``` + +3. **Increase result count:** +```python +search_tool = OpenDeepSearchTool(max_results=15) +``` + +4. **Improve query formulation:** +```python +# Instead of vague queries +"Tell me about AI" + +# Use specific, detailed queries +"Latest developments in large language models for code generation in 2024" +``` + +5. **Use better models:** +```python +# Higher quality models +quality_models = [ + "gpt-4o", + "claude-3-opus-20240229", + "openrouter/google/gemini-2.0-flash-001" +] +``` + +## Integration Problems + +### Problem: SmolAgents Integration Issues + +**Error:** Tool not recognized or import errors + +**Solutions:** + +1. **Check SmolAgents installation:** +```bash +pip install smolagents +``` + +2. **Verify tool registration:** +```python +from smolagents import CodeAgent +from opendeepsearch import OpenDeepSearchTool + +# Create tool +search_tool = OpenDeepSearchTool() + +# Check tool attributes +print(f"Tool name: {search_tool.name}") +print(f"Tool description: {search_tool.description}") + +# Create agent +agent = CodeAgent(tools=[search_tool]) +print("โœ… Integration successful") +``` + +3. **Test tool execution:** +```python +# Direct tool test +result = search_tool.forward("test query") +print("Direct tool:", "โœ…" if result else "โŒ") + +# Agent test +try: + agent_result = agent.run("Search for information about Python") + print("Agent integration:", "โœ…" if agent_result else "โŒ") +except Exception as e: + print(f"Agent error: {e}") +``` + +### Problem: LangChain Integration + +**Error:** Tool interface incompatibility + +**Solutions:** + +1. **Use proper LangChain wrapper:** +```python +from langchain.tools import BaseTool +from pydantic import BaseModel, Field + +class OpenDeepSearchInput(BaseModel): + query: str = Field(description="Search query") + +class OpenDeepSearchLangChainTool(BaseTool): + name = "opendeepsearch" + description = "Search the web for current information" + args_schema = OpenDeepSearchInput + + def __init__(self): + super().__init__() + self.search_tool = OpenDeepSearchTool() + + def _run(self, query: str) -> str: + return self.search_tool.forward(query) + + async def _arun(self, query: str) -> str: + return self._run(query) +``` + +## Getting Help + +### Debug Mode + +Enable detailed logging: + +```python +import logging +logging.basicConfig(level=logging.DEBUG) + +# Or set environment variable +import os +os.environ["OPENDEEPSEARCH_DEBUG"] = "true" +``` + +### Collect System Information + +```python +import sys +import platform +import torch +import opendeepsearch + +def system_info(): + print("=== System Information ===") + print(f"Python version: {sys.version}") + print(f"Platform: {platform.platform()}") + print(f"OpenDeepSearch version: {opendeepsearch.__version__}") + print(f"PyTorch version: {torch.__version__}") + print(f"CUDA available: {torch.cuda.is_available()}") + + print("\n=== Environment Variables ===") + env_vars = [ + "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "GOOGLE_API_KEY", + "SERPER_API_KEY", "JINA_API_KEY", "SEARXNG_INSTANCE_URL" + ] + + for var in env_vars: + value = os.environ.get(var) + if value: + # Show only last 4 characters for security + masked = "*" * (len(value) - 4) + value[-4:] + print(f"{var}: {masked}") + else: + print(f"{var}: Not set") + +system_info() +``` + +### Test Configuration + +```python +def test_configuration(): + """Test all components of OpenDeepSearch setup""" + + tests = [] + + # Test 1: Import + try: + from opendeepsearch import OpenDeepSearchTool + tests.append(("Import", "โœ…", "Success")) + except Exception as e: + tests.append(("Import", "โŒ", str(e))) + return tests + + # Test 2: Basic initialization + try: + tool = OpenDeepSearchTool() + tests.append(("Initialization", "โœ…", "Success")) + except Exception as e: + tests.append(("Initialization", "โŒ", str(e))) + return tests + + # Test 3: Simple search + try: + result = tool.forward("test query") + tests.append(("Search", "โœ…", "Success")) + except Exception as e: + tests.append(("Search", "โŒ", str(e))) + + # Print results + print("\n=== Configuration Test Results ===") + for test_name, status, message in tests: + print(f"{test_name}: {status} {message}") + + return tests + +test_configuration() +``` + +### Community Support + +1. **GitHub Issues**: [Create an issue](https://github.com/sentient-agi/OpenDeepSearch/issues) +2. **Discord**: [Join the community](https://discord.gg/sentientfoundation) +3. **Documentation**: Check other guides in the `docs/` directory + +### Common Error Patterns + +| Error Pattern | Likely Cause | Quick Fix | +|---------------|--------------|-----------| +| `API key` errors | Missing/invalid keys | Check environment variables | +| `Model not found` | Wrong model name | Use correct provider format | +| `Connection` errors | Network/provider issues | Check internet, try different provider | +| `Memory` errors | Large models/results | Use smaller models, fewer results | +| `Import` errors | Installation issues | Reinstall with `pip install -e .` | +| `Timeout` errors | Slow responses | Increase timeout, use faster config | + +### Performance Benchmarks + +Use these benchmarks to validate your setup: + +```python +import time + +def benchmark_search(search_tool, queries): + """Benchmark search performance""" + results = [] + + for query in queries: + start_time = time.time() + try: + result = search_tool.forward(query) + duration = time.time() - start_time + results.append({ + "query": query, + "duration": duration, + "success": True, + "length": len(result) + }) + except Exception as e: + duration = time.time() - start_time + results.append({ + "query": query, + "duration": duration, + "success": False, + "error": str(e) + }) + + # Print summary + successful = [r for r in results if r["success"]] + if successful: + avg_time = sum(r["duration"] for r in successful) / len(successful) + avg_length = sum(r["length"] for r in successful) / len(successful) + print(f"Average response time: {avg_time:.1f}s") + print(f"Average response length: {avg_length:.0f} chars") + print(f"Success rate: {len(successful)}/{len(results)}") + + return results + +# Test queries +test_queries = [ + "What is Python?", + "Latest AI developments 2024", + "How to install Docker?" +] + +search_tool = OpenDeepSearchTool() +benchmark_search(search_tool, test_queries) +``` + +Remember to always test your configuration with simple queries before attempting complex searches! \ No newline at end of file