[Skip to content](https://github.com/mory91/rent-finder#start-of-content)

You signed in with another tab or window. [Reload](https://github.com/mory91/rent-finder) to refresh your session.You signed out in another tab or window. [Reload](https://github.com/mory91/rent-finder) to refresh your session.You switched accounts on another tab or window. [Reload](https://github.com/mory91/rent-finder) to refresh your session.Dismiss alert

{{ message }}

[mory91](https://github.com/mory91)/ **[rent-finder](https://github.com/mory91/rent-finder)** Public

- [Notifications](https://github.com/login?return_to=%2Fmory91%2Frent-finder) You must be signed in to change notification settings
- [Fork\\
0](https://github.com/login?return_to=%2Fmory91%2Frent-finder)
- [Star\\
2](https://github.com/login?return_to=%2Fmory91%2Frent-finder)


master

[**1** Branch](https://github.com/mory91/rent-finder/branches) [**0** Tags](https://github.com/mory91/rent-finder/tags)

[Go to Branches page](https://github.com/mory91/rent-finder/branches)[Go to Tags page](https://github.com/mory91/rent-finder/tags)

Go to file

Code

Open more actions menu

## Folders and files

| Name | Name | Last commit message | Last commit date |
| --- | --- | --- | --- |
| ## Latest commit<br>[![mory91](https://avatars.githubusercontent.com/u/13743297?v=4&size=40)](https://github.com/mory91)[mory91](https://github.com/mory91/rent-finder/commits?author=mory91)<br>[Update README.md](https://github.com/mory91/rent-finder/commit/fff82529c58a818dbb7a87e4810697d944763ddd)<br>last yearJun 23, 2025<br>[fff8252](https://github.com/mory91/rent-finder/commit/fff82529c58a818dbb7a87e4810697d944763ddd) · last yearJun 23, 2025<br>## History<br>[2 Commits](https://github.com/mory91/rent-finder/commits/master/) <br>Open commit details<br>[View commit history for this file.](https://github.com/mory91/rent-finder/commits/master/) 2 Commits |
| [rental\_agent](https://github.com/mory91/rent-finder/tree/master/rental_agent "rental_agent") | [rental\_agent](https://github.com/mory91/rent-finder/tree/master/rental_agent "rental_agent") | [first commit](https://github.com/mory91/rent-finder/commit/f40c4b82ebd964a9b1f3e292427a22eff5d173f1 "first commit") | last yearJun 23, 2025 |
| [tests](https://github.com/mory91/rent-finder/tree/master/tests "tests") | [tests](https://github.com/mory91/rent-finder/tree/master/tests "tests") | [first commit](https://github.com/mory91/rent-finder/commit/f40c4b82ebd964a9b1f3e292427a22eff5d173f1 "first commit") | last yearJun 23, 2025 |
| [.gitignore](https://github.com/mory91/rent-finder/blob/master/.gitignore ".gitignore") | [.gitignore](https://github.com/mory91/rent-finder/blob/master/.gitignore ".gitignore") | [first commit](https://github.com/mory91/rent-finder/commit/f40c4b82ebd964a9b1f3e292427a22eff5d173f1 "first commit") | last yearJun 23, 2025 |
| [Makefile](https://github.com/mory91/rent-finder/blob/master/Makefile "Makefile") | [Makefile](https://github.com/mory91/rent-finder/blob/master/Makefile "Makefile") | [first commit](https://github.com/mory91/rent-finder/commit/f40c4b82ebd964a9b1f3e292427a22eff5d173f1 "first commit") | last yearJun 23, 2025 |
| [README.md](https://github.com/mory91/rent-finder/blob/master/README.md "README.md") | [README.md](https://github.com/mory91/rent-finder/blob/master/README.md "README.md") | [Update README.md](https://github.com/mory91/rent-finder/commit/fff82529c58a818dbb7a87e4810697d944763ddd "Update README.md") | last yearJun 23, 2025 |
| [env.example](https://github.com/mory91/rent-finder/blob/master/env.example "env.example") | [env.example](https://github.com/mory91/rent-finder/blob/master/env.example "env.example") | [first commit](https://github.com/mory91/rent-finder/commit/f40c4b82ebd964a9b1f3e292427a22eff5d173f1 "first commit") | last yearJun 23, 2025 |
| [pyproject.toml](https://github.com/mory91/rent-finder/blob/master/pyproject.toml "pyproject.toml") | [pyproject.toml](https://github.com/mory91/rent-finder/blob/master/pyproject.toml "pyproject.toml") | [first commit](https://github.com/mory91/rent-finder/commit/f40c4b82ebd964a9b1f3e292427a22eff5d173f1 "first commit") | last yearJun 23, 2025 |
| [test\_setup.py](https://github.com/mory91/rent-finder/blob/master/test_setup.py "test_setup.py") | [test\_setup.py](https://github.com/mory91/rent-finder/blob/master/test_setup.py "test_setup.py") | [first commit](https://github.com/mory91/rent-finder/commit/f40c4b82ebd964a9b1f3e292427a22eff5d173f1 "first commit") | last yearJun 23, 2025 |
| [uv.lock](https://github.com/mory91/rent-finder/blob/master/uv.lock "uv.lock") | [uv.lock](https://github.com/mory91/rent-finder/blob/master/uv.lock "uv.lock") | [first commit](https://github.com/mory91/rent-finder/commit/f40c4b82ebd964a9b1f3e292427a22eff5d173f1 "first commit") | last yearJun 23, 2025 |
| View all files |

## Repository files navigation

# Rental Apartment Finding Assistant

[Permalink: Rental Apartment Finding Assistant](https://github.com/mory91/rent-finder#rental-apartment-finding-assistant)

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

## Features

[Permalink: Features](https://github.com/mory91/rent-finder#features)

### Core Capabilities

[Permalink: Core Capabilities](https://github.com/mory91/rent-finder#core-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

### Evaluation & Testing

[Permalink: Evaluation & Testing](https://github.com/mory91/rent-finder#evaluation--testing)

- **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

## Quick Start

[Permalink: Quick Start](https://github.com/mory91/rent-finder#quick-start)

### Prerequisites

[Permalink: Prerequisites](https://github.com/mory91/rent-finder#prerequisites)

- Python 3.13+
- [uv](https://github.com/astral-sh/uv) package manager
- API keys for OpenAI and/or Anthropic

### Installation

[Permalink: Installation](https://github.com/mory91/rent-finder#installation)

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
```


### Basic Usage

[Permalink: Basic Usage](https://github.com/mory91/rent-finder#basic-usage)

#### Interactive Mode

[Permalink: Interactive Mode](https://github.com/mory91/rent-finder#interactive-mode)

```
# Start interactive apartment search
uv run rental-agent interactive

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

#### Automated Testing

[Permalink: Automated Testing](https://github.com/mory91/rent-finder#automated-testing)

```
# 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
```

#### Best-of-N Evaluation

[Permalink: Best-of-N Evaluation](https://github.com/mory91/rent-finder#best-of-n-evaluation)

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

## Project Structure

[Permalink: Project Structure](https://github.com/mory91/rent-finder#project-structure)

```
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
```

## Configuration

[Permalink: Configuration](https://github.com/mory91/rent-finder#configuration)

### Environment Variables

[Permalink: Environment Variables](https://github.com/mory91/rent-finder#environment-variables)

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
```

### Reward Function Weights

[Permalink: Reward Function Weights](https://github.com/mory91/rent-finder#reward-function-weights)

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}
```

## Development

[Permalink: Development](https://github.com/mory91/rent-finder#development)

### Setup Development Environment

[Permalink: Setup Development Environment](https://github.com/mory91/rent-finder#setup-development-environment)

```
# Install development dependencies
make install-dev

# Set up pre-commit hooks
make dev-setup

# Run all development checks
make dev-test
```

### Available Make Commands

[Permalink: Available Make Commands](https://github.com/mory91/rent-finder#available-make-commands)

```
# 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
```

### Code Quality Tools

[Permalink: Code Quality Tools](https://github.com/mory91/rent-finder#code-quality-tools)

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

### Testing

[Permalink: Testing](https://github.com/mory91/rent-finder#testing)

```
# 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
```

## Usage Examples

[Permalink: Usage Examples](https://github.com/mory91/rent-finder#usage-examples)

### Python API

[Permalink: Python API](https://github.com/mory91/rent-finder#python-api)

```
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())
```

### CLI Examples

[Permalink: CLI Examples](https://github.com/mory91/rent-finder#cli-examples)

```
# 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
```

## Architecture

[Permalink: Architecture](https://github.com/mory91/rent-finder#architecture)

### Core Components

[Permalink: Core Components](https://github.com/mory91/rent-finder#core-components)

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

### Tool System

[Permalink: Tool System](https://github.com/mory91/rent-finder#tool-system)

The agent uses a comprehensive tool system for:

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

### Evaluation Framework

[Permalink: Evaluation Framework](https://github.com/mory91/rent-finder#evaluation-framework)

The project includes a robust evaluation framework with:

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

## Contributing

[Permalink: Contributing](https://github.com/mory91/rent-finder#contributing)

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

## License

[Permalink: License](https://github.com/mory91/rent-finder#license)

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

## Support

[Permalink: Support](https://github.com/mory91/rent-finder#support)

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`

## About

No description, website, or topics provided.


### Resources

[Readme](https://github.com/mory91/rent-finder#readme-ov-file)

### Uh oh!

There was an error while loading. [Please reload this page](https://github.com/mory91/rent-finder).

[Activity](https://github.com/mory91/rent-finder/activity)

### Stars

**2**
stars


### Watchers

**0**
watching


### Forks

[**0**\\
forks](https://github.com/mory91/rent-finder/forks)

[Report repository](https://github.com/contact/report-content?content_url=https%3A%2F%2Fgithub.com%2Fmory91%2Frent-finder&report=mory91+%28user%29)

## [Releases](https://github.com/mory91/rent-finder/releases)

No releases published

## [Packages\  0](https://github.com/users/mory91/packages?repo_name=rent-finder)

No packages published

## [Contributors\  1](https://github.com/mory91/rent-finder/graphs/contributors)

- [![@mory91](https://avatars.githubusercontent.com/u/13743297?s=64&v=4)](https://github.com/mory91)[**mory91** M](https://github.com/mory91)

## Languages

- [Python95.8%](https://github.com/mory91/rent-finder/search?l=python)
- [Makefile4.2%](https://github.com/mory91/rent-finder/search?l=makefile)

You can’t perform that action at this time.