Open-source solution to the #1 factor impacting business revenue: location.

Powered by Railtracks

SiteSage is an agentic site-selection system that evaluates retail locations using a staged analysis pipeline powered by LLMs and external data sources. It provides quantitative scores and qualitative insights for customer demographics, traffic accessibility, and competition analysis.

Key Features:

• 🤖 7-stage AI agent pipeline with sequential contextual analysis
• 🗺️ Multi-region support: Google Maps (US/Western) and AMap (China/Asia)
• 📊 Data-driven insights: Population demographics, transit access, competitor analysis
• 📝 Explainable results: Step-by-step markdown reports with evaluation rubrics
• 🎨 Interactive UI: Golden/royal themed web interface with live maps

1. Clone the repository

   git clone <repository-url>
   cd SiteSage

2. Install dependencies Suggested:

uv venv
.venv\Scripts\activate
uv pip install -e .

or

pip install -e .

3. Configure environment

   cp .env.sample .env
   # Edit .env and add your API keys

   Required API keys:

   • OPENAI_API_KEY - OpenAI API for LLM agents
   • GOOGLE_MAPS_API_KEY - Google Maps (for Western locations)
   • AMAP_API_KEY - AMap/高德 (for Chinese locations)

   See docs/INSTALLATION.md for detailed setup instructions.

cd src
python sitesage_frontend.py

Then open http://127.0.0.1:8000 in your browser.

Enter a prompt like:

Open a boutique coffee shop targeting young professionals near Times Square, New York City.

Or in Chinese:

在南京东路300号附近开一家精品咖啡店，目标客户是年轻白领和学生。

The system will analyze:

• ✅ Customer demographics and population density
• ✅ Transit accessibility and parking availability
• ✅ Competitor landscape and market saturation
• ✅ Overall location suitability (0-10 score)

Results include interactive maps, detailed reports, and actionable recommendations.

SiteSage uses a sequential agentic pipeline where each stage builds on previous analyses:

Each agent uses:

• LLM reasoning (GPT-4) for analysis and synthesis
• Specialized tools for data retrieval (maps, demographics)
• Rubric-based evaluation for objective scoring

See docs/DESIGN.md for detailed architecture documentation.

• 📘 Installation Guide - Setup and configuration
• 📗 API Reference - REST API documentation and examples
• 📙 Design Document - Architecture and implementation details
• 📕 AMap Setup - Chinese location setup guide
• 🔧 Troubleshooting - Common issues and solutions

This project is proudly sponsored by Railtracks, a powerful open-source agentic framework that makes building AI applications vibeable. The LLM facing in-code documentation saves me from the debugging nightmare of other framework, 100% recommend.

Features Used in SiteSage:

1. Multi-Agent Orchestration: all 7 specialized agents working in sequence with data flow and connections.
2. Function Tools: Custom tools for maps (Google Maps/AMap) and demographics (WorldPop)
3. State Persistence: All agent states saved for debugging and audit trails
4. LLM Integration: Seamless integration with all models, we use gpt, gemini and deepseek.
5. Tool Call Iteration: Agents can make multiple tool calls with parameter adjustments
6. Error Recovery: Graceful handling of API failures and partial results

Learn More:

• GitHub: https://github.com/RailtownAI/railtracks

• Coordinate Conversion: coordTransform - Helps conversion between WorldPop and standard coordinate systems
• Search: DuckDuckGo Search (ddgs)

MIT. However, please comply with API provider terms of service, in particular for the asia region which use a range of different API and service providers.

Built with ☕ from Railtracks