company-research-agent

1641 GitHub stars recorded

Local Development

1. Start the backend server (choose one option):

   Option 1: Direct Python Module

   python -m application.py
   

   Option 2: FastAPI with Uvicorn

   # Install uvicorn if not already installed
   # With uv (faster):
   uv pip install uvicorn
   # Or with pip:
   # pip install uvicorn
   
   # Run the FastAPI application with hot reload
   uvicorn application:app --reload --port 8000
   

   The backend will be available at:

   • API Endpoint: http://localhost:8000

2. Start the frontend development server:

   cd ui
   npm run dev
   

3. Access the application at http://localhost:5173

⚡ Performance Note: If you used uv during setup, you'll benefit from significantly faster package installation and dependency resolution. uv is a modern Python package manager written in Rust that can be 10-100x faster than pip.

Deployment Options

The application can be deployed to various cloud platforms. Here are some common options:

• Docker: The application includes a Dockerfile for containerized deployment
• Heroku: Deploy directly from GitHub with the Python buildpack
• Google Cloud Run: Suitable for containerized deployment with automatic scaling

Choose the platform that best suits your needs. The application is platform-agnostic and can be hosted anywhere that supports Python web applications.

• Multi-Source Research: Gathers data from various sources, including company websites, news articles, financial reports, and industry analyses
• AI-Powered Content Filtering: Uses Tavily's relevance scoring for content curation
• Asynchronous Processing: Efficient polling-based architecture for tracking research progress
• Dual Model Architecture:
  • Gemini 2.5 Flash for high-context research synthesis
  • GPT-5.1 for precise report formatting and editing
• Modern React Frontend: Responsive UI with progress tracking and download options
• Modular Architecture: Built using a pipeline of specialized research and processing nodes

This approach combines Gemini's strength in handling large context windows with GPT-5.1's precision in following specific formatting instructions.

Content Curation System

The platform uses a content filtering system in curator.py:

1. Relevance Scoring:

   • Documents are scored by Tavily's AI-powered search
   • A minimum threshold (default 0.4) is required to proceed
   • Scores reflect relevance to the specific research query
   • Higher scores indicate better matches to the research intent

2. Document Processing:

   • Content is normalized and cleaned
   • URLs are deduplicated and standardized
   • Documents are sorted by relevance scores
   • Research runs asynchronously in the background

Backend Architecture

The platform implements a simple polling-based communication system:

1. Backend Implementation:

   • Uses FastAPI with async support
   • Research tasks run in background
   • Results are stored and accessed via REST endpoints
   • Simple job status tracking

2. Frontend Integration:

   • React frontend submits research requests
   • Receives job_id for tracking
   • Polls /research/{job_id}/report endpoint
   • Displays final report when complete

3. API Endpoints:

   • POST /research: Submit new research request
   • GET /research/{job_id}/report: Poll for completed report
   • POST /generate-pdf: Generate PDF from report content

3. Install frontend dependencies:

cd ui
npm install

4. Set up Environment Variables:

This project requires two separate .env files for the backend and frontend.

For the Backend:

Create a .env file in the project's root directory and add your backend API keys:

TAVILY_API_KEY=your_tavily_key
GEMINI_API_KEY=your_gemini_key
OPENAI_API_KEY=your_openai_key

# Optional: Enable MongoDB persistence
# MONGODB_URI=your_mongodb_connection_string

For the Frontend:

Create a .env file inside the ui directory. You can copy the example file first:

cp ui/.env.development.example ui/.env

Then, open ui/.env and add your frontend environment variables:

VITE_API_URL=http://localhost:8000
VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here

Docker Setup

The application can be run using Docker and Docker Compose:

1. Clone the repository:

git clone https://github.com/guy-hartstein/company-research-agent.git
cd company-research-agent

2. Set up Environment Variables:

The Docker setup uses two separate .env files.

For the Backend:

Create a .env file in the project's root directory with your backend API keys:

TAVILY_API_KEY=your_tavily_key
GEMINI_API_KEY=your_gemini_key
OPENAI_API_KEY=your_openai_key

# Optional: Enable MongoDB persistence
# MONGODB_URI=your_mongodb_connection_string

For the Frontend:

Create a .env file inside the ui directory. You can copy the example file first:

cp ui/.env.development.example ui/.env

Then, open ui/.env and add your frontend environment variables:

VITE_API_URL=http://localhost:8000
VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here

3. Build and start the containers:

docker compose up --build

This will start both the backend and frontend services:

• Backend API will be available at http://localhost:8000
• Frontend will be available at http://localhost:5174

To stop the services:

docker compose down

Note: When updating environment variables in .env, you'll need to restart the containers:

docker compose down && docker compose up

Running the Application

1. Start the backend server (choose one):

# Option 1: Direct Python Module
python -m application.py

# Option 2: FastAPI with Uvicorn
uvicorn application:app --reload --port 8000

2. In a new terminal, start the frontend:

cd ui
npm run dev

3. Access the application at http://localhost:5173