TeleSearch

An AI-powered real estate listing extraction and search application. TeleSearch monitors Telegram channels and chat groups, automatically parses unstructured property posts into structured data using Google Gemini AI, and provides a web dashboard to filter, search, and manage property leads.

---

Key Features

• Telegram MTProto Integration: Connects directly to Telegram using Telethon to search and retrieve property listings from active agent groups and channels.
• AI Extraction Pipeline: Leverages Google Gemini models to parse messy, unstructured text posts into structured fields (property type, price, location, bedrooms, bathrooms, contact numbers, availability).
• Structured Local Database: Caches and stores parsed listings in SQLite via SQLAlchemy to allow instant offline searches and eliminate redundant AI API calls.
• Fast Web Dashboard: Responsive FastAPI web interface with instant search, keyword aliasing, and listing management.

---

Tech Stack

• Backend: Python, FastAPI, Uvicorn
• Telegram Client: Telethon (MTProto API)
• AI / LLM: Google Gemini API (google-generativeai)
• Database: SQLite, SQLAlchemy
• Frontend: Jinja2 Templates, HTML5, CSS3, JavaScript

---

Project Structure

telesearch/
├── app/
│   ├── aiextractor.py       # Gemini AI prompt engineering and structured extraction
│   ├── config.py            # Pydantic settings & environment configuration
│   ├── crud.py              # Database CRUD operations
│   ├── database.py          # SQLAlchemy engine & session management
│   ├── main.py              # FastAPI application routes & endpoints
│   ├── models.py            # SQLAlchemy database models
│   ├── schemas.py           # Pydantic data validation schemas
│   ├── telegramclient.py    # Telethon client session & message fetching
│   ├── static/              # CSS, JS, and UI assets
│   └── templates/           # Jinja2 HTML templates
├── requirements.txt         # Python package dependencies
├── telesearch.bat           # Quick launcher script for Windows
├── .env.example             # Example environment configuration template
└── .gitignore               # Git ignore rules for credentials, sessions, and databases

---

Getting Started

1. Prerequisites

• Python 3.10 or higher installed
• Telegram API ID and Hash (obtainable from my.telegram.org)
• Google Gemini API Key

2. Installation

1. Clone the repository:

   git clone https://github.com/harithnabilf/telesearch.git
   cd telesearch

2. Create and activate a Python virtual environment:

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

3. Install required dependencies:

   pip install -r requirements.txt

3. Configuration

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Edit .env:

TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_PHONE_NUMBER=your_phone_number
AI_API_KEY=your_gemini_api_key

4. Running the Application

Start the FastAPI application:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Or on Windows, double-click or run:

telesearch.bat

Open your browser and navigate to:

http://127.0.0.1:8000