mcp-gpt-researcher/README.md
ThomasTaroni 43423732e2 Add environment variable placeholders to README
Included new environment variable placeholders for better configuration guidance. These updates clarify setup requirements and improve documentation completeness.
2025-04-25 08:42:32 +02:00

175 lines
No EOL
4.5 KiB
Markdown

# README for FastAPI-Based Report GPT Generation Service
## Overview
This repository contains the implementation of a **FastAPI**-based service designed to generate research reports. The service processes user-provided queries and report types, performing advanced research powered by `GPTResearcher` and responding with comprehensive results, including details, cost, context, images, and other associated metadata.
## Features
- **RESTful API** to handle user queries and generate reports.
- **Streaming responses** to deliver research output in chunks.
- **Secure API access** with API Key authentication.
- Completely containerized setup with Docker.
- Built with modular design for easier scalability and maintenance.
---
## System Architecture
### Core Components
1. **FastAPI App (`main.py`)**:
- Hosts the API endpoints.
- Handles API Key authentication for secure use.
- Accepts user inputs (query and report type) and generates a chunked streaming response.
2. **Research Logic (`deepresearch.py`)**:
- Encapsulates research and report generation.
- Utilizes `GPTResearcher` to conduct research, generate reports, and retrieve extended data like images, contexts, or costs.
3. **Docker Integration**:
- The application is containerized with a well-defined `Dockerfile`.
- Includes dependency installation, environment setup, and FastAPI server configuration for rapid deployment.
---
## Prerequisites
Before running the application, ensure the following are installed on your system:
- **Docker**: Version 24.0+
- **Python**: Version 3.13+
- **pip**: Pre-installed Python package manager.
---
## Running the Application Locally
### Cloning the Repository
Clone the repository to a directory of your choice:
```shell script
git clone https://git.kvant.cloud/phoenix/gpt-researcher.git
cd gpt-researcher
```
### Environment Variable Configuration
Create a `.env` file in the root of the project and define:
```
API_KEY=your_api_key # Replace "your_api_key" with your desired key
OPENAI_BASE_URL=
OPENAI_API_KEY=
EMBEDDING=
FAST_LLM=
SMART_LLM=
STRATEGIC_LLM=
OPENAI_API_VERSION=
SERPER_API_KEY=
RETRIEVER=serper
```
### Installing Dependencies
Install the required Python modules based on the generated `requirements.txt`.
```shell script
pip install --no-cache-dir -r requirements.txt
```
### Running the App
Run the FastAPI app locally:
```shell script
uvicorn main:app --host 0.0.0.0 --port 8000
```
After running, your app will be available at `http://127.0.0.1:8000`.
---
## Using Docker for Deployment
### Building the Docker Image
Build the Docker image using the **Dockerfile** provided:
```shell script
docker build -t fastapi-report-service .
```
### Running the Docker Container
Spin up a container and map FastAPI's default port, `8000`:
```shell script
docker run --env-file .env -p 8000:8000 fastapi-report-service
```
---
## API Usage
### 1. **`/get_report`**
- **Method**: `POST`
- **Description**: Generates a report based on user input.
- **Headers**:
- `X-API-KEY`: API Key for authentication.
- **Request Body** (`JSON`):
```json
{
"query": "Research on AI in healthcare",
"report_type": "research_report|resource_report|outline_report|custom_report|detailed_report|subtopic_report|deep"
}
```
- **Streaming Response**: Research and report are provided in chunks.
---
## Code Structure
```
├── Dockerfile # Configuration for Dockerizing the application
├── requirements.txt # Python dependencies list
├── main.py # FastAPI server entry point
├── deepresearch.py # Research-related logic and GPTResearcher integration
└── src/ # Other project files and assets
```
---
## Features Under the Hood
1. **Authentication**:
- An API key mechanism ensures that only authorized users can access endpoints.
2. **Streaming Response**:
- Large research reports are sent incrementally using `StreamingResponse` for better experience and efficiency.
3. **Modular Research Logic**:
- Research and generation tasks are handled by a dedicated class (`ReportGenerator`), making the application extensible.
---
## Future Enhancements
- **Asynchronous Enhancements**:
- Improve async handling for long-running queries.
- **Database Integration**:
- Save request history for auditing and reference purposes.
- **Web Interface**:
- A user-friendly web application for interacting with the API.
---
## Contributing
Contributions are welcome! Feel free to fork the repository, make updates, and submit a pull request.