A sophisticated 3-agent AI architecture for real estate investment analysis using Google's Gemini models and ATTOM Data API.

• File: agents/customer_agent.py
• Handles user interactions and conversations
• Explains complex analysis in simple terms
• Provides friendly, accessible responses
• Fast response times for real-time chat
• Answers follow-up questions and provides guidance

• File: agents/analysis_engine.py
• Performs complex property valuations and ARV calculations
• Conducts comprehensive market analysis
• Assesses investment risks and opportunities
• Generates deal scores and investment recommendations
• Finds and analyzes comparable properties

• File: agents/deal_finder.py
• Continuously monitors new property listings
• Flags undervalued properties automatically
• Generates investment opportunity alerts
• Background service with configurable search criteria
• User-specific deal notifications

• File: agents/coordinator.py
• Manages communication between all agents
• Priority-based message queuing and routing
• Load balancing and error recovery
• Performance monitoring and metrics

• Quick Property Analysis: Get instant property evaluations with deal scores
• Comprehensive Market Analysis: Deep market insights using AI-powered analysis
• Investment Strategy Recommendations: AI suggests optimal investment approaches
• Risk Assessment: Detailed risk evaluation across multiple categories
• Multi-Agent Coordination: Sophisticated inter-agent communication system
• ATTOM Data Integration: Real property data and market analytics (when configured)

pip install -r requirements.txt

1. Copy .env.example to .env
2. Add your API keys:

   GEMINI_API_KEY=your_gemini_api_key_here
   ATTOM_API_KEY=your_attom_api_key_here  # Optional - will use mock data if not provided
   

1. Go to Google AI Studio
2. Create a new API key
3. Copy the key to your .env file

1. Sign up at ATTOM Data
2. Get your API key from the dashboard
3. Add to .env file (platform works with mock data if not provided)

.\run.ps1

or

run.bat

python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload

1. Open your browser and go to: http://localhost:8000
2. Try the chatbot interface or use the API endpoints directly

• GET / - Main chat interface (HTML)
• POST /chat - Chat with Customer Agent
• GET /health - System health check

• POST /api/analyze/quick - Quick property analysis
• POST /api/analyze/comprehensive - Comprehensive analysis
• GET /api/analyze/status/{analysis_id} - Check analysis status

• POST /api/deals/search - Search for investment deals
• POST /api/deals/monitor - Add property to monitoring
• GET /api/deals/alerts/{user_id} - Get user's deal alerts
• POST /api/deals/criteria/{user_id} - Set search criteria
• GET /api/deals/status - Deal Finder monitoring status

• POST /api/chat/explain - Explain analysis results
• POST /api/chat/followup - Answer follow-up questions
• POST /api/chat/next-steps - Get recommended next steps

• GET /api/agent/coordinator/metrics - Agent coordination metrics
• GET /api/agent/status/{agent_type} - Individual agent status

• GET /api/property/details/{address} - Detailed property information
• GET /api/market/data - Market analytics by area

• GET /api/demo/sample-analysis - Sample analysis results
• GET /api/demo/sample-deals - Sample deals from Deal Finder
• GET /api/demo/all-agents - See all three agents working together

curl -X POST "http://localhost:8000/api/analyze/quick" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "123 Main St, Blacksburg, VA 24060",
    "listing_price": 275000
  }'

curl -X POST "http://localhost:8000/api/deals/search" \
  -H "Content-Type: application/json" \
  -d '{
    "max_price": 300000,
    "min_deal_score": 70,
    "target_locations": ["Blacksburg", "VA"],
    "max_results": 10
  }'

curl -X POST "http://localhost:8000/api/chat/explain" \
  -H "Content-Type: application/json" \
  -d '{
    "analysis_data": {
      "deal_score": 78.5,
      "investment_potential": "Good",
      "arv_estimate": 285000,
      "monthly_cash_flow": 450
    }
  }'

curl "http://localhost:8000/api/demo/all-agents"

{
  "address": "123 Main St, Blacksburg, VA 24060",
  "deal_score": 78.5,
  "investment_potential": "Good",
  "arv_estimate": 285000,
  "recommended_strategy": "buy_and_hold",
  "monthly_cash_flow": 450.0,
  "key_insight": "Property shows strong cash flow potential with moderate appreciation",
  "confidence_score": 0.85
}

VT_Hacks_25/
├── agents/
│   ├── customer_agent.py        # Agent 1: Customer-facing conversational agent
│   ├── analysis_engine.py       # Agent 2: Property analysis engine  
│   ├── deal_finder.py          # Agent 3: Background deal monitoring service
│   ├── coordinator.py          # Multi-agent coordination system
│   └── __init__.py
├── models/
│   ├── data_models.py          # Pydantic models for all data structures
│   └── __init__.py
├── integrations/
│   ├── attom_api.py           # ATTOM Data API integration
│   └── __init__.py
├── static/
│   └── index.html             # Frontend chat interface
├── main.py                    # FastAPI application with all endpoints
├── requirements.txt           # Python dependencies
├── .env.example              # Configuration template
└── README.md                 # This file

The Analysis Engine (Agent 2) provides comprehensive real estate investment analysis:

• ARV (After Repair Value) Calculations: AI-powered property value estimates
• Comparable Property Analysis: Finds and analyzes similar properties
• Market Price Evaluation: Current market value assessments

• Deal Scoring: 0-100 scale rating system for investment opportunities
• Cash Flow Projections: Monthly and annual cash flow estimates
• ROI Calculations: Return on investment and cash-on-cash returns
• Strategy Recommendations: Optimal investment approach (Buy & Hold, Flip, BRRRR, Wholesale)

• Market Risk Analysis: Local market volatility and trends
• Property-Specific Risks: Condition, location, and tenant factors
• Financial Risk Evaluation: Interest rate sensitivity and financing risks
• Regulatory Risk Assessment: Zoning and regulatory considerations

• Local Market Trends: Price movements and inventory analysis
• Neighborhood Dynamics: Gentrification and development patterns
• Economic Indicators: Employment and population growth factors
• Investment Climate: Cap rates and rental yield analysis

• Agent Coordinator: Manages communication between all agents
• Message Queuing: Priority-based request handling
• Load Balancing: Distributes workload across agents
• Error Handling: Robust error recovery and retry mechanisms

• Gemini 1.5 Pro: Complex analysis and reasoning tasks
• Gemini 2.5 Flash: Fast conversational responses

• ATTOM Data API: Property details, market data, comparable sales
• AI Analysis: Gemini-powered insights and recommendations
• Mock Data: Fallback when APIs are unavailable

• Agent 3: Deal Finder - Automated property discovery and monitoring
• Advanced ATTOM Integration - Full property search and filtering
• User Authentication - Personalized analysis and saved properties
• Email Alerts - Automated deal notifications
• Portfolio Tracking - Investment performance monitoring
• Mobile App - iOS and Android companion apps

The platform includes comprehensive error handling:

• API timeouts and retries
• Graceful degradation when services are unavailable
• Fallback calculations when AI analysis fails
• Detailed logging for troubleshooting

All components include detailed logging:

• Request/response tracking
• Performance metrics
• Error diagnostics
• Agent coordination events

├── main.py              # FastAPI backend
├── static/
│   └── index.html       # Chat interface
├── requirements.txt     # Python dependencies
├── .env                 # Environment variables (your API keys)
├── .env.example         # Environment template
├── run.ps1             # PowerShell run script
├── run.bat             # Batch run script
└── README.md           # This file

• ✅ Clean, responsive chat interface
• ✅ Real-time messaging with Gemini AI
• ✅ Health check endpoint
• ✅ Error handling and connection status
• ✅ Typing indicators
• ✅ Mobile-friendly design

1. "Import google.generativeai could not be resolved"

   • Make sure you've installed dependencies: pip install -r requirements.txt

2. "GEMINI_API_KEY not found"

   • Create a .env file with your API key
   • Make sure the key is valid and active

3. "No response generated from Gemini"

   • Check your API key is correct
   • Verify your Google Cloud project has the Gemini API enabled
   • Check the /health endpoint for connection status