apartment-hunter

# Apartment Hunter > [!WARNING] > **Legal Disclaimer:** This is a private automation tool for personal use only. By using this software, you agree to the [Legal Disclaimer and Fair Use Policy](LEGAL.md). Apartment Hunter is a powerful aggregator and search platform for rental apartments. It automates finding, filtering, and scoring housing options without manually checking websites every hour. **Currently, the system only supports data from `krisha.kz`**, but the architecture allows for easy extension. It supports precise polygon-based geographic search, semantic text search (RAG), and LLM-powered quality scoring. ## Quick Start ```powershell # 1. Start the MCP server for Codex Desktop / Claude uv run apartment-hunter-mcp # 2. Or run the data ingestion pipeline manually uv run apartment-hunter-ingest ``` ### AI Skills The project includes specialized AI skills in `.agents/skills` to enhance your AI assistant: - **apartment-search**: Domain workflow for apartment search, ingestion, monitoring, and translating listing jargon. - **city-district-context-kz**: Provides context on Kazakhstan cities and districts (transport, pricing, livability). - **html-report-generator**: Generates a visual HTML report of apartments with photos and links, and launches it on localhost. **How to use skills:** You don't need to manually install these skills. Simply open this project folder using your favorite AI CLI (like Antigravity CLI / Codex CLI) and the agent will automatically discover and load the skills from the local workspace. ## Use Cases - **Agents / MCP:** Connect it to Codex Desktop to chat with your apartment database ("Show me 2-bedroom apartments near Megapark under 500k, sort by newest"). - **Precise Geography:** Stop relying on inaccurate text search. Draw a polygon on a map, pass the coordinates, and only get apartments strictly within that exact boundary. - **AI Scoring:** Automatically rate apartments out of 10 based on renovation quality, furniture condition, and specific user preferences using Vision LLMs. - **Market Monitoring:** Run ingestion periodically (e.g. via cron) to track price drops and immediately catch new listings before they are rented out. ## Architecture Philosophy This is a **Library-First** project. The core logic is built as a reusable, source-agnostic Python library. All site-specific scraping and adapters are isolated plugins, ensuring the core remains stable and extensible. ## License [MIT](LICENSE)