Skip to main content

​
Overview

The GTM Research Engine is a full-stack application with a FastAPI backend and React frontend. This guide will walk you through installing both components.

​
Prerequisites

Before installing the GTM Research Engine, ensure you have the following installed on your system:

Python 3.11+

Required for the backend research engine

Node.js 18+

Required for the frontend React application

Redis Server

Used for caching and deduplication

Git

For cloning the repository
Package Manager Recommendation: The backend uses uv for fast Python dependency management. Install it with: pip install uv

​
System Requirements

  • Memory: Minimum 4GB RAM (8GB recommended for production)
  • Storage: At least 2GB free disk space
  • Network: Internet connection for API calls to external data sources
  • OS: Linux, macOS, or Windows (WSL recommended for Windows)

​
Installation Steps

1

Clone the Repository

First, clone the GTM Research Engine repository to your local machine:
git clone <repository-url>
cd gtm-research-engine
Replace <repository-url> with your actual repository URL.
2

Install Redis

Redis is required for caching and deduplication. Install it based on your operating system:
# Using Homebrew
brew install redis
brew services start redis
Verify Redis is running:
redis-cli ping
# Should return: PONG
3

Install Backend Dependencies

Navigate to the backend directory and install Python dependencies:
cd backend
uv sync
The backend uses the following key dependencies:
  • FastAPI (0.116.1+): Modern web framework for building APIs
  • Google Generative AI (0.8.5+): LLM for query generation and analysis
  • Tavily Python (0.7.10+): Google Search API integration
  • NewsAPI Python (0.2.7+): News data source integration
  • Redis (6.4.0+): Caching and deduplication
  • Scikit-learn (1.7.1+): TF-IDF for job posting analysis
  • Uvicorn (0.35.0+): ASGI server for FastAPI
  • Pydantic (2.11.7+): Data validation and serialization
  • ORJSON (3.11.2+): Fast JSON serialization
4

Install Frontend Dependencies

Navigate to the frontend directory and install Node.js dependencies:
cd ../frontend
npm install
The frontend uses the following key dependencies:
  • React (18.2.0): UI framework
  • Material-UI v7 (7.1.0): Component library
  • TypeScript (5.9.2+): Type-safe JavaScript
  • Vite (5.1.0): Build tool and dev server
  • Emotion (11.11.0+): CSS-in-JS styling
5

Verify Installation

Verify all dependencies are installed correctly:
cd backend
python -c "import fastapi, google.generativeai, tavily; print('Backend dependencies OK')"

​
Post-Installation

Before running the application, you must configure environment variables and API keys. See the Configuration and API Keys guides.

​
Troubleshooting

If you encounter Python version errors, ensure you’re using Python 3.11 or higher:
python --version
# Should show: Python 3.11.x or higher
Consider using pyenv to manage multiple Python versions:
pyenv install 3.11
pyenv local 3.11
If the backend can’t connect to Redis:
  1. Verify Redis is running: redis-cli ping
  2. Check the default port (6379) is not in use: lsof -i :6379
  3. Review Redis logs for errors
# Check Redis status
redis-cli info server
Ensure you’re using Node.js 18 or higher:
node --version
# Should show: v18.x.x or higher
Use nvm (Node Version Manager) to install the correct version:
nvm install 18
nvm use 18
If uv sync or npm install fails:Backend:
# Clear pip cache and retry
pip cache purge
pip install -e . --no-cache-dir
Frontend:
# Clear npm cache and retry
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

​
Next Steps

Configuration

Configure environment variables and settings

API Keys

Set up required API keys for data sources

​
Development Tools (Optional)

For a better development experience, consider installing: 
# Code formatting
pip install black ruff

# Type checking
pip install mypy

# Testing
pip install pytest pytest-asyncio

Build docs developers (and LLMs) love

Get started for freeTalk to us