🛠ī¸ Development

1. Clone the repository

git clone https://github.com/gzileni/kgrag_agent.git
cd kgrag_agent

2. Create a Python virtual environment

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

🔧 Environment Variables

Before starting development, copy each env.xxxx.template file to its corresponding .env.xxxx file. For example:

cp env.development.template .env.development
cp env.production.template .env.production
cp env.ollama.production.template .env.ollama.production
cp env.ollama.development.template .env.development.production
cp env.openai.development.template .env.openai.development
cp env.openai.production.template .env.openai.production
cp env.vllm.production.template .env.vllm.production
cp env.vllm.development.template .env.vllm.development
cp env.template .env

Edit the copied .env.xxxx files as needed for your environment.

Example organization for multiple environments:

.env.development
.env.production
.env.ollama.production
.env.development.production
.env.openai.development
.env.openai.production
.env.vllm.production
.env.vllm.development
.env

🌍 General

Variable Default Description
APP_ENV development Execution environment (development, staging, production, test).
COLLECTION_NAME kgrag_data Name of the collection for data ingestion.

🔄 Redis

Variable Default Description
REDIS_URL redis://localhost:6379 Full URL for Redis.
REDIS_HOST localhost Redis host.
REDIS_PORT 6379 Redis port.
REDIS_DB 4 Redis database number.

🔍 Qdrant

Variable Default Description
QDRANT_URL http://localhost:6333 Qdrant instance URL.

📊 Loki

Variable Default Description
LOKI_URL http://localhost:3100/loki/api/v1/push Loki push URL.

🤖 LLM (Large Language Model)

Variable Default Description
LLM_MODEL_TYPE openai Model type (openai, azure, local, etc.).
LLM_MODEL_NAME gpt-4.1-mini Name of the LLM model to use.
LLM_EMBEDDING_URL (empty) Custom embedding endpoint.
MODEL_EMBEDDING text-embedding-3-small Model for embeddings.
LLM_URL (empty) LLM API endpoint.

🧠 Vector DB

Variable Default Description
VECTORDB_SENTENCE_MODEL BAAI/bge-small-en-v1.5 Embedding model for vectors.
VECTORDB_SENTENCE_TYPE hf Model type (hf, local).
VECTORDB_SENTENCE_PATH (empty) Local path for vector model.

🧠 MCP Server

Variable Default Description
MCP_SERVER_URL http://localhost:8000/sse Url MCP Server Kgrag.

⚙ī¸ Docker

This project uses Docker Compose to run the KGrag Agent stack. The Makefile provides quick commands to start, stop, and restart services.

đŸ“Ļ Requirements

🚀 Available Commands

â–ļī¸ Start the stack

Start all services in detached mode (-d):

make run

Internally runs:

docker-compose -p kgrag-agent up -d

⏚ī¸ Stop the stack

Stops and removes containers defined in docker-compose.yml:

make stop

Internally runs:

docker-compose down

🔄 Restart the stack

Stops and restarts services:

make restart

Equivalent to:

make stop && make run

📜 Notes

  • The stack uses the Docker Compose project named kgrag-agent.
  • You can customize services by editing the docker-compose.yml file.
  • To view logs in real time:
docker-compose -p kgrag-agent logs -f