🔍 DuckDuckGo Search Agent with Gemini - Categorized

Intelligent search agent that uses DuckDuckGo to find relevant content by specific category and presents the 5 best results curated by Gemini LLM. Interactive command-line interface with 10 specialized categories.

✨ Features

• 🗂️ 10 Specialized Categories: Scientific articles, news, tech blogs, videos, education, documentation, corporate, forums, data and general search
• 🔍 Intelligent Search: Automated DuckDuckGo search with category-specific filters
• 🤖 AI Curation: Analysis and refinement of results using Gemini
• 📊 Relevance System: Proprietary algorithm with category-specific bonus
• 💻 CLI Interface: Easy and intuitive terminal interaction
• ⚡ Optimized Results: Top 5 most relevant results for each query
• 🌐 English Content: Searches prioritized for English content
• 🔄 Continuous Session: Conversation history maintained during session

🗂️ Available Categories

ID	Category	Description	Filters Include
1	📖 Scientific Articles	Academic papers, research studies, scientific publications	Scholar, PubMed, ArXiv, ResearchGate, IEEE
2	📰 News	Latest news, headlines, current reports	BBC, CNN, Reuters, NPR, AP News
3	💻 Technical Articles/Blogs	Tutorials, tech blogs, technical guides	Medium, Dev.to, StackOverflow, GitHub Pages
4	🎥 Videos	Video content, courses, lectures	YouTube, Vimeo, Twitch
5	🎓 Educational Content	Courses, MOOCs, educational materials	Coursera, edX, Khan Academy, Udemy, Pluralsight
6	📚 Official Documentation	Official docs, manuals, technical references	Official documentation sites, APIs
7	🏢 Corporate Content	White papers, case studies, business reports	Reports, case studies, corporate research
8	🌐 Forums & Communities	Discussions, Q&A, online communities	Reddit, StackOverflow, Quora, Hacker News
9	📊 Data & Statistics	Datasets, statistics, data analysis	Kaggle, Data.gov, CSV/JSON files
10	🔍 General Search	Broad search without specific filters	All types of content

🚀 Installation and Configuration

Using UV (Recommended)

# Clone the repository
git clone <your-repository>
cd agents

# Install dependencies
uv sync

# Configure environment variable
export GEMINI_API_KEY=your_api_key_here

# Run the agent
uv run python agents/search_agent/agent.py

Using pip

# Clone the repository
git clone <your-repository>
cd agents

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

# Install dependencies
pip install agno ddgs google-genai python-dotenv

# Configure environment variable
export GEMINI_API_KEY=your_api_key_here

# Run the agent
python agents/search_agent/agent.py

🔑 API Key Configuration

Google Gemini API

1. Visit Google AI Studio
2. Create an account or sign in
3. Generate a new API Key
4. Configure the environment variable:

# Linux/Mac
export GEMINI_API_KEY=your_api_key_here

# Windows
set GEMINI_API_KEY=your_api_key_here

💡 How to Use

Execution and Interface

uv run python agents/search_agent/agent.py

Interaction Flow

🔍 DuckDuckGo Search Agent with Gemini - Categorized
=================================================================
🎯 Search specific content by category!
✅ Agent initialized successfully!

------------------------------------------------------------

📋 Show available categories? (y/n): y

🗂️  AVAILABLE CONTENT CATEGORIES:
============================================================
 1. 📖 Scientific Articles
    Academic papers, research studies, scientific publications

 2. 📰 News
    Latest news, headlines, current reports

[... other categories ...]

🎯 Choose category (1-10) or press Enter for general search: 3
✅ Selected category: 💻 Technical Articles/Blogs
📝 Tutorials, tech blogs, technical guides

💬 Enter your search query (or 'exit' to quit): React hooks tutorial

🔍 Searching: React hooks tutorial
🔍 Searching in: 💻 Technical Articles/Blogs
📝 Query: (React hooks tutorial) AND (site:medium.com OR site:dev.to OR site:stackoverflow.com OR site:github.io OR site:hashnode.com OR site:towardsdatascience.com OR tutorial OR guide OR how-to OR blog OR technical)...
⏳ Please wait, processing...

======================================================================
📋 SEARCH RESULTS:
======================================================================
[Curated response by Gemini with the 5 best results]

Available Commands

• Categories: Type y to see all categories
• Selection: Choose 1-10 or press Enter for general search
• Search: Type any term or question
• Exit: Type exit, quit, q or press Enter when empty
• Interrupt: Press Ctrl+C at any time

🎯 Search Examples by Category

📖 Scientific Articles

Category: 1
Search: "machine learning deep learning"
Result: Papers from ArXiv, Google Scholar, PubMed

📰 News

Category: 2
Search: "artificial intelligence 2024"
Result: News from BBC, CNN, Reuters

💻 Technical Articles

Category: 3
Search: "React performance optimization"
Result: Tutorials from Medium, Dev.to, tech blogs

🎥 Videos

Category: 4
Search: "Python for beginners"
Result: Videos from YouTube, Vimeo, online courses

🎓 Educational Content

Category: 5
Search: "data science course"
Result: Courses from Coursera, Udemy, edX

🛠️ Architecture

Main Components

• 🗂️ Category System: 10 categories with specific filters
• 🔍 DuckDuckGo Search: Search engine with advanced filters
• 🤖 Google Gemini: LLM for content analysis and curation
• ⚡ Agno Framework: Agent and tool orchestration
• 📊 Relevance System: Algorithm with category-specific bonus

Processing Flow

1. Category Selection: User chooses from 10 available categories
2. User Input: Receives query via terminal
3. Filter Application: Combines query with category-specific filters
4. Categorized Search: DuckDuckGo returns up to 15 filtered results
5. Relevance Calculation: Scoring with bonus for specific categories
6. Top 5 Selection: Ordering by relevance
7. AI Curation: Gemini analyzes and synthesizes categorized results
8. Presentation: Formatted result displayed in terminal

Filter Algorithm

Each category applies specific filters in the search:

• Site-specific: site:medium.com OR site:github.io
• File types: filetype:pdf research OR paper
• Keywords: tutorial OR guide OR how-to
• Combinations: (query) AND (category filters)

⚙️ Advanced Configuration

Optional Environment Variables

# Search region (default: us-en)
export SEARCH_REGION=us-en

# Maximum initial results (default: 15)
export MAX_SEARCH_RESULTS=15

# Gemini model (default: gemini-2.0-flash-exp)
export GEMINI_MODEL=gemini-2.0-flash-exp

Category Customization

Edit agents/search_agent/agent.py in the CONTENT_CATEGORIES dictionary to:

• Add new categories
• Modify existing filters
• Adjust descriptions
• Customize priorities

Example of New Category

"11": {
    "name": "🎮 Gaming",
    "description": "Games, reviews, gameplay, gaming news",
    "filters": [
        "site:ign.com OR site:gamespot.com OR site:polygon.com",
        "game OR gaming OR review OR gameplay",
        "steam OR playstation OR xbox"
    ]
}

🔧 Development

Project Structure

agents/
├── search_agent/
│   ├── __init__.py
│   └── agent.py          # ⭐ Implementation with categories
├── README.md             # 📚 Complete documentation
├── pyproject.toml        # 📦 Dependencies
└── uv.lock              # 🔒 UV lock file

Main Dependencies

• agno: AI agent framework
• ddgs: DuckDuckGo Search API
• google-genai: Google Gemini API
• python-dotenv: Environment variable management

🐛 Troubleshooting

Error: API Key not configured

⚠️  ERROR: Gemini API key is required

Solution: Configure the GEMINI_API_KEY variable

Error: Invalid category

❌ Invalid option. Choose between 1 and 10.

Solution: Type a number between 1-10 or press Enter for general search

Limited results for specific category

Cause: Very restrictive filters may limit results Solution: Use category "10 - General Search" or adjust filters

Error: Import not found

ModuleNotFoundError: No module named 'agno'

Solution: Run uv sync or install dependencies manually

🚀 Next Steps

• Save search history by category
• Export results (JSON, CSV, Markdown)
• Custom filter configuration
• Support for multiple search APIs
• Optional web interface
• Favorites system by category
• Usage analytics by category

📄 License

This project is under the MIT license. See the LICENSE file for details.

🤝 Contributions

Contributions are welcome! Open an issue or send a pull request.

---

Developed with ❤️ using Agno Framework