# Using Tavily Instead of SearxNG

This guide explains how to configure and use Tavily as a replacement for SearxNG in the Perplexica project.

## What is Tavily?

[Tavily](https://tavily.com/) is an AI-native search engine that provides a powerful API for web searches. It's designed to be more focused on AI applications and provides structured data in its responses.

## Advantages of Tavily over SearxNG

- **AI-Optimized**: Tavily is specifically designed for AI applications and provides more relevant results for AI-powered search.
- **Structured Data**: Results come in a well-structured format that's easy to process.
- **AI-Generated Answers**: Tavily can generate concise answers to queries based on search results.
- **Advanced Search Options**: Includes features like search depth control, domain filtering, time-based filtering, and result limiting.

## Setup Instructions

1. **Get a Tavily API Key**:
   - Sign up for an account at [Tavily](https://tavily.com/)
   - Navigate to your dashboard and create an API key

2. **Configure the API Key**:
   - Open your `config.toml` file
   - Add your Tavily API key to the `TAVILY` field under `[API_ENDPOINTS]`:
     ```toml
     [API_ENDPOINTS]
     TAVILY = "your-tavily-api-key"
     ```
   - Alternatively, you can set the `TAVILY_API_KEY` environment variable

3. **Select Tavily as the Search Engine**:
   - Open your `config.toml` file
   - Set the `ENGINE` field under `[SEARCH]` to `"tavily"`:
     ```toml
     [SEARCH]
     ENGINE = "tavily"
     ```
   - Alternatively, you can set the `SEARCH_ENGINE` environment variable to `"tavily"`

4. **Verify Configuration**:
   - The application will now use Tavily for web searches
   - You can verify this by checking the console logs, which will show "Using search engine: tavily" when a search is performed

## Usage

The Tavily integration is designed to be a drop-in replacement for SearxNG. All existing search functionality will continue to work as before, but with improved results from Tavily.

## API Options

The Tavily implementation supports the following options:

- `topic`: 'general' or 'news' (default: 'general')
- `search_depth`: 'basic' or 'advanced' (default: 'advanced')
- `chunks_per_source`: Number of content chunks to retrieve from each source (1-3, default: 3)
- `max_results`: Maximum number of results to return (default: 10)
- `time_range`: Filter results by time range ('day', 'week', 'month', 'year', 'd', 'w', 'm', 'y')
- `days`: Number of days back from the current date to include (for news topic)
- `include_answer`: Include an AI-generated answer ('basic', 'advanced', or true)
- `include_raw_content`: Include the cleaned and parsed HTML content of each result
- `include_images`: Also perform an image search and include the results
- `include_image_descriptions`: Add descriptive text for each image
- `include_domains`: Array of domains to include in search results
- `exclude_domains`: Array of domains to exclude from search results

## Response Format

Tavily returns a structured response with the following fields:

- `query`: The search query that was executed
- `answer`: An AI-generated answer to the query (if requested)
- `images`: List of query-related images (if requested)
- `results`: A list of search results, each containing:
  - `title`: The title of the search result
  - `url`: The URL of the search result
  - `content`: A short description of the search result
  - `score`: The relevance score of the search result
  - `raw_content`: The cleaned and parsed HTML content (if requested)
- `response_time`: Time in seconds it took to complete the request

## Troubleshooting

If you encounter any issues:

1. Verify your Tavily API key is correctly set in `config.toml` or as an environment variable
2. Check the application logs for any error messages
3. Ensure your Tavily account has sufficient credits/quota for API calls

## Switching Between Search Engines

You can easily switch between SearxNG and Tavily by changing the `ENGINE` setting in your `config.toml` file:

```toml
[SEARCH]
ENGINE = "searxng"  # Use SearxNG (default)
# or
ENGINE = "tavily"   # Use Tavily
```

You can also use the `SEARCH_ENGINE` environment variable to override this setting.

## Reverting to SearxNG

If you need to revert to using SearxNG:

1. Set the `ENGINE` field under `[SEARCH]` in your `config.toml` file to `"searxng"`:
   ```toml
   [SEARCH]
   ENGINE = "searxng"
   ```
2. Ensure your `SEARXNG` entry is properly configured with a valid SearxNG instance URL