Your First Query

Step 1: Open the Admin UI

Navigate to the Admin UI in your browser:

http://localhost/config-ui

The Admin UI is your central control panel for managing FluidRAG configuration.

Step 2: Configure Secrets

All API keys and credentials are stored in etcd and managed through the Admin UI — never in .env files.

1. Open the Admin UI
2. Navigate to Settings
3. In the Secrets section, add your API keys:

Secret	Required	Description
OPENAI_API_KEY	Yes*	OpenAI API key for embeddings and chat completions
FALKORDB_PASSWORD	If auth enabled	Password for your FalkorDB instance
SLACK_BOT_TOKEN	No	For Slack agent (xoxb-...)
SLACK_USER_TOKEN	No	For Slack search (xoxp-...)
JIRA_CLIENT_ID	No	For Jira OAuth integration
JIRA_CLIENT_SECRET	No	For Jira OAuth integration
GITHUB_TOKEN	No	GitHub PAT for code/issue search

* At least one LLM provider API key is required. OpenAI is the default.

Step 3: Configure LLM Provider

FluidRAG supports multiple LLM providers for different pipeline layers. Configure them under Settings → LLM:

Layer	Purpose	Default
Logic Layer	Agent execution	openai / gpt-4o-mini
Route Layer	Query classification	openai / gpt-4o-mini
Synthesis Layer	Final response generation	openai / gpt-4o-mini
Entity Extraction	Ingestion pipeline	openai / gpt-4o-mini
Embedding	Dense embeddings	openai / text-embedding-3-large

Each layer can use a different provider and model. Configuration changes take effect immediately via hot-reload — no restart required.

Step 4: Send a Query

FluidRAG exposes an OpenAI-compatible chat completions endpoint. Use curl or any OpenAI client:

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "What is FluidRAG?"}],
    "stream": false
  }'

For streaming responses:

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "What is FluidRAG?"}],
    "stream": true
  }'

The response follows the standard OpenAI chat.completion.chunk SSE format.

Query Flow

Every query passes through a 5-phase workflow:

1. Classify — Rule-based + LLM classification of query intent
2. Route — Select relevant agents (RAG, Jira, Slack, GitHub, etc.)
3. Execute — Parallel agent execution with individual timeouts
4. Review — Check for partial results, retry if needed (max 2 iterations)
5. Synthesize — Generate final response with citations and sources

Step 5: Ingest Documents

Before the RAG agent can answer questions about your data, you need to ingest documents:

1. Open the Admin UI at http://localhost/config-ui
2. Navigate to Ingestion
3. Enter a directory path (accessible to the Docker containers via volume mounts)
4. Select a chunking strategy:
   • Semantic — Fast, good for general documents
   • Semantic (LlamaIndex) — Context-aware, good for mixed content
   • Propositional — High precision, best for technical documents (slower, higher LLM cost)
5. Click Start Ingestion

Monitor progress in the RQ Dashboard at http://localhost:9181.

Access Points Summary

Service	URL	Description
API	http://localhost:8000	OpenAI-compatible chat completions
Admin UI	http://localhost/config-ui	Configuration, secrets, agents, prompts
Gateway	http://localhost	Nginx reverse proxy (HTTP)
RQ Dashboard	http://localhost:9181	Background job monitoring

Next Steps

• Docker Deployment — Detailed deployment and configuration reference
• Building Images — Docker Bake and Makefile targets