Rental Apartment Finding Assistant

An async engine coding agent for finding rental apartments with multi-turn interaction, tool use, and comprehensive evaluation capabilities.

• Multi-turn Interaction: Natural conversation flow with users
• Tool Use: Web scraping from Craigslist, data extraction, and analysis tools
• Parallel Processing: Async operations for efficient searching
• Multi-Model Support: OpenAI GPT and Anthropic Claude models
• Comprehensive Evaluation: Reward functions and performance metrics

• Reward Functions: Deterministic and quality-based metrics
• Best-of-N Selection: Multiple agent runs with intelligent selection
• Model Comparison: Performance evaluation across different LLMs
• Test Prompts: Comprehensive test suite with varying complexity levels

• Python 3.13+
• uv package manager
• API keys for OpenAI and/or Anthropic

1. Clone the repository:

   git clone <repository-url>
   cd rental-agent

2. Install dependencies with uv:

   uv sync

3. Set up environment variables:

   cp env.example .env
   # Edit .env with your API keys

4. Install development dependencies (optional):

   uv sync --extra dev

# Start interactive apartment search
uv run rental-agent interactive

# Use a specific model
uv run rental-agent interactive --model gpt-4-turbo-preview

# Run basic tests
uv run rental-agent test --complexity basic

# Run advanced tests with output
uv run rental-agent test --complexity advanced --output results.json

# Compare different models
uv run rental-agent evaluate --model1 gpt-4-turbo-preview --model2 gpt-3.5-turbo

# Test Best-of-5 selection
uv run rental-agent best-of-n --n 5

rental-agent/
├── rental_agent/
│   ├── __init__.py              # Package exports
│   ├── config.py                # Configuration settings
│   ├── cli.py                   # Command-line interface
│   ├── prompts.py               # System prompts and templates
│   ├── test_prompts.py          # Test prompts and scenarios
│   ├── core/
│   │   ├── agent.py             # Main rental agent
│   │   └── engine.py            # Async engine with tool use
│   ├── models/
│   │   └── schemas.py           # Data models and schemas
│   ├── tools/
│   │   ├── __init__.py
│   │   ├── constants.py         # Tool constants and configurations
│   │   └── web_tools.py         # Web scraping tools
│   └── evaluation/
│       └── reward.py            # Reward functions and evaluators
├── tests/
│   ├── __init__.py
│   └── test_agent.py            # Comprehensive test suite
├── pyproject.toml               # Project configuration
├── uv.lock                      # Dependency lock file
├── Makefile                     # Development commands
├── env.example                  # Environment template
├── test_setup.py                # Setup verification script
└── README.md                    # This file

Create a .env file with the following variables:

# API Keys
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key

# Model Configuration
DEFAULT_MODEL=gpt-4-turbo-preview
FALLBACK_MODEL=gpt-3.5-turbo
MAX_TOKENS=4000
TEMPERATURE=0.1

# Async Configuration
MAX_CONCURRENT_SEARCHES=5
REQUEST_TIMEOUT=30
RETRY_ATTEMPTS=3

# Web Scraping
HEADLESS_BROWSER=true
BROWSER_TIMEOUT=60
USER_AGENT=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36

# Search Sites
SEARCH_SITES=["zillow.com","apartments.com","rent.com","hotpads.com","craigslist.org"]

# Database Configuration
DATABASE_URL=sqlite:///rental_agent.db
REDIS_URL=redis://localhost:6379

# Logging Configuration
LOG_LEVEL=INFO
LOG_FILE=rental_agent.log

# Evaluation
EVALUATION_BATCH_SIZE=10

# Commute Calculation
GOOGLE_MAPS_API_KEY=your_google_maps_api_key
COMMUTE_WORK_ADDRESS=123 Main St, San Francisco, CA

# Email Configuration
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your_email@gmail.com
SMTP_PASSWORD=your_app_password_here

# Development Configuration
DEBUG=false
TEST_MODE=false

Configure the reward function weights in your .env file:

REWARD_FUNCTION_WEIGHTS={"search_coverage": 0.2, "criteria_compliance": 0.3, "data_accuracy": 0.2, "duplicate_detection": 0.1, "contact_success": 0.1, "listing_relevance": 0.1}

# Install development dependencies
make install-dev

# Set up pre-commit hooks
make dev-setup

# Run all development checks
make dev-test

# Setup and installation
make setup              # Initial setup
make install            # Install production dependencies
make install-dev        # Install development dependencies

# Testing
make test               # Run all tests
make test-unit          # Run unit tests only
make test-integration   # Run integration tests only
make test-performance   # Run performance tests
make test-setup         # Test the setup

# Code Quality
make lint               # Run linting checks
make format             # Format code
make type-check         # Run type checking
make quality            # Run all quality checks

# Usage
make interactive        # Start interactive mode
make test-prompts       # Test with prompts
make evaluate           # Run model evaluation
make best-of-n          # Run Best-of-N evaluation

# Maintenance
make clean              # Clean up generated files
make env-check          # Check environment setup

The project uses several code quality tools:

• Ruff: Fast Python linter and formatter
• MyPy: Static type checking
• Black: Code formatting (via Ruff)
• Pre-commit: Git hooks for code quality

# Run all tests
uv run pytest

# Run specific test categories
uv run pytest tests/test_agent.py::TestApartmentListing
uv run pytest tests/test_agent.py::TestIntegration
uv run pytest tests/test_agent.py::TestPerformance

# Run with coverage
uv run pytest --cov=rental_agent --cov-report=html

import asyncio
from rental_agent import RentalAgent, SearchCriteria, UserPreferences

async def main():
    # Initialize agent
    agent = RentalAgent(model="gpt-4-turbo-preview")
    
    # Define search criteria
    criteria = SearchCriteria(
        target_cities=["San Francisco"],
        max_rent=3000,
        min_bedrooms=2,
        max_bedrooms=2,
        required_amenities=["Gym", "Parking"]
    )
    
    # Define user preferences
    preferences = UserPreferences(
        name="John Doe",
        email="john@example.com",
        price_priority=0.3,
        location_priority=0.3,
        amenities_priority=0.2,
        commute_priority=0.2
    )
    
    # Search for apartments
    search_result = await agent.search_apartments(criteria, preferences)
    
    # Get recommendations
    recommendations = await agent.get_recommendations(
        search_result.search_id, preferences
    )
    
    # Generate inquiry message
    if recommendations:
        inquiry = await agent.generate_inquiry_message(
            recommendations[0], preferences
        )
        print(inquiry)
    
    await agent.close()

if __name__ == "__main__":
    asyncio.run(main())

# Interactive apartment search
uv run rental-agent interactive

# Test with specific complexity
uv run rental-agent test --complexity advanced --output results.json

# Evaluate model performance
uv run rental-agent evaluate --model1 gpt-4-turbo-preview --model2 gpt-3.5-turbo

# Run Best-of-N evaluation
uv run rental-agent best-of-n --n 5 --output best_of_n_results.json

1. RentalAgent: Main agent class that orchestrates the apartment search process
2. AsyncEngine: Handles async operations and tool execution
3. WebTools: Web scraping and data extraction utilities
4. RewardFunctions: Evaluation metrics for agent performance
5. CLI: Command-line interface for easy interaction

The agent uses a comprehensive tool system for:

• Web scraping from multiple rental sites
• Data extraction and parsing
• Duplicate detection
• Contact management
• Performance evaluation

The project includes a robust evaluation framework with:

• Deterministic reward functions
• Quality-based metrics
• Model comparison capabilities
• Best-of-N selection algorithms

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run the test suite (make test)
5. Run code quality checks (make quality)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

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

For support and questions:

• Check the documentation in this README
• Run make help for available commands
• Use make test-setup to verify your installation
• Check the test examples in tests/test_agent.py