import gradio as gr
import requests
import json
from typing import Optional, List
def tavily_search(
api_key: str,
query: str,
topic: str = "general",
search_depth: str = "basic",
chunks_per_source: int = 3,
max_results: int = 5,
time_range: Optional[str] = None,
days: int = 7,
include_answer: bool = True,
include_raw_content: str = "false",
include_images: bool = False,
include_image_descriptions: bool = False,
include_domains: str = "",
exclude_domains: str = "",
country: Optional[str] = None
):
"""
Perform a Tavily search with the given parameters.
"""
if not api_key.strip():
return "❌ Error: Please provide a valid Tavily API key."
if not query.strip():
return "❌ Error: Please provide a search query."
url = "https://api.tavily.com/search"
# Prepare the payload
payload = {
"query": query,
"topic": topic,
"search_depth": search_depth,
"max_results": max_results,
"include_answer": include_answer,
"include_images": include_images,
"include_image_descriptions": include_image_descriptions,
}
# Add optional parameters
if search_depth == "advanced":
payload["chunks_per_source"] = chunks_per_source
if time_range and time_range != "None":
payload["time_range"] = time_range
if topic == "news" and days > 0:
payload["days"] = days
if include_raw_content != "false":
if include_raw_content == "html":
payload["include_raw_content"] = True
else:
payload["include_raw_content"] = include_raw_content
if include_domains.strip():
payload["include_domains"] = [domain.strip() for domain in include_domains.split(",")]
if exclude_domains.strip():
payload["exclude_domains"] = [domain.strip() for domain in exclude_domains.split(",")]
if country and country != "None":
payload["country"] = country
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
try:
response = requests.post(url, json=payload, headers=headers, timeout=30)
if response.status_code == 200:
result = response.json()
# Format the response as clean HTML
html_result = """
Tavily Search Results
""".format(query.replace('"', '"'))
# Add answer section if available
if "answer" in result and result["answer"]:
html_result += f"""
📋 AI Generated Answer
{result['answer']}
"""
# Add search results
if "results" in result and result["results"]:
html_result += f"""
"""
for i, item in enumerate(result["results"], 1):
title = item.get('title', 'No Title').replace('<', '<').replace('>', '>')
url = item.get('url', 'No URL')
content = item.get('content', 'No content available')[:800] + '...'
content = content.replace('<', '<').replace('>', '>')
score = item.get('score', 0)
html_result += f"""
{i}. {title}
{url}
{content}
{f'
⭐ Score: {score:.3f}' if score else ''}
"""
html_result += "
"
# Add images if available
if "images" in result and result.get("images"):
html_result += """
"""
for img in result["images"][:6]: # Limit to 6 images
img_url = img.get('url', '')
img_title = img.get('title', 'Image').replace('<', '<').replace('>', '>')
html_result += f"""
{img_title}
"""
html_result += "
"
# Add metadata
html_result += f"""
"""
return html_result
else:
return f"❌ Error: HTTP {response.status_code}\n{response.text}"
except requests.exceptions.Timeout:
return "❌ Error: Request timed out. Please try again."
except requests.exceptions.RequestException as e:
return f"❌ Error: {str(e)}"
except Exception as e:
return f"❌ Unexpected error: {str(e)}"
# Define the country options
country_options = [
"None", "afghanistan", "albania", "algeria", "andorra", "angola", "argentina",
"armenia", "australia", "austria", "azerbaijan", "bahamas", "bahrain", "bangladesh",
"barbados", "belarus", "belgium", "belize", "benin", "bhutan", "bolivia",
"bosnia and herzegovina", "botswana", "brazil", "brunei", "bulgaria", "burkina faso",
"burundi", "cambodia", "cameroon", "canada", "cape verde", "central african republic",
"chad", "chile", "china", "colombia", "comoros", "congo", "costa rica", "croatia",
"cuba", "cyprus", "czech republic", "denmark", "djibouti", "dominican republic",
"ecuador", "egypt", "el salvador", "equatorial guinea", "eritrea", "estonia",
"ethiopia", "fiji", "finland", "france", "gabon", "gambia", "georgia", "germany",
"ghana", "greece", "guatemala", "guinea", "haiti", "honduras", "hungary", "iceland",
"india", "indonesia", "iran", "iraq", "ireland", "israel", "italy", "jamaica",
"japan", "jordan", "kazakhstan", "kenya", "kuwait", "kyrgyzstan", "latvia", "lebanon",
"lesotho", "liberia", "libya", "liechtenstein", "lithuania", "luxembourg", "madagascar",
"malawi", "malaysia", "maldives", "mali", "malta", "mauritania", "mauritius", "mexico",
"moldova", "monaco", "mongolia", "montenegro", "morocco", "mozambique", "myanmar",
"namibia", "nepal", "netherlands", "new zealand", "nicaragua", "niger", "nigeria",
"north korea", "north macedonia", "norway", "oman", "pakistan", "panama",
"papua new guinea", "paraguay", "peru", "philippines", "poland", "portugal", "qatar",
"romania", "russia", "rwanda", "saudi arabia", "senegal", "serbia", "singapore",
"slovakia", "slovenia", "somalia", "south africa", "south korea", "south sudan",
"spain", "sri lanka", "sudan", "sweden", "switzerland", "syria", "taiwan",
"tajikistan", "tanzania", "thailand", "togo", "trinidad and tobago", "tunisia",
"turkey", "turkmenistan", "uganda", "ukraine", "united arab emirates",
"united kingdom", "united states", "uruguay", "uzbekistan", "venezuela", "vietnam",
"yemen", "zambia", "zimbabwe"
]
# Create the Gradio interface
with gr.Blocks(title="Tavily Search API", theme=gr.themes.Soft()) as app:
gr.Markdown("# 🔍 Tavily Search API Interface")
gr.Markdown("Search the web using Tavily's powerful search API with customizable parameters.")
# Add documentation accordion
with gr.Accordion("📖 API Documentation & Parameter Options", open=False):
gr.Markdown("""
## Available Options
### **topic**: The category of the search
- **news**: Useful for retrieving real-time updates, particularly about politics, sports, and major current events covered by mainstream media sources
- **general**: For broader, more general-purpose searches that may include a wide range of sources
**Available options**: `general`, `news`
### **search_depth**: The depth of the search
- **advanced**: Tailored to retrieve the most relevant sources and content snippets for your query (costs 2 API Credits)
- **basic**: Provides generic content snippets from each source (costs 1 API Credit)
**Available options**: `basic`, `advanced`
### **chunks_per_source**: Content snippets control
Chunks are short content snippets (maximum 500 characters each) pulled directly from the source. Use this to define the maximum number of relevant chunks returned per source and to control the content length. Chunks will appear in the content field as: ` [...] [...] `.
**Note**: Available only when `search_depth` is `advanced`
**Required range**: 1 ≤ x ≤ 3
### **max_results**: Maximum number of search results
The maximum number of search results to return.
**Required range**: 0 ≤ x ≤ 20
### **time_range**: Time filtering
The time range back from the current date to filter results. Useful when looking for sources that have published data.
**Available options**: `day`, `week`, `month`, `year`, `d`, `w`, `m`, `y`
### **days**: Days back for news searches
Number of days back from the current date to include. Available only if topic is `news`.
**Required range**: x ≥ 1
### **include_answer**: LLM-generated answer
Include an LLM-generated answer to the provided query.
- `basic` or `true`: Returns a quick answer
- `advanced`: Returns a more detailed answer
### **include_raw_content**: Raw HTML content
Include the cleaned and parsed HTML content of each search result.
- `markdown` or `true`: Returns search result content in markdown format
- `text`: Returns the plain text from the results (may increase latency)
### **include_images**: Image search
Also perform an image search and include the results in the response.
### **include_image_descriptions**: Image descriptions
When `include_images` is true, also add a descriptive text for each image.
### **include_domains**: Domain inclusion
A list of domains to specifically include in the search results.
### **exclude_domains**: Domain exclusion
A list of domains to specifically exclude from the search results.
### **country**: Country-specific boosting
Boost search results from a specific country. This will prioritize content from the selected country in the search results. Available only if topic is `general`.
**Available countries**: afghanistan, albania, algeria, andorra, angola, argentina, armenia, australia, austria, azerbaijan, bahamas, bahrain, bangladesh, barbados, belarus, belgium, belize, benin, bhutan, bolivia, bosnia and herzegovina, botswana, brazil, brunei, bulgaria, burkina faso, burundi, cambodia, cameroon, canada, cape verde, central african republic, chad, chile, china, colombia, comoros, congo, costa rica, croatia, cuba, cyprus, czech republic, denmark, djibouti, dominican republic, ecuador, egypt, el salvador, equatorial guinea, eritrea, estonia, ethiopia, fiji, finland, france, gabon, gambia, georgia, germany, ghana, greece, guatemala, guinea, haiti, honduras, hungary, iceland, india, indonesia, iran, iraq, ireland, israel, italy, jamaica, japan, jordan, kazakhstan, kenya, kuwait, kyrgyzstan, latvia, lebanon, lesotho, liberia, libya, liechtenstein, lithuania, luxembourg, madagascar, malawi, malaysia, maldives, mali, malta, mauritania, mauritius, mexico, moldova, monaco, mongolia, montenegro, morocco, mozambique, myanmar, namibia, nepal, netherlands, new zealand, nicaragua, niger, nigeria, north korea, north macedonia, norway, oman, pakistan, panama, papua new guinea, paraguay, peru, philippines, poland, portugal, qatar, romania, russia, rwanda, saudi arabia, senegal, serbia, singapore, slovakia, slovenia, somalia, south africa, south korea, south sudan, spain, sri lanka, sudan, sweden, switzerland, syria, taiwan, tajikistan, tanzania, thailand, togo, trinidad and tobago, tunisia, turkey, turkmenistan, uganda, ukraine, united arab emirates, united kingdom, united states, uruguay, uzbekistan, venezuela, vietnam, yemen, zambia, zimbabwe
""")
with gr.Row():
with gr.Column(scale=1):
# API Configuration
gr.Markdown("## 🔑 API Configuration")
api_key = gr.Textbox(
label="Tavily API Key",
placeholder="Enter your Tavily API key here...",
type="password",
info="Your API key will be used to authenticate requests to Tavily."
)
# Search Parameters
gr.Markdown("## 🎯 Search Parameters")
query = gr.Textbox(
label="Search Query",
placeholder="e.g., 'who is Leo Messi?'",
info="The search query you want to execute."
)
with gr.Row():
topic = gr.Dropdown(
choices=["general", "news"],
value="general",
label="Topic",
info="general: broad searches, news: real-time updates"
)
search_depth = gr.Dropdown(
choices=["basic", "advanced"],
value="basic",
label="Search Depth",
info="basic: 1 credit, advanced: 2 credits"
)
with gr.Row():
max_results = gr.Slider(
minimum=1,
maximum=20,
value=5,
step=1,
label="Max Results",
info="Maximum number of search results to return"
)
chunks_per_source = gr.Slider(
minimum=1,
maximum=3,
value=3,
step=1,
label="Chunks per Source",
info="Only applies to advanced search"
)
# Advanced Options
gr.Markdown("## ⚙️ Advanced Options")
with gr.Row():
time_range = gr.Dropdown(
choices=["None", "day", "week", "month", "year"],
value="None",
label="Time Range",
info="Filter results by time period"
)
days = gr.Number(
value=7,
minimum=1,
label="Days (News only)",
info="Number of days back for news searches"
)
with gr.Row():
include_answer = gr.Checkbox(
value=True,
label="Include Answer",
info="Include LLM-generated answer"
)
include_images = gr.Checkbox(
value=False,
label="Include Images",
info="Perform image search"
)
include_image_descriptions = gr.Checkbox(
value=False,
label="Include Image Descriptions",
info="Add descriptions for images"
)
include_raw_content = gr.Dropdown(
choices=["false", "html", "markdown", "text"],
value="html",
label="Include Raw Content",
info="HTML: Clean styled format, Markdown: MD format, Text: Plain text"
)
with gr.Row():
include_domains = gr.Textbox(
label="Include Domains",
placeholder="example.com, another.com",
info="Comma-separated list of domains to include"
)
exclude_domains = gr.Textbox(
label="Exclude Domains",
placeholder="example.com, another.com",
info="Comma-separated list of domains to exclude"
)
country = gr.Dropdown(
choices=country_options,
value="None",
label="Country",
info="Boost results from specific country (general topic only)"
)
# Search Button
search_btn = gr.Button("🔍 Search", variant="primary", size="lg")
with gr.Column(scale=2):
# Results
gr.Markdown("## 📊 Search Results")
results = gr.HTML(
label="Results",
show_label=False,
elem_id="search_results"
)
# Examples
gr.Markdown("## 💡 Comprehensive Test Examples")
gr.Examples(
[
# Basic general search
[
"Who is Leo Messi?", # query
"general", # topic
"basic", # search_depth
3, # chunks_per_source
5, # max_results
"None", # time_range
7, # days
True, # include_answer
"html", # include_raw_content
False, # include_images
False, # include_image_descriptions
"", # include_domains
"", # exclude_domains
"None" # country
],
# Advanced news search with time filter
[
"Latest artificial intelligence breakthroughs",
"news",
"advanced",
3,
3,
"week",
3,
True,
"html",
False,
False,
"",
"",
"None"
],
# Python tutorials with domain inclusion
[
"Python machine learning tutorials",
"general",
"advanced",
2,
8,
"None",
7,
True,
"html",
False,
False,
"github.com, stackoverflow.com, medium.com",
"",
"None"
],
# Climate change news with exclusions
[
"Climate change policy updates",
"news",
"basic",
3,
4,
"month",
14,
True,
"html",
False,
False,
"",
"facebook.com, twitter.com, reddit.com",
"None"
],
# Country-specific search
[
"Best restaurants and food culture",
"general",
"basic",
3,
6,
"None",
7,
True,
"false",
True,
True,
"",
"",
"france"
],
# Technology news with images
[
"iPhone 15 features and specs",
"general",
"advanced",
3,
5,
"None",
7,
True,
"html",
True,
True,
"apple.com, techcrunch.com, theverge.com",
"",
"united states"
],
# Sports news recent
[
"FIFA World Cup 2024 results",
"news",
"advanced",
3,
7,
"day",
1,
True,
"html",
False,
False,
"fifa.com, espn.com, bbc.com",
"",
"None"
],
# Academic research
[
"quantum computing research papers 2024",
"general",
"advanced",
3,
10,
"year",
7,
True,
"html",
False,
False,
"arxiv.org, nature.com, science.org",
"wikipedia.org",
"None"
],
# Stock market news
[
"Tesla stock price analysis",
"news",
"basic",
3,
5,
"week",
7,
True,
"false",
False,
False,
"yahoo.com, bloomberg.com, marketwatch.com",
"",
"None"
],
# Health and medical
[
"COVID-19 vaccine effectiveness studies",
"general",
"advanced",
3,
8,
"month",
7,
True,
"text",
False,
False,
"who.int, cdc.gov, pubmed.ncbi.nlm.nih.gov",
"facebook.com, instagram.com",
"None"
]
],
inputs=[
query, topic, search_depth, chunks_per_source, max_results,
time_range, days, include_answer, include_raw_content, include_images,
include_image_descriptions, include_domains, exclude_domains, country
],
label="🚀 Click on any example to load complete test configurations"
)
# Connect the search button
search_btn.click(
fn=tavily_search,
inputs=[
api_key, query, topic, search_depth, chunks_per_source, max_results,
time_range, days, include_answer, include_raw_content, include_images,
include_image_descriptions, include_domains, exclude_domains, country
],
outputs=results
)
# Footer
gr.Markdown("---")
gr.Markdown("🔗 **Get your Tavily API key at:** [tavily.com](https://tavily.com)")
# Launch the app
if __name__ == "__main__":
app.launch(
share=True
)