Prerequisites
Before you begin, ensure you have the following installed:- Python 3.11+ for the backend
- Node.js 18+ for the frontend
- Redis (optional, for caching)
- Google Gemini - For LLM-powered query generation
- Tavily - For Google Search API access
- NewsAPI - For news data (1,000 requests/day free tier available)
Backend Setup
Install dependencies
The backend uses This will install all required dependencies including:
uv for fast dependency management, but you can also use pip:- FastAPI (web framework)
- Google Generative AI (Gemini integration)
- Tavily Python SDK (Google Search)
- NewsAPI Python client
- Redis (caching and deduplication)
- scikit-learn (semantic job matching)
Start the development server
- API: http://localhost:8000
- Interactive docs: http://localhost:8000/docs
- Alternative docs: http://localhost:8000/redoc
Frontend Setup
Install dependencies
Install all required packages using your preferred package manager:This will install:
- React 18 with TypeScript
- Material-UI (MUI) v7
- Vite build tool
- Emotion for CSS-in-JS
Start the development server
Make sure both the backend (port 8000) and frontend (port 3000) are running simultaneously for the application to work correctly.
Your First Research Query
Now that both services are running, let’s execute your first research query.Using the Web Interface
Open the application
Navigate to http://localhost:3000 in your browser.
Configure settings (optional)
Click the settings/tune icon to adjust:
- Company Domains: Add specific companies to research (e.g.,
stripe.com,paypal.com) - Search Depth: Choose
quick,standard, orcomprehensive - Parallel Searches: Set concurrent search limit (1-10)
- Confidence Threshold: Set minimum confidence score (0.0-1.0)
Using the API Directly
You can also interact with the API programmatically using theBatchResearchRequest model:
Request Parameters
TheBatchResearchRequest model accepts the following parameters:
| Parameter | Type | Description | Required |
|---|---|---|---|
research_goal | string | The high-level research objective | Yes |
company_domains | string[] | List of company domains to analyze | Yes |
search_depth | enum | Controls search breadth: "quick", "standard", or "comprehensive" | Yes |
max_parallel_searches | integer | Number of concurrent searches per source (overrides default) | Yes |
confidence_threshold | float | Minimum confidence score to include findings (0.0-1.0) | Yes |
Example Response
Real-time Streaming (Advanced)
For real-time progress updates, use the streaming endpoint:Next Steps
API Reference
Explore all available endpoints and request/response schemas
Configuration Guide
Learn how to fine-tune search depth, parallelism, and data sources
Architecture Overview
Understand the system design and data flow
Performance Tuning
Optimize your research queries for better results
Troubleshooting
Backend won't start - ModuleNotFoundError
Backend won't start - ModuleNotFoundError
Make sure you’ve installed dependencies and are running from the correct directory:
Frontend can't connect to backend
Frontend can't connect to backend
Ensure the backend is running on port 8000 and CORS is enabled. Check the browser console for specific error messages. The backend includes CORS middleware that allows all origins by default.
API key errors
API key errors
Verify your
.env file is in the backend directory and contains all required keys:GEMINI_API_KEYTAVILY_API_KEYNEWS_API_KEY
Slow research results
Slow research results
Try adjusting these parameters:
- Reduce
max_parallel_searchesif hitting rate limits - Use
"quick"search depth for faster results - Reduce the number of
company_domainsper request - Check your internet connection and API service status
Port already in use
Port already in use
If port 8000 or 3000 is already in use, specify different ports:
Getting Help
If you encounter issues not covered here:- Check the API documentation for endpoint details
- Review the logs in your terminal for error messages
- Ensure all API keys are valid and have sufficient quota
- Verify network connectivity to external APIs