How to Start the FastAPI Backend Service for the Graph-RAG Agent

Run uvicorn server.main:app --reload from the project root after installing dependencies and configuring your .env file.

The FastAPI backend service powers the core API layer of the Graph-RAG agent in the 1517005260/graph-rag-agent repository. This service handles conversational queries, knowledge graph operations, and feedback collection through a modular router architecture defined in the server/ package.

Prerequisites and Environment Setup

Before starting the FastAPI backend service, ensure you have Python 3.10 or newer installed. The project relies on specific package versions defined in requirements.txt, including FastAPI and Uvicorn.

Create and activate a virtual environment to isolate dependencies:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

pip install -r requirements.txt

Configuration and Environment Variables

The backend requires external service credentials and connection strings. These are managed through environment variables loaded by server/server_config/settings.py.

Create your environment file from the example:

cp .env.example .env

Edit .env to include:

• Neo4j connection details: NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD
• LLM API keys: OPENAI_API_KEY or other provider credentials referenced in the settings module

The server/server_config/database.py file reads these values to initialize the Neo4j driver, while server/main.py imports the settings to configure the FastAPI application instance.

Launching the FastAPI Service

Start the backend using Uvicorn, the ASGI server recommended for FastAPI applications. Run this command from the project root directory:

uvicorn server.main:app --reload

This command:

• Targets server.main:app, which points to the FastAPI instance created in server/main.py
• Enables --reload for hot-reloading during development (code changes reflect immediately without restart)

For production deployments or specific network configurations, specify host and port:

uvicorn server.main:app --host 0.0.0.0 --port 8000

Verifying the Installation

Once running, the FastAPI backend exposes interactive API documentation at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

The service includes several modular routers defined in server/main.py:

• server/routers/chat.py handles conversational endpoints
• server/routers/knowledge_graph.py manages graph CRUD operations and queries
• Additional routers handle source management and feedback collection

Test the health of the Neo4j connection by invoking the knowledge graph endpoints through the Swagger UI, which validates that server/server_config/database.py successfully connected to your configured Neo4j instance.

Summary

• Entry point: The FastAPI application is defined in server/main.py and exposed via server.main:app
• Dependencies: Install from requirements.txt with Python 3.10+
• Configuration: Populate .env with Neo4j and LLM credentials for server/server_config/settings.py
• Launch command: uvicorn server.main:app --reload for development
• Verification: Access /docs or /redoc to confirm the service is operational

Frequently Asked Questions

What Python version is required to run the FastAPI backend?

The Graph-RAG agent requires Python 3.10 or newer. This ensures compatibility with the type hints and async features used throughout the server/ package, particularly in server/main.py and the router modules.

Where does the FastAPI application load its configuration?

Configuration is loaded from environment variables via server/server_config/settings.py. You must create a .env file in the project root containing values for NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD, and your LLM API keys. The server/server_config/database.py module uses these settings to initialize the Neo4j driver.

How do I enable hot-reloading during development?

Add the --reload flag to your Uvicorn command: uvicorn server.main:app --reload. This monitors the server/ directory for changes and automatically restarts the service, which is essential when modifying routers in server/routers/chat.py or server/routers/knowledge_graph.py during active development.

Can I run the backend on a specific port or bind to all network interfaces?

Yes. By default, Uvicorn binds to 127.0.0.1:8000. To expose the service on all interfaces (necessary for Docker containers or remote access), use uvicorn server.main:app --host 0.0.0.0 --port 8000. Adjust the port number as needed for your deployment environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}