Gif Search Bot

A Telegram bot for searching information from open sources via DuckDuckGo and Wikipedia.

Features

• DuckDuckGo Search: Web search without API keys or rate limits
• Wikipedia Integration: Direct Wikipedia search with !w command
• Smart Snippets: Prioritizes Wikipedia results and ensures complete sentences
• Multi-Environment: Works in private chats and group conversations
• Statistics Tracking: SQLite-based user activity and query tracking
• Admin Panel: Administrative commands for bot statistics
• Open Source: MIT licensed, fully free and open

Requirements

• Python 3.10 or higher
• Telegram Bot Token from @BotFather

Installation

Clone Repository

git clone https://github.com/gifsearch/gif.git
cd gif

Create Virtual Environment

python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate  # Windows

Install Dependencies

pip install -r requirements.txt

Configure Environment

cp .env.example .env

Edit .env file and add your credentials:

BOT_TOKEN=your_telegram_bot_token_here
ADMINS_ID=123456789,987654321

To obtain your Telegram user ID, message @userinfobot.

Run Bot

python main.py

Usage

Commands

• /start - Display welcome message
• /help - Show command reference
• /about - Information about the bot
• /g <query> - Search in group chats
• !w <query> - Wikipedia-only search
• /stats - View statistics (administrators only)

Private Chats

Send any text query directly:

Python programming language

Group Chats

Use the /g command prefix:

/g Linux operating system

Wikipedia Search

Use the !w command for Wikipedia-specific queries:

!w Artificial Intelligence

Administrator Features

The /stats command displays:

• Total registered users
• Total search queries
• Active users today
• Queries performed today

Configuration

All configuration is managed through environment variables in the .env file.

Required Variables

• BOT_TOKEN - Telegram Bot API token from BotFather

Optional Variables

• ADMINS_ID - Comma-separated list of administrator Telegram IDs

Application Settings

Configuration defaults are defined in bot/config.py:

• SEARCH_RESULTS_LIMIT - Maximum search results (default: 5)
• REQUEST_TIMEOUT - HTTP request timeout in seconds (default: 15)
• USER_AGENT - User agent string for web requests

Database Migration

If migrating from a previous JSON-based statistics system to SQLite:

python scripts/json_to_sqlite.py

Optional arguments:

python scripts/json_to_sqlite.py --json stats.json --db stats.db --backup

The migration script automatically creates a backup of the JSON file before conversion.

Docker Deployment

Build Image

docker build -t gif-bot .

Run Container

docker run -d --env-file .env --name gif-bot gif-bot

Docker Compose

docker-compose up -d

View logs:

docker-compose logs -f

Project Structure

gif/
├── bot/
│   ├── handlers/
│   │   ├── commands.py      # Command handlers (/start, /stats, etc.)
│   │   └── messages.py      # Message handlers (search, Wikipedia)
│   ├── services/
│   │   ├── search.py        # DuckDuckGo and Wikipedia search
│   │   ├── database.py      # SQLite database operations
│   │   └── stats.py         # Statistics tracking service
│   └── config.py            # Application configuration
├── scripts/
│   └── json_to_sqlite.py    # Database migration utility
├── main.py                  # Application entry point
├── requirements.txt         # Python dependencies
├── Dockerfile               # Docker image definition
├── docker-compose.yml       # Docker Compose configuration
├── .env.example             # Environment template
└── README.md               # This file

Development

Code Style

• Follow PEP 8 guidelines
• Use type hints for function signatures
• Write docstrings for public functions
• Comments in English or Russian

Testing

Before submitting changes, verify:

• Bot starts without errors
• All commands function correctly
• No regression bugs introduced

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on:

• Reporting bugs
• Suggesting enhancements
• Submitting pull requests

Roadmap

See ROADMAP.md for planned features and future development.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• python-telegram-bot - Telegram Bot API wrapper
• DuckDuckGo - Privacy-focused search engine
• Wikipedia - Free encyclopedia
• BeautifulSoup - HTML parsing library

Support

• Report issues: GitHub Issues
• Discussions: GitHub Discussions
• Telegram Community: t.me/gif56789f

Disclaimer

This bot is an independent project and is not affiliated with DuckDuckGo, Wikipedia, or Telegram.

---

Made with dedication for the open source community.