whoogle-search/LETA_INTEGRATION.md

Mullvad Leta Backend Integration

Overview

Whoogle Search now supports using Mullvad Leta (https://leta.mullvad.net) as an alternative search backend. This provides an additional privacy-focused search option that routes queries through Mullvad's infrastructure.

Features

• Backend Selection: Users can choose between Google (default) and Mullvad Leta as the search backend
• Privacy-Focused: Leta is designed for privacy and doesn't track searches
• Seamless Integration: Results from Leta are automatically converted to Whoogle's display format
• Automatic Tab Filtering: Image, video, news, and map tabs are automatically hidden when using Leta (as these are not supported)

Limitations

When using the Mullvad Leta backend, the following search types are NOT supported:

• Image search (tbm=isch)
• Video search (tbm=vid)
• News search (tbm=nws)
• Map search

Attempting to use these search types with Leta enabled will show an error message and redirect to the home page.

Configuration

Via Web Interface

1. Click the "Config" button on the Whoogle home page
2. Scroll down to find the "Use Mullvad Leta Backend" checkbox
3. Leta is enabled by default - uncheck the box to use Google instead
4. Click "Apply" to save your settings

Via Environment Variable

Leta is enabled by default. To disable it and use Google instead:

WHOOGLE_CONFIG_USE_LETA=0

To explicitly enable it (though it's already default):

WHOOGLE_CONFIG_USE_LETA=1

Implementation Details

Files Modified

1. app/models/config.py

   • Added use_leta configuration option
   • Added to safe_keys list for URL parameter passing

2. app/request.py

   • Modified Request.__init__() to use Leta URL when configured
   • Added gen_query_leta() function to format queries for Leta's API
   • Leta uses different query parameters than Google:
     • engine=google (or brave)
     • country=XX (lowercase country code)
     • language=XX (language code without lang_ prefix)
     • lastUpdated=d|w|m|y (time period filter)
     • page=N (pagination, 1-indexed)

3. app/filter.py

   • Added convert_leta_to_whoogle() method to parse Leta's HTML structure
   • Modified clean() method to detect and convert Leta results
   • Leta results use <article> tags with specific classes that are converted to Whoogle's format

4. app/routes.py

   • Added validation to prevent unsupported search types when using Leta
   • Shows user-friendly error message when attempting image/video/news/map searches with Leta

5. app/utils/results.py

   • Modified get_tabs_content() to accept use_leta parameter
   • Filters out non-web search tabs when Leta is enabled

6. app/templates/index.html

   • Added checkbox in settings panel for enabling/disabling Leta backend
   • Includes helpful tooltip explaining Leta's limitations

Technical Details

Query Parameter Mapping

Google Parameter	Leta Parameter	Notes
q=<query>	q=<query>	Same format
gl=<country>	country=<code>	Lowercase country code
lr=<lang>	language=<code>	Without lang_ prefix
tbs=qdr:d	lastUpdated=d	Time filters mapped
start=10	page=2	Converted to 1-indexed pages
tbm=isch/vid/nws	N/A	Not supported

Leta HTML Structure

Leta returns results in this structure:

<article class="svelte-fmlk7p">
  <a href="<result-url>">
    <h3>Result Title</h3>
  </a>
  <cite>display-url.com</cite>
  <p class="result__body">Result snippet/description</p>
</article>

This is converted to Whoogle's expected format for consistent display.

Testing

To test the Leta integration:

1. Enable Leta in settings
2. Perform a regular web search - should see results from Leta
3. Try to access an image/video/news tab - should see error message
4. Check pagination works correctly
5. Verify country and language filters work
6. Test time period filters (past day/week/month/year)

Environment Variables

• WHOOGLE_CONFIG_USE_LETA: Set to 0 to disable Leta and use Google instead (default: 1 - Leta enabled)

Future Enhancements

Potential improvements for future versions:

• Add Brave as an alternative engine option (Leta supports both Google and Brave)
• Implement image search support if Leta adds this capability
• Add per-query backend selection (bang-style syntax)
• Cache Leta results for improved performance

Notes

• Leta's search results are cached on their end, so you may see "cached X days ago" messages
• Leta requires no API key or authentication
• Leta respects Tor configuration if enabled in Whoogle
• User agent settings apply to Leta requests as well